@shardflux/cli 0.13.3 → 0.13.4

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.13.4
+
+- Cloud Claude sign-in and reopening the machine editor preserve existing workspace labels while updating their own labels.
+- `shard billing status` on the signup trial suggests `shard billing upgrade pro` when the live catalog offers Pro (the trial is 60 days of Pro from catalog live-v10); otherwise it points to `shard billing plans`.
+- Reuse an account-private setup cache across projects after the agent starts; report cache scope with `shard template --json`.
+- Machine and project filesystem status shows the current platform base and whether a rebase is pending.
+
 ## 0.13.3
 
 - `shard ./` seeds the workspace repository with the checked-out branch and its upstream only, not every local branch, tag and stash. When that history is still above 256 MiB, the workspace fetches the branch from origin with its own Git credentials and receives only the commits origin does not have yet. The workspace branch tracks its origin branch.
@@ -13,7 +20,7 @@
 - Git history above the first copy's 256 MiB limit fails with `repository_too_large` and its next step in the hint, not `internal_error`.
 - A `revision_mismatch` suggests `--expected-revision` only for the file commands that take it; elsewhere it says to run the same command again.
 - Config sync reports project entries keyed by paths on this computer (Codex `config.projects.*`) as one summary line.
-- The command center does not show a setup step that `.shardflux/setup.yaml` marks `required: false` as the setup failure while the template saves, and reads skipped steps (coding template 8+).
+- The command center does not show a setup step that `.shardflux/setup.yaml` marks `required: false` as the setup failure while the template saves, and reads skipped steps (coding template 9+).
 
 ## 0.13.2
 

package/README.md

@@ -264,9 +264,9 @@ plan only when Stripe confirms the payment, so `--wait` polls until the subscrip
 open). An organization that already has a subscription changes plans in the billing portal: the
 command prints the portal URL instead (exit 0).
 
-On the signup trial (60 days at Developer limits, no card), `billing status` shows when it ends and
+On the signup trial (60 days of Pro, no card), `billing status` shows when it ends and
 what follows (0.6.2+): `plan  trial, ends 2026-11-29 14:03:00Z, then free (trial, catalog ...)`, then
-`keep these limits after the trial: shard billing upgrade developer`. A subscription outranks the
+`keep these limits after the trial: shard billing upgrade pro` (0.13.4+). A subscription outranks the
 trial and ends it. The trial is granted, never bought, so `billing plans` leaves it out.
 
 `billing overage` shows and changes opt-in overage (owners and billing members). With it on,
@@ -283,7 +283,7 @@ already charged this period (`spend_cap_below_charges`); a plan without overage
 ```text
 $ shard billing overage on --cap 9
 Acme: overage is on, spend cap $9.00 per billing period ($1.00 to $9.00, the plan price).
-Rates past the allowances: $0.03 per RAM GiB-hour, $0.12 per CPU-hour, charged on the next invoice (this period: shard usage).
+Rates past the allowances: $0.015 per RAM GiB-hour, $0.04 per CPU-hour, charged on the next invoice (this period: shard usage).
 Saved (policy version 1).
 ```
 
@@ -828,12 +828,12 @@ amount:
 ```text
 overage          accruing (usage past the allowances is charged on the next invoice)
 spend cap        $9.00 (at most $9.00, the plan price)
-overage charges  $2.40 of $9.00 (26.67%), $6.60 left; billed on the next invoice
+overage charges  $1.10 of $9.00 (12.22%), $7.90 left; billed on the next invoice
 cap reached      2026-09-29 15:02:46Z (projected at this period's average use)
 
-OVERAGE        UNIT       PAST ALLOWANCE  BILLED  RATE   AMOUNT
-ram_gib_hours  gib_hours  70              60      $0.03  $1.80
-cpu_hours      hours      5               5       $0.12  $0.60
+OVERAGE        UNIT       PAST ALLOWANCE  BILLED  RATE    AMOUNT
+ram_gib_hours  gib_hours  70              60      $0.015  $0.90
+cpu_hours      hours      5               5       $0.04   $0.20
 ```
 
 `--json` prints the API's summary, with `spend_cap` and `exhausted_reason`. Owners and billing members turn overage on

package/dist/account-commands.js

