@shardflux/cli 0.14.0 → 0.14.2

package/dist/agent-commands.js

@@ -8,6 +8,7 @@ import { AgentStateStore } from "./agent-state.js";
 import { attachTerminal, cellConnector } from "./agent-terminal.js";
 import { prepareProjectTemplate } from "./project-template-setup.js";
 import { projectIdentity, projectLabels } from "./project-identity.js";
+import { ensureProjectGit } from "./project-git.js";
 import { json } from "./format.js";
 import { resolveWorkspace } from "./commands.js";
 import { savedMachine } from "./filesystem-state.js";
@@ -21,6 +22,8 @@ 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";
+import { conversationWorkspace, conversationsUnavailable, getConversation, listConversations, resumeConversation } from "./conversations.js";
+import { conversationTerminal } from "./conversation-terminal.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) {
@@ -169,6 +172,10 @@ export const launchProject = async (ctx, values, [path = './', explicitApp]) =>
     if (agent !== 'main')
         agentName(agent);
     const labels = projectLabels(project, agent, app);
+    const local = like ? projectIdentity(path) : project;
+    // A cloud-only --like launch must not initialize an unrelated local checkout.
+    if (!like?.labels.repo_remote || like.labels.repo_remote === (local.remote ?? `file://${local.folder}`))
+        await ensureProjectGit(ctx, local.folder);
     const cloud = ctx.cloud();
     let existing = await cloud.workspaces.findByKey(`${project.slug}/${agent}`, { includeDeleted: false, signal: ctx.signal });
     const owner = agent === 'main' ? existing : like ?? await cloud.workspaces.findByKey(`${project.slug}/main`, { includeDeleted: false, signal: ctx.signal });
@@ -237,18 +244,52 @@ export const AGENT_HANDLERS = {
         }
         await syncCredentials(ctx);
         let ws;
-        if (agent.includes('/'))
-            ws = await ctx.cloud().workspace(agent, { create: false }).open();
+        let conversation;
+        if (/^conv_[a-z0-9]{26}$/.test(agent)) {
+            conversation = await resumeConversation(ctx, await getConversation(ctx, agent));
+            ws = await conversationWorkspace(ctx, conversation);
+        }
         else {
-            const project = projectIdentity('./');
-            if (!/^[a-z0-9][a-z0-9._-]{0,63}$/.test(agent))
-                throw new UsageError('agent must be a workspace key or an agent name');
-            ws = await ctx.cloud().workspace(`${project.slug}/${agent}`, { create: false }).open();
+            let key = agent;
+            if (!agent.includes('/')) {
+                const project = projectIdentity('./');
+                if (!/^[a-z0-9][a-z0-9._-]{0,63}$/.test(agent))
+                    throw new UsageError('agent must be a workspace key or an agent name');
+                key = `${project.slug}/${agent}`;
+            }
+            try {
+                ws = await ctx.cloud().workspace(key, { create: false }).open();
+            }
+            catch (error) {
+                if (!missing(error))
+                    throw error;
+                // A conversation key differs from its VM key (and survives VM moves).
+                let matches;
+                try {
+                    matches = (await listConversations(ctx)).filter(c => c.key === key);
+                }
+                catch (e) {
+                    if (conversationsUnavailable(e))
+                        throw error;
+                    throw e;
+                }
+                if (!matches.length)
+                    throw error;
+                if (matches.length !== 1)
+                    throw new UsageError('Use the conversation id.');
+                conversation = await resumeConversation(ctx, matches[0]);
+                ws = await conversationWorkspace(ctx, conversation);
+            }
+            // The menu bar supplies workspace_key from agents list, not the conversation key.
+            if (!conversation && ws.labels.shard_conversation) {
+                conversation = await resumeConversation(ctx, await getConversation(ctx, ws.labels.shard_conversation));
+                ws = await conversationWorkspace(ctx, conversation);
+            }
         }
         if (values.reachable !== undefined)
             ws = await ctx.cloud().workspaces.open({ key: ws.key, ...agentReachability(values), wait: false });
         const projectKey = typeof values.project === 'string' ? values.project : ws.labels.repo_remote || ws.labels.shard_project || ws.key;
