@shardflux/cli 0.14.1 → 0.14.3

package/CHANGELOG.md

@@ -1,11 +1,23 @@
 # Changelog
 
+## 0.14.3
+
+- Poll device requests and deliver approvals independently of transcript mirroring, so a slow or failed copy cannot delay file-push approvals. Isolate mirror failures by conversation, retry with exponential backoff, and log each failure once per conversation revision with the affected entry name.
+- Skip unknown, nested, symlink and oversized transcript entries while mirroring safe top-level JSONL and JSON files. Log each skipped name once per conversation, preserve the empty append-lock exception, and refuse symlink destinations or ancestors inside the stash.
+
+## 0.14.2
+
+- `shard agents open` accepts conversation keys, VM keys and conversation ids, reattaching the existing Claude Code or Codex session in its conversation worktree. The menu bar's Open action uses the same path; legacy agents retain their existing behavior.
+- Start local projects without Git history: initialize a repository on `main` when needed and create one empty initial commit, preserving existing files and staged work. Use a command-local Shardflux identity when Git identity is missing, and report actionable `git_error` failures.
+
 ## 0.14.1
 
 - `shard ssh-proxy` connects faster: host trust (host key pin and device key) runs alongside the tunnel start, with no guest byte reaching OpenSSH before the host key is pinned, and a reconnect checks its device key with one read.
 
 ## 0.14.0
 
+- Mirror native conversation transcripts when the guest includes its empty append-lock file.
+
 - Ask for device approval before preparing the VM-backed local worktree; report a failed preparation as the request's result and bound preparation to 30 seconds.
 - Keep desktop programs running after a command returns with detached `setsid -f` guidance.
 - Allocate one VM per new ACP conversation, with cached initial model choices and live updates from that same VM.

package/README.md

@@ -81,6 +81,7 @@ Your branch opens in `.shard/worktrees/<name>`, syncs both ways, and its dev ser
 Ctrl-C stops local sync. Your main checkout stays available for your own work.
 Device tools ask Allow once or Always for this project on your Mac before preparing the conversation’s local worktree. Live transcripts stay in
 `~/.config/shardflux/conversations/`; ended sessions enter Claude Code’s or Codex’s native history. Transcript files up to 64 MiB are supported (0.14.0+).
+From 0.14.3, transcript copying runs independently of device approvals. Unknown entries are skipped, and failed copies retry with backoff; diagnostics name the conversation and affected entry.
 
 For application workspace commands, `shard signup` creates an account and saves a project key, or set
 `SHARDFLUX_API_KEY` to a key from the console and run `shard login`. `shard --help` lists every command.
@@ -1153,6 +1154,9 @@ Set `--reachable 30m` when opening a workspace to choose how long waiting agents
 ## Cloud agents (0.13.2+)
 
 Run `shard ./` in your project to start Claude Code or Codex, usable immediately while setup runs in the background.
+
+New project folders are ready to use: `shard ./` and `shard agents new` initialize Git on `main` when needed and create an empty initial commit (CLI 0.14.2+). Existing files and staged work stay yours; the initial commit contains no files. Repositories without commits keep their current branch. If Git identity is missing, that one commit uses `Shardflux <noreply@shardflux.dev>` without changing your Git configuration.
+
 Your **machine** carries credentials, tools, dotfiles, logins and agent config; the project's **template** carries
 toolchains, dependencies, services and project secrets. Both are private filesystem templates and include secrets
 as ordinary files. Browser logins and Claude/Codex config belong to the machine. Set up tools and secrets normally inside the VM;

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.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";
@@ -135,7 +135,7 @@ async function initializeProjectGit(cell, folder, root, signal, populate = false
         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');

package/dist/args.d.ts

@@ -1,4 +1,4 @@
-export declare const CLI_VERSION = "0.14.1";
+export declare const CLI_VERSION = "0.14.3";
 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.1';
+export const CLI_VERSION = '0.14.3';
 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).' },

package/dist/conversation-stash.d.ts