@@ -1403,12 +1403,15 @@ export const ACCOUNT_HANDLERS = {
         const account = ctx.account();
         const org = await resolveOrg(ctx, account, values);
         const s = await account.billing.subscription(org.id);
-        // The trial has Developer limits: Developer keeps them (a subscription outranks the trial and ends it).
+        // The trial has Pro's limits and allowances (catalog live-v10): Pro keeps them (a subscription outranks the trial and ends it).
+        // Name Pro only while the live catalog sells it; a catalog without Pro gets the general hint.
+        const trialToPro = !s.subscription && s.purchase_available && s.plan?.plan_key === 'trial'
+            && (await fetchBillingCatalog({ baseUrl: ctx.apiUrl, fetch: ctx.accountOptions().fetch ?? fetch }).catch(() => null))?.plans?.some((p) => p.plan_key === 'pro') === true;
         const next = s.subscription
             ? 'manage it: shard billing portal'
             : s.purchase_available
-                ? s.plan?.plan_key === 'trial'
-                    ? 'keep these limits after the trial: shard billing upgrade developer'
+                ? trialToPro
+                    ? 'keep these limits after the trial: shard billing upgrade pro'
                     : 'buy a plan: shard billing plans, then shard billing upgrade <plan>'
                 : '';
         out(ctx, `${billingStatusText(s, org)}${next ? `${next}\n` : ''}`, s);

package/dist/agent-commands.d.ts

@@ -3,6 +3,6 @@ import type { Ctx, Handler } from './commands.js';
 /** `<slug>-<6 hex of sha256(identity)>`: the same repository gets the same key on every machine. */
 export declare function disambiguatedSlug(slug: string, identity: string): string;
 export declare function projectTemplate(ctx: Ctx, remote: string | null): Promise<string>;
-export declare function agentPty(cell: CellClient, app: 'claude' | 'codex', agent: string, approvals: boolean, term: string, signal?: AbortSignal, project?: string, setupHash?: string, cwd?: string, ptyName?: string, onLaunch?: () => void): Promise<PtySession>;
+export declare function agentPty(cell: CellClient, app: 'claude' | 'codex', agent: string, approvals: boolean, term: string, signal?: AbortSignal, project?: string, setupHash?: string, cwd?: string, ptyName?: string, onLaunch?: () => void, deferSetup?: boolean): Promise<PtySession>;
 export declare const launchProject: Handler;
 export declare const AGENT_HANDLERS: Record<string, Handler>;

package/dist/agent-commands.js

@@ -1,3 +1,4 @@
+import { prepareSetupCache } from "./setup-cache.js";
 import { agentReachability } from "./agent-reachability.js";
 import { configureCredentialFill, watchCredentialPrompts } from "./credential-prompts.js";
 import { createHash } from 'node:crypto';
@@ -39,11 +40,11 @@ export async function projectTemplate(ctx, remote) {
         throw error;
     }
 }
