@shardflux/cli 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -3,7 +3,24 @@
 Every command and option the README shows is available from the version named here. Breaking changes ship in minor
 releases and are marked **Breaking**.
 
-## 0.10.0 (not yet published)
+## 0.11.0 (not yet published)
+
+- Add opt-in persistent workspace idle deletion retention, workspace/project setters and projected deletion times.
+
+- Accelerate reverse tunnels with a bounded, acknowledged binary WebSocket stream, 64 KiB frames and batched credits. Select `auto`, `pty` or `exec` transport; reconnect preserves byte offsets. Opt-in binary PTY output accepts larger blocks for file transfers.
+
+- Add opt-in resize controls to grow named resources only and return the held server answer without polling a pending operation.
+
+- `shard ws computer stream` reuses a private cached link by API/workspace/credential and kind with more than 60 seconds left. `--fresh` remints; `--stop` clears cached links.
+- `SHARDFLUX_BASE_URL` aliases `SHARDFLUX_API_URL` (the latter wins). Canceled exec results exit 130; timeout, normal exit and signal statuses follow the shared POSIX status helper.
+- Shared SDK proxy support, missing-file classification and computer batch screenshot deduplication.
+- Embed live desktop viewers and port previews in a web app with an explicit HTTPS origin allowlist and partitioned browser sessions.
+
+- Add foreground `shard ws tunnel <key> --remote <port> --to <host:port> [--bind 127.0.0.1|0.0.0.0]`. Ctrl-C closes the reverse tunnel and its guest process.
+
+- Add `shard ws upgrade <key> [--at next-resume]` with operation waiting and JSON output.
+
+## 0.10.0 — 2026-10-04
 
 Needs `@shardflux/sdk` 0.15.0 or later.
 
@@ -30,12 +47,10 @@ Additive (contracts §46), with `@shardflux/sdk` 0.15.0.
 - `shard ws computer enable|disable|inherit <key>` and `shard ws open --computer-use on|off|inherit`: the workspace's
   computer use switch; `shard templates computer-use <slug> on|off`: the switch for every workspace of a template.
 
-## 0.9.0 — 2026-10-04 (not yet published)
+## 0.9.0 — 2026-10-04
 
 - `shard ws hint <workspace>` explicitly stages a parked workspace ahead of a VM tool call, without waiting for restore or resuming a suspended workspace.
 
-## 0.9.0 (not yet published)
-
 Needs `@shardflux/sdk` 0.14.0 or later.
 
 ### Sign up from an agent
@@ -115,7 +130,7 @@ workspace.
   API decides (with elastic-by-default enabled for the organization a new workspace is elastic; otherwise
   `requires_elastic`). With `--allocation-mode fixed` it stays a usage error.
 
-## 0.8.1 (not yet published)
+## 0.8.1 — 2026-10-03
 
 Needs `@shardflux/sdk` 0.13.1 or later.
 
@@ -133,7 +148,7 @@ When the machine a workspace runs on fails, the workspace is suspended, and the
   `--timing` prints the SDK's `restored checkpoint <id> (host_lost; state as of <time>)`.
 - `hostLostNotice()` is exported next to `coldBootNotice()`.
 
-## 0.8.0
+## 0.8.0 — 2026-10-02
 
 Needs `@shardflux/sdk` 0.13.0 or later.
 
@@ -206,7 +221,7 @@ newest published version.
 - **Breaking:** `--json` output no longer carries `update_policy`: the API removed the update policy (it was always
   `pinned`).
 
-## 0.6.2
+## 0.6.2 — 2026-09-30
 
 Needs `@shardflux/sdk` 0.11.1 or later.
 
@@ -241,14 +256,12 @@ New organizations can start on a trial: 60 days at Developer limits, no card. Th
 - An interrupted file-first `ws exec` says `(an execution runs to completion)`; `mode_not_available` drops "yet";
   `--open` no longer says "best effort"; `templates init --help` no longer names an internal document.
 
-## 0.7.0 (release candidate)
+## 0.7.0 — 2026-09-30
 
 Completed exec output streams are drained before releasing their HTTP connections, with a bounded cleanup if a peer does not close.
 
 Uses SDK 0.12.0 and its pooled transport. Adds --labels/--idle-policy to open, --labels to list, ws labels, ws idle, ws exec-start --stdin-open and ws exec-input --offset. Protocol-error JSON includes source. Resume recovers failed workspaces; completed deletion permits key reuse.
 
-Requires the QM integration backend release for labels, failed recovery, key reuse and pipe stdin. No production deployment has occurred from this branch.
-
 ### Instant suspend: durable storage
 
 - `shard ws suspend --wait` still returns when the suspend succeeds (sealed on its host); a finished suspend or fork
