@solarisdk/core 0.3.1 → 0.4.0

package/dist/handle.js

@@ -1,40 +1,37 @@
-// `SessionHandle` — the shared base for {@link Sandbox} and {@link Desktop}.
-//
-// Wraps a {@link ControlChannel} and exposes the CONTRACTS-V2 §4 primitives
-// (commands, pty, runCode, files) plus the gateway-routed lifecycle/admin calls
-// (metrics, snapshot, revert, pause/resume, setTimeout, env, volumes,
-// kill). Both Sandbox and Desktop extend this; Desktop adds the GUI surface.
-//
-// Streaming model: async output from `commands.start`/`pty.create`/`files.watch`
-// arrives as v2 frames `{type:"cmd.data"|"cmd.exit"|"pty.data"|"fs.event", ...}`
-// dispatched by the ControlChannel by `type` + the stream's own id, NOT by the
-// originating request id. We register/unregister those frame handlers as
-// commands/ptys/watches are created and torn down.
 import { downloadAll } from "./chunked-download.js";
-import { GatewayError, SolariError } from "./errors.js";
+import { ActionError, GatewayError, SolariError, TimeoutError } from "./errors.js";
 import { shortId } from "./ids.js";
 import { base64ToBytes, bytesToBase64, ControlChannel, } from "./transport.js";