-export async function agentPty(cell, app, agent, approvals, term, signal, project, setupHash, cwd, ptyName, onLaunch) {
+export async function agentPty(cell, app, agent, approvals, term, signal, project, setupHash, cwd, ptyName, onLaunch, deferSetup = false) {
     const id = `shard-${ptyName || agent}-${app}`;
     // Arrival and changed locks queue the same durable guest job even when the
     // native agent is already alive. Setup never becomes its first user turn.
-    if (setupHash) {
+    if (setupHash && !deferSetup) {
         const queued = await cell.exec.run(['sf-agent', 'setup-start', '--deps-hash', setupHash], { timeoutMs: 30_000, maxOutputBytes: 4096, signal, ...(cwd ? { cwd } : {}) });
         if (queued.exitCode !== 0)
             throw new Error(`project setup could not be queued: ${queued.stderr.trim() || `exit ${queued.exitCode}`}`);
@@ -59,7 +60,7 @@ export async function agentPty(cell, app, agent, approvals, term, signal, projec
     }
     onLaunch?.();
     const launch = await cell.exec.run(['sf-agent', 'run', app, '--name', agent, '--detach', ...(ptyName ? ['--pty-name', ptyName] : []), ...(approvals ? ['--approvals'] : []), ...(setupHash ? ['--setup', '--setup-deps-hash', setupHash] : [])], {
-        env: { TERM: term, ...(project ? { SF_PROJECT_NAME: project } : {}) }, timeoutMs: 30_000, maxOutputBytes: 4096, signal, ...(cwd ? { cwd } : {}),
+        env: { TERM: term, ...(project ? { SF_PROJECT_NAME: project } : {}), ...(setupHash && deferSetup ? { SF_SETUP_DEFERRED: '1' } : {}) }, timeoutMs: 30_000, maxOutputBytes: 4096, signal, ...(cwd ? { cwd } : {}),
     });
     if (launch.exitCode !== 0)
         throw new Error(`agent launch failed: ${launch.stderr.trim() || `exit ${launch.exitCode}`}`);
@@ -88,14 +89,25 @@ async function terminal(ctx, ws, app, agent, project, values, setupHash, cwd = w
     try {
         const credentialFill = await configureCredentialFill(ctx, ws);
         // A cold launch is remembered before it starts, so the listing can show it before the projection does (agent-live.ts).
-        const session = await agentPty(cell, app, agent, values.approvals === true, ctx.io.env.TERM || 'xterm-256color', ctx.signal, ws.labels.shard_project || ws.key.split('/')[0], setupHash, cwd, ws.labels.agent_pty_name, () => { rememberLaunch(ctx, ws.id); progress(ctx, `Starting ${app === 'claude' ? 'Claude' : 'Codex'} in ${ws.key}…`); });
+        const session = await agentPty(cell, app, agent, values.approvals === true, ctx.io.env.TERM || 'xterm-256color', ctx.signal, ws.labels.shard_project || ws.key.split('/')[0], setupHash, cwd, ws.labels.agent_pty_name, () => { rememberLaunch(ctx, ws.id); progress(ctx, `Starting ${app === 'claude' ? 'Claude' : 'Codex'} in ${ws.key}…`); }, true);
+        // The real agent is running before any cache provisioning or mount wait.
+        const preparation = prepareSetupCache(ctx, ws).catch((error) => {
+            ctx.io.stderr.write(`Account setup cache unavailable: ${error instanceof Error ? error.message : String(error)}\n`);
+        }).then(async () => {
+            if (!setupHash)
+                return;
+            const queued = await cell.exec.run(['sf-agent', 'setup-start', '--deps-hash', setupHash], { cwd, timeoutMs: 30_000, maxOutputBytes: 4096, signal: ctx.signal });
+            if (queued.exitCode !== 0)
+                throw new Error(`project setup could not be queued: ${queued.stderr.trim() || `exit ${queued.exitCode}`}`);
+        });
         store.save(project, app);
         if (!attach) {
+            await preparation;
             ctx.io.stdout.write(json({ workspace: ws.data, session }));
             return 0;
         }
         ctx.io.stderr.write(`Shardflux · ${ws.key}\nDetach: Ctrl-] then d\n`);
-        return await attachTerminal({
+        const attached = attachTerminal({
             ...(credentialFill ? { credentialPrompts: (ask, signal) => watchCredentialPrompts(ctx, ws, ask, signal) } : {}),
             io: ctx.io, signal: ctx.signal, connect: cellConnector(cell, session.session_id),
             wake: (signal) => ws.wake({ timeoutMs: ctx.wakeTimeoutMs, signal }),
@@ -108,8 +120,11 @@ async function terminal(ctx, ws, app, agent, project, values, setupHash, cwd = w
                     done();
             }),
         });
+        const [code] = await Promise.all([attached, preparation]);
+        return code;
     }
     finally {
+        cell.close();
         await tunnels?.stop();
     }
 }

package/dist/agent-credentials.js

@@ -76,8 +76,15 @@ export const AGENT_CREDENTIAL_HANDLERS = {
         }
         requireClaudeTerminal(ctx);
         const project = projectIdentity('./');
-        const ws = typeof values.workspace === 'string' ? await resolveWorkspace(ctx, values.workspace)
-            : await ctx.cloud().workspaces.open({ key: `${project.slug}/main`, template: 'coding', labels: projectLabels(project, 'main', 'claude'), wait: { signal: ctx.signal, timeoutMs: ctx.wakeTimeoutMs } });
+        let ws;
+        if (typeof values.workspace === 'string')
+            ws = await resolveWorkspace(ctx, values.workspace);
+        else {
+            const cloud = ctx.cloud();
+            const key = `${project.slug}/main`;
+            const current = await cloud.workspaces.findByKey(key, { includeDeleted: false, signal: ctx.signal });
+            ws = await cloud.workspaces.open({ key, template: 'coding', labels: { ...current?.labels, ...projectLabels(project, 'main', 'claude') }, wait: { signal: ctx.signal, timeoutMs: ctx.wakeTimeoutMs } });
+        }
         output(ctx, await loginClaudeInWorkspace(ctx, ws));
         return 0;
     },

package/dist/args.d.ts

@@ -1,4 +1,4 @@
-export declare const CLI_VERSION = "0.13.3";
+export declare const CLI_VERSION = "0.13.4";
 export interface OptionSpec {
     type: 'string' | 'boolean';
     short?: string;

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.13.3';
+export const CLI_VERSION = '0.13.4';
 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).' },

package/dist/filesystem-commands.d.ts

@@ -1,5 +1,7 @@
 import type { AgentFilesystem } from '@shardflux/sdk';
 import type { Handler } from './commands.js';
-/** One line per status: what is in use and what is saving or failed. */
-export declare function filesystemLine(state: AgentFilesystem): string;
+/** One line per status: what is in use and what is saving or failed, its platform base and setup cache. */
+export declare function filesystemLine(state: AgentFilesystem & {
+    cache_scope?: string;
+}): string;
 export declare const FILESYSTEM_HANDLERS: Record<string, Handler>;

package/dist/filesystem-commands.js

@@ -2,14 +2,19 @@ import { waitTimeout } from "./commands.js";
 import { 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";
 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. */
+/** One line per status: what is in use and what is saving or failed, its platform base and setup cache. */
 export function filesystemLine(state) {
+    const base = state.platform_base ? `; platform ${state.platform_base.slug}@${state.platform_base.version}${state.rebase_pending ? ', rebase pending' : ''}` : '';
+    return usageLine(state) + base + (state.cache_scope ? `; cache: ${state.cache_scope}` : '');
+}
+function usageLine(state) {
     const current = state.version > 0 ? `version ${state.version}` : '';
     if (state.state === 'building' && state.pending)
         return `${state.level}: saving version ${state.pending.version}${current ? ` (${current} stays in use until it is ready)` : ''}`;
@@ -56,7 +61,7 @@ export const FILESYSTEM_HANDLERS = {
         else if (existing.data.observed_state !== 'running')
             progress(ctx, `Resuming your machine VM (${key})…`);
         const ws = await cloud.workspaces.open({ key, template: state.template ? `${state.template.slug}@${state.template.version}` : 'coding',
-            labels: { shard_layer: 'machine', shard_machine: state.organization_id, repo_path: '/home/user', app: 'claude', agent: 'machine' },
+            labels: { ...existing?.labels, shard_layer: 'machine', shard_machine: state.organization_id, repo_path: '/home/user', app: 'claude', agent: 'machine' },
             wait: { timeoutMs: ctx.wakeTimeoutMs, signal: ctx.signal } });
         if (state.version === 0) {
             progress(ctx, 'Syncing your Claude and Codex config into the machine…');
@@ -77,7 +82,13 @@ export const FILESYSTEM_HANDLERS = {
         return output(ctx, await ctx.cloud().machine.rollback({ to: rollbackTo(values.to) }, { signal: ctx.signal }));
     },
     async template(ctx) {
-        return output(ctx, await ctx.cloud().templates.getProject(remote().repoRemote, { signal: ctx.signal }));
+        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 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);
+        return output(ctx, { ...state, cache_scope: progress?.cache_scope ?? (mounted ? 'account' : 'workspace') });
     },
     async 'template save'(ctx, values) {
         const { project, repoRemote } = remote();

package/dist/setup-cache.d.ts

@@ -0,0 +1,5 @@
+import type { Workspace } from '@shardflux/sdk';
+import type { Ctx } from './commands.js';
+export declare const SETUP_CACHE_PATH = "/mnt/shardflux-cache";
+/** Uses ordinary fenced shared-volume operations, after the managed PTY starts. */
+export declare function prepareSetupCache(ctx: Ctx, workspace: Workspace): Promise<void>;

package/dist/setup-cache.js

@@ -0,0 +1,11 @@
+const name = 'shardflux-setup-cache';
+export const SETUP_CACHE_PATH = '/mnt/shardflux-cache';
+/** Uses ordinary fenced shared-volume operations, after the managed PTY starts. */
+export async function prepareSetupCache(ctx, workspace) {
+    const cloud = ctx.cloud();
+    const wait = { timeoutMs: ctx.wakeTimeoutMs, signal: ctx.signal };
+    const { volume } = await cloud.volumes.open({ name, projectId: workspace.data.project_id, wait });
+    if (volume.state !== 'available' || !volume.org_shared || volume.quota_gib !== 1)
+        throw new Error('account setup cache is not available');
+    await cloud.volumes.attach(workspace.id, { volumeId: volume.id, mountPath: SETUP_CACHE_PATH, wait });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shardflux/cli",
-  "version": "0.13.3",
+  "version": "0.13.4",
   "type": "module",
   "description": "shard: the Shardflux command line. Create an account, sign in, set up keys and billing, then open, run commands in, move files to, suspend, resume and fork serverless agent workspaces.",
   "license": "Apache-2.0",
@@ -47,7 +47,7 @@
     "smol-toml": "1.9.0",
     "snappyjs": "0.7.0",
     "yaml": "2.9.1",
-    "@shardflux/sdk": "^0.18.1"
+    "@shardflux/sdk": "^0.18.2"
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",