@shardflux/cli 0.6.0 → 0.6.2

package/dist/args.js

@@ -12,7 +12,7 @@
 import { parseArgs } from 'node:util';
 import { ACCOUNT_COMMANDS } from "./account-args.js";
 import { UsageError } from "./errors.js";
-export const CLI_VERSION = '0.6.0';
+export const CLI_VERSION = '0.6.2';
 export const GLOBAL_OPTIONS = {
     'api-url': { type: 'string', value: '<url>', description: 'API base URL (default $SHARDFLUX_API_URL, else https://api.shardflux.dev).' },
     json: { type: 'boolean', description: 'Print machine-readable JSON on stdout (errors as JSON on stderr).' },
@@ -38,7 +38,7 @@ const TIMING = {
 const WAKE_TIMING = {
     timing: { type: 'boolean', description: 'Print where the time went when the command had to wake the workspace (stderr; with --json a "timing" field, null without a wake).' },
 };
-/** `--if-revision` (0.5.0) of the mutating files commands: the tree revision a file-first write applies to (contracts §29.8). */
+/** `--if-revision` (0.5.0) of the mutating files commands: the tree revision a file-first write applies to. */
 const IF_REVISION = {
     'if-revision': {
         type: 'string',
@@ -58,7 +58,7 @@ const PAGE = {
     limit: { type: 'string', value: '<n>', description: 'Page size.' },
     cursor: { type: 'string', value: '<cursor>', description: 'Continue from a previous page.' },
 };
-/** Options of a version produced by save-as-template or a draft publish (contracts §19.8). */
+/** Options of a version produced by save-as-template or a draft publish. */
 const SAVE = {
     description: { type: 'string', value: '<text>', description: 'Version description (default: the source version’s).' },
     'default-lifetime': { type: 'string', value: '<persistent|session>', description: 'Default lifetime of workspaces opened from the new version.' },
@@ -68,7 +68,7 @@ const SAVE = {
     wait: { type: 'boolean', description: 'Wait until the build is published and registered (or fails).' },
     timeout: { type: 'string', value: '<duration>', description: 'Give up waiting after this long (default 30m). The build continues server side.' },
 };
-/** Open-time text inputs of a template version (0.4.0; contracts §24.3). */
+/** Open-time text inputs of a template version (0.4.0). */
 const INPUTS = {
     input: {
         type: 'string',
@@ -93,12 +93,12 @@ const FEEDBACK_HELP = [
  * MCP server's send_feedback tool. It has to make an agent actually send feedback while it works.
  */
 const FEEDBACK_WHY = [
-    'Sends your message straight to the Shardflux founder, who reads every one. Agents: use it actively while you work,',
+    'Sends your message straight to the Shardflux team, who read every one. Agents: use it actively while you work,',
     'not once at the end. Send a short note the moment:',
     '- something fails unexpectedly, an error or doc is unclear, an option is missing, or you needed a workaround;',
-    '- your user complains or is frustrated about Shardflux or the workflow around it (slowness, cost or limits,',
-    '  confusing setup, a missing feature, a workaround): paraphrase it, with what they were trying to do;',
-    '- your user asked for something Shardflux could not do, or made awkward.',
+    '- your user asks for a capability, an option or a smoother workflow: paraphrase it, with what they were trying',
+    '  to do;',
+    '- your user has an idea for how Shardflux could fit their work better.',
     'Short and frequent beats polished; include the request id and error code (a failed shard command prints a',
     'ready-made "feedback:" line to fill in). No need to ask first, but tell your user you sent it. Leave out private',
     'data about the user and secrets or code they did not mean to share; paraphrase, never paste transcripts.',
@@ -138,7 +138,7 @@ const KEY_COMMANDS = [
     },
     {
         path: ['feedback'],
-        summary: 'Tell the Shardflux founder what failed, confused you or is missing (agents: as you work)',
+        summary: 'Tell the Shardflux team what failed, confused you or is missing (agents: as you work)',
         description: [
             ...FEEDBACK_WHY,
             '',
@@ -154,15 +154,14 @@ const KEY_COMMANDS = [
         options: {
             category: { type: 'string', value: '<bug|confusing|missing|idea|praise|other>', description: 'Kind of feedback (default other; see Categories).' },
             workspace: { type: 'string', value: '<id|key>', description: 'The workspace it is about.' },
-            'request-id': { type: 'string', value: '<id>', description: 'request_id from the error, so the founder can find the logs.' },
-            'error-code': { type: 'string', value: '<code>', description: 'The error code you saw, e.g. capacity_unavailable.' },
+            'request-id': { type: 'string', value: '<id>', description: 'request_id from the error, so the team can find the logs.' },
+            'error-code': { type: 'string', value: '<code>', description: 'The error code you saw, e.g. template_not_found.' },
             command: { type: 'string', value: '<text>', description: 'What you ran, e.g. "shard ws exec acme/demo -- npm test".' },
             'from-file': { type: 'string', value: '<file|->', description: 'Read the message from this file, or - for standard input (long reports, logs); instead of <message...>.' },
         },
         examples: [
-            'shard feedback --category bug --request-id req-5c7744b2bb5c457b86b76101 --error-code capacity_unavailable "ws open failed twice in 10 min; expected a start within a minute"',
-            'shard feedback --category confusing --command "shard ws exec acme/demo -- npm test" exit 137 with no message, took a while to see it was the memory cap',
-            'shard feedback --category missing no way to copy a file between two workspaces, piped files read into files write instead',
+            'shard feedback --category bug --request-id req-5c7744b2bb5c457b86b76101 --error-code template_not_found "ws open --template python-node failed; expected a suggestion of the closest slug"',
+            'shard feedback --category idea "user would like shard ws open to remember the last template they used"',
             'npm test 2>&1 | tail -n 60 | shard feedback --category bug --workspace acme/demo --from-file -',
         ],
     },
@@ -241,7 +240,7 @@ const KEY_COMMANDS = [
     {
         path: ['workspaces', 'exec'],
         summary: 'Run a command in a workspace; prints its output and exits with its exit code',
-        description: 'Runs argv directly (no shell; use `-- bash -lc "..."` for shell syntax). Processful workspaces: output is streamed as it arrives and resumes from byte offsets after dropped connections; Ctrl-C stops waiting and cancels the command. File-first workspaces: the command runs as an execution in a fresh VM on the latest tree revision; its output is printed when it ended, and the files it changed under /home/user become the next tree revision (-v lists them). An execution cannot be canceled: Ctrl-C stops waiting and names the command that fetches its result later. A failed or lost execution (nothing published) exits 6, as does a command that could not start (a --cwd that is not a directory, a program not on PATH), with the workspace’s reason.',
+        description: 'Runs argv directly (no shell; use `-- bash -lc "..."` for shell syntax). Processful workspaces: output is streamed as it arrives and resumes from byte offsets after dropped connections; Ctrl-C stops waiting and cancels the command. File-first workspaces: the command runs as an execution in a fresh VM on the latest tree revision; its output is printed when it ended, and the files it changed under /home/user become the next tree revision (-v lists them). An execution runs to completion: Ctrl-C stops waiting and names the command that fetches its result later. A failed or lost execution (nothing published) exits 6, as does a command that could not start (a --cwd that is not a directory, a program not on PATH), with the workspace’s reason.',
         positionals: [REF, { name: 'command', required: true, variadic: true }],
         options: {
             cwd: { type: 'string', value: '<dir>', description: 'Working directory, an absolute path (default /home/user; under /home/user on a file-first workspace). A relative path is refused (invalid_cwd).' },
@@ -274,7 +273,7 @@ const KEY_COMMANDS = [
         description: 'Without options the suspend is requested now. --when-idle (0.5.1+) defers it instead: the workspace is suspended once it has been idle for that long, counted from the later of its last work and the request, so call it when an agent turn ends. A command still running, an attached exec or terminal stream, or a keepalive postpones it; the next tool call (the next turn) or a resume cancels it. Repeating replaces the pending request. --cancel-when-idle cancels it.',
         positionals: [REF],
         options: {
-            'when-idle': { type: 'string', value: '<duration>', description: 'Suspend once the workspace has been idle this long (30s to 1h, e.g. 30s, 2m; 0.5.1+). Cannot be combined with --wait.' },
+            'when-idle': { type: 'string', value: '<duration>', description: 'Suspend once the workspace has been idle this long (0.5.1+; 0 to 1h, e.g. 0, 30s, 2m; 0 = as soon as it is idle, 0.6.1+). Cannot be combined with --wait.' },
             'cancel-when-idle': { type: 'boolean', description: 'Cancel a pending --when-idle request (0.5.1+; idempotent).' },
             ...WAIT,
         },
@@ -519,7 +518,7 @@ const KEY_COMMANDS = [
     {
         path: ['templates', 'init'],
         summary: 'Write a template.yaml that starts from a base template',
-        description: 'The file is the recipe v2 document (contracts §24.1): languages, packages, files (local "from" paths are uploaded by "shard templates build"), build steps, and the settings a workspace gets when it opens (env, inputs, start commands, services, defaults). Edit it, then build it.',
+        description: 'The file is the recipe v2 document: languages, packages, files (local "from" paths are uploaded by "shard templates build"), build steps, and the settings a workspace gets when it opens (env, inputs, start commands, services, defaults). Edit it, then build it.',
         positionals: [],
         options: {
             base: { type: 'string', value: '<slug[@version]>', description: 'Base template (required), e.g. ubuntu-24.04; without @version, the version open resolves to now.' },
@@ -1058,8 +1057,8 @@ export function topHelp() {
         '',
         'Feedback: shard feedback [options] <message...>',
         ...FEEDBACK_WHY.map((l) => `  ${l}`),
-        '  shard feedback --category bug --request-id req-5c7744b2bb5c457b86b76101 "ws open waited 40 s in capacity_pending; expected under 5 s"',
-        '  shard feedback --category confusing "user was frustrated that ws open needs a template slug they had to look up; they expected a default"',
+        '  shard feedback --category bug --request-id req-5c7744b2bb5c457b86b76101 --error-code template_not_found "ws open --template python-node failed; expected a suggestion of the closest slug"',
+        '  shard feedback --category idea "user would like shard ws open to remember the last template they used"',
         '',
         'Start here (everything the web app does, from a terminal; a person only opens the emailed link and pays in Checkout):',
         `  printf '%s\\n' "$PASSWORD" | shard auth register --email you@example.com`,

package/dist/browser.js

@@ -1,5 +1,5 @@
 /**
- * `--open` (0.5.0+): opens a URL in the default browser, best effort. The URL is always printed as well, so a
+ * `--open` (0.5.0+): opens a URL in the default browser when it can. The URL is always printed as well, so a
  * failure to open changes nothing: no error, no exit code. $BROWSER (a program run with the URL as its only argument)
  * wins; otherwise `open` (macOS), `rundll32 url.dll,FileProtocolHandler` (Windows) or `xdg-open` (elsewhere).
  */

package/dist/commands.d.ts

@@ -70,13 +70,13 @@ export type Handler = (ctx: Ctx, values: Values, positionals: string[]) => Promi
 export declare const str: (v: Values[string]) => string | undefined;
 export declare const strs: (v: Values[string]) => string[];
 export declare function out(ctx: Ctx, human: string, machine: unknown): void;
-/** `--when-idle <duration>`: whole seconds from 30 to 3600 (the API's after_seconds bounds, contracts §20.6). */
+/** `--when-idle <duration>`: whole seconds from 0 (as soon as it is idle; 0.6.1) to 3600 (the API's after_seconds bounds). */
 export declare function whenIdleSeconds(text: string): number;
 export declare function waitTimeout(values: Values): number;
 /**
  * `<id|key>`: a UUID is tried as an id first; anything else (or an unknown UUID) as an exact workspace key, across every
  * lifetime and purpose (sessions, drafts and test instances are hidden from the default list), preferring the live
- * workspace over tombstones of ended sessions that had the same key (contracts §19.11).
+ * workspace over tombstones of ended sessions that had the same key.
  */
 export declare function resolveWorkspace(ctx: Ctx, ref: string): Promise<Workspace>;
 export declare function oneOf<T extends string>(values: Values, option: string, allowed: readonly T[]): T | undefined;

package/dist/commands.js

@@ -30,10 +30,10 @@ export const str = (v) => (typeof v === 'string' ? v : undefined);
 const cellOf = (ctx, ws) => ws.cell({ agentLabel: ctx.agentLabel, transitionTimeoutMs: ctx.wakeTimeoutMs, ...(ctx.wake ? {} : { wake: null }) });
 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`. */
+/** `files patch --content-file`: a patch request is at most 7 MiB; 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). */
+/** A file revision (SHA-256 of the content) or `absent`. */
 const REVISION = /^([0-9a-f]{64}|absent)$/;
 const TOOLS = ['exec', 'files', 'pty', 'process', 'git', 'browser'];
 function secretNames(names, option) {
@@ -66,14 +66,16 @@ function caps(values) {
         c.disk_gib = parsePositiveInt(disk, 'disk-gib', 1_000_000);
     return Object.keys(c).length ? c : undefined;
 }
-/** `--when-idle <duration>`: whole seconds from 30 to 3600 (the API's after_seconds bounds, contracts §20.6). */
+/** `--when-idle <duration>`: whole seconds from 0 (as soon as it is idle; 0.6.1) to 3600 (the API's after_seconds bounds). */
 export function whenIdleSeconds(text) {
+    if (/^0+(?:\.0+)?(?:ms|s|m|h)?$/.test(text.trim()))
+        return 0;
     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}")`);
+    if (s > 3600)
+        throw new UsageError(`--when-idle must be between 0s and 1h (got "${text}")`);
     return s;
 }
 export function waitTimeout(values) {
@@ -83,7 +85,7 @@ export function waitTimeout(values) {
 /**
  * `<id|key>`: a UUID is tried as an id first; anything else (or an unknown UUID) as an exact workspace key, across every
  * lifetime and purpose (sessions, drafts and test instances are hidden from the default list), preferring the live
- * workspace over tombstones of ended sessions that had the same key (contracts §19.11).
+ * workspace over tombstones of ended sessions that had the same key.
  */
 export async function resolveWorkspace(ctx, ref) {
     const cloud = ctx.cloud();
@@ -190,7 +192,7 @@ export function parseSlugVersion(text, what) {
 }
 const INPUT_NAME = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/;
 /**
- * Open-time text inputs (contracts §24.3) from --input-file (NAME=value lines with # comments, or a JSON object of
+ * Open-time text inputs from --input-file (NAME=value lines with # comments, or a JSON object of
  * strings), then each --input NAME=value (a later one wins). Undefined when neither option is given.
  */
 async function inputsFrom(ctx, values) {
@@ -415,7 +417,7 @@ 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) ----------------------------------------------------------------------
+// ---- File-first workspaces (0.5.0) ----------------------------------------------------------------------
 const MODES = { processful: 'processful', 'file-first': 'file_first', file_first: 'file_first' };
 /** `--mode processful|file-first` (`file_first` too). */
 function modeFlag(values) {
@@ -450,7 +452,7 @@ function treeRevisionAfter(ws, cell) {
     return cell.treeRevision ?? ws.treeRevision;
 }
 /**
- * A lifecycle call a file-first workspace does not have (contracts §29.7: suspend, resume, fork, reset,
+ * A lifecycle call a file-first workspace does not have (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.
  */
@@ -517,7 +519,7 @@ export const KEY_HANDLERS = {
         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.
+    // Feedback (0.5.0+): POST /v1/feedback, emailed to the Shardflux team. 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);
@@ -525,7 +527,7 @@ export const KEY_HANDLERS = {
         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`;
+            : `Sent to the Shardflux team (feedback ${r.id}). Thank you.\n`;
         out(ctx, human, { id: r.id, received_at: r.receivedAt, duplicate: r.duplicate });
         return 0;
     },
@@ -659,7 +661,7 @@ export const KEY_HANDLERS = {
         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.
+            // An execution: answered when the command ended. The id is ours, so Ctrl-C can name it.
             const id = executionId ?? newExecutionId();
             let r;
             try {
@@ -675,7 +677,7 @@ export const KEY_HANDLERS = {
             }
             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, {
+                    throw new InterruptedError(`Interrupted; execution ${id} keeps running server side if it started (an execution runs to completion).`, undefined, {
                         executionId: id,
                         hint: `fetch its result later with: shard executions get ${ref} ${id}`,
                     });
@@ -874,7 +876,7 @@ export const KEY_HANDLERS = {
         return 0;
     },
     async 'workspaces resume'(ctx, values, [ref]) {
-        // With --wait the resume is held until the workspace runs (contracts §22.6); its tool token is the CLI's label.
+        // With --wait the resume is held until the workspace runs; 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]) {

package/dist/errors.d.ts

@@ -48,7 +48,7 @@ export declare class CheckoutEndedError extends Error {
 }
 /**
  * The user pressed Ctrl-C; `operationId` is set when a server-side operation keeps running, `executionId` when a
- * file-first execution does (it cannot be canceled), with `hint` naming the command that fetches its result.
+ * file-first execution does (an execution runs to completion), with `hint` naming the command that fetches its result.
  */
 export declare class InterruptedError extends Error {
     name: string;
@@ -60,7 +60,7 @@ export declare class InterruptedError extends Error {
         hint?: string;
     });
 }
-/** A file-first execution that ended `failed` or `lost` (contracts §29.8): nothing was published. */
+/** A file-first execution that ended `failed` or `lost`: nothing was published. */
 export declare class ExecutionFailedError extends Error {
     name: string;
     readonly result: ExecutionResult;

package/dist/errors.js

@@ -59,7 +59,7 @@ export class CheckoutEndedError extends Error {
 }
 /**
  * The user pressed Ctrl-C; `operationId` is set when a server-side operation keeps running, `executionId` when a
- * file-first execution does (it cannot be canceled), with `hint` naming the command that fetches its result.
+ * file-first execution does (an execution runs to completion), with `hint` naming the command that fetches its result.
  */
 export class InterruptedError extends Error {
     name = 'InterruptedError';
@@ -73,7 +73,7 @@ export class InterruptedError extends Error {
         this.hint = more.hint;
     }
 }
-/** A file-first execution that ended `failed` or `lost` (contracts §29.8): nothing was published. */
+/** A file-first execution that ended `failed` or `lost`: nothing was published. */
 export class ExecutionFailedError extends Error {
     name = 'ExecutionFailedError';
     result;
@@ -147,7 +147,7 @@ export function describeError(err) {
         const details = { ...(err.errorCode ? { error_code: err.errorCode } : {}), ...(typeof reason === 'string' ? { reason } : {}) };
         return { code: 'operation_failed', message: err.message, operation_id: err.operationId, retryable: err.retryable, ...(Object.keys(details).length ? { details } : {}), operation: err.operation };
     }
-    // File-first executions (0.5.0; contracts §29.8): failed or lost like a failed operation (details.reason says why;
+    // File-first executions (0.5.0): failed or lost like a failed operation (details.reason says why;
     // retryable: a new execution id may succeed), still running like a wait that gave up.
     if (err instanceof ExecutionFailedError) {
         const e = err.result.error;

package/dist/format.d.ts

@@ -22,13 +22,13 @@ export declare function workspaceRow(w: WorkspaceView): string[];
 export declare function workspaceTable(ws: readonly WorkspaceView[]): string;
 export declare function isReady(w: WorkspaceView): boolean;
 /**
- * The startup of a workspace's template version (contracts §24.4) in one line: state, trigger, and for a failure the
+ * The startup of a workspace's template version in one line: state, trigger, and for a failure the
  * step or service, exit code and reason. Null when the version has no start commands or services.
  */
 export declare function startupText(s: WorkspaceView['startup'] | undefined): string | null;
 /** The failed step's output tail, indented, after the detail block (empty otherwise). */
 export declare function startupTail(s: WorkspaceView['startup'] | undefined): string;
-/** A pending suspend-when-idle request in one line (0.5.1; contracts §20.6). */
+/** A pending suspend-when-idle request in one line (0.5.1). */
 export declare function suspendRequestText(r: SuspendRequest): string;
 /** `shard ws suspend --when-idle`: the recorded request, or the suspend already in progress. */
 export declare function suspendWhenIdleText(w: {
@@ -63,8 +63,8 @@ export declare function capMoney(minor: unknown, currency: string): string;
  */
 export declare function usageText(summary: unknown): string;
 /**
- * The `shard feedback` command a failed command suggests (0.5.0+), with the error's request id and code so the founder
- * can find the logs (a failed operation's or execution's own error code, e.g. capacity_unavailable); the agent fills in
+ * The `shard feedback` command a failed command suggests (0.5.0+), with the error's request id and code so the team
+ * can find the logs (a failed operation's or execution's own error code, e.g. template_not_found); the agent fills in
  * the text.
  */
 export declare function feedbackCommand(e: ErrorInfo): string;
@@ -90,7 +90,7 @@ export declare function languageTable(l: TemplateLanguages): string;
 export declare function packageTable(page: TemplatePackagePage): string;
 /** A template: identity, what open resolves to, its versions, and the open version's settings. */
 export declare function templateDetailText(t: TemplateDetail): string;
-/** A version's settings (contracts §24.3), one line per part. */
+/** A version's settings, one line per part. */
 export declare function settingsText(s: TemplateSettings): string;
 /** How many changed paths the human output lists before "... N more" (--json lists every one the result has). */
 export declare const MAX_CHANGED_SHOWN = 100;
@@ -133,6 +133,17 @@ export declare function usageSeriesText(series: unknown): string;
 /** The period estimate (GET .../usage/estimate): the bill so far and where each allowance is heading. */
 export declare function usageEstimateText(estimate: unknown): string;
 export declare function money(amountMinor: number, currency: string): string;
+export declare function isGrantPlan(plan: {
+    plan_key: string;
+    grant_days?: unknown;
+}): boolean;
+/** The plan in force with the grant's end (`ends_at`, 0.6.2+), which the SDK's generated types add with the API change. */
+type PlanInForce = NonNullable<BillingSubscription['plan']> & {
+    ends_at?: string | null;
+};
+/** "trial, ends 2026-11-29 14:03:00Z, then free (trial, catalog live-v7)"; a plan without an end as before. */
+export declare function planInForceText(plan: PlanInForce | null): string;
+/** The public plans: granted plans (the trial, design partners) are never listed or offered. */
 export declare function planTable(catalog: BillingCatalog): string;
 export declare function billingStatusText(s: BillingSubscription, org: Pick<Organization, 'name' | 'slug'>): string;
 export declare function invoiceTable(rows: readonly BillingInvoicePage['data'][number][]): string;
@@ -149,3 +160,4 @@ export declare function egressVersionTable(rows: readonly EgressPolicyVersion[])
  * cap and its bounds, the rates, and the next step. `saved` adds the version the change was saved as.
  */
 export declare function overagePolicyText(p: SpendPolicy, orgName: string, saved?: boolean): string;
+export {};

package/dist/format.js

@@ -85,7 +85,7 @@ function originText(o) {
     }
 }
 /**
- * The startup of a workspace's template version (contracts §24.4) in one line: state, trigger, and for a failure the
+ * The startup of a workspace's template version in one line: state, trigger, and for a failure the
  * step or service, exit code and reason. Null when the version has no start commands or services.
  */
 export function startupText(s) {
@@ -107,15 +107,15 @@ export function startupTail(s) {
     const lines = s.output_tail.replace(/\n$/, '').split('\n');
     return `startup output (last ${Buffer.byteLength(s.output_tail)} bytes):\n${lines.map((l) => `  | ${l}`).join('\n')}\n`;
 }
-/** A pending suspend-when-idle request in one line (0.5.1; contracts §20.6). */
+/** A pending suspend-when-idle request in one line (0.5.1). */
 export function suspendRequestText(r) {
-    return `after ${r.after_seconds} s idle, not before ${time(r.not_before)} (requested ${time(r.requested_at)})`;
+    return `${r.after_seconds === 0 ? 'as soon as idle' : `after ${r.after_seconds} s idle`}, not before ${time(r.not_before)} (requested ${time(r.requested_at)})`;
 }
 /** `shard ws suspend --when-idle`: the recorded request, or the suspend already in progress. */
 export function suspendWhenIdleText(w, r) {
     if (r.suspend_request) {
         const s = r.suspend_request;
-        return (`Suspend when idle: ${w.key} (${w.id}) is suspended once it has been idle for ${s.after_seconds} s, not before ${time(s.not_before)}.\n` +
+        return (`Suspend when idle: ${w.key} (${w.id}) is suspended ${s.after_seconds === 0 ? 'as soon as it is idle' : `once it has been idle for ${s.after_seconds} s`}, not before ${time(s.not_before)}.\n` +
             'A running command, an attached stream or a keepalive postpones it; the next tool call or a resume cancels it.\n' +
             `cancel with: shard workspaces suspend ${w.key} --cancel-when-idle\n`);
     }
@@ -132,7 +132,7 @@ export function workspaceDetail(w) {
         ['state', `${w.observed_state} (desired ${w.desired_state})`],
         ['ready', isReady(w) ? 'yes' : 'no'],
         ['template', `${w.template.slug} v${w.template.version} (${w.template.version_id})`],
-        // The mode (0.5.0; contracts §29) when the API reports it; a file-first workspace's state is its tree revision.
+        // The mode (0.5.0) when the API reports it; a file-first workspace's state is its tree revision.
         ...(w.mode !== undefined ? [['mode', modeText(w.mode)]] : []),
         ...(w.mode === 'file_first' ? [['tree revision', String(w.tree_revision)]] : []),
         ['cell', w.cell_id ? `${w.cell_id} ${w.cell_endpoint ?? '(endpoint unresolved)'}` : '-'],
@@ -317,8 +317,12 @@ export function usageText(summary) {
     const head = [];
     if (isObject(s.plan))
         head.push(['plan', `${scalar(s.plan.plan_key)}${s.plan.catalog_version !== undefined ? ` (catalog ${scalar(s.plan.catalog_version)})` : ''}`]);
-    if (isObject(s.period))
-        head.push(['period', `${time(scalar(s.period.start))} .. ${time(scalar(s.period.end))}`]);
+    if (isObject(s.period)) {
+        // A plan grant's own window (source `grant`, 0.6.2+): the trial's 60 days rather than the calendar month.
+        const trial = isObject(s.plan) && s.plan.plan_key === 'trial';
+        const grant = s.period.source === 'grant' ? (trial ? ' (the trial; then free)' : ' (the plan grant; it ends then)') : '';
+        head.push(['period', `${time(scalar(s.period.start))} .. ${time(scalar(s.period.end))}${grant}`]);
+    }
     const m = isObject(s.measurement) ? s.measurement : s;
     if (m.measured_through !== undefined)
         head.push(['measured through', time(m.measured_through)]);
@@ -326,7 +330,8 @@ export function usageText(summary) {
         head.push(['estimate', scalar(s.measurement.estimate_status)]);
     if (typeof s.allowance_exhausted === 'boolean') {
         const reason = typeof s.exhausted_reason === 'string' ? `${s.exhausted_reason}: ` : '';
-        head.push(['allowance exhausted', s.allowance_exhausted ? `yes (${reason}new opens/resumes are refused)` : 'no']);
+        const trialEnded = isObject(s.plan) && s.plan.plan_key === 'trial';
+        head.push(['allowance exhausted', s.allowance_exhausted ? (trialEnded ? `yes (${reason}the trial ends; the organization is back on free)` : `yes (${reason}new opens/resumes are refused)`) : 'no']);
     }
     for (const [k, v] of Object.entries(s))
         if (!USAGE_KNOWN.has(k) && (typeof v !== 'object' || v === null))
@@ -363,8 +368,8 @@ export function usageText(summary) {
 /** Request ids and error codes pasted unquoted into the suggested command must be shell-inert. */
 const SHELL_SAFE = /^[A-Za-z0-9._:-]{1,200}$/;
 /**
- * The `shard feedback` command a failed command suggests (0.5.0+), with the error's request id and code so the founder
- * can find the logs (a failed operation's or execution's own error code, e.g. capacity_unavailable); the agent fills in
+ * The `shard feedback` command a failed command suggests (0.5.0+), with the error's request id and code so the team
+ * can find the logs (a failed operation's or execution's own error code, e.g. template_not_found); the agent fills in
  * the text.
  */
 export function feedbackCommand(e) {
@@ -402,7 +407,7 @@ export function errorText(e, hint, feedback) {
         : '';
     return `error: ${e.message}${reason} [${meta.join(' ')}]\n${issues}${hint ? `hint: ${hint}\n` : ''}${feedback ? `feedback: ${feedback}\n` : ''}`;
 }
-// ---- Templates v2 (contracts §19) ---------------------------------------------------------------
+// ---- Templates v2 ---------------------------------------------------------------
 export function templateTable(rows) {
     return table(['SLUG', 'OWNER', 'OPEN VERSION', 'LAYOUTS', 'FILES', 'DRAFT', 'ARCHIVED'], rows.map((t) => {
         const v = t.open_version;
@@ -514,7 +519,7 @@ export function templateDetailText(t) {
         : 'No versions.\n';
     return `${head}\n${versions}${open?.settings ? `\nsettings of v${open.version}:\n${settingsText(open.settings)}` : ''}`;
 }
-/** A version's settings (contracts §24.3), one line per part. */
+/** A version's settings, one line per part. */
 export function settingsText(s) {
     const inputs = Object.entries(s.inputs).map(([n, i]) => `${n} (${i.kind}${i.required ? ', required' : ''}${i.default !== null ? `, default ${JSON.stringify(i.default)}` : ''})`);
     const d = s.defaults;
@@ -528,7 +533,7 @@ export function settingsText(s) {
         ['egress', egress],
     ]).replace(/^/gm, '  ');
 }
-// ---- File-first executions (0.5.0; contracts §29.8) ----------------------------------------------------------------------
+// ---- File-first executions (0.5.0) ----------------------------------------------------------------------
 const CHANGE_LETTER = { added: 'A', modified: 'M', deleted: 'D' };
 /** How many changed paths the human output lists before "... N more" (--json lists every one the result has). */
 export const MAX_CHANGED_SHOWN = 100;
@@ -730,8 +735,25 @@ export function money(amountMinor, currency) {
     const c = currency.toLowerCase();
     return `${zeroDecimal.has(c) ? String(amountMinor) : (amountMinor / 100).toFixed(2)} ${c.toUpperCase()}`;
 }
+/**
+ * Plans that are only ever granted, never bought: the signup trial and the design-partner plan (0.6.2+). The API's
+ * catalog marks them with `grant_days`; the keys cover an API that lists them without it.
+ */
+const GRANT_PLANS = new Set(['trial', 'partner']);
+export function isGrantPlan(plan) {
+    return GRANT_PLANS.has(plan.plan_key) || (typeof plan.grant_days === 'number' && plan.grant_days > 0);
+}
+/** "trial, ends 2026-11-29 14:03:00Z, then free (trial, catalog live-v7)"; a plan without an end as before. */
+export function planInForceText(plan) {
+    if (!plan)
+        return '-';
+    const endsAt = typeof plan.ends_at === 'string' && plan.ends_at !== '' ? plan.ends_at : null;
+    const ends = endsAt ? `, ends ${time(endsAt)}${plan.plan_key === 'trial' ? ', then free' : ''}` : '';
+    return `${plan.plan_key}${ends} (${plan.source}, catalog ${plan.catalog_version})`;
+}
+/** The public plans: granted plans (the trial, design partners) are never listed or offered. */
 export function planTable(catalog) {
-    const rows = catalog.plans.map((p) => {
+    const rows = catalog.plans.filter((p) => !isGrantPlan(p)).map((p) => {
         const prices = p.prices.length ? p.prices.map((x) => `${money(x.amount_minor, x.currency)}/${x.interval}`).join(', ') : 'free';
         const buy = p.prices.some((x) => x.purchasable) ? 'yes' : '-';
         return [p.plan_key, p.name, prices, buy];
@@ -743,7 +765,7 @@ export function billingStatusText(s, org) {
     const pending = s.pending_checkout;
     return kv([
         ['organization', `${org.name} (${org.slug})`],
-        ['plan', s.plan ? `${s.plan.plan_key} (${s.plan.source}, catalog ${s.plan.catalog_version})` : '-'],
+        ['plan', planInForceText(s.plan)],
         ['billing state', s.billing_state],
         ['subscription', sub ? `${sub.status}${sub.plan_key ? ` ${sub.plan_key}` : ''}${sub.cancel_at_period_end ? ', cancels at period end' : ''}` : 'none'],
         ['period end', sub ? time(sub.current_period_end) : '-'],

package/dist/http.d.ts

@@ -1,14 +1,7 @@
 /**
- * The fetch given to the SDK: the runtime's fetch with `Connection: close` on
- * every request (API and cell gateway).
- *
- * Why: Node 26.7's bundled undici (8.9.0) intermittently stalls a request
- * sent on a reused keep-alive connection until an unrelated timer fires (up to
- * ~30 s, the SDK's request timeout, after which the SDK retries). Reproduced
- * with bare fetch against both node:http and Fastify servers; Node 22 (undici
- * 6.28) and `Connection: close` do not stall. A fresh connection per request
- * costs one TCP/TLS handshake, which is negligible for these call rates.
- * Set SHARDFLUX_HTTP_KEEPALIVE=1 to use the runtime's keep-alive pooling.
+ * The fetch given to the SDK: the runtime's fetch (API and cell gateway). By
+ * default every request uses a fresh connection (`Connection: close`);
+ * SHARDFLUX_HTTP_KEEPALIVE=1 reuses connections.
  *
  * `signal` (the CLI's Ctrl-C) is attached to held requests (`Prefer: wait=N`,
  * held by the server for up to 20 s). The SDK passes the caller's signal to its

package/dist/http.js

@@ -1,14 +1,7 @@
 /**
- * The fetch given to the SDK: the runtime's fetch with `Connection: close` on
- * every request (API and cell gateway).
- *
- * Why: Node 26.7's bundled undici (8.9.0) intermittently stalls a request
- * sent on a reused keep-alive connection until an unrelated timer fires (up to
- * ~30 s, the SDK's request timeout, after which the SDK retries). Reproduced
- * with bare fetch against both node:http and Fastify servers; Node 22 (undici
- * 6.28) and `Connection: close` do not stall. A fresh connection per request
- * costs one TCP/TLS handshake, which is negligible for these call rates.
- * Set SHARDFLUX_HTTP_KEEPALIVE=1 to use the runtime's keep-alive pooling.
+ * The fetch given to the SDK: the runtime's fetch (API and cell gateway). By
+ * default every request uses a fresh connection (`Connection: close`);
+ * SHARDFLUX_HTTP_KEEPALIVE=1 reuses connections.
  *
  * `signal` (the CLI's Ctrl-C) is attached to held requests (`Prefer: wait=N`,
  * held by the server for up to 20 s). The SDK passes the caller's signal to its
@@ -16,6 +9,7 @@
  * sends its POST without one), so Ctrl-C would otherwise wait the hold out.
  */
 export function makeFetch(env, base = fetch, signal) {
+    // Why a fresh connection by default (Node 26 keep-alive measurements): docs/progress/startup-latency.md.
     const keepAlive = env.SHARDFLUX_HTTP_KEEPALIVE === '1';
     return (input, init) => {
         const headers = new Headers(init?.headers);