@shardflux/cli 0.13.5 → 0.14.0

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

package/dist/agent-target-commands.js

@@ -9,7 +9,11 @@ import { join, relative } from 'node:path';
 import { projectIdentity } from "./project-identity.js";
 import { projectWorkspacePath } from "./agent-repository.js";
 import { UsageError } from "./errors.js";
+import { prepareDesktopRouter } from "./conversation-router.js";
 import { openUrl } from "./browser.js";
+import { agentMachineName, prepareAgentMachine } from "./agent-machine.js";
+import { prewarmT3 } from "./t3-runtime.js";
+import { AgentStateStore } from "./agent-state.js";
 const missing = (e) => e instanceof ShardfluxApiError && e.status === 404;
 const keyOf = (ref) => ref.includes('/') ? ref : `${projectIdentity('./').slug}/${ref}`;
 /** Optimistic file replacement preserves keys installed by other devices connecting at the same time. */
@@ -47,14 +51,16 @@ export async function installDeviceKey(cell, key, signal) {
 export async function prepareSsh(ws, ctx, targets, host) {
     if (!ws.ready)
         await ws.wake({ timeoutMs: ctx.wakeTimeoutMs, signal: ctx.signal });
+    if (ws.labels?.t3_environment_id)
+        await prepareAgentMachine(ctx, ws);
     const cell = ws.cell({ agentLabel: ctx.agentLabel, transitionTimeoutMs: ctx.wakeTimeoutMs });
     const hostKey = await cell.files.readText('/etc/ssh/ssh_host_ed25519_key.pub', { length: 4096 });
-    targets.pin(host, hostKey);
+    await targets.pin(host, hostKey, ctx.signal);
     await installDeviceKey(cell, targets.deviceKey(), ctx.signal);
     return cell;
 }
 async function openApp(target, env) {
-    const child = spawn('open', ['-b', target === 'claude-desktop' ? 'com.anthropic.claudefordesktop' : 'com.openai.codex'], { env, stdio: 'ignore' });
+    const child = spawn('open', ['-b', { 'claude-desktop': 'com.anthropic.claudefordesktop', 'codex-app': 'com.openai.codex', t3: 'com.t3tools.t3code' }[target]], { env, stdio: 'ignore' });
     await new Promise((resolve, reject) => {
         const timer = setTimeout(() => { child.kill('SIGKILL'); reject(new Error('app launcher timed out')); }, 10_000);
         child.once('error', e => { clearTimeout(timer); reject(e); });
@@ -64,7 +70,7 @@ async function openApp(target, env) {
             reject(new Error(`app launcher exited ${code}`)); });
     });
 }
-export function proxyStream(io) {
+export function proxyStream(io, ended) {
     const stdout = io.stdout;
     const source = Readable.from(io.stdin, { objectMode: false });
     let blocked = false;
@@ -92,15 +98,24 @@ export function proxyStream(io) {
                 done(e);
             }
         },
-        destroy(error, done) { source.destroy(); done(error); },
+        // A guest can close before SSH authenticates (e.g. sshd MaxStartups).
+        // Once output drains, end the proxy so SSH sees EOF instead of waiting
+        // for input EOF from the client that is itself waiting for us.
+        final(done) { done(); ended?.(); },
+        destroy(error, done) { source.destroy(); stdout.off?.('error', outputError); stdout.off?.('close', outputClosed); done(error); },
     });
+    const outputError = (error) => stream.destroy(error);
+    const outputClosed = () => stream.destroy(new Error('SSH client output closed'));
+    stdout.once?.('error', outputError);
+    stdout.once?.('close', outputClosed);
     source.on('readable', pump);
-    source.once('end', () => stream.push(null));
+    source.once('end', () => { stream.push(null); ended?.(); });
     source.once('error', (error) => stream.destroy(error));
     return stream;
 }
 const openTarget = (target) => async (ctx, values, [ref = 'main']) => {
-    if (target !== 'web' && !installedTargets(ctx.io.env).targets.includes(target))
+    const detected = installedTargets(ctx.io.env);
+    if (target !== 'web' && !detected.targets.includes(target))
         throw new UsageError(`${target} is not installed on this machine`);
     let ws = await resolveWorkspace(ctx, keyOf(ref));
     if (values.reachable !== undefined)
@@ -125,37 +140,57 @@ const openTarget = (target) => async (ctx, values, [ref = 'main']) => {
         out(ctx, `${url}\n`, { target, workspace: ws.data, url });
         return 0;
     }
+    return openDesktopWorkspace(ctx, ws, target, detected.versions.t3);
+};
+export async function openDesktopWorkspace(ctx, ws, target, t3Version, prewarmed = false) {
+    if (target !== 't3')
+        ws = await prepareDesktopRouter(ctx, ws);
+    await prepareAgentMachine(ctx, ws);
+    if (target === 't3' && t3Version && !prewarmed)
+        await queueT3Prewarm(ctx, ws, t3Version);
     const targets = new AgentTargets(ctx.io.env, ctx.store.dir);
-    const entry = targets.configure(ws.key, ctx.apiUrl, [target]).find(e => e.workspace === ws.key);
-    const instructions = target === 'claude-desktop'
-        ? `Restart Claude Desktop to load the connection, then choose Shardflux · ${entry.project} · ${entry.agent} in Code's environment dropdown and open ${projectWorkspacePath({ slug: entry.project })}.`
-        : `Restart Codex to import ${entry.host} and its remote project. If it has already been imported, enable ${entry.host} in Settings → Connections → SSH.`;
+    const entry = (await (ws.labels.shard_router === 'project' ? targets.configureProject(ws.key, ctx.apiUrl, [target], ctx.signal) : targets.configure(ws.key, ctx.apiUrl, [target], false, ctx.signal))).find(e => e.workspace === ws.key);
+    const instructions = target === 't3'
+        ? `Add environment → SSH → ${entry.host} (${agentMachineName(ws.key)}), then open ${projectWorkspacePath({ slug: entry.project })}.`
+        : target === 'claude-desktop'
+            ? `Restart Claude Desktop to load the connection, then choose ${targetLabel(entry)} in Code's environment dropdown and open ${projectWorkspacePath({ slug: entry.project })}.`
+            : `Restart Codex to import ${entry.host} and its remote project. If it has already been imported, enable ${entry.host} in Settings → Connections → SSH.`;
     if (!ctx.json)
         await openApp(target, ctx.io.env);
+    new AgentStateStore(ctx.store.dir).saveTarget(ws.labels.repo_remote || ws.labels.shard_project || entry.project, target);
     out(ctx, `${instructions}\n`, { target, workspace: ws.data, host: entry.host, instructions });
     return 0;
-};
+}
+export async function queueT3Prewarm(ctx, ws, version) {
+    try {
+        await prewarmT3(ctx, ws, version);
+    }
+    catch (error) {
+        ctx.io.stderr.write(`T3 runtime will install on connect: ${error instanceof Error ? error.message : String(error)}\n`);
+    }
+}
 const tilde = (targets, file) => file.startsWith(`${targets.home}/`) ? `~/${relative(targets.home, file)}` : file;
