@shardflux/cli 0.14.0 → 0.14.1

package/dist/agent-repository.js

@@ -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-target-commands.d.ts

@@ -7,7 +7,7 @@ import type { DesktopTarget } from './agent-targets.js';
 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, ended?: () => void): 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>;

package/dist/agent-target-commands.js

@@ -19,7 +19,6 @@ const keyOf = (ref) => ref.includes('/') ? ref : `${projectIdentity('./').slug}/
 /** Optimistic file replacement preserves keys installed by other devices connecting at the same time. */
 export async function installDeviceKey(cell, key, signal) {
     const path = '/home/user/.ssh/authorized_keys';
-    await cell.files.mkdir('/home/user/.ssh', { mode: '0700', parents: true });
     for (let attempt = 0; attempt < 4; attempt++) {
         let text = '', revision = 'absent';
         try {
@@ -34,8 +33,11 @@ export async function installDeviceKey(cell, key, signal) {
                 throw e;
         }
         const publicPart = key.split(' ').slice(0, 2).join(' ');
+        // A reconnect finds its key with one read; only a first key creates the directory.
         if (text.split('\n').some(line => line.trim().split(/\s+/).slice(0, 2).join(' ') === publicPart))
             return;
+        if (revision === 'absent')
+            await cell.files.mkdir('/home/user/.ssh', { mode: '0700', parents: true });
         try {
             await cell.files.patch({ path, content: text + (text && !text.endsWith('\n') ? '\n' : '') + key + '\n', expectedRevision: revision, mode: '0600' }, { signal });
             return;
@@ -47,16 +49,22 @@ export async function installDeviceKey(cell, key, signal) {
     }
     throw new Error('authorized_keys kept changing; retry the SSH connection');
 }
-/** Host trust is established over the authenticated files API, before sending any SSH protocol bytes. */
-export async function prepareSsh(ws, ctx, targets, host) {
+async function sshCell(ws, ctx) {
     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 });
-    await targets.pin(host, hostKey, ctx.signal);
-    await installDeviceKey(cell, targets.deviceKey(), ctx.signal);
+    return ws.cell({ agentLabel: ctx.agentLabel, transitionTimeoutMs: ctx.wakeTimeoutMs });
+}
+/** Host trust over the authenticated files API: the host key pin and this device's key, read together. */
+async function trustSsh(cell, targets, host, signal) {
+    const [hostKey] = await Promise.all([cell.files.readText('/etc/ssh/ssh_host_ed25519_key.pub', { length: 4096 }), installDeviceKey(cell, targets.deviceKey(), signal)]);
+    await targets.pin(host, hostKey, signal);
+}
+/** Host trust is established over the authenticated files API, before sending any SSH protocol bytes. */
+export async function prepareSsh(ws, ctx, targets, host) {
+    const cell = await sshCell(ws, ctx);
+    await trustSsh(cell, targets, host, ctx.signal);
     return cell;
 }
 async function openApp(target, env) {
@@ -70,10 +78,10 @@ async function openApp(target, env) {
             reject(new Error(`app launcher exited ${code}`)); });
     });
 }
-export function proxyStream(io, ended) {
+export function proxyStream(io, ended, outputGate) {
     const stdout = io.stdout;
     const source = Readable.from(io.stdin, { objectMode: false });
-    let blocked = false;
+    let blocked = false, gate = outputGate;
     const pump = () => {
         while (!blocked && !stream.destroyed) {
             const bytes = source.read();
@@ -86,17 +94,24 @@ export function proxyStream(io, ended) {
         allowHalfOpen: true,
         read() { blocked = false; pump(); },
         write(bytes, _encoding, done) {
-            try {
-                if (stdout.write(bytes))
-                    done();
-                else if (stdout.once)
-                    stdout.once('drain', done);
-                else
-                    done(new Error('stdout cannot signal backpressure'));
-            }
-            catch (e) {
-                done(e);
-            }
+            const send = () => {
+                try {
+                    if (stdout.write(bytes))
+                        done();
+                    else if (stdout.once)
+                        stdout.once('drain', done);
+                    else
+                        done(new Error('stdout cannot signal backpressure'));
+                }
+                catch (e) {
+                    done(e);
+                }
+            };
+            // No guest byte reaches the SSH client before the gate opens (its host key pinned).
+            if (gate)
+                void gate.then(() => { gate = undefined; send(); }, (e) => done(e instanceof Error ? e : new Error(String(e))));
+            else
+                send();
         },
         // A guest can close before SSH authenticates (e.g. sshd MaxStartups).
         // Once output drains, end the proxy so SSH sees EOF instead of waiting
@@ -220,13 +235,26 @@ export const TARGET_HANDLERS = {
         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')));
+        let trusted, distrusted;
+        const trust = new Promise((resolve, reject) => { trusted = resolve; distrusted = reject; });
+        trust.catch(() => { });
+        const stream = proxyStream(ctx.io, () => controller.abort(new Error('SSH proxy stream ended')), trust);
         stream.on('error', error => controller.abort(error));
         try {
             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 });
+            const cell = await sshCell(ws, proxyCtx);
+            // Trust and the tunnel start run together; the stream holds guest bytes until the host key is pinned.
+            const trusting = trustSsh(cell, targets, host, signal).then(trusted, (e) => { distrusted(e); controller.abort(e); throw e; });
+            const [opened, checked] = await Promise.allSettled([new WorkspaceTunnels(() => cell, () => ws.grantedTools).forward({ remotePort: 22, stream, signal, passive: true }), trusting]);
+            if (checked.status === 'rejected') {
+                if (opened.status === 'fulfilled')
+                    await opened.value.close().catch(() => { });
+                throw checked.reason;
+            }
+            if (opened.status === 'rejected')
+                throw opened.reason;
+            const tunnel = opened.value;
             try {
                 await tunnel.closed;
             }

package/dist/args.d.ts

@@ -1,4 +1,4 @@
-export declare const CLI_VERSION = "0.14.0";
+export declare const CLI_VERSION = "0.14.1";
 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.14.0';
+export const CLI_VERSION = '0.14.1';
 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).' },
@@ -1614,7 +1614,7 @@ export function topHelp() {
         '  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).',
+        '  server’s computer and computer_batch drive the VM’s desktop (start programs with DISPLAY=:1 setsid -f).',
         ...sections,
         '',
         'Aliases: ws = workspaces, ops = operations, org = orgs, keys = api-keys; "shard workspaces files|operations|executions ..." also works.',

package/dist/conversation-router.js

@@ -73,6 +73,9 @@ export async function prepareDesktopRouter(ctx, source) {
             if (imported.exitCode !== 0)
                 throw new Error(`Project router repository could not be prepared: ${imported.stderr.trim()}`);
         }
+        const seed = await cell.exec.run(['git', '-C', workspaceRepositoryPath(source), '-c', 'core.hooksPath=/dev/null', 'push', '/shardflux/project/git/hub.git', `${commit}:refs/shard/router/seeds/${commit}`], { timeoutMs: 120_000, signal: ctx.signal });
+        if (seed.exitCode !== 0)
+            throw new Error(`Project router hub seed failed: ${seed.stderr.trim()}`);
         await destination.files.mkdir('/home/user/.config/shardflux', { parents: true, mode: '0700' });
         await destination.files.write(ROUTER_CONFIG, JSON.stringify({ ...config, cwd: root }) + '\n', { mode: '0600' });
         return router;

package/dist/conversation-stash.js

@@ -7,7 +7,7 @@ import { gitRunner } from "./agent-git.js";
 import { shardRemote } from "./git-remote.js";
 import { writePrivateFile } from "./credentials.js";
 import { conversationClient } from "./conversation-commands.js";
-const MAX = 256 << 20;
+const MAX = 64 << 20; // Guest FileManifest uses the project-sync 64 MiB per-file bound.
 export function rewriteTranscript(bytes, remoteCwd, localCwd) {
     const text = new TextDecoder('utf8', { fatal: true }).decode(bytes);
     const rewrite = (value) => {

package/dist/conversations.d.ts

@@ -1,4 +1,4 @@
-import type { Workspace } from '@shardflux/sdk';
+import type { Workspace, WorkspaceView } from '@shardflux/sdk';
 import type { Ctx } from './commands.js';
 export type Harness = 'claude' | 'codex';
 export interface Conversation {
@@ -45,7 +45,7 @@ export declare function resolveConversation(ctx: Ctx, ref: string, folder?: stri
 /** Re-resolve the binding on every attach: a move changes the VM, never the conversation identity. */
 export declare function conversationWorkspace(ctx: Ctx, c: Conversation): Promise<Workspace>;
 export declare function restoreConversationBinding(ctx: Ctx, c: Conversation, ws: Workspace): Promise<void>;
-export declare function createConversationRecord(ctx: Ctx, folder: string, harness: Harness, route: Conversation['route'], name?: string): Promise<Conversation>;
+export declare function createConversationRecord(ctx: Ctx, folder: string, harness: Harness, route: Conversation['route'], name?: string, allocated?: (workspace: WorkspaceView) => void, idempotencyKey?: string): Promise<Conversation>;
 export declare function createConversation(ctx: Ctx, folder: string, harness: Harness, route: Conversation['route'], name?: string): Promise<{
     conversation: Conversation;
     workspace: Workspace;

package/dist/conversations.js

@@ -85,7 +85,7 @@ export async function restoreConversationBinding(ctx, c, ws) {
     if (result.exitCode !== 0)
         throw new Error(`Conversation restore failed: ${result.stderr.trim()}`);
 }
-export async function createConversationRecord(ctx, folder, harness, route, name) {
+export async function createConversationRecord(ctx, folder, harness, route, name, allocated, idempotencyKey = randomUUID()) {
     const project = projectIdentity(folder);
     // Detect the optional control-plane feature before applying the new Git contract to old APIs.
     await conversationClient(ctx).conversations.list({ limit: 1 });
@@ -93,8 +93,9 @@ export async function createConversationRecord(ctx, folder, harness, route, name
     const commit = await git(['rev-parse', 'HEAD']);
     const branch = await git(['symbolic-ref', '--quiet', '--short', 'HEAD']).catch(() => undefined);
     const response = await conversationClient(ctx).conversations.create({ repoRemote: project.remote ?? `file://${project.folder}`, harness, route, mode: 'new',