-        const app = values.app ?? new AgentStateStore(ctx.store.dir).app(projectKey, ws.labels.app === 'codex' ? 'codex' : 'claude');
+        const app = conversation?.harness ?? values.app ?? new AgentStateStore(ctx.store.dir).app(projectKey, ws.labels.app === 'codex' ? 'codex' : 'claude');
         if (app === 'claude' && !await cloudClaudeLogin(ctx)) {
             progress(ctx, 'Signing in to cloud Claude (once per account)…');
             await loginClaudeInWorkspace(ctx, ws);
@@ -258,6 +299,8 @@ export const AGENT_HANDLERS = {
         if (ws.labels.shard_layer !== 'machine' && !(await savedMachine(ctx))?.template)
             await syncAgentConfig(ctx, ws);
         await prepareAgentMachine(ctx, ws);
+        if (conversation)
+            return conversationTerminal(ctx, ws, conversation, projectKey, values);
         return terminal(ctx, ws, app, (ws.labels.agent ?? agent).split('/').at(-1), projectKey, values);
     },
 };

package/dist/agent-git.d.ts

@@ -16,7 +16,7 @@ export interface GitRepository {
 }
 export type GitRepositories = Record<string, GitRepository>;
 export type GitRun = (args: string[]) => Promise<string>;
