@shardflux/cli 0.20.0 → 0.23.0

package/dist/device-helper.js

@@ -4,16 +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 { AGENT_CONFIG_POLL_MS, AgentConfigReturnState, returnAgentConfigsOnce } from "./agent-config-return.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]);
@@ -68,33 +69,51 @@ 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, returning;
+    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.
-            returning = (async () => {
-                let failures = 0;
-                const reported = new Set();
+            // 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 wait = AGENT_CONFIG_POLL_MS;
-                    try {
-                        await returnAgentConfigsOnce(ctx, config);
-                        failures = 0;
-                    }
-                    catch (e) {
-                        if (signal.aborted)
-                            break;
-                        wait = Math.min(300_000, 5000 * 2 ** Math.min(failures++, 6));
-                        const message = e instanceof Error ? e.message : String(e);
-                        if (!conversationsUnavailable(e) && !reported.has(message)) {
-                            reported.add(message);
-                            ctx.io.stderr.write(`Agent config: ${message} (retrying in ${wait / 1000}s).\n`);
+                    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(wait, undefined, { signal }).catch(() => undefined);
+                    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.
@@ -161,6 +180,8 @@ export async function runDeviceHelper(ctx, options = {}) {
         await returning;
         await config.folding;
         await twin;
+        await preparing;
+        await projects;
         await input.catch(() => undefined);
     }
 }

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. */
@@ -58,9 +58,14 @@ 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
@@ -140,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
@@ -147,6 +153,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

@@ -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. */
@@ -83,9 +83,17 @@ 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
@@ -175,8 +183,38 @@ 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;
+    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;
@@ -202,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 } : {}),
         };
     }
@@ -260,10 +299,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)
@@ -271,7 +314,7 @@ 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) {

package/dist/filesystem-commands.d.ts

@@ -1,6 +1,9 @@
-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;
@@ -10,15 +13,19 @@ export interface BuildQueue {
     slots: number;
     expected_wait_seconds: number;
 }
-/** "about 40 s" / "about 3 min": the queue's estimate, rounded the way people say it. */
-export declare function aboutWait(seconds: number): string;
-/** One line for a build that waits for a slot (0.20.0+): "Queued behind 3 builds · about 40 s" (running ones + those ahead). */
-export declare function queueLine(q: BuildQueue): string;
-/** How often a waited save reads its build's place in the queue. */
-export declare const QUEUE_POLL_MS = 2500;
+/** 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,18 +1,46 @@
+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";
 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}`) };
 }
-/** One line per status: what is in use and what is saving or failed, its platform base and setup cache. */
+/**
+ * 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.
+ */
 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,21 +57,8 @@ function output(ctx, state) {
     ctx.io.stdout.write(ctx.json ? JSON.stringify(state) + '\n' : `${filesystemLine(state)}\n`);
     return 0;
 }
-/** "about 40 s" / "about 3 min": the queue's estimate, rounded the way people say it. */
-export function aboutWait(seconds) {
-    if (seconds < 90)
-        return `about ${Math.max(10, Math.round(seconds / 10) * 10)} s`;
-    return `about ${Math.round(seconds / 60)} min`;
-}
-/** One line for a build that waits for a slot (0.20.0+): "Queued behind 3 builds · about 40 s" (running ones + those ahead). */
-export function queueLine(q) {
-    const behind = q.slots + q.position - 1;
-    return `Queued behind ${behind} build${behind === 1 ? '' : 's'} · ${aboutWait(q.expected_wait_seconds)}`;
-}
-/** How often a waited save reads its build's place in the queue. */
-export const QUEUE_POLL_MS = 2_500;
 /** The pending build's queue, if it waits for a slot; nothing when the API predates it or the build cannot be read. */
-async function pendingQueue(ctx, state) {
+export async function pendingQueue(ctx, state) {
     if (!state.pending)
         return undefined;
     try {
@@ -54,53 +69,74 @@ async function pendingQueue(ctx, state) {
         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: one line naming the version being saved (and its place in the queue when the plan's build slots are in
- * use, 0.20.0+), or with --wait the saved version (progress on stderr, the queue line updating while it waits).
+ * 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, level) {
+async function saved(ctx, values, save, preflight, level) {
     if (values.wait !== true && values.timeout !== undefined)
         throw new UsageError('--timeout needs --wait');
-    const stop = new AbortController();
-    let watcher;
-    // While the save waits, its build's place in the queue: one line each time it changes.
-    const watchQueue = (state) => {
-        if (watcher || !state.pending)
+    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;
-        watcher = (async () => {
-            let last = '';
-            while (!stop.signal.aborted) {
-                const q = await pendingQueue(ctx, state);
-                const line = q ? queueLine(q) : '';
-                if (line && line !== last && !stop.signal.aborted)
-                    progress(ctx, line);
-                last = line;
-                await new Promise(resolve => {
-                    const timer = setTimeout(resolve, QUEUE_POLL_MS);
-                    stop.signal.addEventListener('abort', () => { clearTimeout(timer); resolve(); }, { once: true });
-                });
-            }
-        })();
+        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), onChange: (state) => {
-            if (state.state === 'building' && state.pending) {
-                progress(ctx, `Saving ${level} version ${state.pending.version}…`);
-                watchQueue(state);
+    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 } : {}) });
     }
-    finally {
-        stop.abort();
-        await watcher;
+    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, queue ? { ...state, queue } : state);
+        return output(ctx, document(state, queue ? { queue } : {}));
     const moved = movedLine(state, level);
-    const queued = queue ? `; ${queueLine(queue).replace(/^Q/, 'q')}` : '';
+    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;
 }
@@ -111,6 +147,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;
@@ -119,7 +161,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();
@@ -161,12 +213,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 }));
@@ -174,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);
@@ -182,12 +232,38 @@ 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');
-        return saved(ctx, values, options => ctx.cloud().templates.saveProject({ repoRemote, workspaceId: ws.id }, options), '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) {
         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