-const targetLabel = (e) => `[SF] ${e.project} · ${e.agent}`;
+const targetLabel = (e) => e.agent === 'router' ? `Shardflux · ${e.project}` : `[SF] ${e.project} · ${e.agent}`;
 /** Where each managed connection of an entry lives: the SSH host block (and its Include), then each desktop app's file. */
-function configuredTargets(targets, e) {
+function configuredTargets(targets, e, t3 = false) {
     return [
         { target: 'ssh', label: 'SSH', file: targets.sshFile, name: e.host, detail: `(included from ${tilde(targets, join(targets.home, '.ssh', 'config'))}): ssh ${e.host}` },
         ...(e.targets.includes('claude-desktop') ? [{ target: 'claude-desktop', label: 'Claude Desktop', file: targets.claudeFile, name: targetLabel(e), detail: `(sshConfigs: ${targetLabel(e)}); restart Claude Desktop, then pick it in Code's environment list` }] : []),
         ...(e.targets.includes('codex-app') ? [{ target: 'codex-app', label: 'Codex app', file: targets.codexFile, name: targetLabel(e), detail: `(remoteConnections: ${targetLabel(e)}); restart Codex to import it` }] : []),
+        ...(t3 ? [{ target: 't3', label: 'T3 Code', file: targets.sshFile, name: agentMachineName(e.workspace), detail: `Add environment → SSH → ${e.host}; project ${projectWorkspacePath({ slug: e.project })}` }] : []),
     ];
 }
 function targetFiles(targets, entries) {
     return [...new Set(entries.flatMap(e => configuredTargets(targets, e).map(c => c.file)))];
 }
 export const TARGET_HANDLERS = {
-    'agents targets'(ctx, values, [ref]) {
+    async 'agents targets'(ctx, values, [ref]) {
         const detected = installedTargets(ctx.io.env);
         const targets = new AgentTargets(ctx.io.env, ctx.store.dir);
         const key = ref ? keyOf(ref) : undefined;
-        const before = values.remove === true ? targets.configure(undefined, ctx.apiUrl, []) : [];
+        const before = values.remove === true ? await targets.configure(undefined, ctx.apiUrl, [], false, ctx.signal) : [];
         const entries = ref || values.remove === true
-            ? targets.configure(key, ctx.apiUrl, detected.targets.filter((t) => t === 'claude-desktop' || t === 'codex-app'), values.remove === true)
+            ? await targets.configure(key, ctx.apiUrl, detected.targets.filter((t) => t === 'claude-desktop' || t === 'codex-app' || t === 't3'), values.remove === true, ctx.signal)
             : [];
         const detection = `${detected.clients.join(', ') || 'No installed agent clients'}\nOpen targets: ${detected.targets.join(', ')}\n`;
         if (values.remove === true) {
@@ -168,23 +203,30 @@ export const TARGET_HANDLERS = {
             out(ctx, detection, { ...detected, entries });
             return Promise.resolve(0);
         }
-        const configured = configuredTargets(targets, entry);
+        const t3 = detected.targets.includes('t3');
+        const configured = configuredTargets(targets, entry, t3);
         out(ctx, `Configured ${entry.workspace} as SSH host ${entry.host}:\n${configured.map(c => `  ${c.label.padEnd(15)} ${tilde(targets, c.file)}${c.detail ? ` ${c.detail}` : ''}`).join('\n')}\n` +
-            ['claude-desktop', 'codex-app'].filter(t => !entry.targets.includes(t)).map(t => `  ${(t === 'claude-desktop' ? 'Claude Desktop' : 'Codex app').padEnd(15)} not installed on this computer\n`).join(''), { ...detected, entries, configured: configured.map(({ target, file, name }) => ({ target, file, name })) });
+            ['claude-desktop', 'codex-app', 't3'].filter(t => t === 't3' ? !t3 : !entry.targets.includes(t)).map(t => `  ${{ 'claude-desktop': 'Claude Desktop', 'codex-app': 'Codex app', t3: 'T3 Code' }[t].padEnd(15)} not installed on this computer\n`).join(''), { ...detected, entries, configured: configured.map(({ target, file, name }) => ({ target, file, name })) });
         return Promise.resolve(0);
     },
     'agents open claude-desktop': openTarget('claude-desktop'),
     'agents open codex-app': openTarget('codex-app'),
+    'agents open t3': openTarget('t3'),
     'agents open web': openTarget('web'),
     async 'ssh-proxy'(ctx, _values, [host]) {
         if (ctx.json || !host)
             throw new UsageError('ssh-proxy requires a managed host and binary standard IO');
         const targets = new AgentTargets(ctx.io.env, ctx.store.dir), entry = targets.entry(host, ctx.apiUrl);
-        const ws = await resolveWorkspace(ctx, entry.workspace);
-        const cell = await prepareSsh(ws, ctx, targets, host);
-        const stream = proxyStream(ctx.io);
+        const controller = new AbortController();
+        const signal = AbortSignal.any([ctx.signal, controller.signal]);
+        const proxyCtx = { ...ctx, signal };
+        const stream = proxyStream(ctx.io, () => controller.abort(new Error('SSH proxy stream ended')));
+        stream.on('error', error => controller.abort(error));
         try {
-            const tunnel = await new WorkspaceTunnels(() => cell, () => ws.grantedTools).forward({ remotePort: 22, stream, signal: ctx.signal });
+            const ws = await resolveWorkspace(proxyCtx, entry.workspace);
+            void ws.hint({ signal }).catch(() => undefined);
+            const cell = await prepareSsh(ws, proxyCtx, targets, host);
+            const tunnel = await new WorkspaceTunnels(() => cell, () => ws.grantedTools).forward({ remotePort: 22, stream, signal, passive: true });
             try {
                 await tunnel.closed;
             }

package/dist/agent-targets.d.ts

@@ -1,4 +1,4 @@
-export type DesktopTarget = 'claude-desktop' | 'codex-app';
+export type DesktopTarget = 'claude-desktop' | 'codex-app' | 't3';
 export interface TargetEntry {
     host: string;
     workspace: string;
@@ -10,9 +10,10 @@ export interface TargetEntry {
 export declare function targetIdentity(key: string): Pick<TargetEntry, 'host' | 'workspace' | 'project' | 'agent'>;
 /** Replace only a marked block, retaining every byte outside it. Put Includes before user Host blocks. */
 export declare function managedBlock(text: string, body: string): string;
-export declare function installedTargets(env: Record<string, string | undefined>, platform?: NodeJS.Platform): {
+export declare function installedTargets(env: Record<string, string | undefined>, platform?: NodeJS.Platform, appDirs?: string[]): {
     targets: string[];
     clients: string[];
+    versions: Partial<Record<DesktopTarget, string>>;
 };
 /** All paths are supplied by the invocation; tests use a temporary HOME, never the owner's app stores. */
 export declare class AgentTargets {
@@ -28,6 +29,7 @@ export declare class AgentTargets {
     constructor(env: Record<string, string | undefined>, dir: string);
     entry(host: string, apiUrl: string): TargetEntry;
     deviceKey(): string;
-    pin(host: string, publicKey: string): void;
-    configure(key: string | undefined, apiUrl: string, targets: DesktopTarget[], remove?: boolean): TargetEntry[];
+    pin(host: string, publicKey: string, signal?: AbortSignal): Promise<void>;
+    configure(key: string | undefined, apiUrl: string, targets: DesktopTarget[], remove?: boolean, signal?: AbortSignal): Promise<TargetEntry[]>;
+    configureProject(key: string, apiUrl: string, targets: DesktopTarget[], signal?: AbortSignal): Promise<TargetEntry[]>;
 }

package/dist/agent-targets.js

@@ -1,16 +1,20 @@
 import { spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
-import { accessSync, constants, chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, rmSync } from 'node:fs';
+import { accessSync, constants, chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, rmSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { writePrivateFile } from "./credentials.js";
 import { UsageError } from "./errors.js";
 import { projectWorkspacePath } from "./agent-repository.js";
+import { withTargetLock } from "./target-lock.js";
+const PERSISTED_TARGETS = ['claude-desktop', 'codex-app'];
 const BEGIN = '# BEGIN Shardflux managed targets';
 const END = '# END Shardflux managed targets';
 const object = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
 const shellQuote = (s) => "'" + s.replaceAll("'", "'\\''").replaceAll('%', '%%') + "'";
 const quote = (s) => '"' + s.replaceAll('\\', '\\\\').replaceAll('"', '\\"').replaceAll('%', '%%') + '"';
+// Some SSH config readers (T3 Code's host discovery) split Include on whitespace and keep quotes; quote only when needed.
+const includePath = (s) => /^[^\s"'\\#%]+$/.test(s) ? s : quote(s);
 export function targetIdentity(key) {
     const parts = key.split('/');
     if (parts.length !== 2 || parts.some(p => !/^[a-z0-9][a-z0-9._-]{0,95}$/.test(p)))
@@ -29,15 +33,48 @@ export function managedBlock(text, body) {
     const stop = end + END.length + (text[end + END.length] === '\n' ? 1 : 0);
     return text.slice(0, start) + block + text.slice(stop);
 }
-export function installedTargets(env, platform = process.platform) {
+export function installedTargets(env, platform = process.platform, appDirs) {
     const home = env.HOME || homedir();
-    const hasApp = (name, bundle) => platform === 'darwin' && [join('/Applications', name), join(home, 'Applications', name)].some(path => {
+    // SHARDFLUX_APPLICATIONS_DIRS (colon-separated) replaces the scanned app folders, like SHARDFLUX_CONFIG_DIR does for config.
+    const dirs = appDirs ?? (env.SHARDFLUX_APPLICATIONS_DIRS !== undefined ? env.SHARDFLUX_APPLICATIONS_DIRS.split(':').filter(Boolean) : ['/Applications', join(home, 'Applications')]);
+    const hasApp = (name, bundle) => platform === 'darwin' && dirs.map(dir => join(dir, name)).some(path => {
         const info = join(path, 'Contents', 'Info.plist');
         if (!existsSync(info))
             return false;
         const result = spawnSync('/usr/libexec/PlistBuddy', ['-c', 'Print :CFBundleIdentifier', info], { input: '', encoding: 'utf8', timeout: 1000 });
         return result.status === 0 && result.stdout.trim() === bundle;
     });
+    const versions = {};
+    let t3 = false;
+    if (platform === 'darwin')
+        for (const dir of dirs) {
+            let names;
+            try {
+                names = readdirSync(dir);
+            }
+            catch {
+                continue;
+            }
+            for (const name of names.filter(name => name.endsWith('.app'))) {
+                const info = join(dir, name, 'Contents', 'Info.plist');
+                // XML and binary plists store this ASCII bundle id verbatim. Avoid a
+                // subprocess for every unrelated app on the normal no-T3 path.
+                try {
+                    if (!readFileSync(info).includes('com.t3tools.t3code'))
+                        continue;
+                }
+                catch {
+                    continue;
+                }
+                const result = spawnSync('/usr/libexec/PlistBuddy', ['-c', 'Print :CFBundleIdentifier', '-c', 'Print :CFBundleShortVersionString', info], { input: '', encoding: 'utf8', timeout: 1000 });
+                const [bundle, version] = result.stdout?.trim().split('\n') ?? [];
+                if (bundle !== 'com.t3tools.t3code')
+                    continue;
+                t3 = true;
+                if (result.status === 0 && version && /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(version))
+                    versions.t3 ??= version;
+            }
+        }
     const executable = (name) => (env.PATH ?? '').split(':').filter(Boolean).some(p => { try {
         accessSync(join(p, name), constants.X_OK);
         return true;
@@ -46,7 +83,9 @@ export function installedTargets(env, platform = process.platform) {
         return false;
     } });
     const clients = [hasApp('Claude.app', 'com.anthropic.claudefordesktop') && 'claude-desktop', (hasApp('Codex.app', 'com.openai.codex') || hasApp('ChatGPT.app', 'com.openai.codex')) && 'codex-app', executable('claude') && 'claude', executable('codex') && 'codex'].filter((v) => !!v);
-    return { targets: [...(platform === 'darwin' ? clients.filter(c => c.endsWith('-app') || c === 'claude-desktop') : []), 'web'], clients };
+    if (t3)
+        clients.push('t3');
+    return { targets: [...(platform === 'darwin' ? clients.filter(c => c.endsWith('-app') || c === 'claude-desktop' || c === 't3') : []), 'web'], clients, versions };
 }
 /** All paths are supplied by the invocation; tests use a temporary HOME, never the owner's app stores. */
 export class AgentTargets {
@@ -107,11 +146,16 @@ export class AgentTargets {
         if (Object.values(doc.created).some(v => !Array.isArray(v) || v.some(k => typeof k !== 'string')))
             throw new UsageError('invalid target ownership metadata');
         for (const e of doc.entries) {
-            if (!object(e) || typeof e.workspace !== 'string' || typeof e.api_url !== 'string' || /[\r\n\0]/.test(e.api_url) || !Array.isArray(e.targets) || e.targets.some(t => t !== 'claude-desktop' && t !== 'codex-app'))
+            if (!object(e) || typeof e.workspace !== 'string' || typeof e.api_url !== 'string' || /[\r\n\0]/.test(e.api_url) || !Array.isArray(e.targets) || e.targets.some(t => typeof t !== 'string'))
                 throw new UsageError('invalid Shardflux target entry');
+            // Forward compatible: a newer CLI may record targets this one does not know; they write no files here.
+            e.targets = e.targets.filter(t => PERSISTED_TARGETS.includes(t));
             const identity = targetIdentity(e.workspace);
             if (identity.host !== e.host || identity.project !== e.project || identity.agent !== e.agent)
                 throw new UsageError('invalid Shardflux target identity');
+            // Earlier CVE entries used this optional flag. Identity now comes solely
+            // from the router workspace key; remove the obsolete flag on rewrite.
+            delete e.project_router;
         }
         return doc;
     }
@@ -139,8 +183,8 @@ export class AgentTargets {
         const key = r.stdout.trim().split(/\s+/).slice(0, 2).join(' ');
         return `${key} shardflux-device-${createHash('sha256').update(key).digest('hex').slice(0, 16)}`;
     }
-    pin(host, publicKey) {
-        this.#locked(() => this.#pin(host, publicKey));
+    pin(host, publicKey, signal) {
+        return withTargetLock(this.dir, () => this.#pin(host, publicKey), signal);
     }
     #pin(host, publicKey) {
         if (!/^shardflux-[a-z0-9._-]+$/.test(host) || !/^ssh-ed25519 [A-Za-z0-9+/=]+(?: [^\r\n]*)?$/.test(publicKey.trim()))
@@ -156,28 +200,19 @@ export class AgentTargets {
         if (!previous.length)
             writePrivateFile(this.dir, this.knownHosts, text + (text && !text.endsWith('\n') ? '\n' : '') + `${host} ${key}\n`);
     }
-    configure(key, apiUrl, targets, remove = false) {
-        return this.#locked(() => this.#configure(key, apiUrl, targets, remove));
+    configure(key, apiUrl, targets, remove = false, signal) {
+        return withTargetLock(this.dir, () => this.#configure(key, apiUrl, targets, remove), signal);
     }
-    #locked(work) {
-        mkdirSync(this.dir, { recursive: true, mode: 0o700 });
-        const lock = join(this.dir, 'targets.lock');
-        try {
-            mkdirSync(lock, { mode: 0o700 });
-        }
-        catch (e) {
-            if (e.code === 'EEXIST')
-                throw new UsageError('another target update holds targets.lock; retry after it finishes');
-            throw e;
-        }
-        try {
-            return work();
-        }
-        finally {
-            rmSync(lock, { recursive: true });
-        }
+    configureProject(key, apiUrl, targets, signal) {
+        return withTargetLock(this.dir, () => {
+            const identity = targetIdentity(key);
+            if (identity.agent !== 'router')
+                throw new UsageError('Project targets require the managed router workspace.');
+            const previous = this.#manifest().entries.filter(e => e.project === identity.project && e.api_url === apiUrl).flatMap(e => e.targets);
+            return this.#configure(key, apiUrl, [...new Set([...previous, ...targets])], false, true);
+        }, signal);
     }
-    #configure(key, apiUrl, targets, remove) {
+    #configure(key, apiUrl, targets, remove, projectTarget = false) {
         const url = new URL(apiUrl);
         if (!['https:', 'http:'].includes(url.protocol) || url.username || url.password || /[\r\n\0]/.test(apiUrl))
             throw new UsageError('invalid target API URL');
@@ -188,8 +223,11 @@ export class AgentTargets {
         const existing = old.find(e => e.host === identity?.host);
         if (existing && (existing.workspace !== key || existing.api_url !== apiUrl))
             throw new UsageError('SSH alias already belongs to another workspace or API URL');
-        const added = identity ? { ...identity, api_url: apiUrl, targets: [...new Set([...(existing?.targets ?? []), ...targets])] } : undefined;
-        const entries = remove ? old.filter(e => identity ? e.host !== identity.host : e.api_url !== apiUrl) : existing ? old.map(e => e === existing ? added : e) : [...old, added];
+        // Only targets that own a config file are recorded: published CLIs reject any other value in this manifest.
+        const added = identity ? { ...identity, api_url: apiUrl, targets: [...new Set([...(existing?.targets ?? []), ...targets.filter((t) => PERSISTED_TARGETS.includes(t))])] } : undefined;
+        let entries = remove ? old.filter(e => identity ? e.host !== identity.host : e.api_url !== apiUrl) : existing ? old.map(e => e === existing ? added : e) : [...old, added];
+        if (projectTarget)
+            entries = entries.map(e => e.host !== added.host && e.project === added.project && e.api_url === apiUrl ? { ...e, targets: [] } : e);
         const sshConfig = join(this.home, '.ssh', 'config');
         const writes = new Map();
         const rememberFile = (file) => {
@@ -208,7 +246,7 @@ export class AgentTargets {
             const text = this.#text(this.knownHosts);
             writes.set(this.knownHosts, text.split(/(?<=\n)/).filter(line => !removed.some(e => line.split(/\s+/)[0] === e.host)).join(''));
         }
-        writes.set(sshConfig, managedBlock(this.#text(sshConfig), entries.length ? `Include ${quote(this.sshFile)}` : ''));
+        writes.set(sshConfig, managedBlock(this.#text(sshConfig), entries.length ? `Include ${includePath(this.sshFile)}` : ''));
         const blocks = entries.map(e => `Host ${e.host}\n  HostName ${e.host}\n  ProxyCommand ${this.dir === join(this.home, '.config', 'shardflux') ? '' : `env ${shellQuote(`SHARDFLUX_CONFIG_DIR=${this.dir}`)} `}shard ssh-proxy %n --api-url ${shellQuote(e.api_url)}\n  User user\n  UserKnownHostsFile ${quote(this.knownHosts)}\n  StrictHostKeyChecking yes\n  IdentityFile ${quote(this.identityFile)}\n  IdentitiesOnly yes`);
         writes.set(this.sshFile, managedBlock(this.#text(this.sshFile), blocks.join('\n\n')));
         for (const [file, prop, target] of [[this.claudeFile, 'sshConfigs', 'claude-desktop'], [this.codexFile, 'remoteConnections', 'codex-app']]) {
@@ -229,7 +267,10 @@ export class AgentTargets {
             manifest.created[file] ??= [];
             if (!(prop in doc) && !manifest.created[file].includes(prop))
                 manifest.created[file].push(prop);
-            doc[prop] = [...kept, ...entries.filter(e => e.targets.includes(target)).map(e => target === 'claude-desktop' ? { id: e.host, name: `[SF] ${e.project} · ${e.agent}`, sshHost: e.host, startDirectory: projectWorkspacePath({ slug: e.project }) } : { sshAlias: e.host, projects: [{ remotePath: projectWorkspacePath({ slug: e.project }), label: `[SF] ${e.project} · ${e.agent}` }] })];
+            doc[prop] = [...kept, ...entries.filter(e => e.targets.includes(target)).map(e => {
+                    const label = e.agent === 'router' ? `Shardflux · ${e.project}` : `[SF] ${e.project} · ${e.agent}`;
+                    return target === 'claude-desktop' ? { id: e.host, name: label, sshHost: e.host, startDirectory: projectWorkspacePath({ slug: e.project }) } : { sshAlias: e.host, projects: [{ remotePath: projectWorkspacePath({ slug: e.project }), label }] };
+                })];
             if (!doc[prop].length && manifest.created[file].includes(prop))
                 delete doc[prop];
             if (file === this.codexFile) {

package/dist/args.d.ts

@@ -1,4 +1,4 @@
-export declare const CLI_VERSION = "0.13.5";
+export declare const CLI_VERSION = "0.14.0";
 export interface OptionSpec {
     type: 'string' | 'boolean';
     short?: string;

package/dist/args.js

@@ -12,7 +12,7 @@
 import { parseArgs } from 'node:util';
 import { ACCOUNT_COMMANDS } from "./account-args.js";
 import { UsageError } from "./errors.js";
-export const CLI_VERSION = '0.13.5';
+export const CLI_VERSION = '0.14.0';
 export const GLOBAL_OPTIONS = {
     'api-url': { type: 'string', value: '<url>', description: 'API base URL (default $SHARDFLUX_API_URL, else https://api.shardflux.dev).' },
     json: { type: 'boolean', description: 'Print machine-readable JSON on stdout (errors as JSON on stderr).' },
@@ -139,10 +139,29 @@ const SECRET_PERMISSIONS = {
     'allow-project': { type: 'string', multiple: true, value: '<project-id>', description: 'Organization secrets: projects whose workspaces may use it (repeatable). Default: none until granted.' },
     'all-projects': { type: 'boolean', description: 'Organization secrets: every project of the organization may use it.' },
 };
+// Cloud agents: a VM is the coding template, then the machine, then the project template.
+const LAYER_HELP = {
+    machine: 'Your machine is what every cloud agent starts with: tools, credentials, dotfiles, browser logins, git identity, Claude/Codex settings and skills. "shard machine" opens its VM; change it there (or in any agent’s VM), then run "shard machine save". It is saved from an agent’s VM, so it always keeps Claude Code, Codex and the agent runtime.',
+    template: 'The project template is this repository’s layer: toolchains, dependencies, services and project secrets. Setup after "shard ./" saves it; "shard template save" saves the current agent VM’s project changes. It is saved from an agent’s VM; "shard templates" builds templates for your own app’s workspaces instead.',
+};
 const KEY_COMMANDS = [
+    { path: ['conversations', 'list'], summary: 'List project conversations', positionals: [], options: {
+            project: { type: 'string', value: '<id>', description: 'Project ID for a user session.' }, state: { type: 'string', value: '<state>', description: 'Conversation state.' },
+            parent: { type: 'string', value: '<id>', description: 'Children of this conversation.' }, limit: { type: 'string', value: '<count>', description: 'Page size.' }, cursor: { type: 'string', value: '<cursor>', description: 'Next page cursor.' }
+        } },
+    { path: ['conversations', 'resume'], summary: 'Resume a saved conversation in a fresh VM', positionals: [{ name: 'id', required: true }], options: {} },
+    { path: ['conversations', 'reader'], summary: 'Open a read-only project space reader', positionals: [{ name: 'project_id', required: true }], options: {} },
+    { path: ['conversations', 'get'], summary: 'Show a conversation and its current VM', positionals: [{ name: 'id', required: true }], options: {} },
+    { path: ['conversations', 'send'], summary: 'Send the next user turn', positionals: [{ name: 'id', required: true }, { name: 'text', required: true, variadic: true, words: true }], options: {} },
+    { path: ['conversations', 'wait'], summary: 'Wait for a result or question', positionals: [{ name: 'id', required: true }], options: {
+            until: { type: 'string', value: '<states>', description: 'Comma-separated conversation states.' }, timeout: { type: 'string', value: '<seconds>', description: 'Wait for 0..900 seconds (default 900).' }
+        } },
+    { path: ['conversations', 'land'], summary: 'Record the landing action performed by the agent', positionals: [{ name: 'id', required: true }, { name: 'action', required: true }], options: { into: { type: 'string', value: '<ref>', description: 'Destination branch or PR URL.' } } },
+    { path: ['conversations', 'move'], summary: 'Move at the end of the turn', positionals: [{ name: 'id', required: true }, { name: 'to', required: true }], options: {} },
     ...['machine', 'template'].flatMap((level) => [
-        { path: [level], summary: level === 'machine' ? 'Open your machine agent, or show its saved filesystem with --json' : 'Show this project’s template filesystem', positionals: [], options: {} },
-        { path: [level, 'save'], summary: `Save the ${level} filesystem as a new private version`, positionals: [], options: {
+        { path: [level], summary: level === 'machine' ? 'Open your machine agent, or show its saved filesystem with --json' : 'Show this project’s template filesystem', positionals: [], options: {},
+            description: LAYER_HELP[level] },
+        { path: [level, 'save'], summary: `Save the ${level} filesystem as a new private version`, description: LAYER_HELP[level], positionals: [], options: {
                 wait: { type: 'boolean', description: 'Return when the new version is ready (or failed), printing progress on stderr.' },
                 timeout: { type: 'string', value: '<duration>', description: 'With --wait: give up waiting after this long (default 10m). The save continues server side.' },
             } },
@@ -958,7 +977,7 @@ const KEY_COMMANDS = [
     {
         path: ['templates', 'init'],
         summary: 'Write a template.yaml that starts from a base template',
-        description: 'The file is the recipe v2 document: languages, packages, files (local "from" paths are uploaded by "shard templates build"), build steps, and the settings a workspace gets when it opens (env, inputs, start commands, services, defaults). Edit it, then build it.',
+        description: 'For your own app’s workspaces (SDK/API). Cloud agents do not use it: their machine and project templates are saved from an agent’s VM with "shard machine save" and "shard template save", and a repository bound to another template is refused (template_not_agent_capable). The file is the recipe v2 document: languages, packages, files (local "from" paths are uploaded by "shard templates build"), build steps, and the settings a workspace gets when it opens (env, inputs, start commands, services, defaults). Edit it, then build it.',
         positionals: [],
         options: {
             base: { type: 'string', value: '<slug[@version]>', description: 'Base template (required), e.g. ubuntu-24.04; without @version, the version open resolves to now.' },
@@ -970,7 +989,7 @@ const KEY_COMMANDS = [
     {
         path: ['templates', 'build'],
         summary: 'Build a template from template.yaml: upload its local files and folders, then build it',
-        description: 'Folders named by "from" are packed as a reproducible tar and uploaded with files unless the organization already has the same bytes. The version stays unpublished (test it with "shard templates test") unless --publish. Progress goes to stderr.',
+        description: 'For your own app’s workspaces (SDK/API). Cloud agents do not use it: their machine and project templates are saved from an agent’s VM with "shard machine save" and "shard template save", and a repository bound to another template is refused (template_not_agent_capable). Folders named by "from" are packed as a reproducible tar and uploaded with files unless the organization already has the same bytes. The version stays unpublished (test it with "shard templates test") unless --publish. Progress goes to stderr.',
         positionals: [{ name: 'file', required: true }],
         options: {
             slug: { type: 'string', value: '<slug>', description: 'Organization template to build into (default: the name of the directory holding the file). Created by the first build.' },
@@ -1080,7 +1099,7 @@ const KEY_COMMANDS = [
     {
         path: ['templates', 'draft', 'open'],
         summary: 'Open the draft of an organization template (a layered workspace to edit live)',
-        description: 'One live draft per template. Edit it with "shard ws exec|files ... <draft key>", capture states, open test instances, then publish it as the next version.',
+        description: 'For your own app’s workspaces (SDK/API). Cloud agents do not use it: their machine and project templates are saved from an agent’s VM with "shard machine save" and "shard template save", and a repository bound to another template is refused (template_not_agent_capable). One live draft per template. Edit it with "shard ws exec|files ... <draft key>", capture states, open test instances, then publish it as the next version.',
         positionals: [SLUG],
         options: {
             base: { type: 'string', value: '<slug@version>', description: 'Version to start from (default: the template’s latest published version; required for a new template).' },
@@ -1152,14 +1171,15 @@ const AGENT_OPTIONS = {
     approvals: { type: 'boolean', description: 'Keep the agent’s permission prompts.' },
 };
 export const PROJECT_COMMAND = {
-    path: ['<path>'], summary: 'Open the project’s cloud agent command center, or start its agent directly with claude|codex',
-    description: 'Naming the app starts (or reattaches) that agent at once; with --json it starts detached and prints the session. Detach with Ctrl-] then d; /exit ends the agent session.',
-    positionals: [{ name: 'path', required: true }, { name: 'claude|codex' }], options: AGENT_OPTIONS,
+    path: ['<path>'], summary: 'Start a conversation in its own cloud VM',
+    description: 'Opens Claude Code or Codex directly. --resume continues a project conversation. With --json it starts detached and prints the session. Detach with Ctrl-] then d.',
+    positionals: [{ name: 'path', required: true }, { name: 'claude|codex' }], options: { ...AGENT_OPTIONS, new: { type: 'boolean', description: 'Start a new conversation.' }, resume: { type: 'boolean', description: 'Continue a conversation from this project.' } },
 };
 export const CENTER_COMMAND = { path: ['<center>'], summary: 'Open the cloud agent command center', positionals: [], options: {} };
 const AGENT_COMMANDS = [
+    { path: ['conversations', 'try'], summary: 'Try a conversation in a synced local worktree', positionals: [{ name: 'conversation', required: true }], options: { path: { type: 'string', value: '<path>', description: 'Local project checkout.' }, stop: { type: 'boolean', description: 'Stop the device helper’s local sync and ports.' } } },
     { path: ['agents', 'targets'], summary: 'Detect apps or configure managed desktop connections', positionals: [{ name: 'agent' }], options: { remove: { type: 'boolean', description: 'Remove this agent’s managed entries, or all entries for this API URL.' } } },
-    ...['claude-desktop', 'codex-app', 'web'].map(target => ({ path: ['agents', 'open', target], summary: `Open the agent in ${target}`, positionals: [{ name: 'agent' }], options: { reachable: AGENT_OPTIONS.reachable } })),
+    ...['claude-desktop', 'codex-app', 'web', 't3'].map(target => ({ path: ['agents', 'open', target], summary: `Open the agent in ${target}`, positionals: [{ name: 'agent' }], options: { reachable: AGENT_OPTIONS.reachable } })),
     { path: ['ssh-proxy'], summary: 'Forward SSH standard IO to a managed workspace', positionals: [{ name: 'host', required: true }], options: {} },
     ...['worktree', 'merge', 'keep', 'discard', 'restore'].map((action) => ({
         path: ['agents', action], summary: { worktree: 'Open agent work in a local worktree', merge: 'Merge agent work into the current branch and clean up', keep: 'Keep agent work as a branch and clean up', discard: 'Delete an agent and its local work', restore: 'Restore archived work as a local branch within 30 days' }[action],
@@ -1169,12 +1189,13 @@ const AGENT_COMMANDS = [
             ...(action === 'keep' ? { push: { type: 'boolean', description: 'Push the kept branch to origin and open a PR when gh is installed.' } } : {}),
         },
     })),
-    { path: ['agents', 'open'], summary: 'Attach an agent in the terminal', description: 'Detach with Ctrl-] then d; /exit ends the agent session.', positionals: [{ name: 'agent', required: true }], options: { ...AGENT_OPTIONS, app: { type: 'string', value: '<claude|codex>', description: 'Agent app (default remembered choice).' }, in: { type: 'string', value: '<terminal>', description: 'Where to open the session (default terminal).' } } },
+    { path: ['agents', 'open'], summary: 'Attach an agent in the terminal', description: 'Detach with Ctrl-] then d; /exit ends the agent session.', positionals: [{ name: 'agent', required: true }], options: { ...AGENT_OPTIONS, app: { type: 'string', value: '<claude|codex>', description: 'Agent app (default remembered choice).' }, in: { type: 'string', value: '<terminal|claude-desktop|codex-app|web|t3>', description: 'Where to open the session (default terminal).' } } },
     { path: ['agents', 'new'], summary: 'Start a session or a named agent', positionals: [{ name: 'agent' }], options: {
             ...AGENT_OPTIONS,
             app: { type: 'string', value: '<claude|codex>', description: 'Agent app (default remembered choice).' },
             path: { type: 'string', value: '<path>', description: 'Local project path for first launch.' },
             name: { type: 'string', value: '<name>', description: 'New agent name; copies the project main workspace with --like.' },
+            in: { type: 'string', value: '<terminal|claude-desktop|codex-app|t3>', description: 'Where to open the new agent (default terminal).' },
             like: { type: 'string', value: '<id|key>', description: 'Copy the workspace configuration onto a fresh disk.' },
         } },
     { path: ['agents', 'fork'], summary: 'Fork an agent’s memory and disk', positionals: [{ name: 'agent', required: true }, { name: 'name', required: true }], options: WAIT },
@@ -1193,6 +1214,7 @@ const MENUBAR_COMMANDS = ['start', 'stop', 'status'].map(action => ({
 export const COMMANDS = [...ACCOUNT_COMMANDS.filter((c) => c.path[0] !== 'templates'), ...AGENT_COMMANDS, ...AGENT_CREDENTIAL_COMMANDS, ...MENUBAR_COMMANDS, ...KEY_COMMANDS, ...ACCOUNT_COMMANDS.filter((c) => c.path[0] === 'templates')];
 const GROUPS = {
     menubar: 'macOS menu bar app',
+    conversations: 'Project conversations, branches and messages',
     agents: 'Cloud agent sessions and copied credentials',
     auth: 'Create an account and sign in (the session is saved in the credentials file); passwords, email, two-factor authentication and sessions',
     'auth password': 'Change or reset your password',
@@ -1218,6 +1240,8 @@ const GROUPS = {
     templates: 'Build templates from template.yaml, test and export versions, browse templates (file tree, diff), develop them in a draft, and publish or archive versions',
 };
 const ALIASES = {
+    c: 'conversations',
+    conversation: 'conversations',
     ws: 'workspaces',
     workspace: 'workspaces',
     ops: 'operations',
@@ -1361,6 +1385,8 @@ function toParseArgsOptions(opts) {
  * returns help text for --help, bare groups and non-TTY bare `shard`.
  */
 export function parseCommandLine(argv, options = {}) {
+    if (argv.length === 1 && (argv[0] === 'acp' || argv[0] === 'device-helper'))
+        return { kind: 'run', command: { path: [argv[0]], summary: '', positionals: [], options: {} }, values: {}, positionals: [], global: { apiUrl: undefined, json: false, agentLabel: undefined, wake: undefined, wakeTimeout: undefined } };
     const terminator = argv.indexOf('--');
     const head = terminator < 0 ? argv : argv.slice(0, terminator);
     const leading = [];
@@ -1551,8 +1577,9 @@ export const EXIT_CODE_HELP = [
 /** The top help's sections: every command's group (first word) is in exactly one (args.test.ts checks). */
 export const HELP_SECTIONS = [
     { title: 'Account (a user session: shard signup or shard auth login)', groups: ['signup', 'verify', 'auth', 'setup', 'env', 'orgs', 'projects', 'api-keys', 'members', 'invitations', 'billing', 'audit', 'account'] },
-    { title: 'Workspaces (a project API key: SHARDFLUX_API_KEY, else the one shard setup saved)', groups: ['login', 'whoami', 'status', 'usage', 'machine', 'template', 'agents', 'ssh-proxy', 'workspaces', 'files', 'operations', 'executions', 'secrets', 'credentials', 'volumes', 'egress'] },
-    { title: 'Templates (publish and archive use the session; the rest the API key)', groups: ['templates'] },
+    { title: 'Cloud agents (shard ./ starts one; a project API key)', groups: ['conversations', 'machine', 'template', 'agents', 'ssh-proxy'] },
+    { title: 'Workspaces for your app (a project API key: SHARDFLUX_API_KEY, else the one shard setup saved)', groups: ['login', 'whoami', 'status', 'usage', 'workspaces', 'files', 'operations', 'executions', 'secrets', 'credentials', 'volumes', 'egress'] },
+    { title: 'Templates for your app’s workspaces (not for cloud agents; publish and archive use the session, the rest the API key)', groups: ['templates'] },
     { title: 'Other', groups: ['menubar', 'update', 'feedback', 'version'] },
 ];
 export function topHelp() {
@@ -1575,7 +1602,19 @@ export function topHelp() {
         `  shard auth verify-email '<link from the email>'`,
         `  printf '%s\\n' "$PASSWORD" | shard auth login --email you@example.com`,
         '  shard setup                                   # organization, project and an API key, saved',
-        '  shard ws open demo --template python-node-browser',
+        '  shard ./                                      # a cloud agent for this folder',
+        '  shard ws open demo --template python-node-browser   # or a workspace for your app (SDK/API)',
+        '',
+        'Cloud agents (Claude Code or Codex in its own VM, with your setup):',
+        '  shard ./                                      # a conversation on this folder’s repository: Claude Code in its own VM (shard ./ codex: Codex; --resume: a saved one)',
+        '  shard machine save                            # what every agent starts with: tools, logins, dotfiles, Claude/Codex config',
+        '  shard template save                           # this project: toolchains, dependencies, services, project secrets',
+        '  A VM is the coding template, then your machine, then the project template. Setup after shard ./ saves the',
+        '  project template; machine and project templates are always saved from an agent’s VM, so they keep Claude Code,',
+        '  Codex and the agent runtime. "shard templates" is for your own app’s workspaces, not for agents: a repository',
+        '  bound to such a template is refused (template_not_agent_capable).',
+        '  In the VM, Claude Code and Codex have Shardflux computer use next to their own tools: the shardflux-computer MCP',
+        '  server’s computer and computer_batch drive the VM’s desktop (start programs with DISPLAY=:1).',
         ...sections,
         '',
         'Aliases: ws = workspaces, ops = operations, org = orgs, keys = api-keys; "shard workspaces files|operations|executions ..." also works.',