-/** Cap on PTY output held before the first onData() subscriber (bytes, total). */
+export const DEFAULT_COMMAND_TIMEOUT_MS = 600_000;
+const unreleased = new Map();
+const MAX_TRACKED_UNRELEASED = 1000;
+let exitHookInstalled = false;
+function trackUnreleased(token, id) {
+    unreleased.set(token, id);
+    if (unreleased.size > MAX_TRACKED_UNRELEASED)
+        unreleased.delete(unreleased.keys().next().value);
+    if (exitHookInstalled || typeof process === "undefined" || typeof process.on !== "function")
+        return;
+    exitHookInstalled = true;
+    process.on("exit", () => {
+        for (const id of unreleased.values()) {
+            console.warn(`[solari] this process is exiting but session ${shortId(id)} is still running and will bill until its ` +
+                `idle timeout. Call kill() to release it (or declare it with \`await using\`).`);
+        }
+        unreleased.clear();
+    });
+}
+const MIN_REST_TIMEOUT_MS = 1000;
 export const PTY_EARLY_BUFFER_MAX = 1024 * 1024;
 export class SessionHandle {
-    /** The session id (sandboxId / sessionId). */
     id;
     controlUrl;
     expiresAt;
     channel;
     hooks;
-    /** Set by {@link kill} so {@link close} doesn't warn about a machine we
-     *  have just released. */
     killed = false;
+    releaseToken = {};
     constructor(id, controlUrl, expiresAt, config = {}) {
-        // A blank id is the one bad value that survives to the wire looking almost
-        // right: it builds `/sandboxes//exec` (a double slash), not an obviously
-        // wrong path with the word `undefined` in it, so it goes unnoticed while
-        // every call the handle makes is malformed. Reject it where it enters.
-        // Guard the blank STRING specifically (the sneaky value described above) —
-        // a non-string id is either the obvious `undefined`/`null` case this comment
-        // excludes or a hand-built bare handle, and calling `.trim()` on it would
-        // throw an opaque TypeError instead of this clear message.
         if (typeof id === "string" && id.trim() === "") {
             throw new SolariError("Solari: session id must not be blank — an empty id builds a malformed `/sandboxes//…` request.");
         }
@@ -43,68 +40,35 @@ export class SessionHandle {
         this.expiresAt = expiresAt;
         this.channel = new ControlChannel(controlUrl, config);
         this.hooks = config.hooks ?? {};
+        trackUnreleased(this.releaseToken, id);
     }
-    /** Whether the control channel is open. */
     get connected() {
         return this.channel.connected;
     }
-    /** Subclass hook: send a raw JSON-RPC call over the control channel. */
     rpc(method, params) {
         return this.channel.call(method, params);
     }
-    /** Subclass hook: send a v1 streamed call (per-`id` stdout/stderr frames). */
     rpcStream(method, params, onStream) {
         return this.channel.call(method, params, { onStream });
     }
-    /** Open the control WebSocket. Idempotent. */
     connect() {
         return this.channel.connect();
     }
-    /** Reconnect after a drop (re-opens the socket). */
     reconnect() {
-        // No id check here on purpose: reconnect reuses this handle's id, which was
-        // already validated as non-blank in the constructor. The two real entrances
-        // for an untrusted id are the constructor (create-response wrapping) and
-        // the client's connect(id) — not reconnect().
         return this.channel.reconnect();
     }
-    /**
-     * Close the control channel LOCALLY. This does **not** release the remote
-     * session — the sandbox/desktop keeps running (and keeps billing) until its
-     * idle timeout, or until you call {@link kill}.
-     *
-     * If you meant "I'm done with this machine", call {@link kill}.
-     *
-     * Pass `{ quiet: true }` when the machine is released some other way (for
-     * example a wrapper that pauses or kills it by id right after closing its own
-     * channel) and the "still running" nudge would be wrong.
-     */
     close(opts = {}) {
+        unreleased.delete(this.releaseToken);
         if (!this.killed && !opts.quiet && typeof console !== "undefined") {
-            // Cheap, one-shot nudge: the close/kill distinction is the single most
-            // common misread of this API, and silently leaving a machine running is
-            // expensive in a way nothing else surfaces.
             console.warn(`[solari] close() on session ${shortId(this.id)} closed the local channel only — ` +
                 `the remote machine is still running and will bill until its idle ` +
                 `timeout. Call kill() to release it now.`);
         }
         this.channel.close();
     }
-    // --- commands -------------------------------------------------------------
     commands = {
-        /**
-         * Run a command to completion. `onStdout`/`onStderr` receive output as it
-         * streams (via `cmd.data` frames); the promise resolves with the terminal
-         * exit code (from `cmd.exit`).
-         */
         run: (cmd, opts = {}) => this.runCommand(cmd, opts),
-        /**
-         * Start a command and return a handle immediately (does not wait for exit).
-         * Output streams as `cmd.data`; the handle exposes `stdin`, `onData`,
-         * `wait()`, and `kill()`.
-         */
         start: (cmd, opts = {}) => this.startCommand(cmd, opts),
-        /** Reconnect the control channel (e.g. to resume receiving frames). */
         connect: () => this.channel.reconnect(),
     };
     async startCommand(cmd, opts, acc) {
@@ -117,10 +81,6 @@ export class SessionHandle {
         });
         const cmdId = r.cmdId;
         const dataCbs = [];
-        // Frames can arrive in the microtask gap between this method returning the
-        // handle and the caller (e.g. runCommand) attaching its onData accumulator.
-        // Buffer chunks while no consumer is attached, then replay on first onData
-        // so early stdout/stderr is never dropped (would surface as exit=0 + "").
         const buffered = [];
         let exitResolve = null;
         let exitReject = null;
@@ -128,14 +88,22 @@ export class SessionHandle {
             exitResolve = res;
             exitReject = rej;
         });
-        // If the control channel drops before `cmd.exit` arrives, reject the wait so
-        // callers get a ConnectionError instead of hanging forever.
-        this.channel.onStreamClose(cmdId, (err) => exitReject?.(err));
-        // The result accumulator is subscribed BEFORE any frame handler is registered:
-        // registering the frame handler flushes frames that beat the cmd.start reply
-        // (orphans), and those must reach the accumulator as well as the caller's
-        // callbacks. Attaching it afterwards (via the public onData) lost them whenever
-        // a callback was set, because a non-empty dataCbs skips the replay buffer.
+        let timedOut = false;
+        let deadline;
+        this.channel.onStreamClose(cmdId, (err) => {
+            clearTimeout(deadline);
+            exitReject?.(err);
+        });
+        if (typeof opts.timeoutMs === "number" && opts.timeoutMs > 0) {
+            deadline = setTimeout(() => {
+                timedOut = true;
+                this.channel.call("cmd.kill", { cmdId, signal: 9 }).catch(() => undefined);
+                this.channel.offFrame("cmd.data", cmdId);
+                this.channel.offFrame("cmd.exit", cmdId);
+                this.channel.offStreamClose(cmdId);
+                exitResolve?.(-1);
+            }, opts.timeoutMs);
+        }
         if (acc) {
             dataCbs.push((c) => {
                 if (c.stream === "stdout")
@@ -166,6 +134,7 @@ export class SessionHandle {
             this.channel.offFrame("cmd.data", cmdId);
             this.channel.offFrame("cmd.exit", cmdId);
             this.channel.offStreamClose(cmdId);
+            clearTimeout(deadline);
             exitResolve?.(typeof f.exitCode === "number" ? f.exitCode : 0);
         });
         return {
@@ -182,16 +151,15 @@ export class SessionHandle {
                 dataCbs.push(cb);
             },
             wait: () => exitPromise,
+            get timedOut() {
+                return timedOut;
+            },
             kill: (signal) => this.channel
                 .call("cmd.kill", { cmdId, signal })
                 .then(() => undefined),
         };
     }
     async runCommand(cmd, opts) {
-        // Direct exec means a shell line fails as "no such file or directory",
-        // which reads like a missing tool. Let the call run, then explain that
-        // specific failure rather than rejecting up front (see
-        // explainShellCommandFailure — rejecting would break working callers).
         try {
             return await this.runCommandInner(cmd, opts);
         }
@@ -200,71 +168,58 @@ export class SessionHandle {
         }
     }
     async runCommandInner(cmd, opts) {
-        // One-shot HTTP fast path: for a plain run-to-completion (no streaming
-        // callbacks, not backgrounded, no per-command env/user) run the command
-        // over the already-warm REST connection instead of paying a cold control-WS
-        // handshake. That handshake (~180ms TCP+TLS to the gateway) dominates the
-        // "create → run one command" latency, so skipping it is the single biggest
-        // TTI win. We only take this path when the control channel isn't already
-        // open — if it is, the WS is cheaper and streams. env/user are excluded
-        // because the one-shot guest path runs under the session env only; routing
-        // those through the streaming path keeps behavior identical.
+        const timeoutMs = opts.timeoutMs ?? DEFAULT_COMMAND_TIMEOUT_MS;
+        if (typeof timeoutMs !== "number" || !Number.isFinite(timeoutMs) || timeoutMs < 0) {
+            throw new SolariError(`Solari: timeoutMs must be a non-negative number of milliseconds, got ${String(timeoutMs)}`);
+        }
         if (this.hooks.exec &&
             !opts.background &&
             !opts.onStdout &&
             !opts.onStderr &&
             !opts.env &&
             !opts.user &&
+            timeoutMs >= MIN_REST_TIMEOUT_MS &&
+            timeoutMs <= DEFAULT_COMMAND_TIMEOUT_MS &&
             !this.channel.connected) {
             try {
-                return await this.hooks.exec(this.id, {
+                const r = await this.hooks.exec(this.id, {
                     cmd,
                     args: opts.args,
                     cwd: opts.cwd,
-                    timeoutMs: opts.timeoutMs,
+                    timeoutMs,
                 });
+                return { ...r, timedOut: r.timedOut === true };
             }
             catch (err) {
-                // Fall back to the WS path ONLY when the one-shot route is unavailable
-                // (an older gateway without /exec). Any other failure — including a
-                // real host/command error — propagates, so we never silently
-                // double-execute a command that may have already run guest-side.
                 if (!isRouteUnavailable(err))
-                    throw err;
+                    throw normalizeExecError(err, timeoutMs);
             }
         }
         const acc = { stdout: "", stderr: "" };
-        const handle = await this.startCommand(cmd, opts, acc);
+        const handle = await this.startCommand(cmd, { ...opts, timeoutMs: undefined }, acc);
         if (opts.background) {
-            // Detached: don't block on exit. Caller drives via callbacks/handle.
-            return { exitCode: 0, stdout: "", stderr: "" };
+            return { exitCode: 0, stdout: "", stderr: "", timedOut: false };
         }
-        // `timeoutMs` is a deadline for the command, as on the REST /exec path: when it elapses
-        // the command is killed and the result is exit -1 with whatever output arrived (the
-        // guest's own timeout result). Without this a hung command waited forever here.
-        if (opts.timeoutMs !== undefined && opts.timeoutMs > 0) {
+        if (timeoutMs > 0) {
             let timer;
             const timedOut = new Promise((resolve) => {
-                timer = setTimeout(() => resolve("timeout"), opts.timeoutMs);
+                timer = setTimeout(() => resolve("timeout"), timeoutMs);
             });
-            // Keep a late rejection (channel closed after we gave up) from becoming unhandled.
             const exited = handle.wait().then((code) => ({ code }), (err) => ({ err }));
             const first = await Promise.race([exited, timedOut]);
             clearTimeout(timer);
             if (first === "timeout") {
                 await handle.kill(9).catch(() => undefined);
-                return { exitCode: -1, stdout: acc.stdout, stderr: acc.stderr };
+                return { exitCode: -1, stdout: acc.stdout, stderr: acc.stderr, timedOut: true };
             }
             if ("err" in first)
                 throw first.err;
-            return { exitCode: first.code, stdout: acc.stdout, stderr: acc.stderr };
+            return { exitCode: first.code, stdout: acc.stdout, stderr: acc.stderr, timedOut: false };
         }
         const exitCode = await handle.wait();
-        return { exitCode, stdout: acc.stdout, stderr: acc.stderr };
+        return { exitCode, stdout: acc.stdout, stderr: acc.stderr, timedOut: false };
     }
-    // --- pty ------------------------------------------------------------------
     pty = {
-        /** Open a PTY; output streams as `pty.data` frames. */
         create: (opts) => this.createPty(opts),
     };
     async createPty(opts) {
@@ -277,12 +232,6 @@ export class SessionHandle {
         });
         const ptyId = r.ptyId;
         const dataCbs = [];
-        // Output that arrives before the first onData() (e.g. a shell prompt printed
-        // right after pty.create) is held and replayed to the first subscriber, in
-        // order, instead of being dropped. The hold is capped at PTY_EARLY_BUFFER_MAX
-        // bytes in total: when a PTY nobody subscribes to keeps writing, the OLDEST
-        // output is discarded so client memory stays bounded and the newest output is
-        // what a late subscriber sees.
         let buffered = [];
         let bufferedBytes = 0;
         this.channel.onFrame("pty.data", ptyId, (f) => {
@@ -308,8 +257,6 @@ export class SessionHandle {
                 .call("pty.resize", { ptyId, cols, rows })
                 .then(() => undefined),
             onData: (cb) => {
-                // Detach the held output BEFORE replaying it, so a callback that throws
-                // cannot leave it behind for the next subscriber to receive twice.
                 const early = buffered;
                 buffered = [];
                 bufferedBytes = 0;
@@ -325,11 +272,6 @@ export class SessionHandle {
             },
         };
     }
-    // --- runCode --------------------------------------------------------------
-    /**
-     * Run code in a stateful kernel (`code.run`). Rich outputs (png/html/json/…)
-     * come back as `results` items; `onStdout`/`onStderr` receive streamed text.
-     */
     async runCode(code, opts = {}) {
         const r = await this.channel.call("code.run", {
             code,
@@ -348,12 +290,10 @@ export class SessionHandle {
             .map((i) => i.chart);
         return { results, charts, ...(r.error !== undefined ? { error: r.error } : {}) };
     }
-    /** Create a fresh stateful kernel context (`code.context.create`). */
     async createCodeContext(language = "python") {
         const r = await this.channel.call("code.context.create", { language });
         return r.contextId;
     }
-    // --- files ----------------------------------------------------------------
     files = {
         read: async (path) => {
             const r = await this.channel.call("fs.read", { path });
@@ -382,15 +322,10 @@ export class SessionHandle {
         mkdir: (path) => this.channel
             .call("fs.mkdir", { path })
             .then(() => undefined),
-        /** Recursively grep `query` under `path`. */
         search: async (path, query, maxResults) => {
             const r = await this.channel.call("fs.search", { path, query, maxResults });
             return r.matches ?? [];
         },
-        /**
-         * Watch `path` for changes; `cb` is invoked for each `fs.event` frame.
-         * Returns an unwatch function.
-         */
         watch: async (path, cb, recursive = false) => {
             const r = await this.channel.call("fs.watch", {
                 path,
@@ -398,8 +333,6 @@ export class SessionHandle {
             });
             const watchId = r.watchId;
             this.channel.onFrame("fs.event", watchId, (f) => {
-                // `f.type` is always the frame type ("fs.event"); the change kind
-                // (create|write|remove|rename|chmod) is in `f.event`.
                 cb({ type: String(f.event ?? "change"), path: String(f.path ?? "") });
             });
             return async () => {
@@ -407,77 +340,47 @@ export class SessionHandle {
                 await this.channel.call("fs.unwatch", { watchId });
             };
         },
-        /** Upload local bytes to an in-guest path (chunked base64 under the hood). */
         upload: (path, data) => this.channel
             .call("fs.upload", { path, base64: toB64(data) })
             .then(() => undefined),
-        /** Download an in-guest file's bytes. */
         download: (path) => downloadAll((method, params) => this.channel.call(method, params), path),
     };
-    // --- env ------------------------------------------------------------------
-    /** Inject/replace per-session env vars in the guest (`setEnv`). */
     env(vars) {
         return this.channel
             .call("setEnv", { env: vars })
             .then(() => undefined);
     }
-    /** Signed, time-limited URL to download an in-guest file directly over HTTP
-     *  (bypasses the control channel — good for large files). */
     downloadUrl(path) {
         if (!this.hooks.downloadUrl) {
             return Promise.reject(new Error("downloadUrl requires a client-created handle"));
         }
         return this.hooks.downloadUrl(this.id, path);
     }
-    /** Signed, time-limited URL to upload a file into the guest directly over
-     *  HTTP. `path` is the destination (optional; some backends return a prefix). */
     uploadUrl(path) {
         if (!this.hooks.uploadUrl) {
             return Promise.reject(new Error("uploadUrl requires a client-created handle"));
         }
         return this.hooks.uploadUrl(this.id, path);
     }
-    // --- volumes --------------------------------------------------------------
     volumes = {
-        /**
-         * Mount a volume into the guest at `path`. Thin pass-through to the guest
-         * `volume.mount` RPC; the gateway volume routes may be a 501 stub today.
-         */
         mount: (volId, path) => this.channel
             .call("volume.mount", { volumeId: volId, path })
             .then(() => undefined),
     };
-    // --- git ------------------------------------------------------------------
-    // A first-class version-control surface (Daytona-parity). Every method is a
-    // safe, non-shell `git` invocation over the existing command RPC (`cmd` +
-    // `args`, never a shell string), so there is no injection surface and it runs
-    // against any guest that has `git` on PATH — which the base image ships. No
-    // guest/gateway change is required.
     git = {
-        /** Clone `url` into `opts.path` (or git's default dir) under `opts.cwd`. */
         clone: (url, opts = {}) => this.gitClone(url, opts),
-        /** Parsed working-tree status (branch, ahead/behind, staged/modified/untracked). */
         status: (cwd) => this.gitStatus(cwd),
-        /** Stage `paths` (use `["."]` for everything). */
         add: (paths, cwd) => this.gitAdd(paths, cwd),
-        /** Commit staged changes; returns the new commit hash. */
         commit: (message, opts = {}) => this.gitCommit(message, opts),
-        /** Push to a remote (default `origin` + current branch). */
         push: (opts = {}) => this.gitPushPull("push", opts),
-        /** Pull from a remote (default `origin` + current branch). */
         pull: (opts = {}) => this.gitPushPull("pull", opts),
-        /** Check out an existing ref, or create a branch with `{ create: true }`. */
         checkout: (ref, opts = {}) => this.gitCheckout(ref, opts),
-        /** List local branches (name, short commit, whether it's HEAD). */
         branches: (cwd) => this.gitBranches(cwd),
-        /** Recent commits, newest first. */
         log: (opts = {}) => this.gitLog(opts),
     };
-    /** Run `git <args>` in the guest via the command RPC (no shell). */
     async runGit(args, cwd) {
         return this.runCommand("git", { args, ...(cwd ? { cwd } : {}) });
     }
-    /** Run `git <args>`; throw with the stderr on a non-zero exit. */
     async mustGit(args, cwd) {
         const r = await this.runGit(args, cwd);
         if (r.exitCode !== 0) {
@@ -486,7 +389,6 @@ export class SessionHandle {
         }
         return r.stdout;
     }
-    /** Splice basic-auth creds into an https remote URL (for private remotes). */
     authUrl(url, username, password) {
         if (!username && !password)
             return url;
@@ -499,7 +401,7 @@ export class SessionHandle {
             return u.toString();
         }
         catch {
-            return url; // ssh/scp-style or malformed — leave untouched
+            return url;
         }
     }
     async gitClone(url, opts) {
@@ -533,7 +435,6 @@ export class SessionHandle {
                     st.detached = true;
                 }
                 else {
-                    // "main...origin/main [ahead 1, behind 2]" | "main" | "No commits yet on main"
                     const noCommits = head.match(/^No commits yet on (.+)$/);
                     const body = noCommits?.[1] ?? head;
                     st.branch = (body.split("...")[0] ?? "").split(" ")[0] ?? "";
@@ -573,8 +474,6 @@ export class SessionHandle {
         await this.mustGit(["add", "--", ...paths], cwd);
     }
     async gitCommit(message, opts) {
-        // `-c user.name/email` scopes identity to this one commit without mutating
-        // the repo/global config — handy in an ephemeral sandbox with no git identity.
         const args = [];
         if (opts.author)
             args.push("-c", `user.name=${opts.author}`);
@@ -589,8 +488,6 @@ export class SessionHandle {
     }
     async gitPushPull(op, opts) {
         const remote = opts.remote || "origin";
-        // One-off HTTPS auth without persisting a credential: rewrite the remote's
-        // URL for just this invocation via `-c url.<authed>.insteadOf=<plain>`.
         const cfg = [];
         if (opts.username || opts.password) {
             const plain = (await this.runGit(["remote", "get-url", remote], opts.cwd)).stdout.trim();
@@ -613,8 +510,6 @@ export class SessionHandle {
         await this.mustGit(args, opts.cwd);
     }
     async gitBranches(cwd) {
-        // A stable, parse-friendly format (unit-separated) instead of the porcelain
-        // `* main` layout, so branch names with spaces/`*` never confuse the parser.
         const out = await this.mustGit(["branch", "--format=%(HEAD)%1f%(refname:short)%1f%(objectname:short)"], cwd);
         const branches = [];
         for (const line of out.split("\n")) {
@@ -645,15 +540,12 @@ export class SessionHandle {
         }
         return commits;
     }
-    // --- lifecycle / admin (gateway-routed via hooks) -------------------------
-    /** Live resource metrics. */
     metrics() {
         if (!this.hooks.metrics) {
             return Promise.reject(new Error("metrics requires a client-created handle"));
         }
         return this.hooks.metrics(this.id);
     }
-    /** Checkpoint this RUNNING session; it keeps running. Returns the snapshot id. */
     async snapshot(name) {
         if (!this.hooks.snapshot) {
             throw new Error("snapshot requires a client-created handle");
@@ -661,22 +553,24 @@ export class SessionHandle {
         const r = await this.hooks.snapshot(this.id, name);
         return r.snapshotId;
     }
-    /** Restore this session in place from a snapshot (id stays stable). */
     revert(snapshotId) {
         if (!this.hooks.revert) {
             return Promise.reject(new Error("revert requires a client-created handle"));
         }
-        return this.hooks.revert(this.id, snapshotId);
+        return this.hooks.revert(this.id, snapshotId).then(async () => {
+            if (this.channel.connected) {
+                this.close({ quiet: true });
+                await this.channel.connect().catch(() => undefined);
+            }
+        });
     }
-    /** Pause (snapshot RAM+disk, free the slot). Closes the control channel. */
     async pause() {
         if (!this.hooks.pause) {
             throw new Error("pause requires a client-created handle");
         }
         await this.hooks.pause(this.id);
-        this.close();
+        this.close({ quiet: true });
     }
-    /** Resume a paused session; re-points the control channel at the fresh slot. */
     async resume() {
         if (!this.hooks.resume) {
             throw new Error("resume requires a client-created handle");
@@ -685,17 +579,6 @@ export class SessionHandle {
         this.channel.setControlUrl(r.controlUrl);
         await this.channel.reconnect();
     }
-    /**
-     * Start a **stopped** sandbox (its guest powered itself off) from the disk the
-     * host kept, and re-point the control channel at the fresh `controlUrl`.
-     *
-     * This is a cold boot, not a resume: running processes and memory are gone,
-     * files on disk are kept. Use {@link resume} for a paused sandbox. Idempotent:
-     * a sandbox that is already running just reconnects. Throws
-     * {@link SandboxNotStoppedError} (`409 NotStopped` / `StartInProgress`) for any
-     * other state; if the start fails the sandbox stays stopped with its disk, so
-     * you can call this again.
-     */
     async start() {
         if (!this.hooks.start) {
             throw new Error("start requires a client-created handle");
@@ -704,79 +587,50 @@ export class SessionHandle {
         this.channel.setControlUrl(r.controlUrl);
         await this.channel.reconnect();
     }
-    /**
-     * Park (deschedule) this session: freeze the guest's vCPUs while leaving its
-     * RAM resident on the same host. Milliseconds to park, milliseconds to wake.
-     *
-     * Unlike {@link pause}, this does NOT close the control channel and does not
-     * free the slot -- the session keeps its host, its ports and its routing, so
-     * anything already pointing at it keeps working. There is no need to call
-     * {@link unpark} first: exec, the control/stream channels, port preview and
-     * signed file reads all wake a parked session automatically.
-     *
-     * Use it around a long LLM or tool call to stop paying for vCPU you are not
-     * using. For hands-off behaviour set `lifecycle.parkAfterMs` at create time
-     * instead and the gateway parks on an idle timer.
-     */
     async park() {
         if (!this.hooks.park) {
             throw new Error("park requires a client-created handle");
         }
         await this.hooks.park(this.id);
     }
-    /**
-     * Wake a parked session explicitly. Rarely needed -- every normal request
-     * path unparks on touch -- but lets a caller pay the (millisecond) wake up
-     * front rather than on the next real request.
-     */
     async unpark() {
         if (!this.hooks.unpark) {
             throw new Error("unpark requires a client-created handle");
         }
         await this.hooks.unpark(this.id);
     }
-    /** Extend the idle/keep-alive window. */
     setTimeout(timeoutMs) {
         if (!this.hooks.setTimeout) {
             return Promise.reject(new Error("setTimeout requires a client-created handle"));
         }
         return this.hooks.setTimeout(this.id, timeoutMs);
     }
-    /**
-     * Resolve a public preview URL for an in-guest port (e.g. a dev server on
-     * `:3000`). Returns the routable `https://` URL and, when the gateway signs
-     * one, an access `token`.
-     */
     previewUrl(port) {
         if (!this.hooks.previewUrl) {
             return Promise.reject(new Error("previewUrl requires a client-created handle"));
         }
         return this.hooks.previewUrl(this.id, port);
     }
-    /** Destroy the remote session and close the channel. Idempotent. */
+    async [Symbol.asyncDispose ?? Symbol.for("Symbol.asyncDispose")]() {
+        await this.kill();
+    }
     async kill() {
         if (this.hooks.kill)
             await this.hooks.kill(this.id);
-        // Mark first: close() warns about a still-running machine, which is exactly
-        // wrong once we have just released it.
         this.killed = true;
         this.close();
     }
 }
-/**
- * Add the missing explanation to a failed exec that looks like a shell line.
- *
- * `commands.run(cmd, {args})` exec's `cmd` directly — no shell — which is what
- * makes it injection-safe: nothing in `args` can be reinterpreted as a shell
- * metacharacter. The cost is that `run("ls -la")` looks up a binary literally
- * named `ls -la` and the guest answers "no such file or directory", which reads
- * like a missing tool rather than a misused argument.
- *
- * We do NOT reject such a call up front. Rejecting would be a breaking change
- * for anyone doing it today, and the complaint was never that the call was
- * accepted — it was that the failure did not say why. So let it run, and if it
- * fails the way a shell line fails, explain it.
- */
+function normalizeExecError(err, timeoutMs) {
+    if (err instanceof GatewayError) {
+        if (err.status === 400 && err.code === "ExecFailed")
+            return new ActionError("cmd.start", err.message, err.code);
+        if (err.status === 502 && /i\/o timeout/.test(err.message)) {
+            return new TimeoutError("cmd.run", timeoutMs);
+        }
+    }
+    return err;
+}
 function explainShellCommandFailure(cmd, err) {
     const msg = err instanceof Error ? err.message : String(err);
     if (!/no such file or directory|ENOENT|not found/i.test(msg))
@@ -785,20 +639,19 @@ function explainShellCommandFailure(cmd, err) {
     if (!/\s/.test(trimmed))
         return err;
     const [head = trimmed, ...rest] = trimmed.split(/\s+/);
+    const viaShell = `run("sh", { args: ["-lc", ${JSON.stringify(trimmed)}] })`;
+    const split = /['"\\$`|&;<>*?()]/.test(trimmed)
+        ? ""
+        : `Pass the arguments separately: run(${JSON.stringify(head)}, { args: ${JSON.stringify(rest)} }), or `;
     const hint = ` — commands.run() executes the binary directly and does not interpret a ` +
         `shell line, so ${JSON.stringify(cmd)} was looked up as a single filename. ` +
-        `Pass the arguments separately: run(${JSON.stringify(head)}, { args: ` +
-        `${JSON.stringify(rest)} }), or run it through a shell explicitly: ` +
-        `run("sh", { args: ["-lc", ${JSON.stringify(trimmed)}] }).`;
+        `${split}${split ? "run" : "Run"} it through a shell explicitly: ${viaShell}.`;
     if (err instanceof Error) {
         err.message += hint;
         return err;
     }
     return new Error(msg + hint);
 }
-/** True when an error means the one-shot `/exec` route isn't served (an older
- *  gateway) — the only case where `runCommand` retries over the control WS. A
- *  real host/command failure is NOT route-unavailable and must propagate. */
 function isRouteUnavailable(err) {
     return (err instanceof GatewayError &&
         (err.status === 404 || err.status === 405 || err.status === 501));
@@ -807,4 +660,3 @@ function toB64(data) {
     const bytes = typeof data === "string" ? new TextEncoder().encode(data) : data;
     return bytesToBase64(bytes);
 }
-//# sourceMappingURL=handle.js.map