@shardflux/cli 0.19.1 → 0.22.0

package/dist/device-bridge.d.ts

@@ -63,7 +63,7 @@ export declare class DeviceGrants {
     allows(api: string, project: string, root: string, kind: string, outside: boolean): boolean;
     save(api: string, project: string, root: string, kind: string): Promise<void>;
 }
-export declare function deviceSummary(r: DeviceRequest): string;
+export declare function deviceSummary(r: DeviceRequest, platform?: NodeJS.Platform): string;
 /** Structured local approval details; the summary remains for older menu bar and ACP clients. */
 export declare function deviceApproval(r: DeviceRequest, c: Conversation, target: {
     path: string;

package/dist/device-bridge.js

@@ -14,6 +14,7 @@ import { UsageError } from "./errors.js";
 import { conversationClient } from "./conversation-commands.js";
 import { withTargetLock } from "./target-lock.js";
 import { checkConversationWorktree, rememberConversationWorktree } from "./conversation-worktree.js";
+import { yourComputer } from "./this-computer.js";
 const LIMIT = 256 << 20, OUTPUT = (192 << 10) - 128;
 const inside = (root, target) => target === root || target.startsWith(root + sep);
 const safeId = (value) => { if (!/^[a-zA-Z0-9_-]{1,96}$/.test(value))
@@ -67,14 +68,15 @@ export class DeviceGrants {
         });
     }
 }
