@shardflux/cli 0.22.0 → 0.23.1

package/dist/menubar.js

@@ -1,3 +1,4 @@
+import { desktopAccount } from "./desktop-account.js";
 import { execFile, spawn } from 'node:child_process';
 import { chmodSync, closeSync, cpSync, existsSync, lstatSync, mkdirSync, mkdtempSync, openSync, readdirSync, readFileSync, renameSync, rmSync, writeSync } from 'node:fs';
 import { createRequire } from 'node:module';
@@ -16,7 +17,7 @@ const execute = promisify(execFile);
  * whether or not a built Shardflux.app is in the package.
  */
 export const nativeTools = {
-    run: async (tool, args, signal) => (await execute(tool, args, { timeout: 15000, maxBuffer: 1024 * 1024, signal })).stdout,
+    run: async (tool, args, signal, env) => (await execute(tool, args, { timeout: 15000, maxBuffer: 1024 * 1024, signal, ...(env ? { env: { ...process.env, ...env } } : {}) })).stdout,
 };
 const BUNDLE_ID = 'dev.shardflux.menubar';
 export function compareBundleVersions(left, right) {
@@ -123,7 +124,7 @@ export class MenubarManager {
     constructor(options = {}) {
         this.app = join(options.home ?? homedir(), 'Applications', 'Shardflux.app');
         this.#platform = options.platform ?? process.platform;
-        this.#run = options.run ?? ((tool, args) => nativeTools.run(tool, args, options.signal));
+        this.#run = options.run ?? ((tool, args, env) => nativeTools.run(tool, args, options.signal, env));
         this.#packageApp = options.packageApp ?? (() => {
             const app = packagedAppPath();
             if (!app)
@@ -160,43 +161,51 @@ export class MenubarManager {
             return null;
         }
     }
-    async #control(action, ...args) {
+    /**
+     * The app's --control for `configDir`: its pids are the app running for that config directory, wherever it runs from
+     * (menu bar 0.8.4+, one app per config directory), and any app running from the installed bundle.
+     */
+    async #control(configDir, action, ...args) {
         makeExecutable(this.app);
-        return parseNativeStatus(await this.#run(join(this.app, 'Contents', 'MacOS', 'ShardfluxMenuBar'), ['--control', action, ...args]));
+        const env = configDir ? { SHARDFLUX_CONFIG_DIR: configDir } : undefined;
+        return parseNativeStatus(await this.#run(join(this.app, 'Contents', 'MacOS', 'ShardfluxMenuBar'), ['--control', action, ...args], env));
     }
-    async status() {
+    async status(configDir) {
         this.#requireMac();
         if (!existsSync(this.app))
             return { installed: false, version: null, running: false, pids: [], login: 'off' };
         const version = await this.#version(this.app);
-        return { installed: true, version, ...await this.#control('status') };
+        return { installed: true, version, ...await this.#control(configDir, 'status') };
     }
     async #stripQuarantine() {
         const attributes = await this.#run('/usr/bin/xattr', ['-lr', this.app]);
         if (attributes.includes('com.apple.quarantine'))
             await this.#run('/usr/bin/xattr', ['-dr', 'com.apple.quarantine', this.app]);
     }
-    async stop() {
-        const current = await this.status();
+    async stop(configDir) {
+        const current = await this.status(configDir);
         if (!current.installed || !current.running)
             return current;
-        await this.#control('stop');
+        await this.#control(configDir, 'stop');
         for (let i = 0; i < 20; i++) {
-            const status = await this.status();
+            const status = await this.status(configDir);
             if (!status.running)
                 return status;
             await new Promise(resolve => setTimeout(resolve, 100));
         }
         throw new UsageError('Shardflux is still stopping. Run shard menubar status before retrying.');
     }
-    async login(value) {
-        if (!(await this.status()).installed)
+    async login(value, configDir) {
+        if (!(await this.status(configDir)).installed)
             throw new UsageError('Run shard menubar start before changing launch at login.');
-        await this.#control('login', value);
-        return this.status();
+        await this.#control(configDir, 'login', value);
+        return this.status(configDir);
     }
-    /** Replaces the installed app with `source` (verified first), stopping it while it is swapped. */
-    async #install(source, current) {
+    /**
+     * Replaces the installed app with `source` (verified first), stopping it while it is swapped: the app running from
+     * the bundle and the one running for `configDir` from elsewhere, so no older app stays behind.
+     */
+    async #install(source, current, configDir) {
         // Verify the source before stopping or replacing any existing app.
         await this.#run('/usr/bin/codesign', ['--verify', '--deep', '--strict', source]);
         mkdirSync(dirname(this.app), { recursive: true });
@@ -206,7 +215,7 @@ export class MenubarManager {
         try {
             cpSync(source, staged, { recursive: true, dereference: false });
             if (current.running)
-                await this.stop();
+                await this.stop(configDir);
             if (current.installed)
                 renameSync(this.app, backup);
             makeExecutable(staged);
@@ -235,17 +244,19 @@ export class MenubarManager {
     async start(configDir, apiUrl) {
         this.#requireMac();
         const source = this.#packageApp(), sourceVersion = await this.#version(source);
-        const current = await this.status();
+        const current = await this.status(configDir);
         if (!current.installed || compareAppVersions(current.version, sourceVersion) < 0)
-            await this.#install(source, current);
+            await this.#install(source, current, configDir);
         await this.#stripQuarantine();
-        if (!(await this.status()).running) {
+        if (!(await this.status(configDir)).running) {
             mkdirSync(configDir, { recursive: true, mode: 0o700 });
             const log = join(configDir, 'menubar.log');
-            await this.#run('/usr/bin/open', ['-g', this.app, '--env', `SHARDFLUX_CONFIG_DIR=${configDir}`, '--env', `SHARDFLUX_API_URL=${apiUrl}`, '--stdout', log, '--stderr', log]);
+            // A start that races another one for this config directory hands over to it without opening the launcher.
+            await this.#run('/usr/bin/open', ['-g', this.app, '--env', `SHARDFLUX_CONFIG_DIR=${configDir}`, '--env', `SHARDFLUX_API_URL=${apiUrl}`,
+                '--env', 'SHARDFLUX_MENUBAR_LAUNCH=background', '--stdout', log, '--stderr', log]);
         }
         for (let i = 0; i < 20; i++) {
-            const status = await this.status();
+            const status = await this.status(configDir);
             if (status.running)
                 return status;
             await new Promise(resolve => setTimeout(resolve, 100));
@@ -260,7 +271,7 @@ export class MenubarManager {
      */
     async refresh(configDir, apiUrl) {
         this.#requireMac();
-        const current = await this.status();
+        const current = await this.status(configDir);
         if (!current.installed || !current.version)
             return { result: 'not_installed', from: null, to: null };
         const to = await this.packagedVersion(), from = current.version;
@@ -274,7 +285,7 @@ export class MenubarManager {
             await this.start(configDir, apiUrl);
             return { result: 'restarted', from, to };
         }
-        await this.#install(this.#packageApp(), current);
+        await this.#install(this.#packageApp(), current, configDir);
         await this.#stripQuarantine();
         return { result: 'installed', from, to };
     }
@@ -301,7 +312,7 @@ export async function ensureMenubar(dir, apiUrl, manager = new MenubarManager(),
     if (store.read().menubar_stopped === true)
         return undefined;
     try {
-        const status = await manager.status();
+        const status = await manager.status(dir);
         // A running app is brought up to the one this CLI carries (after `npm i -g shardflux`) by the background refresh
         // every command starts (refreshMenubarInBackground), at a moment when it shows no window.
         if (status.running)
@@ -310,7 +321,7 @@ export async function ensureMenubar(dir, apiUrl, manager = new MenubarManager(),
         if (!started.running)
             return undefined;
         if (started.login !== 'on')
-            await manager.login('on').catch(() => undefined);
+            await manager.login('on', dir).catch(() => undefined);
         return 'Menu bar started · shard menubar stop to turn it off';
     }
     catch {
@@ -468,7 +479,7 @@ export const MENUBAR_HANDLERS = Object.fromEntries(['start', 'stop', 'status'].m
         if (values.login !== undefined && !['on', 'off'].includes(String(values.login)))
             throw new UsageError('--login must be on or off.');
         const manager = new MenubarManager({ home: ctx.io.env.HOME || homedir(), signal: ctx.signal });
-        let status = action === 'start' ? await manager.start(ctx.store.dir, ctx.apiUrl) : action === 'stop' ? await manager.stop() : await manager.status();
+        let status = action === 'start' ? await manager.start(ctx.store.dir, ctx.apiUrl) : action === 'stop' ? await manager.stop(ctx.store.dir) : await manager.status(ctx.store.dir);
         // An explicit stop keeps `shard` from starting the menu bar again; an explicit start re-enables it.
         if (action !== 'status')
             new AgentStateStore(ctx.store.dir).update(doc => { if (action === 'stop')
@@ -476,9 +487,10 @@ export const MENUBAR_HANDLERS = Object.fromEntries(['start', 'stop', 'status'].m
             else
                 delete doc.menubar_stopped; });
         if (values.login === 'on' || values.login === 'off')
-            status = await manager.login(values.login);
+            status = await manager.login(values.login, ctx.store.dir);
         ctx.io.stdout.write(ctx.json ? json(status) : `Menu bar: ${status.running ? 'running' : 'stopped'}${status.installed ? ` · app ${status.version}` : ' · not installed'} · login ${status.login}\n`);
         return 0;
     };
     return [`menubar ${action}`, handler];
 }));
+MENUBAR_HANDLERS['menubar account'] = async (ctx) => { ctx.io.stdout.write(json(await desktopAccount(ctx))); return 0; };

package/dist/move-worktrees.d.ts

@@ -27,26 +27,32 @@ export interface WorktreeMigration {
     bytes: number;
     files: number;
     referenced: string[];
+    /** Registrations Git reports as prunable (their folder or its .git is gone): nothing to copy, never a refusal. */
+    stale: string[];
 }
+/**
+ * Other registered worktrees of this repository that the session's transcript works in. A normal move leaves them on
+ * this computer; the CLI says so. Best effort: an empty list when Git cannot answer.
+ */
+export declare function referencedWorktrees(folder: string, transcript: Buffer, signal?: AbortSignal): Promise<string[]>;
 /** Git is the source of membership; sibling folders and symlink targets never expand the upload scope. */
 export declare function inspectWorktreeMigration(folder: string, transcript: Buffer, signal?: AbortSignal): Promise<WorktreeMigration | null>;
 /** Size/hash pass only after preserve-all is selected (ignored caches may be large). */
 export declare function captureWorktreeMigration(plan: WorktreeMigration, signal?: AbortSignal): Promise<void>;
 export declare function migrationScope(plan: WorktreeMigration): {
+    local_refs: string[];
+    bytes: number;
+    files: number;
+    scope: string;
+    size_basis: string;
+    stale_registrations?: string[] | undefined;
     worktrees: {
         path: string;
         branch: string;
         target: string;
     }[];
     referenced: string[];
-    local_refs: string[];
-    bytes: number;
-    files: number;
-    scope: string;
-    size_basis: string;
 };
-/** User refs a normal move leaves behind. Shardflux's own refs/shard/* (twin snapshots, land and agent refs) are rebuilt, never user work. */
-export declare function omittedLocalRefs(plan: WorktreeMigration): string[];
 /** Longest paths first, before replacing a parent. Message text and signed thinking keep the existing rewrite contract. */
 export declare function rewriteWorktreeTranscript(bytes: Buffer, plan: WorktreeMigration, root: string): Buffer;
 export interface MigrationResult {

package/dist/move-worktrees.js

@@ -9,6 +9,60 @@ import { projectGit } from "./project-sync-manifest.js";
 import { UsageError } from "./errors.js";
 import { rewriteSessionPaths } from "./local-sessions.js";
 const inside = (root, path) => path === root || path.startsWith(`${root}/`);
+/** `git worktree list --porcelain -z`: each registration's path and whether Git calls it prunable. */
+async function registeredWorktrees(folder, signal) {
+    const out = [];
+    for (const field of (await git(folder, ['worktree', 'list', '--porcelain', '-z'], signal)).split('\0')) {
+        if (field.startsWith('worktree '))
+            out.push({ path: field.slice(9), prunable: false });
+        else if ((field === 'prunable' || field.startsWith('prunable ')) && out.length)
+            out.at(-1).prunable = true;
+    }
+    return out;
+}
+/**
+ * Whether the transcript names `path` itself (or a file below it), not just a longer registered worktree path that
+ * starts with it (the main checkout is a prefix of every worktree nested inside it). JSON-escaped spellings count.
+ */
+function names(text, path, registered) {
+    const longer = registered.filter(p => p.length > path.length && p.startsWith(path));
+    for (const spelled of new Set([path, JSON.stringify(path).slice(1, -1)])) {
+        for (let at = text.indexOf(spelled); at >= 0; at = text.indexOf(spelled, at + 1)) {
+            const next = text[at + spelled.length];
+            if (next !== undefined && /[\w.-]/.test(next))
+                continue; // a sibling folder: /repo-old for /repo
+            if (longer.some(p => text.startsWith(p, at) || text.startsWith(JSON.stringify(p).slice(1, -1), at)))
+                continue;
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Other registered worktrees of this repository that the session's transcript works in. A normal move leaves them on
+ * this computer; the CLI says so. Best effort: an empty list when Git cannot answer.
+ */
+export async function referencedWorktrees(folder, transcript, signal) {
+    try {
+        const selected = await realpath(folder), text = transcript.toString('utf8');
+        const live = (await registeredWorktrees(folder, signal)).filter(w => !w.prunable).map(w => w.path);
+        const all = [...new Set([...live, selected])];
+        const others = [];
+        for (const path of live) {
+            const real = await realpath(path).catch(() => '');
+            if (!real || real === selected)
+                continue;
+            if (names(text, path, all) || (real !== path && names(text, real, all)))
+                others.push(real);
+        }
+        return others;
+    }
+    catch (e) {
+        if (signal?.aborted)
+            throw e;
+        return [];
+    }
+}
 const git = (folder, args, signal) => projectGit(folder, args, signal);
 const hash = async (file, signal) => {
     const sha = createHash('sha256');
@@ -47,15 +101,17 @@ export async function inspectWorktreeMigration(folder, transcript, signal) {
     if (await readFile(alternates, 'utf8').then(s => !!s.trim(), (e) => { if (e.code !== 'ENOENT')
         throw e; return false; }))
         throw new UsageError('This repository borrows an external Git object store. Make it self-contained before preserving all worktrees.');
-    const registered = (await git(folder, ['worktree', 'list', '--porcelain', '-z'], signal)).split('\0').filter(v => v.startsWith('worktree ')).map(v => v.slice(9));
-    const sources = [];
-    for (const path of registered) {
-        try {
-            sources.push(await realpath(path));
-        }
-        catch {
-            throw new UsageError(`Registered worktree is missing: ${path}. Recover it or explicitly remove its stale Git registration before moving all worktrees.`);
+    // A registration whose folder (or its .git) is gone has nothing to copy: Git itself calls it prunable. It is
+    // reported, never a reason to refuse; its branch is a local ref and moves with the others.
+    const registered = [], sources = [], stale = [];
+    for (const w of await registeredWorktrees(folder, signal)) {
+        const real = w.prunable ? '' : await realpath(w.path).catch(() => '');
+        if (!real) {
+            stale.push(w.path);
+            continue;
         }
+        registered.push(w.path);
+        sources.push(real);
     }
     if (!sources.includes(folder) || !sources.includes(main))
         throw new UsageError('Git did not list the selected and main worktrees.');
@@ -73,9 +129,9 @@ export async function inspectWorktreeMigration(folder, transcript, signal) {
             status: await git(source, ['status', '--porcelain=v1', '-z', '--untracked-files=all'], signal), files: [],
             exclude: sources.filter(p => p !== source && inside(source, p)).map(p => relative(source, p)) });
     }
-    const text = transcript.toString('utf8');
-    const referenced = trees.filter(t => t.source !== folder && t.spellings.some(p => text.includes(p) || text.includes(JSON.stringify(p).slice(1, -1)))).map(t => t.source);
-    return { version: 1, selected: folder, commonDir, main, trees, referenced,
+    const text = transcript.toString('utf8'), all = trees.flatMap(t => t.spellings);
+    const referenced = trees.filter(t => t.source !== folder && t.spellings.some(p => names(text, p, all))).map(t => t.source);
+    return { version: 1, selected: folder, commonDir, main, trees, referenced, stale,
         refs: await git(folder, ['for-each-ref', '--format=%(objectname) %(refname)'], signal), bytes: 0, files: 0 };
 }
 /** Size/hash pass only after preserve-all is selected (ignored caches may be large). */
@@ -111,16 +167,11 @@ export async function captureWorktreeMigration(plan, signal) {
 }
 export function migrationScope(plan) {
     return { worktrees: plan.trees.map(t => ({ path: t.source, branch: t.branch || '(detached)', target: t.target })), referenced: plan.referenced,
+        ...(plan.stale.length ? { stale_registrations: plan.stale } : {}),
         local_refs: plan.refs.trim().split('\n').filter(Boolean).map(line => line.slice(line.indexOf(' ') + 1)),
         bytes: plan.bytes, files: plan.files, scope: 'All files, including ignored files and Git metadata, inside these registered worktrees. Symlink targets and unrelated sibling folders are not uploaded.',
         size_basis: 'File bytes before tar headers; archive bytes and free-space requirement are larger. Ignored dependency/build caches are included.' };
 }
-/** User refs a normal move leaves behind. Shardflux's own refs/shard/* (twin snapshots, land and agent refs) are rebuilt, never user work. */
-export function omittedLocalRefs(plan) {
-    const selected = plan.trees.find(t => t.source === plan.selected);
-    return plan.refs.trim().split('\n').filter(Boolean).map(line => line.slice(line.indexOf(' ') + 1))
-        .filter(ref => ref !== selected.branch && !ref.startsWith('refs/remotes/') && !ref.startsWith('refs/shard/'));
-}
 /** Longest paths first, before replacing a parent. Message text and signed thinking keep the existing rewrite contract. */
 export function rewriteWorktreeTranscript(bytes, plan, root) {
     const mappings = plan.trees.flatMap(tree => tree.spellings.map(from => ({ from, to: tree.target === '.' ? root : `${root}/${tree.target}` })));

package/dist/move.js

@@ -33,7 +33,7 @@ import { openUrl } from "./browser.js";
 import { SYNC_CHUNK_BYTES } from "./project-sync-transfer.js";
 import { completeRecords, continuedAfter, findLocalSession, homeRelativeTranscript, listLocalSessions, readTranscript, recordCwd, rewriteSessionPaths, sessionState } from "./local-sessions.js";
 import { installDivergenceNotice, movedKey, movedSession, movedSessions, rememberMoved } from "./moved-sessions.js";
-import { captureWorktreeMigration, inspectWorktreeMigration, migrationScope, omittedLocalRefs, preserveWorktreeMigration, rewriteWorktreeTranscript } from "./move-worktrees.js";
+import { captureWorktreeMigration, inspectWorktreeMigration, migrationScope, preserveWorktreeMigration, referencedWorktrees, rewriteWorktreeTranscript } from "./move-worktrees.js";
 const VM_HOME = '/home/user';
 const SPACE = '/shardflux/project';
 /** A transcript above this moves with the repository's history bound. */
@@ -196,13 +196,6 @@ async function alreadyMoved(ctx, m) {
         throw e;
     }
 }
-function requireExplicitWorktreeScope(plan, values, sessionId) {
-    if (!plan || values['preserve-all-worktrees'] === true || values['this-worktree-only'] === true)
-        return;
-    const omitted = omittedLocalRefs(plan);
-    if (plan.trees.length > 1 || omitted.length)
-        throw new UsageError(`This repository has ${plan.trees.length} registered worktrees and ${omitted.length} other local refs${plan.referenced.length ? `; the session references ${plan.referenced.length} other worktrees` : ''}. Normal migration omits those refs and other worktree files. Inspect paths and bytes with shard move --session ${sessionId} --plan, then choose --preserve-all-worktrees or explicitly --this-worktree-only.`);
-}
 export async function moveSession(ctx, values) {
     const env = { ...process.env, ...ctx.io.env };
     const here = projectRoot(typeof values.path === 'string' ? values.path : process.cwd());
@@ -216,28 +209,27 @@ export async function moveSession(ctx, values) {
             return 0;
         }
     }
+    // A normal move continues the session from this checkout, uncommitted edits included; the repository's other
+    // worktrees and local branches stay on this computer, untouched (as `this-worktree-only` says explicitly).
+    // --preserve-all-worktrees copies them too.
+    const preserveAll = values['preserve-all-worktrees'] === true;
+    if (preserveAll && values['this-worktree-only'] === true)
+        throw new UsageError('Choose --preserve-all-worktrees or --this-worktree-only.');
     if (values.plan !== true) {
-        // A local MCP caller is still in its turn. Report the required scope choice
-        // before waiting, so it can answer while it still runs on this computer.
-        if (values['preserve-all-worktrees'] !== true && values['this-worktree-only'] !== true) {
-            const current = completeRecords(readTranscript(s.file));
-            confirmedCwds(s, current, folder);
-            requireExplicitWorktreeScope(await inspectWorktreeMigration(folder, current, ctx.signal), values, s.session_id);
-        }
+        // A local MCP caller is still in its turn: an unrelated folder is refused while it can still answer.
+        if (!preserveAll)
+            confirmedCwds(s, completeRecords(readTranscript(s.file)), folder);
         await waitForTurnEnd(ctx, s, env);
     }
     const bytes = completeRecords(readTranscript(s.file));
     if (bytes.length > TRANSCRIPT_LIMIT)
         throw new UsageError('This session’s transcript is above the 256 MiB move bound.');
-    if (values['preserve-all-worktrees'] && values['this-worktree-only'])
-        throw new UsageError('Choose --preserve-all-worktrees or --this-worktree-only.');
-    const plan = values['this-worktree-only'] === true && values.plan !== true ? null : await inspectWorktreeMigration(folder, bytes, ctx.signal);
+    const plan = preserveAll || values.plan === true ? await inspectWorktreeMigration(folder, bytes, ctx.signal) : null;
     // Refuse before syncing credentials, creating a VM or snapshotting an unrelated
     // folder. An explicit all-worktree scope also accepts record-confirmed linked owners.
-    confirmedCwds(s, bytes, folder, values['preserve-all-worktrees'] === true || values.plan === true ? plan ?? undefined : undefined);
-    if (values.plan === true || values['preserve-all-worktrees'] === true) {
-        if (!plan)
-            throw new UsageError('Preserve-all-worktrees requires a Git repository.');
+    confirmedCwds(s, bytes, folder, plan ?? undefined);
+    let elsewhere = [];
+    if (plan) {
         await captureWorktreeMigration(plan, ctx.signal);
         const scope = migrationScope(plan);
         if (values.plan === true) {
@@ -246,8 +238,11 @@ export async function moveSession(ctx, values) {
         }
         ctx.io.stderr.write(`Preserving ${plan.trees.length} registered worktrees, ${plan.files} files, ${plan.bytes} file bytes (archives add headers). Includes ignored files and Git metadata:\n${plan.trees.map(t => `  ${t.source}`).join('\n')}\nSymlink targets and unrelated sibling folders are not uploaded.\n`);
     }
-    else
-        requireExplicitWorktreeScope(plan, values, s.session_id);
+    else if (values['this-worktree-only'] !== true) {
+        elsewhere = await referencedWorktrees(folder, bytes, ctx.signal);
+        if (elsewhere.length && !ctx.json)
+            ctx.io.stderr.write(`This session also worked in ${elsewhere.length === 1 ? 'another worktree' : `${elsewhere.length} other worktrees`} of this repository (${elsewhere.join(', ')}); ${elsewhere.length === 1 ? 'it stays' : 'they stay'} on this computer. shard move --preserve-all-worktrees copies every worktree.\n`);
+    }
     const sha256 = createHash('sha256').update(bytes).digest('hex');
     if (!ctx.json)
         ctx.io.stderr.write(`Moving ${s.harness === 'claude' ? 'Claude Code' : 'Codex'} session “${s.title}” to the cloud…\n`);
@@ -298,7 +293,7 @@ export async function moveSession(ctx, values) {
     if (!attach) {
         const quiet = { ...ctx, io: { ...ctx.io, stdout: { write: () => true } } };
         await conversationTerminal(quiet, ws, c, place, { ...values, detach: true });
-        out(ctx, `Moved to the cloud as ${c.key}: the same session, with its history. Open it: shard agents open ${c.key}\n`, { moved, conversation: c, workspace: ws.data, ...(placed ? { transcript: placed } : {}), ...(preserved ? { preserved } : {}) });
+        out(ctx, `Moved to the cloud as ${c.key}: the same session, with its history. Open it: shard agents open ${c.key}\n`, { moved, conversation: c, workspace: ws.data, ...(placed ? { transcript: placed } : {}), ...(preserved ? { preserved } : {}), ...(elsewhere.length ? { other_worktrees: elsewhere } : {}) });
         return 0;
     }
     const where = openInChoices(ctx, project.slug)[s.harness];

package/dist/onboarding.js

@@ -301,8 +301,10 @@ export async function onboardingReport(ctx, values, platform = process.platform)
     const claude = { id: 'claude', picked: apps.includes('claude'), found: found.includes('claude'),
         ...(!connected ? signIn : credentialError !== undefined ? failure(credentialError) : claudeConnection(credentials.find(row => row.app === 'claude'))) };
     const codex = { id: 'codex', picked: apps.includes('codex'), found: found.includes('codex'),
-        ...(!connected ? signIn : (credentialError ?? codexError) !== undefined ? failure(credentialError ?? codexError)
-            : codexConnection(localCodex, credentials.some(row => row.app === 'codex'), connector, health)) };
+        ...(!connected ? signIn : codexError instanceof ShardfluxApiError && codexError.reason === 'codex_chatgpt_login_required'
+            ? { state: 'action', fact: codexError.message, action: { title: 'Sign in with ChatGPT', command: ['codex', 'login'] } }
+            : (credentialError ?? codexError) !== undefined ? failure(credentialError ?? codexError)
+                : codexConnection(localCodex, credentials.some(row => row.app === 'codex'), connector, health)) };
     const t3 = await t3Connection(ctx, connected || ctx.sessionSource() !== null, undefined, undefined, values['t3-connect'] === true, values);
     const connections = [account, claude, codex, ...(t3 ? [t3] : [])];
     // The cloud machine (0.20.2+), the same row `shard machine setup --status` reports: whether what is installed carries

package/dist/prepared-repository.d.ts

@@ -172,6 +172,8 @@ export interface PreparedApplyOptions {
     };
     /** The VM's workspace: a checkout another VM's conversation made (and a template image brought) is taken over. */
     workspace?: string;
+    /** Media already sent land before the reply, not after it (a client that compares the worktree's files at once). */
+    landNow?: boolean;
 }
 /** Where and how a revision is checked out: the VM half's apply request. */
 export interface PreparedApplyTarget {

package/dist/prepared-repository.js

@@ -785,7 +785,7 @@ const applyRequest = ({ root, branch, options = {} }) => ({ root, branch, ...opt
     ...(options.background === false ? { background: false } : {}), ...(options.releasePin ? { release_pin: options.releasePin } : {}),
     ...(options.after ? { after: options.after } : {}),
     ...(options.setupIntent ? { setup_intent: { conversation: options.setupIntent.conversation, deps_hash: options.setupIntent.depsHash } } : {}),
-    ...(options.workspace ? { workspace: options.workspace } : {}) });
+    ...(options.workspace ? { workspace: options.workspace } : {}), ...(options.landNow ? { land_now: true } : {}) });
 /**
  * Checks out the revision as `branch` at `root`, in one exec. Media not in the cache yet stay pending
  * (landDeferredFiles). A root holding the same revision is left as it is; one holding another is refused, unless it is

package/dist/prepared-repository.py

@@ -998,8 +998,9 @@ def apply_locked(cache, req, revision, root, branch, m=None, extras_tar=None, pr
     except BaseException:
         discard(work, root)
         raise
-    # Media are files Git ignores: the agent can start before they are written. They land right after the reply.
-    land_now(cache, root, [], sync=not req.get("background", True))
+    # Media are files Git ignores: the agent can start before they are written. They land right after the reply, or
+    # before it for a client that compares the worktree's files at once (an editor's file sync).
+    land_now(cache, root, [], sync=not req.get("background", True) or req.get("land_now") is True)
     if req.get("after"):
         AFTER.append(lambda: run_after(root, req["after"]))
     if req.get("background", True):

package/dist/project-preparation.d.ts

@@ -1,5 +1,6 @@
 import type { Ctx, Handler } from './commands.js';
 import type { PreparedTransfer } from './prepared-repository.js';
+import { CodedError } from './errors.js';
 export interface SelectedProject {
     api_url: string;
     folder: string;
@@ -24,6 +25,19 @@ export interface SelectedProject {
     /** Preparation VMs this revision's attempts deleted: the next open is a new one, never the deleted one again. */
     attempt?: number;
 }
+/** The guest's setup state (`sf-agent template --json`): its steps, each failed one with the guest's error. */
+export interface SetupStatus {
+    state?: string;
+    tasks?: {
+        name: string;
+        state: string;
+        error?: {
+            code?: string;
+            message: string;
+        };
+    }[];
+}
+export declare function setupFailure(status: SetupStatus): CodedError;
 /** New content past this, or a dependency change, makes a quiet project worth preparing again. */
 export declare const PREPARE_AGAIN_BYTES: number;
 /** Quiet this long after the last edit before preparing again. */

package/dist/project-preparation.js

@@ -23,10 +23,22 @@ import { projectGit } from "./project-sync-manifest.js";
 import { inspectWorktree, pauseReason, twinSeed, worktreeId } from "./worktree-twin.js";
 import { applyPreparedSnapshot, capturePreparedSnapshot, preparedCachePath, preparedGitConfig, pruneLocalPrepared, prunePreparedCache, releaseLocalSnapshot, transferPreparedSnapshot } from "./prepared-repository.js";
 import { withTargetLock } from "./target-lock.js";
-import { UsageError } from "./errors.js";
+import { CodedError, UsageError } from "./errors.js";
 import { dependencyHash } from "./project-template-setup.js";
-/** A setup that ran and failed: the same files fail again, so it waits for a change instead of a timer. */
-class SetupFailed extends Error {
+/**
+ * A setup that ran and failed: the same files fail again, so it waits for a change instead of a timer. Reported as
+ * `project_setup_failed` with the failed step and its own message (0.23.0+; before, `internal_error`).
+ */
+class SetupFailed extends CodedError {
+}
+export function setupFailure(status) {
+    const step = status.tasks?.find(t => t.state === 'failed');
+    const message = step ? `Project setup failed at ${step.name}: ${step.error?.message ?? 'the step failed'}` : 'Project setup failed.';
+    // A step setup could not work out (a missing lockfile) or a command that failed; the repository's own command for the
+    // step is the other way forward.
+    const first = step?.error?.code === 'setup_detection_unresolved' ? 'commit what the message names' : 'fix the cause in the repository and commit';
+    const fix = `${first}${step ? `, or set run for ${step.name} under steps in .shardflux/setup.yaml` : ''}; the project is prepared again after the change`;
+    return new SetupFailed('project_setup_failed', message, fix, step ? { step: step.name, ...(step.error?.code ? { error_code: step.error.code } : {}) } : undefined);
 }
 /** New content past this, or a dependency change, makes a quiet project worth preparing again. */
 export const PREPARE_AGAIN_BYTES = 8 << 20;
@@ -147,7 +159,7 @@ export async function prepareSelectedProject(ctx, selected) {
                         throw new Error(`Project setup status failed: ${status.stderr.trim()}`);
                     const state = JSON.parse(status.stdout);
                     if (state.state === 'failed')
-                        throw new SetupFailed(state.tasks?.find(t => t.state === 'failed')?.error?.message ?? 'Project setup failed.');
+                        throw setupFailure(state);
                     if (Date.now() > deadline)
                         throw new Error('The project template is still being saved; the next preparation picks it up.');
                     await delay(5000, undefined, { signal: ctx.signal });

package/dist/project-sync.d.ts

@@ -38,6 +38,7 @@ export declare function projectReconciler(options: {
     signal?: AbortSignal;
     vmBaseline?: boolean;
     cache?: LocalHashCache;
+    inFlight?: () => Iterable<string>;
 }): (() => Promise<void>) & {
     settled(): boolean;
 };
@@ -51,6 +52,8 @@ export interface ProjectSyncOptions {
     vmBaseline?: boolean;
     /** This computer's file hashes, filled ahead of the first reconcile (localManifest with the same map, 0.21.1+). */
     cache?: LocalHashCache;
+    /** Paths another transfer is still bringing to the VM (a prepared start's large media, 0.22.0+): left alone until then. */
+    inFlight?: () => Iterable<string>;
 }
 /** Editors reconcile between turns without a watcher keeping an idle VM active. */
 export declare function projectSyncBoundary(ctx: Ctx, ws: Workspace, project: ReturnType<typeof projectIdentity>, options?: ProjectSyncOptions): Promise<ProjectSyncBoundary>;

package/dist/project-sync.js

@@ -36,6 +36,9 @@ export function projectReconciler(options) {
                 report(`Project sync skipped ${side} ${skip.path}: ${skip.reason}`);
             }
         }
+        // Files another transfer is still bringing to the VM: this pass leaves them alone (a later one sees them landed).
+        for (const path of options.inFlight?.() ?? [])
+            blocked.add(path);
         // Until a pass completes, a VM that has run nothing since this checkout seeded it holds the baseline of every file
         // both sides have: an edit made here before the first pass is this computer's change, not a conflict (0.21.1+).
         let common = state.common;
@@ -144,7 +147,7 @@ export async function projectSyncBoundary(ctx, ws, project, options = {}) {
     };
     const report = (message) => { ctx.io.stderr.write(`${message}\n`); };
     const reconcile = projectReconciler({ folder: project.folder, root, agent: options.agent ?? ws.labels.agent ?? 'main', cell, state, save, report, signal: ctx.signal,
-        vmBaseline: options.vmBaseline === true && !stored, ...(options.cache ? { cache: options.cache } : {}) });
+        vmBaseline: options.vmBaseline === true && !stored, ...(options.cache ? { cache: options.cache } : {}), ...(options.inFlight ? { inFlight: options.inFlight } : {}) });
     return { root, conflicts: () => state.conflicts.slice(), reconcile, settled: () => reconcile.settled() };
 }
 export async function startProjectSync(ctx, ws, project, options = {}) {

package/dist/t3-launch.d.ts

@@ -32,6 +32,7 @@ export declare function launchT3(ctx: Ctx, values: Values, path: string, explici
 export declare function t3Fields(ws: Workspace, project: string, install: T3Install | undefined, started: T3ThreadResult | undefined, conversation?: string | null): Record<string, unknown>;
 /**
  * `agents open t3 <conversation>` for a conversation that runs on T3's Shardflux provider (ACP mode): T3 is brought to
- * the front with that thread's id. A conversation of another route opens its VM as T3's SSH environment.
+ * the front with that thread's id. A Codex Cloud conversation opens its Codex chat; a conversation of another route
+ * opens its VM as T3's SSH environment.
  */
 export declare function openT3Conversation(ctx: Ctx, conversationId: string, values?: Values): Promise<number>;

package/dist/t3-launch.js

@@ -99,13 +99,22 @@ export function t3Fields(ws, project, install, started, conversation) {
 }
 /**
  * `agents open t3 <conversation>` for a conversation that runs on T3's Shardflux provider (ACP mode): T3 is brought to
- * the front with that thread's id. A conversation of another route opens its VM as T3's SSH environment.
+ * the front with that thread's id. A Codex Cloud conversation opens its Codex chat; a conversation of another route
+ * opens its VM as T3's SSH environment.
  */
 export async function openT3Conversation(ctx, conversationId, values = {}) {
+    const conversation = await getConversation(ctx, conversationId);
+    // A Codex Cloud conversation's chat is its Codex thread, which T3 Code cannot show: its existing history opens (as
+    // `agents open` does), without waking the VM, linking it to T3 or starting another conversation (0.23.0+).
+    if (conversation.route === 'codex-cloud') {
+        if (!ctx.json)
+            ctx.io.stderr.write('Codex Cloud runs this conversation, so its chat is in Codex, not T3 Code.\n');
+        const { openCodexConversation } = await import("./codex-cloud.js");
+        return openCodexConversation(ctx, conversation);
+    }
     const install = t3Install(ctx.io.env);
     if (!install)
         throw t3NotInstalled();
-    const conversation = await getConversation(ctx, conversationId);
     if (install.mode === 'acp' && conversation.route === 'acp') {
         let threadId;
         try {