@shardflux/cli 0.4.1 → 0.5.1

package/dist/commands.js

@@ -1,31 +1,40 @@
 /**
- * Command implementations. Everything goes through @shardflux/sdk (the same
- * client, retries, idempotency keys, operation polling and tool-token
- * management as SDK users get); `cloud.request()` covers the two endpoints
- * the SDK has no typed method for yet (GET /v1/operations/{id}, usage summary).
+ * Command implementations of the project-key commands (workspaces, files, operations, secrets, templates, usage).
+ * Everything goes through @shardflux/sdk (the same client, retries, idempotency keys, operation polling and
+ * tool-token management as SDK users get); `cloud.request()` covers the two endpoints the SDK has no typed method
+ * for yet (GET /v1/operations/{id}, usage summary). The account plane (0.5.0) is in account-commands.ts; handlers.ts
+ * joins both tables.
  */
 import { randomUUID } from 'node:crypto';
 import { access, readFile, writeFile } from 'node:fs/promises';
 import { basename, dirname, resolve as resolvePath } from 'node:path';
-import { SDK_VERSION, ShardfluxApiError } from '@shardflux/sdk';
+import { EXECUTION_ID, FEEDBACK_CATEGORIES, FEEDBACK_MESSAGE_MAX_LENGTH, NotSupportedForModeError, SDK_VERSION, ShardfluxApiError, newExecutionId } from '@shardflux/sdk';
 import { parse as parseYaml } from 'yaml';
 import { CLI_VERSION, SECRET_NAME, UUID, parseDuration, parseEnvPairs, parsePositiveInt } from "./args.js";
-import { InterruptedError, NotFoundError, UsageError } from "./errors.js";
+import { ExecutionFailedError, ExecutionPendingError, InterruptedError, NotFoundError, UsageError } from "./errors.js";
+import { updateCheckDisabled } from "./update-check.js";
 import { initTemplateYaml, recipeYaml } from "./template-yaml.js";
 import { BuildTimer, buildTimingJson, buildTimingText, progressLine } from "./timing.js";
 import { timingJson } from "./timing.js";
-import { bindingsText, buildTable, buildText, changesTable, diffSummaryText, diffTable, draftText, draftStateTable, fileTable, languageTable, json, kv, operationDetail, operationTable, packageTable, secretAccessTable, secretDetail, secretTable, secretVersionTable, sessionTable, templateDetailText, templateEntryText, templateFileTable, templateTable, usageText, workspaceDetail, workspaceTable, } from "./format.js";
+import { bindingsText, buildTable, buildText, changesTable, diffSummaryText, diffTable, draftText, draftStateTable, executionJson, executionSummary, fileInfoText, fileTable, languageTable, json, kv, modeText, operationDetail, pairs, operationTable, packageTable, searchText, secretAccessTable, secretDetail, secretTable, secretVersionTable, sessionTable, suspendRequestText, suspendWhenIdleText, templateDetailText, templateEntryText, templateFileTable, templateTable, usageEstimateText, usageSeriesText, usageText, workspaceDetail, workspaceTable, } from "./format.js";
 const DEFAULT_WAIT_MS = 300_000;
 const MAX_JSON_OUTPUT = 16 * 1024 * 1024;
 const MAX_STDIN = 1024 * 1024;
-const str = (v) => (typeof v === 'string' ? v : undefined);
+/** `--output-limit` of a file-first execution: 1 byte to 16 MiB per stream (cell-api.yaml output_limit_bytes). */
+const MAX_OUTPUT_LIMIT = 16 * 1024 * 1024;
+export const str = (v) => (typeof v === 'string' ? v : undefined);
 /**
  * The workspace's cell client as this invocation configures it: the CLI's agent label, wake on use unless turned off,
  * and the wake timeout (an OperationTimeoutError past it exits 5).
  */
 const cellOf = (ctx, ws) => ws.cell({ agentLabel: ctx.agentLabel, transitionTimeoutMs: ctx.wakeTimeoutMs, ...(ctx.wake ? {} : { wake: null }) });
-const strs = (v) => (Array.isArray(v) ? v : typeof v === 'string' ? [v] : []);
+export const strs = (v) => (Array.isArray(v) ? v : typeof v === 'string' ? [v] : []);
 const MAX_SECRET_VALUE_BYTES = 65_536;
