@shardflux/cli 0.22.0 → 0.23.0

package/dist/command-center-actions.js

@@ -60,8 +60,14 @@ export const CENTER_HANDLERS = {
         }
         if (values.review === true)
             throw new UsageError('--review needs --on <conversation>.');
-        if ((values.prompt !== undefined || values['prompt-file'] !== undefined || values.image !== undefined) && (ref || values.name !== undefined || values.like !== undefined || values.in !== undefined)) {
-            throw new UsageError('An initial prompt needs a new conversation: use agents new --path <folder> --app claude|codex.');
+        if (values.prompt !== undefined || values['prompt-file'] !== undefined || values.image !== undefined) {
+            // --in terminal is where a new conversation opens anyway: it starts one with its first message (0.23.0+). Codex
+            // opens in Codex Cloud, which says so.
+            if (fresh && values.in === 'terminal')
+                return launchConversationProject(ctx, values, [str(values.path) ?? './', ...(str(values.app) ? [str(values.app)] : [])]);
+            const other = ref ? `the agent argument ${ref}` : values.name !== undefined ? '--name' : values.like !== undefined ? '--like' : values.in !== undefined ? `--in ${str(values.in)}` : undefined;
+            if (other)
+                throw new UsageError(`--prompt, --prompt-file and --image are for a new conversation and cannot be combined with ${other}: omit it.`, 'start one with shard agents new --path <folder> --app claude|codex --prompt "<task>"; --in auto opens it where agents targets --open-in says');
         }
         if (!ref && values.name === undefined && values.like === undefined && values.in === undefined) {
             return launchConversationProject(ctx, values, [str(values.path) ?? './', ...(str(values.app) ? [str(values.app)] : [])]);
@@ -145,8 +151,11 @@ export const CENTER_HANDLERS = {
             if (ws.labels.shard_conversation && CONVERSATION_ID.test(ws.labels.shard_conversation))
                 conversation = await getConversation(ctx, ws.labels.shard_conversation);
         }
-        if (conversation?.route === 'codex-cloud')
-            throw new UsageError(`Codex Cloud runs this conversation; follow it with shard agents open ${conversation.id}.`);
+        // Codex Cloud holds the conversation's output in its Codex thread; no terminal in the VM shows it (0.23.0+: the
+        // refusal names the commands that do).
+        if (conversation?.route === 'codex-cloud') {
+            throw new UsageError(`Codex Cloud runs this conversation, so its output is in its Codex thread, not a terminal: open the thread with shard agents open ${conversation.id}; shard c wait ${conversation.id} waits for its reply and shard c get ${conversation.id} shows it.`);
+        }
         if (conversation?.route === 'acp')
             throw new UsageError('This conversation runs through its ACP client, which shows its output; it has no terminal to follow.');
         if (conversation && values.app !== undefined && values.app !== conversation.harness)

package/dist/command-center-model.d.ts

@@ -24,6 +24,8 @@ export interface CenterRow {
 /** Older K5 captures used the workspace key as the agent label. K1 needs its leaf name. */
 export declare const agentName: (key: string, labels: Record<string, string>) => string;
 export declare const projectName: (key: string, labels: Record<string, string>) => string;
+/** What `shard agents open` gets for a row: a Cloud thread's conversation id, else the VM's key. */
+export declare const openReference: (row: Pick<CenterRow, "key" | "agent">) => string;
 export declare function loadCenter(ctx: Ctx): Promise<CenterData>;
 export declare function scopedProject(data: CenterData, scope: ProjectScope): string;
 export declare function centerRows(data: CenterData, scope?: ProjectScope, filter?: string): CenterRow[];

package/dist/command-center-model.js

@@ -6,6 +6,11 @@ import { readSetupProgress } from "./assisted-setup.js";
 export const agentName = (key, labels) => (labels.agent || key).split('/').at(-1);
 export const projectName = (key, labels) => labels.shard_project || key.split('/')[0];
 const parked = (workspace) => ['suspended', 'hibernated', 'parked'].includes(workspace?.observed_state ?? '');
+/** A Codex Cloud thread (API rows labeled shard_route=codex-cloud, 0.23.0+): it runs in Codex, so its VM being parked
+ * says nothing about it, and it opens by its conversation id, in Codex, without waking that VM. */
+const cloudThread = (agent) => agent?.labels.shard_route === 'codex-cloud' && !!agent.conversation_id;
+/** What `shard agents open` gets for a row: a Cloud thread's conversation id, else the VM's key. */
+export const openReference = (row) => cloudThread(row.agent) ? row.agent.conversation_id : row.key;
 export async function loadCenter(ctx) {
     const collect = async (path) => {
         const rows = [], cursors = new Set();
@@ -62,7 +67,7 @@ export function centerRows(data, scope, filter = '') {
         const workspace = workspaces.get(agent.workspace_id);
         if (workspace?.deleted_at)
             continue;
-        const badge = agent.app === 'claude' && agent.credential_status === 'needs_sign_in' ? 'Claude sign-in needed' : agent.state === 'exited' ? 'done' : parked(workspace) ? 'parked' : agent.state === 'waiting' ? 'needs you' : 'working';
+        const badge = agent.app === 'claude' && agent.credential_status === 'needs_sign_in' ? 'Claude sign-in needed' : agent.state === 'exited' ? 'done' : !cloudThread(agent) && parked(workspace) ? 'parked' : agent.state === 'waiting' ? 'needs you' : 'working';
         rows.push({ id: agent.id, key: agent.workspace_key, project: projectName(agent.workspace_key, agent.labels), agent, workspace, badge,
             attention: badge === 'Claude sign-in needed' ? -1 : ['needs you', 'working', 'parked', 'done'].indexOf(badge) });
         withSessions.add(agent.workspace_id);

package/dist/command-center.js

@@ -5,7 +5,7 @@ import { AgentStateStore } from "./agent-state.js";
 import { installedTargets } from "./agent-targets.js";
 import { randomUUID } from 'node:crypto';
 import { agentAction, availableTargets } from "./command-center-actions.js";
-import { centerRows, loadCenter } from "./command-center-model.js";
+import { centerRows, loadCenter, openReference } from "./command-center-model.js";
 import { AnsiRenderer, renderCenter } from "./command-center-renderer.js";
 import { CenterKeys } from "./command-center-keys.js";
 import { ensureMenubar } from "./menubar.js";
@@ -320,13 +320,13 @@ export async function showCenter(ctx, scope, options = {}) {
         const app = row.agent?.app || options.app || new AgentStateStore(ctx.store.dir).app(project, row.workspace?.labels.app === 'codex' ? 'codex' : 'claude');
         if (key === 'enter') {
             const target = new AgentStateStore(ctx.store.dir).target(project, ['terminal', ...installedTargets(ctx.io.env).targets]);
-            await dispatch('open', { app, project, in: target }, [row.key], true);
+            await dispatch('open', { app, project, in: target }, [openReference(row)], true);
         }
         else if (key === 'o') {
             const targets = await availableTargets(ctx);
             menu('Open in…', targets.map(target => ({ label: target, run: async () => {
                     new AgentStateStore(ctx.store.dir).saveTarget(project, target);
-                    await dispatch('open', { app, project, in: target }, [row.key], true);
+                    await dispatch('open', { app, project, in: target }, [openReference(row)], true);
                 } })));
         }
         else if (key === 'N' || key === 'f') {

package/dist/commands.js

@@ -1104,7 +1104,7 @@ export const KEY_HANDLERS = {
             })));
         }
         if (s.state === 'starting' || s.state === 'running') {
-            throw new ExecSessionRunningError(`Exec session ${s.session_id} is still ${s.state}.`, s, `follow it to its end with: shard ws exec-read ${ref} ${s.session_id} --follow`);
+            throw new ExecSessionRunningError(`Exec session ${s.session_id} is still ${s.state}${s.error ? `: ${s.error}` : ''}.`, s, `follow it to its end with: shard ws exec-read ${ref} ${s.session_id} --follow`);
         }
         const result = { exitCode: s.exit_code ?? null, termSignal: s.term_signal ?? null, timedOut: s.timed_out ?? false, canceled: s.canceled ?? false };
         if (!ctx.json && result.exitCode === null && !result.timedOut && !(result.termSignal !== null && result.termSignal > 0)) {
@@ -1121,7 +1121,7 @@ export const KEY_HANDLERS = {
         const s = await cellOf(ctx, ws).exec.cancel(sessionId, graceMs);
         const ended = s.state !== 'starting' && s.state !== 'running';
         const status = !ended ? `${s.state} (cancel sent)` : s.canceled ? `canceled${s.term_signal ? ` (signal ${s.term_signal})` : ''}` : `already ${s.state}${typeof s.exit_code === 'number' ? ` (exit code ${s.exit_code})` : ''}`;
-        out(ctx, `exec session ${s.session_id}: ${status}\n`, s);
+        out(ctx, `exec session ${s.session_id}: ${status}${s.error ? `: ${s.error}` : ''}${!ended || s.error?.startsWith('cancel accepted; execution drain') ? `; follow with: shard ws exec-read ${ref} ${s.session_id} --follow` : ''}\n`, s);
         return 0;
     },
     async 'workspaces exec-input'(ctx, values, [ref, sessionId, data]) {

package/dist/conversation-terminal.js

@@ -1,6 +1,6 @@
 import { linuxTerminalSession } from "./linux-terminal.js";
 import { resolve } from 'node:path';
-import { attachable, openShardInTerminal, reportTerminalOpen } from "./terminal-apps.js";
+import { attachable, handedToTerminal, openShardInTerminal, reportTerminalOpen } from "./terminal-apps.js";
 import { randomUUID } from 'node:crypto';
 import { AgentStateStore } from "./agent-state.js";
 import { projectIdentity, projectLabels } from "./project-identity.js";
@@ -71,7 +71,8 @@ export async function reopenConversation(ctx, c, values) {
  */
 export const launchProjectCommand = async (ctx, values, [path = './', explicit]) => {
     const named = explicit ?? (values.claude === true ? 'claude' : values.codex === true ? 'codex' : undefined);
-    const typing = attachable(ctx.io), here = typing || ctx.json;
+    // A terminal this CLI opened for it runs it there, never in yet another one (0.23.0+).
+    const typing = attachable(ctx.io), here = typing || ctx.json || handedToTerminal(ctx.io.env);
     if (values.resume !== true && values.review !== true) {
         const project = projectIdentity(path);
         const app = named === 'claude' || named === 'codex' ? named : new AgentStateStore(ctx.store.dir).app(project.remote ?? project.folder);

package/dist/conversations.d.ts

@@ -111,6 +111,9 @@ export declare function rememberConversation(ctx: Pick<Ctx, 'store' | 'apiUrl'>,
 export declare function conversationsUnavailable(e: unknown): boolean;
 export declare function getConversation(ctx: Ctx, id: string): Promise<Conversation>;
 export declare function listConversations(ctx: Ctx, projectId?: string): Promise<Conversation[]>;
+/** Resolve an open reference without using the local cwd or waking a VM. A conversation key survives a VM move;
+ * a computer key names its bound conversation. Legacy computers without that binding keep the workspace path. */
+export declare function conversationForOpen(ctx: Ctx, ref: string): Promise<Conversation | undefined>;
 export declare function resolveConversation(ctx: Ctx, ref: string, folder?: string): Promise<Conversation>;
 /** 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>;
@@ -131,6 +134,11 @@ export interface MovedInSession {
  * they pass. The conversation API's availability is read meanwhile too.
  */
 export declare function createConversationRecord(ctx: Ctx, folder: string, harness: Harness, route: Conversation['route'], name?: string, allocated?: (workspace: WorkspaceView) => void, idempotencyKey?: string, choice?: ModelChoice, movedIn?: MovedInSession, ready?: Promise<unknown>): Promise<Conversation>;
+/**
+ * Files of a conversation's prepared start still on their way (large media that follow the first prompt): an editor's
+ * file sync leaves them alone until they land, instead of sending them a second time.
+ */
+export declare function preparedInFlight(ctx: Pick<Ctx, 'store' | 'apiUrl'>, id: string): string[];
 /**
  * Brings the conversation's accepted revision into its VM (0.22.0+): only what the project cache lacks is sent, and
  * with `defer` large incompressible files follow the first prompt. Resumable: a later call (the device helper, or
@@ -142,6 +150,7 @@ export declare function prepareAcceptedConversation(ctx: Ctx, c: Conversation, w
     setup?: Promise<{
         depsHash: string;
     } | undefined>;
+    landNow?: boolean;
 }): Promise<boolean>;
 /**
  * Sends a conversation's deferred large files and lands them in its worktree. Runs while its VM is awake (it never
@@ -157,7 +166,11 @@ export declare function seedConversation(ctx: Ctx, c: Conversation, ws: Workspac
     seedRepository?(ws: Workspace, c: Conversation): Promise<void>;
 }, changes?: Promise<LocalChanges>, setup?: Promise<{
     depsHash: string;
-} | undefined>): Promise<void>;
+} | undefined>, editor?: {
+    initialFiles?: readonly string[];
+    onInitialFiles?: () => void;
+    landNow?: boolean;
+}): Promise<void>;
 export declare function createConversation(ctx: Ctx, folder: string, harness: Harness, route: Conversation['route'], name?: string, choice?: ModelChoice, movedIn?: MovedInSession & {
     beforeSeed(ws: Workspace, c: Conversation): Promise<void>;
     seedRepository?(ws: Workspace, c: Conversation): Promise<void>;

package/dist/conversations.js

@@ -96,6 +96,41 @@ export async function listConversations(ctx, projectId) {
     } while (cursor);
     return all;
 }
+/** Resolve an open reference without using the local cwd or waking a VM. A conversation key survives a VM move;
+ * a computer key names its bound conversation. Legacy computers without that binding keep the workspace path. */
+export async function conversationForOpen(ctx, ref) {
+    if (/^conv_[a-z0-9]{26}$/.test(ref))
+        return getConversation(ctx, ref);
+    if (!ref.includes('/'))
+        return undefined;
+    const ws = await ctx.cloud().workspaces.findByKey(ref, { signal: ctx.signal });
+    if (ws) {
+        const id = ws.labels.shard_conversation;
+        if (!id)
+            return undefined;
+        try {
+            const c = await getConversation(ctx, id);
+            return c.workspace_id === ws.data.id ? c : undefined;
+        }
+        catch (error) {
+            if (conversationsUnavailable(error))
+                return undefined;
+            throw error;
+        }
+    }
+    let matches;
+    try {
+        matches = (await listConversations(ctx)).filter(c => c.key === ref);
+    }
+    catch (error) {
+        if (conversationsUnavailable(error))
+            return undefined;
+        throw error;
+    }
+    if (matches.length > 1)
+        throw new UsageError('Use the conversation id.');
+    return matches[0] ? getConversation(ctx, matches[0].id) : undefined;
+}
 export async function resolveConversation(ctx, ref, folder) {
     if (ref.startsWith('conv_'))
         return getConversation(ctx, ref);
@@ -190,8 +225,8 @@ export async function createConversationRecord(ctx, folder, harness, route, name
     const commit = seed.commit;
     // The prepared revision of that state (0.22.0+): its media and what Git does not hold (.env files, filter output),
     // captured while the VM is requested and boots. A capture that cannot complete falls back to the copy seed, never fails
-    // the start. ACP sessions seed their own way (acp-models.ts).
-    const capture = movedIn || route === 'acp' ? Promise.resolve(undefined) : capturePreparedSnapshot(ctx.store.dir, project.folder, seed, project.remote, ctx.signal).catch((error) => {
+    // the start. Every route but a moved-in session (its own worktrees) starts this way, editors' (ACP) too (0.22.0+).
+    const capture = movedIn ? Promise.resolve(undefined) : capturePreparedSnapshot(ctx.store.dir, project.folder, seed, project.remote, ctx.signal).catch((error) => {
         if (ctx.signal.aborted)
             throw error;
         ctx.io.stderr.write(`Project snapshot: ${error instanceof Error ? error.message : String(error)}; copying the project instead.\n`);
@@ -211,6 +246,7 @@ export async function createConversationRecord(ctx, folder, harness, route, name
     // The seed awaits the capture (prepareAcceptedConversation), so it runs on while the VM boots, with the Git settings
     // the VM repository copies from this one.
     pendingCaptures.set(c.id, capture.then(async (prepared) => {
+        seedPhase('capture_done');
         if (!prepared)
             return undefined;
         new AgentStateStore(ctx.store.dir).update(doc => {
@@ -223,6 +259,14 @@ export async function createConversationRecord(ctx, folder, harness, route, name
     acceptedProgress(c.id, c.key);
     return c;
 }
+/**
+ * Files of a conversation's prepared start still on their way (large media that follow the first prompt): an editor's
+ * file sync leaves them alone until they land, instead of sending them a second time.
+ */
+export function preparedInFlight(ctx, id) {
+    const preparation = localConversations(ctx)[id]?.preparation;
+    return preparation?.state === 'deferred' ? preparation.pending ?? [] : [];
+}
 /** Captures still running for conversations this process created (createConversationRecord). */
 const pendingCaptures = new Map();
 /** A start the copy seed took over: its prepared revision is no longer this conversation's (recorded as the reason). */
@@ -280,7 +324,7 @@ export async function prepareAcceptedConversation(ctx, c, ws, options = {}) {
             const target = { root: c.worktree_path, branch: c.branch, options: { signal: ctx.signal, adopt: true,
                     git: fresh?.git ?? await preparedGitConfig(local.folder, snapshot.manifest, ctx.signal), ...(outside ? { dependencySource: templateCheckout(c) } : {}),
                     after: { script: SEED_SNAPSHOT, args: [c.worktree_path, c.branch.replace(/^shard\//, ''), HUB_PATH, 'background'] },
-                    ...(intent ? { setupIntent: { conversation: c.id, depsHash: intent.depsHash } } : {}), workspace: ws.id } };
+                    ...(intent ? { setupIntent: { conversation: c.id, depsHash: intent.depsHash } } : {}), workspace: ws.id, ...(options.landNow ? { landNow: true } : {}) } };
             let transfer, apply;
             try {
                 // A warm start: the probe checks the revision out in its own exec.
@@ -363,7 +407,7 @@ export async function completeDeferredPreparation(ctx, c) {
  * its prepared revision (0.22.0+), or the copy seed when the start has none or the VM cannot take one. Repeatable: a
  * start resumed after a deadline continues here.
  */
-export async function seedConversation(ctx, c, ws, folder, movedIn, changes, setup) {
+export async function seedConversation(ctx, c, ws, folder, movedIn, changes, setup, editor = {}) {
     // Requests the copy seed starts and nothing waits for (the history backfill's start), settled before this returns.
     const background = [];
     const cell = ws.cell();
@@ -383,9 +427,14 @@ export async function seedConversation(ctx, c, ws, folder, movedIn, changes, set
         void recordIntent();
         await movedIn.seedRepository(ws, c);
     }
-    else if (!await prepareAcceptedConversation(ctx, c, ws, { fallback: true, ...(setup ? { setup } : {}) })) {
+    else if (await prepareAcceptedConversation(ctx, c, ws, { fallback: true, ...(setup ? { setup } : {}), ...(editor.landNow ? { landNow: true } : {}) })) {
+        // A prepared worktree appears whole: an editor's agent settings are there with everything else.
+        editor.onInitialFiles?.();
+    }
+    else {
         await seedAgentRepository(ctx, ws, folder, { root: c.worktree_path, populate: true, changes: changes ?? localChanges(folder, ctx.signal),
-            background: started => background.push(started), beforeHistory: recordIntent() });
+            background: started => background.push(started), beforeHistory: recordIntent(),
+            ...(editor.initialFiles ? { initialFiles: editor.initialFiles } : {}), ...(editor.onInitialFiles ? { onInitialFiles: editor.onInitialFiles } : {}) });
     }
     await recorded;
     seedPhase('seed_done');

package/dist/desktop-linux.js

@@ -1,6 +1,6 @@
 import { spawn, execFile } from 'node:child_process';
 import { createRequire } from 'node:module';
-import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync, chmodSync, mkdtempSync } from 'node:fs';
+import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync, chmodSync, mkdtempSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { homedir } from 'node:os';
 import { promisify } from 'node:util';
@@ -19,6 +19,15 @@ export function linuxDesktopPackage(arch = process.arch) {
 }
 export function graphicalSession(env) { return !!(env.DISPLAY || env.WAYLAND_DISPLAY); }
 const desktopString = (text) => `"${text.replace(/(["`$\\])/g, '\\$1')}"`;
+// fnm's multishell aliases belong to the launching shell; the desktop and its autostart entry outlive it.
+function stableDesktopRuntime(runtime) {
+    try {
+        return { node: realpathSync(runtime.node), script: realpathSync(runtime.script) };
+    }
+    catch {
+        throw new UsageError('Open shard from its installed CLI to start the Shardflux window.');
+    }
+}
 export class LinuxDesktopManager {
     home;
     app;
@@ -117,6 +126,7 @@ export class LinuxDesktopManager {
             throw new UsageError('Install the window with npm i -g shardflux --include=optional, then run shard.');
         if (!graphicalSession(this.#env))
             throw new UsageError('Open shard from your desktop session to show the window.');
+        const stable = stableDesktopRuntime(runtime);
         const current = await this.status(dir);
         if (!current.version || (compareVersions(current.version, version) ?? -1) < 0) {
             if (existsSync(this.app) && (lstatSync(this.app).isSymbolicLink() || !current.version))
@@ -148,11 +158,14 @@ export class LinuxDesktopManager {
             }
         }
         mkdirSync(dir, { recursive: true, mode: 0o700 });
-        const env = { ...this.#env, SHARDFLUX_CONFIG_DIR: dir, SHARDFLUX_API_URL: api, SHARDFLUX_NODE: runtime.node, SHARDFLUX_CLI: runtime.script };
+        const env = { ...this.#env, SHARDFLUX_CONFIG_DIR: dir, SHARDFLUX_API_URL: api, SHARDFLUX_NODE: stable.node, SHARDFLUX_CLI: stable.script };
         const desktop = join(this.home, '.local/share/applications/dev.shardflux.Desktop.desktop');
         mkdirSync(dirname(desktop), { recursive: true });
-        const args = ['/usr/bin/env', `SHARDFLUX_CONFIG_DIR=${dir}`, `SHARDFLUX_API_URL=${api}`, `SHARDFLUX_NODE=${runtime.node}`, `SHARDFLUX_CLI=${runtime.script}`, join(this.app, 'shardflux-desktop')];
+        const args = ['/usr/bin/env', `SHARDFLUX_CONFIG_DIR=${dir}`, `SHARDFLUX_API_URL=${api}`, `SHARDFLUX_NODE=${stable.node}`, `SHARDFLUX_CLI=${stable.script}`, join(this.app, 'shardflux-desktop')];
         writeFileSync(desktop, `[Desktop Entry]\nType=Application\nName=Shardflux\nComment=Your agents, a shortcut away\nExec=${args.map(desktopString).join(' ')}\nIcon=${join(this.app, 'ui/assets/shardflux-icon.png')}\nTerminal=false\nCategories=Development;\nStartupWMClass=dev.shardflux.Desktop\n`, { mode: 0o644 });
+        const autostart = join(this.home, '.config/autostart/shardflux.desktop');
+        if (existsSync(autostart))
+            cpSync(desktop, autostart);
         if ((await this.status(dir)).running)
             await this.#exec(join(this.app, 'shardflux-desktop'), ['--control', view], { env, timeout: 5_000 });
         else {

package/dist/errors.d.ts

@@ -1,4 +1,4 @@
-import type { CheckoutStatus, ExecSession, ExecutionResult } from '@shardflux/sdk';
+import type { RateLimitInfo, CheckoutStatus, ExecSession, ExecutionResult } from '@shardflux/sdk';
 export declare const EXIT: {
     readonly ok: 0;
     /** Any other failure: API refusal (conflict, quota, ...), network, protocol. */
@@ -145,6 +145,7 @@ export interface ErrorInfo {
     execution_id?: string;
     /** The refusal's Retry-After in seconds (0.9.0+), e.g. 429 quota_exceeded from the cell gateway. */
     retry_after_seconds?: number;
+    rate_limit?: RateLimitInfo;
 }
 /**
  * Removes anything shaped like a Shardflux API key or user session token from text, and each of the given secrets

package/dist/errors.js

@@ -3,7 +3,7 @@
  * stderr with the API's error code, message and request id; the process exit
  * code tells scripts what kind of failure it was (README "Exit codes").
  */
-import { CheckoutTimeoutError, DurabilityLostError, ExecStartError, FilesystemSaveFailedError, FilesystemSaveTimeoutError, OperationFailedError, OperationTimeoutError, ShardfluxApiError, ShardfluxProtocolError, TemplateBuildTimeoutError, TemplateFileError, TemplateUploadError } from '@shardflux/sdk';
+import { budgetHint, CheckoutTimeoutError, DurabilityLostError, ExecStartError, FilesystemSaveFailedError, FilesystemSaveTimeoutError, OperationFailedError, OperationTimeoutError, ShardfluxApiError, ShardfluxProtocolError, TemplateBuildTimeoutError, TemplateFileError, TemplateUploadError } from '@shardflux/sdk';
 export const EXIT = {
     ok: 0,
     /** Any other failure: API refusal (conflict, quota, ...), network, protocol. */
@@ -212,7 +212,9 @@ export function planDiskLimit(failure) {
 /** Bytes as the plan names a disk: `2 GiB`, `2.5 GiB`. */
 export const gib = (bytes) => `${Number((bytes / 2 ** 30).toFixed(2))} GiB`;
 export function ownHint(err) {
-    return err instanceof HintedError ? err.hint : undefined;
+    if (err instanceof ShardfluxApiError && err.reason === 'codex_chatgpt_login_required')
+        return 'Sign in to Codex with ChatGPT using codex login, then copy your Codex login with shard setup again.';
+    return budgetHint(err) ?? (err instanceof HintedError ? err.hint : undefined);
 }
 function isNamed(err, name) {
     return typeof err === 'object' && err !== null && err.name === name;
@@ -238,6 +240,7 @@ export function describeError(err) {
             ...(err.operationId ? { operation_id: err.operationId } : {}),
             ...(err.details ? { details: err.details } : {}),
             source: err.source,
+            ...(err.rateLimit ? { rate_limit: err.rateLimit } : {}),
             ...(err.retryAfterSeconds !== undefined ? { retry_after_seconds: err.retryAfterSeconds } : {}),
         };
     }

package/dist/filesystem-commands.js

@@ -8,10 +8,32 @@ import { AGENT_HANDLERS } from "./agent-commands.js";
 import { readSetupProgress } from "./assisted-setup.js";
 import { syncAgentConfig } from "./agent-config-sync.js";
 import { progress } from "./progress.js";
+import { getConversation, localConversations } from "./conversations.js";
 function remote() {
     const project = projectIdentity('./');
     return { project, repoRemote: project.remote ?? normalizeRemote(`file://${project.folder}`) };
 }
+/**
+ * The VM this computer saves a project's template from (0.23.0+): the newest conversation this checkout started whose
+ * VM is there now, else the project's workspace (`<project>/main`, setups from before conversations). Each
+ * conversation's VM is read from the API: a restore by any client moves it to a new VM. In a VM, `shard template save`
+ * saves that VM itself.
+ */
+async function templateSource(ctx, project) {
+    const gone = (error) => { if (error instanceof ShardfluxApiError && error.status === 404)
+        return undefined; throw error; };
+    const started = Object.values(localConversations(ctx)).filter(r => r.folder === project.folder && r.api_url === ctx.apiUrl)
+        .sort((a, b) => Date.parse(b.conversation.created_at) - Date.parse(a.conversation.created_at));
+    for (const r of started) {
+        const c = await getConversation(ctx, r.conversation.id).catch(gone);
+        if (!c || c.ended_at || !c.workspace_id)
+            continue;
+        const ws = await ctx.cloud().workspaces.get(c.workspace_id, { signal: ctx.signal }).catch(gone);
+        if (ws && !ws.data.deleted_at)
+            return ws;
+    }
+    return await ctx.cloud().workspaces.findByKey(`${project.slug}/main`, { signal: ctx.signal }) ?? undefined;
+}
 /**
  * One line per status: what is in use and what is saving or failed, its platform base and setup cache. A project
  * template unused for 30 days (rebase_deferred, 0.20.1+) follows the machine when the next conversation starts.
@@ -202,7 +224,7 @@ export const FILESYSTEM_HANDLERS = {
     async template(ctx) {
         const { project, repoRemote } = remote();
         const state = await ctx.cloud().templates.getProject(repoRemote, { signal: ctx.signal });
-        const ws = await ctx.cloud().workspaces.findByKey(`${project.slug}/main`, { signal: ctx.signal });
+        const ws = await templateSource(ctx, project);
         const progress = ws ? await readSetupProgress(ctx, ws.data) : undefined;
         const attachments = ws ? await ctx.cloud().volumes.listAttached(ws.id) : undefined;
         const mounted = attachments?.data.some((a) => a.mount_path === '/mnt/shardflux-cache' && a.mounted && a.volume.name === 'shardflux-setup-cache' && a.volume.org_shared);
@@ -210,9 +232,9 @@ export const FILESYSTEM_HANDLERS = {
     },
     async 'template save'(ctx, values) {
         const { project, repoRemote } = remote();
-        const ws = await ctx.cloud().workspaces.findByKey(`${project.slug}/main`, { signal: ctx.signal });
+        const ws = await templateSource(ctx, project);
         if (!ws)
-            throw new UsageError('Run shard ./ for this project before saving its template');
+            throw new UsageError('Start a conversation in this project with shard ./ before saving its template', 'or run shard template save in a conversation\'s VM');
         return saved(ctx, values, options => ctx.cloud().templates.saveProject({ repoRemote, workspaceId: ws.id }, options), () => ctx.cloud().templates.preflightProject({ workspaceId: ws.id }, { signal: ctx.signal }), 'template');
     },
     async 'template rollback'(ctx, values) {

package/dist/menubar.d.ts

@@ -1,12 +1,13 @@
 import type { Handler } from './commands.js';
-export type NativeRunner = (tool: string, args: string[]) => Promise<string>;
+/** `env` adds variables to this process's environment for the tool (the app's --control reads its config directory). */
+export type NativeRunner = (tool: string, args: string[], env?: Record<string, string>) => Promise<string>;
 /**
  * Every native tool a default MenubarManager runs (plutil, codesign, xattr, open, the app's --control) goes through
  * `nativeTools.run`. The CLI test support replaces it, so a test run never starts, stops or inspects a real app,
  * whether or not a built Shardflux.app is in the package.
  */
 export declare const nativeTools: {
-    run: (tool: string, args: string[], signal?: AbortSignal) => Promise<string>;
+    run: (tool: string, args: string[], signal?: AbortSignal, env?: Record<string, string>) => Promise<string>;
 };
 export interface MenubarStatus {
     installed: boolean;
@@ -57,9 +58,9 @@ export declare class MenubarManager {
     packagedVersion(): Promise<string>;
     /** Whether the app shows any window (see windowsOpen); null when that could not be read. */
     windowsOpen(pids: number[]): Promise<boolean | null>;
-    status(): Promise<MenubarStatus>;
-    stop(): Promise<MenubarStatus>;
-    login(value: 'on' | 'off'): Promise<MenubarStatus>;
+    status(configDir?: string): Promise<MenubarStatus>;
+    stop(configDir?: string): Promise<MenubarStatus>;
+    login(value: 'on' | 'off', configDir?: string): Promise<MenubarStatus>;
     start(configDir: string, apiUrl: string): Promise<MenubarStatus>;
     /**
      * Brings an installed app up to the one this CLI's npm package carries, without disturbing the person: nothing when