@struktoai/mirage-cli 0.0.7-alpha.2 → 0.0.7

package/dist/bin/mirage.js

@@ -1,35 +1,47 @@
 #!/usr/bin/env node
 import {
-  emit,
-  exitCodeFromResponse,
-  fail,
-  formatAge,
-  formatTable,
+  DaemonUnreachable,
+  LoginError,
+  endsAt,
   getConfig,
-  handleResponse,
+  isLocalUrl,
+  jsonBody,
   listConfig,
   loadDaemonSettings,
   makeClient,
+  readLogin,
+  removeLogin,
+  renewBy,
   resolvedConfig,
   setConfig,
-  unsetConfig
-} from "../chunk-BNUV7A4V.js";
+  tokenClaims,
+  unsetConfig,
+  writeLogin
+} from "../chunk-IJUWWUKK.js";
+import {
+  emit,
+  exitCodeFromResponse,
+  fail,
+  formatAge,
+  formatTable,
+  handleResponse
+} from "../chunk-VOPUKMVY.js";
 
 // src/bin/mirage.ts
-import { DaemonConfigError as DaemonConfigError2 } from "@struktoai/mirage-server";
+import { DaemonConfigError as DaemonConfigError2 } from "@struktoai/mirage-server/daemon_config";
 
 // src/main.ts
-import { readFileSync as readFileSync4 } from "fs";
+import { readFileSync as readFileSync3 } from "fs";
 import { dirname as dirname2, join } from "path";
 import { fileURLToPath } from "url";
 import { Command } from "commander";
 
 // src/config.ts
 import { compareCodePoints } from "@struktoai/mirage-core/utils/sort";