-export declare function gitRunner(root: string, env?: NodeJS.ProcessEnv, signal?: AbortSignal): GitRun;
+export declare function gitRunner(root: string, env?: NodeJS.ProcessEnv, signal?: AbortSignal, remoteHelper?: boolean): GitRun;
 export declare function agentName(name: string): string;
 export declare class AgentGit {
     readonly root: string;

package/dist/agent-git.js

@@ -2,18 +2,25 @@ import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
-import { UsageError } from "./errors.js";
+import { GitError, UsageError } from "./errors.js";
 import { AgentStateStore } from "./agent-state.js";
 import { gitPath } from "./git-remote-helper.js";
 const execute = promisify(execFile);
 const DAY = 86_400_000;
-export function gitRunner(root, env = process.env, signal) {
+export function gitRunner(root, env = process.env, signal, remoteHelper = true) {
     return async (args) => {
-        const result = await execute('git', ['--no-pager', '-C', root, ...args], {
-            env: { ...env, PATH: gitPath(env), GIT_TERMINAL_PROMPT: '0', GIT_MERGE_AUTOEDIT: 'no' },
-            timeout: 120_000, maxBuffer: 4 * 1024 * 1024, signal,
-        });
-        return result.stdout.trim();
+        try {
+            const result = await execute('git', ['--no-pager', '-C', root, ...args], {
+                env: { ...env, PATH: remoteHelper ? gitPath(env) : env.PATH, GIT_TERMINAL_PROMPT: '0', GIT_MERGE_AUTOEDIT: 'no' },
+                timeout: 120_000, maxBuffer: 4 * 1024 * 1024, signal,
+            });
+            return result.stdout.trim();
+        }
+        catch (error) {
+            if (signal?.aborted)
+                throw error;
+            throw new GitError(root, error);
+        }
     };
 }
 export function agentName(name) {

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

@@ -2,7 +2,7 @@ import { randomUUID } from 'node:crypto';
 import { mkdtemp, readFile, rm, stat } from 'node:fs/promises';
 import { homedir, tmpdir } from 'node:os';
 import { join, resolve } from 'node:path';
-import { CodedError } from "./errors.js";
+import { CodedError, UsageError } from "./errors.js";
 import { AgentStateStore } from "./agent-state.js";
 import { projectIdentity } from "./project-identity.js";
 import { localManifest, projectGit } from "./project-sync-manifest.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,11 +131,11 @@ 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)
-        throw new Error('project sync requires the Git repository root; run shard there');
+        throw new UsageError('project sync requires the Git repository root; run shard there');
     const existing = await cell.exec.run(['git', '-C', root, 'rev-parse', '--verify', 'HEAD'], { timeoutMs: 5000, signal });
     if (existing.exitCode !== 0 && existing.exitCode !== 128)
         throw new Error('could not check workspace Git history');
@@ -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.2";
 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.2';
 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) => {
@@ -62,6 +62,10 @@ export async function mirrorConversation(ctx, record, source) {
             throw new Error('Project transcript copy includes files outside the mirror bound.');
         let count = 0;
         for (const entry of manifest.entries) {
+            // Flush holds this empty regular file while appending the transcript.
+            // It is synchronization metadata, not native history to mirror.
+            if (entry.path === '.lock' && !entry.symlink && entry.size === 0 && entry.sha256 === 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855')
+                continue;
             if (entry.symlink || entry.path.includes('/') || !/^[a-zA-Z0-9_.-]+\.(jsonl|json)$/.test(entry.path))
                 throw new Error('Project transcript copy has an unsafe entry.');
             const file = join(dir, entry.path), expected = existsSync(file) ? createHash('sha256').update(readFileSync(file)).digest('hex') : '';

package/dist/conversation-terminal.d.ts

@@ -1,3 +1,8 @@
-import type { Handler } from './commands.js';
+import type { Workspace } from '@shardflux/sdk';
+import type { Ctx, Handler } from './commands.js';
+import type { Values } from './args.js';
+import type { Conversation } from './conversations.js';
+/** Every terminal entry point uses the durable conversation's native harness, worktree and session. */
+export declare function conversationTerminal(ctx: Ctx, ws: Workspace, c: Conversation, project: string, values: Values): Promise<number>;
 /** Select a durable conversation, then use the harness's native terminal for all interaction. */
 export declare const launchConversationProject: Handler;

package/dist/conversation-terminal.js

@@ -1,7 +1,7 @@
 import { randomUUID } from 'node:crypto';
 import { AgentStateStore } from "./agent-state.js";
 import { projectIdentity, projectLabels } from "./project-identity.js";
-import { createConversation, conversationWorkspace, conversationsUnavailable, listConversations, localConversations, rememberConversation, resumeConversation, restoreConversationBinding } from "./conversations.js";
+import { createConversation, conversationName, conversationWorkspace, conversationsUnavailable, listConversations, localConversations, rememberConversation, resumeConversation, restoreConversationBinding } from "./conversations.js";
 import { terminal } from "./agent-commands.js";
 import { cloudClaudeLogin, loginClaudeInWorkspace, requireClaudeTerminal } from "./claude-cloud-login.js";
 import { syncAgentCredentials } from "./agent-credentials.js";
@@ -13,6 +13,11 @@ import { ensureMenubar, MenubarManager } from "./menubar.js";
 import { UsageError } from "./errors.js";
 import { localResumeTerminal } from "./conversation-local-resume.js";
 import { agentReachability } from "./agent-reachability.js";
+/** Every terminal entry point uses the durable conversation's native harness, worktree and session. */
+export async function conversationTerminal(ctx, ws, c, project, values) {
+    await restoreConversationBinding(ctx, c, ws);
+    return terminal(ctx, ws, c.harness, conversationName(c), project, values, undefined, c.worktree_path, { id: c.id, session: c.harness_session_id });
+}
 /** Select a durable conversation, then use the harness's native terminal for all interaction. */
 export const launchConversationProject = async (ctx, values, [path = './', explicit]) => {
     const project = projectIdentity(path), store = new AgentStateStore(ctx.store.dir);
@@ -35,8 +40,7 @@ export const launchConversationProject = async (ctx, values, [path = './', expli
         const next = await resumeConversation(ctx, c);
         rememberConversation(ctx, next, project.folder);
         const ws = await conversationWorkspace(ctx, next);
-        await restoreConversationBinding(ctx, next, ws);
-        return terminal(ctx, ws, app, next.key.split('/').at(-1), project.remote ?? project.folder, values, undefined, next.worktree_path, { id: next.id, session: next.harness_session_id });
+        return conversationTerminal(ctx, ws, next, project.remote ?? project.folder, values);
     }
     await syncAgentCredentials(ctx.cloud(), { home: ctx.io.env.HOME, redact: value => ctx.addSecret(value) });
     const signedIn = app === 'claude' ? await cloudClaudeLogin(ctx) : true;
@@ -70,5 +74,5 @@ export const launchConversationProject = async (ctx, values, [path = './', expli
     if (!(await savedMachine(ctx))?.template)
         await syncAgentConfig(ctx, ws);
     await ensureMenubar(ctx.store.dir, ctx.apiUrl, new MenubarManager({ home: ctx.io.env.HOME, signal: ctx.signal }));
-    return terminal(ctx, ws, app, c.key.split('/').at(-1), project.remote ?? project.folder, values, undefined, c.worktree_path, { id: c.id, session: c.harness_session_id });
+    return conversationTerminal(ctx, ws, c, project.remote ?? project.folder, values);
 };

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

@@ -3,6 +3,7 @@ import { ShardfluxApiError } from '@shardflux/sdk';
 import { AgentStateStore } from "./agent-state.js";
 import { gitRunner } from "./agent-git.js";
 import { projectIdentity } from "./project-identity.js";
+import { ensureProjectGit } from "./project-git.js";
 import { seedAgentRepository } from "./agent-repository.js";
 import { UsageError } from "./errors.js";
 import { conversationClient } from "./conversation-commands.js";
@@ -85,16 +86,18 @@ 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 ensureProjectGit(ctx, project.folder);
+    // Both the conversation API and its legacy workspace fallback need a usable local HEAD.
     await conversationClient(ctx).conversations.list({ limit: 1 });
     const git = gitRunner(project.folder, { ...process.env, ...ctx.io.env }, ctx.signal);
     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;