+/** `files patch --content-file`: a patch request is at most 7 MiB (contracts §26.2); larger files go through `files write`. */
+const MAX_PATCH_CONTENT = 7 * 1024 * 1024;
+const STOPPED_AT = { max_matches: '--max matches', budget: 'its 10 s budget', max_bytes: '4 MiB of results' };
+/** A file revision (SHA-256 of the content) or `absent` (contracts §26.2). */
+const REVISION = /^([0-9a-f]{64}|absent)$/;
 const TOOLS = ['exec', 'files', 'pty', 'process', 'git', 'browser'];
 function secretNames(names, option) {
     for (const n of names)
@@ -41,7 +50,7 @@ function withTiming(ctx, machine) {
         return machine;
     return { ...machine, timing: timingJson(ctx.traces.last) };
 }
-function out(ctx, human, machine) {
+export function out(ctx, human, machine) {
     ctx.io.stdout.write(ctx.json ? json(withTiming(ctx, machine)) : human);
 }
 function caps(values) {
@@ -57,7 +66,17 @@ function caps(values) {
         c.disk_gib = parsePositiveInt(disk, 'disk-gib', 1_000_000);
     return Object.keys(c).length ? c : undefined;
 }
-function waitTimeout(values) {
+/** `--when-idle <duration>`: whole seconds from 30 to 3600 (the API's after_seconds bounds, contracts §20.6). */
+export function whenIdleSeconds(text) {
+    const ms = parseDuration(text, 'when-idle');
+    if (ms % 1000 !== 0)
+        throw new UsageError('--when-idle must be a whole number of seconds (e.g. 30s, 90s, 2m)');
+    const s = ms / 1000;
+    if (s < 30 || s > 3600)
+        throw new UsageError(`--when-idle must be between 30s and 1h (got "${text}")`);
+    return s;
+}
+export function waitTimeout(values) {
     const t = str(values.timeout);
     return t === undefined ? DEFAULT_WAIT_MS : parseDuration(t, 'timeout');
 }
@@ -96,7 +115,7 @@ const PURPOSE_FILTERS = ['standard', 'template_draft', 'template_test', 'any'];
 const DIFF_CHANGES = ['added', 'removed', 'changed', 'type_changed', 'metadata'];
 const OWNERS = ['platform', 'organization'];
 const DEFAULT_BUILD_WAIT_MS = 1_800_000;
-function oneOf(values, option, allowed) {
+export function oneOf(values, option, allowed) {
     const v = str(values[option]);
     if (v === undefined)
         return undefined;
@@ -104,7 +123,7 @@ function oneOf(values, option, allowed) {
         throw new UsageError(`--${option} must be one of ${allowed.join(', ')} (got "${v}")`);
     return v;
 }
-function listLimit(values, max) {
+export function listLimit(values, max) {
     const t = str(values.limit);
     return t === undefined ? undefined : parsePositiveInt(t, 'limit', max);
 }
@@ -160,7 +179,7 @@ function parseVersion(text, what) {
 }
 const SLUG = /^[a-z0-9](?:[a-z0-9._-]{0,98}[a-z0-9])?$/;
 /** `<slug>@<version>`. */
-function parseSlugVersion(text, what) {
+export function parseSlugVersion(text, what) {
     const at = text.lastIndexOf('@');
     if (at <= 0)
         throw new UsageError(`${what} must be <slug>@<version>, e.g. acme-dev@3 (got "${text}")`);
@@ -230,7 +249,7 @@ const BUILD_STATES = ['queued', 'building', 'testing', 'publishing', 'published'
 function buildExitCode(b) {
     return b.state === 'failed' || b.state === 'canceled' || b.registration.state === 'failed' ? 6 : 0;
 }
-async function fileExists(path) {
+export async function fileExists(path) {
     return access(path).then(() => true, () => false);
 }
 /** Writes `text` to `path`, refusing to overwrite an existing file without --force. */
@@ -283,7 +302,7 @@ async function readAll(stream, max, what) {
     }
     return new Uint8Array(Buffer.concat(chunks));
 }
-async function readInput(ctx, source, max, what) {
+export async function readInput(ctx, source, max, what) {
     if (source === '-') {
         if (ctx.io.stdin.isTTY)
             throw new UsageError(`${what}: standard input is a terminal; pipe data in or pass a file`);
@@ -296,7 +315,7 @@ async function readInput(ctx, source, max, what) {
         throw new UsageError(`${what} exceeds ${max} bytes`);
     return new Uint8Array(data);
 }
-async function principal(ctx) {
+export async function principal(ctx) {
     const me = await ctx.cloud().me();
     if (me.type !== 'api_key' || !me.api_key)
         throw new UsageError('SHARDFLUX_API_KEY did not authenticate as an API key');
@@ -317,6 +336,72 @@ function principalText(p) {
         ['tools', p.tool_permissions.length ? p.tool_permissions.join(', ') : '(none: read-only key)'],
     ]);
 }
+/**
+ * Who sends the feedback: the project API key when one is configured (SHARDFLUX_API_KEY or saved by shard setup),
+ * else the signed-in session (SHARDFLUX_SESSION_TOKEN or saved by shard auth login), so an agent that is still setting
+ * up can report what got in its way. With neither, the key's own error (its hint names both ways, plus email).
+ */
+function feedbackSender(ctx) {
+    const keyConfigured = Boolean(ctx.io.env.SHARDFLUX_API_KEY?.trim()) || ctx.store.profile(ctx.apiUrl).api_key !== undefined;
+    const sessionConfigured = Boolean(ctx.io.env.SHARDFLUX_SESSION_TOKEN?.trim()) || ctx.store.profile(ctx.apiUrl).session !== undefined;
+    return keyConfigured || !sessionConfigured ? ctx.cloud() : ctx.account();
+}
+/** Contract bounds of the feedback context fields shard sends (characters). */
+const FEEDBACK_CONTEXT_MAX = { workspace: 200, 'request-id': 200, 'error-code': 100, command: 2000 };
+/**
+ * The feedback message: the positional words joined with spaces, or --from-file (a file, or - for standard input),
+ * trimmed, 1-8000 characters (the API's bound, counted in UTF-16 units so nothing the API would refuse is sent).
+ */
+async function feedbackMessage(ctx, values, words) {
+    const file = str(values['from-file']);
+    if (file !== undefined && words.length > 0)
+        throw new UsageError('give the message as arguments or with --from-file, not both');
+    let text;
+    if (file !== undefined) {
+        const bytes = await readInput(ctx, file, MAX_STDIN, '--from-file');
+        try {
+            text = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+        }
+        catch {
+            throw new UsageError('--from-file: the message must be UTF-8 text');
+        }
+    }
+    else if (words.length > 0) {
+        text = words.join(' ');
+    }
+    else {
+        throw new UsageError('missing <message> for "shard feedback": shard feedback "what happened and what you expected" (or --from-file <file|->)');
+    }
+    text = text.trim();
+    if (text.length === 0)
+        throw new UsageError('the feedback message is empty');
+    if (text.length > FEEDBACK_MESSAGE_MAX_LENGTH) {
+        throw new UsageError(`the feedback message is ${text.length} characters; the limit is ${FEEDBACK_MESSAGE_MAX_LENGTH} (keep the relevant part, e.g. tail -n 100 of a log, or send it in two messages)`);
+    }
+    return text;
+}
+/** The context shard sends: its own client, the agent label when one is set, and the given references. */
+function feedbackContext(ctx, values) {
+    const c = { client: `shard-cli/${CLI_VERSION}` };
+    if (ctx.agentLabel !== 'cli')
+        c.agent = ctx.agentLabel;
+    for (const [option, max] of Object.entries(FEEDBACK_CONTEXT_MAX)) {
+        const v = str(values[option])?.trim();
+        if (v === undefined)
+            continue;
+        if (v.length === 0 || v.length > max)
+            throw new UsageError(`--${option} must be 1-${max} characters`);
+        if (option === 'workspace')
+            c.workspace = v;
+        else if (option === 'request-id')
+            c.requestId = v;
+        else if (option === 'error-code')
+            c.errorCode = v;
+        else
+            c.command = v;
+    }
+    return c;
+}
 /** The exit code `shard exec` returns for a finished command. */
 export function execExitCode(r) {
     if (r.timedOut)
@@ -330,14 +415,95 @@ export function execExitCode(r) {
 async function bestEffortCancel(cell, sessionId) {
     await Promise.race([cell.exec.cancel(sessionId).catch(() => undefined), new Promise((r) => setTimeout(r, 3_000).unref())]);
 }
+// ---- File-first workspaces (0.5.0; contracts §29) ----------------------------------------------------------------------
+const MODES = { processful: 'processful', 'file-first': 'file_first', file_first: 'file_first' };
+/** `--mode processful|file-first` (`file_first` too). */
+function modeFlag(values) {
+    const v = str(values.mode);
+    if (v === undefined)
+        return undefined;
+    const m = MODES[v];
+    if (!m)
+        throw new UsageError(`--mode must be processful or file-first (got "${v}")`);
+    return m;
+}
+const EXECUTION_ID_TEXT = '8-128 characters of A-Z a-z 0-9 . _ : -, starting with a letter or digit';
+/** `--if-revision <n>`: a tree revision, a non-negative integer (0 is the empty tree a file-first workspace starts with). */
+function ifRevision(values) {
+    const t = str(values['if-revision']);
+    if (t === undefined)
+        return undefined;
+    if (!/^\d{1,15}$/.test(t.trim()))
+        throw new UsageError(`--if-revision must be a tree revision, a non-negative integer (got "${t}")`);
+    return Number(t.trim());
+}
+/** Options that exist only for file-first workspaces are a usage error on a processful one (known once resolved). */
+function fileFirstOnly(ws, flags, note = '') {
+    if (flags.length === 0 || ws.mode === 'file_first')
+        return;
+    throw new UsageError(`${flags.join(' and ')} ${flags.length > 1 ? 'apply' : 'applies'} to file-first workspaces only; ${ws.key} is ${modeText(ws.mode)}${note}`);
+}
+/** The tree revision after a mutating files call on a file-first workspace (the newest its responses reported); else null. */
+function treeRevisionAfter(ws, cell) {
+    if (ws.mode !== 'file_first')
+        return null;
+    return cell.treeRevision ?? ws.treeRevision;
+}
+/**
+ * A lifecycle call a file-first workspace does not have (contracts §29.7: suspend, resume, fork, reset,
+ * save-as-template), refused before any request as the SDK's workspace handle does: NotSupportedForModeError, printed
+ * with its hint like the API's own refusal.
+ */
+function requireProcessful(ws, operation, what) {
+    if (ws.mode !== 'file_first')
+        return;
+    throw NotSupportedForModeError.local('file_first', operation, 'api', `${what} is not available for a file-first workspace: it has no VM between executions and is never suspended; its state is its file tree (revision ${ws.treeRevision ?? 0}).`);
+}
+/**
+ * Prints an execution's result and returns the exit code. Human: the command's stdout and stderr bytes as they are
+ * (binary safe), a note when output was cut at the output limit, and with `summary` what ran (stderr; see
+ * executionSummary). --json: one document (executionJson). The exit code is the command's once it succeeded (like a
+ * processful exec: 124 timed out, 128+N killed by signal N); a failed or lost execution throws ExecutionFailedError
+ * (exit 6), one still queued or running ExecutionPendingError (exit 5, naming the command that waits for it).
+ */
+function reportExecution(ctx, ref, r, opts) {
+    if (ctx.json)
+        ctx.io.stdout.write(json(withTiming(ctx, executionJson(r))));
+    else if (!r.pending) {
+        if (r.stdout.length)
+            ctx.io.stdout.write(r.stdout);
+        if (r.stderr.length)
+            ctx.io.stderr.write(r.stderr);
+        const cut = [r.stdoutTruncated ? 'stdout' : '', r.stderrTruncated ? 'stderr' : ''].filter(Boolean).join(' and ');
+        if (opts.summary)
+            ctx.io.stderr.write(executionSummary(r, undefined, opts.fetched ? { replayed: false } : {}));
+        else {
+            if (cut)
+                ctx.io.stderr.write(`truncated: ${cut} reached the output limit (--output-limit, default 1 MiB, at most 16 MiB)\n`);
+            if (opts.timings && Object.keys(r.timings).length)
+                ctx.io.stderr.write(`execution ${r.executionId} timings: ${pairs(r.timings)}\n`);
+        }
+    }
+    if (r.pending) {
+        const when = opts.waited ? `still ${r.state} after ${opts.waited}` : `${r.state} (on tree revision ${r.baseRevision})`;
+        throw new ExecutionPendingError(`Execution ${r.executionId} is ${when}; it continues server side.`, r, `wait for its result with: shard executions get ${ref} ${r.executionId} --wait 10m`);
+    }
+    if (r.state === 'failed' || r.state === 'lost')
+        throw new ExecutionFailedError(r);
+    return execExitCode(r);
+}
 function lifecycleText(verb, w, op) {
     const finished = op.state === 'succeeded' || op.state === 'failed' || op.state === 'canceled';
     return `${verb} ${w.key} (${w.id}): operation ${op.id} ${op.kind} ${op.state}${op.state_reason ? ` (${op.state_reason})` : ''}\n${finished ? '' : `wait with: shard operations wait ${op.id}\n`}`;
 }
-export const HANDLERS = {
+/** The project-key commands; handlers.ts adds the account plane's. */
+export const KEY_HANDLERS = {
     async login(ctx) {
         const p = await principal(ctx);
-        out(ctx, `Authenticated.\n${principalText(p)}shard stores nothing; it reads SHARDFLUX_API_KEY on every run.\n`, p);
+        const where = ctx.apiKey().source === 'env'
+            ? 'The key comes from SHARDFLUX_API_KEY; shard stores nothing for it.'
+            : `The key is the one saved in ${ctx.store.file} (shard setup).`;
+        out(ctx, `Authenticated.\n${principalText(p)}${where} To sign in to your account instead: shard auth login.\n`, p);
         return 0;
     },
     async whoami(ctx) {
@@ -345,14 +511,54 @@ export const HANDLERS = {
         out(ctx, principalText(p), p);
         return 0;
     },
-    version(ctx) {
-        out(ctx, `shard ${CLI_VERSION} (@shardflux/sdk ${SDK_VERSION})\n`, { cli: CLI_VERSION, sdk: SDK_VERSION });
-        return Promise.resolve(0);
+    async version(ctx, values) {
+        const update = await ctx.versionStatus(values.check === true);
+        const line = update === null && updateCheckDisabled(ctx.io.env) ? 'update check: off (SHARDFLUX_NO_UPDATE_CHECK or NO_UPDATE_NOTIFIER; shard version --check asks anyway)\n' : updateLine(update, ctx.distribution);
+        out(ctx, `shard ${CLI_VERSION} (@shardflux/sdk ${SDK_VERSION})\n${line}`, { cli: CLI_VERSION, sdk: SDK_VERSION, update });
+        return 0;
+    },
+    // Feedback (0.5.0+): POST /v1/feedback, emailed to the founder. Validated here first so a bad call costs no request.
+    async feedback(ctx, values, words) {
+        const category = oneOf(values, 'category', FEEDBACK_CATEGORIES);
+        const context = feedbackContext(ctx, values);
+        const message = await feedbackMessage(ctx, values, words);
+        const r = await feedbackSender(ctx).sendFeedback({ message, ...(category ? { category } : {}), context });
+        const human = r.duplicate
+            ? `Already received: the same message was sent in the last 24 hours (feedback ${r.id}); not emailed again.\n`
+            : `Sent to the Shardflux founder (feedback ${r.id}). Thank you.\n`;
+        out(ctx, human, { id: r.id, received_at: r.receivedAt, duplicate: r.duplicate });
+        return 0;
     },
     async usage(ctx, values) {
+        const views = [values.estimate === true, values.series === true, str(values.workspace) !== undefined].filter(Boolean).length;
+        if (views > 1)
+            throw new UsageError('use one of --estimate, --series and --workspace');
+        const seriesOnly = ['from', 'to', 'granularity', 'meter'].filter((k) => values[k] !== undefined);
+        if (seriesOnly.length > 0 && values.series !== true && str(values.workspace) === undefined) {
+            throw new UsageError(`--${seriesOnly[0]} needs --series or --workspace`);
+        }
+        const granularity = values.granularity === undefined ? undefined : oneOf(values, 'granularity', ['hour', 'day']);
+        const range = { from: str(values.from), to: str(values.to), granularity, meter: str(values.meter) };
+        const workspaceRef = str(values.workspace);
+        if (workspaceRef !== undefined) {
+            const ws = await resolveWorkspace(ctx, workspaceRef);
+            const series = await ctx.cloud().usage.workspace(ws.id, range);
+            out(ctx, usageSeriesText(series), series);
+            return 0;
+        }
         const org = str(values.org) ?? (await principal(ctx)).organization_id;
         if (!UUID.test(org))
             throw new UsageError(`--org must be an organization id (UUID)`);
+        if (values.estimate === true) {
+            const estimate = await ctx.cloud().usage.estimate(org);
+            out(ctx, usageEstimateText(estimate), estimate);
+            return 0;
+        }
+        if (values.series === true) {
+            const series = await ctx.cloud().usage.series(org, range);
+            out(ctx, usageSeriesText(series), series);
+            return 0;
+        }
         const summary = await ctx.cloud().request('GET', `/v1/organizations/${encodeURIComponent(org)}/usage/summary`);
         out(ctx, usageText(summary), summary);
         return 0;
@@ -364,6 +570,9 @@ export const HANDLERS = {
         const c = caps(values);
         const bind = secretNames(strs(values.secret), '--secret');
         const lifetime = oneOf(values, 'lifetime', LIFETIMES);
+        const mode = modeFlag(values);
+        if (mode === 'file_first' && lifetime === 'session')
+            throw new UsageError('a file-first workspace is persistent: --lifetime session is for processful workspaces');
         const inputs = await inputsFrom(ctx, values);
         const timeoutMs = waitTimeout(values);
         const cloud = ctx.cloud();
@@ -376,6 +585,7 @@ export const HANDLERS = {
             ...(bind.length ? { secrets: bind } : {}),
             ...(inputs ? { inputs } : {}),
             ...(lifetime ? { lifetime } : {}),
+            ...(mode ? { mode } : {}),
             agentLabel: ctx.agentLabel,
             wait: values.wait === false ? false : { timeoutMs, signal: ctx.signal },
         }));
@@ -438,16 +648,49 @@ export const HANDLERS = {
         const env = parseEnvPairs(values.env ?? []);
         const timeout = str(values.timeout);
         const timeoutMs = timeout === undefined ? undefined : parseDuration(timeout, 'timeout');
+        const executionId = str(values['execution-id']);
+        if (executionId !== undefined && !EXECUTION_ID.test(executionId))
+            throw new UsageError(`--execution-id must be ${EXECUTION_ID_TEXT} (got "${executionId}")`);
+        const limitText = str(values['output-limit']);
+        const outputLimit = limitText === undefined ? undefined : parsePositiveInt(limitText, 'output-limit', MAX_OUTPUT_LIMIT);
         const stdinSource = str(values.stdin);
         const stdin = stdinSource === undefined ? undefined : await readInput(ctx, stdinSource, MAX_STDIN, '--stdin');
         const ws = await resolveWorkspace(ctx, ref);
         const cell = cellOf(ctx, ws);
+        const cwd = str(values.cwd);
+        if (ws.mode === 'file_first') {
+            // An execution (contracts §29.8): answered when the command ended. The id is ours, so Ctrl-C can name it.
+            const id = executionId ?? newExecutionId();
+            let r;
+            try {
+                r = await cell.executions.run(argv, {
+                    executionId: id,
+                    ...(cwd !== undefined ? { cwd } : {}),
+                    ...(Object.keys(env).length ? { env } : {}),
+                    ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+                    ...(stdin !== undefined ? { stdin } : {}),
+                    ...(outputLimit !== undefined ? { outputLimitBytes: outputLimit } : {}),
+                    signal: ctx.signal,
+                });
+            }
+            catch (err) {
+                if (ctx.signal.aborted) {
+                    throw new InterruptedError(`Interrupted; execution ${id} keeps running server side if it started (an execution cannot be canceled).`, undefined, {
+                        executionId: id,
+                        hint: `fetch its result later with: shard executions get ${ref} ${id}`,
+                    });
+                }
+                throw err;
+            }
+            return reportExecution(ctx, ref, r, { summary: values.verbose === true, timings: ctx.timing });
+        }
+        fileFirstOnly(ws, [...(executionId !== undefined ? ['--execution-id'] : []), ...(outputLimit !== undefined ? ['--output-limit'] : [])]);
         const sessionId = `cli-${randomUUID().replace(/-/g, '').slice(0, 24)}`;
         let r;
         try {
             r = await cell.exec.run(argv, {
                 sessionId,
-                ...(str(values.cwd) !== undefined ? { cwd: str(values.cwd) } : {}),
+                ...(cwd !== undefined ? { cwd } : {}),
                 ...(Object.keys(env).length ? { env } : {}),
                 ...(timeoutMs !== undefined ? { timeoutMs } : {}),
                 ...(stdin !== undefined ? { stdin } : {}),
@@ -464,8 +707,30 @@ export const HANDLERS = {
             throw err;
         }
         const code = execExitCode(r);
+        // No exit code, no timeout, no signal: the session ended without the command's own ending (e.g. lost when its host
+        // restarted). Say so rather than exit 1 in silence (0.5.1); a command that could not start threw ExecStartError.
+        const unexplained = r.exitCode === null && !r.timedOut && !(r.termSignal !== null && r.termSignal > 0);
+        if (values.verbose === true && !ctx.json) {
+            const status = r.timedOut ? 'timed out' : r.canceled ? 'canceled' : r.termSignal ? `killed by signal ${r.termSignal}` : unexplained ? r.session.state : `exit code ${r.exitCode ?? '-'}`;
+            ctx.io.stderr.write(kv([['session', r.sessionId], ['status', status], ['output', `${r.stdoutBytes} bytes stdout, ${r.stderrBytes} bytes stderr`], ['reconnects', String(r.reconnects)]]));
+        }
         if (ctx.json) {
-            ctx.io.stdout.write(json(withTiming(ctx, { session_id: r.sessionId, exit_code: r.exitCode, term_signal: r.termSignal, timed_out: r.timedOut, canceled: r.canceled, stdout: r.stdout, stderr: r.stderr, truncated: r.truncated, reconnects: r.reconnects })));
+            ctx.io.stdout.write(json(withTiming(ctx, {
+                session_id: r.sessionId,
+                state: r.session.state,
+                exit_code: r.exitCode,
+                term_signal: r.termSignal,
+                timed_out: r.timedOut,
+                canceled: r.canceled,
+                stdout: r.stdout,
+                stderr: r.stderr,
+                truncated: r.truncated,
+                reconnects: r.reconnects,
+                ...(r.session.error ? { error: r.session.error } : {}),
+            })));
+        }
+        else if (unexplained) {
+            ctx.io.stderr.write(`exec session ${r.sessionId} ended ${r.session.state} without an exit code${r.session.error ? `: ${r.session.error}` : ''}\n`);
         }
         return code;
     },
@@ -486,10 +751,15 @@ export const HANDLERS = {
         return 0;
     },
     async 'files write'(ctx, values, [ref, path]) {
+        const ifRev = ifRevision(values);
         const data = await readInput(ctx, str(values.from) ?? '-', 1024 * 1024 * 1024, 'input');
         const ws = await resolveWorkspace(ctx, ref);
-        const r = await cellOf(ctx, ws).files.write(path, data, { append: values.append === true, createParents: values.parents !== false });
-        out(ctx, `wrote ${r.bytes_written} bytes to ${r.path}${r.sha256 ? ` (sha256 ${r.sha256})` : ''}\n`, r);
+        fileFirstOnly(ws, ifRev !== undefined ? ['--if-revision'] : []);
+        const cell = cellOf(ctx, ws);
+        const r = await cell.files.write(path, data, { append: values.append === true, createParents: values.parents !== false, ...(ifRev !== undefined ? { ifTreeRevision: ifRev } : {}) });
+        // File-first: the tree revision the write published (or the current one when nothing changed), to chain --if-revision.
+        const tree = treeRevisionAfter(ws, cell);
+        out(ctx, `wrote ${r.bytes_written} bytes to ${r.path}${r.sha256 ? ` (sha256 ${r.sha256})` : ''}${tree !== null ? `, tree revision ${tree}` : ''}\n`, tree !== null ? { ...r, tree_revision: tree } : r);
         return 0;
     },
     async 'files ls'(ctx, values, [ref, path]) {
@@ -499,11 +769,113 @@ export const HANDLERS = {
         out(ctx, `${fileTable(list)}${list.truncated ? '(truncated)\n' : ''}`, list);
         return 0;
     },
+    async 'files stat'(ctx, values, [ref, path]) {
+        const ws = await resolveWorkspace(ctx, ref);
+        const info = await cellOf(ctx, ws).files.stat(path, values.revision === true ? { revision: true } : {});
+        out(ctx, fileInfoText(info), info);
+        return 0;
+    },
+    async 'files search'(ctx, values, [ref, path, pattern]) {
+        const maxText = str(values.max);
+        const include = strs(values.include);
+        const exclude = strs(values.exclude);
+        for (const g of [...include, ...exclude])
+            if (g.length === 0 || g.length > 256)
+                throw new UsageError('--include/--exclude globs must be 1-256 characters');
+        if (include.length > 32 || exclude.length > 32)
+            throw new UsageError('at most 32 --include and 32 --exclude globs');
+        if (pattern.length === 0 || pattern.length > 1000)
+            throw new UsageError('<pattern> must be 1-1000 characters');
+        const maxMatches = maxText === undefined ? undefined : parsePositiveInt(maxText, 'max', 5000);
+        const ws = await resolveWorkspace(ctx, ref);
+        const r = await cellOf(ctx, ws).files.search(path, pattern, {
+            ...(values.regex === true ? { regex: true } : {}),
+            ...(values['ignore-case'] === true ? { caseInsensitive: true } : {}),
+            ...(include.length ? { include } : {}),
+            ...(exclude.length ? { exclude } : {}),
+            ...(maxMatches !== undefined ? { maxMatches } : {}),
+            signal: ctx.signal,
+        });
+        out(ctx, searchText(r), r);
+        if (!ctx.json && r.truncated) {
+            const at = r.stop_reason ? ` at ${STOPPED_AT[r.stop_reason] ?? r.stop_reason}` : '';
+            const raise = r.stop_reason === undefined || r.stop_reason === 'max_matches' ? ' or raise --max' : '';
+            ctx.io.stderr.write(`truncated: the search stopped${at} after ${r.matches.length} matches (${r.files_scanned} files scanned); narrow it${raise}\n`);
+        }
+        if (!ctx.json && r.served_from === 'disk')
+            ctx.io.stderr.write('note: searched the suspended workspace’s disk (its state at suspension)\n');
+        return 0;
+    },
+    async 'files patch'(ctx, values, [ref, path]) {
+        const olds = strs(values.old);
+        const news = strs(values.new);
+        const contentFile = str(values['content-file']);
+        const expected = str(values['expected-revision']);
+        if (contentFile !== undefined && (olds.length || news.length))
+            throw new UsageError('use either --old/--new or --content-file, not both');
+        if (contentFile === undefined && olds.length === 0)
+            throw new UsageError('give --old <text> --new <text> (repeatable), or --content-file <file|->');
+        if (olds.length !== news.length)
+            throw new UsageError(`every --old needs a --new (got ${olds.length} --old and ${news.length} --new)`);
+        if (olds.some((o) => o.length === 0))
+            throw new UsageError('--old must not be empty');
+        if (olds.length > 100)
+            throw new UsageError('at most 100 --old/--new pairs');
+        if (contentFile !== undefined && values['replace-all'] === true)
+            throw new UsageError('--replace-all applies to --old/--new, not --content-file');
+        if (expected !== undefined && !REVISION.test(expected))
+            throw new UsageError('--expected-revision must be a 64-character lowercase SHA-256 hex revision or "absent"');
+        const ifRev = ifRevision(values);
+        let content;
+        if (contentFile !== undefined) {
+            const bytes = await readInput(ctx, contentFile, MAX_PATCH_CONTENT, '--content-file');
+            try {
+                content = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+            }
+            catch {
+                throw new UsageError('--content-file must be UTF-8 text (files patch edits text; use files write for binary data)');
+            }
+        }
+        const ws = await resolveWorkspace(ctx, ref);
+        fileFirstOnly(ws, ifRev !== undefined ? ['--if-revision'] : [], ' (--expected-revision checks the file’s own revision in any workspace)');
+        const cell = cellOf(ctx, ws);
+        const common = { path: path, ...(expected !== undefined ? { expectedRevision: expected } : {}) };
+        const opts = { signal: ctx.signal, ...(ifRev !== undefined ? { ifTreeRevision: ifRev } : {}) };
+        const r = content !== undefined
+            ? await cell.files.patch({ ...common, content }, opts)
+            : await cell.files.patch({ ...common, edits: olds.map((o, i) => ({ oldText: o, newText: news[i], ...(values['replace-all'] === true ? { replaceAll: true } : {}) })) }, opts);
+        const what = r.replacements !== undefined ? `${r.replacements} replacement${r.replacements === 1 ? '' : 's'}` : `${r.bytes_written} bytes`;
+        const tree = treeRevisionAfter(ws, cell);
+        out(ctx, `patched ${r.path}: ${what}, revision ${r.revision}${tree !== null ? `, tree revision ${tree}` : ''}\n`, tree !== null ? { ...r, tree_revision: tree } : r);
+        return 0;
+    },
     async 'workspaces suspend'(ctx, values, [ref]) {
-        return lifecycle(ctx, values, ref, 'Suspending', (ws, o) => ctx.cloud().workspaces.suspend(ws.id, o));
+        const whenIdle = str(values['when-idle']);
+        const cancel = values['cancel-when-idle'] === true;
+        if (whenIdle === undefined && !cancel)
+            return lifecycle(ctx, values, ref, 'Suspending', (ws, o) => ctx.cloud().workspaces.suspend(ws.id, o), ['suspend', 'Suspend']);
+        if (whenIdle !== undefined && cancel)
+            throw new UsageError('--when-idle and --cancel-when-idle cannot be combined');
+        const flag = cancel ? '--cancel-when-idle' : '--when-idle';
+        if (values.wait === true || str(values.timeout) !== undefined)
+            throw new UsageError(`${flag} cannot be combined with --wait or --timeout (nothing is suspended now)`);
+        if (cancel) {
+            const ws = await resolveWorkspace(ctx, ref);
+            const pending = ws.suspendRequest;
+            const after = await ctx.cloud().workspaces.cancelSuspendWhenIdle(ws.id);
+            out(ctx, pending ? `Canceled the pending suspend-when-idle request of ${ws.key} (${ws.id}): ${suspendRequestText(pending)}.\n` : `No suspend-when-idle request was pending for ${ws.key} (${ws.id}).\n`, after.data);
+            return 0;
+        }
+        const afterSeconds = whenIdleSeconds(whenIdle);
+        const ws = await resolveWorkspace(ctx, ref);
+        requireProcessful(ws, 'suspend_when_idle', 'Suspend when idle');
+        const r = await ctx.cloud().workspaces.suspendWhenIdle(ws.id, { afterSeconds });
+        out(ctx, suspendWhenIdleText(ws, { suspend_request: r.suspendRequest, operation: r.operation }), { workspace: r.workspace.data, operation: r.operation, suspend_request: r.suspendRequest });
+        return 0;
     },
     async 'workspaces resume'(ctx, values, [ref]) {
-        return lifecycle(ctx, values, ref, 'Resuming', (ws, o) => ctx.cloud().workspaces.resume(ws.id, o));
+        // With --wait the resume is held until the workspace runs (contracts §22.6); its tool token is the CLI's label.
+        return lifecycle(ctx, values, ref, 'Resuming', (ws, o) => ctx.cloud().workspaces.resume(ws.id, { ...o, agentLabel: ctx.agentLabel }), ['resume', 'Resume']);
     },
     async 'workspaces delete'(ctx, values, [ref]) {
         if (values.yes !== true)
@@ -516,7 +888,7 @@ export const HANDLERS = {
     async 'workspaces reset'(ctx, values, [ref]) {
         if (values.yes !== true)
             throw new UsageError('refusing to reset without --yes (reset wipes every change in the workspace and restarts it on its template)');
-        return lifecycle(ctx, values, ref, 'Resetting', (ws, o) => ctx.cloud().workspaces.reset(ws.id, o));
+        return lifecycle(ctx, values, ref, 'Resetting', (ws, o) => ctx.cloud().workspaces.reset(ws.id, o), ['reset', 'Reset']);
     },
     async 'workspaces save-as-template'(ctx, values, [ref]) {
         const template = str(values.template);
@@ -528,6 +900,7 @@ export const HANDLERS = {
         const defaults = saveDefaults(values);
         const ack = acknowledged(values);
         const ws = await resolveWorkspace(ctx, ref);
+        requireProcessful(ws, 'save_as_template', 'Saving as a template');
         const res = await ctx.cloud().workspaces.saveAsTemplate(ws.id, {
             templateSlug: template,
             ...(str(values['display-name']) !== undefined ? { displayName: str(values['display-name']) } : {}),
@@ -1004,6 +1377,7 @@ export const HANDLERS = {
         const c = caps(values);
         const timeoutMs = waitTimeout(values);
         const source = await resolveWorkspace(ctx, ref);
+        requireProcessful(source, 'fork', 'A fork');
         const res = await waited(ctx, 'the fork continues server side.', () => ctx.cloud().workspaces.fork(source.id, { key: newKey, ...(c ? { caps: c } : {}) }, lifecycleOptions(ctx, values, timeoutMs)));
         const op = res.operation;
         out(ctx, lifecycleText(`Forking ${source.key} into`, res.workspace, op), { operation: op, workspace: res.workspace.data });
@@ -1154,7 +1528,41 @@ export const HANDLERS = {
         out(ctx, operationDetail(op), op);
         return 0;
     },
+    async 'executions get'(ctx, values, [ref, id]) {
+        if (!EXECUTION_ID.test(id))
+            throw new UsageError(`<execution-id> must be ${EXECUTION_ID_TEXT} (got "${id}")`);
+        const waitText = str(values.wait);
+        const waitMs = waitText === undefined ? 0 : parseDuration(waitText, 'wait');
+        const ws = await resolveWorkspace(ctx, ref);
+        let r;
+        try {
+            r = await cellOf(ctx, ws).executions.get(id, { waitMs, signal: ctx.signal });
+        }
+        catch (err) {
+            if (ctx.signal.aborted)
+                throw new InterruptedError(`Interrupted; execution ${id} continues server side.`, undefined, { executionId: id, hint: `fetch its result later with: shard executions get ${ref} ${id}` });
+            throw err;
+        }
+        return reportExecution(ctx, ref, r, { summary: true, timings: false, fetched: true, ...(waitText !== undefined ? { waited: waitText } : {}) });
+    },
 };
+/** The update line of `shard version`. */
+function updateLine(u, d) {
+    const pkg = d.package === '@shardflux/cli' ? '' : ` (${d.package} ${d.version})`;
+    if (!u)
+        return `update check: not done yet${pkg} (shard version --check asks now)\n`;
+    const when = u.checked_at ? `, checked ${u.checked_at.slice(0, 19).replace('T', ' ')}Z` : '';
+    switch (u.status) {
+        case 'current':
+            return `up to date${pkg}: latest ${u.latest ?? '-'}${when}\n`;
+        case 'outdated':
+            return `update available${pkg}: ${u.latest} (you have ${u.current}). Update: ${u.upgrade_command ?? '-'}\n`;
+        case 'unsupported':
+            return `no longer supported${pkg}: the API needs ${u.minimum_supported} or later (latest ${u.latest ?? '-'}). Update: ${u.upgrade_command ?? '-'}\n`;
+        default:
+            return `update status unknown${pkg}${when} (the API could not be asked, or has no release of ${u.package} yet)\n`;
+    }
+}
 /** `--org <id>`: organization scope; null: the API key's project. */
 function scopeFlag(values) {
     const org = str(values.org);
@@ -1262,9 +1670,11 @@ async function resolveSecret(ctx, values, ref) {
 function lifecycleOptions(ctx, values, timeoutMs) {
     return values.wait === true ? { wait: { timeoutMs, signal: ctx.signal } } : {};
 }
-async function lifecycle(ctx, values, ref, verb, start) {
+async function lifecycle(ctx, values, ref, verb, start, processfulOnly) {
     const timeoutMs = waitTimeout(values);
     const ws = await resolveWorkspace(ctx, ref);
+    if (processfulOnly)
+        requireProcessful(ws, processfulOnly[0], processfulOnly[1]);
     const op = await waited(ctx, 'the operation continues server side.', () => start(ws, lifecycleOptions(ctx, values, timeoutMs)));
     out(ctx, lifecycleText(verb, ws, op), op);
     return 0;