-import { ALLOWED_KEYS, DaemonConfigError } from "@struktoai/mirage-server";
-function mask(key, value) {
-  if (key === "auth_token" && value !== "") return "***";
-  return value;
+import { ALLOWED_KEYS, DaemonConfigError } from "@struktoai/mirage-server/daemon_config";
+function mask(key, value2) {
+  if (key === "auth_token" && value2 !== "") return "***";
+  return value2;
 }
 function humanTable(table) {
   return Object.entries(table).map(([k, v]) => `${k} = ${v}`).join("\n");
@@ -46,8 +58,8 @@ function listResolved() {
     return;
   }
   const payload = {};
-  for (const [key, [value, origin]] of Object.entries(resolved)) {
-    payload[key] = { value: mask(key, value), origin };
+  for (const [key, [value2, origin]] of Object.entries(resolved)) {
+    payload[key] = { value: mask(key, value2), origin };
   }
   emit(payload, humanResolved);
 }
@@ -76,27 +88,27 @@ function registerConfigCommands(program) {
     else listFile();
   });
   config.command("get").argument("<key>").description("Print one [daemon] key.").action((key) => {
-    let value;
+    let value2;
     try {
-      value = getConfig(key);
+      value2 = getConfig(key);
     } catch (e) {
       fail(e.message, 2);
       return;
     }
-    if (value === void 0) {
+    if (value2 === void 0) {
       fail(`${key} is not set`, 1);
       return;
     }
-    emit({ [key]: value }, () => value);
+    emit({ [key]: value2 }, () => value2);
   });
-  config.command("set").argument("<key>").argument("<value>").description("Write a [daemon] key (path settings apply on next daemon restart).").action((key, value) => {
+  config.command("set").argument("<key>").argument("<value>").description("Write a [daemon] key (path settings apply on next daemon restart).").action((key, value2) => {
     try {
-      setConfig(key, value);
+      setConfig(key, value2);
     } catch (e) {
       fail(e.message, 2);
       return;
     }
-    emit({ [key]: value, written: true }, () => `${key} = ${value}`);
+    emit({ [key]: value2, written: true }, () => `${key} = ${value2}`);
   });
   config.command("unset").argument("<key>").description("Remove a [daemon] key.").action((key) => {
     try {
@@ -111,12 +123,12 @@ function registerConfigCommands(program) {
 
 // src/daemon.ts
 import { existsSync, readFileSync } from "fs";
-import { pidFilePath } from "@struktoai/mirage-server";
+import { pidFilePath } from "@struktoai/mirage-server/paths";
 function formatStatus(d) {
   if (!d.running) return `Daemon not running. URL: ${d.url}`;
   const parts = [`Running. PID ${d.pid !== null ? String(d.pid) : "?"}`];
-  if (d.uptimeS !== void 0) {
-    parts.push(`uptime ${formatAge(Date.now() / 1e3 - d.uptimeS)}`);
+  if (d.uptime_s !== void 0) {
+    parts.push(`uptime ${formatAge(Date.now() / 1e3 - d.uptime_s)}`);
   }
   if (d.workspaces !== void 0) {
     parts.push(`${String(d.workspaces)} workspace${d.workspaces === 1 ? "" : "s"}`);
@@ -128,7 +140,7 @@ function formatStop(d) {
   return `Stopped (via ${via}${d.pid !== void 0 ? `, PID ${String(d.pid)}` : ""}).`;
 }
 function formatRestart(d) {
-  if (d.spawnedFresh === true) return "Restarted (eager spawn).";
+  if (d.spawned_fresh === true) return "Restarted (eager spawn).";
   return "Restarted; next CLI command will auto-spawn.";
 }
 function formatKill(d) {
@@ -139,8 +151,8 @@ function formatKill(d) {
 function readPid() {
   const p = pidFilePath();
   if (!existsSync(p)) return null;
-  const text = readFileSync(p, "utf-8").trim();
-  const pid = Number(text);
+  const text2 = readFileSync(p, "utf-8").trim();
+  const pid = Number(text2);
   return Number.isFinite(pid) && pid > 0 ? pid : null;
 }
 function processAlive(pid) {
@@ -227,13 +239,13 @@ function registerDaemonCommands(program) {
     }
     if (opts.eager === true) {
       await buildClient().ensureRunning({ allowSpawn: true });
-      emit({ restarted: true, spawnedFresh: true }, formatRestart);
+      emit({ restarted: true, spawned_fresh: true }, formatRestart);
       return;
     }
     emit(
       {
         restarted: true,
-        spawnedFresh: false,
+        spawned_fresh: false,
         note: "next workspace create will auto-spawn"
       },
       formatRestart
@@ -259,30 +271,242 @@ function registerDaemonCommands(program) {
   });
 }
 
-// src/execute.ts
-import { readFileSync as readFileSync2 } from "fs";
-function registerExecuteCommand(program) {
-  program.command("execute").description("Execute a command.").requiredOption("-w, --workspace <id>", "Workspace id").requiredOption("-c, --command <command>", "Shell command to execute").option("-s, --session <id>", "Session id").option("--cwd <path>", "Working directory for this line (a workspace path)").option("--runtime <name>", "Workspace runtime entry to place this line's captured stages on").option("--bg", "Background; return job_id immediately").action(
+// src/vfs.ts
+import { Buffer as Buffer2 } from "buffer";
+import { buffer } from "stream/consumers";
+import {
+  BYTES,
+  FLAG,
+  INTEGER,
+  OWNER,
+  SIZE,
+  VFS_CALLS
+} from "@struktoai/mirage-server/vfs_calls";
+async function post(target, route, body) {
+  const c = makeClient(loadDaemonSettings());
+  await c.ensureRunning({ allowSpawn: false });
+  const query = new URLSearchParams();
+  if (target.session !== void 0) query.set("session_id", target.session);
+  if (target.explain === true) query.set("explain", "true");
+  const suffix = query.size === 0 ? "" : `?${query.toString()}`;
+  const path = `/v1/workspaces/${encodeURIComponent(target.workspace)}/${route}${suffix}`;
+  return c.request("POST", path, { body: JSON.stringify(body) });
+}
+async function answer(r) {
+  if (r.status >= 400) {
+    const text2 = await r.clone().text();
+    let body = {};
+    try {
+      body = JSON.parse(text2);
+    } catch {
+    }
+    if (body.errno !== void 0) {
+      process.stderr.write(`${String(body.detail)} (${body.errno})
+`);
+      if (body.refusal) process.stderr.write(`policy denied: ${body.refusal.reason}
+`);
+      process.exit(1);
+    }
+  }
+  return handleResponse(r);
+}
+function explained(said) {
+  let verdict = String(said.outcome);
+  if (said.reason !== "") verdict += `: ${String(said.reason)}`;
+  let line = `${String(said.call)} ${said.paths.join(" ")}  [${verdict}]`;
+  if (said.error !== "") line += `  ${String(said.error)}`;
+  return line;
+}
+var text = (key) => (result) => Buffer2.from(String(result[key]), "base64").toString("utf-8");
+var HUMAN = {
+  read: text("data_base64"),
+  getxattr: text("value_base64"),
+  readdir: (result) => result.entries.join("\n"),
+  list_files: (result) => result.files.join("\n"),
+  listxattr: (result) => result.names.join("\n"),
+  readlink: (result) => String(result.target)
+};
+var flagName = (name) => name.replace(/_base64$/, "");
+async function value(call, name, given) {
+  if (call.params[name] === BYTES) {
+    const data = typeof given === "string" ? Buffer2.from(given) : await buffer(process.stdin);
+    return data.toString("base64");
+  }
+  if (call.params[name] === OWNER && typeof given === "string" && /^\d+$/.test(given))
+    return Number(given);
+  return given;
+}
+function camel(name) {
+  return name.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
+}
+function command(vfs, call) {
+  const cmd = vfs.command(call.name.replace(/_/g, "-")).description(call.description);
+  const positional = Object.keys(call.params).filter(
+    (name) => call.required.includes(name) && call.params[name] !== BYTES
+  );
+  for (const name of positional) cmd.argument(`<${name}>`);
+  for (const name of Object.keys(call.params)) {
+    if (positional.includes(name)) continue;
+    if (call.params[name] === BYTES) {
+      const flag = flagName(name);
+      cmd.option(`--${flag} <text>`, `The ${flag} as text; stdin when absent`);
+    } else if (call.params[name] === FLAG) {
+      cmd.option(`--${name}`);
+    } else if (call.params[name] === INTEGER || call.params[name] === SIZE) {
+      cmd.option(`--${name} <n>`, `The ${name}`, Number);
+    } else {
+      cmd.option(`--${name} <value>`);
+    }
+  }
+  cmd.requiredOption("-w, --workspace <id>", "Workspace id").option("-s, --session <id>", "Session id").option("--explain", "Say what the call would do; run nothing").action(async (...given) => {
+    const opts = given[positional.length];
+    const body = {};
+    for (const [i, name] of positional.entries()) {
+      body[name] = call.params[name] === INTEGER ? Number(given[i]) : given[i];
+    }
+    for (const name of Object.keys(call.params)) {
+      if (positional.includes(name)) continue;
+      const raw = opts[camel(call.params[name] === BYTES ? flagName(name) : name)];
+      if (call.params[name] === BYTES || raw !== void 0)
+        body[name] = await value(call, name, raw);
+    }
+    const result = await answer(await post(opts, `vfs/${call.name}`, body));
+    emit(result, opts.explain === true ? explained : HUMAN[call.name]);
+  });
+}
+function registerVfsCommands(program) {
+  const vfs = program.command("vfs").description("The session's VFS calls, one command per call, as POSIX names them.");
+  for (const call of VFS_CALLS) command(vfs, call);
+  program.command("glob").description("Every path a pattern matches, as the session sees them.").argument("<pattern>", "Pathname pattern such as /**/*.py").requiredOption("-w, --workspace <id>", "Workspace id").option("-s, --session <id>", "Session id").action(async (pattern, opts) => {
+    const result = await answer(await post(opts, "glob", { pattern }));
+    emit(result, (r) => r.paths.join("\n"));
+  });
+}
+
+// src/shell.ts
+function formatExplanation(data) {
+  let verdict = `${data.outcome}, exit ${String(data.exit_code)}`;
+  if (data.reason !== "") verdict += `: ${data.reason}`;
+  const out = [`${data.line}  [${verdict}]`];
+  for (const child of data.node.children) explainedLines(child, 1, out);
+  return out.join("\n");
+}
+function explainedLines(node, depth, out) {
+  const pad = "  ".repeat(depth);
+  if (node.outcome === void 0) {
+    out.push(`${pad}${node.type}: ${node.text}`);
+  } else {
+    let line = `${pad}${node.text}  [${node.outcome}`;
+    if (node.exit_code !== void 0 && node.exit_code !== 0)
+      line += `, exit ${String(node.exit_code)}`;
+    line += node.reason !== void 0 && node.reason !== "" ? `: ${node.reason}]` : "]";
+    if (node.source !== void 0 && node.source !== "") line += `  ${node.source}`;
+    if (node.runtime !== void 0 && node.runtime !== "") line += `  on ${node.runtime}`;
+    out.push(line);
+  }
+  for (const child of node.children) explainedLines(child, depth + 1, out);
+}
+function registerShellCommand(program) {
+  program.command("shell").description("Run a shell line in a workspace.").requiredOption("-w, --workspace <id>", "Workspace id").requiredOption("-c, --command <command>", "Shell line to run").option("-s, --session <id>", "Session id").option("--cwd <path>", "Working directory for this line (a workspace path)").option("--runtime <name>", "Workspace runtime entry to place this line's captured stages on").option("--bg", "Background; return job_id immediately").option("--json", "Collect output and print the final result as JSON").option("--explain", "Say what the line would do, as a tree; run nothing").action(
     async (opts) => {
-      const body = { command: opts.command, provision: false };
-      if (opts.session !== void 0) body.sessionId = opts.session;
+      const body = { command: opts.command };
       if (opts.cwd !== void 0) body.cwd = opts.cwd;
       if (opts.runtime !== void 0) body.runtime = opts.runtime;
-      if (opts.bg !== true && !process.stdin.isTTY) {
-        body.stdinBase64 = readFileSync2(0).toString("base64");
+      if (opts.explain === true) {
+        const said = await answer(await post(opts, "shell", body));
+        emit(said, opts.json === true ? void 0 : formatExplanation);
+        return;
       }
-      const path = `/v1/workspaces/${opts.workspace}/execute` + (opts.bg === true ? "?background=true" : "");
+      const session = opts.session === void 0 ? "" : `session_id=${encodeURIComponent(opts.session)}`;
+      const path = `/v1/workspaces/${encodeURIComponent(opts.workspace)}/shell`;
       const c = makeClient(loadDaemonSettings());
       await c.ensureRunning({ allowSpawn: false });
-      const response = await handleResponse(
-        await c.request("POST", path, { body: JSON.stringify(body) })
-      );
-      emit(response);
-      process.exit(exitCodeFromResponse(response));
+      const foreground = session === "" ? path : `${path}?${session}`;
+      const background = session === "" ? `${path}?background=true` : `${path}?${session}&background=true`;
+      const piped = !process.stdin.isTTY;
+      if (opts.bg !== true) {
+        const { streamShell } = await import("../stream-LJTY7SCX.js");
+        try {
+          process.exitCode = await streamShell(
+            c,
+            `${foreground}${session === "" ? "?" : "&"}stream=true`,
+            body,
+            piped,
+            opts.json === true
+          );
+        } catch (error) {
+          fail(error instanceof Error ? error.message : String(error), 2);
+        }
+        return;
+      }
+      const response = piped ? await c.requestUpload("POST", background, body, { name: "stdin", data: process.stdin }) : await c.request("POST", background, { body: JSON.stringify(body) });
+      emit(await handleResponse(response));
     }
   );
 }
 
+// src/tools.ts
+import { buffer as buffer2 } from "stream/consumers";
+async function callTool(target, name, args) {
+  const c = makeClient(loadDaemonSettings());
+  await c.ensureRunning({ allowSpawn: false });
+  const query = target.session === void 0 ? "" : `?session_id=${encodeURIComponent(target.session)}`;
+  const path = `/v1/workspaces/${encodeURIComponent(target.workspace)}/tools/${name}${query}`;
+  const response = await handleResponse(
+    await c.request("POST", path, { body: JSON.stringify(args) })
+  );
+  emit(response, (r) => r.text);
+  if (response.is_error) process.exitCode = 1;
+}
+function toolCommand(program, name, description) {
+  return program.command(name).description(description).requiredOption("-w, --workspace <id>", "Workspace id").option("-s, --session <id>", "Session id");
+}
+function registerToolCommands(parent) {
+  const program = parent.command("tools").description("The session's agent tools, as MCP serves them.");
+  toolCommand(program, "shell", "Run a command line and read its output as the agent does.").argument("<command>", "The command line to run").action(async (command2, opts) => {
+    await callTool(opts, "shell", { command: command2 });
+  });
+  toolCommand(program, "read", "Read a file with line numbers.").argument("<path>", "File to read").option("--offset <n>", "Line to start at (0-based)", Number).option("--limit <n>", "Most lines to return", Number).action(async (path, opts) => {
+    const args = { path };
+    if (opts.offset !== void 0) args.offset = opts.offset;
+    if (opts.limit !== void 0) args.limit = opts.limit;
+    await callTool(opts, "read", args);
+  });
+  toolCommand(program, "write", "Write a file; an existing one must be read in full first.").argument("<path>", "File to write").option("--content <text>", "Text to write; stdin when absent").action(async (path, opts) => {
+    const content = opts.content ?? (await buffer2(process.stdin)).toString("utf-8");
+    await callTool(opts, "write", { path, content });
+  });
+  toolCommand(program, "edit", "Replace a string in an existing file.").argument("<path>", "File to edit").argument("<old>", "The exact text to replace").argument("<new>", "The text to put in its place").option("--replace-all", "Replace every occurrence").action(
+    async (path, oldString, newString, opts) => {
+      await callTool(opts, "edit", {
+        path,
+        old_string: oldString,
+        new_string: newString,
+        replace_all: opts.replaceAll === true
+      });
+    }
+  );
+  toolCommand(program, "ls", "List a directory.").argument("<path>", "Directory to list").action(async (path, opts) => {
+    await callTool(opts, "ls", { path });
+  });
+  toolCommand(program, "grep", "Search files recursively, as grep -rn does.").argument("<pattern>", "Regular expression to search for").argument("<path>", "File or directory to search under").option("-i, --ignore-case", "Match case-insensitively").option("-F, --fixed-strings", "Read the pattern as a literal string").option("--include <glob>", "Search only files whose name matches the glob").option("-C, --context <n>", "Lines of context around each match", Number).option("-l, --files-with-matches", "Print only the names of matching files").option("-c, --count", "Print only a count of matching lines per file").option("-m, --max-count <n>", "Stop each file after this many matches", Number).action(
+    async (pattern, path, opts) => {
+      const args = { pattern, path };
+      if (opts.ignoreCase === true) args.ignore_case = true;
+      if (opts.fixedStrings === true) args.fixed_strings = true;
+      if (opts.include !== void 0) args.include = opts.include;
+      if (opts.context !== void 0) args.context = opts.context;
+      if (opts.filesWithMatches === true) args.files_with_matches = true;
+      if (opts.count === true) args.count = true;
+      if (opts.maxCount !== void 0) args.max_count = opts.maxCount;
+      await callTool(opts, "grep", args);
+    }
+  );
+  toolCommand(program, "glob", "Find files whose path matches a pattern.").argument("<pattern>", "Pathname pattern such as **/*.py").argument("[path]", "Directory a relative pattern is matched under", "/").action(async (pattern, path, opts) => {
+    await callTool(opts, "glob", { pattern, path });
+  });
+}
+
 // src/job.ts
 function buildClient2() {
   return makeClient(loadDaemonSettings());
@@ -292,77 +516,437 @@ function registerJobCommands(program) {
   job.command("list").option("-w, --workspace <id>").action(async (opts) => {
     const c = buildClient2();
     await c.ensureRunning({ allowSpawn: false });
-    const path = "/v1/jobs" + (opts.workspace !== void 0 ? `?workspaceId=${opts.workspace}` : "");
+    const path = "/v1/jobs" + (opts.workspace !== void 0 ? `?workspace_id=${encodeURIComponent(opts.workspace)}` : "");
     emit(await handleResponse(await c.request("GET", path)));
   });
   job.command("get").argument("<id>").action(async (id) => {
     const c = buildClient2();
     await c.ensureRunning({ allowSpawn: false });
-    const response = await handleResponse(await c.request("GET", `/v1/jobs/${id}`));
+    const response = await handleResponse(
+      await c.request("GET", `/v1/jobs/${encodeURIComponent(id)}`)
+    );
     emit(response);
-    process.exit(exitCodeFromResponse(response));
+    process.exitCode = exitCodeFromResponse(response);
   });
   job.command("wait").argument("<id>").option("--timeout <s>").action(async (id, opts) => {
     const c = buildClient2();
     await c.ensureRunning({ allowSpawn: false });
     const body = {};
-    if (opts.timeout !== void 0) body.timeoutS = Number(opts.timeout);
+    if (opts.timeout !== void 0) body.timeout_s = Number(opts.timeout);
     const response = await handleResponse(
-      await c.request("POST", `/v1/jobs/${id}/wait`, { body: JSON.stringify(body) })
+      await c.request("POST", `/v1/jobs/${encodeURIComponent(id)}/wait`, {
+        body: JSON.stringify(body)
+      })
     );
     emit(response);
-    process.exit(exitCodeFromResponse(response));
+    process.exitCode = exitCodeFromResponse(response);
   });
   job.command("cancel").argument("<id>").action(async (id) => {
     const c = buildClient2();
     await c.ensureRunning({ allowSpawn: false });
-    emit(await handleResponse(await c.request("DELETE", `/v1/jobs/${id}`)));
+    emit(await handleResponse(await c.request("DELETE", `/v1/jobs/${encodeURIComponent(id)}`)));
   });
 }
 
-// src/mcp.ts
-import { serveMirageMcp } from "@struktoai/mirage-agents/mcp";
-import { buildWorkspaceFromConfig, resolveWorkspaceConfig } from "@struktoai/mirage-server";
-function resolveMcpConfig(config, options = {}) {
-  return resolveWorkspaceConfig(config, {
-    ...options.cwd !== void 0 ? { cwd: options.cwd } : {},
-    ...options.env !== void 0 ? { env: options.env } : {},
-    envNames: ["MIRAGE_MCP_CONFIG", "MIRAGE_CONFIG"]
+// src/login.ts
+import { spawn } from "child_process";
+import { createHash, randomBytes } from "crypto";
+import { createServer } from "http";
+import { rstripSlash } from "@struktoai/mirage-core/utils/slash";
+import {
+  AUTHORIZATION_SERVER_PATH,
+  PROTECTED_RESOURCE_PATH
+} from "@struktoai/mirage-server/auth/config";
+var CALLBACK_PATH = "/callback";
+var CALLBACK_TIMEOUT_SECONDS = 300;
+var SCOPE = "profile email offline_access";
+function noLogin(url) {
+  return `${url} publishes no login: a local daemon needs none, and a server with a shared token takes \`mirage login --token\``;
+}
+function metadataUrl(issuer) {
+  const parts = new URL(issuer);
+  return `${parts.protocol}//${parts.host}${AUTHORIZATION_SERVER_PATH}${rstripSlash(parts.pathname)}`;
+}
+async function getJson(url) {
+  let reply;
+  try {
+    reply = await fetch(url, { signal: AbortSignal.timeout(3e4) });
+  } catch (error) {
+    throw new LoginError(`could not reach ${url}: ${String(error)}`);
+  }
+  if (reply.status !== 200) throw new LoginError(`${url} answered ${String(reply.status)}`);
+  return jsonBody(reply);
+}
+function challenge(verifier) {
+  return createHash("sha256").update(verifier).digest("base64url");
+}
+function openBrowser(url) {
+  const custom = process.env.BROWSER ?? "";
+  const [command2, args] = custom !== "" ? [custom, [url]] : process.platform === "darwin" ? ["open", [url]] : process.platform === "win32" ? ["rundll32", ["url.dll,FileProtocolHandler", url]] : ["xdg-open", [url]];
+  const child = spawn(command2, args, { stdio: "ignore", detached: true });
+  child.on("error", (error) => {
+    console.error(`could not open the browser: ${error.message}`);
   });
+  child.unref();
 }
-async function buildMcpWorkspace(configPath) {
-  return buildWorkspaceFromConfig(configPath);
+async function listen(state) {
+  let settle = () => void 0;
+  const answer2 = new Promise((resolve2) => {
+    settle = resolve2;
+  });
+  const server = createServer((req, res) => {
+    const parts = new URL(req.url ?? "/", "http://127.0.0.1");
+    const query = Object.fromEntries(parts.searchParams);
+    if (parts.pathname !== CALLBACK_PATH || query.state !== state) {
+      res.writeHead(404).end();
+      return;
+    }
+    const text2 = query.code !== void 0 ? "Logged in to Mirage. You can close this tab." : `Login failed: ${query.error ?? "no code"}.`;
+    const escaped = text2.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+    res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+    res.end(`<!doctype html><p>${escaped}</p>`);
+    settle(query);
+  });
+  await new Promise((resolve2) => server.listen(0, "127.0.0.1", resolve2));
+  const { port } = server.address();
+  return {
+    redirect: `http://127.0.0.1:${String(port)}${CALLBACK_PATH}`,
+    answer: answer2,
+    close: () => {
+      server.closeAllConnections();
+      server.close();
+    }
+  };
 }
-async function runMcpServer(config, options) {
-  const configPath = resolveMcpConfig(config);
-  const workspace = await buildMcpWorkspace(configPath);
+async function browserLogin(url) {
+  let found;
   try {
-    await serveMirageMcp(workspace, {
-      staleWriteProtection: options.staleWriteProtection
+    found = await fetch(url + PROTECTED_RESOURCE_PATH, { signal: AbortSignal.timeout(3e4) });
+  } catch (error) {
+    if (isLocalUrl(url)) return null;
+    throw new LoginError(`could not reach ${url}: ${String(error)}`);
+  }
+  if (found.status === 404) return null;
+  const resource = await jsonBody(found);
+  const servers = resource.authorization_servers;
+  const clientId = resource.client_id;
+  if (!Array.isArray(servers) || servers.length === 0 || typeof clientId !== "string") {
+    throw new LoginError(`${url} published no issuer to log in through`);
+  }
+  const issuer = String(servers[0]);
+  const meta = await getJson(metadataUrl(issuer));
+  if (meta.issuer !== issuer) {
+    throw new LoginError(`${issuer} published another issuer's endpoints`);
+  }
+  const verifier = randomBytes(48).toString("base64url");
+  const state = randomBytes(16).toString("base64url");
+  const callback = await listen(state);
+  let answer2;
+  try {
+    const authorize = new URL(String(meta.authorization_endpoint));
+    const params = {
+      response_type: "code",
+      client_id: clientId,
+      redirect_uri: callback.redirect,
+      scope: SCOPE,
+      state,
+      code_challenge: challenge(verifier),
+      code_challenge_method: "S256"
+    };
+    for (const [key, value2] of Object.entries(params)) authorize.searchParams.set(key, value2);
+    process.stderr.write(
+      `Log in to ${url} in your browser. If it does not open, go to:
+
+  ${authorize.href}
+
+`
+    );
+    openBrowser(authorize.href);
+    let timer;
+    const late = new Promise((_, reject) => {
+      timer = setTimeout(() => {
+        reject(new LoginError("the browser did not come back in time"));
+      }, CALLBACK_TIMEOUT_SECONDS * 1e3);
+    });
+    try {
+      answer2 = await Promise.race([callback.answer, late]);
+    } finally {
+      clearTimeout(timer);
+    }
+  } finally {
+    callback.close();
+  }
+  const code = answer2.code;
+  if (code === void 0) {
+    throw new LoginError(`the issuer refused the login: ${answer2.error ?? "no code"}`);
+  }
+  const tokenEndpoint = String(meta.token_endpoint);
+  const signedIn = Date.now() / 1e3;
+  let reply;
+  try {
+    reply = await fetch(tokenEndpoint, {
+      method: "POST",
+      body: new URLSearchParams({
+        grant_type: "authorization_code",
+        code,
+        redirect_uri: callback.redirect,
+        client_id: clientId,
+        code_verifier: verifier
+      }),
+      signal: AbortSignal.timeout(3e4)
     });
   } catch (error) {
-    await workspace.close();
-    throw error;
+    throw new LoginError(`could not reach the issuer: ${String(error)}`);
+  }
+  const body = await jsonBody(reply);
+  if (reply.status !== 200 || typeof body.access_token !== "string") {
+    const reason = typeof body.error === "string" ? body.error : String(reply.status);
+    throw new LoginError(`the issuer refused the code: ${reason}`);
   }
+  const refresh = body.refresh_token;
+  return {
+    url,
+    access_token: body.access_token,
+    logged_in_at: signedIn,
+    refresh_token: typeof refresh === "string" && refresh !== "" ? refresh : null,
+    expires_at: endsAt(body, signedIn),
+    client_id: clientId,
+    token_endpoint: tokenEndpoint
+  };
 }
-function registerMcpCommand(program) {
-  program.command("mcp").argument("[config]", "Mirage workspace YAML config").option("--no-stale-write-protection", "allow edits after a file changed since it was read").description("Serve a Mirage workspace as MCP tools over stdio.").action(runMcpServer);
+async function tokenLogin(url, token) {
+  let reply;
+  try {
+    reply = await fetch(`${url}/v1/workspaces`, {
+      headers: { Authorization: `Bearer ${token}` },
+      signal: AbortSignal.timeout(3e4)
+    });
+  } catch (error) {
+    throw new LoginError(`could not reach ${url}: ${String(error)}`);
+  }
+  if (reply.status === 401) throw new LoginError(`${url} refused the token`);
+  if (!reply.ok) throw new LoginError(`${url} answered ${String(reply.status)}`);
+  const exp = tokenClaims(token).exp;
+  return {
+    url,
+    access_token: token,
+    logged_in_at: Date.now() / 1e3,
+    refresh_token: null,
+    expires_at: typeof exp === "number" ? exp : null,
+    client_id: null,
+    token_endpoint: null
+  };
 }
-
-// src/provision.ts
-function registerProvisionCommand(program) {
-  program.command("provision").description("Estimate cost / preview a command without running it.").requiredOption("-w, --workspace <id>", "Workspace id").requiredOption("-c, --command <command>", "Shell command to estimate").option("-s, --session <id>", "Session id").action(async (opts) => {
-    const body = { command: opts.command, provision: true };
-    if (opts.session !== void 0) body.sessionId = opts.session;
-    const c = makeClient(loadDaemonSettings());
-    await c.ensureRunning({ allowSpawn: false });
+function registerLoginCommands(program) {
+  program.command("login").description("Log in to the server the CLI points at.").option(
+    "--token <token>",
+    "Keep this token instead of using the browser; - reads it from stdin"
+  ).action(async (opts) => {
+    let token = opts.token;
+    if (token === "-") {
+      const chunks = [];
+      for await (const chunk of process.stdin) chunks.push(chunk);
+      token = Buffer.concat(chunks).toString("utf-8").trim();
+      if (token === "") fail("no token on stdin");
+    }
+    const url = rstripSlash(loadDaemonSettings().url);
+    const login = token !== void 0 && token !== "" ? await tokenLogin(url, token) : await browserLogin(url);
+    if (login === null) {
+      process.stdout.write(noLogin(url) + "\n");
+      return;
+    }
+    writeLogin(login);
+    const account = tokenClaims(login.access_token).sub;
+    const who = typeof account === "string" ? ` as ${account}.` : ".";
+    process.stdout.write(`Logged in to ${url}${who}
+`);
+  });
+  program.command("logout").description("Forget the stored login.").action(() => {
+    const login = removeLogin();
+    process.stdout.write(login !== null ? `Logged out of ${login.url}.
+` : "Not logged in.\n");
+  });
+  program.command("whoami").description("Print who the login is for, and when to log in again.").action(() => {
+    const url = rstripSlash(loadDaemonSettings().url);
+    const login = readLogin();
+    if (login?.url !== url) fail(`not logged in to ${url}`);
+    const account = tokenClaims(login.access_token).sub;
     emit(
-      await handleResponse(
-        await c.request("POST", `/v1/workspaces/${opts.workspace}/execute`, {
-          body: JSON.stringify(body)
-        })
-      )
+      {
+        account: typeof account === "string" ? account : null,
+        url,
+        renew_by: new Date(renewBy(login) * 1e3).toISOString().slice(0, 10)
+      },
+      (row) => Object.entries(row).map(([k, v]) => `${k}: ${String(v)}`).join("\n")
+    );
+  });
+}
+
+// src/mcp.ts
+import { resolveWorkspaceConfig } from "@struktoai/mirage-server/workspace_config";
+var MCP_ENV_NAMES = ["MIRAGE_MCP_CONFIG", "MIRAGE_CONFIG"];
+async function hasSession(client, workspacePath, sessionId) {
+  const r = await client.request("GET", `${workspacePath}/sessions`);
+  if (r.status >= 400) {
+    const { detail } = await r.json();
+    throw new Error(`daemon error ${String(r.status)}: ${String(detail)}`);
+  }
+  const rows = await r.json();
+  return Array.isArray(rows) && rows.some((row) => row.session_id === sessionId);
+}
+async function runMcp(config, options) {
+  if (options.workspace !== void 0 && config !== void 0) {
+    fail("pass a config or --workspace, not both", 2);
+  }
+  let path;
+  if (options.workspace === void 0) {
+    try {
+      path = resolveWorkspaceConfig(config, { envNames: MCP_ENV_NAMES });
+    } catch (error) {
+      fail(error instanceof Error ? error.message : String(error), 2);
+    }
+  }
+  const { relayStdio } = await import("@struktoai/mirage-server/mcp");
+  await relayWorkspace(
+    path,
+    options.workspace,
+    options.session,
+    "mcp",
+    relayStdio,
+    options.allCalls === true
+  );
+}
+async function deleteWorkspace(client, workspaceId) {
+  const path = `/v1/workspaces/${encodeURIComponent(workspaceId)}`;
+  const { url, idleGraceSeconds } = client.settings;
+  const attempt = (bearer) => makeClient({ url, idleGraceSeconds, authToken: bearer }).request("DELETE", path);
+  let done = await attempt(client.held);
+  if (done.status === 401 && client.settings.login !== void 0) {
+    let fresh;
+    try {
+      fresh = await client.token();
+    } catch (error) {
+      if (!(error instanceof LoginError)) throw error;
+      process.stderr.write(`could not delete workspace ${workspaceId}: ${error.message}
+`);
+      return;
+    }
+    done = await attempt(fresh);
+  }
+  if (!done.ok) {
+    process.stderr.write(
+      `could not delete workspace ${workspaceId}: daemon error ${String(done.status)}
+`
+    );
+  }
+}
+async function relayWorkspace(path, workspace, session, endpoint, relay, allCalls = false) {
+  const client = makeClient(loadDaemonSettings());
+  try {
+    await client.ensureRunning({ allowSpawn: true });
+  } catch (error) {
+    fail(error instanceof Error ? error.message : String(error));
+  }
+  let workspaceId;
+  let minted = false;
+  if (path !== void 0) {
+    const { checkWorkspaceConfigFile } = await import("@struktoai/mirage-node/config");
+    const loaded = checkWorkspaceConfigFile(path);
+    const body = JSON.stringify({ config: loaded });
+    const created = await handleResponse(await client.request("POST", "/v1/workspaces", { body }));
+    workspaceId = created.id;
+    minted = typeof loaded.workspace_id !== "string" || loaded.workspace_id === "";
+  } else {
+    workspaceId = workspace ?? "";
+    await handleResponse(
+      await client.request("GET", `/v1/workspaces/${encodeURIComponent(workspaceId)}`)
     );
+  }
+  const workspacePath = `/v1/workspaces/${encodeURIComponent(workspaceId)}`;
+  const query = new URLSearchParams();
+  if (session !== void 0) query.set("session_id", session);
+  if (allCalls) query.set("calls", "all");
+  const suffix = query.size === 0 ? "" : `?${query.toString()}`;
+  const url = `${client.settings.url}${workspacePath}/${endpoint}${suffix}`;
+  let refusal;
+  try {
+    if (session !== void 0) {
+      refusal = await hasSession(client, workspacePath, session).then(
+        (found) => found ? void 0 : `session not found: ${session}`,
+        (error) => error instanceof Error ? error.message : String(error)
+      );
+    }
+    if (refusal === void 0) await relay(url, () => client.token());
+  } finally {
+    if (minted) await deleteWorkspace(client, workspaceId);
+  }
+  if (refusal !== void 0) fail(refusal, 2);
+}
+function registerMcpCommand(program) {
+  program.command("mcp").argument("[config]", "Mirage workspace YAML config").option("-w, --workspace <id>", "Serve this daemon workspace instead of loading a config").option("-s, --session <id>", "Session the tools act as; the workspace's default when absent").option("--all-calls", "Also serve each VFS call as a tool, and explain").description("Serve a Mirage workspace's MCP tools over stdio.").action(runMcp);
+}
+
+// src/rpc.ts
+import { resolveWorkspaceConfig as resolveWorkspaceConfig2 } from "@struktoai/mirage-server/workspace_config";
+var RPC_ENV_NAMES = ["MIRAGE_RPC_CONFIG", "MIRAGE_CONFIG"];
+function registerRpcCommand(program) {
+  program.command("rpc").argument("[config]", "Mirage workspace YAML config").option("-w, --workspace <id>", "Serve this daemon workspace instead of loading a config").option("-s, --session <id>", "Session the methods act as; the workspace's default when absent").description("Serve a workspace session's API over JSON-RPC on stdio.").action(
+    async (config, options) => {
+      if (options.workspace !== void 0 && config !== void 0) {
+        fail("pass a config or --workspace, not both", 2);
+      }
+      let path;
+      if (options.workspace === void 0) {
+        try {
+          path = resolveWorkspaceConfig2(config, { envNames: RPC_ENV_NAMES });
+        } catch (error) {
+          fail(error instanceof Error ? error.message : String(error), 2);
+        }
+      }
+      const { relayStdio } = await import("@struktoai/mirage-server/rpc");
+      await relayWorkspace(path, options.workspace, options.session, "rpc", relayStdio);
+    }
+  );
+}
+
+// src/ssh.ts
+function registerSshProxyCommand(program) {
+  program.command("ssh-proxy").argument("<workspace>", "The workspace to log in to").description("Carry SSH to a workspace over the server's HTTPS port, on stdio.").action(async (workspace) => {
+    const client = makeClient(loadDaemonSettings());
+    try {
+      await client.ensureRunning({ allowSpawn: true });
+    } catch (error) {
+      fail(error instanceof Error ? error.message : String(error));
+    }
+    const base = client.settings.url;
+    const token = await client.token();
+    const url = `ws${base.slice("http".length)}/v1/workspaces/${encodeURIComponent(workspace)}/ssh`;
+    const headers = token === "" ? {} : { Authorization: `Bearer ${token}` };
+    const { TunnelRefused, relaySsh } = await import("@struktoai/mirage-server/ssh/relay");
+    try {
+      await relaySsh(url, headers);
+    } catch (error) {
+      if (error instanceof TunnelRefused) fail(`ssh-proxy: ${error.message}`);
+      throw error;
+    }
+  });
+}
+function registerCodexExecCommand(program) {
+  program.command("codex-exec").argument("<workspace>", "The workspace to serve").option("--listen <address>", "HOST:PORT to accept codex exec-server forward on", "127.0.0.1:0").description("Serve a workspace to `codex exec-server forward` on a local port.").action(async (workspace, opts) => {
+    const at = opts.listen.lastIndexOf(":");
+    const host = opts.listen.slice(0, at);
+    const port = opts.listen.slice(at + 1);
+    if (at <= 0 || !/^\d+$/.test(port)) fail("codex-exec: --listen takes HOST:PORT");
+    const client = makeClient(loadDaemonSettings());
+    try {
+      await client.ensureRunning({ allowSpawn: true });
+    } catch (error) {
+      fail(error instanceof Error ? error.message : String(error));
+    }
+    const base = client.settings.url;
+    const url = `ws${base.slice("http".length)}/v1/workspaces/${encodeURIComponent(workspace)}/codex-exec`;
+    const { relayCodex } = await import("@struktoai/mirage-server/ssh/relay");
+    await relayCodex(host.replace(/^\[|\]$/g, ""), Number(port), url, () => client.token());
   });
 }
 
@@ -389,7 +973,7 @@ function registerSessionCommands(program) {
   sess.command("create").argument("<wsId>").option("--id <sessionId>").option(
     "-m, --mount <prefix>",
     "narrow a mount's mode for this session: '/data:read' (alias '/data:r'), '/scratch:rw', '/bin:rwx', or a bare '/data' to keep the mount's own mode; repeatable. This narrows only: a mount you do not name keeps its own mode, and keeping a session away from one is a hide in its profile",
-    (value, prev) => prev.concat([value]),
+    (value2, prev) => prev.concat([value2]),
     []
   ).option(
     "-p, --profile <name>",
@@ -398,14 +982,14 @@ function registerSessionCommands(program) {
     const c = buildClient3();
     await c.ensureRunning({ allowSpawn: false });
     const body = {};
-    if (opts.id !== void 0) body.sessionId = opts.id;
+    if (opts.id !== void 0) body.session_id = opts.id;
     if (opts.mount !== void 0 && opts.mount.length > 0) {
       body.mounts = parseMountModes(opts.mount);
     }
     if (opts.profile !== void 0) body.profile = opts.profile;
     emit(
       await handleResponse(
-        await c.request("POST", `/v1/workspaces/${wsId}/sessions`, {
+        await c.request("POST", `/v1/workspaces/${encodeURIComponent(wsId)}/sessions`, {
           body: JSON.stringify(body)
         })
       )
@@ -414,44 +998,81 @@ function registerSessionCommands(program) {
   sess.command("list").argument("<wsId>").action(async (wsId) => {
     const c = buildClient3();
     await c.ensureRunning({ allowSpawn: false });
-    emit(await handleResponse(await c.request("GET", `/v1/workspaces/${wsId}/sessions`)));
+    emit(
+      await handleResponse(
+        await c.request("GET", `/v1/workspaces/${encodeURIComponent(wsId)}/sessions`)
+      )
+    );
   });
   sess.command("delete").argument("<wsId>").argument("<sessionId>").action(async (wsId, sessionId) => {
     const c = buildClient3();
     await c.ensureRunning({ allowSpawn: false });
     emit(
       await handleResponse(
-        await c.request("DELETE", `/v1/workspaces/${wsId}/sessions/${sessionId}`)
+        await c.request(
+          "DELETE",
+          `/v1/workspaces/${encodeURIComponent(wsId)}/sessions/${encodeURIComponent(sessionId)}`
+        )
       )
     );
   });
+  sess.command("cancel").description("Cancel the session's running and queued commands.").argument("<wsId>").argument("<sessionId>").action(async (wsId, sessionId) => {
+    const c = buildClient3();
+    await c.ensureRunning({ allowSpawn: false });
+    emit(
+      await handleResponse(
+        await c.request(
+          "POST",
+          `/v1/workspaces/${encodeURIComponent(wsId)}/sessions/${encodeURIComponent(sessionId)}/cancel`
+        )
+      )
+    );
+  });
+  sess.command("kill").description("Kill the session's background jobs; the session stays open.").argument("<wsId>").argument("<sessionId>").action(async (wsId, sessionId) => {
+    const c = buildClient3();
+    await c.ensureRunning({ allowSpawn: false });
+    emit(
+      await handleResponse(
+        await c.request(
+          "POST",
+          `/v1/workspaces/${encodeURIComponent(wsId)}/sessions/${encodeURIComponent(sessionId)}/kill`
+        )
+      )
+    );
+  });
+  sess.command("update").description("Replace the session's profile; its cwd, env and history stay.").argument("<wsId>").argument("<sessionId>").option("-p, --profile <name>", "Replace the live session's profile.").option("--default-profile", "Use the workspace default profile.").action(
+    async (wsId, sessionId, opts) => {
+      if (opts.profile === void 0 === (opts.defaultProfile !== true))
+        fail("choose --profile or --default-profile", 2);
+      const c = buildClient3();
+      await c.ensureRunning({ allowSpawn: false });
+      emit(
+        await handleResponse(
+          await c.request(
+            "PATCH",
+            `/v1/workspaces/${encodeURIComponent(wsId)}/sessions/${encodeURIComponent(sessionId)}`,
+            { body: JSON.stringify({ profile: opts.profile ?? null }) }
+          )
+        )
+      );
+    }
+  );
 }
 
 // src/workspace.ts
-import { existsSync as existsSync2, readFileSync as readFileSync3 } from "fs";
+import { createReadStream, existsSync as existsSync2, readFileSync as readFileSync2, writeFileSync } from "fs";
 import { dirname, resolve } from "path";
-import {
-  absolutizeScripts,
-  checkWorkspaceConfigFile,
-  interpolateEnv
-} from "@struktoai/mirage-server";
-import { parse as yamlParse } from "yaml";
 function buildClient4() {
   return makeClient(loadDaemonSettings());
 }
-function envRecord() {
-  const out = {};
-  for (const [k, v] of Object.entries(process.env)) {
-    if (typeof v === "string") out[k] = v;
-  }
-  return out;
-}
-function loadConfigArgument(path) {
+async function loadConfigArgument(path) {
   if (!existsSync2(path)) fail(`config file not found: ${path}`, 2);
-  const text = readFileSync3(path, "utf-8");
+  const { absolutizeScripts, interpolateEnv, readProcessEnv } = await import("@struktoai/mirage-node/config");
+  const { parse: yamlParse } = await import("yaml");
+  const text2 = readFileSync2(path, "utf-8");
   let config;
   try {
-    config = interpolateEnv(yamlParse(text), envRecord());
+    config = interpolateEnv(yamlParse(text2), readProcessEnv());
   } catch (err) {
     fail(`invalid config YAML/JSON at ${path}: ${String(err)}`, 2);
   }
@@ -465,9 +1086,9 @@ function formatWorkspaceList(items) {
   const rows = items.map((w) => [
     w.id,
     w.mode,
-    String(w.mountCount),
-    String(w.sessionCount),
-    formatAge(w.createdAt)
+    String(w.mount_count),
+    String(w.session_count),
+    formatAge(w.created_at)
   ]);
   return formatTable(["ID", "MODE", "MOUNTS", "SESSIONS", "AGE"], rows);
 }
@@ -475,17 +1096,17 @@ function formatWorkspaceDetail(d) {
   const lines = [
     `ID:        ${d.id}`,
     `Mode:      ${d.mode}`,
-    `Created:   ${formatAge(d.createdAt)} ago`
+    `Created:   ${formatAge(d.created_at)} ago`
   ];
   if (d.mounts !== void 0 && d.mounts.length > 0) {
-    const rows = d.mounts.map((m) => [m.prefix, m.resource, m.mode]);
+    const rows = d.mounts.map((m) => [m.prefix, m.vfs, m.mode]);
     lines.push("", "Mounts:");
-    for (const ln of formatTable(["PREFIX", "RESOURCE", "MODE"], rows).split("\n")) {
+    for (const ln of formatTable(["PREFIX", "VFS", "MODE"], rows).split("\n")) {
       lines.push("  " + ln);
     }
   }
   if (d.sessions !== void 0 && d.sessions.length > 0) {
-    const rows = d.sessions.map((s) => [s.sessionId, s.cwd]);
+    const rows = d.sessions.map((s) => [s.session_id, s.cwd]);
     lines.push("", "Sessions:");
     for (const ln of formatTable(["SESSION", "CWD"], rows).split("\n")) {
       lines.push("  " + ln);
@@ -493,9 +1114,9 @@ function formatWorkspaceDetail(d) {
   }
   if (d.internals != null) {
     lines.push("", "Internals:");
-    for (const k of ["cacheBytes", "cacheEntries", "historyLength", "inFlightJobs"]) {
-      const value = d.internals[k];
-      lines.push(`  ${k.padEnd(16)} ${value === null ? "n/a (not tracked)" : String(value)}`);
+    for (const k of ["cache_bytes", "cache_entries", "history_length", "in_flight_jobs"]) {
+      const value2 = d.internals[k];
+      lines.push(`  ${k.padEnd(16)} ${value2 === null ? "n/a (not tracked)" : String(value2)}`);
     }
   }
   return lines.join("\n");
@@ -506,31 +1127,38 @@ function formatAsks(items) {
     ["ID", "SESSION", "COMMAND", "STATUS", "REASON"],
     items.map((a) => [
       a.id,
-      a.sessionId,
+      a.session_id,
       [a.command, ...a.argv].join(" "),
       a.outcome ?? "pending",
       a.reason
     ])
   );
 }
-function formatVersionLog(items) {
-  if (items.length === 0) return "No versions.";
-  return formatTable(
-    ["VERSION", "MESSAGE"],
-    items.map((v) => [v.id.slice(0, 12), v.message])
-  );
-}
-function formatDiff(changes) {
-  const lines = [];
-  for (const kind of ["added", "modified", "deleted"]) {
-    for (const path of changes[kind]) lines.push(`${kind.padEnd(9)} ${path}`);
-  }
-  return lines.length > 0 ? lines.join("\n") : "No changes.";
-}
 function registerWorkspaceCommands(program) {
   const ws = program.command("workspace").description("Manage workspaces.");
+  for (const kind of ["vfs", "skill"]) {
+    ws.command(`${kind}-md`).argument("<wsId>").description(`Generate ${kind} Markdown, or expose it inside the workspace with --path.`).option("--path <path>", "Expose a live file at this workspace path.").option("--session <id>", "Limit exposure or generation to this session.").option("--profile <name>", "Preview a profile without creating a file.").action(async (wsId, opts) => {
+      if (opts.profile !== void 0 && (opts.path !== void 0 || opts.session !== void 0))
+        fail("--profile requires no --path or --session", 2);
+      const c = buildClient4();
+      await c.ensureRunning({ allowSpawn: false });
+      let route = `/v1/workspaces/${encodeURIComponent(wsId)}`;
+      if (opts.session !== void 0) route += `/sessions/${encodeURIComponent(opts.session)}`;
+      route += `/${kind}-md`;
+      if (opts.profile !== void 0) route += `?profile=${encodeURIComponent(opts.profile)}`;
+      const response = opts.path === void 0 ? await c.request("GET", route) : await c.request("PUT", route, { body: JSON.stringify({ path: opts.path }) });
+      if (!response.ok) await handleResponse(response);
+      if (opts.path === void 0) process.stdout.write(await response.text());
+    });
+  }
   ws.command("create").description("Create a workspace; daemon auto-spawns if not running.").argument("<config>", "YAML/JSON workspace config").option("--id <id>", "Explicit workspace id").action(async (configPath, opts) => {
-    const cfg = checkWorkspaceConfigFile(configPath);
+    const { checkWorkspaceConfigFile } = await import("@struktoai/mirage-node/config");
+    let cfg;
+    try {
+      cfg = checkWorkspaceConfigFile(configPath);
+    } catch (err) {
+      fail(err instanceof Error ? err.message : String(err), 2);
+    }
     const body = { config: cfg };
     if (opts.id !== void 0) body.id = opts.id;
     const c = buildClient4();
@@ -549,7 +1177,7 @@ function registerWorkspaceCommands(program) {
   ws.command("get").description("Show full details for one workspace.").argument("<id>").option("--verbose", "Include cache/dirty/history internals").action(async (id, opts) => {
     const c = buildClient4();
     await c.ensureRunning({ allowSpawn: false });
-    const path = `/v1/workspaces/${id}` + (opts.verbose === true ? "?verbose=true" : "");
+    const path = `/v1/workspaces/${encodeURIComponent(id)}` + (opts.verbose === true ? "?verbose=true" : "");
     emit(
       await handleResponse(await c.request("GET", path)),
       formatWorkspaceDetail
@@ -559,66 +1187,61 @@ function registerWorkspaceCommands(program) {
     const c = buildClient4();
     await c.ensureRunning({ allowSpawn: false });
     emit(
-      await handleResponse(await c.request("DELETE", `/v1/workspaces/${id}`)),
+      await handleResponse(
+        await c.request("DELETE", `/v1/workspaces/${encodeURIComponent(id)}`)
+      ),
       (d) => `Deleted workspace ${d.id}.`
     );
   });
-  ws.command("clone").description("Clone a workspace, optionally from one of its past versions.").argument("<srcId>").option("--id <id>", "Explicit id for the clone").option("--at <ref>", "Clone from a past version (id or branch) not the live state").action(async (srcId, opts) => {
-    const body = { sourceId: srcId };
-    if (opts.id !== void 0) body.id = opts.id;
-    if (opts.at !== void 0) body.at = opts.at;
+  ws.command("close").description("Stop a workspace and keep its state for the same id.").argument("<id>").action(async (id) => {
     const c = buildClient4();
     await c.ensureRunning({ allowSpawn: false });
-    const r = await c.request("POST", "/v1/workspaces/clone", { body: JSON.stringify(body) });
-    emit(await handleResponse(r), formatWorkspaceDetail);
+    emit(
+      await handleResponse(
+        await c.request("POST", `/v1/workspaces/${encodeURIComponent(id)}/close`)
+      ),
+      (d) => `Closed workspace ${d.id}.`
+    );
   });
-  ws.command("commit").description("Commit the workspace's current state as a version.").argument("<id>").option("-m, --message <msg>", "Version message", "").option("-b, --branch <branch>", "Branch to commit on", "main").action(async (id, opts) => {
+  ws.command("cancel").description("Cancel the running and queued commands of every session.").argument("<id>").action(async (id) => {
     const c = buildClient4();
     await c.ensureRunning({ allowSpawn: false });
-    const r = await c.request("POST", `/v1/workspaces/${id}/commit`, {
-      body: JSON.stringify({ message: opts.message, branch: opts.branch })
-    });
     emit(
-      await handleResponse(r),
-      (d) => `Committed ${d.version.slice(0, 12)} on ${d.branch}.`
+      await handleResponse(
+        await c.request("POST", `/v1/workspaces/${encodeURIComponent(id)}/cancel`)
+      )
     );
   });
-  ws.command("branch").description("Create a branch at another branch's current version.").argument("<id>").argument("<name>").option("--from <branch>", "Branch to fork from", "main").action(async (id, name, opts) => {
+  ws.command("kill").description("Kill the background jobs of every session.").argument("<id>").action(async (id) => {
     const c = buildClient4();
     await c.ensureRunning({ allowSpawn: false });
-    const r = await c.request("POST", `/v1/workspaces/${id}/branch`, {
-      body: JSON.stringify({ name, fromBranch: opts.from })
-    });
     emit(
-      await handleResponse(r),
-      (d) => `Created branch ${d.branch} at ${d.version.slice(0, 12)}.`
+      await handleResponse(
+        await c.request("POST", `/v1/workspaces/${encodeURIComponent(id)}/kill`)
+      )
     );
   });
-  ws.command("log").description("List a workspace's versions (newest first).").argument("<id>").option("-b, --branch <branch>", "Branch", "main").action(async (id, opts) => {
+  ws.command("clone").description("Clone a workspace's live state.").argument("<srcId>").option("--id <id>", "Explicit id for the clone").action(async (srcId, opts) => {
+    const body = {};
+    if (opts.id !== void 0) body.id = opts.id;
     const c = buildClient4();
     await c.ensureRunning({ allowSpawn: false });
-    const r = await c.request("GET", `/v1/workspaces/${id}/versions?branch=${opts.branch}`);
-    emit(await handleResponse(r), formatVersionLog);
-  });
-  ws.command("diff").description("Show changed files (git-style): live vs HEAD, live vs <a>, or <a> vs <b>.").argument("<id>").argument("[a]", "Base ref; omit to use live state").argument("[b]", "Compare ref; omit to use live state").option("-b, --branch <branch>", "Branch", "main").action(
-    async (id, a, b, opts) => {
-      const params = new URLSearchParams({ branch: opts.branch });
-      if (a !== void 0) params.set("a", a);
-      if (b !== void 0) params.set("b", b);
-      const c = buildClient4();
-      await c.ensureRunning({ allowSpawn: false });
-      const r = await c.request("GET", `/v1/workspaces/${id}/diff?${params.toString()}`);
-      emit(await handleResponse(r), formatDiff);
-    }
-  );
+    const r = await c.request("POST", `/v1/workspaces/${encodeURIComponent(srcId)}/clone`, {
+      body: JSON.stringify(body)
+    });
+    emit(await handleResponse(r), formatWorkspaceDetail);
+  });
   ws.command("list-asks").description("List pending asks (every decision with --all).").argument("<id>").option("--session <sessionId>", "Only this session's asks").option("--all", "Include settled decisions, not just pending asks").action(async (id, opts) => {
     const params = new URLSearchParams();
-    if (opts.session !== void 0) params.set("sessionId", opts.session);
+    if (opts.session !== void 0) params.set("session_id", opts.session);
     if (opts.all === true) params.set("all", "true");
     const c = buildClient4();
     await c.ensureRunning({ allowSpawn: false });
     const qs = params.toString();
-    const r = await c.request("GET", `/v1/workspaces/${id}/asks${qs === "" ? "" : `?${qs}`}`);
+    const r = await c.request(
+      "GET",
+      `/v1/workspaces/${encodeURIComponent(id)}/asks${qs === "" ? "" : `?${qs}`}`
+    );
     emit(await handleResponse(r), formatAsks);
   });
   ws.command("allow").description("Allow a pending ask; the retry of the asked line passes.").argument("<id>").argument("<askId>", "Ask id, as quoted in the refusal").option(
@@ -628,48 +1251,87 @@ function registerWorkspaceCommands(program) {
   ).option("--note <note>", "What to record alongside the answer", "").action(async (id, askId, opts) => {
     const c = buildClient4();
     await c.ensureRunning({ allowSpawn: false });
-    const r = await c.request("POST", `/v1/workspaces/${id}/asks/${askId}`, {
-      body: JSON.stringify({ answer: "allow", scope: opts.scope, note: opts.note })
-    });
+    const r = await c.request(
+      "POST",
+      `/v1/workspaces/${encodeURIComponent(id)}/asks/${encodeURIComponent(askId)}`,
+      {
+        body: JSON.stringify({ answer: "allow", scope: opts.scope, note: opts.note })
+      }
+    );
     emit(await handleResponse(r), (d) => `Allowed ${d.id} (${d.scope}).`);
   });
   ws.command("deny").description("Deny a pending ask; the retry is refused in the deny voice, once.").argument("<id>").argument("<askId>", "Ask id, as quoted in the refusal").option("--note <note>", "What to record alongside the answer", "").action(async (id, askId, opts) => {
     const c = buildClient4();
     await c.ensureRunning({ allowSpawn: false });
-    const r = await c.request("POST", `/v1/workspaces/${id}/asks/${askId}`, {
-      body: JSON.stringify({ answer: "deny", note: opts.note })
-    });
+    const r = await c.request(
+      "POST",
+      `/v1/workspaces/${encodeURIComponent(id)}/asks/${encodeURIComponent(askId)}`,
+      {
+        body: JSON.stringify({ answer: "deny", note: opts.note })
+      }
+    );
     emit(await handleResponse(r), (d) => `Denied ${d.id}.`);
   });
-  ws.command("checkout").description("Restore a workspace in place to one of its versions.").argument("<id>").argument("<ref>", "Version id or branch to restore").action(async (id, ref) => {
-    const c = buildClient4();
-    await c.ensureRunning({ allowSpawn: false });
-    const r = await c.request("POST", `/v1/workspaces/${id}/checkout`, {
-      body: JSON.stringify({ ref })
-    });
-    emit(await handleResponse(r), formatWorkspaceDetail);
-  });
   ws.command("snapshot").description(
-    "Snapshot a workspace to a tar file. The path is resolved to an absolute path and the daemon writes the tar."
-  ).argument("<id>").argument("<output>", "Path to write the .tar to").action(async (id, output) => {
+    "Snapshot a workspace. The server sends the tar back and it is written to <output> here, whether the server runs on this machine or another; with --key it goes to the server's snapshot store."
+  ).argument("<id>").argument("[output]", "File to write the .tar to, on this machine").option("--key <key>", "Put it in the server's snapshot store instead").action(async (id, output, opts) => {
+    if (output !== void 0 && opts.key !== void 0) {
+      fail("snapshot takes an output file or --key", 2);
+    }
     const c = buildClient4();
     await c.ensureRunning({ allowSpawn: false });
-    const r = await c.request("POST", `/v1/workspaces/${id}/snapshot`, {
-      body: JSON.stringify({ path: resolve(output) })
-    });
-    const d = await handleResponse(r);
-    emit(d, (x) => `Snapshot ${x.id} -> ${x.path} (${x.size.toLocaleString()} bytes).`);
-  });
-  ws.command("load").description("Load a workspace from a tar file.").argument("<tar>", "Path to a .tar produced by `mirage workspace snapshot`").argument("[config]", "Workspace YAML/JSON config").option("--id <id>", "Explicit workspace id").action(async (tarPath, configPath, opts) => {
-    if (!existsSync2(tarPath)) fail(`tar file not found: ${tarPath}`, 2);
-    const body = { path: resolve(tarPath) };
-    if (opts.id !== void 0) body.id = opts.id;
-    if (configPath !== void 0) body.override = loadConfigArgument(configPath);
-    const c = buildClient4();
-    await c.ensureRunning({ allowSpawn: true });
-    const r = await c.request("POST", "/v1/workspaces/load", { body: JSON.stringify(body) });
-    emit(await handleResponse(r), formatWorkspaceDetail);
+    const path = `/v1/workspaces/${encodeURIComponent(id)}/snapshot`;
+    const human = (d, target2) => `Snapshot ${d.id} -> ${target2} (${d.size.toLocaleString()} bytes).`;
+    if (opts.key !== void 0) {
+      const key = opts.key;
+      const r2 = await c.request("POST", path, {
+        body: JSON.stringify({ key }),
+        timeoutMs: null
+      });
+      emit(
+        await handleResponse(r2),
+        (d) => human(d, key)
+      );
+      return;
+    }
+    if (output === void 0) fail("snapshot takes an output file or --key", 2);
+    const target = output;
+    const r = await c.request("GET", path, { timeoutMs: null });
+    if (!r.ok) await handleResponse(r);
+    const tar = new Uint8Array(await r.arrayBuffer());
+    writeFileSync(target, tar);
+    emit({ id, path: target, size: tar.byteLength }, (d) => human(d, target));
   });
+  ws.command("load").description(
+    "Load a workspace from a snapshot. <file> is read here and uploaded, whether the server runs on this machine or another; with --key the tar comes from the server's snapshot store."
+  ).argument("[file]", "The .tar to upload; omit with --key").argument("[config]", "Workspace YAML/JSON config").option("--key <key>", "Load from the server's snapshot store").option("--id <id>", "Explicit workspace id").action(
+    async (first, second, opts) => {
+      const given = [first, second].filter((p) => p !== void 0);
+      if (opts.key !== void 0 && given.length > 1)
+        fail("load takes a FILE or --key, not both", 2);
+      if (opts.key === void 0 && given.length === 0) {
+        fail("load takes a FILE (or --key) and an optional CONFIG", 2);
+      }
+      const tarPath = opts.key === void 0 ? given.shift() : void 0;
+      const configPath = given[0];
+      for (const p of [tarPath, configPath]) {
+        if (p !== void 0 && !existsSync2(p)) fail(`file not found: ${p}`, 2);
+      }
+      const body = {};
+      if (opts.id !== void 0) body.id = opts.id;
+      if (configPath !== void 0) body.override = await loadConfigArgument(configPath);
+      const c = buildClient4();
+      await c.ensureRunning({ allowSpawn: true });
+      const r = tarPath === void 0 ? await c.request("POST", "/v1/workspaces/load", {
+        body: JSON.stringify({ ...body, key: opts.key }),
+        timeoutMs: null
+      }) : await c.requestUpload("POST", "/v1/workspaces/load", body, {
+        name: "snapshot",
+        data: createReadStream(tarPath)
+      });
+      emit(await handleResponse(r), formatWorkspaceDetail);
+    }
+  );
 }
 
 // src/main.ts
@@ -677,7 +1339,7 @@ function resolveVersion() {
   let dir = dirname2(fileURLToPath(import.meta.url));
   for (let i = 0; i < 6; i++) {
     try {
-      const pkg = JSON.parse(readFileSync4(join(dir, "package.json"), "utf8"));
+      const pkg = JSON.parse(readFileSync3(join(dir, "package.json"), "utf8"));
       if (pkg.name === "@struktoai/mirage-cli" && pkg.version) return pkg.version;
     } catch {
     }
@@ -687,13 +1349,18 @@ function resolveVersion() {
 }
 function buildProgram() {
   const program = new Command();
-  program.name("mirage").description("Mirage daemon CLI: manage workspaces and execute commands.").version(resolveVersion());
+  program.name("mirage").description("Mirage daemon CLI: manage workspaces and run shell lines.").version(resolveVersion());
   registerWorkspaceCommands(program);
   registerSessionCommands(program);
   registerJobCommands(program);
-  registerExecuteCommand(program);
+  registerShellCommand(program);
+  registerVfsCommands(program);
+  registerToolCommands(program);
   registerMcpCommand(program);
-  registerProvisionCommand(program);
+  registerRpcCommand(program);
+  registerSshProxyCommand(program);
+  registerCodexExecCommand(program);
+  registerLoginCommands(program);
   registerDaemonCommands(program);
   registerConfigCommands(program);
   return program;
@@ -702,7 +1369,8 @@ function buildProgram() {
 // src/bin/mirage.ts
 var ALIASES = {
   "--workspace_id": "--workspace",
-  "--session_id": "--session"
+  "--session_id": "--session",
+  "--background": "--bg"
 };
 function rewriteArgv(argv) {
   return argv.map((arg) => {
@@ -718,6 +1386,10 @@ buildProgram().parseAsync(rewriteArgv(process.argv)).catch((err) => {
     console.error(err.message);
     process.exit(2);
   }
+  if (err instanceof DaemonUnreachable || err instanceof LoginError) {
+    console.error(err.message);
+    process.exit(1);
+  }
   console.error(err);
   process.exit(1);
 });