@@ -4,8 +4,18 @@ import type { Conversation, LocalConversation } from './conversations.js';
 export declare function rewriteTranscript(bytes: Uint8Array, remoteCwd: string, localCwd: string): Uint8Array;
 export declare function transcriptDestination(c: Conversation, folder: string, filename: string, env: Record<string, string | undefined>): string;
 /** Keep growing copies away from native session discovery until the control plane ends the conversation. */
-export declare function mirrorConversation(ctx: Ctx, record: LocalConversation, source: Workspace): Promise<void>;
+export declare function mirrorConversation(ctx: Ctx, record: LocalConversation, source: Workspace, skipped?: Set<string>): Promise<void>;
 export declare function handoffConversation(ctx: Pick<Ctx, 'io' | 'store' | 'apiUrl' | 'signal'>, c: Conversation, folder: string, dir: string, source?: Pick<Workspace, 'key'> | {
     hub: string;
 }): Promise<void>;
-export declare function mirrorProjectConversations(ctx: Ctx, mirrored?: Map<string, string>): Promise<void>;
+export declare class ConversationMirrorState {
+    readonly mirrored: Map<string, string>;
+    readonly skipped: Map<string, Set<string>>;
+    readonly retries: Map<string, {
+        revision: string;
+        failures: number;
+        retryAt: number;
+        reported: Set<string>;
+    }>;
+}
+export declare function mirrorProjectConversations(ctx: Ctx, state?: ConversationMirrorState): Promise<void>;

package/dist/conversation-stash.js

@@ -1,5 +1,5 @@
 import { createHash } from 'node:crypto';
