skydive-cli 0.1.0-beta.353 → 0.1.0-beta.378

package/README.md

@@ -8,9 +8,45 @@ npx skydive-cli --help
 
 ## Authentication
 
-The CLI has two credentials, stored together in a single `config.json`. The
-location is platform-conventional (resolved via `env-paths`), so it is **not**
-`~/.config/skydive/` everywhere:
+Sign in once via the browser — the same shape as `doppler login`: the CLI
+opens the approval page, shows a short code, waits for you to approve, and
+then automatically mints an API key for this machine:
+
+```sh
+skydive auth login
+```
+
+That single flow yields both credentials the CLI uses, stored together in a
+single `config.json`:
+
+- an **API key** (`sky_live_…`) named after this machine and the workspace it
+  was minted in (`CLI (host) — Acme`) — the durable credential for the
+  management commands (`agents`, `keys`, `secrets`). Logging in again from the
+  same machine replaces it rather than accumulating rows, and
+  `skydive auth logout` revokes it, so signing out doesn't leave a live key
+  behind. The workspace is in the name because the key is pinned to it: unlike
+  the session, a key never follows `workspace switch`.
+- a **user session** for `skydive chat`. Chat is user-level and multi-agent,
+  so it authenticates as you — and unlike the API key (which is pinned to the
+  workspace that minted it), the session follows `skydive workspace switch`.
+  The management commands prefer the session while it's valid and fall back
+  to the API key.
+
+The flow doesn't require a TTY: in a non-interactive shell (an agent harness,
+SSH without a display) `auth login` still prints the verification URL + code
+and waits — open the link in any browser to approve. For unattended CI, skip
+the wait entirely and pass an existing key (mint one at
+`skydive.com/settings/account`):
+
+```sh
+skydive auth login --api-key sky_live_…   # or set SKYDIVE_API_KEY
+```
+
+`skydive auth status` shows both credentials; `skydive auth logout` revokes
+the auto-minted key and clears them.
+
+The config location is platform-conventional (resolved via `env-paths`), so
+it is **not** `~/.config/skydive/` everywhere:
 
 | Platform | Path                                                             |
 | -------- | ---------------------------------------------------------------- |
@@ -21,29 +57,6 @@ location is platform-conventional (resolved via `env-paths`), so it is **not**
 `skydive auth status` prints the real resolved path (`Config: …`) — trust that
 over this table if they ever disagree.
 
-- **API key** (`sky_live_…`). Mint one at `skydive.com/settings/account`, then:
-
-  ```sh
-  skydive auth login            # paste the key
-  ```
-
-- **User session** for `skydive chat`. Chat is user-level and multi-agent,
-  so it signs you in via the browser (device flow) rather than a per-agent
-  API key. `skydive chat` does this automatically on first run; you can also
-  do it up front:
-
-  ```sh
-  skydive auth login --web      # opens the browser, prompts for approval
-  ```
-
-Either credential authenticates the management commands (`agents`, `keys`,
-`secrets`): the CLI prefers the API key and falls back to the `--web` chat
-session, so a `--web` login alone is enough to run them — you do **not** need a
-separate API key. The API key is only required when you have no chat session
-(e.g. CI). `skydive chat` requires the chat session specifically.
-
-`skydive auth status` shows both; `skydive auth logout` clears them.
-
 ## Commands
 
 ```sh
@@ -164,7 +177,7 @@ skydive chat -p "status?" --agent grace --json               # structured envelo
 - `--conversation <id>` continues an existing thread; omitted, it starts a new
   one. The conversation id is included in `--json` output for chaining.
 - `-p` needs a user session just like `chat`, but never opens the interactive
-  browser login — sign in first with `skydive auth login --web` or set
+  browser login — sign in first with `skydive auth login` or set
   `SKYDIVE_SESSION_TOKEN`.
 - `--json` prints `{ agentId, agentName, conversationId, isNewConversation,
 messageId, text }` instead of streaming the raw text.

package/dist/js/bin.mjs

@@ -2,7 +2,7 @@
 import { t as __exportAll } from "./rolldown-runtime-Cz4Tg37Z.mjs";
 import { hideBin } from "yargs/helpers";
 import yargs from "yargs";
-import { createInterface } from "node:readline";
+import os, { hostname } from "node:os";
 import path from "node:path";
 import Conf from "conf";
 import { err, ok } from "neverthrow";
@@ -13,10 +13,10 @@ import { spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import fs from "node:fs";
 import zlib from "node:zlib";
-import os from "node:os";
+import { WebSocket } from "ws";
 
 //#region package.json
-var version$1 = "0.1.0-beta.353";
+var version$1 = "0.1.0-beta.378";
 
 //#endregion
 //#region src/types.ts
@@ -56,10 +56,18 @@ const DEFAULT_WEB_URL = "https://skydive.com";
 function resolveWebUrl(appUrl) {
 	return appUrl === DEFAULT_APP_URL ? DEFAULT_WEB_URL : appUrl;
 }
-/** Prefix on every Skydive API key. Kept in sync with the API's
+/** Prefix on workspace-scoped Skydive API keys. Kept in sync with the API's
 * `API_KEY_PREFIX` (`apps/anyone/api/src/lib/api-key.ts`); the CLI is a
 * standalone published package so it can't import the backend constant. */
 const API_KEY_PREFIX = "sky_live_";
+/**
+* Common prefix across all Skydive API key kinds — `sky_live_…` workspace
+* keys today, `sky_user_…` account keys when ANY-5105 lands. The CLI only
+* sanity-checks the family on `--api-key`; the server authoritatively rejects
+* a kind that can't drive a given route, with a clearer message than the
+* client could produce.
+*/
+const API_KEY_FAMILY_PREFIX = "sky_";
 /** Where users mint and copy API keys. Shown in the login prompt. */
 const API_KEYS_URL = "skydive.com/settings/account";
 const store = new Conf({
@@ -78,9 +86,9 @@ function resolveConfig(opts) {
 }
 /**
 * Resolve the bearer credential for the management API (`agents` / `keys` /
-* `secrets`). The server's `/v1` gate accepts either an API key or the `--web`
-* session bearer, so both work — but only one of them tracks the active
-* workspace.
+* `secrets`). The server's `/v1` gate accepts either an API key or the
+* device-flow session bearer, so both work — but only one of them tracks the
+* active workspace.
 *
 * An API key is pinned server-side to the organization that minted it and
 * ignores the workspace header by design, so it can never follow `skydive
@@ -104,11 +112,17 @@ function resolveManagementAuth(opts) {
 		apiUrl: process.env["SKYDIVE_API_URL"] ?? opts.apiUrl ?? store.get("apiUrl") ?? DEFAULT_API_URL,
 		kind: "api-key"
 	});
