@sandbar-sdk/cli 0.0.0 → 0.3.0

package/dist/main.js

@@ -0,0 +1,2335 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { parseArgs } from "node:util";
+// package.json
+var package_default = {
+  name: "@sandbar-sdk/cli",
+  version: "0.3.0",
+  private: false,
+  type: "module",
+  description: "Agent-first command line for creating and managing Sandbar sandboxes.",
+  bin: {
+    sandbar: "./dist/main.js"
+  },
+  files: [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  engines: {
+    node: ">=20"
+  },
+  scripts: {
+    check: "tsc -p tsconfig.json",
+    build: "rm -rf dist && bun build src/main.ts --target node --format esm --outdir dist --external sandbar-sdk --external @sandbar-sdk/adapter --external zod"
+  },
+  dependencies: {
+    "@sandbar-sdk/adapter": "workspace:*",
+    "sandbar-sdk": "workspace:*",
+    zod: "4.6.5"
+  },
+  devDependencies: {
+    "@sandbar/provider-fake": "workspace:*"
+  },
+  license: "Apache-2.0",
+  repository: {
+    type: "git",
+    url: "git+https://github.com/pandemicsyn/sandbar.git",
+    directory: "packages/cli"
+  },
+  bugs: {
+    url: "https://github.com/pandemicsyn/sandbar/issues"
+  },
+  publishConfig: {
+    access: "public"
+  }
+};
+
+// src/commands.ts
+import { readFile as readFile4, stat as stat2, writeFile as writeFile2 } from "node:fs/promises";
+import { basename, join as join4, resolve as resolve3 } from "node:path";
+import {
+  AdapterSandbox,
+  Image,
+  NonzeroExitError,
+  ResourceReference as ResourceReference2,
+  SandbarError as SandbarError2
+} from "sandbar-sdk";
+import { z as z4 } from "zod";
+
+// src/config.ts
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { z } from "zod";
+
+// src/output.ts
+import {
+  OutcomeUnknownError,
+  SandbarError
+} from "sandbar-sdk";
+
+class CliError extends Error {
+  code;
+  hint;
+  known;
+  outcome;
+  details;
+  constructor(code, message, hint, known, outcome = code === "OUTCOME_UNKNOWN" ? "unknown" : "rejected", details) {
+    super(message);
+    this.code = code;
+    this.hint = hint;
+    this.known = known;
+    this.outcome = outcome;
+    this.details = details;
+    this.name = "CliError";
+  }
+}
+function usage(message, hint) {
+  return new CliError("USAGE", message, hint);
+}
+var retryableCodes = new Set(["RATE_LIMIT", "CAPACITY", "UNAVAILABLE"]);
+var uncertainEffects = new Set(["possible", "unknown", "partial", "applied"]);
+function describeError(cause) {
+  if (cause instanceof CliError)
+    return {
+      code: cause.code,
+      message: cause.message,
+      retryable: false,
+      outcome: cause.outcome,
+      hint: cause.hint,
+      known: cause.known,
+      details: cause.details
+    };
+  if (cause instanceof SandbarError) {
+    const partial = cause.outcome?.status === "partial";
+    let known;
+    if (cause.outcome && "sandbox" in cause.outcome && cause.outcome.sandbox)
+      known = { reference: cause.outcome.sandbox };
+    if (cause.reference)
+      known = { ...known, recovery: cause.reference };
+    const outcome = partial ? "partial" : cause instanceof OutcomeUnknownError || uncertainEffects.has(cause.effect) ? "unknown" : "rejected";
+    return {
+      code: partial ? "PARTIAL" : cause.code,
+      message: cause.message,
+      retryable: outcome === "rejected" && retryableCodes.has(cause.code),
+      outcome,
+      known
+    };
+  }
+  const local = cause instanceof Error && "syscall" in cause && "code" in cause;
+  if (local)
+    return {
+      code: "LOCAL_IO",
+      message: cause.message,
+      retryable: false,
+      outcome: "rejected"
+    };
+  return {
+    code: "INTERNAL",
+    message: cause instanceof Error ? cause.message : String(cause),
+    retryable: false,
+    outcome: "unknown"
+  };
+}
+var managementExitCodes = new Map([
+  ["USAGE", 2],
+  ["LOCAL_IO", 2],
+  ["INVALID_ARGUMENT", 2],
+  ["NOT_FOUND", 3],
+  ["UNSUPPORTED", 4],
+  ["ADAPTER_NOT_INSTALLED", 4],
+  ["LIMIT_REACHED", 4],
+  ["SECRET_TOOL_MISSING", 4],
+  ["SECRET_UNAVAILABLE", 5],
+  ["UNAUTHENTICATED", 5],
+  ["FORBIDDEN", 5]
+]);
+function managementExitCode(report) {
+  if (report.outcome === "partial")
+    return 8;
+  if (report.outcome === "unknown")
+    return report.code === "INTERNAL" ? 1 : 6;
+  if (report.retryable)
+    return 7;
+  return managementExitCodes.get(report.code) ?? 1;
+}
+function commandExitCode() {
+  return 125;
+}
+
+class Output {
+  json;
+  streams;
+  constructor(json, streams) {
+    this.json = json;
+    this.streams = streams;
+  }
+  success(data, human) {
+    if (this.json)
+      this.streams.stdout(`${JSON.stringify({ ok: true, data })}
+`);
+    else if (human)
+      this.streams.stdout(human.endsWith(`
+`) ? human : `${human}
+`);
+  }
+  failure(report) {
+    if (this.json) {
+      this.streams.stdout(`${JSON.stringify({ ok: false, error: report })}
+`);
+      return;
+    }
+    this.streams.stderr(`sandbar: ${report.message}
+`);
+    if (report.hint)
+      this.streams.stderr(`hint: ${report.hint}
+`);
+    if (report.outcome === "unknown" && report.code !== "INTERNAL")
+      this.streams.stderr(`The operation may have taken effect; inspect before retrying (sandbar ls, sandbar inspect).
+`);
+    if (report.known?.reference)
+      this.streams.stderr(`known sandbox reference: ${JSON.stringify(report.known.reference)}
+`);
+    else if (report.known?.recovery)
+      this.streams.stderr(`operation recovery reference: ${JSON.stringify(report.known.recovery)}
+`);
+    for (const item of report.details?.removed ?? [])
+      this.streams.stdout(`${item.name}
+`);
+    for (const item of report.details?.skipped ?? [])
+      this.streams.stderr(`skipped ${item.name}: ${item.reason ?? item.result}
+`);
+    for (const item of report.details?.failed ?? [])
+      this.streams.stderr(`failed ${item.name}: ${item.code} ${item.reason ?? ""}
+`);
+  }
+  note(text) {
+    this.streams.stderr(`${text}
+`);
+  }
+}
+
+// src/config.ts
+var ProfileConfig = z.strictObject({
+  provider: z.string().regex(/^[a-z0-9-]{1,64}$/).optional(),
+  module: z.string().min(1).max(1024).optional(),
+  export: z.string().min(1).max(128).optional(),
+  config: z.record(z.string(), z.json()).optional(),
+  credentials: z.record(z.string(), z.string()).optional()
+}).refine((profile) => profile.provider || profile.module, {
+  message: "A profile needs a provider or a module"
+});
+var CliConfig = z.strictObject({
+  default: z.string().min(1).optional(),
+  profiles: z.record(z.string(), ProfileConfig).optional(),
+  state: z.strictObject({ kind: z.literal("fs"), dir: z.string().min(1).optional() }).optional(),
+  limits: z.strictObject({ maxSandboxes: z.number().int().positive().nullable().optional() }).optional(),
+  images: z.strictObject({ autoBuild: z.boolean().optional() }).optional(),
+  adapters: z.strictObject({ searchProject: z.boolean().optional() }).optional()
+});
+function configHome(env) {
+  return join(env.XDG_CONFIG_HOME || join(env.HOME || homedir(), ".config"), "sandbar");
+}
+function expandHome(path, env) {
+  return path === "~" || path.startsWith("~/") ? join(env.HOME || homedir(), path.slice(1)) : path;
+}
+async function loadConfig(explicitPath, env) {
+  const chosen = explicitPath ?? env.SANDBAR_CONFIG;
+  const path = resolve(expandHome(chosen ?? join(configHome(env), "sandbar.json"), env));
+  let text;
+  try {
+    text = await readFile(path, "utf8");
+  } catch (cause) {
+    if (!chosen && cause instanceof Error && "code" in cause && cause.code === "ENOENT")
+      return { path, dir: dirname(path), exists: false, value: {} };
+    throw usage(`Cannot read config ${path}: ${cause instanceof Error ? cause.message : cause}`);
+  }
+  let json;
+  try {
+    json = z.json().parse(JSON.parse(text));
+  } catch {
+    throw usage(`Config ${path} is not valid JSON`);
+  }
+  const parsed = CliConfig.safeParse(json);
+  if (!parsed.success)
+    throw usage(`Config ${path} is invalid: ${z.prettifyError(parsed.error).replaceAll(`
+`, "; ")}`);
+  return { path, dir: dirname(path), exists: true, value: parsed.data };
+}
+function stateDir(flag, config, env, cwd) {
+  const given = flag ?? env.SANDBAR_STATE_DIR;
+  if (given)
+    return resolve(cwd, expandHome(given, env));
+  const configured = config.value.state?.dir;
+  if (configured)
+    return resolve(config.dir, expandHome(configured, env));
+  return join(configHome(env), "state");
+}
+function searchProjectAdapters(config, env) {
+  const fromEnv = env.SANDBAR_PROJECT_ADAPTERS;
+  if (fromEnv !== undefined && fromEnv !== "")
+    return fromEnv === "1" || fromEnv === "true";
+  return config.value.adapters?.searchProject ?? false;
+}
+function maxSandboxes(config, env) {
+  const fromEnv = env.SANDBAR_MAX_SANDBOXES;
+  if (fromEnv !== undefined && fromEnv !== "") {
+    const parsed = z.coerce.number().int().positive().safeParse(fromEnv);
+    if (!parsed.success)
+      throw usage("SANDBAR_MAX_SANDBOXES must be a positive integer");
+    return parsed.data;
+  }
+  return config.value.limits?.maxSandboxes ?? null;
+}
+var EnvReference = z.string().regex(/^env:[A-Za-z_][A-Za-z0-9_]*$/);
+function valueAvailable(value, env) {
+  const reference = EnvReference.safeParse(value);
+  return !reference.success || Boolean(env[reference.data.slice(4)]);
+}
+function resolveEnvReferences(value, env, where) {
+  const reference = EnvReference.safeParse(value);
+  if (reference.success) {
+    const name = reference.data.slice(4);
+    const found = env[name];
+    if (found === undefined || found === "")
+      throw new CliError("USAGE", `${where} needs environment variable ${name}`);
+    return found;
+  }
+  if (Array.isArray(value))
+    return value.map((item) => resolveEnvReferences(item, env, where));
+  const record = z.record(z.string(), z.json()).safeParse(value);
+  if (record.success)
+    return Object.fromEntries(Object.entries(record.data).map(([key, item]) => [
+      key,
+      resolveEnvReferences(item, env, `${where}.${key}`)
+    ]));
+  return value;
+}
+
+// src/providers.ts
+import { access, readFile as readFile2 } from "node:fs/promises";
+import { dirname as dirname2, isAbsolute, join as join2, relative, resolve as resolve2 } from "node:path";
+import { pathToFileURL } from "node:url";
+import {
+  bindAdapter
+} from "@sandbar-sdk/adapter";
+import { Sandbar } from "sandbar-sdk";
+import { z as z2 } from "zod";
+var providers = [
+  {
+    id: "daytona",
+    module: "@sandbar-sdk/daytona",
+    export: "daytonaAdapter",
+    experimental: false,
+    credentials: { apiKey: "DAYTONA_API_KEY" },
+    config: { target: { env: "DAYTONA_TARGET", required: true } }
+  },
+  {
+    id: "e2b",
+    module: "@sandbar-sdk/e2b",
+    export: "e2bAdapter",
+    experimental: false,
+    credentials: { apiKey: "E2B_API_KEY" },
+    config: {}
+  },
+  {
+    id: "boxd",
+    module: "@sandbar-sdk/boxd",
+    export: "boxdAdapter",
+    experimental: true,
+    credentials: { apiKey: "BOXD_API_KEY" },
+    config: {
+      org: { env: "BOXD_ORG", required: true },
+      network: { env: "BOXD_NETWORK", required: true }
+    }
+  },
+  {
+    id: "vercel",
+    module: "@sandbar-sdk/vercel",
+    export: "vercel",
+    experimental: false,
+    credentials: { token: "VERCEL_TOKEN" },
+    config: {
+      teamId: { env: "VERCEL_TEAM_ID", required: true },
+      projectId: { env: "VERCEL_PROJECT_ID", required: true }
+    }
+  },
+  {
+    id: "modal",
+    module: "@sandbar-sdk/modal",
+    export: "modalAdapter",
+    experimental: true,
+    credentials: { tokenId: "MODAL_TOKEN_ID", tokenSecret: "MODAL_TOKEN_SECRET" },
+    config: {
+      appName: { env: "MODAL_APP_NAME", required: true },
+      environment: { env: "MODAL_ENVIRONMENT", required: true }
+    }
+  }
+];
+function descriptor(id) {
+  return providers.find((provider) => provider.id === id);
+}
+function missingEnv(provider, env, covered = new Set) {
+  const needed = [
+    ...Object.entries(provider.credentials),
+    ...Object.entries(provider.config).flatMap(([key, entry]) => entry.required ? [[key, entry.env]] : [])
+  ];
+  return needed.flatMap(([key, name]) => covered.has(key) || env[name] ? [] : [name]);
+}
+function resolveProfile(flags, loaded, env) {
+  const profiles = loaded.value.profiles ?? {};
+  const profileName = flags.profile ?? (flags.provider ? undefined : env.SANDBAR_PROFILE);
+  if (profileName) {
+    const profile = profiles[profileName];
+    if (!profile)
+      throw usage(`Profile ${profileName} is not defined in ${loaded.path}`, Object.keys(profiles).length ? `known profiles: ${Object.keys(profiles).join(", ")}` : 'add it under "profiles" in sandbar.json');
+    return fromProfile(profileName, profile, loaded, env);
+  }
+  const providerId = flags.provider ?? env.SANDBAR_PROVIDER;
+  if (providerId)
+    return fromProfile(providerId, { provider: providerId }, loaded, env);
+  const fallback = loaded.value.default;
+  if (fallback) {
+    const profile = profiles[fallback];
+    if (!profile)
+      throw usage(`Default profile ${fallback} is not defined in ${loaded.path}`);
+    return fromProfile(fallback, profile, loaded, env);
+  }
+  const ready = providers.filter((provider) => !missingEnv(provider, env).length);
+  throw usage("No provider selected", ready.length ? `credentials found for: ${ready.map((provider) => provider.id).join(", ")}; set SANDBAR_PROVIDER or pass --provider` : "set SANDBAR_PROVIDER and the provider's credentials (see `sandbar providers`), or add a profile to sandbar.json");
+}
+function fromProfile(name, profile, loaded, env) {
+  const official = profile.provider ? descriptor(profile.provider) : undefined;
+  if (profile.provider && !official && !profile.module)
+    throw usage(`Unknown provider ${profile.provider}`, `official providers: ${providers.map((provider) => provider.id).join(", ")}; use "module" for other adapters`);
+  const where = `profile ${name}`;
+  const credentials = Object.fromEntries([
+    ...Object.entries(official?.credentials ?? {}).flatMap(([key, variable]) => {
+      const value = env[variable];
+      return value ? [[key, value]] : [];
+    }),
+    ...Object.entries(profile.credentials ?? {}).map(([key, value]) => [
+      key,
+      z2.string().parse(resolveEnvReferences(value, env, `${where}.credentials.${key}`))
+    ])
+  ]);
+  const config = Object.fromEntries([
+    ...Object.entries(official?.config ?? {}).flatMap(([key, entry]) => {
+      const value = env[entry.env];
+      return value ? [[key, value]] : [];
+    }),
+    ...Object.entries(profile.config ?? {}).map(([key, value]) => [key, resolveEnvReferences(value, env, `${where}.config.${key}`)])
+  ]);
+  if (official) {
+    const missing = [
+      ...Object.entries(official.credentials).filter(([key]) => !credentials[key]).map(([, variable]) => variable),
+      ...Object.entries(official.config).filter(([key, entry]) => entry.required && config[key] === undefined).map(([, entry]) => entry.env)
+    ];
+    if (missing.length)
+      throw usage(`${where} (${official.id}) is missing ${missing.join(", ")}`, "set the environment variables, or put the values in the profile in sandbar.json");
+  }
+  return {
+    name,
+    provider: official?.id ?? profile.provider ?? name,
+    module: profile.module ?? official?.module ?? "",
+    export: profile.export ?? official?.export ?? "default",
+    baseDir: loaded.dir,
+    searchProject: searchProjectAdapters(loaded, env),
+    config,
+    credentials
+  };
+}
+var ConditionalEntry = z2.object({
+  import: z2.string().optional(),
+  default: z2.string().optional()
+});
+var PackageManifest = z2.object({
+  main: z2.string().optional(),
+  exports: z2.union([
+    z2.string(),
+    z2.object({ ".": z2.union([z2.string(), ConditionalEntry]).optional() }),
+    ConditionalEntry
+  ]).optional()
+});
+async function exists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function rootEntry(manifest) {
+  const field = manifest.exports;
+  const plain = z2.string().safeParse(field);
+  if (plain.success)
+    return plain.data;
+  const dotted = z2.object({ ".": z2.union([z2.string(), ConditionalEntry]) }).safeParse(field);
+  const target = dotted.success ? dotted.data["."] : field;
+  const direct = z2.string().safeParse(target);
+  if (direct.success)
+    return direct.data;
+  const conditional = ConditionalEntry.safeParse(target);
+  return conditional.success && (conditional.data.import ?? conditional.data.default) || manifest.main || "index.js";
+}
+async function entryFor(packageDir) {
+  const manifestPath = join2(packageDir, "package.json");
+  if (!await exists(manifestPath))
+    return null;
+  const manifest = PackageManifest.safeParse(JSON.parse(await readFile2(manifestPath, "utf8")));
+  if (!manifest.success)
+    return null;
+  const entry = resolve2(packageDir, rootEntry(manifest.data));
+  const inside = relative(packageDir, entry);
+  if (!inside || inside.startsWith("..") || isAbsolute(inside))
+    throw new CliError("ADAPTER_NOT_INSTALLED", `${manifestPath} points its entry outside the package (${rootEntry(manifest.data)})`);
+  return entry;
+}
+var PackageName = /^(@[a-z0-9][a-z0-9._~-]*\/)?[a-z0-9][a-z0-9._~-]*$/;
+async function resolveAdapterModule(profile, cwd, env) {
+  const spec = profile.module;
+  if (spec.startsWith(".") || isAbsolute(spec))
+    return pathToFileURL(resolve2(profile.baseDir, spec)).href;
+  if (!PackageName.test(spec))
+    throw usage(`Adapter module ${spec} is not a package name or a path`);
+  const roots = [join2(configHome(env), "adapters", "node_modules")];
+  if (profile.searchProject)
+    for (let dir = resolve2(cwd);; dir = dirname2(dir)) {
+      roots.push(join2(dir, "node_modules"));
+      if (dirname2(dir) === dir)
+        break;
+    }
+  for (const root of roots) {
+    const entry = await entryFor(join2(root, spec));
+    if (entry)
+      return pathToFileURL(entry).href;
+  }
+  return spec;
+}
+function isAdapter(value) {
+  return value instanceof Object && "name" in value && "connect" in value && "config" in value;
+}
+var AdapterExport = z2.custom(isAdapter);
+async function loadAdapter(profile, cwd, env, secrets) {
+  const target = await resolveAdapterModule(profile, cwd, env);
+  const schema = z2.object({ [profile.export]: AdapterExport });
+  let parsed;
+  try {
+    parsed = schema.safeParse(await import(target));
+  } catch (cause) {
+    const official = descriptor(profile.provider);
+    throw new CliError("ADAPTER_NOT_INSTALLED", `Cannot load adapter ${profile.module} for profile ${profile.name}: ${cause instanceof Error ? cause.message : cause}`, official ? `install it into ${join2(configHome(env), "adapters")} (cd there && npm install ${official.module}); project installs need adapters.searchProject or SANDBAR_PROJECT_ADAPTERS=1` : "check the profile's module path");
+  }
+  if (!parsed.success)
+    throw new CliError("ADAPTER_NOT_INSTALLED", `${profile.module} has no adapter export named ${profile.export}`);
+  const exported = parsed.data[profile.export];
+  if (!exported)
+    throw new CliError("ADAPTER_NOT_INSTALLED", `${profile.module} export is empty`);
+  if ("bound" in exported)
+    return exported;
+  const where = `profile ${profile.name}`;
+  const config = await secrets.resolve(profile.config, `${where}.config`);
+  const credentials = z2.record(z2.string(), z2.string()).parse(await secrets.resolve(profile.credentials, `${where}.credentials`));
+  return bindAdapter(exported, config, credentials);
+}
+async function connect(profile, cwd, env, secrets) {
+  return Sandbar.connect(await loadAdapter(profile, cwd, env, secrets));
+}
+
+// src/store.ts
+import { createHash, randomBytes } from "node:crypto";
+import { link, mkdir, readFile as readFile3, readdir, rename, stat, unlink, writeFile } from "node:fs/promises";
+import { join as join3 } from "node:path";
+import { ResourceReference } from "sandbar-sdk";
+import { z as z3 } from "zod";
+var RecordName = z3.string().regex(/^[a-z0-9][a-z0-9-]{0,62}$/);
+var SandboxRecord = z3.strictObject({
+  format: z3.literal(1),
+  kind: z3.literal("sandbox"),
+  name: RecordName,
+  status: z3.enum(["creating", "created", "unknown"]),
+  profile: z3.string().min(1),
+  provider: z3.string().min(1),
+  createdAt: z3.iso.datetime({ offset: true }),
+  labels: z3.record(z3.string(), z3.string()),
+  image: z3.string().optional(),
+  reference: ResourceReference.extend({ kind: z3.literal("sandbox") }).nullable(),
+  recovery: z3.custom((value) => z3.record(z3.string(), z3.unknown()).safeParse(value).success).optional()
+});
+function errorCode(cause) {
+  return cause instanceof Error && "code" in cause ? String(cause.code) : undefined;
+}
+function versionOf(text) {
+  return createHash("sha256").update(text).digest("hex");
+}
+function encode(record) {
+  return `${JSON.stringify(SandboxRecord.parse(record), null, 2)}
+`;
+}
+var STALE_LOCK_MS = 30000;
+var sleep = (ms) => new Promise((done) => setTimeout(done, ms));
+
+class FsStateStore {
+  dir;
+  constructor(dir) {
+    this.dir = dir;
+  }
+  folder(kind) {
+    return join3(this.dir, `${kind}es`);
+  }
+  path(kind, name) {
+    return join3(this.folder(kind), `${RecordName.parse(name)}.json`);
+  }
+  async temporary(kind, name, text) {
+    await mkdir(this.folder(kind), { recursive: true });
+    const path = `${this.path(kind, name)}.${randomBytes(6).toString("hex")}.tmp`;
+    await writeFile(path, text, { flag: "wx" });
+    return path;
+  }
+  async locked(kind, name, action) {
+    const lock = `${this.path(kind, name)}.lock`;
+    await mkdir(this.folder(kind), { recursive: true });
+    for (let attempt = 0;; attempt++) {
+      try {
+        await writeFile(lock, String(process.pid), { flag: "wx" });
+        break;
+      } catch (cause) {
+        if (errorCode(cause) !== "EEXIST")
+          throw cause;
+        const held = await stat(lock).catch(() => null);
+        if (held && Date.now() - held.mtimeMs > STALE_LOCK_MS)
+          await unlink(lock).catch(() => {});
+        else if (attempt >= 100)
+          throw new CliError("CONFLICT", `Store record ${name} is locked by another process`);
+        else
+          await sleep(20);
+      }
+    }
+    try {
+      return await action();
+    } finally {
+      await unlink(lock).catch(() => {});
+    }
+  }
+  async get(kind, name) {
+    let text;
+    try {
+      text = await readFile3(this.path(kind, name), "utf8");
+    } catch (cause) {
+      if (errorCode(cause) === "ENOENT")
+        return null;
+      throw cause;
+    }
+    let json;
+    try {
+      json = z3.json().parse(JSON.parse(text));
+    } catch {
+      throw new CliError("STORE_INVALID", `Store record ${this.path(kind, name)} is not valid JSON`);
+    }
+    const parsed = SandboxRecord.safeParse(json);
+    if (!parsed.success)
+      throw new CliError("STORE_INVALID", `Store record ${this.path(kind, name)} is invalid`);
+    return { record: parsed.data, version: versionOf(text) };
+  }
+  async create(kind, name, record) {
+    const text = encode(record);
+    const temporary = await this.temporary(kind, name, text);
+    try {
+      await link(temporary, this.path(kind, name));
+    } catch (cause) {
+      if (errorCode(cause) === "EEXIST")
+        throw new CliError("CONFLICT", `Name ${name} is already in use`);
+      throw cause;
+    } finally {
+      await unlink(temporary).catch(() => {});
+    }
+    return { version: versionOf(text) };
+  }
+  async update(kind, name, record, version) {
+    return this.locked(kind, name, async () => {
+      const current = await this.get(kind, name);
+      if (!current || current.version !== version)
+        throw new CliError("CONFLICT", `Store record ${name} changed concurrently`);
+      const text = encode(record);
+      await rename(await this.temporary(kind, name, text), this.path(kind, name));
+      return { version: versionOf(text) };
+    });
+  }
+  async remove(kind, name, version) {
+    await this.locked(kind, name, async () => {
+      if (version !== undefined) {
+        const current = await this.get(kind, name);
+        if (current && current.version !== version)
+          throw new CliError("CONFLICT", `Store record ${name} changed concurrently`);
+      }
+      try {
+        await unlink(this.path(kind, name));
+      } catch (cause) {
+        if (errorCode(cause) !== "ENOENT")
+          throw cause;
+      }
+    });
+  }
+  async list(kind, cursor, limit = 1000) {
+    let files;
+    try {
+      files = await readdir(this.folder(kind));
+    } catch (cause) {
+      if (errorCode(cause) === "ENOENT")
+        return { names: [] };
+      throw cause;
+    }
+    const names = files.filter((file) => file.endsWith(".json")).map((file) => file.slice(0, -5)).filter((name) => RecordName.safeParse(name).success && (!cursor || name > cursor)).sort();
+    const page = names.slice(0, limit);
+    return { names: page, cursor: names.length > limit ? page.at(-1) : undefined };
+  }
+}
+async function listAll(store, kind, onInvalid) {
+  const found = [];
+  let cursor;
+  do {
+    const page = await store.list(kind, cursor);
+    for (const name of page.names) {
+      try {
+        const entry = await store.get(kind, name);
+        if (entry)
+          found.push(entry);
+      } catch (cause) {
+        if (!(cause instanceof CliError) || cause.code !== "STORE_INVALID")
+          throw cause;
+        onInvalid?.(`warning: ${cause.message}; skipped`);
+      }
+    }
+    cursor = page.cursor;
+  } while (cursor);
+  return found;
+}
+function checkName(name) {
+  const parsed = RecordName.safeParse(name);
+  if (!parsed.success)
+    throw usage(`Invalid name ${name}`, "use 1-63 lowercase letters, digits and dashes, starting with a letter or digit");
+  return parsed.data;
+}
+function generatedName() {
+  return `sb-${randomBytes(3).toString("hex").slice(0, 5)}`;
+}
+
+// src/units.ts
+var durationUnits = new Map([
+  ["", 1],
+  ["s", 1],
+  ["m", 60],
+  ["h", 3600]
+]);
+function parseDuration(value, flag) {
+  const match = /^(\d+)(s|m|h)?$/.exec(value.trim());
+  const seconds = match ? Number(match[1]) * (durationUnits.get(match[2] ?? "") ?? 1) : NaN;
+  if (!Number.isSafeInteger(seconds) || seconds <= 0)
+    throw usage(`--${flag} must be a duration like 90s, 30m or 2h`);
+  return seconds;
+}
+var sizeUnits = new Map([
+  ["", 1],
+  ["b", 1],
+  ["k", 1024],
+  ["m", 1024 ** 2],
+  ["g", 1024 ** 3]
+]);
+function parseSize(value, flag) {
+  const match = /^(\d+)(b|k|m|g)?$/i.exec(value.trim());
+  const bytes = match ? Number(match[1]) * (sizeUnits.get((match[2] ?? "").toLowerCase()) ?? 1) : NaN;
+  if (!Number.isSafeInteger(bytes) || bytes <= 0)
+    throw usage(`--${flag} must be a size like 4096, 512k or 1m`);
+  return bytes;
+}
+function parsePairs(values, flag) {
+  const pairs = values.map((value) => {
+    const index = value.indexOf("=");
+    if (index <= 0)
+      throw usage(`--${flag} expects KEY=VALUE, got ${value}`);
+    return [value.slice(0, index), value.slice(index + 1)];
+  });
+  return Object.fromEntries(pairs);
+}
+
+// src/commands.ts
+class Flags {
+  values;
+  positionals;
+  rest;
+  constructor(values, positionals, rest) {
+    this.values = values;
+    this.positionals = positionals;
+    this.rest = rest;
+  }
+  string(name) {
+    return z4.string().optional().parse(this.values[name]);
+  }
+  strings(name) {
+    return z4.array(z4.string()).optional().parse(this.values[name]) ?? [];
+  }
+  bool(name) {
+    return z4.boolean().optional().parse(this.values[name]) ?? false;
+  }
+}
+function createRequest(flags) {
+  if (flags.string("image") && flags.string("prepared"))
+    throw usage("Pass either --image or --prepared, not both");
+  if (flags.bool("build"))
+    throw usage("--build is not available yet", "build images in a later CLI release; for now use a prepared image or a provider that boots OCI images directly");
+  return {
+    name: flags.string("name"),
+    ifNotExists: flags.bool("if-not-exists"),
+    image: flags.string("image"),
+    prepared: flags.string("prepared"),
+    network: flags.string("network"),
+    labels: parsePairs(flags.strings("label"), "label")
+  };
+}
+function createInput(request) {
+  return {
+    environment: request.image ? Image.oci(request.image) : request.prepared ? Image.prepared(request.prepared) : undefined,
+    network: request.network,
+    labels: Object.keys(request.labels).length ? request.labels : undefined
+  };
+}
+async function claimName(store, record, requested, ifNotExists = false) {
+  for (let attempt = 0;; attempt++) {
+    const name = requested ? checkName(requested) : generatedName();
+    const full = { ...record, name };
+    try {
+      const { version } = await store.create("sandbox", name, full);
+      return { record: full, version };
+    } catch (cause) {
+      if (!(cause instanceof CliError) || cause.code !== "CONFLICT" || attempt >= 8)
+        throw cause;
+      if (requested)
+        throw new CliError("CONFLICT", cause.message, ifNotExists ? "its record is not a confirmed sandbox (still creating, or outcome unknown); check `sandbar inspect`, or drop it with `sandbar rm --force`" : "pass --if-not-exists to reuse it, or choose another --name");
+    }
+  }
+}
+async function liveCount(store) {
+  return (await listAll(store, "sandbox")).length;
+}
+async function createSandbox(session, request) {
+  const store = await session.store();
+  const profile = await session.profile();
+  if (request.name && request.ifNotExists) {
+    const current = await store.get("sandbox", checkName(request.name));
+    if (current?.record.status === "created" && current.record.reference) {
+      const client2 = await session.connect(await session.profileNamed(current.record.profile));
+      try {
+        const box2 = await session.reopen(current.record, client2);
+        return { client: client2, box: box2, ...current, existing: true };
+      } catch (cause) {
+        if (!(cause instanceof SandbarError2) || cause.code !== "NOT_FOUND")
+          throw cause;
+        await store.remove("sandbox", current.record.name, current.version);
+      }
+    }
+  }
+  const limit = await session.limit();
+  if (limit !== null && await liveCount(store) >= limit)
+    throw new CliError("LIMIT_REACHED", `The store already holds ${limit} sandboxes (limits.maxSandboxes)`, "remove some with `sandbar rm`, or raise limits.maxSandboxes in sandbar.json");
+  const claimed = await claimName(store, {
+    format: 1,
+    kind: "sandbox",
+    status: "creating",
+    profile: profile.name,
+    provider: profile.provider,
+    createdAt: new Date().toISOString(),
+    labels: request.labels,
+    image: request.image ?? request.prepared,
+    reference: null
+  }, request.name, request.ifNotExists);
+  let client;
+  const input = createInput(request);
+  try {
+    client = await session.connect(profile);
+    if (input.environment) {
+      const plan = await client.sandboxes.checkCreate(input);
+      if (plan.status === "unsupported" || plan.status === "unavailable")
+        throw new CliError("UNSUPPORTED", `${profile.provider} cannot create this sandbox: ${plan.reason}`, request.image ? "this provider may need the image built first (sandbar image build arrives in a later release), or use --prepared with a provider image" : undefined);
+    }
+  } catch (cause) {
+    await store.remove("sandbox", claimed.record.name, claimed.version);
+    throw cause;
+  }
+  let box;
+  try {
+    box = await client.sandboxes.create(input, { signal: session.ctx.signal });
+  } catch (cause) {
+    const report = describeError(cause);
+    if (report.outcome === "rejected") {
+      await store.remove("sandbox", claimed.record.name, claimed.version);
+      if (report.code === "INVALID_ARGUMENT" && !input.environment)
+        throw new CliError("INVALID_ARGUMENT", `${profile.provider} needs an image for this sandbox: ${report.message}`, "pass --prepared <id> (a provider template or snapshot) or --image <oci-ref>");
+      throw cause;
+    }
+    const reference = report.known?.reference ?? null;
+    const recovery = report.known?.recovery;
+    let kept = `the store keeps ${claimed.record.name} so it can be inspected or removed`;
+    try {
+      await store.update("sandbox", claimed.record.name, { ...claimed.record, status: "unknown", reference, recovery }, claimed.version);
+    } catch (storeCause) {
+      kept = `the store could not record it (${describeError(storeCause).message}); keep the reference below`;
+    }
+    throw new CliError(report.outcome === "partial" ? "PARTIAL" : "OUTCOME_UNKNOWN", report.message, kept, { sandbox: claimed.record.name, reference, recovery }, report.outcome);
+  }
+  const record = { ...claimed.record, status: "created", reference: box.reference };
+  if (!box.reference)
+    session.ctx.out.note(`warning: ${profile.provider} returned no reopenable reference; later commands cannot reach ${record.name}`);
+  try {
+    await store.update("sandbox", record.name, record, claimed.version);
+  } catch (cause) {
+    const unrecorded = cause instanceof Error ? cause : new Error(String(cause));
+    return { client, box, record, existing: false, unrecorded };
+  }
+  return { client, box, record, existing: false };
+}
+function unrecordedError(created) {
+  return new CliError("STORE_WRITE_FAILED", `Created ${created.record.name} but could not record it in the store: ${created.unrecorded?.message}`, "save the reference below to a file and use `sandbar rm @<file>` to destroy it", { sandbox: created.record.name, reference: created.record.reference }, "partial");
+}
+function sandboxSummary(record) {
+  return {
+    name: record.name,
+    id: record.reference?.nativeId ?? null,
+    provider: record.provider,
+    profile: record.profile,
+    status: record.status,
+    createdAt: record.createdAt,
+    labels: record.labels,
+    image: record.image ?? null
+  };
+}
+async function findTarget(session, target) {
+  const store = await session.store();
+  if (target.startsWith("@")) {
+    const path = resolve3(session.ctx.cwd, target.slice(1));
+    const parsed = ResourceReference2.safeParse(JSON.parse(await readFile4(path, "utf8")));
+    if (!parsed.success || parsed.data.kind !== "sandbox")
+      throw usage(`${path} does not hold a sandbox reference`);
+    const profile = await session.profile();
+    return {
+      record: {
+        format: 1,
+        kind: "sandbox",
+        name: "from-file",
+        status: "created",
+        profile: profile.name,
+        provider: parsed.data.provider,
+        createdAt: new Date().toISOString(),
+        labels: {},
+        reference: { ...parsed.data, kind: "sandbox" }
+      },
+      version: "",
+      fromFile: true
+    };
+  }
+  if (RecordName.safeParse(target).success) {
+    const entry = await store.get("sandbox", target);
+    if (entry)
+      return entry;
+  }
+  const byId = (await listAll(store, "sandbox")).find((entry) => entry.record.reference?.nativeId === target);
+  if (byId)
+    return byId;
+  throw new CliError("NOT_FOUND", `No sandbox named ${target} in the store`, "list known sandboxes with `sandbar ls`");
+}
+async function createCommand(session, flags) {
+  const created = await createSandbox(session, createRequest(flags));
+  if (created.unrecorded)
+    throw unrecordedError(created);
+  session.ctx.out.success({
+    ...sandboxSummary(created.record),
+    existing: created.existing,
+    reference: created.record.reference
+  }, created.record.name);
+  return 0;
+}
+async function stateOf(session, record, client) {
+  if (!record.reference || !client)
+    return record.status === "created" ? "unreachable" : record.status;
+  try {
+    const box = await session.reopen(record, client);
+    return (await box.inspect({ signal: session.ctx.signal })).state;
+  } catch (cause) {
+    if (cause instanceof SandbarError2 && cause.code === "NOT_FOUND")
+      return "gone";
+    if (cause instanceof SandbarError2 && cause.code === "UNSUPPORTED")
+      return "unknown";
+    return "unreachable";
+  }
+}
+async function lsCommand(session, flags) {
+  const entries = await listAll(await session.store(), "sandbox", (warning) => session.ctx.out.note(warning));
+  const offline = flags.bool("offline");
+  const clients = new Map;
+  if (!offline)
+    for (const profile of new Set(entries.map((entry) => entry.record.profile))) {
+      try {
+        clients.set(profile, await session.connect(await session.profileNamed(profile)));
+      } catch {
+        clients.set(profile, null);
+      }
+    }
+  const rows = await Promise.all(entries.map(async ({ record }) => ({
+    ...sandboxSummary(record),
+    state: offline ? null : await stateOf(session, record, clients.get(record.profile) ?? null)
+  })));
+  const table = [
+    ["NAME", "STATE", "PROVIDER", "PROFILE", "ID", "CREATED"],
+    ...rows.map((row) => [
+      row.name,
+      row.state ?? row.status,
+      row.provider,
+      row.profile,
+      row.id ?? "-",
+      row.createdAt
+    ])
+  ];
+  const widths = table[0].map((_, column) => Math.max(...table.map((row) => row[column].length)));
+  session.ctx.out.success({ sandboxes: rows }, rows.length ? table.map((row) => row.map((cell, column) => cell.padEnd(widths[column])).join("  ").trimEnd()).join(`
+`) : "");
+  return 0;
+}
+function onePositional(flags, what) {
+  if (flags.positionals.length !== 1)
+    throw usage(`Expected exactly one ${what}`);
+  return flags.positionals[0];
+}
+async function inspectCommand(session, flags) {
+  const { record } = await recoverCreate(session, await session.store(), await findTarget(session, onePositional(flags, "sandbox")));
+  const box = await session.reopen(record);
+  const info = await box.inspect({ signal: session.ctx.signal });
+  const lines = [
+    `name      ${record.name}`,
+    `id        ${box.id}`,
+    `provider  ${record.provider} (profile ${record.profile})`,
+    `state     ${info.state}${info.nativeState ? ` (${info.nativeState})` : ""}`,
+    `expires   ${info.expires.status === "known" ? `${info.expires.at} (${info.expires.action})` : info.expires.status}`,
+    `observed  ${info.observedAt}`
+  ];
+  session.ctx.out.success({
+    ...sandboxSummary(record),
+    info: { ...info, reference: undefined },
+    reference: record.reference
+  }, lines.join(`
+`));
+  return 0;
+}
+function refusal(record) {
+  if (!record.reference)
+    return new CliError("UNSUPPORTED", `${record.name} has no reopenable reference (status ${record.status}); it cannot be destroyed from here`, "check the provider for it, then `sandbar rm --force` to drop the record", { sandbox: record.name });
+  if (record.reference.ownership !== "verified-created")
+    return new CliError("FORBIDDEN", `${record.name} was not created by this CLI (ownership ${record.reference.ownership})`, "pass --force to destroy it anyway", { sandbox: record.name });
+  return null;
+}
+function sameSandbox(a, b) {
+  if (a.createdAt !== b.createdAt || a.provider !== b.provider || a.profile !== b.profile)
+    return false;
+  return !a.reference || !b.reference || a.reference.nativeId === b.reference.nativeId;
+}
+async function forget(store, target) {
+  if (target.fromFile)
+    return;
+  for (let attempt = 0;; attempt++) {
+    const current = await store.get("sandbox", target.record.name);
+    if (!current || !sameSandbox(current.record, target.record))
+      return;
+    try {
+      await store.remove("sandbox", target.record.name, current.version);
+      return;
+    } catch (cause) {
+      if (!(cause instanceof CliError) || cause.code !== "CONFLICT" || attempt === 2)
+        throw cause;
+    }
+  }
+}
+async function recoverCreate(session, store, target) {
+  const { record } = target;
+  if (target.fromFile || record.status !== "unknown" || record.reference || !record.recovery)
+    return target;
+  if (record.recovery.kind !== "create")
+    return target;
+  const client = await session.connect(await session.profileNamed(record.profile));
+  let value;
+  try {
+    value = await (await client.recover(record.recovery)).observe();
+  } catch (cause) {
+    if (cause instanceof SandbarError2 && cause.effect !== "none")
+      return target;
+    throw cause;
+  }
+  if (!(value instanceof AdapterSandbox))
+    return target;
+  const { recovery: _recovery, ...rest } = record;
+  const recovered = { ...rest, status: "created", reference: value.reference };
+  const { version } = await store.update("sandbox", record.name, recovered, target.version);
+  session.ctx.out.note(`${record.name}: recovered the uncertain create as ${value.id}`);
+  return { record: recovered, version };
+}
+async function removeOne(session, store, found, force, all) {
+  const target = await recoverCreate(session, store, found).catch((cause) => {
+    if (force)
+      return found;
+    throw cause;
+  });
+  const { record } = target;
+  const refused = refusal(record);
+  if (refused && !force) {
+    if (all)
+      return {
+        kind: "skipped",
+        item: { name: record.name, result: "skipped", reason: refused.message }
+      };
+    throw refused;
+  }
+  if (!record.reference) {
+    await forget(store, target);
+    return {
+      kind: "removed",
+      item: { name: record.name, result: "forgotten", retainedResources: [] }
+    };
+  }
+  let box;
+  try {
+    box = await session.reopen(record);
+  } catch (cause) {
+    if (!(cause instanceof SandbarError2) || cause.code !== "NOT_FOUND")
+      throw cause;
+    await forget(store, target);
+    return { kind: "removed", item: { name: record.name, result: "gone", retainedResources: [] } };
+  }
+  const destroyed = await box.destroy({ signal: session.ctx.signal });
+  await forget(store, target);
+  return {
+    kind: "removed",
+    item: {
+      name: record.name,
+      result: "destroyed",
+      retainedResources: destroyed.retainedResources
+    }
+  };
+}
+async function rmCommand(session, flags) {
+  const store = await session.store();
+  const all = flags.bool("all");
+  const force = flags.bool("force");
+  const { out } = session.ctx;
+  if (all === Boolean(flags.positionals.length))
+    throw usage("Name sandboxes to remove, or pass --all");
+  const targets = all ? (await listAll(store, "sandbox", (warning) => out.note(warning))).map((entry) => ({
+    name: entry.record.name,
+    find: async () => entry
+  })) : flags.positionals.map((target) => ({
+    name: target,
+    find: () => findTarget(session, target)
+  }));
+  const details = {
+    removed: [],
+    skipped: [],
+    failed: []
+  };
+  let lastCause;
+  for (const target of targets) {
+    try {
+      const result = await removeOne(session, store, await target.find(), force, all);
+      if (result.kind === "skipped") {
+        details.skipped.push(result.item);
+        continue;
+      }
+      details.removed.push(result.item);
+      if (result.item.result === "gone")
+        out.note(`${result.item.name}: already gone`);
+      if (result.item.retainedResources.length)
+        out.note(`${result.item.name}: retained ${result.item.retainedResources.join(", ")}`);
+    } catch (cause) {
+      const report = describeError(cause);
+      lastCause = cause;
+      details.failed.push({
+        name: target.name,
+        result: "failed",
+        code: report.code,
+        reason: report.message
+      });
+    }
+  }
+  if (details.failed.length === 1 && targets.length === 1)
+    throw lastCause;
+  if (details.failed.length)
+    throw new CliError("PARTIAL", `Removed ${details.removed.length} of ${targets.length} sandboxes; ${details.failed.length} failed`, "see error.details; retry the failed names once the cause is fixed", undefined, "partial", details);
+  for (const item of details.skipped)
+    out.note(`skipped ${item.name}: ${item.reason}`);
+  out.success({ removed: details.removed, skipped: details.skipped }, details.removed.map((entry) => entry.name).join(`
+`));
+  return 0;
+}
+async function execInput(session, flags, command) {
+  if (flags.bool("stdin") && flags.string("stdin-file"))
+    throw usage("Pass either --stdin or --stdin-file");
+  const stdinFile = flags.string("stdin-file");
+  const stdin = flags.bool("stdin") ? await session.ctx.readStdin() : stdinFile ? new Uint8Array(await readFile4(resolve3(session.ctx.cwd, stdinFile))) : undefined;
+  const timeout = flags.string("timeout");
+  const maxOutput = flags.string("max-output");
+  const env = parsePairs(flags.strings("env"), "env");
+  return {
+    command,
+    cwd: flags.string("cwd"),
+    env: Object.keys(env).length ? env : undefined,
+    stdin,
+    deadlineSeconds: timeout ? parseDuration(timeout, "timeout") : undefined,
+    maxOutputBytes: maxOutput ? parseSize(maxOutput, "max-output") : undefined
+  };
+}
+function argvCommand(flags) {
+  if (!flags.rest?.length)
+    throw usage("Give the command after --, e.g. sandbar exec web -- ls -la");
+  return { kind: "argv", argv: [...flags.rest] };
+}
+async function execute(session, box, input) {
+  try {
+    return await box.exec(input, { signal: session.ctx.signal });
+  } catch (cause) {
+    if (!(cause instanceof NonzeroExitError))
+      throw cause;
+    return cause.result;
+  }
+}
+function execSummary(result) {
+  return {
+    exitCode: result.exitCode,
+    stdout: result.stdoutText({ full: true }),
+    stderr: result.stderrText({ full: true }),
+    truncated: result.truncated
+  };
+}
+function printStreams(out, result) {
+  if (out.json)
+    return;
+  if (result.stdout.byteLength)
+    out.streams.stdout(result.stdout);
+  if (result.stderr.byteLength)
+    out.streams.stderr(result.stderr);
+  if (result.truncated)
+    out.note("sandbar: output was truncated; raise --max-output to capture more");
+}
+function finishExec(out, result, sandbox) {
+  printStreams(out, result);
+  if (result.exitCode === null)
+    throw new CliError("OUTCOME_UNKNOWN", "The command ran but the provider reported no exit status", "the captured output is in error.known.exec", { exec: execSummary(result) });
+  if (out.json)
+    out.success({ ...execSummary(result), sandbox }, "");
+  return result.exitCode;
+}
+async function execCommand(session, flags) {
+  const { record } = await findTarget(session, onePositional(flags, "sandbox"));
+  const input = await execInput(session, flags, argvCommand(flags));
+  const box = await session.reopen(record);
+  return finishExec(session.ctx.out, await execute(session, box, input));
+}
+function shScript(flags) {
+  const [target, inline] = flags.positionals;
+  if (flags.rest && flags.positionals.length === 1 && flags.rest.length === 1)
+    return { target, script: flags.rest[0] };
+  if (!flags.rest && flags.positionals.length === 2)
+    return { target, script: inline };
+  throw usage("Usage: sandbar sh <sandbox> '<script>' (or put the script after --, as one argument)");
+}
+async function shCommand(session, flags) {
+  const { target, script } = shScript(flags);
+  const { record } = await findTarget(session, target);
+  const input = await execInput(session, flags, { kind: "shell", script });
+  const box = await session.reopen(record);
+  return finishExec(session.ctx.out, await execute(session, box, input));
+}
+async function runCommand(session, flags) {
+  if (flags.positionals.length)
+    throw usage("run takes no positional arguments; put the command after --");
+  const command = argvCommand(flags);
+  const request = createRequest(flags);
+  const input = await execInput(session, flags, command);
+  const keep = flags.bool("keep");
+  const created = await createSandbox(session, { ...request, ifNotExists: false });
+  const store = await session.store();
+  const { out, signal } = session.ctx;
+  let result;
+  let failure;
+  const sandbox = (kept) => ({
+    name: created.record.name,
+    id: created.record.reference?.nativeId ?? null,
+    kept
+  });
+  if (created.unrecorded)
+    failure = unrecordedError(created);
+  else
+    try {
+      result = await execute(session, created.box, input);
+    } catch (cause) {
+      failure = cause;
+    }
+  if (keep) {
+    out.note(`kept sandbox ${created.record.name}`);
+    if (failure)
+      throw failure;
+    return finishExec(out, result, sandbox(true));
+  }
+  try {
+    await created.box.destroy();
+    await store.remove("sandbox", created.record.name);
+  } catch (cause) {
+    const report = describeError(cause);
+    if (result)
+      printStreams(out, result);
+    throw new CliError("CLEANUP_FAILED", `Cleanup of ${created.record.name} failed: ${report.message}${failure ? `; the command also failed: ${describeError(failure).message}` : ""}`, `remove it with \`sandbar rm ${created.record.name}\``, {
+      sandbox: created.record.name,
+      reference: created.record.reference,
+      exec: result ? execSummary(result) : undefined
+    }, "partial");
+  }
+  if (failure && signal.aborted)
+    throw new CliError("INTERRUPTED", `Interrupted; sandbox ${created.record.name} was destroyed`, "the command may have partly run before the sandbox was destroyed", { sandbox: created.record.name, reference: created.record.reference }, "partial");
+  if (failure) {
+    if (failure instanceof CliError && failure.code === "STORE_WRITE_FAILED")
+      throw new CliError("STORE_WRITE_FAILED", `${failure.message}; the sandbox was destroyed, so nothing was run`);
+    throw failure;
+  }
+  return finishExec(out, result, sandbox(false));
+}
+var RemotePath = /^([a-z0-9][a-z0-9-]{0,62}):(\/.*)$/;
+function remote(spec) {
+  const match = RemotePath.exec(spec);
+  return match ? { target: match[1], path: match[2] } : null;
+}
+async function cpCommand(session, flags) {
+  if (flags.positionals.length !== 2)
+    throw usage("Usage: sandbar cp <src> <dst> (one side is <sandbox>:/path)");
+  if (flags.bool("recursive"))
+    throw usage("Recursive copy is not available yet; copy files one at a time");
+  const [source, destination] = [flags.positionals[0], flags.positionals[1]];
+  const from = remote(source);
+  const to = remote(destination);
+  if (Boolean(from) === Boolean(to))
+    throw usage("Exactly one side of cp must be <sandbox>:/path");
+  if (to) {
+    const local2 = resolve3(session.ctx.cwd, source);
+    if ((await stat2(local2)).isDirectory())
+      throw usage(`${source} is a directory; recursive copy is not available yet`);
+    const bytes2 = new Uint8Array(await readFile4(local2));
+    const { record: record2 } = await findTarget(session, to.target);
+    const box2 = await session.reopen(record2);
+    await box2.writeFile(to.path, bytes2, {
+      overwrite: !flags.bool("no-clobber"),
+      signal: session.ctx.signal
+    });
+    session.ctx.out.success({ sandbox: record2.name, path: to.path, bytes: bytes2.byteLength }, "");
+    return 0;
+  }
+  const { record } = await findTarget(session, from.target);
+  const box = await session.reopen(record);
+  const bytes = await box.readFile(from.path, { signal: session.ctx.signal });
+  let local = resolve3(session.ctx.cwd, destination);
+  try {
+    if ((await stat2(local)).isDirectory())
+      local = join4(local, basename(from.path));
+  } catch {}
+  try {
+    await writeFile2(local, bytes, { flag: flags.bool("no-clobber") ? "wx" : "w" });
+  } catch (cause) {
+    if (cause instanceof Error && "code" in cause && cause.code === "EEXIST")
+      throw new CliError("CONFLICT", `${local} already exists`, "drop --no-clobber to overwrite it");
+    throw cause;
+  }
+  session.ctx.out.success({ sandbox: record.name, path: local, bytes: bytes.byteLength }, "");
+  return 0;
+}
+async function catCommand(session, flags) {
+  const location = remote(onePositional(flags, "<sandbox>:/path"));
+  if (!location)
+    throw usage("Usage: sandbar cat <sandbox>:/path");
+  const { record } = await findTarget(session, location.target);
+  const box = await session.reopen(record);
+  const bytes = await box.readFile(location.path, { signal: session.ctx.signal });
+  const { out } = session.ctx;
+  if (!out.json) {
+    out.streams.stdout(bytes);
+    return 0;
+  }
+  let text = null;
+  try {
+    text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  } catch {}
+  out.success(text === null ? {
+    path: location.path,
+    bytes: bytes.byteLength,
+    base64: Buffer.from(bytes).toString("base64")
+  } : { path: location.path, bytes: bytes.byteLength, text }, "");
+  return 0;
+}
+async function doctorCommand(session) {
+  const loaded = await session.config();
+  const profile = await session.profile();
+  const client = await session.connect(profile);
+  const capabilities = await client.capabilities();
+  let plan;
+  try {
+    plan = await client.sandboxes.checkCreate();
+  } catch (cause) {
+    plan = { status: "unavailable", reason: describeError(cause).message };
+  }
+  const store = await session.store();
+  const count = (await listAll(store, "sandbox")).length;
+  session.ctx.out.success({
+    config: { path: loaded.path, exists: loaded.exists },
+    profile: profile.name,
+    provider: profile.provider,
+    connected: true,
+    create: plan,
+    sandboxesInStore: count,
+    capabilities
+  }, [
+    `config    ${loaded.path}${loaded.exists ? "" : " (not found, using defaults)"}`,
+    `profile   ${profile.name} (${profile.provider})`,
+    "connect   ok",
+    `create    ${plan.status}${plan.status === "supported" ? "" : `: ${plan.reason}`}`,
+    `store     ${count} sandbox record(s)`
+  ].join(`
+`));
+  return 0;
+}
+function profileKeys(loaded, provider, env) {
+  return new Set(Object.values(loaded.value.profiles ?? {}).filter((profile) => profile.provider === provider).flatMap((profile) => [
+    ...Object.entries(profile.config ?? {}),
+    ...Object.entries(profile.credentials ?? {})
+  ].flatMap(([key, value]) => valueAvailable(value, env) ? [key] : [])));
+}
+async function providersCommand(session) {
+  const { env, cwd } = session.ctx;
+  const loaded = await session.config();
+  const rows = await Promise.all(providers.map(async (provider) => {
+    const resolved = await resolveAdapterModule({
+      name: provider.id,
+      provider: provider.id,
+      module: provider.module,
+      export: provider.export,
+      baseDir: cwd,
+      searchProject: searchProjectAdapters(loaded, env),
+      config: {},
+      credentials: {}
+    }, cwd, env);
+    let installed = resolved !== provider.module;
+    if (!installed)
+      try {
+        import.meta.resolve(provider.module);
+        installed = true;
+      } catch {
+        installed = false;
+      }
+    return {
+      id: provider.id,
+      module: provider.module,
+      experimental: provider.experimental,
+      installed,
+      missingEnv: missingEnv(provider, env, profileKeys(loaded, provider.id, env))
+    };
+  }));
+  session.ctx.out.success({ providers: rows }, rows.map((row) => `${row.id.padEnd(8)} ${row.installed ? "installed" : "not installed"}  ${row.missingEnv.length ? `needs ${row.missingEnv.join(", ")}` : "credentials set"}${row.experimental ? "  (experimental)" : ""}`).join(`
+`));
+  return 0;
+}
+
+// src/secrets.ts
+import { execFile } from "node:child_process";
+import { z as z5 } from "zod";
+var BwsSecret = z5.object({ value: z5.string() });
+var backends = [
+  {
+    name: "1Password",
+    pattern: /^op:\/\/[^/\s]+\/[^/\s]+(\/[^/\s]+){1,2}(\?\S*)?$/,
+    command: "op",
+    args: (reference) => ["read", "--no-newline", reference],
+    value: (stdout) => stdout,
+    install: "install the 1Password CLI (https://developer.1password.com/docs/cli) and sign in",
+    check: "check `op whoami` and that the vault, item and field exist"
+  },
+  {
+    name: "Bitwarden Secrets Manager",
+    pattern: /^bws:\/\/[0-9a-fA-F-]{36}$/,
+    command: "bws",
+    args: (reference) => ["secret", "get", reference.slice("bws://".length), "--output", "json"],
+    value: (stdout) => BwsSecret.parse(JSON.parse(stdout)).value,
+    install: "install the Bitwarden Secrets Manager CLI (https://bitwarden.com/help/secrets-manager-cli/) and set BWS_ACCESS_TOKEN",
+    check: "check BWS_ACCESS_TOKEN and that the machine account can read the secret"
+  },
+  {
+    name: "pass",
+    pattern: /^pass:\/\/(?!.*(^|\/)\.\.(\/|$))[\w@+.-]+(\/[\w@+.-]+)*$/,
+    command: "pass",
+    args: (reference) => ["show", reference.slice("pass://".length)],
+    value: (stdout) => stdout.split(`
+`)[0] ?? "",
+    install: "install pass (https://www.passwordstore.org) and initialise your store",
+    check: "check that `pass show <path>` works, including the GPG agent"
+  }
+];
+function backendFor(value) {
+  return backends.find((backend) => backend.pattern.test(value));
+}
+function run(command, args, env, signal) {
+  return new Promise((done) => {
+    execFile(command, args, { env: { ...env }, signal, timeout: 60000, maxBuffer: 1024 * 1024 }, (error, stdout, stderr) => done({
+      code: error ? error.code ?? "FAILED" : 0,
+      stdout: String(stdout),
+      stderr: String(stderr)
+    }));
+  });
+}
+
+class SecretReader {
+  env;
+  signal;
+  cache = new Map;
+  constructor(env, signal) {
+    this.env = env;
+    this.signal = signal;
+  }
+  read(backend, reference, where) {
+    let pending = this.cache.get(reference);
+    if (!pending) {
+      pending = this.fetch(backend, reference, where);
+      this.cache.set(reference, pending);
+    }
+    return pending;
+  }
+  async fetch(backend, reference, where) {
+    const result = await run(backend.command, backend.args(reference), this.env, this.signal);
+    if (result.code === "ENOENT")
+      throw new CliError("SECRET_TOOL_MISSING", `${where} is a ${backend.name} reference, but \`${backend.command}\` is not installed`, backend.install);
+    if (result.code !== 0)
+      throw new CliError("SECRET_UNAVAILABLE", `Cannot read ${where} from ${backend.name} (${reference}): ${result.stderr.trim() || `${backend.command} exited with ${result.code}`}`, backend.check);
+    try {
+      return backend.value(result.stdout);
+    } catch {
+      throw new CliError("SECRET_UNAVAILABLE", `${backend.name} returned an unreadable answer for ${where} (${reference})`, backend.check);
+    }
+  }
+  async resolve(value, where) {
+    const text = z5.string().safeParse(value);
+    if (text.success) {
+      const backend = backendFor(text.data);
+      return backend ? this.read(backend, text.data, where) : value;
+    }
+    if (Array.isArray(value))
+      return Promise.all(value.map((item, index) => this.resolve(item, `${where}[${index}]`)));
+    const record = z5.record(z5.string(), z5.json()).safeParse(value);
+    if (record.success)
+      return Object.fromEntries(await Promise.all(Object.entries(record.data).map(async ([key, item]) => [key, await this.resolve(item, `${where}.${key}`)])));
+    return value;
+  }
+}
+
+// src/session.ts
+class Session {
+  ctx;
+  loaded;
+  opened = [];
+  secrets;
+  constructor(ctx) {
+    this.ctx = ctx;
+    this.secrets = new SecretReader(ctx.env, ctx.signal);
+  }
+  async config() {
+    this.loaded ??= await loadConfig(this.ctx.flags.config, this.ctx.env);
+    return this.loaded;
+  }
+  async store() {
+    const { flags, env, cwd } = this.ctx;
+    return new FsStateStore(stateDir(flags.stateDir, await this.config(), env, cwd));
+  }
+  async limit() {
+    return maxSandboxes(await this.config(), this.ctx.env);
+  }
+  async profile() {
+    return resolveProfile(this.ctx.flags, await this.config(), this.ctx.env);
+  }
+  async profileNamed(name) {
+    const loaded = await this.config();
+    if (loaded.value.profiles?.[name])
+      return resolveProfile({ profile: name }, loaded, this.ctx.env);
+    if (descriptor(name))
+      return resolveProfile({ provider: name }, loaded, this.ctx.env);
+    throw new CliError("USAGE", `Profile ${name} is no longer defined`, `restore it in ${loaded.path}; the sandbox was created with it`);
+  }
+  async connect(profile) {
+    const client = await connect(profile, this.ctx.cwd, this.ctx.env, this.secrets);
+    this.opened.push(client);
+    return client;
+  }
+  async reopen(record, client) {
+    if (!record.reference)
+      throw new CliError("UNSUPPORTED", `Sandbox ${record.name} has no reopenable reference (status ${record.status})`, "inspect it with the provider's own tools; `sandbar rm --force` drops the record");
+    const connected = client ?? await this.connect(await this.profileNamed(record.profile));
+    return connected.sandboxes.get(record.reference, { signal: this.ctx.signal });
+  }
+  async close() {
+    await Promise.allSettled(this.opened.splice(0).map((client) => client.close()));
+  }
+}
+
+// src/skill.ts
+import { access as access2, mkdir as mkdir2, readFile as readFile5, writeFile as writeFile3 } from "node:fs/promises";
+import { homedir as homedir2 } from "node:os";
+import { dirname as dirname3, join as join5 } from "node:path";
+
+// ../../skills/sandbar-cli/SKILL.md
+var SKILL_default = "---\nname: sandbar-cli\ndescription: Create, use and clean up cloud sandboxes from the shell with the `sandbar` CLI (Daytona, E2B, boxd, Vercel, Modal). Use when you need an isolated machine to run untrusted or generated code, try a build or test in a clean environment, or manage sandboxes someone created with sandbar; prefer it over provider-specific CLIs.\n---\n\n# Use sandboxes with the sandbar CLI\n\n`sandbar` creates and manages sandboxes on any Sandbar provider. It is built for agents: it never prompts, every command has a stable `--json` form, and exit codes tell you what to do next.\n\n## Check the setup first\n\n```sh\nsandbar doctor --json      # config, credentials, provider connection; creates nothing\nsandbar providers --json   # which adapters are installed and which credentials are missing\n```\n\n- If `sandbar` is not on PATH, stop and tell the user; do not install anything yourself.\n- The provider comes from `--profile`, `SANDBAR_PROFILE`, `--provider`, `SANDBAR_PROVIDER`, then `default` in `~/.config/sandbar/sandbar.json`. Do not edit that file or credentials unless the user asks.\n- A missing adapter (exit 4, `ADAPTER_NOT_INSTALLED`) or missing credential (exit 2) is the user's to fix. Report the `hint` from the error.\n\n**Sandboxes cost money.** Create only what the task needs and destroy it when done.\n\n## Always use JSON\n\nPass `--json` (or set `SANDBAR_JSON=1`). stdout then holds exactly one document:\n\n```json\n{\"ok\": true, \"data\": {...}}\n{\"ok\": false, \"error\": {\"code\": \"...\", \"message\": \"...\", \"retryable\": false, \"outcome\": \"rejected\", \"hint\": \"...\", \"known\": {...}}}\n```\n\nDiagnostics go to stderr. Read `error.hint` before deciding what to do.\n\n## One-shot work: `run`\n\n`run` creates a sandbox, runs one command and always destroys it. Prefer it whenever you do not need the sandbox afterwards.\n\n```sh\nsandbar run --json -- python3 -c 'print(2 + 2)'\nsandbar run --json --prepared base --timeout 5m -- sh -c 'pip install -q requests && python3 app.py'\n```\n\nPass the command after `--` as separate arguments. Its data is `{exitCode, stdout, stderr, truncated, sandbox}`, where `sandbox` names the sandbox it created and destroyed.\n\n## Longer work: create, use, remove\n\n```sh\nsandbar create --json --name job-1 --prepared base   # prints the name; reuse it everywhere\nsandbar cp ./app.py job-1:/home/user/app.py\nsandbar exec --json job-1 --cwd /home/user -- python3 app.py\nsandbar sh --json job-1 'cd /home/user && ls -la | head'\nsandbar cat job-1:/home/user/out.txt\nsandbar rm --json job-1\n```\n\n- Give sandboxes a `--name` so you can find them again; names are lowercase letters, digits and dashes. `--if-not-exists` reuses a live sandbox with that name instead of failing.\n- `exec` takes an argv after `--`; no shell runs. Use `sh` only when you need pipes, redirects or `&&`. For a script that starts with `-`, put it after `--`: `sandbar sh job-1 -- '-n ...'`.\n- `--env K=V` (repeatable), `--cwd`, `--stdin` or `--stdin-file <path>`, `--timeout 30s|5m|1h`, `--max-output 1m`.\n- `cp` copies one file; one side is `<sandbox>:/absolute/path`. `--no-clobber` refuses to overwrite.\n- `--image <oci-ref>` boots an OCI image where the provider supports it; `--prepared <id>` uses a provider template or snapshot. On providers that need an image built first, `--image` fails with exit 4 before creating anything.\n- `sandbar ls --json` lists known sandboxes with their live state (`running`, `gone`, `unreachable`, ...). `sandbar inspect --json <name>` shows state, expiry and the saved reference.\n\nAlways `rm` what you created before finishing, even after failures. `rm` only destroys sandboxes this CLI created; never pass `--force` or `rm --all` unless the user asked.\n\n## Exit codes\n\n`exec`, `sh` and `run` exit with the **remote command's** exit code. Their own failures always exit **125**, with the error in the JSON document. A command that ran but reported no exit status is 125 with `OUTCOME_UNKNOWN`; its output is in `error.known.exec`. It is never success.\n\nOther commands:\n\n| Code | Meaning                                                           | What to do                                           |\n| ---- | ----------------------------------------------------------------- | ---------------------------------------------------- |\n| 0    | success                                                           |                                                      |\n| 1    | other failure, including a name already taken                     | read the message                                     |\n| 2    | usage or local error                                              | fix the command; `sandbar <command> --help`          |\n| 3    | not found                                                         | `sandbar ls`                                         |\n| 4    | unsupported, adapter or tool not installed, limit reached         | tell the user; do not work around it                 |\n| 5    | authentication, permission, or unreadable password-manager secret | tell the user                                        |\n| 6    | **outcome unknown**: the effect may have happened                 | **do not retry**; run `sandbar ls` / `inspect` first |\n| 7    | retryable (rate limit, capacity, unavailable) before any effect   | wait, then retry once or twice                       |\n| 8    | partial: some steps happened                                      | read `error.known` and `error.details`               |\n\n## When things go wrong\n\n- **Never repeat a create after exit 6 or `outcome: \"unknown\"`.** The store keeps the name in status `unknown`; check `sandbar ls --json`. `sandbar rm <name>` first asks the provider how that create ended (never resending it) and destroys the sandbox if one exists. If it still exits 4 because the outcome is unknown, and the user agrees it is gone, `sandbar rm --force <name>` drops the record.\n- **`run` exits 125 with `CLEANUP_FAILED`**: the command result is in `error.known.exec`, but the sandbox is still running. Tell the user and run the `rm` from the hint.\n- **`rm` exits 8**: `error.details` lists what was `removed`, `skipped` and `failed`. Retry only the failed names once the cause is fixed.\n- **`STORE_WRITE_FAILED`**: the sandbox exists but was not recorded. The reference is in `error.known.reference`; save it to a file and destroy with `sandbar rm @file.json`.\n- Interrupting `run` (Ctrl-C, SIGTERM) still destroys its sandbox and exits 130 (143 for SIGTERM) with `INTERRUPTED`. A second signal exits immediately and may leave it running.\n\n## Discover more\n\n`sandbar schema` prints every command, flag and exit code as JSON. `sandbar <command> --help` shows usage and examples.\n";
+
+// src/skill.ts
+var skillName = "sandbar-cli";
+var marker = "<!-- Installed by `sandbar skill install`; rerun it to update this file. -->";
+async function exists2(path) {
+  try {
+    await access2(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function skillRoots(base) {
+  const roots = [join5(base, ".agents", "skills")];
+  if (await exists2(join5(base, ".claude")))
+    roots.push(join5(base, ".claude", "skills"));
+  return roots;
+}
+async function installAt(root, content) {
+  const path = join5(root, skillName, "SKILL.md");
+  let current = null;
+  try {
+    current = await readFile5(path, "utf8");
+  } catch (cause) {
+    if (!(cause instanceof Error && ("code" in cause) && cause.code === "ENOENT"))
+      throw cause;
+  }
+  if (current === content)
+    return { path, result: "unchanged" };
+  if (current !== null && !current.includes(marker))
+    return {
+      path,
+      result: "skipped",
+      reason: "a copy installed another way is already there; remove it to let sandbar manage it"
+    };
+  await mkdir2(dirname3(path), { recursive: true });
+  await writeFile3(path, content);
+  return { path, result: current === null ? "written" : "updated" };
+}
+async function skillCommand(session, flags) {
+  const [action, ...extra] = flags.positionals;
+  const { out, env, cwd } = session.ctx;
+  if (extra.length || action !== undefined && action !== "install")
+    throw usage("Usage: sandbar skill [install [--project]]");
+  if (action === undefined) {
+    if (flags.bool("project"))
+      throw usage("--project only applies to `sandbar skill install`");
+    if (out.json)
+      out.success({ name: skillName, content: SKILL_default }, "");
+    else
+      out.streams.stdout(SKILL_default);
+    return 0;
+  }
+  const content = `${SKILL_default.trimEnd()}
+
+${marker}
+`;
+  const base = flags.bool("project") ? cwd : env.HOME || homedir2();
+  const results = await Promise.all((await skillRoots(base)).map((root) => installAt(root, content)));
+  if (results.every((entry) => entry.result === "skipped"))
+    throw new CliError("CONFLICT", `The ${skillName} skill is already installed another way: ${results.map((entry) => entry.path).join(", ")}`, "remove those files and rerun, or update them with the tool that installed them");
+  for (const entry of results)
+    if (entry.reason)
+      out.note(`skipped ${entry.path}: ${entry.reason}`);
+  out.success({ name: skillName, installed: results }, results.filter((entry) => entry.result !== "skipped").map((entry) => `${entry.result.padEnd(9)} ${entry.path}`).join(`
+`));
+  return 0;
+}
+
+// src/completion.ts
+var NoSpace = 1;
+var Files = 2;
+var fileFlags = new Set(["config", "state-dir", "stdin-file"]);
+var sandboxArguments = new Map([
+  ["inspect", 1],
+  ["exec", 1],
+  ["sh", 1],
+  ["rm", Infinity]
+]);
+async function sandboxNames(session) {
+  const entries = await listAll(await session.store(), "sandbox");
+  return entries.map(({ record }) => ({
+    value: record.name,
+    description: `${record.provider}, ${record.status}`
+  }));
+}
+async function profileNames(session) {
+  const loaded = await session.config();
+  return Object.keys(loaded.value.profiles ?? {}).map((name) => ({ value: name }));
+}
+function flagCandidates(flags, globals) {
+  return Object.entries({ ...globals, ...flags }).filter(([name]) => name !== "help").map(([name, spec]) => ({ value: `--${name}`, description: spec.description }));
+}
+async function complete(words, commands, globals, session) {
+  const current = words.at(-1) ?? "";
+  const before = words.slice(0, -1);
+  const none = { candidates: [], directive: 0 };
+  if (before.includes("--"))
+    return { candidates: [], directive: Files };
+  let command;
+  const positionals = [];
+  for (let index = 0;index < before.length; index++) {
+    const word = before[index];
+    if (word.startsWith("--")) {
+      const spec = { ...globals, ...command?.flags }[word.slice(2)];
+      if (spec?.type === "string" && !word.includes("="))
+        index++;
+      continue;
+    }
+    if (!command)
+      command = commands.find((candidate) => candidate.name === word);
+    else
+      positionals.push(word);
+  }
+  const previous = before.at(-1);
+  const valueOf = previous?.startsWith("--") ? { ...globals, ...command?.flags }[previous.slice(2)] : undefined;
+  if (previous && valueOf?.type === "string") {
+    const flag = previous.slice(2);
+    if (fileFlags.has(flag))
+      return { candidates: [], directive: Files };
+    if (flag === "profile")
+      return { candidates: await profileNames(session), directive: 0 };
+    if (flag === "provider")
+      return {
+        candidates: providers.map((provider) => ({ value: provider.id })),
+        directive: 0
+      };
+    return none;
+  }
+  if (current.startsWith("-"))
+    return { candidates: flagCandidates(command?.flags ?? {}, globals), directive: 0 };
+  if (!command)
+    return {
+      candidates: commands.map((candidate) => ({
+        value: candidate.name,
+        description: candidate.summary
+      })),
+      directive: 0
+    };
+  const limit = sandboxArguments.get(command.name);
+  if (limit !== undefined)
+    return positionals.length < limit ? { candidates: await sandboxNames(session), directive: 0 } : none;
+  if (command.name === "cp" || command.name === "cat") {
+    if (current.includes(":"))
+      return none;
+    const remote2 = (await sandboxNames(session)).map((entry) => ({
+      ...entry,
+      value: `${entry.value}:`
+    }));
+    return { candidates: remote2, directive: NoSpace | (command.name === "cp" ? Files : 0) };
+  }
+  if (command.name === "skill" && positionals.length === 0)
+    return {
+      candidates: [{ value: "install", description: "Install the skill for your agents" }],
+      directive: 0
+    };
+  if (command.name === "completion" && positionals.length === 0)
+    return { candidates: shells.map((shell) => ({ value: shell })), directive: 0 };
+  return none;
+}
+function formatCompletion(completion) {
+  const lines = completion.candidates.map((candidate) => candidate.description ? `${candidate.value}	${candidate.description.replaceAll(/\s+/g, " ")}` : candidate.value);
+  return `${[...lines, `:${completion.directive}`].join(`
+`)}
+`;
+}
+var zsh = `#compdef sandbar
+# sandbar completion for zsh. Enable with: source <(sandbar completion zsh)
+
+_sandbar() {
+  local -a lines described plain
+  local line value description directive
+  lines=("\${(@f)$(command sandbar __complete -- "\${(@)words[2,CURRENT]}" 2>/dev/null)}")
+  directive=\${lines[-1]#:}
+  lines=("\${(@)lines[1,-2]}")
+
+  for line in "\${lines[@]}"; do
+    [[ -z $line ]] && continue
+    value=\${line%%$'\\t'*}
+    if [[ $line == *$'\\t'* ]]; then
+      description=\${line#*$'\\t'}
+      described+=("\${value//:/\\\\:}:$description")
+    else
+      plain+=("$value")
+    fi
+  done
+
+  local -a suffix
+  (( directive & 1 )) && suffix=(-S '')
+  (( \${#described} )) && _describe -t sandbar sandbar described "\${suffix[@]}"
+  (( \${#plain} )) && compadd "\${suffix[@]}" -a plain
+  (( directive & 2 )) && _files
+  return 0
+}
+
+if [[ $zsh_eval_context[-1] == loadautofunc ]]; then
+  _sandbar "$@"
+else
+  compdef _sandbar sandbar
+fi
+`;
+var bash = `# sandbar completion for bash. Enable with: source <(sandbar completion bash)
+
+_sandbar() {
+  local line current output directive
+  local -a words candidates
+  # Split the line ourselves so "name:/path" stays one word whatever COMP_WORDBREAKS says.
+  line=\${COMP_LINE:0:COMP_POINT}
+  read -ra words <<< "$line"
+  [[ $line == *" " ]] && words+=("")
+  current=\${words[-1]}
+  output=$(command sandbar __complete -- "\${words[@]:1}" 2>/dev/null) || return 0
+  directive=\${output##*:}
+  output=\${output%:*}
+
+  while IFS= read -r candidate; do
+    [[ -z $candidate ]] && continue
+    candidate=\${candidate%%$'\\t'*}
+    [[ $candidate == "$current"* ]] && candidates+=("$candidate")
+  done <<< "$output"
+
+  if (( directive & 2 )); then
+    local file
+    while IFS= read -r file; do candidates+=("$file"); done < <(compgen -f -- "$current")
+  fi
+
+  # bash replaces only the text after the last ':' when ':' is a word break.
+  if [[ $current == *:* && $COMP_WORDBREAKS == *:* ]]; then
+    local prefix=\${current%:*}:
+    candidates=("\${candidates[@]#"$prefix"}")
+  fi
+
+  COMPREPLY=("\${candidates[@]}")
+  (( directive & 1 )) && compopt -o nospace 2>/dev/null
+  return 0
+}
+
+complete -F _sandbar sandbar
+`;
+var fish = `# sandbar completion for fish. Enable with: sandbar completion fish | source
+
+function __sandbar_complete
+    set -l words (commandline -opc)[2..-1] (commandline -ct)
+    set -l output (command sandbar __complete -- $words 2>/dev/null)
+    set -l directive (string replace ':' '' -- $output[-1])
+    string join \\n -- $output[1..-2]
+    if test (math "bitand($directive, 2)") -ne 0
+        __fish_complete_path (commandline -ct)
+    end
+end
+
+complete -c sandbar -f -a '(__sandbar_complete)'
+`;
+var scripts = { zsh, bash, fish };
+var shells = Object.keys(scripts);
+async function completionCommand(session, flags) {
+  const shell = flags.positionals[0];
+  const script = Object.entries(scripts).find(([name]) => name === shell)?.[1];
+  if (flags.positionals.length !== 1 || !script)
+    throw usage(`Usage: sandbar completion <${shells.join("|")}>`, "e.g. source <(sandbar completion zsh)");
+  session.ctx.out.streams.stdout(script);
+  return 0;
+}
+
+// src/cli.ts
+var globalFlags = {
+  json: { type: "boolean", description: "Print one JSON document on stdout (also SANDBAR_JSON=1)" },
+  profile: {
+    type: "string",
+    value: "name",
+    description: "Profile from sandbar.json (also SANDBAR_PROFILE)"
+  },
+  provider: {
+    type: "string",
+    value: "id",
+    description: "Official provider from environment credentials (also SANDBAR_PROVIDER)"
+  },
+  config: {
+    type: "string",
+    value: "path",
+    description: "Config file (default ~/.config/sandbar/sandbar.json, also SANDBAR_CONFIG)"
+  },
+  "state-dir": {
+    type: "string",
+    value: "dir",
+    description: "State store folder (default ~/.config/sandbar/state, also SANDBAR_STATE_DIR)"
+  },
+  help: { type: "boolean", short: "h", description: "Show help" },
+  version: { type: "boolean", short: "V", description: "Print the CLI version" }
+};
+var createFlags = {
+  name: {
+    type: "string",
+    value: "name",
+    description: "Store name (default: generated, like sb-1a2b3)"
+  },
+  image: {
+    type: "string",
+    value: "oci-ref",
+    description: "OCI image, e.g. python:3.12; default is the profile's image"
+  },
+  prepared: {
+    type: "string",
+    value: "id",
+    description: "Provider-prepared image id (template, snapshot name)"
+  },
+  network: {
+    type: "string",
+    value: "policy",
+    description: "blocked or internet; default is the profile's policy"
+  },
+  label: { type: "string", multiple: true, value: "k=v", description: "Label to set (repeatable)" },
+  build: {
+    type: "boolean",
+    description: "Build --image first when the provider needs it (not available yet)"
+  }
+};
+var execFlags = {
+  cwd: { type: "string", value: "dir", description: "Working directory in the sandbox" },
+  env: {
+    type: "string",
+    multiple: true,
+    value: "K=V",
+    description: "Environment variable (repeatable)"
+  },
+  stdin: { type: "boolean", description: "Send this process's stdin to the command" },
+  "stdin-file": {
+    type: "string",
+    value: "path",
+    description: "Send a local file as the command's stdin"
+  },
+  timeout: {
+    type: "string",
+    value: "duration",
+    description: "Execution deadline, e.g. 90s or 10m (default 300s)"
+  },
+  "max-output": { type: "string", value: "size", description: "Captured output limit, e.g. 1m" }
+};
+var commands = [
+  {
+    name: "create",
+    summary: "Create a sandbox and print its name",
+    usage: "sandbar create [--name <name>] [--image <oci-ref> | --prepared <id>] [--network <policy>]",
+    flags: {
+      ...createFlags,
+      "if-not-exists": {
+        type: "boolean",
+        description: "Return the named sandbox if it is still alive instead of failing"
+      }
+    },
+    passthrough: false,
+    remoteExit: false,
+    examples: [
+      "sandbar create --name web --network internet",
+      "sandbar create --name job-42 --if-not-exists --json"
+    ],
+    run: createCommand
+  },
+  {
+    name: "ls",
+    summary: "List sandboxes in the store with their current state",
+    usage: "sandbar ls [--offline]",
+    flags: {
+      offline: { type: "boolean", description: "Show stored records without asking providers" }
+    },
+    passthrough: false,
+    remoteExit: false,
+    examples: ["sandbar ls", "sandbar ls --json"],
+    run: lsCommand
+  },
+  {
+    name: "inspect",
+    summary: "Show a sandbox's state, expiry and reference",
+    usage: "sandbar inspect <sandbox>",
+    flags: {},
+    passthrough: false,
+    remoteExit: false,
+    examples: ["sandbar inspect web --json"],
+    run: inspectCommand
+  },
+  {
+    name: "rm",
+    summary: "Destroy sandboxes and remove their records",
+    usage: "sandbar rm <sandbox>... | --all [--force]",
+    flags: {
+      all: { type: "boolean", description: "Every sandbox in this store" },
+      force: {
+        type: "boolean",
+        description: "Also destroy sandboxes this CLI did not create, or drop unreachable records"
+      }
+    },
+    passthrough: false,
+    remoteExit: false,
+    examples: ["sandbar rm web", "sandbar rm --all"],
+    run: rmCommand
+  },
+  {
+    name: "exec",
+    summary: "Run a command in a sandbox; exits with the command's exit code",
+    usage: "sandbar exec <sandbox> [--cwd <dir>] [--env K=V]... [--stdin] -- <command> [args...]",
+    flags: execFlags,
+    passthrough: true,
+    remoteExit: true,
+    examples: [
+      "sandbar exec web -- ls -la /",
+      "sandbar exec web --cwd /work --env CI=1 -- npm test"
+    ],
+    run: execCommand
+  },
+  {
+    name: "sh",
+    summary: "Run a shell script in a sandbox; exits with its exit code",
+    usage: "sandbar sh <sandbox> '<script>' | sandbar sh <sandbox> -- '<script>'",
+    flags: execFlags,
+    passthrough: true,
+    remoteExit: true,
+    examples: ["sandbar sh web 'cd /work && make test'", "sandbar sh web -- '-n is fine here'"],
+    run: shCommand
+  },
+  {
+    name: "run",
+    summary: "Create a sandbox, run one command, and always destroy it",
+    usage: "sandbar run [create flags] [exec flags] [--keep] -- <command> [args...]",
+    flags: {
+      ...createFlags,
+      ...execFlags,
+      keep: { type: "boolean", description: "Keep the sandbox and print its name on stderr" }
+    },
+    passthrough: true,
+    remoteExit: true,
+    examples: [
+      "sandbar run -- python3 -c 'print(2 + 2)'",
+      "sandbar run --network internet -- curl -sI https://example.com"
+    ],
+    run: runCommand
+  },
+  {
+    name: "cp",
+    summary: "Copy one file to or from a sandbox",
+    usage: "sandbar cp <src> <dst>   (one side is <sandbox>:/path)",
+    flags: {
+      "no-clobber": {
+        type: "boolean",
+        description: "Fail instead of overwriting a file in the sandbox"
+      },
+      recursive: {
+        type: "boolean",
+        short: "r",
+        description: "Copy directories (not available yet)"
+      }
+    },
+    passthrough: false,
+    remoteExit: false,
+    examples: ["sandbar cp ./app.py web:/work/app.py", "sandbar cp web:/work/out.json ./out.json"],
+    run: cpCommand
+  },
+  {
+    name: "cat",
+    summary: "Print a file from a sandbox",
+    usage: "sandbar cat <sandbox>:/path",
+    flags: {},
+    passthrough: false,
+    remoteExit: false,
+    examples: ["sandbar cat web:/etc/os-release"],
+    run: catCommand
+  },
+  {
+    name: "doctor",
+    summary: "Check config, credentials and the provider connection without creating anything",
+    usage: "sandbar doctor",
+    flags: {},
+    passthrough: false,
+    remoteExit: false,
+    examples: ["sandbar doctor --provider e2b"],
+    run: doctorCommand
+  },
+  {
+    name: "providers",
+    summary: "List official providers, whether their adapter is installed and their credentials set",
+    usage: "sandbar providers",
+    flags: {},
+    passthrough: false,
+    remoteExit: false,
+    examples: ["sandbar providers --json"],
+    run: providersCommand
+  },
+  {
+    name: "skill",
+    summary: "Print the agent skill for this CLI, or install it for your coding agents",
+    usage: "sandbar skill [install [--project]]",
+    flags: {
+      project: {
+        type: "boolean",
+        description: "Install into this folder's .agents/skills (and .claude/skills) instead of your home"
+      }
+    },
+    passthrough: false,
+    remoteExit: false,
+    examples: ["sandbar skill", "sandbar skill install", "sandbar skill install --project"],
+    run: skillCommand
+  },
+  {
+    name: "completion",
+    summary: "Print a shell completion script for zsh, bash or fish",
+    usage: "sandbar completion <zsh|bash|fish>",
+    flags: {},
+    passthrough: false,
+    remoteExit: false,
+    examples: [
+      "source <(sandbar completion zsh)   # in ~/.zshrc",
+      "source <(sandbar completion bash)  # in ~/.bashrc",
+      "sandbar completion fish > ~/.config/fish/completions/sandbar.fish"
+    ],
+    run: completionCommand
+  }
+];
+var exitCodes = [
+  { code: 0, meaning: "success" },
+  { code: 1, meaning: "other failure" },
+  { code: 2, meaning: "usage error; fix the command" },
+  { code: 3, meaning: "not found" },
+  {
+    code: 4,
+    meaning: "unsupported by this provider or profile, adapter or password-manager CLI not installed, or store limit reached"
+  },
+  {
+    code: 5,
+    meaning: "authentication or permission failure, or an unreadable password-manager secret"
+  },
+  { code: 6, meaning: "outcome unknown: an effect may have happened, inspect before retrying" },
+  { code: 7, meaning: "retryable: rate limit, capacity or unavailable before any effect" },
+  { code: 8, meaning: "partial: some steps were confirmed; read error.known" },
+  { code: 125, meaning: "exec/run: the CLI or provider failed; details in the error" },
+  {
+    code: 130,
+    meaning: "interrupted by SIGINT (129 for SIGHUP, 143 for SIGTERM); an interrupted run still destroys its sandbox"
+  }
+];
+function schema() {
+  return {
+    version: 1,
+    cliVersion: package_default.version,
+    globalFlags,
+    commands: commands.map(({ run: _run, ...spec }) => spec),
+    exitCodes,
+    output: {
+      json: "With --json, stdout holds exactly one document: {ok:true,data} or {ok:false,error:{code,message,retryable,outcome,hint?,known?,details?}}",
+      exec: "exec, sh and run exit with the remote command's exit code; their JSON data is {exitCode,stdout,stderr,truncated}, and run adds sandbox {name,id,kept}"
+    }
+  };
+}
+function flagLines(flags) {
+  return Object.entries(flags).map(([name, spec]) => {
+    const label = `${spec.short ? `-${spec.short}, ` : ""}--${name}${spec.value ? ` <${spec.value}>` : ""}`;
+    return `  ${label.padEnd(26)} ${spec.description}`;
+  });
+}
+function topHelp() {
+  return [
+    "sandbar: create and manage sandboxes on any Sandbar provider",
+    "",
+    "Usage: sandbar <command> [flags]",
+    "",
+    "Commands:",
+    ...commands.map((command) => `  ${command.name.padEnd(10)} ${command.summary}`),
+    "  schema     Print a machine-readable description of every command",
+    "",
+    "Global flags:",
+    ...flagLines(globalFlags),
+    "",
+    "Quick start:",
+    "  export SANDBAR_PROVIDER=e2b E2B_API_KEY=...",
+    "  sandbar create --name web",
+    "  sandbar exec web -- uname -a",
+    "  sandbar rm web",
+    "  sandbar run -- python3 -c 'print(2 + 2)'   # create, run, destroy",
+    "",
+    "Run `sandbar <command> --help` for details, `sandbar schema` for JSON."
+  ].join(`
+`);
+}
+function commandHelp(command) {
+  return [
+    command.summary,
+    "",
+    `Usage: ${command.usage}`,
+    ...Object.keys(command.flags).length ? ["", "Flags:", ...flagLines(command.flags)] : [],
+    "",
+    "Examples:",
+    ...command.examples.map((example) => `  ${example}`)
+  ].join(`
+`);
+}
+function parseOption(spec) {
+  const option = { type: spec.type };
+  if (spec.multiple)
+    option.multiple = true;
+  if (spec.short)
+    option.short = spec.short;
+  return option;
+}
+function commandIndex(head) {
+  for (let index = 0;index < head.length; index++) {
+    const arg = head[index];
+    if (!arg.startsWith("-"))
+      return index;
+    const spec = Object.entries(globalFlags).find(([flag]) => flag === arg.slice(2))?.[1];
+    if (spec?.type === "string" && !arg.includes("="))
+      index++;
+  }
+  return -1;
+}
+async function completeWords(words, io) {
+  const flagValue = (name) => {
+    const index = words.indexOf(`--${name}`);
+    return index === -1 ? undefined : words[index + 1];
+  };
+  const session = new Session({
+    env: io.env,
+    cwd: io.cwd,
+    out: new Output(false, io.streams),
+    signal: io.signal,
+    readStdin: io.readStdin,
+    flags: { json: false, config: flagValue("config"), stateDir: flagValue("state-dir") }
+  });
+  try {
+    io.streams.stdout(formatCompletion(await complete(words, commands, globalFlags, session)));
+  } catch {
+    io.streams.stdout(`:0
+`);
+  }
+  return 0;
+}
+async function main(argv, io) {
+  if (argv[0] === "__complete")
+    return completeWords(argv.slice(argv[1] === "--" ? 2 : 1), io);
+  const separator = argv.indexOf("--");
+  const head = separator === -1 ? argv : argv.slice(0, separator);
+  const rest = separator === -1 ? null : argv.slice(separator + 1);
+  const nameIndex = commandIndex(head);
+  const name = nameIndex === -1 ? undefined : head[nameIndex];
+  const jsonFromEnv = io.env.SANDBAR_JSON === "1" || io.env.SANDBAR_JSON === "true";
+  const out = new Output(jsonFromEnv || head.includes("--json"), io.streams);
+  const command = commands.find((candidate) => candidate.name === name);
+  try {
+    if (!name && (head.includes("--version") || head.includes("-V"))) {
+      out.success({ version: package_default.version }, package_default.version);
+      return 0;
+    }
+    if (!name) {
+      out.streams.stdout(`${topHelp()}
+`);
+      return head.includes("--help") || head.includes("-h") ? 0 : 2;
+    }
+    if (name === "schema") {
+      out.streams.stdout(`${JSON.stringify(schema(), null, 2)}
+`);
+      return 0;
+    }
+    if (name === "help") {
+      const topic = commands.find((candidate) => candidate.name === head[1]);
+      out.streams.stdout(`${topic ? commandHelp(topic) : topHelp()}
+`);
+      return 0;
+    }
+    if (!command) {
+      const close = commands.find((candidate) => candidate.name.startsWith(name.slice(0, 2)));
+      throw usage(`Unknown command ${name}`, close ? `did you mean \`sandbar ${close.name}\`?` : "run `sandbar --help`");
+    }
+    if (rest && !command.passthrough)
+      throw usage(`${command.name} does not take a command after --`);
+    const options = { ...globalFlags, ...command.flags };
+    let parsed;
+    try {
+      parsed = parseArgs({
+        args: head.filter((_, index) => index !== nameIndex),
+        options: Object.fromEntries(Object.entries(options).map(([flag, spec]) => [flag, parseOption(spec)])),
+        allowPositionals: true,
+        strict: true
+      });
+    } catch (cause) {
+      const known = Object.keys(options).map((flag) => `--${flag}`);
+      throw usage(cause instanceof Error ? cause.message.split(`
+`)[0] : String(cause), `${command.name} accepts: ${known.join(" ")}`);
+    }
+    const flags = new Flags(parsed.values, parsed.positionals, rest);
+    if (flags.bool("help")) {
+      out.streams.stdout(`${commandHelp(command)}
+`);
+      return 0;
+    }
+    const context = {
+      env: io.env,
+      cwd: io.cwd,
+      out,
+      signal: io.signal,
+      readStdin: io.readStdin,
+      flags: {
+        json: out.json,
+        profile: flags.string("profile"),
+        provider: flags.string("provider"),
+        config: flags.string("config"),
+        stateDir: flags.string("state-dir")
+      }
+    };
+    const session = new Session(context);
+    try {
+      return await command.run(session, flags);
+    } finally {
+      await session.close();
+    }
+  } catch (cause) {
+    const report = describeError(cause);
+    out.failure(report);
+    return command?.remoteExit ? commandExitCode() : managementExitCode(report);
+  }
+}
+
+// src/main.ts
+var controller = new AbortController;
+var interrupted = false;
+var signalExitCodes = { SIGINT: 130, SIGHUP: 129, SIGTERM: 143 };
+var exitCode = 130;
+for (const [name, code] of Object.entries(signalExitCodes))
+  process.on(name, () => {
+    if (interrupted)
+      process.exit(code);
+    interrupted = true;
+    exitCode = code;
+    controller.abort(new Error(`Interrupted by ${name}`));
+  });
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin)
+    chunks.push(new Uint8Array(chunk));
+  return new Uint8Array(Buffer.concat(chunks));
+}
+var code = await main(process.argv.slice(2), {
+  env: process.env,
+  cwd: process.cwd(),
+  signal: controller.signal,
+  readStdin,
+  streams: {
+    stdout: (text) => process.stdout.write(text),
+    stderr: (text) => process.stderr.write(text)
+  }
+});
+process.exitCode = interrupted ? exitCode : code;