-export function deviceSummary(r) {
+export function deviceSummary(r, platform = process.platform) {
+    const yours = yourComputer(platform);
     if (tryLocallyAction(r))
         return tryLocallyAction(r) === 'stop' ? 'Stop this conversation’s local sync and ports.' : 'Try this conversation in an isolated local worktree with two-way sync and localhost ports.';
     if (r.kind === 'exec')
-        return `Run on your Mac: ${JSON.stringify(r.exec?.argv)} · directory ${r.exec?.cwd_relative ?? '.'}`;
+        return `Run on ${yours}: ${JSON.stringify(r.exec?.argv)} · directory ${r.exec?.cwd_relative ?? '.'}`;
     if (r.files)
-        return `${r.kind === 'files_pull' ? 'Share with conversation' : 'Save on your Mac'}: ${r.files.local_path_relative} ↔ ${r.files.remote_path}`;
-    return `${r.kind === 'port_forward' ? 'Open conversation preview on your Mac' : 'Connect conversation to your Mac'}: ${r.port?.remote_port} ↔ localhost:${r.port?.local_port}`;
+        return `${r.kind === 'files_pull' ? 'Share with conversation' : `Save on ${yours}`}: ${r.files.local_path_relative} ↔ ${r.files.remote_path}`;
+    return `${r.kind === 'port_forward' ? `Open conversation preview on ${yours}` : `Connect conversation to ${yours}`}: ${r.port?.remote_port} ↔ localhost:${r.port?.local_port}`;
 }
 /** Structured local approval details; the summary remains for older menu bar and ACP clients. */
 export function deviceApproval(r, c, target, folder) {

package/dist/device-helper.js

@@ -4,15 +4,17 @@ import { ConversationMirrorState, mirrorProjectConversations } from "./conversat
 import { FilesMirrorState, mirrorFilesOnce } from "./files-mirror.js";
 import { withTargetLock } from "./target-lock.js";
 import { join } from 'node:path';
-import { conversationsUnavailable } from "./conversations.js";
-import { localConversations } from "./conversations.js";
+import { completeDeferredPreparation, conversationsUnavailable, localConversations } from "./conversations.js";
 import { randomUUID } from 'node:crypto';
 import { readFileSync } from 'node:fs';
 import { writePrivateFile } from "./credentials.js";
 import { conversationClient } from "./conversation-commands.js";
 import { Readable } from 'node:stream';
 import { runWorktreeTwin } from "./worktree-twin-engine.js";
+import { AgentConfigReturnState, runAgentConfigLoop } from "./agent-config-return.js";
 import { askLocalDeviceApproval } from "./device-approvals.js";
+import { resumeCloudStartup, startCarried } from "./codex-cloud.js";
+import { runProjectPreparation } from "./project-preparation.js";
 /** The menu bar owns this helper and its stdin; VM data can request actions but cannot answer approvals. */
 export async function runDeviceHelper(ctx, options = {}) {
     const abort = new AbortController(), signal = AbortSignal.any([ctx.signal, abort.signal]);
@@ -55,7 +57,7 @@ export async function runDeviceHelper(ctx, options = {}) {
             ctx.io.stdout.write(JSON.stringify({ type: 'approval_resolved', request_id: approval.request_id }) + '\n'); });
     };
     const working = new Map();
-    const mirrored = new ConversationMirrorState(), files = new FilesMirrorState();
+    const mirrored = new ConversationMirrorState(), files = new FilesMirrorState(), config = new AgentConfigReturnState();
     const deviceFile = join(ctx.store.dir, 'device-id');
     let deviceId;
     try {
@@ -67,11 +69,53 @@ export async function runDeviceHelper(ctx, options = {}) {
     }
     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, twin;
+    let mirroring, twin, returning, preparing, projects;
     try {
         return await withTargetLock(join(ctx.store.dir, 'device-helper-lock'), async () => {
             // Finished conversations land in their local branches (worktree-twin-engine.ts); its own loop and backoff.
             twin = runWorktreeTwin(ctx, deviceId, signal).catch(report);
+            // Skills, memories and CLAUDE.md lines saved in the cloud come back on their own cadence (agent-config-return.ts):
+            // never behind a files-mirror pass, which takes minutes for an account with hundreds of conversations. Every 2 s
+            // while one of this user's conversations is active, backing off to 60 s when none is.
+            returning = runAgentConfigLoop(ctx, config, signal).catch(report);
+            projects = runProjectPreparation(ctx).catch(report);
+            // Starts outlive the foreground command (0.22.0+): an accepted Codex Cloud start resumes with its own revision
+            // and idempotent admission and message; large media that followed a first prompt land while the VM is awake.
+            preparing = (async () => {
+                const failures = new Map();
+                while (!signal.aborted) {
+                    let deferred = false;
+                    for (const local of Object.values(localConversations(ctx))) {
+                        if (local.conversation.ended_at || (failures.get(local.conversation.id) ?? 0) > Date.now())
+                            continue;
+                        try {
+                            // A start a foreground command still carries is its own: resumed only once nobody does.
+                            if (local.cloud_start && local.cloud_start.state !== 'active' && !local.cloud_start.attachments_pending) {
+                                if (!startCarried(local.cloud_start))
+                                    await resumeCloudStartup(ctx, local.conversation);
+                            }
+                            else if (local.preparation?.state === 'deferred') {
+                                // A parked VM is never woken for this: its media land the next time it is awake.
+                                if (await completeDeferredPreparation(ctx, local.conversation))
+                                    failures.delete(local.conversation.id);
+                                else {
+                                    deferred = true;
+                                    failures.set(local.conversation.id, Date.now() + 15_000);
+                                }
+                                continue;
+                            }
+                            failures.delete(local.conversation.id);
+                        }
+                        catch (error) {
+                            if (signal.aborted)
+                                break;
+                            report(error);
+                            failures.set(local.conversation.id, Date.now() + 60_000);
+                        }
+                    }
+                    await delay(deferred ? 5_000 : 30_000, undefined, { signal }).catch(() => undefined);
+                }
+            })();
             // A slow or failed transcript copy must not delay heartbeats, request polling or approvals.
             mirroring = (async () => {
                 let failures = 0;
@@ -133,7 +177,11 @@ export async function runDeviceHelper(ctx, options = {}) {
         await executor.close();
         await Promise.all([...working.values()]);
         await mirroring;
+        await returning;
+        await config.folding;
         await twin;
+        await preparing;
+        await projects;
         await input.catch(() => undefined);
     }
 }

package/dist/errors.d.ts

@@ -58,9 +58,21 @@ export declare class TermsNotAcceptedError extends CodedError {
 export declare class AuthConfigError extends HintedError {
     name: string;
 }
-/** A workspace key that no workspace of this project has (or another name that resolves to nothing). */
+/**
+ * A workspace key that no workspace of this project has (or another name that resolves to nothing). `details` keeps the
+ * API's reason when shard rewords its 404 (0.20.1+: `filesystem_not_found` from shard template delete).
+ */
 export declare class NotFoundError extends HintedError {
     name: string;
+    readonly details: Record<string, unknown> | undefined;
+    constructor(message: string, hint?: string, details?: Record<string, unknown>);
+}
+/**
+ * `shard machine setup --from-this-computer` (0.20.0+) ran but did not save a machine: the agent failed, ran past its
+ * time box, or the save failed. Retryable: the same command runs it again (exit 6).
+ */
+export declare class MachineSetupError extends HintedError {
+    name: string;
 }
 /** `auth login` of a two-factor account without a code: the pending sign-in is saved; `shard auth mfa` completes it (exit 4). */
 export declare class MfaPendingError extends HintedError {
@@ -140,6 +152,27 @@ export interface ErrorInfo {
  */
 export declare function redact(text: string, ...secrets: (string | null | undefined)[]): string;
 /** The `hint:` a CLI error carries itself, if any. */
+/**
+ * After a save that failed (0.20.2+): the version in use and the source VM are as they were, so the same save can run
+ * again; the build's log says what happened.
+ */
+export declare function saveRecovery(level: 'machine' | 'template', inUse: number, buildId?: string, failure?: SaveFailure): string;
+/** What a failed save reports about its build (SDK 0.26.0+ on an API that carries them). */
+export interface SaveFailure {
+    code?: string | undefined;
+    retryable?: boolean | undefined;
+    details?: Record<string, unknown> | undefined;
+}
+/**
+ * A save larger than the plan's workspace disk (0.21.1+): resource_limit with details.limit template_org_bytes_max;
+ * `limit` is the plan's workspace disk and `actual` the version's size, in bytes.
+ */
+export declare function planDiskLimit(failure: SaveFailure | undefined): {
+    limit: number;
+    actual: number;
+} | undefined;
+/** Bytes as the plan names a disk: `2 GiB`, `2.5 GiB`. */
+export declare const gib: (bytes: number) => string;
 export declare function ownHint(err: unknown): string | undefined;
 export declare function describeError(err: unknown): ErrorInfo;
 /** Maps an error to the documented exit code. */

package/dist/errors.js

@@ -83,9 +83,24 @@ export class TermsNotAcceptedError extends CodedError {
 export class AuthConfigError extends HintedError {
     name = 'AuthConfigError';
 }
-/** A workspace key that no workspace of this project has (or another name that resolves to nothing). */
+/**
+ * A workspace key that no workspace of this project has (or another name that resolves to nothing). `details` keeps the
+ * API's reason when shard rewords its 404 (0.20.1+: `filesystem_not_found` from shard template delete).
+ */
 export class NotFoundError extends HintedError {
     name = 'NotFoundError';
+    details;
+    constructor(message, hint, details) {
+        super(message, hint);
+        this.details = details;
+    }
+}
+/**
+ * `shard machine setup --from-this-computer` (0.20.0+) ran but did not save a machine: the agent failed, ran past its
+ * time box, or the save failed. Retryable: the same command runs it again (exit 6).
+ */
+export class MachineSetupError extends HintedError {
+    name = 'MachineSetupError';
 }
 /** `auth login` of a two-factor account without a code: the pending sign-in is saved; `shard auth mfa` completes it (exit 4). */
 export class MfaPendingError extends HintedError {
@@ -168,6 +183,34 @@ export function redact(text, ...secrets) {
     return out;
 }
 /** The `hint:` a CLI error carries itself, if any. */
+/**
+ * After a save that failed (0.20.2+): the version in use and the source VM are as they were, so the same save can run
+ * again; the build's log says what happened.
+ */
+export function saveRecovery(level, inUse, buildId, failure) {
+    const kept = inUse > 0 ? `version ${inUse} stays in use and ` : '';
+    const vm = level === 'machine' ? 'machine' : 'project';
+    // Larger than the plan's workspace disk (0.21.1+): the same save fails again until the VM or the plan changes.
+    const disk = planDiskLimit(failure);
+    if (disk) {
+        const open = level === 'machine' ? ' (shard machine open)' : '';
+        return `${kept}your ${vm} VM is untouched; delete what it does not need there${open}, such as caches and build output, then run shard ${level} save --wait; or upgrade to a plan with more than ${gib(disk.limit)} of disk: shard billing plans`;
+    }
+    if (failure?.retryable === false)
+        return `${kept}your ${vm} VM is untouched; change what the message names in it, then run shard ${level} save --wait`;
+    const log = buildId ? `; build log: shard templates builds log ${buildId}` : '';
+    return `${kept}your ${vm} VM is untouched; run shard ${level} save --wait again (it saves from the same VM)${log}`;
+}
+/**
+ * A save larger than the plan's workspace disk (0.21.1+): resource_limit with details.limit template_org_bytes_max;
+ * `limit` is the plan's workspace disk and `actual` the version's size, in bytes.
+ */
+export function planDiskLimit(failure) {
+    const d = failure?.details;
+    return failure?.code === 'resource_limit' && d?.limit === 'template_org_bytes_max' && typeof d.value === 'number' && typeof d.actual === 'number' ? { limit: d.value, actual: d.actual } : undefined;
+}
+/** 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;
 }
@@ -253,10 +296,14 @@ export function describeError(err) {
     if (err instanceof TemplateBuildTimeoutError)
         return { code: 'timeout', message: `${err.message}; follow it with: shard templates builds get ${err.build.id}`, last_state: err.build.state };
     // machine/template save --wait (0.13.3+): the save ended without its version, or is still building at the deadline.
-    if (err instanceof FilesystemSaveFailedError)
-        return { code: 'filesystem_save_failed', message: err.message, retryable: true, details: { level: err.state.level, version: err.version } };
+    // 0.20.2+: details.build_id, and a failure's recovery as `fix` (the hint line).
+    // 0.21.1+: the build's failure (error_code and its details, e.g. limit/value/actual) and whether the same save can
+    // succeed (retryable false: larger than the plan's workspace disk, or another refusal that repeats until the VM changes).
+    if (err instanceof FilesystemSaveFailedError) {
+        return { code: 'filesystem_save_failed', message: err.message, retryable: err.retryable, fix: saveRecovery(err.state.level, err.state.version, err.buildId, err), details: { ...(err.details ?? {}), ...(err.code ? { error_code: err.code } : {}), level: err.state.level, version: err.version, ...(err.buildId ? { build_id: err.buildId } : {}), ...(err.progress ? { last_progress: err.progress } : {}) } };
+    }
     if (err instanceof FilesystemSaveTimeoutError)
-        return { code: 'timeout', message: `${err.message}; check with shard ${err.state.level}`, last_state: err.state.state, details: { level: err.state.level, version: err.version } };
+        return { code: 'timeout', message: `${err.message}; check with shard ${err.state.level}`, last_state: err.state.state, details: { level: err.state.level, version: err.version, ...(err.buildId ? { build_id: err.buildId } : {}), ...(err.progress ? { last_progress: err.progress } : {}) } };
     if (err instanceof TemplateUploadError)
         return { code: 'upload_failed', message: err.message, ...(err.status ? { status: err.status } : {}), details: { sha256: err.sha256, ...(err.code ? { storage_code: err.code } : {}) } };
     if (err instanceof AuthConfigError)
@@ -264,7 +311,9 @@ export function describeError(err) {
     if (err instanceof MfaPendingError)
         return { code: 'mfa_required', message: err.message };
     if (err instanceof NotFoundError)
-        return { code: 'not_found', message: err.message };
+        return { code: 'not_found', message: err.message, ...(err.details ? { details: err.details } : {}) };
+    if (err instanceof MachineSetupError)
+        return { code: 'machine_setup_failed', message: err.message, retryable: true };
     if (err instanceof InterruptedError) {
         return { code: 'interrupted', message: err.message, ...(err.operationId ? { operation_id: err.operationId } : {}), ...(err.executionId ? { execution_id: err.executionId } : {}) };
     }
@@ -294,6 +343,8 @@ export function exitCodeFor(err, interrupted = false) {
         return EXIT.operationFailed;
     if (err instanceof NotFoundError)
         return EXIT.notFound;
+    if (err instanceof MachineSetupError)
+        return EXIT.operationFailed;
     if (err instanceof OperationTimeoutError || err instanceof CheckoutTimeoutError || isNamed(err, 'TimeoutError'))
         return EXIT.timeout;
     if (err instanceof OperationFailedError || err instanceof DurabilityLostError || err instanceof ExecutionFailedError || err instanceof CheckoutEndedError)

package/dist/filesystem-commands.d.ts

@@ -1,12 +1,31 @@
-import type { AgentFilesystem, Workspace } from '@shardflux/sdk';
+import type { AgentFilesystem, AgentFilesystemDeleted, Workspace } from '@shardflux/sdk';
 import type { Ctx, Handler } from './commands.js';
-/** One line per status: what is in use and what is saving or failed, its platform base and setup cache. */
+/**
+ * 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.
+ */
 export declare function filesystemLine(state: AgentFilesystem & {
     cache_scope?: string;
 }): string;
+/** A build's place while it waits for one of the plan's build slots (API: TemplateBuild.queue). */
+export interface BuildQueue {
+    position: number;
+    slots: number;
+    expected_wait_seconds: number;
+}
+/** The pending build's queue, if it waits for a slot; nothing when the API predates it or the build cannot be read. */
+export declare function pendingQueue(ctx: Ctx, state: AgentFilesystem): Promise<BuildQueue | undefined>;
+/** Within one phase of a waited save, a changed counter line is printed at most this often (0.20.2+). */
+export declare const SAVE_PROGRESS_LINE_MS = 30000;
 /** The save's one line about software under the home that went into the image (0.18.0+), as the in-VM shard says it. */
 export declare function movedLine(state: AgentFilesystem, level: 'machine' | 'template'): string;
-/** Creates or resumes the machine VM of the saved machine version; the first one gets this computer's agent config. */
+/** `shard template delete` (0.20.1+): what went, in one line. A binding-only delete has no template. */
+export declare function deletedLine(deleted: AgentFilesystemDeleted): string;
+/**
+ * The VM `shard machine save` saves: the machine VM of the version in use, else the one the last save came from. A
+ * deleted one is not there (0.20.2+: the machine row offers Save again only while it is).
+ */
+export declare function machineSaveSource(ctx: Ctx, state: AgentFilesystem): Promise<Workspace | null>;
 /** The account's machine VM, created or resumed; `sync: false` skips the first-open config sync (an account sign-in). */
 export declare function openMachine(ctx: Ctx, state?: AgentFilesystem, opts?: {
     sync?: boolean;

package/dist/filesystem-commands.js

@@ -1,6 +1,8 @@
+import { randomUUID } from 'node:crypto';
+import { FilesystemSaveFailedError, FilesystemSaveTimeoutError, SavePhases, ShardfluxApiError, savePreflightText, saveProgressText } from '@shardflux/sdk';
 import { codingAgentShell } from "./agent-setup.js";
 import { waitTimeout } from "./commands.js";
-import { UsageError } from "./errors.js";
+import { NotFoundError, UsageError } from "./errors.js";
 import { projectIdentity, normalizeRemote } from "./project-identity.js";
 import { AGENT_HANDLERS } from "./agent-commands.js";
 import { readSetupProgress } from "./assisted-setup.js";
@@ -10,9 +12,13 @@ function remote() {
     const project = projectIdentity('./');
     return { project, repoRemote: project.remote ?? normalizeRemote(`file://${project.folder}`) };
 }
-/** One line per status: what is in use and what is saving or failed, its platform base and setup cache. */
+/**
+ * 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.
+ */
 export function filesystemLine(state) {
-    const base = state.platform_base ? `; platform ${state.platform_base.slug}@${state.platform_base.version}${state.rebase_pending ? ', rebase pending' : ''}` : '';
+    const rebase = state.rebase_deferred ? ', follows your machine on next use' : state.rebase_pending ? ', rebase pending' : '';
+    const base = state.platform_base ? `; platform ${state.platform_base.slug}@${state.platform_base.version}${rebase}` : '';
     return usageLine(state) + base + (state.cache_scope ? `; cache: ${state.cache_scope}` : '');
 }
 function usageLine(state) {
@@ -29,17 +35,87 @@ function output(ctx, state) {
     ctx.io.stdout.write(ctx.json ? JSON.stringify(state) + '\n' : `${filesystemLine(state)}\n`);
     return 0;
 }
-/** Save output: one line naming the version being saved, or with --wait the saved version (progress on stderr). */
-async function saved(ctx, values, save, level) {
+/** The pending build's queue, if it waits for a slot; nothing when the API predates it or the build cannot be read. */
+export async function pendingQueue(ctx, state) {
+    if (!state.pending)
+        return undefined;
+    try {
+        const build = await ctx.cloud().templates.builds.get(state.organization_id, state.pending.build_id);
+        return build.queue ?? undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Within one phase of a waited save, a changed counter line is printed at most this often (0.20.2+). */
+export const SAVE_PROGRESS_LINE_MS = 30_000;
+/**
+ * Save output: the preflight line (what the save copies and about how long it takes, 0.20.2+), then one line naming
+ * the version being saved and its state (its place in the queue while the plan's build slots are in use, 0.20.0+), or
+ * with --wait one stderr line per phase with its counters, and the saved version. --json: one document at the end
+ * (`phases` with --wait, `preflight` when known), the progress as {"event":"save_progress"} lines on stderr.
+ */
+async function saved(ctx, values, save, preflight, level) {
     if (values.wait !== true && values.timeout !== undefined)
         throw new UsageError('--timeout needs --wait');
-    const wait = values.wait === true ? { timeoutMs: waitTimeout(values, 600_000), onChange: (state) => { if (state.state === 'building' && state.pending)
-            progress(ctx, `Saving ${level} version ${state.pending.version}…`); } } : undefined;
-    const state = await save({ signal: ctx.signal, ...(wait ? { wait } : {}) });
+    const pf = await preflight();
+    if (pf && !ctx.json)
+        progress(ctx, savePreflightText(pf));
+    else if (pf && values.wait === true)
+        ctx.io.stderr.write(`${JSON.stringify({ event: 'save_preflight', ...pf })}\n`);
+    const phases = new SavePhases();
+    // The first line names the version; later lines say what changed: a new phase or place in the queue at once, newer
+    // counters within a phase at most every SAVE_PROGRESS_LINE_MS.
+    let announced = false;
+    let last = { line: '', milestone: '', at: 0 };
+    const onProgress = (p, final = false) => {
+        phases.update(p);
+        const line = saveProgressText(p);
+        const milestone = JSON.stringify([p.state, p.progress?.phase ?? null, p.queue?.position ?? null, p.queue?.slots ?? null]);
+        const now = Date.now();
+        if (announced && (line === last.line || (!final && milestone === last.milestone && now - last.at < SAVE_PROGRESS_LINE_MS)))
+            return;
+        if (ctx.json)
+            ctx.io.stderr.write(`${JSON.stringify({ event: 'save_progress', ...p })}\n`);
+        else
+            progress(ctx, announced ? line : `${level}: saving version ${p.version} · ${line}`);
+        announced = true;
+        last = { line, milestone, at: now };
+    };
+    const wait = values.wait === true ? { timeoutMs: waitTimeout(values, 600_000), onProgress, onChange: (state) => {
+            // An API that does not show the build: the version alone.
+            if (!announced && state.state === 'building' && state.pending) {
+                // The filesystem says saving; the unavailable build view cannot tell us queued versus running.
+                if (ctx.json)
+                    ctx.io.stderr.write(`${JSON.stringify({ event: 'save_started', level, version: state.pending.version, build_id: state.pending.build_id })}\n`);
+                else
+                    progress(ctx, `${level}: saving version ${state.pending.version}`);
+                announced = true;
+            }
+        } } : undefined;
+    const document = (state, extra = {}) => ({ ...state, ...extra, ...(wait ? { phases: phases.list() } : {}), ...(pf ? { preflight: pf } : {}) });
+    let state;
+    try {
+        state = await save({ signal: ctx.signal, ...(wait ? { wait } : {}) });
+    }
+    catch (err) {
+        if ((err instanceof FilesystemSaveTimeoutError || err instanceof FilesystemSaveFailedError) && err.progress)
+            onProgress(err.progress, true);
+        // --json: stdout still gets its one document, with how far the save got (still building at a timeout).
+        if (ctx.json && (err instanceof FilesystemSaveTimeoutError || err instanceof FilesystemSaveFailedError)) {
+            if (err instanceof FilesystemSaveFailedError)
+                phases.end();
+            ctx.io.stdout.write(`${JSON.stringify(document(err.state))}\n`);
+        }
+        throw err;
+    }
+    phases.end();
+    const queue = wait ? undefined : await pendingQueue(ctx, state);
     if (ctx.json)
-        return output(ctx, state);
+        return output(ctx, document(state, queue ? { queue } : {}));
     const moved = movedLine(state, level);
-    ctx.io.stdout.write(wait ? `${level}: version ${state.version} saved${moved}\n` : state.pending ? `${filesystemLine(state)}; shard ${level} shows when it is ready${moved}\n` : `${filesystemLine(state)}${moved}\n`);
+    const queued = queue ? `; ${saveProgressText({ version: state.pending?.version ?? 0, build_id: state.pending?.build_id ?? '', state: 'queued', queue })}` : '';
+    ctx.io.stdout.write(wait ? `${level}: version ${state.version} saved${moved}\n` : state.pending ? `${filesystemLine(state)}${queued}; shard ${level} shows when it is ready${moved}\n` : `${filesystemLine(state)}${moved}\n`);
     return 0;
 }
 /** The save's one line about software under the home that went into the image (0.18.0+), as the in-VM shard says it. */
@@ -49,6 +125,12 @@ export function movedLine(state, level) {
         return '';
     return `; ${moved.length} large tool folder${moved.length === 1 ? '' : 's'} went into the ${level} image (${moved.join(', ')}); they keep working at the same paths`;
 }
+/** `shard template delete` (0.20.1+): what went, in one line. A binding-only delete has no template. */
+export function deletedLine(deleted) {
+    const versions = deleted.template ? ` (${deleted.template.versions} saved version${deleted.template.versions === 1 ? '' : 's'})` : '';
+    const builds = deleted.canceled_builds > 0 ? `, stopped ${deleted.canceled_builds} build${deleted.canceled_builds === 1 ? '' : 's'}` : '';
+    return `template: deleted${versions}${builds}; new conversations start from your machine until setup saves a new one`;
+}
 const rollbackTo = (value) => {
     if (value === undefined)
         return undefined;
@@ -57,7 +139,17 @@ const rollbackTo = (value) => {
         throw new UsageError('--to must be a saved version number');
     return n;
 };
-/** Creates or resumes the machine VM of the saved machine version; the first one gets this computer's agent config. */
+/**
+ * The VM `shard machine save` saves: the machine VM of the version in use, else the one the last save came from. A
+ * deleted one is not there (0.20.2+: the machine row offers Save again only while it is).
+ */
+export async function machineSaveSource(ctx, state) {
+    const cloud = ctx.cloud();
+    const ws = await cloud.workspaces.findByKey(`machine/${state.organization_id}/v${state.version}`, { includeDeleted: false, signal: ctx.signal }) ??
+        (state.workspace_id ? await cloud.workspaces.get(state.workspace_id).catch((e) => { if (e instanceof ShardfluxApiError && e.status === 404)
+            return null; throw e; }) : null);
+    return ws && !ws.data.deleted_at ? ws : null;
+}
 /** The account's machine VM, created or resumed; `sync: false` skips the first-open config sync (an account sign-in). */
 export async function openMachine(ctx, state, opts = {}) {
     const cloud = ctx.cloud();
@@ -99,12 +191,10 @@ export const FILESYSTEM_HANDLERS = {
     },
     async 'machine save'(ctx, values) {
         const cloud = ctx.cloud();
-        const state = await cloud.machine.get({ signal: ctx.signal });
-        const ws = await cloud.workspaces.findByKey(`machine/${state.organization_id}/v${state.version}`, { signal: ctx.signal }) ??
-            (state.workspace_id ? await cloud.workspaces.get(state.workspace_id) : null);
+        const ws = await machineSaveSource(ctx, await cloud.machine.get({ signal: ctx.signal }));
         if (!ws)
             throw new UsageError('Open your machine and change it first, then run shard machine save', 'shard machine in a terminal, or shard machine open --json for an agent (0.17.1+)');
-        return saved(ctx, values, options => cloud.machine.save({ workspaceId: ws.id }, options), 'machine');
+        return saved(ctx, values, options => cloud.machine.save({ workspaceId: ws.id }, options), () => cloud.machine.preflight({ workspaceId: ws.id }, { signal: ctx.signal }), 'machine');
     },
     async 'machine rollback'(ctx, values) {
         return output(ctx, await ctx.cloud().machine.rollback({ to: rollbackTo(values.to) }, { signal: ctx.signal }));
@@ -123,9 +213,35 @@ export const FILESYSTEM_HANDLERS = {
         const ws = await ctx.cloud().workspaces.findByKey(`${project.slug}/main`, { signal: ctx.signal });
         if (!ws)
             throw new UsageError('Run shard ./ for this project before saving its template');
-        return saved(ctx, values, options => ctx.cloud().templates.saveProject({ repoRemote, workspaceId: ws.id }, options), 'template');
+        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) {
         return output(ctx, await ctx.cloud().templates.rollbackProject({ repoRemote: remote().repoRemote, to: rollbackTo(values.to) }, { signal: ctx.signal }));
     },
+    /** `shard template delete` (0.20.1+): asks first in a terminal; elsewhere it needs --yes. */
+    async 'template delete'(ctx, values) {
+        const { repoRemote } = remote();
+        if (values.yes !== true) {
+            if (!ctx.input.interactive)
+                throw new UsageError(`refusing to delete without --yes (the project template of ${repoRemote} and its saved versions are deleted; new conversations start from your machine until setup saves a new one)`, 'run: shard template delete --yes');
+            const answer = (await ctx.input.answer(`Delete the project template for ${repoRemote}? Its saved versions go; new conversations start from your machine until setup saves a new one. [y/N] `))?.trim() ?? '';
+            if (!/^y(es)?$/i.test(answer)) {
+                ctx.io.stderr.write('Kept the project template.\n');
+                return 0;
+            }
+        }
+        let deleted;
+        try {
+            // One key per run: a retry after a dropped connection replays the same delete.
+            deleted = await ctx.cloud().templates.deleteProject({ repoRemote }, { idempotencyKey: randomUUID(), signal: ctx.signal });
+        }
+        catch (err) {
+            if (err instanceof ShardfluxApiError && err.status === 404 && err.details?.reason === 'filesystem_not_found') {
+                throw new NotFoundError(`template: nothing saved yet for ${repoRemote}, so there is nothing to delete`, 'setup saves it after shard ./, or run shard template save', { reason: 'filesystem_not_found', repo_remote: repoRemote });
+            }
+            throw err;
+        }
+        ctx.io.stdout.write(ctx.json ? JSON.stringify(deleted) + '\n' : `${deletedLine(deleted)}\n`);
+        return 0;
+    },
 };

package/dist/format.d.ts

@@ -1,4 +1,4 @@
-import type { AgentSession, ApiKey, AuditEvent, AuthSessionInfo, BillingCatalog, BillingInvoicePage, BillingSubscription, DataExport, DraftState, ExecutionChange, ExecutionResult, FileInfo, EgressPolicyVersion, Invitation, Member, Organization, Project, ProjectEgressPolicy, Volume, VolumeAttachment, WorkspaceEgressPolicy, FileList, FileSearchResponse, Operation, Secret, SecretAccessEvent, SecretVersion, SpendPolicy, SuspendRequest, TemplateBuild, TemplateDetail, TemplateDiffEntry, TemplateDraft, TemplateFileEntry, TemplateLanguages, TemplatePackagePage, TemplateSettings, TemplateSummary, TemplateVersion, WorkspaceChange, WorkspaceSecretBindings, WorkspaceMemory, WorkspaceView, MemoryGrow, BurstSummary, ResizeResult, ExposePortResult, ExposedPort } from '@shardflux/sdk';
+import type { AgentSession, ApiKey, AuditEvent, AuthSessionInfo, BillingCatalog, BillingInvoicePage, BillingSubscription, DataExport, DraftState, ExecutionChange, ExecutionResult, FileInfo, EgressPolicyVersion, Invitation, Member, Organization, Project, ProjectEgressPolicy, Volume, VolumeAttachment, WorkspaceEgressPolicy, FileList, FileSearchResponse, Operation, Secret, SecretAccessEvent, SecretVersion, SpendPolicy, SuspendRequest, SuspendProgress, TemplateBuild, TemplateDetail, TemplateDiffEntry, TemplateDraft, TemplateFileEntry, TemplateLanguages, TemplatePackagePage, TemplateSettings, TemplateSummary, TemplateVersion, WorkspaceChange, WorkspaceSecretBindings, WorkspaceMemory, WorkspaceView, MemoryGrow, BurstSummary, ResizeResult, ExposePortResult, ExposedPort } from '@shardflux/sdk';
 import type { ErrorInfo } from './errors.js';
 /** A workspace as the port commands name it. */
 interface PortWorkspace {
@@ -70,6 +70,7 @@ export declare function operationTable(ops: readonly Operation[]): string;
  */
 export declare function durableText(op: Operation): string;
 export declare function operationDetail(op: Operation): string;
+export declare function suspendProgressText(p: SuspendProgress): string;
 export declare function sessionTable(sessions: readonly AgentSession[]): string;
 /** `files stat`: one path's metadata; the revision only when requested and returned. */
 export declare function fileInfoText(f: FileInfo): string;

package/dist/format.js

@@ -300,6 +300,15 @@ export function operationDetail(op) {
         ['updated', time(op.updated_at)],
         ['completed', time(op.completed_at)],
         ['error', err ? `${scalar(err.code)}${err.message ? `: ${scalar(err.message)}` : ''}` : '-'],
+    ]) + (op.progress ? `\n${suspendProgressText(op.progress)}` : '');
+}
+export function suspendProgressText(p) {
+    return kv([
+        ['operation', p.operation_id], ['phase', p.phase], ['operation state', p.state], ['workspace state', p.workspace_state],
+        ['cancelable', p.cancelable ? 'yes' : 'no'], ['progress supported', p.supported ? 'yes' : 'unavailable'], ['next action', p.safe_action],
+        ...(p.phase_started_at ? [['phase started', p.phase_started_at]] : []),
+        ...(p.deadline_at ? [['host deadline', p.deadline_at]] : []),
+        ...(p.accepted === true ? [['cancel request', 'accepted; use the operation state to confirm recovery']] : []),
     ]);
 }
 export function sessionTable(sessions) {
@@ -546,7 +555,7 @@ export function feedbackCommand(e) {
     if (SHELL_SAFE.test(code))
         parts.push(`--error-code ${code}`);
     parts.push('"<what you expected>"');
-    return parts.join(' ');
+    return `${parts.join(' ')} # preview only; show the message and context, then use --yes only after explicit user authorization`;
 }
 /**
  * One stderr line: `error: <message> [code=... status=... request_id=...]` plus a hint when there is one, and the

package/dist/handlers.js

@@ -23,4 +23,7 @@ import { CLI_PROXY_HANDLERS } from "./cli-proxy.js";
 import { ACCOUNT_POOL_HANDLERS } from "./account-pool.js";
 import { MOVE_HANDLERS } from "./move.js";
 import { AGENT_CONFIG_HANDLERS } from "./agent-config-sync.js";
-export const HANDLERS = { ...MOVE_HANDLERS, ...DEVICE_HANDLERS, ...CODEX_CLOUD_HANDLERS, ...CLI_PROXY_HANDLERS, ...THREAD_HANDLERS, ...CONVERSATION_HANDLERS, ...LOCAL_CONVERSATION_HANDLERS, ...TWIN_HANDLERS, ...CREDENTIAL_HANDLERS, ...AGENT_CREDENTIAL_HANDLERS, ...ACCOUNT_POOL_HANDLERS, ...KEY_HANDLERS, ...ACCOUNT_HANDLERS, ...AGENT_HANDLERS, ...CENTER_HANDLERS, ...TARGET_HANDLERS, ...AGENT_GIT_HANDLERS, ...MENUBAR_HANDLERS, ...FILESYSTEM_HANDLERS, ...UPDATE_HANDLERS, 'agents config-sync': AGENT_CONFIG_HANDLERS['agents config-sync'] };
+import { MACHINE_SETUP_HANDLERS } from "./machine-setup.js";
+import { SETTINGS_HANDLERS } from "./client-settings.js";
+import { PROJECT_PREPARATION_HANDLERS } from "./project-preparation.js";
+export const HANDLERS = { ...PROJECT_PREPARATION_HANDLERS, ...MOVE_HANDLERS, ...DEVICE_HANDLERS, ...CODEX_CLOUD_HANDLERS, ...CLI_PROXY_HANDLERS, ...THREAD_HANDLERS, ...CONVERSATION_HANDLERS, ...LOCAL_CONVERSATION_HANDLERS, ...TWIN_HANDLERS, ...CREDENTIAL_HANDLERS, ...AGENT_CREDENTIAL_HANDLERS, ...ACCOUNT_POOL_HANDLERS, ...KEY_HANDLERS, ...ACCOUNT_HANDLERS, ...AGENT_HANDLERS, ...CENTER_HANDLERS, ...TARGET_HANDLERS, ...AGENT_GIT_HANDLERS, ...MENUBAR_HANDLERS, ...FILESYSTEM_HANDLERS, ...MACHINE_SETUP_HANDLERS, ...SETTINGS_HANDLERS, ...UPDATE_HANDLERS, ...AGENT_CONFIG_HANDLERS };

package/dist/initial-prompt.d.ts

@@ -30,6 +30,14 @@ export declare const INBOX_MAX_CHARS = 65536;
  * options. The guest's own first-message delivery reads the screen the same way (coding 39+).
  */
 export declare function inputBoxReady(tail: string, glyph: string): boolean;
+/**
+ * The first prompt typed by the VM's own guest (0.21.1+, with a guest that has it): `sf-agent conversation first-prompt` waits for
+ * the input box, pastes, waits for the paste to show and presses Enter inside the VM, with the same checks as
+ * `submitInitialPrompt`, in one request from here instead of an attachment and three round trips. Nothing was typed
+ * when the result is `unsupported` (an older guest without the command: this terminal types it) or `not_ready` (the
+ * harness never showed its input box within the guest's wait: the conversation's inbox takes it, where there is one).
+ */
+export declare function guestFirstPrompt(cell: Pick<CellClient, 'exec'>, ptyId: string, app: 'claude' | 'codex', prompt: string, workspaceKey: string, signal: AbortSignal): Promise<'submitted' | 'unsupported' | 'not_ready'>;
 /**
  * Wait for the native terminal to enable paste before submitting one first turn. No blind timing or input replay.
  * When nothing was typed yet and the terminal never became ready, `queue` hands the prompt to the conversation's guest