-import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync } from 'node:fs';
+import { closeSync, constants, existsSync, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { homedir } from 'node:os';
 import { conversationName, listConversations, localConversations, rememberConversation } from "./conversations.js";
@@ -45,31 +45,79 @@ function privateDirectory(path) {
         at = parent;
     }
     if (existsSync(at) && lstatSync(at).isSymbolicLink())
-        throw new Error('Transcript directory must not be a symlink.');
+        throw new Error(`Transcript directory must not be a symlink: ${at}`);
     mkdirSync(path, { recursive: true, mode: 0o700 });
     if (lstatSync(path).isSymbolicLink())
-        throw new Error('Transcript directory must not be a symlink.');
+        throw new Error(`Transcript directory must not be a symlink: ${path}`);
+}
+function readStashFile(file) {
+    const fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    try {
+        if (!fstatSync(fd).isFile())
+            throw new Error(`Stash entry is not a regular file: ${file}`);
+        return readFileSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
 }
 /** Keep growing copies away from native session discovery until the control plane ends the conversation. */
-export async function mirrorConversation(ctx, record, source) {
+export async function mirrorConversation(ctx, record, source, skipped = new Set()) {
     const c = record.conversation;
-    const dir = join(ctx.store.dir, 'conversations', c.project_id, c.id), root = `/shardflux/project/transcripts/${c.id}`;
+    if (!/^[a-zA-Z0-9_-]+$/.test(c.project_id) || !/^conv_[a-z0-9]{26}$/.test(c.id))
+        throw new Error('Transcript stash identity is unsafe.');
+    let dir = ctx.store.dir;
+    // Check each stash component before creating children; no ancestor inside the stash may be a symlink.
     privateDirectory(dir);
+    for (const part of ['conversations', c.project_id, c.id]) {
+        dir = join(dir, part);
+        privateDirectory(dir);
+    }
+    const root = `/shardflux/project/transcripts/${c.id}`;
+    const skip = (name, reason) => {
+        if (skipped.has(name))
+            return;
+        skipped.add(name);
+        ctx.io.stderr.write(`Transcript mirror ${c.id}: skipped entry ${JSON.stringify(name)} (${reason}).\n`);
+    };
     const cell = source.cell({ wake: null });
+    const close = () => cell.close();
+    ctx.signal.addEventListener('abort', close, { once: true });
     try {
+        ctx.signal.throwIfAborted();
         const manifest = await cell.files.manifest(root, { maxFileBytes: MAX, signal: ctx.signal });
-        if (manifest.skipped.length)
-            throw new Error('Project transcript copy includes files outside the mirror bound.');
+        for (const entry of manifest.skipped)
+            skip(entry.path, entry.reason);
         let count = 0;
         for (const entry of manifest.entries) {
-            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') : '';
-            if (expected !== entry.sha256) {
-                const bytes = await cell.files.read(`${root}/${entry.path}`, { length: Math.min(MAX + 1, entry.size + 1) });
-                if (bytes.length !== entry.size || createHash('sha256').update(bytes).digest('hex') !== entry.sha256)
-                    throw new Error('Transcript changed during copying; retaining the previous stash.');
-                writePrivateFile(dir, file, new TextDecoder('utf8', { fatal: true }).decode(bytes));
+            // 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('..') || entry.path.includes('/') || !/^[a-zA-Z0-9_.-]+\.(jsonl|json)$/.test(entry.path)) {
+                skip(entry.path, 'not a safe top-level JSONL or JSON file');
+                continue;
+            }
+            if (!Number.isSafeInteger(entry.size) || entry.size < 0 || entry.size > MAX) {
+                skip(entry.path, 'outside the 64 MiB mirror bound');
+                continue;
+            }
+            try {
+                const file = join(dir, entry.path), existing = lstatSync(file, { throwIfNoEntry: false });
+                if (existing && !existing.isFile()) {
+                    skip(entry.path, 'stash destination is not a regular file');
+                    continue;
+                }
+                const expected = existing ? createHash('sha256').update(readStashFile(file)).digest('hex') : '';
+                if (expected !== entry.sha256) {
+                    const bytes = await cell.files.read(`${root}/${entry.path}`, { length: entry.size + 1 });
+                    if (bytes.length !== entry.size || createHash('sha256').update(bytes).digest('hex') !== entry.sha256)
+                        throw new Error('Transcript changed during copying; retaining the previous stash.');
+                    writePrivateFile(dir, file, new TextDecoder('utf8', { fatal: true }).decode(bytes));
+                }
+            }
+            catch (e) {
+                throw new Error(`Entry ${JSON.stringify(entry.path)}: ${e instanceof Error ? e.message : String(e)}`, { cause: e });
             }
             if (entry.path.endsWith('.jsonl'))
                 count++;
@@ -80,26 +128,27 @@ export async function mirrorConversation(ctx, record, source) {
             const binding = await conversationClient(ctx).workspaces.get(c.workspace_id);
             if (!binding.data.deleted_at)
                 return;
-            const meta = JSON.parse(readFileSync(join(dir, 'meta.json'), 'utf8'));
-            if (!c.harness_session_id || meta.harness !== c.harness || meta.harness_session_id !== c.harness_session_id || !/^[a-zA-Z0-9_.-]+\.jsonl$/.test(meta.file))
-                throw new Error('Transcript handoff metadata does not match the ended conversation.');
-            const bytes = readFileSync(join(dir, meta.file));
+            const meta = JSON.parse(readStashFile(join(dir, 'meta.json')).toString('utf8'));
+            if (!meta || !c.harness_session_id || meta.harness !== c.harness || meta.harness_session_id !== c.harness_session_id || typeof meta.file !== 'string' || meta.file.includes('..') || !/^[a-zA-Z0-9_.-]+\.jsonl$/.test(meta.file))
+                throw new Error('Entry "meta.json": transcript handoff metadata does not match the ended conversation.');
+            const bytes = readStashFile(join(dir, meta.file));
             if (bytes.length !== meta.bytes || createHash('sha256').update(bytes).digest('hex') !== meta.sha256)
-                throw new Error('Transcript handoff checkpoint differs from its durable metadata.');
+                throw new Error(`Entry ${JSON.stringify(meta.file)}: transcript handoff checkpoint differs from its durable metadata.`);
             await handoffConversation(ctx, { ...c, worktree_path: meta.cwd }, record.folder, dir, source);
         }
     }
     finally {
+        ctx.signal.removeEventListener('abort', close);
         cell.close();
     }
 }
 export async function handoffConversation(ctx, c, folder, dir, source) {
     if (c.state !== 'done' && c.state !== 'archived')
         throw new Error('Only an ended conversation can enter native history.');
-    const files = readdirSync(dir).filter(f => f.endsWith('.jsonl'));
+    const files = readdirSync(dir).filter(f => !f.includes('..') && /^[a-zA-Z0-9_.-]+\.jsonl$/.test(f) && lstatSync(join(dir, f)).isFile());
     if (!files.length)
         throw new Error('Conversation has no transcript to hand off.');
-    const writes = files.map(name => ({ dest: transcriptDestination(c, folder, name, ctx.io.env), bytes: rewriteTranscript(readFileSync(join(dir, name)), c.worktree_path, folder) }));
+    const writes = files.map(name => ({ dest: transcriptDestination(c, folder, name, ctx.io.env), bytes: rewriteTranscript(readStashFile(join(dir, name)), c.worktree_path, folder) }));
     // Check every destination before the first write. Preserve local native history on any collision.
     for (const { dest, bytes } of writes) {
         if (existsSync(dest) && (lstatSync(dest).isSymbolicLink() || !readFileSync(dest).equals(Buffer.from(bytes))))
@@ -119,7 +168,12 @@ export async function handoffConversation(ctx, c, folder, dir, source) {
     rememberConversation(ctx, c, folder, true);
     writePrivateFile(dir, join(dir, 'handoff.json'), JSON.stringify({ conversation_id: c.id, branch: c.branch, destinations: writes.map(w => w.dest), at: new Date().toISOString() }) + '\n');
 }
-export async function mirrorProjectConversations(ctx, mirrored = new Map()) {
+export class ConversationMirrorState {
+    mirrored = new Map();
+    skipped = new Map();
+    retries = new Map();
+}
+export async function mirrorProjectConversations(ctx, state = new ConversationMirrorState()) {
     const records = localConversations(ctx);
     if (!Object.keys(records).length)
         return;
@@ -129,30 +183,57 @@ export async function mirrorProjectConversations(ctx, mirrored = new Map()) {
         if (!c || record.handed_off || !c.harness_session_id)
             continue;
         const revision = JSON.stringify([c.workspace_id, c.harness_session_id, c.state, c.durable, c.last_activity_at, c.summary]);
-        if (mirrored.get(c.id) === revision)
+        if (state.mirrored.get(c.id) === revision)
             continue;
-        rememberConversation(ctx, c, record.folder);
-        let source;
-        for (const candidate of [c, ...all.filter(other => other.project_id === c.project_id && other.id !== c.id)]) {
-            try {
-                const ws = await conversationClient(ctx).workspaces.get(candidate.workspace_id);
-                if (!ws.data.deleted_at && ws.ready) {
-                    source = ws;
-                    break;
+        let retry = state.retries.get(c.id);
+        if (!retry || retry.revision !== revision) {
+            retry = { revision, failures: 0, retryAt: 0, reported: new Set() };
+            state.retries.set(c.id, retry);
+        }
+        if (Date.now() < retry.retryAt)
+            continue;
+        try {
+            rememberConversation(ctx, c, record.folder);
+            let source;
+            for (const candidate of [c, ...all.filter(other => other.project_id === c.project_id && other.id !== c.id)]) {
+                try {
+                    const ws = await conversationClient(ctx).workspaces.get(candidate.workspace_id);
+                    if (!ws.data.deleted_at && ws.ready) {
+                        source = ws;
+                        break;
+                    }
                 }
+                catch { /* Another binding may be available. */ }
+            }
+            if (!source) {
+                const client = conversationClient(ctx);
+                const reader = await client.conversations.spaceReader(c.project_id, { signal: ctx.signal });
+                source = await client.workspaces.get(reader.workspace.id);
+                if (!source.ready)
+                    await source.wake({ timeoutMs: ctx.wakeTimeoutMs, signal: ctx.signal });
+            }
+            let skipped = state.skipped.get(c.id);
+            if (!skipped) {
+                skipped = new Set();
+                state.skipped.set(c.id, skipped);
             }
-            catch { /* Another binding may be available. */ }
+            await mirrorConversation(ctx, { ...record, conversation: c }, source, skipped);
+            retry.failures = 0;
+            retry.retryAt = 0;
+            // An ended record may precede its VM tombstone; retry until the handoff receipt is written.
+            if (c.state !== 'done' && c.state !== 'archived')
+                state.mirrored.set(c.id, revision);
         }
-        if (!source) {
-            const client = conversationClient(ctx);
-            const reader = await client.conversations.spaceReader(c.project_id, { signal: ctx.signal });
-            source = await client.workspaces.get(reader.workspace.id);
-            if (!source.ready)
-                await source.wake({ timeoutMs: ctx.wakeTimeoutMs, signal: ctx.signal });
+        catch (e) {
+            if (ctx.signal.aborted)
+                return;
+            const message = e instanceof Error ? e.message : String(e);
+            const backoff = Math.min(300_000, 5000 * 2 ** Math.min(retry.failures++, 6));
+            retry.retryAt = Date.now() + backoff;
+            if (!retry.reported.has(message)) {
+                retry.reported.add(message);
+                ctx.io.stderr.write(`Transcript mirror ${c.id}: ${message} (retrying in ${backoff / 1000}s).\n`);
+            }
         }
-        await mirrorConversation(ctx, { ...record, conversation: c }, source);
-        // An ended record may precede its VM tombstone; retry until the handoff receipt is written.
-        if (c.state !== 'done' && c.state !== 'archived')
-            mirrored.set(c.id, revision);
     }
 }

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.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";
@@ -87,7 +88,8 @@ export async function restoreConversationBinding(ctx, c, ws) {
 }
 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']);

package/dist/device-helper.js

@@ -1,6 +1,6 @@
 import { setTimeout as delay } from 'node:timers/promises';
 import { DeviceExecutor, askConnectedAcp } from "./device-bridge.js";
-import { mirrorProjectConversations } from "./conversation-stash.js";
+import { ConversationMirrorState, mirrorProjectConversations } from "./conversation-stash.js";
 import { withTargetLock } from "./target-lock.js";
 import { join } from 'node:path';
 import { conversationsUnavailable } from "./conversations.js";
@@ -49,7 +49,7 @@ export async function runDeviceHelper(ctx) {
         });
     };
     const working = new Map();
-    const mirrored = new Map();
+    const mirrored = new ConversationMirrorState();
     const deviceFile = join(ctx.store.dir, 'device-id');
     let deviceId;
     try {
@@ -61,8 +61,32 @@ export async function runDeviceHelper(ctx) {
     }
     const executor = new DeviceExecutor(ctx, ask, deviceId);
     const report = (e) => { ctx.io.stderr.write(`Device bridge: ${e instanceof Error ? e.message : String(e)}\n`); };
+    let mirroring;
     try {
         return await withTargetLock(join(ctx.store.dir, 'device-helper-lock'), async () => {
+            // A slow or failed transcript copy must not delay heartbeats, request polling or approvals.
+            mirroring = (async () => {
+                let failures = 0;
+                const reported = new Set();
+                while (!signal.aborted) {
+                    let wait = 1000;
+                    try {
+                        await mirrorProjectConversations(ctx, mirrored);
+                        failures = 0;
+                    }
+                    catch (e) {
+                        if (signal.aborted)
+                            break;
+                        wait = Math.min(300_000, 5000 * 2 ** Math.min(failures++, 6));
+                        const message = e instanceof Error ? e.message : String(e);
+                        if (!conversationsUnavailable(e) && !reported.has(message)) {
+                            reported.add(message);
+                            ctx.io.stderr.write(`Transcript mirror discovery: ${message} (retrying in ${wait / 1000}s).\n`);
+                        }
+                    }
+                    await delay(wait, undefined, { signal }).catch(() => undefined);
+                }
+            })();
             while (!signal.aborted) {
                 try {
                     for (const projectId of new Set(Object.values(localConversations(ctx)).map(r => r.project_id))) {
@@ -80,7 +104,6 @@ export async function runDeviceHelper(ctx) {
                         } while (cursor && !signal.aborted);
                     }
                     await executor.reap();
-                    await mirrorProjectConversations(ctx, mirrored);
                 }
                 catch (e) {
                     if (!signal.aborted && !conversationsUnavailable(e))
@@ -99,6 +122,7 @@ export async function runDeviceHelper(ctx) {
         pending.clear();
         await executor.close();
         await Promise.all([...working.values()]);
+        await mirroring;
         await input.catch(() => undefined);
     }
 }

package/dist/errors.d.ts

@@ -28,6 +28,13 @@ declare class HintedError extends Error {
 export declare class UsageError extends HintedError {
     name: string;
 }
+/** Keep Git exit statuses for optional probes while reporting actionable CLI errors. */
+export declare class GitError extends HintedError {
+    name: string;
+    readonly code: string | number | undefined;
+    readonly stderr: string;
+    constructor(folder: string, cause: unknown);
+}
 /**
  * A refusal `shard` detects itself, with a stable code, its facts in `details` and the next step as `hint` (exit 1),
  * e.g. `repository_too_large` (0.13.3+) for Git history over the initial sync limit.

package/dist/errors.js

@@ -36,6 +36,22 @@ class HintedError extends Error {
 export class UsageError extends HintedError {
     name = 'UsageError';
 }
+/** Keep Git exit statuses for optional probes while reporting actionable CLI errors. */
+export class GitError extends HintedError {
+    name = 'GitError';
+    code;
+    stderr;
+    constructor(folder, cause) {
+        const failure = cause;
+        const detail = failure.stderr?.trim() || failure.message || 'Git command failed';
+        super(`Git failed in ${folder}: ${detail}\n${failure.code === 'ENOENT' ? 'Install Git and make sure git is on PATH, then run shard again.' : 'Resolve this Git error, then run shard again.'}`, failure.code === 'ENOENT'
+            ? 'Install Git and make sure git is on PATH, then run shard again.'
+            : `Check Git permissions, configuration and repository state with git -C ${JSON.stringify(folder)} status, resolve the error above, then run shard again.`);
+        this.code = failure.code;
+        this.stderr = failure.stderr ?? '';
+        this.cause = cause;
+    }
+}
 /**
  * A refusal `shard` detects itself, with a stable code, its facts in `details` and the next step as `hint` (exit 1),
  * e.g. `repository_too_large` (0.13.3+) for Git history over the initial sync limit.
@@ -199,6 +215,8 @@ export function describeError(err) {
         return { code: 'timeout', message: err.message, last_state: err.session.state, details: { session_id: err.session.session_id } };
     if (err instanceof UsageError)
         return { code: 'usage', message: err.message };
+    if (err instanceof GitError)
+        return { code: 'git_error', message: err.message, retryable: false };
     if (err instanceof CodedError)
         return { code: err.code, message: err.message, retryable: false, ...(err.details ? { details: err.details } : {}) };
     if (err instanceof CheckoutTimeoutError) {

package/dist/project-git.d.ts

@@ -0,0 +1,3 @@
+import type { Ctx } from './commands.js';
+/** Prepare only the selected project root. Never stage files or initialize a nested repository. */
+export declare function ensureProjectGit(ctx: Ctx, folder: string): Promise<void>;

package/dist/project-git.js

@@ -0,0 +1,52 @@
+import { existsSync, realpathSync } from 'node:fs';
+import { join } from 'node:path';
+import { gitRunner } from "./agent-git.js";
+import { GitError } from "./errors.js";
+/** Prepare only the selected project root. Never stage files or initialize a nested repository. */
+export async function ensureProjectGit(ctx, folder) {
+    const git = gitRunner(folder, { ...process.env, ...ctx.io.env, LC_ALL: 'C' }, ctx.signal, false);
+    let initialized = false;
+    try {
+        const top = await git(['rev-parse', '--show-toplevel']);
+        if (realpathSync(top) !== realpathSync(folder))
+            return;
+    }
+    catch (error) {
+        if (!(error instanceof GitError) || error.code !== 128 || !error.stderr.includes('not a git repository'))
+            throw error;
+        if (existsSync(join(folder, '.git')))
+            throw error;
+        await git(['init', '-b', 'main']);
+        initialized = true;
+    }
+    try {
+        await git(['rev-parse', '--verify', '--quiet', 'HEAD^{commit}']);
+        return;
+    }
+    catch (error) {
+        if (!(error instanceof GitError) || error.code !== 1)
+            throw error;
+        // An absent branch is unborn; a broken existing ref is a Git failure, not permission to replace it.
+        const branch = await git(['symbolic-ref', 'HEAD']);
+        const absent = await git(['show-ref', '--verify', '--quiet', branch]).then(() => false, (refError) => {
+            if (!(refError instanceof GitError) || refError.code !== 1)
+                throw refError;
+            return true;
+        });
+        if (!absent)
+            throw error;
+    }
+    // --only with no paths makes an empty commit even when the user already has staged files.
+    const commit = ['-c', 'core.hooksPath=/dev/null', 'commit', '--allow-empty', '--only', '-m', 'Initial commit'];
+    try {
+        await git(commit);
+    }
+    catch (error) {
+        if (!(error instanceof GitError) || !/Author identity unknown|Committer identity unknown|unable to auto-detect email address|empty ident name|no (?:name|email) was given/.test(error.stderr))
+            throw error;
+        await git(['-c', 'user.name=Shardflux', '-c', 'user.email=noreply@shardflux.dev', ...commit]);
+    }
+    ctx.io.stderr.write(initialized
+        ? `Initialized a git repository in ${folder} (shard tracks your project with git).\n`
+        : `Created an initial empty commit in ${folder}.\n`);
+}

package/dist/project-sync-manifest.js

@@ -3,6 +3,7 @@ import { execFile } from 'node:child_process';
 import { constants } from 'node:fs';
 import { lstat, open, readdir, readlink, realpath } from 'node:fs/promises';
 import { basename, dirname, join, relative, resolve, sep } from 'node:path';
+import { GitError } from "./errors.js";
 export const MAX_SYNC_FILE_BYTES = 64 * 1024 * 1024;
 export const MAX_SYNC_ENTRIES = 20_000;
 export function validSyncPath(path) {
@@ -46,13 +47,19 @@ export function parseManifest(manifest) {
 }
 export async function projectGit(folder, args, signal, input = '') {
     return new Promise((resolve, reject) => {
-        const child = execFile('git', ['-C', folder, '-c', 'core.fsmonitor=false', '-c', 'core.untrackedCache=false', '-c', 'core.hooksPath=/dev/null', ...args], { encoding: 'utf8', timeout: 30_000, maxBuffer: 4 << 20, signal, env: { ...process.env, GIT_TERMINAL_PROMPT: '0', GIT_OPTIONAL_LOCKS: '0' } }, (error, stdout) => {
-            if (error) {
-                const failure = Object.assign(new Error(error.message, { cause: error }), { code: error.code, stdout });
-                reject(failure);
-            }
-            else
+        const child = execFile('git', ['-C', folder, '-c', 'core.fsmonitor=false', '-c', 'core.untrackedCache=false', '-c', 'core.hooksPath=/dev/null', ...args], { encoding: 'utf8', timeout: 30_000, maxBuffer: 4 << 20, signal, env: { ...process.env, GIT_TERMINAL_PROMPT: '0', GIT_OPTIONAL_LOCKS: '0' } }, (error, stdout, stderr) => {
+            if (!error) {
                 resolve(stdout);
+                return;
+            }
+            if (signal?.aborted) {
+                const abortError = error;
+                reject(abortError);
+                return;
+            }
+            const failure = new GitError(folder, Object.assign(error, { stderr }));
+            Object.assign(failure, { stdout });
+            reject(failure);
         });
         child.stdin?.on('error', () => undefined); // Early Git refusal is reported by the callback.
         child.stdin?.end(input);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shardflux/cli",
-  "version": "0.14.1",
+  "version": "0.14.3",
   "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",