-	return err({ message: "Not authenticated. Run `skydive auth login` (API key) or `skydive auth login --web`." });
+	return err({ message: "Not authenticated. Run `skydive auth login`." });
 }
 function saveConfig(config) {
 	store.set("apiKey", config.apiKey);
 	store.set("apiUrl", config.apiUrl);
+	if (config.apiKeyId) store.set("apiKeyId", config.apiKeyId);
+	else store.delete("apiKeyId");
+}
+/** Server-side id of the auto-minted key, if login minted one. */
+function getStoredApiKeyId() {
+	return store.get("apiKeyId") ?? null;
 }
 function deleteConfig() {
 	store.clear();
@@ -320,7 +334,7 @@ var SkydiveApiClient = class {
 				if (body.error && typeof body.error === "string") message = body.error;
 				else if (body.error?.message) message = body.error.message;
 			} catch {}
-			if (response.status === 401 && this.authKind === "session") message = `${message} — your chat session may have expired. Run \`skydive auth login --web\`.`;
+			if (response.status === 401 && this.authKind === "session") message = `${message} — your chat session may have expired. Run \`skydive auth login\`.`;
 			return err({
 				message,
 				status: response.status
@@ -647,6 +661,94 @@ function sleep$1(ms) {
 	return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
+//#endregion
+//#region src/auth/mint-key.ts
+const mintedKeySchema = z.object({
+	id: z.string(),
+	name: z.string(),
+	prefix: z.string(),
+	key: z.string()
+});
+/**
+* Mint an org-scoped (account-level) API key off a fresh device-flow session,
+* so `auth login` ends with a durable machine credential the way
+* `doppler login` does. Calls the same internal endpoint the web settings page
+* uses; no `agentId` is sent, so the key is account-level, not agent-bound.
+*
+* Scopes are `use` + `edit` because the management commands the key powers
+* (`agents create`, `keys create`, `secrets set`) are edit-tier operations.
+*/
+async function mintCliApiKey({ appUrl, sessionToken, name }) {
+	try {
+		const res = await fetch(`${appUrl}/api/v1/api-keys`, {
+			method: "POST",
+			headers: {
+				authorization: `Bearer ${sessionToken}`,
+				"content-type": "application/json"
+			},
+			body: JSON.stringify({
+				name,
+				scopes: ["use", "edit"]
+			})
+		});
+		if (!res.ok) return err({ message: `failed to mint API key (${res.status})` });
+		const parsed = mintedKeySchema.safeParse(await res.json());
+		if (!parsed.success) return err({ message: "unexpected mint response" });
+		return ok(parsed.data);
+	} catch (e) {
+		return err({ message: e instanceof Error ? e.message : String(e) });
+	}
+}
+const keyListSchema = z.object({ keys: z.array(z.object({
+	id: z.string(),
+	name: z.string(),
+	agentId: z.string().nullish()
+})) });
+/**
+* Revoke every active account-level key with the given name. Login calls this
+* before minting so repeated logins from the same machine + workspace replace
+* their key instead of piling up indistinguishable rows (`logout`'s revoke is
+* best-effort, and login-without-logout is the normal case — a wiped
+* container, an expired session). Agent-scoped keys are never touched even on
+* a name collision.
+*/
+async function revokeKeysByName({ appUrl, sessionToken, name }) {
+	try {
+		const res = await fetch(`${appUrl}/api/v1/api-keys`, { headers: { authorization: `Bearer ${sessionToken}` } });
+		if (!res.ok) return err({ message: `failed to list API keys (${res.status})` });
+		const parsed = keyListSchema.safeParse(await res.json());
+		if (!parsed.success) return err({ message: "unexpected key list response" });
+		const matches = parsed.data.keys.filter((key) => key.name === name && !key.agentId);
+		const failures = (await Promise.all(matches.map((key) => revokeApiKey({
+			appUrl,
+			token: sessionToken,
+			id: key.id
+		})))).filter((result) => result.isErr());
+		if (failures.length > 0) return err({ message: `failed to revoke ${failures.length} of ${matches.length} existing keys` });
+		return ok(matches.length);
+	} catch (e) {
+		return err({ message: e instanceof Error ? e.message : String(e) });
+	}
+}
+/**
+* Revoke an API key by id. Used by `auth logout` to clean up the key that
+* login auto-minted, so signing out on a machine doesn't leave a live
+* credential behind. `token` may be a session bearer or an API key — the
+* server accepts both on this route.
+*/
+async function revokeApiKey({ appUrl, token, id }) {
+	try {
+		const res = await fetch(`${appUrl}/api/v1/api-keys/${id}`, {
+			method: "DELETE",
+			headers: { authorization: `Bearer ${token}` }
+		});
+		if (!res.ok && res.status !== 404) return err({ message: `failed to revoke API key (${res.status})` });
+		return ok(void 0);
+	} catch (e) {
+		return err({ message: e instanceof Error ? e.message : String(e) });
+	}
+}
+
 //#endregion
 //#region src/output.ts
 function output(argv, data) {
@@ -676,99 +778,160 @@ function printError(message) {
 //#region src/commands/auth.ts
 const loginCommand = {
 	command: "login",
-	describe: "Authenticate with a Skydive API key (or --web for chat)",
+	describe: "Sign in via the browser (use --api-key for CI / headless)",
 	builder: (y) => y.option("api-key", {
 		type: "string",
-		describe: `API key (${API_KEY_PREFIX}...)`
+		describe: `Skip the browser and authenticate with an existing API key (${API_KEY_PREFIX}...)`
 	}).option("web", {
 		type: "boolean",
 		default: false,
-		describe: "Sign in for `skydive chat` via the browser (device flow) instead of an API key"
+		hidden: true,
+		describe: "Deprecated: browser sign-in is now the default"
 	}),
 	handler: async (argv) => {
-		if (argv.web) {
-			await runWebLogin(argv);
+		if (argv["api-key"]) {
+			await runApiKeyLogin(argv, argv["api-key"]);
 			return;
 		}
-		let apiKey = argv["api-key"] ?? process.env["SKYDIVE_API_KEY"];
-		if (!apiKey) {
-			const rl = createInterface({
-				input: process.stdin,
-				output: process.stderr
-			});
-			apiKey = await new Promise((resolve) => {
-				rl.question(`Enter your API key (from ${API_KEYS_URL}): `, (answer) => {
-					rl.close();
-					resolve(answer.trim());
-				});
-			});
-		}
-		if (!apiKey) {
-			printError("No API key provided.");
-			process.exit(1);
-		}
-		if (!apiKey.startsWith(API_KEY_PREFIX)) {
-			printError(`API key must start with ${API_KEY_PREFIX}`);
-			process.exit(1);
-		}
-		const apiUrl = argv["api-url"] ?? DEFAULT_API_URL;
-		const result = await new SkydiveApiClient({
-			token: apiKey,
-			apiUrl,
-			kind: "api-key"
-		}).listAgents({
-			limit: 1,
-			scope: null
-		});
-		if (result.isErr()) {
-			printError(`Invalid API key or unreachable server: ${result.error.message}`);
-			process.exit(1);
+		if (isNonInteractive()) {
+			const envKey = process.env["SKYDIVE_API_KEY"];
+			if (envKey) {
+				await runApiKeyLogin(argv, envKey);
+				return;
+			}
 		}
-		saveConfig({
-			apiKey,
-			apiUrl
-		});
-		if (argv.json) output(argv, {
+		await runBrowserLogin(argv);
+	}
+};
+/**
+* Browser sign-in, shaped like `doppler login`: open the approval page with a
+* short code, wait for the user to approve, then automatically mint an API
+* key for this machine. One flow yields both credentials — the session (chat,
+* workspace-following management calls) and a durable `sky_live_…` key that
+* keeps headless/management use working after the session expires.
+*
+* Deliberately no TTY requirement: the flow only prints the verification URL
+* + code and polls, so it also works from a non-interactive shell — an agent
+* driving the CLI relays the URL to its human, who approves in any browser
+* (the auto-open is best-effort). The cost is that an unattended run with no
+* key configured waits out the device code's expiry instead of failing fast.
+*/
+async function runBrowserLogin(argv) {
+	const appUrl = resolveAppUrl({ appUrl: argv["api-url"] });
+	const login = await loginWithDevice({ appUrl });
+	if (login.isErr()) {
+		printError(login.error.message);
+		process.exit(1);
+	}
+	const { sessionToken } = login.value;
+	const identity = (await getSessionIdentity({
+		appUrl,
+		sessionToken
+	})).unwrapOr(null);
+	const keyName = identity?.activeWorkspaceName ? `CLI (${hostname()}) — ${identity.activeWorkspaceName}` : `CLI (${hostname()})`;
+	const replaced = await revokeKeysByName({
+		appUrl,
+		sessionToken,
+		name: keyName
+	});
+	if (replaced.isErr()) process.stderr.write(`Warning: could not revoke this machine's previous API key (${replaced.error.message}); minting a new one anyway.\n`);
+	const minted = await mintCliApiKey({
+		appUrl,
+		sessionToken,
+		name: keyName
+	});
+	if (minted.isOk()) saveConfig({
+		apiKey: minted.value.key,
+		apiUrl: appUrl,
+		apiKeyId: minted.value.id
+	});
+	else process.stderr.write(`Warning: signed in, but could not mint an API key (${minted.error.message}). Management commands will use your session; run \`skydive auth login\` again to retry.
+`);
+	if (argv.json) {
+		output(argv, {
 			authenticated: true,
-			prefix: apiKey.slice(0, 12),
+			mode: "browser",
+			appUrl,
+			prefix: minted.isOk() ? minted.value.prefix : null,
+			email: identity?.email ?? null,
+			workspaceName: identity?.activeWorkspaceName ?? null,
 			configPath: getConfigPath()
 		});
-		else if (!argv.quiet) {
-			console.log(`Authenticated successfully.`);
-			console.log(`  Key:    ${apiKey.slice(0, 12)}...`);
-			console.log(`  Config: ${getConfigPath()}`);
-		}
+		return;
 	}
-};
-async function runWebLogin(argv) {
-	if (isNonInteractive()) {
-		printError("`auth login --web` needs an interactive terminal. Set SKYDIVE_SESSION_TOKEN for non-interactive use.");
+	if (argv.quiet) return;
+	const who = identity?.name ?? identity?.email;
+	console.log(who ? `Welcome, ${who}!` : "Signed in.");
+	if (identity?.activeWorkspaceName) console.log(`  Workspace: ${identity.activeWorkspaceName}`);
+	if (minted.isOk()) console.log(`  API key:   ${minted.value.prefix}… (${minted.value.name})`);
+	console.log(`  Config:    ${getConfigPath()}`);
+}
+/** CI / headless path: validate and persist an existing key, no browser. */
+async function runApiKeyLogin(argv, apiKey) {
+	if (!apiKey.startsWith(API_KEY_FAMILY_PREFIX)) {
+		printError(`API key must start with ${API_KEY_FAMILY_PREFIX}`);
 		process.exit(1);
 	}
-	const result = await loginWithDevice({ appUrl: resolveAppUrl({ appUrl: argv["api-url"] }) });
+	const apiUrl = argv["api-url"] ?? DEFAULT_API_URL;
+	const result = await new SkydiveApiClient({
+		token: apiKey,
+		apiUrl,
+		kind: "api-key"
+	}).listAgents({
+		limit: 1,
+		scope: null
+	});
 	if (result.isErr()) {
-		printError(result.error.message);
+		printError(`Invalid API key or unreachable server: ${result.error.message}`);
 		process.exit(1);
 	}
+	saveConfig({
+		apiKey,
+		apiUrl,
+		apiKeyId: null
+	});
 	if (argv.json) output(argv, {
 		authenticated: true,
-		mode: "session",
-		appUrl: result.value.appUrl,
+		prefix: apiKey.slice(0, 12),
 		configPath: getConfigPath()
 	});
 	else if (!argv.quiet) {
-		console.log("Signed in for chat.");
-		console.log(`  App:    ${result.value.appUrl}`);
+		console.log(`Authenticated successfully.`);
+		console.log(`  Key:    ${apiKey.slice(0, 12)}...`);
 		console.log(`  Config: ${getConfigPath()}`);
 	}
 }
 const logoutCommand = {
 	command: "logout",
-	describe: "Clear stored credentials (API key and chat session)",
+	describe: "Revoke the auto-minted API key and clear stored credentials",
 	handler: async (argv) => {
+		const keyId = getStoredApiKeyId();
+		let keyRevoked = false;
+		if (keyId) {
+			const session = resolveSession({ appUrl: argv["api-url"] });
+			const config = resolveConfig({ apiUrl: argv["api-url"] });
+			const credential = session.isOk() ? {
+				appUrl: session.value.appUrl,
+				token: session.value.sessionToken
+			} : config.isOk() ? {
+				appUrl: config.value.apiUrl,
+				token: config.value.apiKey
+			} : null;
+			if (credential) {
+				const revoked = await revokeApiKey({
+					...credential,
+					id: keyId
+				});
+				keyRevoked = revoked.isOk();
+				if (revoked.isErr()) process.stderr.write(`Warning: could not revoke this machine's API key (${revoked.error.message}). Revoke it manually at ${API_KEYS_URL}.\n`);
+			}
+		}
 		deleteConfig();
-		if (argv.json) output(argv, { authenticated: false });
-		else if (!argv.quiet) console.log("Logged out.");
+		if (argv.json) output(argv, {
+			authenticated: false,
+			keyRevoked
+		});
+		else if (!argv.quiet) console.log(keyRevoked ? "Logged out. API key revoked." : "Logged out.");
 	}
 };
 const statusCommand$1 = {
@@ -801,7 +964,7 @@ const statusCommand$1 = {
 			return;
 		}
 		if (apiKey.isErr() && session.isErr()) {
-			console.log("Not authenticated. Run `skydive auth login` (API key) or `skydive auth login --web` (chat).");
+			console.log("Not authenticated. Run `skydive auth login`.");
 			return;
 		}
 		if (apiKey.isOk()) {
@@ -838,6 +1001,10 @@ const authCommand = {
 
 //#endregion
 //#region src/chat/api/rest.ts
+var rest_exports = /* @__PURE__ */ __exportAll({
+	HttpError: () => HttpError,
+	createRestClient: () => createRestClient
+});
 var HttpError = class extends Error {
 	constructor(status, body) {
 		super(`HTTP ${status}: ${body.slice(0, 200)}`);
@@ -1257,7 +1424,7 @@ const conversationStreamEventSchema = z.discriminatedUnion("kind", [z.object({
 function requireSession(argv) {
 	const session = resolveSession({ appUrl: resolveAppUrl({ appUrl: argv["api-url"] }) });
 	if (session.isErr()) {
-		printError(`${session.error.message} Run \`skydive auth login --web\` first, or set SKYDIVE_SESSION_TOKEN.`);
+		printError(`${session.error.message} Run \`skydive auth login\` first, or set SKYDIVE_SESSION_TOKEN.`);
 		process.exit(1);
 	}
 	return session.value;
@@ -2592,7 +2759,7 @@ const chatCommand = {
 		let session = resolveSession({ appUrl });
 		if (session.isErr()) {
 			if (isNonInteractive()) {
-				printError("Not signed in for chat and no interactive terminal. Run `skydive auth login --web`, or set SKYDIVE_SESSION_TOKEN.");
+				printError("Not signed in for chat and no interactive terminal. Run `skydive auth login`, or set SKYDIVE_SESSION_TOKEN.");
 				process.exit(1);
 			}
 			const login = await loginWithDevice({ appUrl });
@@ -2611,7 +2778,7 @@ const chatCommand = {
 			printError(`Unknown theme "${themeId}". Valid themes: ${themes.map((t) => t.id).join(", ")}`);
 			process.exit(1);
 		}
-		const { runChat } = await import("./boot-DLHvjtxn.mjs");
+		const { runChat } = await import("./boot-QnNiy1cA.mjs");
 		await runChat({
 			appUrl,
 			sessionToken: session.value.sessionToken,
@@ -2635,7 +2802,7 @@ function resolveShareMachine(argv) {
 async function runPrintMode({ argv, appUrl }) {
 	const session = resolveSession({ appUrl });
 	if (session.isErr()) {
-		printError(`${session.error.message} For non-interactive use, run \`skydive auth login --web\` first, or set SKYDIVE_SESSION_TOKEN.`);
+		printError(`${session.error.message} For non-interactive use, run \`skydive auth login\` first, or set SKYDIVE_SESSION_TOKEN.`);
 		process.exit(1);
 	}
 	const { runPrint, readStdin } = await Promise.resolve().then(() => print_exports);
@@ -2653,7 +2820,7 @@ async function runPrintMode({ argv, appUrl }) {
 	}
 	let machineShare = null;
 	if (resolveShareMachine(argv)) {
-		const { PortalClient } = await import("./client-_OL8-XGH.mjs").then((n) => n.n);
+		const { PortalClient } = await import("./client-XFsd0Wy9.mjs").then((n) => n.n);
 		let signalConnected;
 		const connected = new Promise((resolve) => {
 			signalConnected = resolve;
@@ -2723,7 +2890,7 @@ const getCommand = {
 		const appUrl = resolveAppUrl({ appUrl: argv["api-url"] });
 		const session = resolveSession({ appUrl });
 		if (session.isErr()) {
-			printError(`${session.error.message} Run \`skydive auth login --web\` first, or set SKYDIVE_SESSION_TOKEN.`);
+			printError(`${session.error.message} Run \`skydive auth login\` first, or set SKYDIVE_SESSION_TOKEN.`);
 			process.exit(1);
 		}
 		const { messageGet } = await Promise.resolve().then(() => print_exports);
@@ -3405,7 +3572,7 @@ const switchCommand = {
 				printError("The workspace picker needs the Bun runtime and it could not be set up automatically. Pass a workspace slug instead, or install Bun and retry.");
 				process.exit(1);
 			}
-			const { runWorkspacePicker } = await import("./boot-DLHvjtxn.mjs");
+			const { runWorkspacePicker } = await import("./boot-QnNiy1cA.mjs");
 			await runWorkspacePicker(session);
 			return;
 		}
@@ -3622,7 +3789,7 @@ const openCommand = {
 		const agent = argv.agent ? resolveAgent((await fetchPortalDevices(session)).agents, argv.agent) : null;
 		const cwd = argv.cwd ? path.resolve(argv.cwd) : process.cwd();
 		const { machineName } = machineIdentity();
-		const { PortalClient } = await import("./client-_OL8-XGH.mjs").then((n) => n.n);
+		const { PortalClient } = await import("./client-XFsd0Wy9.mjs").then((n) => n.n);
 		let lastLine = "";
 		let signalConnected;
 		const connected = new Promise((resolve) => {
@@ -3753,10 +3920,298 @@ const portalCommand = {
 	handler: () => {}
 };
 
+//#endregion
+//#region ../sandbox-stream-protocol/src/index.ts
+const SANDBOX_STREAM_PATH = "/api/v1/sandbox/stream";
+const FRAME = {
+	DATA: 1,
+	EXIT: 2,
+	ERROR: 3,
+	INPUT: 16,
+	RESIZE: 17
+};
+const MAX_INPUT_BYTES = 1 * 1024 * 1024;
+/** Query params for the upgrade URL, from a spec. Inverse of {@link parseStreamSpec}. */
+function streamSpecToQuery(spec) {
+	if (spec.mode === "pty") return {
+		agentId: spec.agentId,
+		mode: "pty",
+		cols: String(spec.cols),
+		rows: String(spec.rows)
+	};
+	return {
+		agentId: spec.agentId,
+		mode: "exec",
+		command: spec.command
+	};
+}
+function withType(type, payload) {
+	const frame = new Uint8Array(1 + payload.length);
+	frame[0] = type;
+	frame.set(payload, 1);
+	return frame;
+}
+/** client → server: keystroke bytes for the pty stdin. */
+function encodeInput(data) {
+	return withType(FRAME.INPUT, data);
+}
+/** client → server: the client terminal was resized. */
+function encodeResize(cols, rows) {
+	const frame = new Uint8Array(5);
+	frame[0] = FRAME.RESIZE;
+	const view = new DataView(frame.buffer);
+	view.setUint16(1, cols & 65535);
+	view.setUint16(3, rows & 65535);
+	return frame;
+}
+const view = (frame) => new DataView(frame.buffer, frame.byteOffset, frame.byteLength);
+/**
+* Decode a frame the server sent. Returns null for an empty, unknown, or
+* truncated frame — a peer speaking a newer protocol must not crash us.
+*/
+function decodeServerFrame(frame) {
+	const payload = frame.subarray(1);
+	switch (frame[0]) {
+		case FRAME.DATA: return {
+			type: "data",
+			payload
+		};
+		case FRAME.EXIT: return {
+			type: "exit",
+			code: payload.length >= 4 ? view(frame).getInt32(1) : 0
+		};
+		case FRAME.ERROR: return {
+			type: "error",
+			message: new TextDecoder().decode(payload)
+		};
+		default: return null;
+	}
+}
+
+//#endregion
+//#region src/chat/sandbox/client.ts
+function wsBase(appUrl) {
+	const base = appUrl.replace(/\/+$/, "");
+	if (base.startsWith("https://")) return `wss://${base.slice(8)}`;
+	if (base.startsWith("http://")) return `ws://${base.slice(7)}`;
+	return `wss://${base}`;
+}
+/**
+* A connected sandbox-stream session. Construct via `openSandboxStream`. Carries
+* the write side (keystrokes / resize for pty mode) and teardown.
+*/
+var SandboxStream = class SandboxStream {
+	ws;
+	closed = false;
+	constructor(ws, onEvent) {
+		this.ws = ws;
+		let ended = false;
+		const emitEnd = (event) => {
+			if (ended) return;
+			ended = true;
+			onEvent(event);
+		};
+		ws.on("message", (data, isBinary) => {
+			if (!isBinary) return;
+			const frame = decodeServerFrame(toBuffer(data));
+			if (!frame) return;
+			switch (frame.type) {
+				case "data":
+					onEvent({
+						type: "data",
+						bytes: new Uint8Array(frame.payload)
+					});
+					break;
+				case "exit":
+					emitEnd({
+						type: "exit",
+						code: frame.code
+					});
+					break;
+				case "error":
+					emitEnd({
+						type: "error",
+						message: frame.message
+					});
+					break;
+			}
+		});
+		let failure = null;
+		ws.on("error", (err) => {
+			failure = err.message;
+		});
+		ws.on("close", () => {
+			this.closed = true;
+			emitEnd({
+				type: "close",
+				failure
+			});
+		});
+	}
+	/** Feed keystroke bytes to the pty stdin. */
+	sendInput(data) {
+		if (this.closed || this.ws.readyState !== WebSocket.OPEN) return;
+		this.ws.send(encodeInput(data));
+	}
+	/** Notify the pty of a terminal resize. */
+	resize(cols, rows) {
+		if (this.closed || this.ws.readyState !== WebSocket.OPEN) return;
+		this.ws.send(encodeResize(cols, rows));
+	}
+	close() {
+		this.closed = true;
+		this.ws.close();
+	}
+	/** Open a stream. `mode` is 'pty' (interactive) or 'exec' (one-shot). */
+	static open(opts) {
+		const spec = opts.mode === "pty" ? {
+			mode: "pty",
+			agentId: opts.agentId,
+			cols: opts.cols,
+			rows: opts.rows
+		} : {
+			mode: "exec",
+			agentId: opts.agentId,
+			command: opts.command
+		};
+		const url = new URL(`${wsBase(opts.appUrl)}${SANDBOX_STREAM_PATH}`);
+		for (const [key, value] of Object.entries(streamSpecToQuery(spec))) url.searchParams.set(key, value);
+		return new SandboxStream(new WebSocket(url.toString(), { headers: { authorization: `Bearer ${opts.sessionToken}` } }), opts.onEvent);
+	}
+};
+function toBuffer(data) {
+	if (Buffer.isBuffer(data)) return data;
+	if (Array.isArray(data)) return Buffer.concat(data);
+	return Buffer.from(data);
+}
+
+//#endregion
+//#region src/commands/sandbox.ts
+/** POSIX single-quote one word so the remote shell treats it as one token. */
+function shellQuote(word) {
+	if (/^[A-Za-z0-9_@%+=:,./-]+$/.test(word)) return word;
+	return `'${word.replace(/'/g, `'\\''`)}'`;
+}
+/**
+* Serialize the command words into the single shell string the relay runs.
+*
+* Words arrive already split by the caller's shell, so each must be re-quoted
+* or the remote shell re-splits any word containing spaces or metacharacters:
+* `sandbox -- sh -c 'echo hi; whoami'` would otherwise run `sh -c echo hi`
+* and then, separately, `whoami`. A pipeline still works the explicit way —
+* `sandbox -- sh -c 'ls | wc -l'` — which is what `docker`/`kubectl exec` ask
+* for too. yargs number-coerces bare numerals, so words are stringified.
+*/
+function joinCommandWords(words) {
+	return words.map(String).map(shellQuote).join(" ").trim();
+}
+/**
+* `skydive sandbox` — the standalone counterpart to the chat TUI's `/sandbox`
+* composer command (ANY-4928): a live terminal (or one-shot exec) in the
+* agent's own sandbox without opening the TUI. Runs under Node (no Bun/
+* OpenTUI): the PTY is a raw byte passthrough on the caller's real terminal.
+* The relay gates on EDIT access to the agent and the sandbox-terminal-enabled
+* kill switch, and boots the sandbox when it isn't running.
+*/
+const sandboxCommand = {
+	command: "sandbox [command..]",
+	describe: "Open a live terminal in an agent's sandbox, or run a one-shot command there",
+	builder: (y) => y.option("agent", {
+		type: "string",
+		describe: "Target agent, by id, slug, or name. Optional when the account has exactly one agent."
+	}).positional("command", {
+		type: "string",
+		array: true,
+		describe: "Command to run one-shot (streams output, exits with its exit code). Omit for a live interactive terminal. Put it after `--` if it has flags of its own."
+	}).example("skydive sandbox --agent grace", "Live terminal (Ctrl-] detaches)").example("skydive sandbox --agent grace -- tail -n 50 /tmp/harness.log", "One-shot command (use `--` so its flags reach the sandbox)").example("skydive sandbox --agent grace -- sh -c 'ls /tmp | wc -l'", "Shell features go through an explicit `sh -c`"),
+	handler: async (argv) => {
+		const session = requireSession(argv);
+		const { createRestClient } = await Promise.resolve().then(() => rest_exports);
+		const { resolveAgent } = await Promise.resolve().then(() => print_exports);
+		const client = createRestClient({
+			appUrl: session.appUrl,
+			sessionToken: session.sessionToken
+		});
+		let agent;
+		try {
+			agent = resolveAgent(await client.listAgents({
+				scope: "org",
+				onPage: null
+			}), argv.agent ?? null);
+		} catch (error) {
+			printError(error instanceof Error ? error.message : String(error));
+			process.exit(1);
+		}
+		const command = joinCommandWords([...argv.command ?? [], ...argv["--"] ?? []]);
+		const code = command ? await runExec({
+			session,
+			agentId: agent.id,
+			command
+		}) : await runPty({
+			session,
+			agentId: agent.id,
+			agentName: agent.name
+		});
+		process.exit(code);
+	}
+};
+/** One-shot exec: stream output to stdout, resolve to the command's exit code. */
+function runExec({ session, agentId, command }) {
+	console.error("Connecting to the sandbox…");
+	return new Promise((resolve) => {
+		const finish = (code) => {
+			process.stdout.write("", () => resolve(code));
+		};
+		SandboxStream.open({
+			mode: "exec",
+			appUrl: session.appUrl,
+			sessionToken: session.sessionToken,
+			agentId,
+			command,
+			onEvent: (e) => {
+				switch (e.type) {
+					case "data":
+						process.stdout.write(e.bytes);
+						break;
+					case "exit":
+						finish(e.code);
+						break;
+					case "error":
+						printError(e.message);
+						finish(1);
+						break;
+					case "close":
+						printError(e.failure ? `Could not run the command in the sandbox: ${e.failure}` : "The connection to the sandbox closed before the command finished.");
+						finish(1);
+						break;
+				}
+			}
+		});
+	});
+}
+/** Live terminal on the caller's real TTY. */
+async function runPty({ session, agentId, agentName }) {
+	if (!process.stdin.isTTY || !process.stdout.isTTY) {
+		printError("A live sandbox terminal needs an interactive TTY. For scripted use, pass a command: `skydive sandbox -- <cmd>`.");
+		return 1;
+	}
+	console.error(`Connecting to ${agentName}'s sandbox… (Ctrl-] detaches)`);
+	const { runRawPtyPassthrough } = await import("./raw-pty-C1DXKms6.mjs").then((n) => n.t);
+	const result = await runRawPtyPassthrough({
+		stdin: process.stdin,
+		stdout: process.stdout,
+		appUrl: session.appUrl,
+		sessionToken: session.sessionToken,
+		agentId
+	});
+	if (result.reason === "detach") console.error("\nDetached.");
+	return result.code;
+}
+
 //#endregion
 //#region src/cli.ts
 function createCli(argv) {
-	return yargs(argv).scriptName("skydive").usage("$0 <command> [options]").example("skydive auth login", "Store your API key").example("skydive chat", "Open the interactive chat TUI (prod)").example("skydive chat --api-url http://localhost:4500", "Chat against a local dev API").example("skydive agents list", "List your agents").example("skydive keys create \"my-key\"", "Create an API key").example("skydive secrets set OPENAI_API_KEY --agent-id <id>", "Set a secret (value from stdin)").example("skydive workspace list", "List workspaces on your account").example("skydive workspace switch acme-team", "Switch the workspace all `skydive` commands act on").example("skydive portal open --agent grace", "Open the portal to this machine for an agent, headless (no TUI)").option("json", {
+	return yargs(argv).scriptName("skydive").usage("$0 <command> [options]").parserConfiguration({ "populate--": true }).example("skydive auth login", "Store your API key").example("skydive chat", "Open the interactive chat TUI (prod)").example("skydive chat --api-url http://localhost:4500", "Chat against a local dev API").example("skydive agents list", "List your agents").example("skydive keys create \"my-key\"", "Create an API key").example("skydive secrets set OPENAI_API_KEY --agent-id <id>", "Set a secret (value from stdin)").example("skydive workspace list", "List workspaces on your account").example("skydive workspace switch acme-team", "Switch the workspace all `skydive` commands act on").example("skydive portal open --agent grace", "Open the portal to this machine for an agent, headless (no TUI)").option("json", {
 		type: "boolean",
 		default: false,
 		global: true,
@@ -3770,7 +4225,7 @@ function createCli(argv) {
 		type: "string",
 		global: true,
 		describe: "Override API base URL"
-	}).command(authCommand).command(chatCommand).command(messagesCommand).command(conversationsCommand).command(agentsCommand).command(keysCommand).command(secretsCommand).command(workspaceCommand).command(portalCommand).demandCommand(1, "Specify a command. Run --help for usage.").strict().wrap(null).version(version$1).alias("v", "version").alias("h", "help").help().fail((msg, err) => {
+	}).command(authCommand).command(chatCommand).command(messagesCommand).command(conversationsCommand).command(agentsCommand).command(keysCommand).command(secretsCommand).command(workspaceCommand).command(portalCommand).command(sandboxCommand).demandCommand(1, "Specify a command. Run --help for usage.").strict().wrap(null).version(version$1).alias("v", "version").alias("h", "help").help().fail((msg, err) => {
 		printError(err ? err instanceof Error ? err.message : String(err) : msg ?? "Unknown error");
 		process.exit(1);
 	});
@@ -3844,4 +4299,4 @@ function resolveArgv(args, tty = {
 createCli(resolveArgv(hideBin(process.argv))).parse();
 
 //#endregion
-export { createRestClient as A, theme as C, themeVersion as D, themeModeFromColorFgBg as E, DEFAULT_APP_URL as F, getConfigPath as I, getSavedTheme as L, listWorkspaces as M, setActiveWorkspace as N, themesForMode as O, DEFAULT_API_URL as P, resolveWebUrl as R, noColorRequested as S, themeMode as T, isRecord as _, buildEnv as a, findTheme as b, resolveAgent as c, parseExternalOauthConnectParams as d, parseOauthConnectParams as f, errorMessage as g, parseConnectCard as h, mintPortalDeviceToken as i, getActiveWorkspaceId as j, HttpError as k, MASK_CHAR as l, resolveConnectUrl as m, findThisDevice as n, machineIdentity as o, reconcileMaskedInput as p, grantPortalAccess as r, portalWsUrl as s, fetchPortalDevices as t, cardActionErrorMessage as u, DEFAULT_THEME_ID as v, themeForMode as w, monoTheme as x, applyTheme as y, saveTheme as z };
+export { HttpError as A, saveTheme as B, noColorRequested as C, themeModeFromColorFgBg as D, themeMode as E, DEFAULT_API_URL as F, DEFAULT_APP_URL as I, getConfigPath as L, getActiveWorkspaceId as M, listWorkspaces as N, themeVersion as O, setActiveWorkspace as P, getSavedTheme as R, monoTheme as S, themeForMode as T, errorMessage as _, mintPortalDeviceToken as a, applyTheme as b, portalWsUrl as c, cardActionErrorMessage as d, parseExternalOauthConnectParams as f, parseConnectCard as g, resolveConnectUrl as h, grantPortalAccess as i, createRestClient as j, themesForMode as k, resolveAgent as l, reconcileMaskedInput as m, fetchPortalDevices as n, buildEnv as o, parseOauthConnectParams as p, findThisDevice as r, machineIdentity as s, SandboxStream as t, MASK_CHAR as u, isRecord as v, theme as w, findTheme as x, DEFAULT_THEME_ID as y, resolveWebUrl as z };

package/dist/js/{boot-DLHvjtxn.mjs → boot-QnNiy1cA.mjs}

@@ -1,19 +1,19 @@
 #!/usr/bin/env node
-import { A as createRestClient, C as theme, D as themeVersion, E as themeModeFromColorFgBg, F as DEFAULT_APP_URL, I as getConfigPath, L as getSavedTheme, M as listWorkspaces, N as setActiveWorkspace, O as themesForMode, P as DEFAULT_API_URL, R as resolveWebUrl, S as noColorRequested, T as themeMode, _ as isRecord, b as findTheme, c as resolveAgent, d as parseExternalOauthConnectParams, f as parseOauthConnectParams, g as errorMessage, h as parseConnectCard, j as getActiveWorkspaceId, k as HttpError, l as MASK_CHAR, m as resolveConnectUrl, p as reconcileMaskedInput, u as cardActionErrorMessage, v as DEFAULT_THEME_ID, w as themeForMode, x as monoTheme, y as applyTheme, z as saveTheme } from "./bin.mjs";
-import { t as PortalClient } from "./client-_OL8-XGH.mjs";
+import { A as HttpError, B as saveTheme, C as noColorRequested, D as themeModeFromColorFgBg, E as themeMode, F as DEFAULT_API_URL, I as DEFAULT_APP_URL, L as getConfigPath, M as getActiveWorkspaceId, N as listWorkspaces, O as themeVersion, P as setActiveWorkspace, R as getSavedTheme, S as monoTheme, T as themeForMode, _ as errorMessage, b as applyTheme, d as cardActionErrorMessage, f as parseExternalOauthConnectParams, g as parseConnectCard, h as resolveConnectUrl, j as createRestClient, k as themesForMode, l as resolveAgent, m as reconcileMaskedInput, p as parseOauthConnectParams, t as SandboxStream, u as MASK_CHAR, v as isRecord, w as theme, x as findTheme, y as DEFAULT_THEME_ID, z as resolveWebUrl } from "./bin.mjs";
+import { t as PortalClient } from "./client-XFsd0Wy9.mjs";
+import { n as runRawPtyPassthrough } from "./raw-pty-C1DXKms6.mjs";
+import * as os$1 from "node:os";
+import { homedir, platform, release, tmpdir } from "node:os";
 import path, { basename, extname, isAbsolute, join, win32 } from "node:path";
 import { z } from "zod";
 import open from "open";
 import { execFile, spawn } from "node:child_process";
 import { createHash } from "node:crypto";
 import { constants } from "node:fs";
-import * as os$1 from "node:os";
-import { homedir, platform, release, tmpdir } from "node:os";
 import { MarkdownRenderable, RenderableEvents, SyntaxStyle, createCliRenderer, decodePasteBytes, detectLinks } from "@opentui/core";
 import { createRoot, extend, useKeyboard, usePaste, useRenderer, useTerminalDimensions } from "@opentui/react";
 import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState } from "react";
 import { create } from "zustand";
-import { WebSocket } from "ws";
 import { createConnection } from "node:net";
 import { access, appendFile, mkdir, mkdtemp, readFile, rm, stat, writeFile } from "node:fs/promises";
 import { Fragment, jsx, jsxs } from "@opentui/react/jsx-runtime";
@@ -5284,255 +5284,30 @@ function formatShellContext(command, output, exitCode) {
 	].join("\n");
 }
 
-//#endregion
-//#region ../sandbox-stream-protocol/src/index.ts
-const SANDBOX_STREAM_PATH = "/api/v1/sandbox/stream";
-const FRAME = {
-	DATA: 1,
-	EXIT: 2,
-	ERROR: 3,
-	INPUT: 16,
-	RESIZE: 17
-};
-const MAX_INPUT_BYTES = 1 * 1024 * 1024;
-/** Query params for the upgrade URL, from a spec. Inverse of {@link parseStreamSpec}. */
-function streamSpecToQuery(spec) {
-	if (spec.mode === "pty") return {
-		agentId: spec.agentId,
-		mode: "pty",
-		cols: String(spec.cols),
-		rows: String(spec.rows)
-	};
-	return {
-		agentId: spec.agentId,
-		mode: "exec",
-		command: spec.command
-	};
-}
-function withType(type, payload) {
-	const frame = new Uint8Array(1 + payload.length);
-	frame[0] = type;
-	frame.set(payload, 1);
-	return frame;
-}
-/** client → server: keystroke bytes for the pty stdin. */
-function encodeInput(data) {
-	return withType(FRAME.INPUT, data);
-}
-/** client → server: the client terminal was resized. */
-function encodeResize(cols, rows) {
-	const frame = new Uint8Array(5);
-	frame[0] = FRAME.RESIZE;
-	const view = new DataView(frame.buffer);
-	view.setUint16(1, cols & 65535);
-	view.setUint16(3, rows & 65535);
-	return frame;
-}
-const view = (frame) => new DataView(frame.buffer, frame.byteOffset, frame.byteLength);
-/**
-* Decode a frame the server sent. Returns null for an empty, unknown, or
-* truncated frame — a peer speaking a newer protocol must not crash us.
-*/
-function decodeServerFrame(frame) {
-	const payload = frame.subarray(1);
-	switch (frame[0]) {
-		case FRAME.DATA: return {
-			type: "data",
-			payload
-		};
-		case FRAME.EXIT: return {
-			type: "exit",
-			code: payload.length >= 4 ? view(frame).getInt32(1) : 0
-		};
-		case FRAME.ERROR: return {
-			type: "error",
-			message: new TextDecoder().decode(payload)
-		};
-		default: return null;
-	}
-}
-
-//#endregion
-//#region src/chat/sandbox/client.ts
-function wsBase(appUrl) {
-	const base = appUrl.replace(/\/+$/, "");
-	if (base.startsWith("https://")) return `wss://${base.slice(8)}`;
-	if (base.startsWith("http://")) return `ws://${base.slice(7)}`;
-	return `wss://${base}`;
-}
-/**
-* A connected sandbox-stream session. Construct via `openSandboxStream`. Carries
-* the write side (keystrokes / resize for pty mode) and teardown.
-*/
-var SandboxStream = class SandboxStream {
-	ws;
-	closed = false;
-	constructor(ws, onEvent) {
-		this.ws = ws;
-		ws.on("message", (data, isBinary) => {
-			if (!isBinary) return;
-			const frame = decodeServerFrame(toBuffer(data));
-			if (!frame) return;
-			switch (frame.type) {
-				case "data":
-					onEvent({
-						type: "data",
-						bytes: new Uint8Array(frame.payload)
-					});
-					break;
-				case "exit":
-					onEvent({
-						type: "exit",
-						code: frame.code
-					});
-					break;
-				case "error":
-					onEvent({
-						type: "error",
-						message: frame.message
-					});
-					break;
-			}
-		});
-		ws.on("close", () => {
-			this.closed = true;
-			onEvent({ type: "close" });
-		});
-		ws.on("error", () => {});
-	}
-	/** Feed keystroke bytes to the pty stdin. */
-	sendInput(data) {
-		if (this.closed || this.ws.readyState !== WebSocket.OPEN) return;
-		this.ws.send(encodeInput(data));
-	}
-	/** Notify the pty of a terminal resize. */
-	resize(cols, rows) {
-		if (this.closed || this.ws.readyState !== WebSocket.OPEN) return;
-		this.ws.send(encodeResize(cols, rows));
-	}
-	close() {
-		this.closed = true;
-		this.ws.close();
-	}
-	/** Open a stream. `mode` is 'pty' (interactive) or 'exec' (one-shot). */
-	static open(opts) {
-		const spec = opts.mode === "pty" ? {
-			mode: "pty",
-			agentId: opts.agentId,
-			cols: opts.cols,
-			rows: opts.rows
-		} : {
-			mode: "exec",
-			agentId: opts.agentId,
-			command: opts.command
-		};
-		const url = new URL(`${wsBase(opts.appUrl)}${SANDBOX_STREAM_PATH}`);
-		for (const [key, value] of Object.entries(streamSpecToQuery(spec))) url.searchParams.set(key, value);
-		return new SandboxStream(new WebSocket(url.toString(), { headers: { authorization: `Bearer ${opts.sessionToken}` } }), opts.onEvent);
-	}
-};
-function toBuffer(data) {
-	if (Buffer.isBuffer(data)) return data;
-	if (Array.isArray(data)) return Buffer.concat(data);
-	return Buffer.from(data);
-}
-
 //#endregion
 //#region src/chat/sandbox/pty-session.ts
 /**
 * Runs a live interactive PTY into the agent's sandbox as a full-screen raw
-* terminal, by SUSPENDING the opentui renderer for the duration and doing a
-* direct byte passthrough:
-*
-*   local stdin  → INPUT frames → sandbox pty
-*   sandbox pty  → DATA frames  → local stdout
-*
-* This is the correct shape for a real terminal: we don't reimplement a
-* terminal emulator, we hand the actual TTY to the remote shell. On exit
-* (the shell exits, the socket drops, or the user hits the detach key) we
-* restore the terminal and resume the TUI.
-*
-* Detach key: Ctrl-] (0x1d), the classic telnet/ssh escape — leaves the shell
-* running server-side is NOT a goal here; detaching closes the session.
+* terminal from inside the chat TUI, by SUSPENDING the opentui renderer for
+* the duration (restoring the normal screen buffer and releasing the terminal
+* and its input to us) and handing the TTY to the shared raw passthrough
+* (raw-pty.ts). On exit (the shell exits, the socket drops, or the user hits
+* Ctrl-]) the terminal is restored and the TUI resumes.
 */
-const DETACH_BYTE = 29;
 async function runPtySession(opts) {
 	const { renderer } = opts;
-	const stdin = renderer.stdin;
-	const stdout = process.stdout;
-	const size = () => ({
-		cols: stdout.columns ?? 80,
-		rows: stdout.rows ?? 24
-	});
 	renderer.suspend();
-	return await new Promise((resolve) => {
-		let settled = false;
-		const initial = size();
-		const stream = SandboxStream.open({
-			mode: "pty",
+	try {
+		return await runRawPtyPassthrough({
+			stdin: renderer.stdin,
+			stdout: process.stdout,
 			appUrl: opts.appUrl,
 			sessionToken: opts.sessionToken,
-			agentId: opts.agentId,
-			cols: initial.cols,
-			rows: initial.rows,
-			onEvent: (e) => {
-				switch (e.type) {
-					case "data":
-						stdout.write(e.bytes);
-						break;
-					case "error":
-						stdout.write(`\r\n\x1b[31m${e.message}\x1b[0m\r\n`);
-						finish({
-							reason: "error",
-							code: 1
-						});
-						break;
-					case "exit":
-						finish({
-							reason: "exit",
-							code: e.code
-						});
-						break;
-					case "close":
-						finish({
-							reason: "exit",
-							code: 0
-						});
-						break;
-				}
-			}
+			agentId: opts.agentId
 		});
-		const onStdin = (chunk) => {
-			if (chunk.length === 1 && chunk[0] === DETACH_BYTE) {
-				finish({
-					reason: "detach",
-					code: 0
-				});
-				return;
-			}
-			stream.sendInput(new Uint8Array(chunk));
-		};
-		const onResize = () => {
-			const s = size();
-			stream.resize(s.cols, s.rows);
-		};
-		const wasRaw = stdin.isRaw ?? false;
-		stdin.setRawMode?.(true);
-		stdin.resume();
-		stdin.on("data", onStdin);
-		stdout.on("resize", onResize);
-		stream.resize(initial.cols, initial.rows);
-		function finish(result) {
-			if (settled) return;
-			settled = true;
-			stdin.off("data", onStdin);
-			stdout.off("resize", onResize);
-			stdin.setRawMode?.(wasRaw);
-			stream.close();
-			renderer.resume();
-			resolve(result);
-		}
-	});
+	} finally {
+		renderer.resume();
+	}
 }
 
 //#endregion
@@ -6142,6 +5917,10 @@ function ChatScreen({ agent, conversation }) {
 					append(`\n${e.message}`);
 					stamp(1);
 				} else if (e.type === "exit") stamp(e.code);
+				else if (e.type === "close") {
+					append(`\n${e.failure ? `connection failed: ${e.failure}` : "connection closed before the command finished"}`);
+					stamp(1);
+				}
 			}
 		});
 	}, [

package/dist/js/{client-_OL8-XGH.mjs → client-XFsd0Wy9.mjs}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { t as __exportAll } from "./rolldown-runtime-Cz4Tg37Z.mjs";
-import { a as buildEnv, g as errorMessage, i as mintPortalDeviceToken, n as findThisDevice, o as machineIdentity, r as grantPortalAccess, s as portalWsUrl, t as fetchPortalDevices } from "./bin.mjs";
+import { _ as errorMessage, a as mintPortalDeviceToken, c as portalWsUrl, i as grantPortalAccess, n as fetchPortalDevices, o as buildEnv, r as findThisDevice, s as machineIdentity } from "./bin.mjs";
 import { z } from "zod";
 import { spawn } from "node:child_process";
 import { WebSocket } from "ws";

package/dist/js/raw-pty-C1DXKms6.mjs

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+import { t as __exportAll } from "./rolldown-runtime-Cz4Tg37Z.mjs";
+import { t as SandboxStream } from "./bin.mjs";
+
+//#region src/chat/sandbox/raw-pty.ts
+var raw_pty_exports = /* @__PURE__ */ __exportAll({ runRawPtyPassthrough: () => runRawPtyPassthrough });
+/**
+* The transport-and-TTY core of a live sandbox terminal: direct byte
+* passthrough between a raw local TTY and the remote pty.
+*
+*   local stdin  → INPUT frames → sandbox pty
+*   sandbox pty  → DATA frames  → local stdout
+*
+* This is the correct shape for a real terminal: we don't reimplement a
+* terminal emulator, we hand the actual TTY to the remote shell. Callers own
+* the surrounding lifecycle — the chat TUI suspends/resumes its renderer
+* around this (pty-session.ts), the standalone `skydive sandbox` command runs
+* it bare.
+*
+* Detach key: Ctrl-] (0x1d), the classic telnet/ssh escape. Leaving the shell
+* running server-side is NOT a goal here; detaching closes the session.
+*/
+const DETACH_BYTE = 29;
+async function runRawPtyPassthrough(opts) {
+	const { stdin, stdout } = opts;
+	const size = () => ({
+		cols: stdout.columns ?? 80,
+		rows: stdout.rows ?? 24
+	});
+	return await new Promise((resolve) => {
+		let settled = false;
+		const initial = size();
+		const stream = SandboxStream.open({
+			mode: "pty",
+			appUrl: opts.appUrl,
+			sessionToken: opts.sessionToken,
+			agentId: opts.agentId,
+			cols: initial.cols,
+			rows: initial.rows,
+			onEvent: (e) => {
+				switch (e.type) {
+					case "data":
+						stdout.write(e.bytes);
+						break;
+					case "error":
+						stdout.write(`\r\n\x1b[31m${e.message}\x1b[0m\r\n`);
+						finish({
+							reason: "error",
+							code: 1
+						});
+						break;
+					case "exit":
+						finish({
+							reason: "exit",
+							code: e.code
+						});
+						break;
+					case "close":
+						stdout.write(`\r\n\x1b[31m${e.failure ? `Could not open the sandbox terminal: ${e.failure}` : "The sandbox terminal connection closed unexpectedly."}\x1b[0m\r\n`);
+						finish({
+							reason: "error",
+							code: 1
+						});
+						break;
+				}
+			}
+		});
+		const onStdin = (chunk) => {
+			if (chunk.length === 1 && chunk[0] === DETACH_BYTE) {
+				finish({
+					reason: "detach",
+					code: 0
+				});
+				return;
+			}
+			stream.sendInput(new Uint8Array(chunk));
+		};
+		const onResize = () => {
+			const s = size();
+			stream.resize(s.cols, s.rows);
+		};
+		const wasRaw = stdin.isRaw ?? false;
+		stdin.setRawMode?.(true);
+		stdin.resume();
+		stdin.on("data", onStdin);
+		stdout.on("resize", onResize);
+		stream.resize(initial.cols, initial.rows);
+		function finish(result) {
+			if (settled) return;
+			settled = true;
+			stdin.off("data", onStdin);
+			stdout.off("resize", onResize);
+			stdin.setRawMode?.(wasRaw);
+			stream.close();
+			resolve(result);
+		}
+	});
+}
+
+//#endregion
+export { runRawPtyPassthrough as n, raw_pty_exports as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skydive-cli",
-  "version": "0.1.0-beta.353",
+  "version": "0.1.0-beta.378",
   "description": "Skydive CLI — manage AI agents from the command line",
   "homepage": "https://skydive.com",
   "license": "MIT",