-        base: { commit, ...(branch ? { branch } : {}) }, ...(name ? { name } : {}), projectId: ctx.store.profile(ctx.apiUrl).project_id }, { idempotencyKey: randomUUID(), signal: ctx.signal });
+        base: { commit, ...(branch ? { branch } : {}) }, ...(name ? { name } : {}), projectId: ctx.store.profile(ctx.apiUrl).project_id }, { idempotencyKey, signal: ctx.signal });
     const c = validateConversation({ ...response.conversation, restore: response.restore });
+    allocated?.(response.workspace);
     rememberConversation(ctx, c, project.folder);
     return c;
 }

package/dist/device-bridge.d.ts

@@ -39,7 +39,7 @@ type Result = {
     stderr_b64?: string;
     files_artifact?: string;
 };
-/** Resolve every existing ancestor, including symlinks. Missing leaf files do not hide an outside parent. */
+/** Resolve existing ancestors even before the conversation worktree is created. */
 export declare function devicePath(root: string, requested?: string): {
     path: string;
     outside: boolean;

package/dist/device-bridge.js

@@ -18,11 +18,7 @@ const LIMIT = 256 << 20, OUTPUT = (192 << 10) - 128;
 const inside = (root, target) => target === root || target.startsWith(root + sep);
 const safeId = (value) => { if (!/^[a-zA-Z0-9_-]{1,96}$/.test(value))
     throw new Error('Invalid device request identity'); return value; };
-/** Resolve every existing ancestor, including symlinks. Missing leaf files do not hide an outside parent. */
-export function devicePath(root, requested = '.') {
-    if (/[\0\r\n]/.test(requested))
-        throw new UsageError('Device path contains invalid characters.');
-    const base = realpathSync(root), target = isAbsolute(requested) ? resolve(requested) : resolve(base, requested);
+function canonicalDevicePath(target) {
     let ancestor = target;
     while (!existsSync(ancestor)) {
         const parent = dirname(ancestor);
@@ -30,7 +26,14 @@ export function devicePath(root, requested = '.') {
             throw new UsageError('Device path is unavailable.');
         ancestor = parent;
     }
-    const canonical = resolve(realpathSync(ancestor), relative(ancestor, target));
+    return resolve(realpathSync(ancestor), relative(ancestor, target));
+}
+/** Resolve existing ancestors even before the conversation worktree is created. */
+export function devicePath(root, requested = '.') {
+    if (/[\0\r\n]/.test(requested))
+        throw new UsageError('Device path contains invalid characters.');
+    const base = canonicalDevicePath(resolve(root)), target = isAbsolute(requested) ? resolve(requested) : resolve(base, requested);
+    const canonical = canonicalDevicePath(target);
     return { path: canonical, outside: !inside(base, canonical) };
 }
 export class DeviceGrants {
@@ -162,12 +165,13 @@ export class DeviceExecutor {
         const record = records[r.conversation_id] ?? (folders.size === 1 ? matching[0] : undefined);
         if (!record || record.project_id !== r.project_id)
             return; // No inferred local path for unknown projects.
-        let c = await getConversation(ctx, r.conversation_id), ws = await conversationWorkspace(ctx, c);
+        let c = await getConversation(ctx, r.conversation_id);
         if (c.project_id !== r.project_id)
             throw new Error('Device request project changed.');
-        const root = await ensureConversationWorktree(ctx, c, record.folder, ws);
+        const planned = devicePath(record.folder, join('.shard', 'worktrees', conversationName(c)));
         const requested = r.exec?.cwd_relative ?? r.files?.local_path_relative ?? '.';
-        const target = devicePath(root, requested), grants = new DeviceGrants(ctx.store.dir);
+        const target = devicePath(planned.path, requested), grants = new DeviceGrants(ctx.store.dir);
+        target.outside ||= planned.outside;
         const choice = grants.allows(ctx.apiUrl, r.project_id, record.folder, r.kind, target.outside) ? 'once' : await this.#ask({ type: 'approval', request_id: r.id, project_id: r.project_id, conversation_id: c.id, summary: deviceSummary(r), outside: target.outside });
         if (choice === 'deny') {
             await this.result(r, { state: 'denied' });
@@ -180,20 +184,27 @@ export class DeviceExecutor {
         if (choice === 'always')
             await grants.save(ctx.apiUrl, r.project_id, record.folder, r.kind);
         // Re-read after the approval, before claiming or touching data.
-        if (devicePath(root, requested).path !== target.path)
+        if (devicePath(record.folder, join('.shard', 'worktrees', conversationName(c))).path !== planned.path || devicePath(planned.path, requested).path !== target.path)
             throw new Error('Device path changed during approval.');
         const current = await getConversation(ctx, r.conversation_id);
         if (current.project_id !== c.project_id || current.branch !== c.branch || current.state === 'done' || current.state === 'archived')
             throw new Error('The conversation changed or ended during device approval.');
-        if (current.workspace_id !== c.workspace_id) {
-            ws.cell().close();
-            ws = await conversationWorkspace(ctx, current);
-        }
         c = current;
         await this.result(r, { state: 'approved' });
         await this.result(r, { state: 'running' });
-        const cell = ws.cell();
+        let ws;
         try {
+            // Approval is independent of VM/Git availability. Bound setup and report its
+            // failure through the existing running -> failed transition.
+            const preparation = { ...ctx, signal: AbortSignal.any([ctx.signal, AbortSignal.timeout(30_000)]) };
+            ws = await conversationWorkspace(preparation, c);
+            const root = await ensureConversationWorktree(preparation, c, record.folder, ws);
+            if (root !== planned.path || devicePath(root, requested).path !== target.path)
+                throw new Error('Device path changed during preparation.');
+            const prepared = await getConversation(ctx, c.id);
+            if (prepared.project_id !== c.project_id || prepared.workspace_id !== c.workspace_id || prepared.branch !== c.branch || prepared.state === 'done' || prepared.state === 'archived')
+                throw new Error('The conversation changed or ended during device preparation.');
+            const cell = ws.cell();
             let result;
             if (r.kind === 'try_locally' || tryLocallyAction(r)) {
                 const action = tryLocallyAction(r);
@@ -260,7 +271,7 @@ export class DeviceExecutor {
         }
         finally {
             if (!this.#handles.has(r.id))
-                cell.close();
+                ws?.cell().close();
         }
     }
     async reap() {

package/dist/git-remote-bin.js

@@ -22,7 +22,9 @@ try {
         if (!ws)
             throw new Error(`workspace ${remote.key} does not exist`);
         cell = ws.cell({ agentLabel: 'git-remote-shard', transitionTimeoutMs: 120_000 });
-        return cell.exec;
+        const capability = await cell.exec.run(['/usr/local/bin/sf-agent', 'git-bridge-info'], { timeoutMs: 10_000, maxOutputBytes: 4096, signal: controller.signal });
+        const platformGitBridge = capability.exitCode === 0 && JSON.parse(capability.stdout).version === 1;
+        return { ...cell.exec, platformGitBridge };
     }, controller.signal);
 }
 catch (error) {

package/dist/git-remote.d.ts

@@ -7,7 +7,9 @@ export interface ShardRemote {
 /** Keys have two segments (K9). Everything after the agent is an absolute guest path. */
 export declare function parseShardRemote(url: string): ShardRemote;
 export declare function shardRemote(key: string, path: string): string;
-export type GitExec = Pick<CellClient['exec'], 'start' | 'input' | 'output' | 'cancel'>;
+export type GitExec = Pick<CellClient['exec'], 'start' | 'input' | 'output' | 'cancel'> & {
+    platformGitBridge?: boolean;
+};
 /** No text decoding of the pack stream; offsets are acknowledged bytes, including partial stdin writes. */
 export declare function bridgeGit(exec: GitExec, service: string, path: string, input: AsyncIterable<Uint8Array>, stdout: Writable, stderr: Writable, signal: AbortSignal): Promise<number>;
 /** Git's `connect` capability switches from newline commands to a full-duplex smart protocol. */

package/dist/git-remote.js

@@ -28,7 +28,8 @@ export async function bridgeGit(exec, service, path, input, stdout, stderr, sign
         throw new UsageError('unsupported Git service');
     const controller = new AbortController();
     const combined = AbortSignal.any([signal, controller.signal]);
-    const session = await exec.start({ argv: [service, path], stdin_open: true, timeout_ms: 600_000 }, combined);
+    const argv = exec.platformGitBridge ? ['/usr/local/bin/sf-agent', 'git-bridge', '--service', service, '--path', path] : [service, path];
+    const session = await exec.start({ argv, stdin_open: true, timeout_ms: 600_000 }, combined);
     let ended = false, offset = 0;
     const send = async () => {
         for await (const chunk of input) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shardflux/cli",
-  "version": "0.14.0",
+  "version": "0.14.1",
   "type": "module",
   "description": "shard: the Shardflux command line. Create an account, sign in, set up keys and billing, then open, run commands in, move files to, suspend, resume and fork serverless agent workspaces.",
   "license": "Apache-2.0",
@@ -47,7 +47,7 @@
     "smol-toml": "1.9.0",
     "snappyjs": "0.7.0",
     "yaml": "2.9.1",
-    "@shardflux/sdk": "^0.19.0"
+    "@shardflux/sdk": "^0.19.1"
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",