@@ -264,7 +277,7 @@ Requires the QM integration backend release for labels, failed recovery, key reu
 - A suspend-when-idle canceled `workspace_active` says the workspace was in use and keeps running.
 - The `ws suspend` summary no longer says "durable checkpoint".
 
-## 0.6.1
+## 0.6.1 — 2026-09-30
 
 Needs `@shardflux/sdk` 0.11.0 or later.
 
@@ -276,7 +289,7 @@ flush grace after its last work), and a running command, an attached stream or a
 it ends. The human output says `is suspended as soon as it is idle`, and `ws get` shows `as soon as idle`. Out of
 range is still exit 2 before any request: `--when-idle must be between 0s and 1h`.
 
-## 0.6.0
+## 0.6.0 — 2026-09-29
 
 Needs `@shardflux/sdk` 0.11.0 or later.
 
@@ -296,17 +309,17 @@ suspend; every process was restarted.
   processes restarted (runtime_changed)` (the SDK's `formatTiming()`).
 - `coldBootNotice()` is exported next to `TimingRecorder`, which records the call as `coldBoot`.
 
-## 0.5.3
+## 0.5.3 — 2026-09-29
 
 Fix: `shard --version`, the User-Agent and the update check reports 0.5.3. 0.5.2 was published reporting 0.5.1, its previous version; the build now
 fails when `CLI_VERSION` differs from package.json.
 
-## 0.5.2
+## 0.5.2 — 2026-09-29
 
 Public support: package metadata and the README now link to the [shared bug tracker](https://github.com/shardfluxdev/community/issues),
 feature requests, and private support/security reporting.
 
-## 0.5.1
+## 0.5.1 — 2026-09-29
 
 ### A command that could not start is never a silent exit
 
@@ -356,7 +369,7 @@ cell had ended the session `failed_to_start` (`working directory "app" is not a
   `--cancel-when-idle` cancels it. `--json` prints `{workspace, operation, suspend_request}`.
 - `shard workspaces get` shows a pending request (`suspend when idle  after N s idle, not before ...`).
 
-## 0.5.0
+## 0.5.0 — 2026-09-29
 
 Needs `@shardflux/sdk` 0.9.0 or later.
 
@@ -529,13 +542,12 @@ unchanged and still stores nothing.
   edit that does not match, a mode the workspace lacks, a reused execution id), and `shard feedback` itself.
 - The positional usage of `shard feedback` is shown as `<message...>`; `--agent-label` also names the reporting agent.
 
-
-## 0.4.1 (2026-09-28)
+## 0.4.1 — 2026-09-28
 
 Needs `@shardflux/sdk` 0.8.0 or later. No command changes: the SDK's 0.8.0 is a types-only release (its provider tool
 exports type-check without casts), and the CLI moves to it so `shardflux` installs one copy of the SDK.
 
-## 0.4.0 (2026-09-28)
+## 0.4.0 — 2026-09-28
 
 Needs `@shardflux/sdk` 0.7.0 or later. New dependency: `yaml` (template.yaml).
 
@@ -563,7 +575,7 @@ Needs `@shardflux/sdk` 0.7.0 or later. New dependency: `yaml` (template.yaml).
 - `buildText` names a recipe v2 build's recipe sha256, its build network and denied hosts, and points at
   `shard templates builds get`.
 
-## 0.3.1 (2026-09-28)
+## 0.3.1 — 2026-09-28
 
 Needs `@shardflux/sdk` 0.6.2 or later.
 
@@ -580,7 +592,7 @@ stays suspended).
 - `shard workspaces get` names the origin of a template version test instance (`template <id> version <n>`, contracts
   §24.6) instead of reading it as a draft state.
 
-## 0.3.0 (2026-09-28)
+## 0.3.0 — 2026-09-28
 
 Needs `@shardflux/sdk` 0.6.0 or later.
 
@@ -609,13 +621,13 @@ Needs `@shardflux/sdk` 0.6.0 or later.
 - Ctrl-C ends a held open at once (exit 130); the open continues server side, and opening the key again keeps
   waiting.
 
-## 0.2.0 (2026-09-28)
+## 0.2.0 — 2026-09-28
 
 Secrets (`secrets ...`, `workspaces open --secret`, `workspaces secrets`), session workspaces (`--lifetime session`,
 `workspaces close`), layered workspaces (`workspaces reset|save-as-template|changes`), templates
 (`templates list|files|diff|draft ...`), and waking suspended workspaces on use (`--no-wake`, `--wake-timeout`).
 
-## 0.1.0 (2026-09-26)
+## 0.1.0 — 2026-09-26
 
 First release: `login`, `whoami`, `usage`, `workspaces open|list|get|exec|suspend|resume|fork|delete|sessions`,
 `files read|write|ls`, `operations list|get|wait`, `--json`, and documented exit codes.

package/README.md

@@ -1,6 +1,6 @@
 # @shardflux/cli: `shard`
 
-The command line for [Shardflux](https://shardflux.dev): cloud computers for AI agents. Open a
+The command line for [Shardflux](https://shardflux.dev): serverless VMs for AI agents. Open a
 persistent workspace by key, run commands in it, move files in and out, and suspend, resume, fork
 or delete it. From 0.5.0 it also does everything the web app does: create an account, sign in
 (with two-factor authentication), set up an organization, project and API key, manage members,
@@ -24,6 +24,20 @@ For usage, account, billing, or private support, email [shardflux@heliosone.fi](
 Report vulnerabilities through [private security reporting](https://github.com/shardfluxdev/community/security/advisories/new).
 See the [support guide](https://github.com/shardfluxdev/community/blob/main/SUPPORT.md) for all reporting options.
 
+## Reverse tunnels (0.11.0+)
+
+Run a foreground TCP tunnel from a workspace to a service on this machine:
+
+```sh
+shard ws tunnel customer-42/main --remote 8081 --to localhost:8081
+```
+
+Commands in the workspace can then call `http://127.0.0.1:8081`. The target is dialed on the machine running
+`shard`. Ctrl-C closes the sockets and guest process. `--bind 0.0.0.0` selects all guest interfaces; loopback is the
+default. An open tunnel keeps the workspace awake, and persistent workspaces preserve it across explicit suspend/resume.
+
+The tunnel selects a streaming transport automatically when `pty` permission is granted. Choose `transport: 'pty'` or `transport: 'exec'` in the SDK, or `--transport pty|exec` in the CLI, to select it explicitly. The handle reports `transport`.
+
 ## Install
 
 ```sh
@@ -1022,3 +1036,44 @@ Use the byte offset in each acknowledgement, including partial writes. `ws resum
 ### Prepare an imminent command (0.9.0+)
 
 Call `shard ws hint <workspace>` ahead of a tool call to stage a parked workspace while the input is prepared. It returns without waiting for restore. Resume a suspended workspace first. The hint is explicit; ordinary commands add no early hint.
+
+Resize controls (0.11.0+): `shard ws resize <workspace> --memory 6144 --disk 2 --at-least --no-wait` grows only
+resources that need more capacity and returns the held server answer with the operation. The normal command waits
+for completion. Fixed memory without `--memory-mib` uses the template default.
+
+## New in 0.11.0
+
+`shard ws computer stream <workspace>` reuses a private viewer link with more than 60 seconds left across CLI invocations. `--fresh` mints a new link, and `--stop` clears it. Canceled exec commands exit 130, timeouts exit 124, and signal exits use 128 + signal. `SHARDFLUX_BASE_URL` aliases `SHARDFLUX_API_URL`; the latter and `--api-url` take precedence. The SDK transport honors environment HTTP(S)_PROXY and NO_PROXY.
+
+## Embed a live viewer (0.11.0+)
+
+Watch the desktop or a port preview inside your web app. Choose 1–10 distinct HTTPS origins, then use the returned URL as the iframe source.
+
+```bash
+shard ws computer stream acme/demo --embed-origin https://app.example.com
+shard ws port link acme/demo 3000 --embed-origin https://app.example.com --embed-origin https://admin.example.com
+```
+
+```html
+<iframe src="RETURNED_LINK_URL" title="Watch the agent" style="width:100%;height:600px;border:0"></iframe>
+```
+
+The browser session is partitioned by the top-level site. Each origin is exactly a scheme and host with an optional port, such as `https://app.example.com:8443`. The viewer permits framing by those origins; interactive viewing uses the same allowlist.
+
+## Idle deletion retention (0.11.0+)
+
+```sh
+shard ws open chat/42 --template python-node-browser --delete-after-idle 14d
+shard ws retention chat/42 30d
+shard projects retention PROJECT_ID 14d --labels '{"app":"chat"}'
+shard projects retention PROJECT_ID
+shard ws retention chat/42 off
+```
+
+Use 1d through 3650d with persistent workspaces. `off` removes the workspace's own policy and follows its
+project default; `shard projects retention PROJECT_ID off` clears that default. All selector labels match
+exactly, and a workspace's own setting wins. With no policy, workspaces stay until you delete them.
+
+## Workspace upgrade (0.11.0+)
+
+`shard ws upgrade <key>` keeps files and installed package files through one cold start. Memory and processes end. Use `--at next-resume` to schedule it without stopping the VM; `--json` returns the operation and its applied/scheduled result.

package/dist/args.d.ts

@@ -1,4 +1,4 @@
-export declare const CLI_VERSION = "0.10.0";
+export declare const CLI_VERSION = "0.11.0";
 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.10.0';
+export const CLI_VERSION = '0.11.0';
 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).' },
@@ -200,6 +200,17 @@ const KEY_COMMANDS = [
         },
         examples: ['shard usage', 'shard usage --estimate', 'shard usage --series --granularity day', 'shard usage --workspace acme/demo --meter cpu_seconds'],
     },
+    {
+        path: ['workspaces', 'retention'], summary: 'Set or clear persistent workspace idle deletion',
+        positionals: [{ name: 'key', required: true }, { name: 'policy', required: true }], options: {},
+        examples: ['shard ws retention acme/thread-42 14d', 'shard ws retention acme/thread-42 off'],
+    },
+    {
+        path: ['projects', 'retention'], summary: 'Read or set the project default idle deletion policy (project key)',
+        positionals: [{ name: 'project-id', required: true }, { name: 'policy', required: false }],
+        options: { labels: { type: 'string', value: '<json>', description: 'Exact-match label selectors.' } },
+        examples: ["shard projects retention <project-id> 14d --labels '{\"app\":\"chat\"}'"],
+    },
     {
         path: ['workspaces', 'open'],
         summary: 'Open a workspace by key (create on first use, reconnect or resume afterwards)',
@@ -208,6 +219,7 @@ const KEY_COMMANDS = [
         options: {
             template: { type: 'string', value: '<slug>', description: 'Template slug (required), e.g. python-node-browser.' },
             labels: { type: 'string', value: '<json>', description: 'Replace workspace labels with a JSON object of strings.' },
+            'delete-after-idle': { type: 'string', value: '<days>d', description: 'Delete this persistent workspace after 1..3650 idle days (e.g. 14d).' },
             'idle-policy': { type: 'string', value: '<policy>', description: 'adaptive, never or fixed:<seconds>.' },
             secret: {
                 type: 'string',
@@ -294,6 +306,17 @@ const KEY_COMMANDS = [
         },
         examples: ['shard ws exec-start acme/demo --session-id build-1 --timeout 2h -- bash -lc "make -C /home/user/app"', 'shard ws exec-read acme/demo build-1 --follow'],
     },
+    {
+        path: ['workspaces', 'tunnel'], summary: 'Reach this machine from a workspace TCP port',
+        description: 'Runs in the foreground. The guest listener defaults to loopback; --to is dialed on this machine. Ctrl-C closes the tunnel. An open tunnel keeps the workspace awake.',
+        positionals: [REF], options: {
+            transport: { type: 'string', value: '<auto|pty|exec>', description: 'Tunnel transport (default auto).' },
+            remote: { type: 'string', value: '<port>', description: 'Required guest listener port (1..65535).' },
+            to: { type: 'string', value: '<host:port>', description: 'Required TCP target on this machine (host:port or [IPv6]:port).' },
+            bind: { type: 'string', value: '<127.0.0.1|0.0.0.0>', description: 'Guest bind address (default 127.0.0.1).' },
+        },
+        examples: ['shard ws tunnel acme/demo --remote 8081 --to localhost:8081'],
+    },
     {
         path: ['workspaces', 'exec-read'],
         summary: 'Print a background exec session’s output and state; --follow streams it until the command exits',
@@ -387,6 +410,11 @@ const KEY_COMMANDS = [
         positionals: [REF, { name: 'new-key', required: true }],
         options: { ...CAPS, ...MEMORY_ALLOCATION, ...WAIT },
     },
+    {
+        path: ['workspaces', 'upgrade'], summary: 'Upgrade in place, keeping files and installed packages',
+        description: 'One cold start drops memory and processes. --at next-resume schedules it without stopping the VM.',
+        positionals: [REF], options: { ...WAIT, at: { type: 'string', value: '<now|next-resume>', description: 'When to cold start (default now).' } },
+    },
     {
         path: ['workspaces', 'resize'],
         summary: 'Change a workspace’s memory, CPU or disk, running or suspended, without a restart (0.9.0+)',
@@ -399,6 +427,8 @@ const KEY_COMMANDS = [
             elastic: { type: 'boolean', description: 'Switch to elastic memory: the workspace holds what its commands use and grows up to the memory size.' },
             cpu: { type: 'string', value: '<millis>', description: 'CPU in millicores (1000 = one vCPU).' },
             disk: { type: 'string', value: '<gib>', description: 'Disk in GiB (disks grow only).' },
+            'at-least': { type: 'boolean', description: 'Only grow each named resource; smaller or equal values stay unchanged.' },
+            wait: { type: 'boolean', description: 'Wait for the operation (default); --no-wait returns the held server answer.' },
             timeout: { type: 'string', value: '<duration>', description: 'Give up waiting after this long (default 5m); the resize continues server side.' },
             ...TIMING,
         },
@@ -493,6 +523,7 @@ const KEY_COMMANDS = [
         description: 'Opening the link starts a browser session for the port (until it expires) and lands on --path. Anyone with the link can open the port until then: share it like a password. --json prints {url, expires_at}.',
         positionals: [REF, PORT],
         options: {
+            'embed-origin': { type: 'string', multiple: true, value: '<https-origin>', description: 'Allow this HTTPS origin to embed the viewer (repeatable, 1–10 distinct origins).' },
             ttl: { type: 'string', value: '<duration>', description: 'Lifetime of the link and its browser session, 1m to 7d (default 24h).' },
             path: { type: 'string', value: '<path>', description: 'Where the link lands: a path starting with one / (query allowed; default /).' },
         },
@@ -660,7 +691,9 @@ const KEY_COMMANDS = [
         description: 'Starts the viewer in the workspace, exposes its port and signs a link to it (inbound ports). View only unless --interactive. Anyone with the link can open it until it expires: share it like a password. --stop ends every view instead. --json prints {url, expires_at, port, interactive}.',
         positionals: [REF],
         options: {
+            fresh: { type: 'boolean', description: 'Mint a new viewer link instead of reusing a link with more than 60 seconds left.' },
             interactive: { type: 'boolean', description: 'Let the viewer use the mouse and keyboard.' },
+            'embed-origin': { type: 'string', multiple: true, value: '<https-origin>', description: 'Allow this HTTPS origin to embed the viewer (repeatable, 1–10 distinct origins).' },
             ttl: { type: 'string', value: '<duration>', description: 'Lifetime of the link, 1m to 7d (default 24h).' },
             stop: { type: 'boolean', description: 'End every view and close the viewer ports.' },
         },

package/dist/commands.d.ts

@@ -99,7 +99,9 @@ export declare function principal(ctx: Ctx): Promise<{
     tool_permissions: ("git" | "exec" | "files" | "pty" | "process" | "browser" | "computer")[];
 }>;
 /** The exit code `shard exec` returns for a finished command. */
-export declare function execExitCode(r: Pick<RunResult, 'exitCode' | 'termSignal' | 'timedOut'>): number;
+export declare function execExitCode(r: Pick<RunResult, 'exitCode' | 'termSignal' | 'timedOut'> & {
+    canceled?: boolean;
+}): number;
 /**
  * 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

package/dist/commands.js

@@ -5,10 +5,11 @@
  * 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 { computerStreamCache } from "./computer-stream-cache.js";
 import { randomUUID } from 'node:crypto';
 import { access, readFile, writeFile } from 'node:fs/promises';
 import { basename, dirname, resolve as resolvePath } from 'node:path';
-import { EXECUTION_ID, ExecStartError, FEEDBACK_CATEGORIES, FEEDBACK_MESSAGE_MAX_LENGTH, NotSupportedForModeError, SDK_VERSION, ShardfluxApiError, ShardfluxProtocolError, newExecutionId } from '@shardflux/sdk';
+import { EXECUTION_ID, ExecStartError, FEEDBACK_CATEGORIES, FEEDBACK_MESSAGE_MAX_LENGTH, NotSupportedForModeError, SDK_VERSION, ShardfluxApiError, ShardfluxProtocolError, newExecutionId, exitCodePosix } from '@shardflux/sdk';
 import { parse as parseYaml } from 'yaml';
 import { CLI_VERSION, SECRET_NAME, UUID, parseDuration, parseEnvPairs, parsePositiveInt } from "./args.js";
 import { ExecSessionRunningError, ExecutionFailedError, ExecutionPendingError, InterruptedError, NotFoundError, UsageError } from "./errors.js";
@@ -94,6 +95,10 @@ function resizeParams(values) {
         p.diskGib = parsePositiveInt(disk, 'disk', 1_000_000);
     if (Object.keys(p).length === 0)
         throw new UsageError('nothing to resize: give --memory, --held, --fixed, --elastic, --cpu or --disk');
+    if (values['at-least'] === true)
+        p.atLeast = true;
+    if (values.wait === false)
+        p.wait = false;
     return p;
 }
 /**
@@ -493,13 +498,7 @@ function feedbackContext(ctx, values) {
 }
 /** The exit code `shard exec` returns for a finished command. */
 export function execExitCode(r) {
-    if (r.timedOut)
-        return 124;
-    if (typeof r.exitCode === 'number' && r.exitCode >= 0)
-        return Math.min(r.exitCode, 255);
-    if (typeof r.termSignal === 'number' && r.termSignal > 0)
-        return 128 + r.termSignal;
-    return 1;
+    return Math.min(exitCodePosix(r), 255);
 }
 /** The longest cancel grace the workspace applies (it waits 5 s without one). */
 const MAX_CANCEL_GRACE_MS = 60_000;
@@ -860,6 +859,35 @@ export const KEY_HANDLERS = {
             ctx.io.stderr.write(`read it with: shard ws exec-read ${ref} ${session.session_id} --follow; stop it with: shard ws exec-cancel ${ref} ${session.session_id}\n`);
         return 0;
     },
+    async 'workspaces tunnel'(ctx, values, [ref]) {
+        const remote = str(values.remote);
+        const target = str(values.to);
+        if (!remote || !target)
+            throw new UsageError('tunnel requires --remote <port> and --to <host:port>');
+        const remotePort = parsePositiveInt(remote, 'remote');
+        if (remotePort > 65535)
+            throw new UsageError('--remote must be 1..65535');
+        const bindAddress = oneOf(values, 'bind', ['127.0.0.1', '0.0.0.0']);
+        const transport = oneOf(values, 'transport', ['auto', 'pty', 'exec']);
+        const terminated = new AbortController();
+        const onTerm = () => terminated.abort(new Error('terminated'));
+        process.once('SIGTERM', onTerm);
+        try {
+            const ws = await resolveWorkspace(ctx, ref);
+            const tunnel = await ws.tunnels.reverse({ remotePort, target, ...(bindAddress ? { bindAddress } : {}), ...(transport ? { transport } : {}), signal: AbortSignal.any([ctx.signal, terminated.signal]) });
+            out(ctx, `${bindAddress ?? '127.0.0.1'}:${remotePort} in ${ws.key} → ${target} on this machine; Ctrl-C closes the tunnel\n`, { remote_port: remotePort, target, session_id: tunnel.sessionId, transport: tunnel.transport });
+            try {
+                await tunnel.closed;
+            }
+            finally {
+                await tunnel.close();
+            }
+            return terminated.signal.aborted ? 143 : ctx.signal.aborted ? 130 : 0;
+        }
+        finally {
+            process.removeListener('SIGTERM', onTerm);
+        }
+    },
     async 'workspaces exec-read'(ctx, values, [ref, sessionId]) {
         const ws = await resolveWorkspace(ctx, ref);
         const cell = cellOf(ctx, ws);
@@ -904,7 +932,7 @@ export const KEY_HANDLERS = {
         if (s.state === 'starting' || s.state === 'running') {
             throw new ExecSessionRunningError(`Exec session ${s.session_id} is still ${s.state}.`, s, `follow it to its end with: shard ws exec-read ${ref} ${s.session_id} --follow`);
         }
-        const result = { exitCode: s.exit_code ?? null, termSignal: s.term_signal ?? null, timedOut: s.timed_out ?? false };
+        const result = { exitCode: s.exit_code ?? null, termSignal: s.term_signal ?? null, timedOut: s.timed_out ?? false, canceled: s.canceled ?? false };
         if (!ctx.json && result.exitCode === null && !result.timedOut && !(result.termSignal !== null && result.termSignal > 0)) {
             ctx.io.stderr.write(`exec session ${s.session_id} ended ${s.state} without an exit code${s.error ? `: ${s.error}` : ''}\n`);
         }
@@ -931,6 +959,22 @@ export const KEY_HANDLERS = {
         out(ctx, JSON.stringify(ack) + '\n', ack);
         return 0;
     },
+    async 'workspaces retention'(ctx, _values, [ref, policy]) {
+        const ws = await resolveWorkspace(ctx, ref);
+        await ws.setRetention(retentionDays(policy));
+        out(ctx, `${JSON.stringify(ws.retention)}\n`, ws.data);
+        return 0;
+    },
+    async 'projects retention'(ctx, values, [projectId, policy]) {
+        const api = ctx.cloud().projects;
+        if (policy === 'off' && values.labels !== undefined)
+            throw new UsageError('--labels cannot be combined with off');
+        if (policy === undefined && values.labels !== undefined)
+            throw new UsageError('--labels requires a retention policy');
+        const retention = policy === undefined ? await api.getRetention(projectId) : await api.setRetention(projectId, policy === 'off' ? null : { ...openRetentionDays(policy), ...(str(values.labels) === undefined ? {} : { labels: labelMap(str(values.labels)) }) });
+        out(ctx, `${JSON.stringify(retention)}\n`, retention);
+        return 0;
+    },
     async 'workspaces open'(ctx, values, [key]) {
         const template = str(values.template);
         if (!template)
@@ -954,6 +998,7 @@ export const KEY_HANDLERS = {
             key: key,
             template,
             ...(str(values.labels) !== undefined ? { labels: labelMap(str(values.labels)) } : {}),
+            ...(str(values['delete-after-idle']) !== undefined ? { retention: openRetentionDays(str(values['delete-after-idle'])) } : {}),
             ...(str(values['idle-policy']) ? { idlePolicy: str(values['idle-policy']) } : {}),
             ...(c ? { caps: c } : {}),
             ...(bind.length ? { secrets: bind } : {}),
@@ -1301,6 +1346,12 @@ export const KEY_HANDLERS = {
     async 'workspaces close'(ctx, values, [ref]) {
         return lifecycle(ctx, values, ref, 'Closing', (ws, o) => ctx.cloud().workspaces.close(ws.id, o));
     },
+    async 'workspaces upgrade'(ctx, values, [ref]) {
+        const at = str(values.at) ?? 'now';
+        if (at !== 'now' && at !== 'next-resume')
+            throw new UsageError('--at must be now or next-resume');
+        return lifecycle(ctx, values, ref, at === 'now' ? 'Upgrading' : 'Scheduling upgrade for', (ws, o) => ctx.cloud().workspaces.upgrade(ws.id, { ...o, at: at === 'next-resume' ? 'next_resume' : 'now' }), ['upgrade', 'Upgrade']);
+    },
     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)');
@@ -1860,7 +1911,7 @@ export const KEY_HANDLERS = {
         if (path !== undefined && !path.startsWith('/'))
             throw new UsageError(`--path must start with / (got "${path}")`);
         const ws = await portWorkspace(ctx, ref);
-        const l = await ws.ports.link(port, { ...(ttl !== undefined ? { ttlSeconds: ttl } : {}), ...(path !== undefined ? { path } : {}) });
+        const l = await ws.ports.link(port, { ...(values['embed-origin'] !== undefined ? { embed: { origins: values['embed-origin'] } } : {}), ...(ttl !== undefined ? { ttlSeconds: ttl } : {}), ...(path !== undefined ? { path } : {}) });
         out(ctx, `${l.url}\n`, { url: l.url, expires_at: l.expiresAt });
         if (!ctx.json)
             ctx.io.stderr.write(`Opens port ${port} of ${ws.key} in a browser until ${time(l.expiresAt)}; anyone with the link can open it until then.\n`);
@@ -2004,13 +2055,20 @@ export const KEY_HANDLERS = {
     },
     async 'workspaces computer stream'(ctx, values, [ref]) {
         const ws = await computerWorkspace(ctx, ref);
+        const credential = ctx.io.env.SHARDFLUX_API_KEY?.trim() ?? ctx.store.profile(ctx.apiUrl).api_key?.token ?? '';
+        const cache = computerStreamCache(ctx.io.env, ctx.apiUrl, ws.id, credential);
         if (values.stop === true) {
+            cache.clear();
             await ws.computer.stopStream();
             out(ctx, `Ended every view of the desktop of ${ws.key}.\n`, { workspace_id: ws.id, stopped: true });
             return 0;
         }
         const ttl = ttlSeconds(values, PORT_LINK_TTL);
-        const s = await ws.computer.stream({ interactive: values.interactive === true, ...(ttl !== undefined ? { ttlSeconds: ttl } : {}) });
+        const streamOptions = { fresh: values.fresh === true, interactive: values.interactive === true,
+            ...(values['embed-origin'] !== undefined ? { embed: { origins: values['embed-origin'] } } : {}),
+            ...(ttl !== undefined ? { ttlSeconds: ttl } : {}) };
+        const s = (values.fresh !== true ? cache.get(values.interactive === true, streamOptions) : undefined) ?? await ws.computer.stream(streamOptions);
+        cache.set(s, streamOptions);
         out(ctx, `${s.url}\n`, { url: s.url, expires_at: s.expiresAt, port: s.port, interactive: s.interactive });
         if (!ctx.json) {
             ctx.io.stderr.write(`${s.interactive ? 'Uses' : 'Watches'} the desktop of ${ws.key} until ${time(s.expiresAt)}; anyone with the link can open it until then.\n`);
@@ -2334,3 +2392,18 @@ function labelMap(value) {
         throw new UsageError('labels must be a JSON object of strings');
     return parsed;
 }
+function retentionDays(value) {
+    if (value === 'off')
+        return null;
+    const match = /^([0-9]+)d$/.exec(value);
+    const days = match ? Number(match[1]) : NaN;
+    if (!Number.isInteger(days) || days < 1 || days > 3650)
+        throw new UsageError('retention must be 1d..3650d or off');
+    return { delete_after_idle_days: days };
+}
+function openRetentionDays(value) {
+    const policy = retentionDays(value);
+    if (policy === null)
+        throw new UsageError('--delete-after-idle requires 1d..3650d; clear an own policy with shard ws retention KEY off');
+    return policy;
+}

package/dist/computer-stream-cache.d.ts

@@ -0,0 +1,8 @@
+import type { ComputerStream, ComputerStreamOptions } from '@shardflux/sdk';
+type StreamOptions = Pick<ComputerStreamOptions, 'embed' | 'ttlSeconds'>;
+export declare function computerStreamCache(env: Record<string, string | undefined>, apiUrl: string, workspaceId: string, credential: string): {
+    get(interactive: boolean, options?: StreamOptions): ComputerStream | undefined;
+    set(link: ComputerStream, options?: StreamOptions): void;
+    clear(): void;
+};
+export {};

package/dist/computer-stream-cache.js

@@ -0,0 +1,34 @@
+/** Viewer links survive CLI invocations in the private config directory, scoped to API/workspace/credential. */
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { configDir } from "./credentials.js";
+export function computerStreamCache(env, apiUrl, workspaceId, credential) {
+    const digest = (text) => createHash('sha256').update(text).digest('hex');
+    const dir = join(configDir(env), 'computer-streams', digest(`${apiUrl}\0${workspaceId}`));
+    const path = (interactive, options = {}) => join(dir, `${digest(credential)}-${interactive ? 'interactive' : 'view'}-${digest(JSON.stringify({ ttlSeconds: options.ttlSeconds, embed: options.embed }))}.json`);
+    return {
+        get(interactive, options = {}) {
+            try {
+                const link = JSON.parse(readFileSync(path(interactive, options), 'utf8'));
+                if (typeof link.url === 'string' && typeof link.expiresAt === 'string' && Number.isInteger(link.port) && link.interactive === interactive && Date.parse(link.expiresAt) - Date.now() > 60_000)
+                    return link;
+            }
+            catch { /* cache misses are ordinary; mint through the SDK */ }
+            return undefined;
+        },
+        set(link, options = {}) {
+            const temp = `${path(link.interactive, options)}.${randomUUID()}.tmp`;
+            try {
+                mkdirSync(dir, { recursive: true, mode: 0o700 });
+                writeFileSync(temp, JSON.stringify(link), { mode: 0o600, flag: 'wx' });
+                renameSync(temp, path(link.interactive, options));
+            }
+            catch { /* caching is optional; the minted link remains usable */ }
+            finally {
+                rmSync(temp, { force: true });
+            }
+        },
+        clear() { rmSync(dir, { recursive: true, force: true }); },
+    };
+}

package/dist/format.js

@@ -155,6 +155,9 @@ const deferText = (r) => (r === null || r === 'suspended' || r === 'stopped' ? '
  * applied in part (requested above a limit, a partial grow, a shrink the guest did not finish).
  */
 export function resizeText(w, r) {
+    if (r.operation && !['succeeded', 'failed', 'canceled'].includes(r.operation.state)) {
+        return `Resize accepted for ${w.key} (${w.id}); operation ${r.operation.id} is ${r.operation.state}.\n`;
+    }
     const rows = [];
     const row = (name, unit, x, extra = '', converged = null) => {
         const notes = [];

package/dist/main.js

@@ -415,7 +415,7 @@ export async function run(argv, io, opts = {}) {
     let ctx;
     let updates = null;
     try {
-        const apiUrl = resolveApiUrl(parsed.global.apiUrl, io.env.SHARDFLUX_API_URL);
+        const apiUrl = resolveApiUrl(parsed.global.apiUrl, io.env.SHARDFLUX_API_URL ?? io.env.SHARDFLUX_BASE_URL);
         apiUrlForCleanup = apiUrl;
         const agentLabel = parsed.global.agentLabel ?? io.env.SHARDFLUX_AGENT_LABEL ?? 'cli';
         if (!isLabel(agentLabel))
@@ -609,7 +609,8 @@ export async function run(argv, io, opts = {}) {
     const running = handler(ctx, parsed.values, parsed.positionals).then((code) => ({ code }), (err) => ({ err }));
     // On Ctrl-C give the command a moment to clean up (exec sends a cancel), then stop regardless.
     const interrupted = new Promise((resolve) => {
-        const onAbort = () => setTimeout(() => resolve({ interrupted: true }), 4_000).unref();
+        const cleanupMs = parsed.command.path.join(' ') === 'workspaces tunnel' ? 90_000 : 4_000;
+        const onAbort = () => setTimeout(() => resolve({ interrupted: true }), cleanupMs).unref();
         if (signal.aborted)
             onAbort();
         else

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@shardflux/cli",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "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 persistent agent workspaces.",
+  "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",
   "homepage": "https://shardflux.dev",
   "bugs": {
@@ -44,7 +44,7 @@
   },
   "dependencies": {
     "yaml": "2.9.1",
-    "@shardflux/sdk": "^0.15.0"
+    "@shardflux/sdk": "^0.16.0"
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",