@machinen/cli 0.3.3 → 0.4.0

package/dist/cli.js

@@ -13,7 +13,7 @@ import {
   symlinkSync,
   unlinkSync
 } from "fs";
-import { homedir as homedir2, tmpdir } from "os";
+import { arch as osArch, homedir as homedir2, tmpdir } from "os";
 import { dirname as dirname2, join as join2, resolve } from "path";
 import { PassThrough, Transform } from "stream";
 import { pipeline } from "stream/promises";
@@ -33,7 +33,7 @@ import debugLib2 from "debug";
 // package.json
 var package_default = {
   name: "@machinen/cli",
-  version: "0.3.3",
+  version: "0.4.0",
   license: "FSL-1.1-MIT",
   repository: {
     type: "git",
@@ -64,7 +64,8 @@ var package_default = {
   },
   optionalDependencies: {
     "@machinen/native-arm64-darwin": "workspace:*",
-    "@machinen/native-arm64-linux": "workspace:*"
+    "@machinen/native-arm64-linux": "workspace:*",
+    "@machinen/native-x64-linux": "workspace:*"
   }
 };
 
@@ -95,7 +96,7 @@ var COMMANDS = [
         name: "--mount-live",
         type: "string",
         repeatable: true,
-        description: "Live-share host dir. Spec: <host>:<guest>[:rw|ro][:fuse|virtiofs]."
+        description: "Live-share host dir over virtio-fs. Spec: <host>:<guest>[:rw|ro]."
       },
       {
         name: "--env",
@@ -122,6 +123,11 @@ var COMMANDS = [
         description: "Detach the VMM from the CLI on first-guest-byte readiness."
       },
       { name: "--memory", type: "integer", description: "Guest RAM ceiling in MiB (debug knob)." },
+      {
+        name: "--nested",
+        type: "boolean",
+        description: "Expose arm64 EL2 / /dev/kvm to the guest when the host supports it."
+      },
       {
         name: "--json",
         type: "boolean",
@@ -144,7 +150,7 @@ var COMMANDS = [
       {
         name: "--lazy",
         type: "boolean",
-        description: "Opt into lazy-pages restore (#266) \u2014 vsock-FUSE mount the bundle and fault pages on demand. Default is eager."
+        description: "Opt into CRIU lazy-pages restore (#266) \u2014 virtio-fs mount the bundle and fault pages on demand. Default is eager."
       },
       {
         name: "-p",
@@ -237,7 +243,7 @@ var COMMANDS = [
       {
         name: "--lazy",
         type: "boolean",
-        description: "Opt into lazy-pages restore (#266); ignored when --detach is set since the FUSE server can't survive supervisor exit."
+        description: "Opt into CRIU lazy-pages restore (#266); the CLI currently ignores this when --detach is set."
       },
       {
         name: "-p",
@@ -486,120 +492,175 @@ import { ParseError as ParseError2 } from "@machinen/runtime";
 
 // src/parse-run-args.ts
 import { ParseError } from "@machinen/runtime";
+var RUN_VALUE_FLAGS = /* @__PURE__ */ new Map([
+  ["--mount", "mount"],
+  ["--mount-live", "liveMount"],
+  ["--env", "env"],
+  ["-p", "portForward"],
+  ["--publish", "portForward"],
+  ["--snapshot", "snapshot"],
+  ["--cwd", "guestCwd"],
+  ["--name", "name"],
+  ["--memory", "memory"]
+]);
+var RUN_BARE_FLAGS = /* @__PURE__ */ new Map([
+  ["--nested", "nested"],
+  ["--detached", "detach"],
+  ["--detach", "detach"],
+  ["--json", "json"]
+]);
+var RUN_FLAG_HANDLERS = {
+  mount: handleRunMount,
+  liveMount: handleRunLiveMount,
+  env: handleRunEnv,
+  portForward: handleRunPortForward,
+  snapshot: handleRunSnapshot,
+  nested: handleRunNested,
+  nestedValue: handleRunNestedValue,
+  guestCwd: handleRunGuestCwd,
+  name: handleRunName,
+  detach: handleRunDetach,
+  json: handleRunJson,
+  memory: handleRunMemory
+};
 function parseRunArgs(argv) {
-  const idx = argv.indexOf("--");
-  const pre = idx === -1 ? argv : argv.slice(0, idx);
-  const double_dash_args = idx === -1 ? [] : argv.slice(idx + 1);
-  const positional = [];
-  let mount;
-  const liveMounts = [];
-  const env = {};
-  const portForward = [];
-  const seenHostPorts = /* @__PURE__ */ new Set();
-  let snapshot;
-  let name;
-  let guestCwd;
-  let detached = false;
-  let memory;
-  let json = false;
+  const { pre, double_dash_args } = splitCommandArgs(argv);
+  const state = newRunParseState();
   for (let i = 0; i < pre.length; i++) {
-    const a = pre[i];
-    if (a === "--mount" || a.startsWith("--mount=")) {
-      if (mount) {
-        throw new ParseError(
-          "PARSE_FLAG_DUPLICATE",
-          "--mount may be given at most once per invocation"
-        );
-      }
-      const r = consumeMount(a, pre, i);
-      mount = r.value;
-      i = r.next;
-    } else if (a === "--mount-live" || a.startsWith("--mount-live=")) {
-      const r = consumeLiveMount(a, pre, i);
-      liveMounts.push(r.value);
-      i = r.next;
-    } else if (a === "--env" || a.startsWith("--env=")) {
-      const r = consumeEnv(a, pre, i);
-      env[r.key] = r.value;
-      i = r.next;
-    } else if (a === "-p" || a === "--publish" || a.startsWith("-p=") || a.startsWith("--publish=")) {
-      i = consumePortForward(a, pre, i, seenHostPorts, portForward);
-    } else if (a === "--snapshot" || a.startsWith("--snapshot=")) {
-      if (snapshot) {
-        throw new ParseError(
-          "PARSE_FLAG_DUPLICATE",
-          "--snapshot may be given at most once per invocation"
-        );
-      }
-      const { spec, next } = takeValue(a, pre, i, "a path value");
-      snapshot = spec;
-      i = next;
-    } else if (a === "--cwd" || a.startsWith("--cwd=")) {
-      if (guestCwd !== void 0) {
-        throw new ParseError(
-          "PARSE_FLAG_DUPLICATE",
-          "--cwd may be given at most once per invocation"
-        );
-      }
-      const r = consumeGuestCwd(a, pre, i);
-      guestCwd = r.value;
-      i = r.next;
-    } else if (a === "--name" || a.startsWith("--name=")) {
-      if (name) {
-        throw new ParseError(
-          "PARSE_FLAG_DUPLICATE",
-          "--name may be given at most once per invocation"
-        );
-      }
-      const { spec, next } = takeValue(a, pre, i, "a value");
-      name = spec;
-      i = next;
-    } else if (a === "--detached" || a === "--detach") {
-      if (detached) {
-        throw new ParseError(
-          "PARSE_FLAG_DUPLICATE",
-          "--detached may be given at most once per invocation"
-        );
-      }
-      detached = true;
-      if (a === "--detached" && !process.env.MACHINEN_QUIET_DEPRECATIONS && !process.env.VITEST) {
-        process.stderr.write(
-          "machinen: --detached is deprecated; use --detach (same behaviour).\n"
-        );
-      }
-    } else if (a === "--json") {
-      json = true;
-    } else if (a === "--memory" || a.startsWith("--memory=")) {
-      if (memory !== void 0) {
-        throw new ParseError(
-          "PARSE_FLAG_DUPLICATE",
-          "--memory may be given at most once per invocation"
-        );
-      }
-      const r = consumeMemory(a, pre, i);
-      memory = r.value;
-      i = r.next;
-    } else if (a.startsWith("-")) {
-      throw new ParseError("PARSE_FLAG_UNKNOWN", `unknown flag: ${a}`);
-    } else {
-      positional.push(a);
+    const arg = pre[i];
+    const flag = runFlagFor(arg);
+    if (flag) {
+      i = RUN_FLAG_HANDLERS[flag](state, arg, pre, i);
+      continue;
     }
+    if (arg.startsWith("-")) {
+      throw new ParseError("PARSE_FLAG_UNKNOWN", `unknown flag: ${arg}`);
+    }
+    state.positional.push(arg);
+  }
+  return finishRunArgs(state, double_dash_args);
+}
+function splitCommandArgs(argv) {
+  const idx = argv.indexOf("--");
+  if (idx === -1) {
+    return { pre: argv, double_dash_args: [] };
+  }
+  return { pre: argv.slice(0, idx), double_dash_args: argv.slice(idx + 1) };
+}
+function newRunParseState() {
+  return {
+    positional: [],
+    liveMounts: [],
+    env: {},
+    portForward: [],
+    seenHostPorts: /* @__PURE__ */ new Set(),
+    nested: false,
+    detached: false,
+    json: false
+  };
+}
+function runFlagFor(arg) {
+  const eq = arg.indexOf("=");
+  if (eq !== -1) {
+    const head = arg.slice(0, eq);
+    if (head === "--nested") {
+      return "nestedValue";
+    }
+    return RUN_VALUE_FLAGS.get(head);
   }
+  return RUN_BARE_FLAGS.get(arg) ?? RUN_VALUE_FLAGS.get(arg);
+}
+function finishRunArgs(state, double_dash_args) {
   return {
-    positional,
+    positional: state.positional,
     double_dash_args,
-    mount,
-    liveMounts: liveMounts.length > 0 ? liveMounts : void 0,
-    env: Object.keys(env).length > 0 ? env : void 0,
-    portForward: portForward.length > 0 ? portForward : void 0,
-    snapshot,
-    name,
-    guestCwd,
-    detached: detached || void 0,
-    memory,
-    json: json || void 0
+    mount: state.mount,
+    liveMounts: state.liveMounts.length > 0 ? state.liveMounts : void 0,
+    env: Object.keys(state.env).length > 0 ? state.env : void 0,
+    portForward: state.portForward.length > 0 ? state.portForward : void 0,
+    snapshot: state.snapshot,
+    nested: state.nested || void 0,
+    name: state.name,
+    guestCwd: state.guestCwd,
+    detached: state.detached || void 0,
+    memory: state.memory,
+    json: state.json || void 0
   };
 }
+function handleRunMount(state, flag, args, index) {
+  assertRunFlagUnused(state.mount !== void 0, "--mount");
+  const result = consumeMount(flag, args, index);
+  state.mount = result.value;
+  return result.next;
+}
+function handleRunLiveMount(state, flag, args, index) {
+  const result = consumeLiveMount(flag, args, index);
+  state.liveMounts.push(result.value);
+  return result.next;
+}
+function handleRunEnv(state, flag, args, index) {
+  const result = consumeEnv(flag, args, index);
+  state.env[result.key] = result.value;
+  return result.next;
+}
+function handleRunPortForward(state, flag, args, index) {
+  return consumePortForward(flag, args, index, state.seenHostPorts, state.portForward);
+}
+function handleRunSnapshot(state, flag, args, index) {
+  assertRunFlagUnused(state.snapshot !== void 0, "--snapshot");
+  const { spec, next } = takeValue(flag, args, index, "a path value");
+  state.snapshot = spec;
+  return next;
+}
+function handleRunNested(state, _flag, _args, index) {
+  assertRunFlagUnused(state.nested, "--nested");
+  state.nested = true;
+  return index;
+}
+function handleRunNestedValue() {
+  throw new ParseError("PARSE_FLAG_MALFORMED", "--nested does not take a value");
+}
+function handleRunGuestCwd(state, flag, args, index) {
+  assertRunFlagUnused(state.guestCwd !== void 0, "--cwd");
+  const result = consumeGuestCwd(flag, args, index);
+  state.guestCwd = result.value;
+  return result.next;
+}
+function handleRunName(state, flag, args, index) {
+  assertRunFlagUnused(state.name !== void 0, "--name");
+  const { spec, next } = takeValue(flag, args, index, "a value");
+  state.name = spec;
+  return next;
+}
+function handleRunDetach(state, flag, _args, index) {
+  assertRunFlagUnused(state.detached, "--detached");
+  state.detached = true;
+  warnDeprecatedDetached(flag);
+  return index;
+}
+function handleRunJson(state, _flag, _args, index) {
+  state.json = true;
+  return index;
+}
+function handleRunMemory(state, flag, args, index) {
+  assertRunFlagUnused(state.memory !== void 0, "--memory");
+  const result = consumeMemory(flag, args, index);
+  state.memory = result.value;
+  return result.next;
+}
+function assertRunFlagUnused(used, flag) {
+  if (used) {
+    throw new ParseError(
+      "PARSE_FLAG_DUPLICATE",
+      `${flag} may be given at most once per invocation`
+    );
+  }
+}
+function warnDeprecatedDetached(flag) {
+  if (flag === "--detached" && !process.env.MACHINEN_QUIET_DEPRECATIONS && !process.env.VITEST) {
+    process.stderr.write("machinen: --detached is deprecated; use --detach (same behaviour).\n");
+  }
+}
 function parsePort(raw, label) {
   if (!/^[0-9]+$/.test(raw)) {
     throw new ParseError("PARSE_PORT_INVALID", `-p: ${label} must be numeric (got '${raw}')`);
@@ -715,167 +776,255 @@ function consumeGuestCwd(flag, args, i) {
 }
 
 // src/parse-fork-args.ts
+var FORK_VALUE_FLAGS = /* @__PURE__ */ new Map([
+  ["--new-name", "newName"],
+  ["--out-dir", "outDir"],
+  ["-p", "portForward"],
+  ["--publish", "portForward"],
+  ["--mount", "mount"],
+  ["--mount-live", "liveMount"],
+  ["--env", "env"],
+  ["--cwd", "guestCwd"],
+  ["--memory", "memory"]
+]);
+var FORK_BARE_FLAGS = /* @__PURE__ */ new Map([
+  ["--tcp-keep", "tcpKeep"],
+  ["--detach", "detach"],
+  ["--lazy", "lazy"]
+]);
+var FORK_FLAG_HANDLERS = {
+  newName: handleForkNewName,
+  outDir: handleForkOutDir,
+  tcpKeep: handleForkTcpKeep,
+  detach: handleForkDetach,
+  lazy: handleForkLazy,
+  portForward: handleForkPortForward,
+  mount: handleForkMount,
+  liveMount: handleForkLiveMount,
+  env: handleForkEnv,
+  guestCwd: handleForkGuestCwd,
+  memory: handleForkMemory
+};
 function parseForkArgs(argv) {
-  let newName;
-  let outDir;
-  let tcpKeep = false;
-  let detach = false;
-  let lazy = false;
-  const portForward = [];
-  const seenHostPorts = /* @__PURE__ */ new Set();
-  let mount;
-  const liveMounts = [];
-  const env = {};
-  let guestCwd;
-  let memory;
-  const rest = [];
+  const state = newForkParseState();
   for (let i = 0; i < argv.length; i++) {
-    const a = argv[i];
-    if (a === "--new-name" || a.startsWith("--new-name=")) {
-      if (newName !== void 0) {
-        throw new ParseError2(
-          "PARSE_FLAG_DUPLICATE",
-          "--new-name may be given at most once per invocation"
-        );
-      }
-      const { spec, next } = takeValue(a, argv, i, "a value");
-      newName = spec;
-      i = next;
-    } else if (a === "--out-dir" || a.startsWith("--out-dir=")) {
-      if (outDir !== void 0) {
-        throw new ParseError2(
-          "PARSE_FLAG_DUPLICATE",
-          "--out-dir may be given at most once per invocation"
-        );
-      }
-      const { spec, next } = takeValue(a, argv, i, "a directory path");
-      outDir = spec;
-      i = next;
-    } else if (a === "--tcp-keep") {
-      tcpKeep = true;
-    } else if (a === "--detach") {
-      detach = true;
-    } else if (a === "--lazy") {
-      lazy = true;
-    } else if (a === "-p" || a === "--publish" || a.startsWith("-p=") || a.startsWith("--publish=")) {
-      i = consumePortForward(a, argv, i, seenHostPorts, portForward);
-    } else if (a === "--mount" || a.startsWith("--mount=")) {
-      if (mount) {
-        throw new ParseError2(
-          "PARSE_FLAG_DUPLICATE",
-          "--mount may be given at most once per invocation"
-        );
-      }
-      const r = consumeMount(a, argv, i);
-      mount = r.value;
-      i = r.next;
-    } else if (a === "--mount-live" || a.startsWith("--mount-live=")) {
-      const r = consumeLiveMount(a, argv, i);
-      liveMounts.push(r.value);
-      i = r.next;
-    } else if (a === "--env" || a.startsWith("--env=")) {
-      const r = consumeEnv(a, argv, i);
-      env[r.key] = r.value;
-      i = r.next;
-    } else if (a === "--cwd" || a.startsWith("--cwd=")) {
-      if (guestCwd !== void 0) {
-        throw new ParseError2(
-          "PARSE_FLAG_DUPLICATE",
-          "--cwd may be given at most once per invocation"
-        );
-      }
-      const r = consumeGuestCwd(a, argv, i);
-      guestCwd = r.value;
-      i = r.next;
-    } else if (a === "--memory" || a.startsWith("--memory=")) {
-      if (memory !== void 0) {
-        throw new ParseError2(
-          "PARSE_FLAG_DUPLICATE",
-          "--memory may be given at most once per invocation"
-        );
-      }
-      const r = consumeMemory(a, argv, i);
-      memory = r.value;
-      i = r.next;
-    } else {
-      rest.push(a);
+    const arg = argv[i];
+    const flag = forkFlagFor(arg);
+    if (flag) {
+      i = FORK_FLAG_HANDLERS[flag](state, arg, argv, i);
+      continue;
     }
+    state.rest.push(arg);
+  }
+  return finishForkArgs(state);
+}
+function newForkParseState() {
+  return {
+    tcpKeep: false,
+    detach: false,
+    lazy: false,
+    portForward: [],
+    seenHostPorts: /* @__PURE__ */ new Set(),
+    liveMounts: [],
+    env: {},
+    rest: []
+  };
+}
+function forkFlagFor(arg) {
+  const eq = arg.indexOf("=");
+  if (eq !== -1) {
+    return FORK_VALUE_FLAGS.get(arg.slice(0, eq));
   }
+  return FORK_BARE_FLAGS.get(arg) ?? FORK_VALUE_FLAGS.get(arg);
+}
+function finishForkArgs(state) {
   return {
-    newName,
-    outDir,
-    tcpKeep,
-    detach,
-    lazy: lazy && !detach,
-    portForward,
-    mount,
-    liveMounts: liveMounts.length > 0 ? liveMounts : void 0,
-    env: Object.keys(env).length > 0 ? env : void 0,
-    guestCwd,
-    memory,
-    rest
+    newName: state.newName,
+    outDir: state.outDir,
+    tcpKeep: state.tcpKeep,
+    detach: state.detach,
+    lazy: state.lazy && !state.detach,
+    portForward: state.portForward,
+    mount: state.mount,
+    liveMounts: state.liveMounts.length > 0 ? state.liveMounts : void 0,
+    env: Object.keys(state.env).length > 0 ? state.env : void 0,
+    guestCwd: state.guestCwd,
+    memory: state.memory,
+    rest: state.rest
   };
 }
+function handleForkNewName(state, flag, args, index) {
+  assertForkFlagUnused(state.newName !== void 0, "--new-name");
+  const { spec, next } = takeValue(flag, args, index, "a value");
+  state.newName = spec;
+  return next;
+}
+function handleForkOutDir(state, flag, args, index) {
+  assertForkFlagUnused(state.outDir !== void 0, "--out-dir");
+  const { spec, next } = takeValue(flag, args, index, "a directory path");
+  state.outDir = spec;
+  return next;
+}
+function handleForkTcpKeep(state, _flag, _args, index) {
+  state.tcpKeep = true;
+  return index;
+}
+function handleForkDetach(state, _flag, _args, index) {
+  state.detach = true;
+  return index;
+}
+function handleForkLazy(state, _flag, _args, index) {
+  state.lazy = true;
+  return index;
+}
+function handleForkPortForward(state, flag, args, index) {
+  return consumePortForward(flag, args, index, state.seenHostPorts, state.portForward);
+}
+function handleForkMount(state, flag, args, index) {
+  assertForkFlagUnused(state.mount !== void 0, "--mount");
+  const result = consumeMount(flag, args, index);
+  state.mount = result.value;
+  return result.next;
+}
+function handleForkLiveMount(state, flag, args, index) {
+  const result = consumeLiveMount(flag, args, index);
+  state.liveMounts.push(result.value);
+  return result.next;
+}
+function handleForkEnv(state, flag, args, index) {
+  const result = consumeEnv(flag, args, index);
+  state.env[result.key] = result.value;
+  return result.next;
+}
+function handleForkGuestCwd(state, flag, args, index) {
+  assertForkFlagUnused(state.guestCwd !== void 0, "--cwd");
+  const result = consumeGuestCwd(flag, args, index);
+  state.guestCwd = result.value;
+  return result.next;
+}
+function handleForkMemory(state, flag, args, index) {
+  assertForkFlagUnused(state.memory !== void 0, "--memory");
+  const result = consumeMemory(flag, args, index);
+  state.memory = result.value;
+  return result.next;
+}
+function assertForkFlagUnused(used, flag) {
+  if (used) {
+    throw new ParseError2(
+      "PARSE_FLAG_DUPLICATE",
+      `${flag} may be given at most once per invocation`
+    );
+  }
+}
 
 // src/parse-restore-args.ts
 import { ParseError as ParseError3 } from "@machinen/runtime";
+var RESTORE_VALUE_FLAGS = /* @__PURE__ */ new Map([
+  ["--name", "name"],
+  ["--image", "image"],
+  ["--mount-live", "liveMount"],
+  ["-p", "portForward"],
+  ["--publish", "portForward"]
+]);
+var RESTORE_BARE_FLAGS = /* @__PURE__ */ new Map([["--lazy", "lazy"]]);
+var RESTORE_FLAG_HANDLERS = {
+  lazy: handleRestoreLazy,
+  name: handleRestoreName,
+  image: handleRestoreImage,
+  liveMount: handleRestoreLiveMount,
+  portForward: handleRestorePortForward
+};
 function parseRestoreArgs(argv) {
-  const positional = [];
-  let name;
-  let image;
-  let lazy = false;
-  const portForward = [];
-  const liveMounts = [];
-  const seenLiveGuests = /* @__PURE__ */ new Set();
-  const seenHostPorts = /* @__PURE__ */ new Set();
+  const state = newRestoreParseState();
   for (let i = 0; i < argv.length; i++) {
-    const a = argv[i];
-    if (a === "--lazy") {
-      lazy = true;
-    } else if (a === "--name" || a.startsWith("--name=")) {
-      const v = a === "--name" ? argv[++i] : a.slice("--name=".length);
-      if (!v) {
-        throw new ParseError3("PARSE_FLAG_MISSING_VALUE", "--name requires a value");
-      }
-      if (name !== void 0) {
-        throw new ParseError3(
-          "PARSE_FLAG_DUPLICATE",
-          "--name may be given at most once per invocation"
-        );
-      }
-      name = v;
-    } else if (a === "--image" || a.startsWith("--image=")) {
-      const v = a === "--image" ? argv[++i] : a.slice("--image=".length);
-      if (!v) {
-        throw new ParseError3("PARSE_FLAG_MISSING_VALUE", "--image requires a value");
-      }
-      if (image !== void 0) {
-        throw new ParseError3(
-          "PARSE_FLAG_DUPLICATE",
-          "--image may be given at most once per invocation"
-        );
-      }
-      image = v;
-    } else if (a === "--mount-live" || a.startsWith("--mount-live=")) {
-      const { value, next } = consumeLiveMount(a, argv, i);
-      i = next;
-      if (seenLiveGuests.has(value.guest)) {
-        throw new ParseError3(
-          "PARSE_FLAG_DUPLICATE",
-          `--mount-live override for guest=${value.guest} given more than once`
-        );
-      }
-      seenLiveGuests.add(value.guest);
-      liveMounts.push(value);
-    } else if (a === "-p" || a === "--publish" || a.startsWith("-p=") || a.startsWith("--publish=")) {
-      i = consumePortForward(a, argv, i, seenHostPorts, portForward);
-    } else if (a.startsWith("-")) {
-      throw new ParseError3("PARSE_FLAG_UNKNOWN", `unknown flag: ${a}`);
-    } else {
-      positional.push(a);
+    const arg = argv[i];
+    const flag = restoreFlagFor(arg);
+    if (flag) {
+      i = RESTORE_FLAG_HANDLERS[flag](state, arg, argv, i);
+      continue;
     }
+    if (arg.startsWith("-")) {
+      throw new ParseError3("PARSE_FLAG_UNKNOWN", `unknown flag: ${arg}`);
+    }
+    state.positional.push(arg);
+  }
+  return finishRestoreArgs(state);
+}
+function newRestoreParseState() {
+  return {
+    positional: [],
+    portForward: [],
+    lazy: false,
+    liveMounts: [],
+    seenLiveGuests: /* @__PURE__ */ new Set(),
+    seenHostPorts: /* @__PURE__ */ new Set()
+  };
+}
+function restoreFlagFor(arg) {
+  const eq = arg.indexOf("=");
+  if (eq !== -1) {
+    return RESTORE_VALUE_FLAGS.get(arg.slice(0, eq));
+  }
+  return RESTORE_BARE_FLAGS.get(arg) ?? RESTORE_VALUE_FLAGS.get(arg);
+}
+function finishRestoreArgs(state) {
+  return {
+    positional: state.positional,
+    name: state.name,
+    image: state.image,
+    portForward: state.portForward,
+    lazy: state.lazy,
+    liveMounts: state.liveMounts
+  };
+}
+function handleRestoreLazy(state, _flag, _args, index) {
+  state.lazy = true;
+  return index;
+}
+function handleRestoreName(state, flag, args, index) {
+  const { spec, next } = takeRestoreValue(flag, args, index, "a value", "--name");
+  assertRestoreFlagUnused(state.name !== void 0, "--name");
+  state.name = spec;
+  return next;
+}
+function handleRestoreImage(state, flag, args, index) {
+  const { spec, next } = takeRestoreValue(flag, args, index, "a value", "--image");
+  assertRestoreFlagUnused(state.image !== void 0, "--image");
+  state.image = spec;
+  return next;
+}
+function handleRestoreLiveMount(state, flag, args, index) {
+  const { value, next } = consumeLiveMount(flag, args, index);
+  assertRestoreLiveGuestUnused(state, value.guest);
+  state.seenLiveGuests.add(value.guest);
+  state.liveMounts.push(value);
+  return next;
+}
+function handleRestorePortForward(state, flag, args, index) {
+  return consumePortForward(flag, args, index, state.seenHostPorts, state.portForward);
+}
+function takeRestoreValue(flag, args, index, label, displayFlag) {
+  const result = takeValue(flag, args, index, label);
+  if (!result.spec) {
+    throw new ParseError3("PARSE_FLAG_MISSING_VALUE", `${displayFlag} requires ${label}`);
+  }
+  return result;
+}
+function assertRestoreFlagUnused(used, flag) {
+  if (used) {
+    throw new ParseError3(
+      "PARSE_FLAG_DUPLICATE",
+      `${flag} may be given at most once per invocation`
+    );
+  }
+}
+function assertRestoreLiveGuestUnused(state, guest) {
+  if (state.seenLiveGuests.has(guest)) {
+    throw new ParseError3(
+      "PARSE_FLAG_DUPLICATE",
+      `--mount-live override for guest=${guest} given more than once`
+    );
   }
-  return { positional, name, image, portForward, lazy, liveMounts };
 }
 
 // src/parse-target.ts
@@ -1095,37 +1244,69 @@ function printDiagnostics(summary, opts = {}) {
   if (!isQuiet()) {
     return;
   }
-  const bufStr = typeof opts.buffer === "string" ? opts.buffer : opts.buffer?.toString() ?? "";
+  const buffer = diagnosticsBuffer(opts.buffer);
   const tails = opts.tails ?? {};
-  const hasBuf = bufStr.trim().length > 0;
-  const hasTails = Object.values(tails).some((t) => t && t.trim().length > 0);
-  if (hasBuf || hasTails) {
-    process.stderr.write("\n--- diagnostics ---\n");
-    if (hasBuf) {
-      process.stderr.write(bufStr);
-      if (!bufStr.endsWith("\n")) {
-        process.stderr.write("\n");
-      }
+  printDiagnosticsEnvelope(buffer, tails);
+  printDiagnosticsHint(opts.hint);
+}
+function diagnosticsBuffer(buffer) {
+  if (typeof buffer === "string") {
+    return buffer;
+  }
+  if (buffer === void 0) {
+    return "";
+  }
+  return buffer.toString();
+}
+function printDiagnosticsEnvelope(buffer, tails) {
+  const hasBuffer = hasDiagnosticsContent(buffer);
+  if (!hasBuffer && !hasDiagnosticsTails(tails)) {
+    return;
+  }
+  process.stderr.write("\n--- diagnostics ---\n");
+  printDiagnosticsBuffer(buffer, hasBuffer);
+  printDiagnosticsTails(tails, hasBuffer);
+  process.stderr.write("--------------------\n\n");
+}
+function hasDiagnosticsContent(content) {
+  if (!content) {
+    return false;
+  }
+  return content.trim().length > 0;
+}
+function hasDiagnosticsTails(tails) {
+  return Object.values(tails).some(hasDiagnosticsContent);
+}
+function printDiagnosticsBuffer(buffer, hasBuffer) {
+  if (!hasBuffer) {
+    return;
+  }
+  process.stderr.write(buffer);
+  writeTrailingNewline(buffer);
+}
+function printDiagnosticsTails(tails, afterBuffer) {
+  for (const [label, content] of Object.entries(tails)) {
+    if (!hasDiagnosticsContent(content)) {
+      continue;
     }
-    for (const [label, content] of Object.entries(tails)) {
-      if (!content || content.trim().length === 0) {
-        continue;
-      }
-      if (hasBuf) {
-        process.stderr.write("\n");
-      }
-      process.stderr.write(`[${label}]
-`);
-      process.stderr.write(content);
-      if (!content.endsWith("\n")) {
-        process.stderr.write("\n");
-      }
+    if (afterBuffer) {
+      process.stderr.write("\n");
     }
-    process.stderr.write("--------------------\n\n");
+    process.stderr.write(`[${label}]
+`);
+    process.stderr.write(content);
+    writeTrailingNewline(content);
+  }
+}
+function writeTrailingNewline(content) {
+  if (!content.endsWith("\n")) {
+    process.stderr.write("\n");
   }
-  const hint = opts.hint ?? ESCAPE_HINT;
-  if (hint.length > 0) {
-    process.stderr.write(hint);
+}
+function printDiagnosticsHint(hint) {
+  const text = hint ?? ESCAPE_HINT;
+  if (text.length > 0) {
+    process.stderr.write(text);
   }
 }
 
@@ -1155,51 +1336,93 @@ var CACHE_ROOT = join2(homedir2(), ".machinen");
 function cacheDirFor(tag) {
   return join2(CACHE_ROOT, tag);
 }
-function baseDirFor(tag, distro = "debian", cpu = "arm64") {
+function guestCpu() {
+  const override = process.env.MACHINEN_GUEST_ARCH;
+  if (override === "arm64" || override === "amd64") {
+    return override;
+  }
+  return osArch() === "x64" ? "amd64" : "arm64";
+}
+function baseAssetSpec() {
+  return guestCpu() === "amd64" ? {
+    cpu: "amd64",
+    kernelAsset: "bzImage-x86_64",
+    rootfsAsset: "rootfs-debian-amd64.tar.gz"
+  } : {
+    cpu: "arm64",
+    kernelAsset: "Image-arm64",
+    dtbAsset: "virt-arm64.dtb",
+    rootfsAsset: "rootfs-debian-arm64.tar.gz"
+  };
+}
+function baseDirFor(tag, distro = "debian", cpu = guestCpu()) {
   return join2(cacheDirFor(tag), "bases", `${distro}-${cpu}`);
 }
 function baseAssetsComplete(tag) {
-  const base = baseDirFor(tag);
-  return existsSync2(join2(base, "Image")) && existsSync2(join2(base, "virt.dtb")) && existsSync2(join2(base, "rootfs.tar.gz"));
+  const spec = baseAssetSpec();
+  const base = baseDirFor(tag, "debian", spec.cpu);
+  return existsSync2(join2(base, "Image")) && (!spec.dtbAsset || existsSync2(join2(base, "virt.dtb"))) && existsSync2(join2(base, "rootfs.tar.gz"));
 }
-var ASSETS_DIR_FILES = ["Image-arm64", "virt-arm64.dtb", "rootfs-debian-arm64.tar.gz"];
 function validateAssetsDir(dir) {
   const abs = resolve(dir);
   if (!existsSync2(abs)) {
     die(`MACHINEN_ASSETS_DIR=${dir} does not exist`);
   }
-  const missing = ASSETS_DIR_FILES.filter((f) => !existsSync2(join2(abs, f)));
+  const spec = baseAssetSpec();
+  const required = [spec.kernelAsset, spec.rootfsAsset, ...spec.dtbAsset ? [spec.dtbAsset] : []];
+  const missing = required.filter((f) => !existsSync2(join2(abs, f)));
   if (missing.length > 0) {
     die(
-      `MACHINEN_ASSETS_DIR=${dir} is missing: ${missing.join(", ")}
+      `MACHINEN_ASSETS_DIR=${dir} is missing for ${spec.cpu}: ${missing.join(", ")}
   Produce them with ./scripts/build-base-assets.sh (outputs to ./release-assets/).`
     );
   }
 }
 async function ensureBaseAssets(tag) {
-  const base = baseDirFor(tag);
-  const kernel = join2(base, "Image");
-  const dtb = join2(base, "virt.dtb");
-  const tarball = join2(base, "rootfs.tar.gz");
-  if (existsSync2(kernel) && existsSync2(dtb) && existsSync2(tarball)) {
+  const spec = baseAssetSpec();
+  const base = baseDirFor(tag, "debian", spec.cpu);
+  if (cachedBaseAssetsReady(base, spec)) {
     return base;
   }
   mkdirSync2(base, { recursive: true });
-  const assets = [
-    { name: "Image-arm64", dest: kernel },
-    { name: "virt-arm64.dtb", dest: dtb },
-    { name: "rootfs-debian-arm64.tar.gz", dest: tarball }
-  ];
-  await Promise.all(assets.map((a) => downloadWithChecksum(a.name, a.dest, tag)));
+  await downloadBaseAssets(tag, base, spec);
+  replaceCurrentBaseSymlink(tag);
+  return base;
+}
+function cachedBaseAssetsReady(base, spec) {
+  if (!existsSync2(join2(base, "Image"))) {
+    return false;
+  }
+  if (spec.dtbAsset && !existsSync2(join2(base, "virt.dtb"))) {
+    return false;
+  }
+  return existsSync2(join2(base, "rootfs.tar.gz"));
+}
+async function downloadBaseAssets(tag, base, spec) {
+  await Promise.all(
+    baseAssetDownloads(base, spec).map((a) => downloadWithChecksum(a.name, a.dest, tag))
+  );
+}
+function baseAssetDownloads(base, spec) {
+  const assets = [{ name: spec.kernelAsset, dest: join2(base, "Image") }];
+  if (spec.dtbAsset) {
+    assets.push({ name: spec.dtbAsset, dest: join2(base, "virt.dtb") });
+  }
+  assets.push({ name: spec.rootfsAsset, dest: join2(base, "rootfs.tar.gz") });
+  return assets;
+}
+function replaceCurrentBaseSymlink(tag) {
   const current = join2(CACHE_ROOT, "current");
   try {
-    if (existsSync2(current) || isSymlink(current)) {
-      unlinkSync(current);
-    }
+    unlinkCurrentSymlink(current);
   } catch {
   }
   symlinkSync(tag, current, "dir");
-  return base;
+}
+function unlinkCurrentSymlink(current) {
+  if (existsSync2(current) || isSymlink(current)) {
+    unlinkSync(current);
+  }
 }
 function isSymlink(p) {
   try {
@@ -1343,36 +1566,7 @@ function emitJson(value) {
 function emitJsonError(code, message) {
   process.stderr.write(JSON.stringify({ schema_version: 1, error: { code, message } }) + "\n");
 }
-async function cmdBoot(args) {
-  let parsed;
-  try {
-    parsed = parseRunArgs(args);
-  } catch (err) {
-    handleError(err);
-  }
-  const {
-    positional,
-    double_dash_args,
-    mount,
-    liveMounts,
-    env,
-    portForward,
-    snapshot,
-    name,
-    guestCwd,
-    detached,
-    memory,
-    json
-  } = parsed;
-  if (json && !detached) {
-    die("boot --json is only meaningful with --detach (attached boots take over stdio).");
-  }
-  if (positional.length > 1) {
-    die(
-      "usage: machinen boot [<image>] [--snapshot <path>] [--name <name>] [--cwd <abs-path>] [--mount ...] [--mount-live ...] [--env KEY=VALUE]... [--detached] [--memory <mib>] [-- <cmd> [args...]]"
-    );
-  }
-  const imageOverride = positional[0];
+async function resolveCliBaseAssets() {
   const assetsOverride = process.env.MACHINEN_ASSETS_DIR;
   if (assetsOverride) {
     validateAssetsDir(assetsOverride);
@@ -1381,311 +1575,462 @@ async function cmdBoot(args) {
 `);
     await ensureBaseAssets(RELEASE_TAG);
   }
-  const baseDir = assetsOverride ? resolve(assetsOverride) : baseDirFor(RELEASE_TAG);
-  const kernelPath = join2(baseDir, assetsOverride ? "Image-arm64" : "Image");
-  const dtbPath = join2(baseDir, assetsOverride ? "virt-arm64.dtb" : "virt.dtb");
-  const defaultImagePath = join2(
-    baseDir,
-    assetsOverride ? "rootfs-debian-arm64.tar.gz" : "rootfs.tar.gz"
-  );
-  const imagePath = imageOverride ? resolve(imageOverride) : defaultImagePath;
-  debug(
-    "boot baseDir=%s kernel=%s dtb=%s image=%s snapshot=%s name=%s",
+  return cliBaseAssetPaths(assetsOverride);
+}
+function cliBaseAssetPaths(assetsOverride) {
+  const spec = baseAssetSpec();
+  const baseDir = cliBaseDir(assetsOverride, spec.cpu);
+  return {
     baseDir,
-    kernelPath,
-    dtbPath,
-    imagePath,
-    snapshot ?? "<none>",
-    name ?? "<unset>"
-  );
-  const cmd = double_dash_args.length > 0 ? ["/usr/bin/env", ...double_dash_args] : void 0;
-  const headlineName = name ?? deriveBootName(imageOverride);
-  const showHeadlines = isQuiet() && !(detached && json);
-  const bootT0 = Date.now();
-  const buffer = new RingBuffer();
-  let filter = null;
-  let filterOut = null;
-  if (showHeadlines) {
-    printHeadline(`booting ${headlineName}\u2026`);
-    if (!detached) {
-      filterOut = new PassThrough();
-      filter = new NoiseFilter({
-        buffer,
-        out: filterOut,
-        onReady: () => {
-          printHeadline("guest ready");
-          printHeadline(`ready in ${formatElapsed(Date.now() - bootT0)}`);
-        }
-      });
-    }
+    kernelPath: cliKernelPath(baseDir, assetsOverride, spec),
+    dtbPath: cliDtbPath(baseDir, assetsOverride, spec),
+    defaultImagePath: cliRootfsPath(baseDir, assetsOverride, spec)
+  };
+}
+function cliBaseDir(assetsOverride, cpu) {
+  if (assetsOverride) {
+    return resolve(assetsOverride);
   }
-  const onLog = filter ? (evt) => {
-    if (evt.source === "guest-console") {
-      filter.push(evt.chunk);
-    }
-  } : showHeadlines ? (evt) => {
-    if (evt.source === "guest-console") {
-      buffer.push(evt.chunk);
-    }
-  } : void 0;
-  let vm;
-  try {
-    vm = await boot({
-      // Always pass the base rootfs so /sbin/machinen-restore and
-      // friends are in the initramfs even on a bare `machinen restore
-      // <snap>` (no --image, no -- cmd).
-      image: imagePath,
-      cmd,
-      env,
-      kernel: kernelPath,
-      dtb: dtbPath,
-      mount,
-      liveMounts,
-      portForward,
-      snapshot,
-      name,
-      guestCwd,
-      detached,
-      memory,
-      onLog,
-      // Interactive CLI: the session lives as long as the guest does.
-      // Don't impose the default 60s cap. Detached boots fall back to
-      // the runtime's own readiness timeout (60s) so the CLI can't
-      // hang forever waiting for first-guest-byte.
-      timeoutMs: detached ? void 0 : null
-    });
-  } catch (err) {
-    filter?.flush();
-    if (showHeadlines) {
-      failQuiet(`boot ${headlineName} failed: ${describeError(err)}`, {
-        buffer
-      });
-    }
-    handleError(err);
+  return baseDirFor(RELEASE_TAG, "debian", cpu);
+}
+function cliKernelPath(baseDir, assetsOverride, spec) {
+  return join2(baseDir, assetsOverride ? spec.kernelAsset : "Image");
+}
+function cliDtbPath(baseDir, assetsOverride, spec) {
+  if (!spec.dtbAsset) {
+    return void 0;
   }
-  if (detached) {
-    if (json) {
-      emitJson({
-        schema_version: 1,
-        pid: vm.pid,
-        name: name ?? null,
-        detached: true
-      });
-    } else {
-      const target = name ?? `pid ${vm.pid}`;
-      process.stderr.write(
-        `machinen: detached (${target}). Reattach: machinen attach ${name ?? vm.pid}
-Stop: kill ${vm.pid}  (machinen stop ships in PR2)
-`
-      );
-    }
-    return 0;
+  return join2(baseDir, assetsOverride ? spec.dtbAsset : "virt.dtb");
+}
+function cliRootfsPath(baseDir, assetsOverride, spec) {
+  return join2(baseDir, assetsOverride ? spec.rootfsAsset : "rootfs.tar.gz");
+}
+function resolveOptionalImageOverride(imageOverride) {
+  if (!imageOverride) {
+    return void 0;
+  }
+  const imagePath = resolve(imageOverride);
+  if (!existsSync2(imagePath)) {
+    die(`--image: file not found: ${imagePath}`);
   }
+  return imagePath;
+}
+async function runAttachedVmSession(vm, opts) {
   vm.stdout.pipe(process.stdout);
-  if (!filter) {
+  if (!opts.filter) {
     vm.stderr.pipe(process.stderr);
   }
   const restoreStdin = rawModeStdinIfTTY();
   const cancelHintRepeat = printCtrlDHint();
-  let forwardedSignal = null;
+  const signalState = installVmSignalHandlers(vm);
+  pipeStdinToVm(vm.stdin, () => {
+    process.stderr.write("\nmachinen: Ctrl-D \u2014 stopping VM\n");
+    signalState.forwardedSignal = "SIGTERM";
+    void vm.kill();
+  });
+  opts.filterOut?.pipe(process.stderr);
+  try {
+    return await waitForAttachedVm(vm, opts, signalState);
+  } finally {
+    signalState.remove();
+    cancelHintRepeat();
+    restoreStdin();
+  }
+}
+function installVmSignalHandlers(vm) {
+  const state = { forwardedSignal: null, remove: () => {
+  } };
   const onSigint = () => {
-    forwardedSignal = "SIGINT";
+    state.forwardedSignal = "SIGINT";
     void vm.kill();
   };
   const onSigterm = () => {
-    forwardedSignal = "SIGTERM";
+    state.forwardedSignal = "SIGTERM";
     void vm.kill();
   };
   process.on("SIGINT", onSigint);
   process.on("SIGTERM", onSigterm);
-  pipeStdinToVm(vm.stdin, () => {
-    process.stderr.write("\nmachinen: Ctrl-D \u2014 stopping VM\n");
-    forwardedSignal = "SIGTERM";
-    void vm.kill();
-  });
-  filterOut?.pipe(process.stderr);
-  try {
-    const { code } = await vm.wait();
-    filter?.flush();
-    if (forwardedSignal === "SIGINT") {
-      return 130;
-    }
-    if (forwardedSignal === "SIGTERM") {
-      return 143;
-    }
-    if (filter && !filter.ready && code != null && code !== 0 && !forwardedSignal) {
-      printDiagnostics(`boot ${headlineName} exited ${code} before reaching ready`, { buffer });
-    }
-    return code ?? 0;
-  } finally {
+  state.remove = () => {
     process.off("SIGINT", onSigint);
     process.off("SIGTERM", onSigterm);
-    cancelHintRepeat();
-    restoreStdin();
+  };
+  return state;
+}
+async function waitForAttachedVm(vm, opts, signalState) {
+  const { code } = await vm.wait();
+  opts.filter?.flush();
+  const signalExitCode = forwardedSignalExitCode(signalState.forwardedSignal);
+  if (signalExitCode !== void 0) {
+    return signalExitCode;
+  }
+  if (shouldPrintPreReadyDiagnostics(opts.filter, code, signalState.forwardedSignal)) {
+    printDiagnostics(opts.preReadyExitSummary(code), { buffer: opts.buffer });
   }
+  return code ?? 0;
 }
-async function cmdInstall(args) {
-  const { json, rest } = consumeJsonFlag(args);
-  const tag = argValue(rest, "--version") ?? RELEASE_TAG;
-  const wasComplete = baseAssetsComplete(tag);
-  const t0 = Date.now();
-  if (!json) {
-    process.stderr.write(`installing base assets for ${tag}\u2026
-`);
-    if (!isQuiet()) {
-      process.stderr.write(`  into ${cacheDirFor(tag)}
-`);
-    }
+function forwardedSignalExitCode(signal) {
+  if (signal === "SIGINT") {
+    return 130;
   }
-  let base;
-  try {
-    base = await ensureBaseAssets(tag);
-  } catch (err) {
-    if (isQuiet() && !json) {
-      failQuiet(`install ${tag} failed: ${describeError(err)}`);
-    }
-    throw err;
+  if (signal === "SIGTERM") {
+    return 143;
   }
-  if (json) {
-    emitJson({
-      schema_version: 1,
-      tag,
-      base_dir: base,
-      fetched: !wasComplete
-    });
-  } else if (wasComplete) {
-    process.stderr.write(`ready: ${base} (cached)
-`);
-  } else {
-    process.stderr.write(`ready in ${formatElapsed(Date.now() - t0)}: ${base}
-`);
+  return void 0;
+}
+function shouldPrintPreReadyDiagnostics(filter, code, forwardedSignal) {
+  if (!filter) {
+    return false;
   }
-  return 0;
+  if (filter.ready || forwardedSignal) {
+    return false;
+  }
+  return isNonZeroExit(code);
 }
-async function cmdRestore(args) {
-  let parsed;
+function isNonZeroExit(code) {
+  if (code === null) {
+    return false;
+  }
+  return code !== 0;
+}
+async function cmdBoot(args) {
+  const parsed = parseBootCommandArgs(args);
+  validateBootCommandArgs(parsed);
+  const imageOverride = parsed.positional[0];
+  const paths = await resolveCliBaseAssets();
+  const imagePath = imageOverride ? resolve(imageOverride) : paths.defaultImagePath;
+  logBootPlan(paths, imagePath, parsed);
+  const quiet = createBootQuietState(parsed, imageOverride);
+  const vm = await startBootVm(parsed, paths, imagePath, bootEnvCommand(parsed), quiet);
+  if (parsed.detached) {
+    reportDetachedBoot(vm, parsed);
+    return 0;
+  }
+  return runBootAttachedSession(vm, quiet);
+}
+function parseBootCommandArgs(args) {
   try {
-    parsed = parseRestoreArgs(args);
+    return parseRunArgs(args);
   } catch (err) {
     handleError(err);
   }
-  const { positional, name, image: imageOverride, portForward, lazy, liveMounts } = parsed;
-  if (positional.length !== 1) {
-    die(
-      "usage: machinen restore <snap-dir> [--image <tarball>] [--name <name>] [--lazy] [-p <hostPort>:<guestPort>] [--mount-live <host>:<guest>[:<mode>]]"
-    );
+}
+function validateBootCommandArgs(parsed) {
+  if (parsed.json && !parsed.detached) {
+    die("boot --json is only meaningful with --detach (attached boots take over stdio).");
   }
-  const snapDir = resolve(positional[0]);
-  const assetsOverride = process.env.MACHINEN_ASSETS_DIR;
-  if (assetsOverride) {
-    validateAssetsDir(assetsOverride);
-  } else if (!baseAssetsComplete(RELEASE_TAG)) {
-    process.stderr.write(`machinen: fetching base assets for ${RELEASE_TAG} (first run)
-`);
-    await ensureBaseAssets(RELEASE_TAG);
+  if (parsed.positional.length > 1) {
+    die(bootUsage());
   }
-  const baseDir = assetsOverride ? resolve(assetsOverride) : baseDirFor(RELEASE_TAG);
-  const kernelPath = join2(baseDir, assetsOverride ? "Image-arm64" : "Image");
-  const dtbPath = join2(baseDir, assetsOverride ? "virt-arm64.dtb" : "virt.dtb");
-  let imagePath;
-  if (imageOverride) {
-    imagePath = resolve(imageOverride);
-    if (!existsSync2(imagePath)) {
-      die(`--image: file not found: ${imagePath}`);
-    }
+}
+function bootUsage() {
+  return "usage: machinen boot [<image>] [--snapshot <path>] [--name <name>] [--cwd <abs-path>] [--mount ...] [--mount-live ...] [--env KEY=VALUE]... [--detached] [--nested] [--memory <mib>] [-- <cmd> [args...]]";
+}
+function logBootPlan(paths, imagePath, parsed) {
+  debug(
+    "boot baseDir=%s kernel=%s dtb=%s image=%s snapshot=%s name=%s",
+    paths.baseDir,
+    paths.kernelPath,
+    paths.dtbPath,
+    imagePath,
+    parsed.snapshot ?? "<none>",
+    parsed.name ?? "<unset>"
+  );
+}
+function bootEnvCommand(parsed) {
+  if (parsed.double_dash_args.length === 0) {
+    return void 0;
   }
-  const headlineName = name ?? deriveBootName(snapDir);
-  const showHeadlines = isQuiet();
-  const restoreT0 = Date.now();
+  return ["/usr/bin/env", ...parsed.double_dash_args];
+}
+function createBootQuietState(parsed, imageOverride) {
+  const headlineName = parsed.name ?? deriveBootName(imageOverride);
+  const showHeadlines = shouldShowBootHeadlines(parsed);
   const buffer = new RingBuffer();
-  let filter = null;
-  if (showHeadlines) {
-    printHeadline(`restoring ${headlineName}\u2026`);
-    filter = new NoiseFilter({
-      buffer,
-      out: process.stderr,
-      onReady: () => {
-        printHeadline(`restored in ${formatElapsed(Date.now() - restoreT0)}`);
-      }
-    });
+  if (!showHeadlines) {
+    return { headlineName, showHeadlines, buffer, filter: null, filterOut: null };
   }
-  const onLog = filter ? (evt) => {
+  return createVisibleBootQuietState(parsed, headlineName, showHeadlines, buffer);
+}
+function shouldShowBootHeadlines(parsed) {
+  if (!isQuiet()) {
+    return false;
+  }
+  if (parsed.detached && parsed.json) {
+    return false;
+  }
+  return true;
+}
+function createVisibleBootQuietState(parsed, headlineName, showHeadlines, buffer) {
+  printHeadline(`booting ${headlineName}\u2026`);
+  if (parsed.detached) {
+    return bootBufferOnlyQuietState(headlineName, showHeadlines, buffer);
+  }
+  return bootFilteredQuietState(headlineName, showHeadlines, buffer, Date.now());
+}
+function bootBufferOnlyQuietState(headlineName, showHeadlines, buffer) {
+  return {
+    headlineName,
+    showHeadlines,
+    buffer,
+    filter: null,
+    filterOut: null,
+    onLog: guestConsoleOnLog((chunk) => buffer.push(chunk))
+  };
+}
+function bootFilteredQuietState(headlineName, showHeadlines, buffer, bootT0) {
+  const filterOut = new PassThrough();
+  const filter = new NoiseFilter({
+    buffer,
+    out: filterOut,
+    onReady: () => {
+      printHeadline("guest ready");
+      printHeadline(`ready in ${formatElapsed(Date.now() - bootT0)}`);
+    }
+  });
+  return {
+    headlineName,
+    showHeadlines,
+    buffer,
+    filter,
+    filterOut,
+    onLog: guestConsoleOnLog((chunk) => filter.push(chunk))
+  };
+}
+function guestConsoleOnLog(push) {
+  return (evt) => {
     if (evt.source === "guest-console") {
-      filter.push(evt.chunk);
+      push(evt.chunk);
     }
-  } : void 0;
-  let vm;
+  };
+}
+async function startBootVm(parsed, paths, imagePath, cmd, quiet) {
   try {
-    vm = await restore({
-      snapDir,
+    return await boot({
+      // Always pass the base rootfs so /sbin/machinen-restore and
+      // friends are in the initramfs even on a bare `machinen restore
+      // <snap>` (no --image, no -- cmd).
       image: imagePath,
-      kernel: kernelPath,
-      dtb: dtbPath,
-      name,
-      lazy,
-      portForward: portForward.length > 0 ? portForward : void 0,
+      cmd,
+      env: parsed.env,
+      kernel: paths.kernelPath,
+      dtb: paths.dtbPath,
+      mount: parsed.mount,
+      liveMounts: parsed.liveMounts,
+      portForward: parsed.portForward,
+      snapshot: parsed.snapshot,
+      nested: parsed.nested,
+      name: parsed.name,
+      guestCwd: parsed.guestCwd,
+      detached: parsed.detached,
+      memory: parsed.memory,
+      onLog: quiet.onLog,
+      // Interactive CLI: the session lives as long as the guest does.
+      // Don't impose the default 60s cap. Detached boots fall back to
+      // the runtime's own readiness timeout (60s) so the CLI can't
+      // hang forever waiting for first-guest-byte.
+      timeoutMs: parsed.detached ? void 0 : null
+    });
+  } catch (err) {
+    handleBootFailure(err, quiet);
+  }
+}
+function handleBootFailure(err, quiet) {
+  quiet.filter?.flush();
+  if (quiet.showHeadlines) {
+    failQuiet(`boot ${quiet.headlineName} failed: ${describeError(err)}`, {
+      buffer: quiet.buffer
+    });
+  }
+  handleError(err);
+}
+function reportDetachedBoot(vm, parsed) {
+  if (parsed.json) {
+    emitDetachedBootJson(vm, parsed);
+    return;
+  }
+  printDetachedBootHint(vm, parsed);
+}
+function emitDetachedBootJson(vm, parsed) {
+  emitJson({ schema_version: 1, pid: vm.pid, name: parsed.name ?? null, detached: true });
+}
+function printDetachedBootHint(vm, parsed) {
+  const target = parsed.name ?? `pid ${vm.pid}`;
+  process.stderr.write(
+    `machinen: detached (${target}). Reattach: machinen attach ${parsed.name ?? vm.pid}
+Stop: kill ${vm.pid}  (machinen stop ships in PR2)
+`
+  );
+}
+function runBootAttachedSession(vm, quiet) {
+  return runAttachedVmSession(vm, {
+    filter: quiet.filter,
+    filterOut: quiet.filterOut,
+    buffer: quiet.buffer,
+    preReadyExitSummary: (code) => `boot ${quiet.headlineName} exited ${code} before reaching ready`
+  });
+}
+async function cmdInstall(args) {
+  const opts = parseInstallOptions(args);
+  const result = await installBaseAssets(opts);
+  reportInstallResult(opts, result);
+  return 0;
+}
+function parseInstallOptions(args) {
+  const { json, rest } = consumeJsonFlag(args);
+  return { json, tag: argValue(rest, "--version") ?? RELEASE_TAG };
+}
+async function installBaseAssets(opts) {
+  const wasComplete = baseAssetsComplete(opts.tag);
+  const t0 = Date.now();
+  printInstallStart(opts);
+  try {
+    const base = await ensureBaseAssets(opts.tag);
+    return { base, wasComplete, elapsedMs: Date.now() - t0 };
+  } catch (err) {
+    reportInstallFailure(opts, err);
+    throw err;
+  }
+}
+function printInstallStart(opts) {
+  if (opts.json) {
+    return;
+  }
+  process.stderr.write(`installing base assets for ${opts.tag}\u2026
+`);
+  if (!isQuiet()) {
+    process.stderr.write(`  into ${cacheDirFor(opts.tag)}
+`);
+  }
+}
+function reportInstallFailure(opts, err) {
+  if (isQuiet() && !opts.json) {
+    failQuiet(`install ${opts.tag} failed: ${describeError(err)}`);
+  }
+}
+function reportInstallResult(opts, result) {
+  if (opts.json) {
+    emitInstallJson(opts, result);
+    return;
+  }
+  printInstallReady(result);
+}
+function emitInstallJson(opts, result) {
+  emitJson({
+    schema_version: 1,
+    tag: opts.tag,
+    base_dir: result.base,
+    fetched: !result.wasComplete
+  });
+}
+function printInstallReady(result) {
+  if (result.wasComplete) {
+    process.stderr.write(`ready: ${result.base} (cached)
+`);
+    return;
+  }
+  process.stderr.write(`ready in ${formatElapsed(result.elapsedMs)}: ${result.base}
+`);
+}
+async function cmdRestore(args) {
+  const parsed = parseRestoreCommandArgs(args);
+  validateRestoreCommandArgs(parsed);
+  const snapDir = resolve(parsed.positional[0]);
+  const paths = await resolveCliBaseAssets();
+  const quiet = createRestoreQuietState(parsed, snapDir);
+  const vm = await startRestoreVm(parsed, snapDir, paths, quiet);
+  reportRestoreSuccess(vm, quiet);
+  return runRestoreAttachedSession(vm, quiet);
+}
+function parseRestoreCommandArgs(args) {
+  try {
+    return parseRestoreArgs(args);
+  } catch (err) {
+    handleError(err);
+  }
+}
+function validateRestoreCommandArgs(parsed) {
+  if (parsed.positional.length !== 1) {
+    die(restoreUsage());
+  }
+}
+function restoreUsage() {
+  return "usage: machinen restore <snap-dir> [--image <tarball>] [--name <name>] [--lazy] [-p <hostPort>:<guestPort>] [--mount-live <host>:<guest>[:<mode>]]";
+}
+function createRestoreQuietState(parsed, snapDir) {
+  const headlineName = parsed.name ?? deriveBootName(snapDir);
+  const buffer = new RingBuffer();
+  if (!isQuiet()) {
+    return { headlineName, showHeadlines: false, buffer, filter: null, filterOut: null };
+  }
+  printHeadline(`restoring ${headlineName}\u2026`);
+  return restoreFilteredQuietState(headlineName, buffer, Date.now());
+}
+function restoreFilteredQuietState(headlineName, buffer, restoreT0) {
+  const filter = new NoiseFilter({
+    buffer,
+    out: process.stderr,
+    onReady: () => {
+      printHeadline(`restored in ${formatElapsed(Date.now() - restoreT0)}`);
+    }
+  });
+  return {
+    headlineName,
+    showHeadlines: true,
+    buffer,
+    filter,
+    filterOut: null,
+    onLog: guestConsoleOnLog((chunk) => filter.push(chunk))
+  };
+}
+async function startRestoreVm(parsed, snapDir, paths, quiet) {
+  try {
+    return await restore({
+      snapDir,
+      image: resolveOptionalImageOverride(parsed.image),
+      kernel: paths.kernelPath,
+      dtb: paths.dtbPath,
+      name: parsed.name,
+      lazy: parsed.lazy,
+      portForward: optionalList(parsed.portForward),
       // #273: per-guest overrides for the bundle's recorded
       // liveMounts. Empty list = use the bundle's recorded mounts
       // verbatim; non-empty entries replace the matching guest's
       // host/mode (BOOT_LIVE_MOUNT_OVERRIDE_UNKNOWN if no match).
-      liveMounts: liveMounts.length > 0 ? liveMounts : void 0,
+      liveMounts: optionalList(parsed.liveMounts),
       timeoutMs: null,
-      onLog
+      onLog: quiet.onLog
     });
   } catch (err) {
-    filter?.flush();
-    if (showHeadlines) {
-      failQuiet(`restore ${headlineName} failed: ${describeError(err)}`, {
-        buffer
-      });
-    }
-    handleError(err);
+    handleRestoreFailure(err, quiet);
   }
-  if (!showHeadlines) {
+}
+function optionalList(items) {
+  if (items.length === 0) {
+    return void 0;
+  }
+  return items;
+}
+function handleRestoreFailure(err, quiet) {
+  quiet.filter?.flush();
+  if (quiet.showHeadlines) {
+    failQuiet(`restore ${quiet.headlineName} failed: ${describeError(err)}`, {
+      buffer: quiet.buffer
+    });
+  }
+  handleError(err);
+}
+function reportRestoreSuccess(vm, quiet) {
+  if (!quiet.showHeadlines) {
     process.stderr.write(`restored as: ${vm.name ?? "<anonymous>"} (pid ${vm.pid})
 `);
   }
-  vm.stdout.pipe(process.stdout);
-  if (!filter) {
-    vm.stderr.pipe(process.stderr);
-  }
-  const restoreStdin = rawModeStdinIfTTY();
-  const cancelHintRepeat = printCtrlDHint();
-  let forwardedSignal = null;
-  const onSigint = () => {
-    forwardedSignal = "SIGINT";
-    void vm.kill();
-  };
-  const onSigterm = () => {
-    forwardedSignal = "SIGTERM";
-    void vm.kill();
-  };
-  process.on("SIGINT", onSigint);
-  process.on("SIGTERM", onSigterm);
-  pipeStdinToVm(vm.stdin, () => {
-    process.stderr.write("\nmachinen: Ctrl-D \u2014 stopping VM\n");
-    forwardedSignal = "SIGTERM";
-    void vm.kill();
+}
+function runRestoreAttachedSession(vm, quiet) {
+  return runAttachedVmSession(vm, {
+    filter: quiet.filter,
+    buffer: quiet.buffer,
+    preReadyExitSummary: (code) => `restore ${quiet.headlineName} exited ${code} before reaching ready`
   });
-  try {
-    const { code } = await vm.wait();
-    filter?.flush();
-    if (forwardedSignal === "SIGINT") {
-      return 130;
-    }
-    if (forwardedSignal === "SIGTERM") {
-      return 143;
-    }
-    if (filter && !filter.ready && code != null && code !== 0 && !forwardedSignal) {
-      printDiagnostics(`restore ${headlineName} exited ${code} before reaching ready`, { buffer });
-    }
-    return code ?? 0;
-  } finally {
-    process.off("SIGINT", onSigint);
-    process.off("SIGTERM", onSigterm);
-    cancelHintRepeat();
-    restoreStdin();
-  }
 }
 async function cmdLs(args) {
   const { json, rest } = consumeJsonFlag(args);
@@ -1693,52 +2038,95 @@ async function cmdLs(args) {
     die(`unknown argument: ${rest[0]}`);
   }
   const entries = list();
-  const rssByPid = readHostRssBytesMulti(
-    entries.map((e) => ({ pid: e.pid, statsPath: e.statsPath }))
-  );
+  const rssByPid = rssByRegistryPid(entries);
   if (json) {
-    emitJson({
-      schema_version: 1,
-      vms: entries.map((e) => ({
-        pid: e.pid,
-        name: e.name ?? null,
-        started_at: e.startedAt,
-        uptime_ms: Date.now() - e.startedAt,
-        memory: {
-          rss_bytes: rssByPid.get(e.pid) ?? null,
-          ceiling_mib: e.memoryCeilingMib ?? null
-        },
-        ports: e.portForward ?? [],
-        forked_from: e.forkedFrom ?? null
-      }))
-    });
-    return 0;
+    emitLsJson(entries, rssByPid);
+  } else {
+    printLsTable(entries, rssByPid);
+  }
+  return 0;
+}
+function rssByRegistryPid(entries) {
+  return readHostRssBytesMulti(
+    entries.map((entry) => ({ pid: entry.pid, statsPath: entry.statsPath }))
+  );
+}
+function emitLsJson(entries, rssByPid) {
+  emitJson({
+    schema_version: 1,
+    vms: entries.map((entry) => vmJson(entry, rssByPid))
+  });
+}
+function vmJson(entry, rssByPid) {
+  return {
+    pid: entry.pid,
+    name: nullable(entry.name),
+    started_at: entry.startedAt,
+    uptime_ms: Date.now() - entry.startedAt,
+    memory: vmMemoryJson(entry, rssByPid),
+    ports: portsJson(entry),
+    forked_from: nullable(entry.forkedFrom)
+  };
+}
+function portsJson(entry) {
+  if (entry.portForward === void 0) {
+    return [];
   }
+  return entry.portForward;
+}
+function vmMemoryJson(entry, rssByPid) {
+  return {
+    rss_bytes: nullable(rssByPid.get(entry.pid)),
+    ceiling_mib: nullable(entry.memoryCeilingMib)
+  };
+}
+function nullable(value) {
+  if (value === void 0) {
+    return null;
+  }
+  return value;
+}
+function printLsTable(entries, rssByPid) {
   if (entries.length === 0) {
     process.stdout.write("(no running VMs)\n");
-    return 0;
+    return;
   }
   const header = ["PID", "NAME", "UP", "MEM", "PORTS", "FORKED-FROM"];
-  const rows = entries.map((e) => [
-    String(e.pid),
-    e.name ?? "-",
-    formatUptime(Date.now() - e.startedAt),
-    formatMem(rssByPid.get(e.pid) ?? null, e.memoryCeilingMib),
-    formatPorts(e.portForward),
-    e.forkedFrom ?? "-"
+  const rows = lsRows(entries, rssByPid);
+  const widths = tableWidths(header, rows);
+  const visible = visibleLsColumns(header, widths);
+  printTable(header, rows, widths, visible);
+}
+function lsRows(entries, rssByPid) {
+  return entries.map((entry) => [
+    String(entry.pid),
+    entry.name ?? "-",
+    formatUptime(Date.now() - entry.startedAt),
+    formatMem(rssByPid.get(entry.pid) ?? null, entry.memoryCeilingMib),
+    formatPorts(entry.portForward),
+    entry.forkedFrom ?? "-"
   ]);
-  const widths = header.map((h, i) => Math.max(h.length, ...rows.map((r) => r[i].length)));
+}
+function tableWidths(header, rows) {
+  return header.map(
+    (heading, index) => Math.max(heading.length, ...rows.map((row) => row[index].length))
+  );
+}
+function visibleLsColumns(header, widths) {
   const gap = "  ";
-  const fullWidth = widths.reduce((sum, w) => sum + w, 0) + gap.length * (widths.length - 1);
+  const fullWidth = widths.reduce((sum, width) => sum + width, 0) + gap.length * (widths.length - 1);
   const cols = process.stdout.columns;
   const includeMem = cols === void 0 || fullWidth <= cols;
-  const visible = includeMem ? header.map((_, i) => i) : header.map((_, i) => i).filter((i) => i !== 3);
-  const line = (cells) => visible.map((i) => cells[i].padEnd(widths[i])).join(gap);
-  process.stdout.write(line(header) + "\n");
+  return includeMem ? header.map((_, i) => i) : header.map((_, i) => i).filter((i) => i !== 3);
+}
+function printTable(header, rows, widths, visible) {
+  process.stdout.write(formatTableLine(header, widths, visible) + "\n");
   for (const row of rows) {
-    process.stdout.write(line(row) + "\n");
+    process.stdout.write(formatTableLine(row, widths, visible) + "\n");
   }
-  return 0;
+}
+function formatTableLine(cells, widths, visible) {
+  return visible.map((index) => cells[index].padEnd(widths[index])).join("  ");
 }
 function formatUptime(ms) {
   const s = Math.floor(ms / 1e3);
@@ -1756,180 +2144,265 @@ function formatUptime(ms) {
   return `${Math.floor(h / 24)}d`;
 }
 async function cmdGc(args) {
-  const { json, rest: afterJson } = consumeJsonFlag(args);
-  const { dryRun, rest } = consumeDryRunFlag(afterJson);
-  for (const a of rest) {
-    die(`unknown flag: ${a}`);
-  }
+  const { json, dryRun, rest } = parseGcOptions(args);
+  dieOnUnexpectedArgs(rest);
   const results = runGc({ dryRun });
   if (json) {
-    emitJson({
-      schema_version: 1,
-      dry_run: dryRun,
-      results: results.map((r) => ({
-        pid: r.pid,
-        name: r.name ?? null,
-        status: r.status,
-        removed_paths: r.removedPaths,
-        failed_paths: r.failedPaths
-      }))
-    });
-    return 0;
+    emitGcJson(dryRun, results);
+  } else {
+    printGcResults(results, dryRun);
   }
+  return 0;
+}
+function parseGcOptions(args) {
+  const { json, rest: afterJson } = consumeJsonFlag(args);
+  const { dryRun, rest } = consumeDryRunFlag(afterJson);
+  return { json, dryRun, rest };
+}
+function dieOnUnexpectedArgs(args) {
+  for (const arg of args) {
+    die(`unknown flag: ${arg}`);
+  }
+}
+function emitGcJson(dryRun, results) {
+  emitJson({
+    schema_version: 1,
+    dry_run: dryRun,
+    results: results.map((r) => ({
+      pid: r.pid,
+      name: r.name ?? null,
+      status: r.status,
+      removed_paths: r.removedPaths,
+      failed_paths: r.failedPaths
+    }))
+  });
+}
+function printGcResults(results, dryRun) {
   if (results.length === 0) {
     process.stdout.write("(nothing to clean up)\n");
-    return 0;
+    return;
   }
-  for (const r of results) {
-    const label = r.name ? `${r.name} (pid ${r.pid})` : `pid ${r.pid}`;
-    const verb = dryRun ? "would clean" : "cleaned";
-    process.stdout.write(`${verb} ${label} [${r.status}]: ${r.removedPaths.length} path(s)
-`);
-    for (const p of r.removedPaths) {
-      process.stdout.write(`  ${p}
-`);
-    }
-    for (const p of r.failedPaths) {
-      process.stdout.write(`  failed: ${p}
+  for (const result of results) {
+    printGcResult(result, dryRun);
+  }
+}
+function printGcResult(result, dryRun) {
+  const label = result.name ? `${result.name} (pid ${result.pid})` : `pid ${result.pid}`;
+  const verb = dryRun ? "would clean" : "cleaned";
+  process.stdout.write(
+    `${verb} ${label} [${result.status}]: ${result.removedPaths.length} path(s)
+`
+  );
+  printIndentedPaths(result.removedPaths, "");
+  printIndentedPaths(result.failedPaths, "failed: ");
+}
+function printIndentedPaths(paths, prefix) {
+  for (const path of paths) {
+    process.stdout.write(`  ${prefix}${path}
 `);
-    }
   }
-  return 0;
 }
 async function cmdStop(args) {
+  const opts = parseStopOptions(args);
+  const entry = lookupEntry(opts.target);
+  if (!entry) {
+    reportStopMissingTarget(opts);
+    return 1;
+  }
+  return stopExistingEntry(entry, opts);
+}
+async function stopExistingEntry(entry, opts) {
+  const status = validateStopEntry(entry);
+  if (await handleInactiveStopEntry(entry, status, opts)) {
+    return 0;
+  }
+  if (opts.dryRun) {
+    reportStopDryRun(entry, opts);
+    return 0;
+  }
+  return stopLiveEntry(entry, opts);
+}
+async function stopLiveEntry(entry, opts) {
+  const sig = stopSignal(opts.force);
+  if (!signalStopProcess(entry.pid, sig, opts, "STOP_KILL_FAILED")) {
+    return 1;
+  }
+  await escalateIfNeeded(entry.pid, opts.force);
+  await stopGvproxy(entry, sig, opts.force);
+  finishStoppedEntry(entry, opts);
+  return 0;
+}
+function parseStopOptions(args) {
   const { json, rest: afterJson } = consumeJsonFlag(args);
   const { dryRun, rest: afterDry } = consumeDryRunFlag(afterJson);
-  let force = false;
+  const { force, rest } = consumeForceFlag(afterDry);
+  return { json, dryRun, force, target: parseTargetFlags(rest, "stop") };
+}
+function consumeForceFlag(args) {
   const rest = [];
-  for (const a of afterDry) {
-    if (a === "--force" || a === "-9") {
+  let force = false;
+  for (const arg of args) {
+    if (arg === "--force" || arg === "-9") {
       force = true;
     } else {
-      rest.push(a);
+      rest.push(arg);
     }
   }
-  const target = parseTargetFlags(rest, "stop");
-  const entry = lookupEntry(target);
-  if (!entry) {
-    if (json) {
-      emitJsonError("VM_NOT_FOUND", `no running VM matched ${describeTarget(target)}`);
-    } else {
-      process.stderr.write(`machinen stop: no running VM matched ${describeTarget(target)}
+  return { force, rest };
+}
+function reportStopMissingTarget(opts) {
+  const message = `no running VM matched ${describeTarget(opts.target)}`;
+  if (opts.json) {
+    emitJsonError("VM_NOT_FOUND", message);
+  } else {
+    process.stderr.write(`machinen stop: ${message}
 `);
-    }
-    return 1;
   }
-  const emitStop = (status2) => {
-    if (json) {
-      emitJson({
-        schema_version: 1,
-        pid: entry.pid,
-        name: entry.name ?? null,
-        status: status2,
-        dry_run: dryRun
-      });
-    }
-  };
-  const status = validatePid(entry.pid, {
+}
+function emitStop(entry, opts, status) {
+  if (!opts.json) {
+    return;
+  }
+  emitJson({
+    schema_version: 1,
+    pid: entry.pid,
+    name: entry.name ?? null,
+    status,
+    dry_run: opts.dryRun
+  });
+}
+function validateStopEntry(entry) {
+  return validatePid(entry.pid, {
     vmmExe: entry.vmmExe,
     startedAt: entry.startedAt
   });
+}
+async function handleInactiveStopEntry(entry, status, opts) {
   if (status === "recycled") {
-    if (!json) {
-      process.stderr.write(
-        `machinen stop: registry entry pid ${entry.pid} is now held by an unrelated process; ` + (dryRun ? "would skip kill and gc.\n" : "skipping kill and running gc.\n")
-      );
-    }
-    if (!dryRun) {
-      runGc({ pid: entry.pid });
-    }
-    emitStop("recycled");
-    return 0;
+    reportRecycledStopEntry(entry, opts);
+    gcStoppedEntry(entry, opts.dryRun);
+    emitStop(entry, opts, "recycled");
+    return true;
   }
   if (status === "dead") {
-    if (!json) {
-      process.stderr.write(
-        `machinen stop: pid ${entry.pid} already gone; ` + (dryRun ? "would gc.\n" : "running gc.\n")
-      );
-    }
-    if (!dryRun) {
-      runGc({ pid: entry.pid });
-    }
-    emitStop("already_dead");
-    return 0;
+    reportDeadStopEntry(entry, opts);
+    gcStoppedEntry(entry, opts.dryRun);
+    emitStop(entry, opts, "already_dead");
+    return true;
   }
-  if (dryRun) {
-    if (!json) {
-      const label = entry.name ? `${entry.name} (pid ${entry.pid})` : `pid ${entry.pid}`;
-      const sigLabel = force ? "SIGKILL" : "SIGTERM (escalates to SIGKILL after 2s)";
-      process.stdout.write(`would ${sigLabel} ${label}
+  return false;
+}
+function reportRecycledStopEntry(entry, opts) {
+  if (opts.json) {
+    return;
+  }
+  process.stderr.write(
+    `machinen stop: registry entry pid ${entry.pid} is now held by an unrelated process; ` + (opts.dryRun ? "would skip kill and gc.\n" : "skipping kill and running gc.\n")
+  );
+}
+function reportDeadStopEntry(entry, opts) {
+  if (opts.json) {
+    return;
+  }
+  process.stderr.write(
+    `machinen stop: pid ${entry.pid} already gone; ` + (opts.dryRun ? "would gc.\n" : "running gc.\n")
+  );
+}
+function gcStoppedEntry(entry, dryRun) {
+  if (!dryRun) {
+    runGc({ pid: entry.pid });
+  }
+}
+function reportStopDryRun(entry, opts) {
+  if (!opts.json) {
+    const sigLabel = opts.force ? "SIGKILL" : "SIGTERM (escalates to SIGKILL after 2s)";
+    process.stdout.write(`would ${sigLabel} ${entryLabel(entry)}
 `);
-    }
-    emitStop("would_stop");
-    return 0;
   }
-  const sig = force ? "SIGKILL" : "SIGTERM";
+  emitStop(entry, opts, "would_stop");
+}
+function stopSignal(force) {
+  return force ? "SIGKILL" : "SIGTERM";
+}
+function signalStopProcess(pid, signal, opts, errorCode) {
   try {
-    process.kill(entry.pid, sig);
+    process.kill(pid, signal);
+    return true;
   } catch (err) {
-    const msg = `failed to signal pid ${entry.pid}: ${err instanceof Error ? err.message : String(err)}`;
-    if (json) {
-      emitJsonError("STOP_KILL_FAILED", msg);
-    } else {
-      process.stderr.write(`machinen stop: ${msg}
+    reportStopSignalError(pid, err, opts, errorCode);
+    return false;
+  }
+}
+function reportStopSignalError(pid, err, opts, errorCode) {
+  const msg = `failed to signal pid ${pid}: ${describeError(err)}`;
+  if (opts.json) {
+    emitJsonError(errorCode, msg);
+  } else {
+    process.stderr.write(`machinen stop: ${msg}
 `);
-    }
-    return 1;
   }
-  if (!force) {
-    await waitForExit(entry.pid, 2e3);
-    try {
-      process.kill(entry.pid, 0);
-      try {
-        process.kill(entry.pid, "SIGKILL");
-      } catch {
-      }
-    } catch {
-    }
+}
+async function escalateIfNeeded(pid, force) {
+  if (force) {
+    return;
   }
-  if (entry.gvproxyPid && entry.gvproxyExe) {
-    const gvStatus = validatePid(entry.gvproxyPid, { vmmExe: entry.gvproxyExe });
-    if (gvStatus === "alive") {
-      try {
-        process.kill(entry.gvproxyPid, sig);
-      } catch (err) {
-        process.stderr.write(
-          `machinen stop: failed to signal gvproxy pid ${entry.gvproxyPid}: ${err instanceof Error ? err.message : String(err)}
-`
-        );
-      }
-      if (!force) {
-        await waitForExit(entry.gvproxyPid, 2e3);
-        try {
-          process.kill(entry.gvproxyPid, 0);
-          try {
-            process.kill(entry.gvproxyPid, "SIGKILL");
-          } catch {
-          }
-        } catch {
-        }
-      }
-    } else if (gvStatus === "recycled") {
-      process.stderr.write(
-        `machinen stop: gvproxy pid ${entry.gvproxyPid} now held by an unrelated process; skipping.
+  await waitForExit(pid, 2e3);
+  if (pidIsAlive(pid)) {
+    tryKill(pid, "SIGKILL");
+  }
+}
+function pidIsAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function tryKill(pid, signal) {
+  try {
+    process.kill(pid, signal);
+  } catch {
+  }
+}
+async function stopGvproxy(entry, signal, force) {
+  if (!entry.gvproxyPid || !entry.gvproxyExe) {
+    return;
+  }
+  await handleGvproxyStatus(
+    entry.gvproxyPid,
+    validatePid(entry.gvproxyPid, { vmmExe: entry.gvproxyExe }),
+    signal,
+    force
+  );
+}
+async function handleGvproxyStatus(pid, status, signal, force) {
+  if (status === "alive") {
+    await signalGvproxy(pid, signal, force);
+  } else if (status === "recycled") {
+    process.stderr.write(
+      `machinen stop: gvproxy pid ${pid} now held by an unrelated process; skipping.
 `
-      );
-    }
+    );
   }
+}
+async function signalGvproxy(pid, signal, force) {
+  if (!signalStopProcess(pid, signal, { json: false }, "STOP_GVPROXY_KILL_FAILED")) {
+    return;
+  }
+  await escalateIfNeeded(pid, force);
+}
+function finishStoppedEntry(entry, opts) {
   runGc({ pid: entry.pid });
-  if (json) {
-    emitStop("stopped");
+  if (opts.json) {
+    emitStop(entry, opts, "stopped");
   } else {
-    const label = entry.name ? `${entry.name} (pid ${entry.pid})` : `pid ${entry.pid}`;
-    process.stdout.write(`stopped ${label}
+    process.stdout.write(`stopped ${entryLabel(entry)}
 `);
   }
-  return 0;
+}
+function entryLabel(entry) {
+  return entry.name ? `${entry.name} (pid ${entry.pid})` : `pid ${entry.pid}`;
 }
 async function waitForExit(pid, timeoutMs) {
   const deadline = Date.now() + timeoutMs;
@@ -1943,406 +2416,510 @@ async function waitForExit(pid, timeoutMs) {
   }
 }
 function lookupEntry(target) {
-  for (const e of list()) {
-    if ("name" in target && e.name === target.name) {
-      return e;
-    }
-    if ("pid" in target && e.pid === target.pid) {
-      return e;
-    }
+  return list().find((entry) => entryMatchesTarget(entry, target));
+}
+function entryMatchesTarget(entry, target) {
+  if ("name" in target) {
+    return entry.name === target.name;
   }
-  return void 0;
+  return entry.pid === target.pid;
 }
 function describeTarget(target) {
   return "name" in target ? `name ${target.name}` : `pid ${target.pid}`;
 }
 async function cmdExec(args) {
-  let usePty = false;
-  const filtered = [];
-  for (const a of args) {
-    if (a === "--tty" || a === "--pty") {
-      usePty = true;
-    } else {
-      filtered.push(a);
-    }
+  const parsed = parseExecArgs(args);
+  const vm = await attach(parsed.target).catch(handleError);
+  try {
+    return await runExecCommand(vm, parsed);
+  } finally {
+    await vm.detach();
   }
+}
+function parseExecArgs(args) {
+  const { usePty, filtered } = consumeExecPtyFlag(args);
   const dashIdx = filtered.indexOf("--");
   if (dashIdx === -1 || dashIdx === filtered.length - 1) {
     die("usage: machinen exec <name|pid> [--tty] -- <cmd>");
   }
-  const pre = filtered.slice(0, dashIdx);
-  const cmdArgs = filtered.slice(dashIdx + 1);
-  const target = parseTargetFlags(pre, "exec");
-  const vm = await attach(target).catch(handleError);
-  try {
-    const joined = cmdArgs.join(" ");
-    if (usePty) {
-      if (!process.stdin.isTTY) {
-        die("machinen exec --tty: stdin is not a TTY; pass via terminal or drop --tty");
-      }
-      return await runPtyExec(vm, joined);
+  return {
+    usePty,
+    target: parseTargetFlags(filtered.slice(0, dashIdx), "exec"),
+    cmd: filtered.slice(dashIdx + 1).join(" ")
+  };
+}
+function consumeExecPtyFlag(args) {
+  const filtered = [];
+  let usePty = false;
+  for (const arg of args) {
+    if (arg === "--tty" || arg === "--pty") {
+      usePty = true;
+    } else {
+      filtered.push(arg);
     }
-    const res = await vm.execRaw(joined, {
-      onStdout: (chunk) => process.stdout.write(chunk),
-      onStderr: (chunk) => process.stderr.write(chunk)
-    });
-    return res.exitCode;
-  } finally {
-    await vm.detach();
   }
+  return { usePty, filtered };
+}
+async function runExecCommand(vm, parsed) {
+  if (parsed.usePty) {
+    assertExecPtyTty();
+    return runPtyExec(vm, parsed.cmd);
+  }
+  return runRawExec(vm, parsed.cmd);
+}
+function assertExecPtyTty() {
+  if (!process.stdin.isTTY) {
+    die("machinen exec --tty: stdin is not a TTY; pass via terminal or drop --tty");
+  }
+}
+async function runRawExec(vm, cmd) {
+  const res = await vm.execRaw(cmd, {
+    onStdout: (chunk) => process.stdout.write(chunk),
+    onStderr: (chunk) => process.stderr.write(chunk)
+  });
+  return res.exitCode;
 }
 async function runPtyExec(vm, cmd) {
-  const stdin = process.stdin;
-  const stdout = process.stdout;
-  const initialCols = stdout.columns ?? 80;
-  const initialRows = stdout.rows ?? 24;
-  const wasRaw = stdin.isRaw === true;
-  stdin.setRawMode(true);
-  stdin.resume();
+  const tty = enterPtyRawMode();
   const handle = vm.execPty(cmd, {
-    cols: initialCols,
-    rows: initialRows,
-    stdin,
-    stdout
+    cols: tty.cols,
+    rows: tty.rows,
+    stdin: process.stdin,
+    stdout: process.stdout
   });
-  const onResize = () => {
-    handle.resize(stdout.columns ?? initialCols, stdout.rows ?? initialRows);
-  };
-  stdout.on("resize", onResize);
+  const onResize = () => handle.resize(process.stdout.columns ?? tty.cols, process.stdout.rows ?? tty.rows);
+  process.stdout.on("resize", onResize);
   try {
     const { exitCode } = await handle.result;
     return exitCode;
   } finally {
-    stdout.removeListener("resize", onResize);
-    if (!wasRaw) {
-      try {
-        stdin.setRawMode(false);
-      } catch {
-      }
-    }
+    process.stdout.removeListener("resize", onResize);
+    tty.restore();
+  }
+}
+function enterPtyRawMode() {
+  const wasRaw = process.stdin.isRaw === true;
+  process.stdin.setRawMode(true);
+  process.stdin.resume();
+  return {
+    cols: process.stdout.columns ?? 80,
+    rows: process.stdout.rows ?? 24,
+    restore: () => restorePtyRawMode(wasRaw)
+  };
+}
+function restorePtyRawMode(wasRaw) {
+  if (wasRaw) {
+    return;
+  }
+  try {
+    process.stdin.setRawMode(false);
+  } catch {
   }
 }
 async function cmdSnapshot(args) {
+  const opts = parseSnapshotOptions(args);
+  if (opts.dryRun) {
+    return snapshotDryRun(opts);
+  }
+  return runSnapshot(opts);
+}
+function parseSnapshotOptions(args) {
   const { json, rest: afterJson } = consumeJsonFlag(args);
   const { dryRun, rest: afterDry } = consumeDryRunFlag(afterJson);
+  const { keepAlive, rest } = consumeKeepAliveFlag(afterDry);
+  const { target, rest: afterTarget } = resolveTarget(rest, "snapshot");
+  const outDir = parseSnapshotOutDir(afterTarget);
+  return { json, dryRun, keepAlive, target, outDir, resolvedOutDir: resolve(outDir) };
+}
+function consumeKeepAliveFlag(args) {
+  const rest = [];
   let keepAlive = false;
-  const remaining = [];
-  for (const a of afterDry) {
-    if (a === "--keep-alive") {
+  for (const arg of args) {
+    if (arg === "--keep-alive") {
       keepAlive = true;
     } else {
-      remaining.push(a);
+      rest.push(arg);
     }
   }
-  const { target, rest: afterTarget } = resolveTarget(remaining, "snapshot");
-  if (afterTarget.length === 0) {
+  return { keepAlive, rest };
+}
+function parseSnapshotOutDir(args) {
+  if (args.length === 0) {
     die("usage: machinen snapshot <name|pid> <out-dir> [--keep-alive] [--dry-run] [--json]");
   }
-  if (afterTarget.length > 1) {
-    die(`unknown argument: ${afterTarget[1]}`);
+  if (args.length > 1) {
+    die(`unknown argument: ${args[1]}`);
+  }
+  return args[0];
+}
+function snapshotDryRun(opts) {
+  const entry = lookupEntry(opts.target);
+  if (!entry) {
+    reportSnapshotMissingTarget(opts);
+    return 1;
+  }
+  reportSnapshotDryRun(entry, opts);
+  return 0;
+}
+function reportSnapshotMissingTarget(opts) {
+  const msg = `no running VM matched ${describeTarget(opts.target)}`;
+  if (opts.json) {
+    emitJsonError("VM_NOT_FOUND", msg);
+  } else {
+    process.stderr.write(`machinen snapshot: ${msg}
+`);
+  }
+}
+function reportSnapshotDryRun(entry, opts) {
+  if (opts.json) {
+    emitSnapshotJson(opts.resolvedOutDir, 0, true);
+    return;
+  }
+  const suffix = opts.keepAlive ? " (--keep-alive)\n" : "\n";
+  process.stdout.write(`would snapshot ${entryLabel(entry)} \u2192 ${opts.resolvedOutDir}${suffix}`);
+}
+async function runSnapshot(opts) {
+  const vm = await attach(opts.target).catch(handleError);
+  const quiet = createSnapshotQuietState(vm, opts);
+  try {
+    const res = await vm.snapshot({
+      outDir: opts.resolvedOutDir,
+      leaveRunning: opts.keepAlive,
+      tcpClose: opts.keepAlive,
+      onLog: snapshotOnLog(quiet)
+    });
+    reportSnapshotSuccess(res.snapDir, res.elapsedMs, opts);
+    return 0;
+  } catch (err) {
+    handleSnapshotFailure(err, quiet);
+  } finally {
+    await vm.detach();
+  }
+}
+function createSnapshotQuietState(vm, opts) {
+  const headlineName = vm.name ?? `pid ${vm.pid}`;
+  const showHeadlines = isQuiet() && !opts.json;
+  const buffer = new RingBuffer();
+  if (showHeadlines) {
+    printHeadline(`snapshotting ${headlineName}\u2026`);
   }
-  const outDir = afterTarget[0];
-  const resolvedOutDir = resolve(outDir);
-  if (dryRun) {
-    const entry = lookupEntry(target);
-    if (!entry) {
-      const msg = `no running VM matched ${describeTarget(target)}`;
-      if (json) {
-        emitJsonError("VM_NOT_FOUND", msg);
-      } else {
-        process.stderr.write(`machinen snapshot: ${msg}
-`);
-      }
-      return 1;
+  return { headlineName, showHeadlines, buffer, filter: null, filterOut: null };
+}
+function snapshotOnLog(quiet) {
+  return (evt) => {
+    if (evt.source === "phase") {
+      return;
     }
-    if (json) {
-      emitJson({
-        schema_version: 1,
-        snap_dir: resolvedOutDir,
-        elapsed_ms: 0,
-        dry_run: true
-      });
+    if (quiet.showHeadlines) {
+      quiet.buffer.push(evt.chunk);
     } else {
-      const label = entry.name ? `${entry.name} (pid ${entry.pid})` : `pid ${entry.pid}`;
-      process.stdout.write(
-        `would snapshot ${label} \u2192 ${resolvedOutDir}` + (keepAlive ? " (--keep-alive)\n" : "\n")
-      );
+      process.stderr.write(evt.chunk);
     }
-    return 0;
+  };
+}
+function reportSnapshotSuccess(snapDir, elapsedMs, opts) {
+  if (opts.json) {
+    emitSnapshotJson(snapDir, elapsedMs, false);
+    return;
   }
-  const vm = await attach(target).catch(handleError);
-  const snapHeadlineName = vm.name ?? `pid ${vm.pid}`;
-  const showHeadlines = isQuiet() && !json;
-  const buffer = new RingBuffer();
-  if (showHeadlines) {
-    printHeadline(`snapshotting ${snapHeadlineName}\u2026`);
+  process.stdout.write(`snapshot: ${snapDir} (${elapsedMs}ms)
+`);
+}
+function emitSnapshotJson(snapDir, elapsedMs, dryRun) {
+  emitJson({ schema_version: 1, snap_dir: snapDir, elapsed_ms: elapsedMs, dry_run: dryRun });
+}
+function handleSnapshotFailure(err, quiet) {
+  if (quiet.showHeadlines) {
+    failQuiet(`snapshot ${quiet.headlineName} failed: ${describeError(err)}`, {
+      buffer: quiet.buffer
+    });
   }
+  handleError(err);
+}
+async function cmdFork(args) {
+  const opts = await prepareForkCommand(args);
+  const vm = await attach(opts.target).catch(handleError);
   try {
-    const res = await vm.snapshot({
-      outDir: resolvedOutDir,
-      leaveRunning: keepAlive,
-      tcpClose: keepAlive,
-      onLog: (evt) => {
-        if (evt.source === "phase") {
-          return;
-        }
-        if (showHeadlines) {
-          buffer.push(evt.chunk);
-        } else {
-          process.stderr.write(evt.chunk);
-        }
-      }
-    });
-    if (json) {
-      emitJson({
-        schema_version: 1,
-        snap_dir: res.snapDir,
-        elapsed_ms: res.elapsedMs,
-        dry_run: false
-      });
-    } else {
-      process.stdout.write(`snapshot: ${res.snapDir} (${res.elapsedMs}ms)
-`);
+    const fork = await startForkVm(vm, opts);
+    reportForkStarted(fork, opts);
+    if (opts.parsed.detach) {
+      return detachFork(fork, opts);
     }
-    return 0;
+    return runForkAttachedSession(fork, opts.quiet);
   } catch (err) {
-    if (showHeadlines) {
-      failQuiet(`snapshot ${snapHeadlineName} failed: ${describeError(err)}`, {
-        buffer
-      });
-    }
     handleError(err);
   } finally {
     await vm.detach();
   }
 }
-async function cmdFork(args) {
-  const { json, rest: forkArgs } = consumeJsonFlag(args);
-  let parsed;
+async function prepareForkCommand(args) {
+  const { json, rest } = consumeJsonFlag(args);
+  const parsed = parseForkCommandArgs(rest);
+  const target = parseTargetFlags(parsed.rest, "fork");
+  validateForkCommand(json, parsed);
+  const paths = await resolveCliBaseAssets();
+  const resolvedOutDir = resolveForkOutDir(parsed.outDir);
+  return {
+    json,
+    target,
+    parsed,
+    paths,
+    resolvedOutDir,
+    quiet: createForkQuietState(json, parsed, target)
+  };
+}
+function parseForkCommandArgs(args) {
   try {
-    parsed = parseForkArgs(forkArgs);
+    return parseForkArgs(args);
   } catch (err) {
     handleError(err);
   }
-  const {
-    newName,
-    outDir,
-    tcpKeep,
-    detach,
-    lazy,
-    portForward,
-    mount,
-    liveMounts,
-    env,
-    guestCwd,
-    memory,
-    rest
-  } = parsed;
-  const target = parseTargetFlags(rest, "fork");
-  if (json && !detach) {
+}
+function validateForkCommand(json, parsed) {
+  if (json && !parsed.detach) {
     die("fork --json is only meaningful with --detach (attached forks take over stdio).");
   }
-  const assetsOverride = process.env.MACHINEN_ASSETS_DIR;
-  if (assetsOverride) {
-    validateAssetsDir(assetsOverride);
-  } else if (!baseAssetsComplete(RELEASE_TAG)) {
-    process.stderr.write(`machinen: fetching base assets for ${RELEASE_TAG} (first run)
-`);
-    await ensureBaseAssets(RELEASE_TAG);
+}
+function resolveForkOutDir(outDir) {
+  if (outDir) {
+    return resolve(outDir);
   }
-  const baseDir = assetsOverride ? resolve(assetsOverride) : baseDirFor(RELEASE_TAG);
-  const kernelPath = join2(baseDir, assetsOverride ? "Image-arm64" : "Image");
-  const dtbPath = join2(baseDir, assetsOverride ? "virt-arm64.dtb" : "virt.dtb");
-  const imagePath = join2(baseDir, assetsOverride ? "rootfs-debian-arm64.tar.gz" : "rootfs.tar.gz");
-  const resolvedOutDir = outDir ? resolve(outDir) : mkdtempSync(join2(tmpdir(), "machinen-fork-"));
-  const vm = await attach(target).catch(handleError);
-  const sourceLabel = "name" in target ? target.name : `pid ${target.pid}`;
-  const forkHeadlineName = newName ?? sourceLabel;
-  const showHeadlines = isQuiet() && !(detach && json);
-  const forkT0 = Date.now();
+  return mkdtempSync(join2(tmpdir(), "machinen-fork-"));
+}
+function createForkQuietState(json, parsed, target) {
+  const sourceLabel = describeForkSource(target);
+  const headlineName = parsed.newName ?? sourceLabel;
   const buffer = new RingBuffer();
-  let filter = null;
-  if (showHeadlines) {
-    printHeadline(`forking ${sourceLabel} \u2192 ${forkHeadlineName}\u2026`);
-    if (!detach) {
-      filter = new NoiseFilter({
-        buffer,
-        out: process.stderr,
-        onReady: () => {
-          printHeadline(`fork ready in ${formatElapsed(Date.now() - forkT0)}`);
-        }
-      });
-    }
+  if (!shouldShowForkHeadlines(json, parsed)) {
+    return forkOperatorQuietState(headlineName, buffer);
   }
-  const onLog = filter ? (evt) => {
-    if (evt.source === "guest-console") {
-      filter.push(evt.chunk);
-    }
-  } : showHeadlines ? (evt) => {
-    if (evt.source === "guest-console") {
-      buffer.push(evt.chunk);
-    }
-  } : (evt) => {
-    if (evt.source !== "phase") {
-      process.stderr.write(evt.chunk);
+  return createVisibleForkQuietState(parsed, sourceLabel, headlineName, buffer);
+}
+function shouldShowForkHeadlines(json, parsed) {
+  if (!isQuiet()) {
+    return false;
+  }
+  if (parsed.detach && json) {
+    return false;
+  }
+  return true;
+}
+function createVisibleForkQuietState(parsed, sourceLabel, headlineName, buffer) {
+  printHeadline(`forking ${sourceLabel} \u2192 ${headlineName}\u2026`);
+  if (parsed.detach) {
+    return bootBufferOnlyQuietState(headlineName, true, buffer);
+  }
+  return forkFilteredQuietState(headlineName, true, buffer, Date.now());
+}
+function describeForkSource(target) {
+  return "name" in target ? target.name : `pid ${target.pid}`;
+}
+function forkOperatorQuietState(headlineName, buffer) {
+  return {
+    headlineName,
+    showHeadlines: false,
+    buffer,
+    filter: null,
+    filterOut: null,
+    onLog: operatorForkOnLog
+  };
+}
+function operatorForkOnLog(evt) {
+  if (evt.source !== "phase") {
+    process.stderr.write(evt.chunk);
+  }
+}
+function forkFilteredQuietState(headlineName, showHeadlines, buffer, forkT0) {
+  const filter = new NoiseFilter({
+    buffer,
+    out: process.stderr,
+    onReady: () => {
+      printHeadline(`fork ready in ${formatElapsed(Date.now() - forkT0)}`);
     }
+  });
+  return {
+    headlineName,
+    showHeadlines,
+    buffer,
+    filter,
+    filterOut: null,
+    onLog: guestConsoleOnLog((chunk) => filter.push(chunk))
   };
+}
+async function startForkVm(vm, opts) {
   try {
-    let fork;
-    try {
-      fork = await vm.fork({
-        name: newName,
-        outDir: resolvedOutDir,
-        image: imagePath,
-        kernel: kernelPath,
-        dtb: dtbPath,
-        tcpKeep,
-        lazy,
-        portForward: portForward.length > 0 ? portForward : void 0,
-        mount,
-        liveMounts,
-        env,
-        guestCwd,
-        memory,
-        onLog
-      });
-    } catch (err) {
-      filter?.flush();
-      if (showHeadlines) {
-        failQuiet(`fork ${forkHeadlineName} failed: ${describeError(err)}`, {
-          buffer
-        });
-      }
-      throw err;
-    }
-    if (!showHeadlines && !json) {
-      process.stderr.write(`forked: ${fork.name ?? "<anonymous>"} (pid ${fork.pid})
+    return await vm.fork({
+      name: opts.parsed.newName,
+      outDir: opts.resolvedOutDir,
+      image: opts.paths.defaultImagePath,
+      kernel: opts.paths.kernelPath,
+      dtb: opts.paths.dtbPath,
+      tcpKeep: opts.parsed.tcpKeep,
+      lazy: opts.parsed.lazy,
+      portForward: optionalList(opts.parsed.portForward),
+      mount: opts.parsed.mount,
+      liveMounts: opts.parsed.liveMounts,
+      env: opts.parsed.env,
+      guestCwd: opts.parsed.guestCwd,
+      memory: opts.parsed.memory,
+      onLog: opts.quiet.onLog
+    });
+  } catch (err) {
+    handleForkFailure(err, opts.quiet);
+  }
+}
+function handleForkFailure(err, quiet) {
+  quiet.filter?.flush();
+  if (quiet.showHeadlines) {
+    failQuiet(`fork ${quiet.headlineName} failed: ${describeError(err)}`, {
+      buffer: quiet.buffer
+    });
+  }
+  handleError(err);
+}
+function reportForkStarted(fork, opts) {
+  if (!shouldPrintForkStarted(opts)) {
+    return;
+  }
+  process.stderr.write(`forked: ${fork.name ?? "<anonymous>"} (pid ${fork.pid})
 `);
-      if (!outDir) {
-        process.stderr.write(`bundle: ${resolvedOutDir} (rm -rf when the fork exits)
+  printForkBundleHint(opts);
+}
+function shouldPrintForkStarted(opts) {
+  if (opts.quiet.showHeadlines) {
+    return false;
+  }
+  return !opts.json;
+}
+function printForkBundleHint(opts) {
+  if (!opts.parsed.outDir) {
+    process.stderr.write(`bundle: ${opts.resolvedOutDir} (rm -rf when the fork exits)
 `);
-      }
-    }
-    if (detach) {
-      await fork.detach();
-      if (json) {
-        emitJson({
-          schema_version: 1,
-          pid: fork.pid,
-          name: fork.name ?? null,
-          source: "name" in target ? target.name : `pid ${target.pid}`,
-          bundle_dir: resolvedOutDir,
-          ephemeral: !outDir
-        });
-      }
-      return 0;
-    }
-    fork.stdout.pipe(process.stdout);
-    if (!filter) {
-      fork.stderr.pipe(process.stderr);
-    }
-    const restoreStdin = rawModeStdinIfTTY();
-    const cancelHintRepeat = printCtrlDHint();
-    const promptNudge = setTimeout(() => {
-      try {
-        fork.stdin.write("\r");
-      } catch {
-      }
-    }, 1500);
-    promptNudge.unref();
-    let forwardedSignal = null;
-    const onSigint = () => {
-      forwardedSignal = "SIGINT";
-      void fork.kill();
-    };
-    const onSigterm = () => {
-      forwardedSignal = "SIGTERM";
-      void fork.kill();
-    };
-    process.on("SIGINT", onSigint);
-    process.on("SIGTERM", onSigterm);
-    pipeStdinToVm(fork.stdin, () => {
-      process.stderr.write("\nmachinen: Ctrl-D \u2014 stopping VM\n");
-      forwardedSignal = "SIGTERM";
-      void fork.kill();
+  }
+}
+async function detachFork(fork, opts) {
+  await fork.detach();
+  if (opts.json) {
+    emitJson({
+      schema_version: 1,
+      pid: fork.pid,
+      name: fork.name ?? null,
+      source: describeForkSource(opts.target),
+      bundle_dir: opts.resolvedOutDir,
+      ephemeral: !opts.parsed.outDir
+    });
+  }
+  return 0;
+}
+async function runForkAttachedSession(fork, quiet) {
+  const cancelPromptNudge = scheduleForkPromptNudge(fork);
+  try {
+    return await runAttachedVmSession(fork, {
+      filter: quiet.filter,
+      buffer: quiet.buffer,
+      preReadyExitSummary: (code) => `fork ${quiet.headlineName} exited ${code} before reaching ready`
     });
-    try {
-      const { code } = await fork.wait();
-      filter?.flush();
-      if (forwardedSignal === "SIGINT") {
-        return 130;
-      }
-      if (forwardedSignal === "SIGTERM") {
-        return 143;
-      }
-      if (filter && !filter.ready && code != null && code !== 0 && !forwardedSignal) {
-        printDiagnostics(`fork ${forkHeadlineName} exited ${code} before reaching ready`, {
-          buffer
-        });
-      }
-      return code ?? 0;
-    } finally {
-      process.off("SIGINT", onSigint);
-      process.off("SIGTERM", onSigterm);
-      cancelHintRepeat();
-      restoreStdin();
-    }
-  } catch (err) {
-    handleError(err);
   } finally {
-    await vm.detach();
+    cancelPromptNudge();
+  }
+}
+function scheduleForkPromptNudge(fork) {
+  const promptNudge = setTimeout(() => tryWriteForkPromptNudge(fork), 1500);
+  promptNudge.unref();
+  return () => clearTimeout(promptNudge);
+}
+function tryWriteForkPromptNudge(fork) {
+  try {
+    fork.stdin.write("\r");
+  } catch {
   }
 }
 async function cmdAttach(args) {
-  let shell = "/bin/bash -i";
-  let tail;
-  const filtered = [];
+  const opts = parseAttachOptions(args);
+  printAttachTailIfRequested(opts);
+  const vm = await attach(opts.target).catch(handleError);
+  return runAttachedPty(vm, opts.shell);
+}
+function parseAttachOptions(args) {
+  const state = {
+    shell: "/bin/bash -i",
+    tail: void 0,
+    rest: []
+  };
   for (let i = 0; i < args.length; i++) {
-    const a = args[i];
-    if (a === "--shell" || a.startsWith("--shell=")) {
-      const v = a === "--shell" ? args[++i] : a.slice("--shell=".length);
-      if (!v) {
-        die("--shell requires a value");
-      }
-      shell = v;
-    } else if (a === "--tail" || a.startsWith("--tail=")) {
-      let v;
-      if (a === "--tail") {
-        const peek = args[i + 1];
-        if (peek && /^[0-9]+$/.test(peek)) {
-          v = peek;
-          i++;
-        }
-      } else {
-        v = a.slice("--tail=".length);
-      }
-      if (v === void 0) {
-        tail = "all";
-      } else {
-        const n = Number(v);
-        if (!Number.isInteger(n) || n < 0) {
-          die(`--tail: expected a non-negative integer, got '${v}'`);
-        }
-        tail = n;
-      }
-    } else {
-      filtered.push(a);
-    }
+    i = consumeAttachArg(args, i, state);
   }
-  const target = parseTargetFlags(filtered, "attach");
-  if (tail !== void 0) {
-    const entry = lookupEntry(target);
-    if (!entry) {
-      die(`machinen attach: no running VM matched ${describeTarget(target)}`);
-    }
-    if (!entry.bootLogPath) {
-      die(
-        `machinen attach --tail: VM was not booted with --detached, no snapshot exists. Use 'machinen attach' (no --tail) for live console access.`
-      );
-    }
-    printBootLogTail(entry.bootLogPath, tail);
+  return { shell: state.shell, tail: state.tail, target: parseTargetFlags(state.rest, "attach") };
+}
+function consumeAttachArg(args, index, state) {
+  const arg = args[index];
+  const handler = attachArgHandler(arg);
+  if (handler) {
+    return handler(args, index, arg, state);
   }
-  const vm = await attach(target).catch(handleError);
+  state.rest.push(arg);
+  return index;
+}
+var ATTACH_ARG_HANDLERS = [
+  [(arg) => arg === "--shell" || arg.startsWith("--shell="), consumeAttachShell],
+  [(arg) => arg === "--tail" || arg.startsWith("--tail="), consumeAttachTail]
+];
+function attachArgHandler(arg) {
+  return ATTACH_ARG_HANDLERS.find(([matches]) => matches(arg))?.[1];
+}
+function consumeAttachShell(args, index, arg, state) {
+  const value = arg === "--shell" ? args[index + 1] : arg.slice("--shell=".length);
+  if (!value) {
+    die("--shell requires a value");
+  }
+  state.shell = value;
+  return arg === "--shell" ? index + 1 : index;
+}
+function consumeAttachTail(args, index, arg, state) {
+  const { value, nextIndex } = attachTailValue(args, index, arg);
+  state.tail = parseAttachTail(value);
+  return nextIndex;
+}
+function attachTailValue(args, index, arg) {
+  if (arg !== "--tail") {
+    return { value: arg.slice("--tail=".length), nextIndex: index };
+  }
+  const peek = args[index + 1];
+  if (peek && /^[0-9]+$/.test(peek)) {
+    return { value: peek, nextIndex: index + 1 };
+  }
+  return { value: void 0, nextIndex: index };
+}
+function parseAttachTail(value) {
+  if (value === void 0) {
+    return "all";
+  }
+  const n = Number(value);
+  if (!Number.isInteger(n) || n < 0) {
+    die(`--tail: expected a non-negative integer, got '${value}'`);
+  }
+  return n;
+}
+function printAttachTailIfRequested(opts) {
+  if (opts.tail === void 0) {
+    return;
+  }
+  const entry = lookupAttachTailEntry(opts.target);
+  printBootLogTail(entry.bootLogPath, opts.tail);
+}
+function lookupAttachTailEntry(target) {
+  const entry = lookupEntry(target);
+  if (!entry) {
+    die(`machinen attach: no running VM matched ${describeTarget(target)}`);
+  }
+  if (!entry.bootLogPath) {
+    die(
+      `machinen attach --tail: VM was not booted with --detached, no snapshot exists. Use 'machinen attach' (no --tail) for live console access.`
+    );
+  }
+  return entry;
+}
+async function runAttachedPty(vm, shell) {
   if (!process.stdin.isTTY) {
     await vm.detach();
     die("machinen attach: stdin is not a TTY (pipe scripts via `machinen repl` instead)");
@@ -2371,6 +2948,15 @@ function printBootLogTail(path, tail) {
 async function cmdRepl(args) {
   const target = parseTargetFlags(args, "repl");
   const vm = await attach(target).catch(handleError);
+  printReplIntro(vm);
+  try {
+    await runReplLoop(vm);
+    return 0;
+  } finally {
+    await vm.detach();
+  }
+}
+function printReplIntro(vm) {
   process.stderr.write(`repl: ${vm.name ?? `pid ${vm.pid}`}
 `);
   process.stderr.write(
@@ -2380,22 +2966,22 @@ for an interactive shell with job control + TUI support, use:
 Ctrl-D to exit.
 `
   );
-  try {
-    const { createInterface } = await import("readline");
-    const rl = createInterface({ input: process.stdin, output: process.stdout, terminal: false });
-    for await (const line of rl) {
-      if (line.length === 0) {
-        continue;
-      }
-      await vm.execRaw(line, {
-        onStdout: (chunk) => process.stdout.write(chunk),
-        onStderr: (chunk) => process.stderr.write(chunk)
-      });
-    }
-    return 0;
-  } finally {
-    await vm.detach();
+}
+async function runReplLoop(vm) {
+  const { createInterface } = await import("readline");
+  const rl = createInterface({ input: process.stdin, output: process.stdout, terminal: false });
+  for await (const line of rl) {
+    await runReplLine(vm, line);
+  }
+}
+async function runReplLine(vm, line) {
+  if (line.length === 0) {
+    return;
   }
+  await vm.execRaw(line, {
+    onStdout: (chunk) => process.stdout.write(chunk),
+    onStderr: (chunk) => process.stderr.write(chunk)
+  });
 }
 async function cmdAgentContext(args) {
   for (const a of args) {
@@ -2407,86 +2993,103 @@ async function cmdAgentContext(args) {
   return 0;
 }
 async function cmdFeedback(args) {
-  const { json, rest: afterJson } = consumeJsonFlag(args);
-  let listMode = false;
-  const positional = [];
-  for (const a of afterJson) {
-    if (a === "--list") {
-      listMode = true;
-    } else if (a.startsWith("--")) {
-      die(`unknown argument: ${a}`);
-    } else {
-      positional.push(a);
-    }
+  const opts = parseFeedbackOptions(args);
+  if (opts.listMode) {
+    return listFeedback(opts);
   }
-  if (listMode) {
-    if (positional.length > 0) {
-      die("machinen feedback --list takes no positional arguments");
-    }
-    const entries = readFeedback();
-    if (json) {
-      emitJson({ schema_version: 1, entries });
-      return 0;
-    }
-    if (entries.length === 0) {
-      process.stdout.write("(no feedback recorded)\n");
-      return 0;
-    }
-    for (const e of entries) {
-      process.stdout.write(`${e.timestamp}  ${e.text}
-`);
-    }
+  return recordFeedback(opts);
+}
+function parseFeedbackOptions(args) {
+  const { json, rest } = consumeJsonFlag(args);
+  const opts = { json, listMode: false, positional: [] };
+  for (const arg of rest) {
+    consumeFeedbackArg(opts, arg);
+  }
+  return opts;
+}
+function consumeFeedbackArg(opts, arg) {
+  if (arg === "--list") {
+    opts.listMode = true;
+    return;
+  }
+  if (arg.startsWith("--")) {
+    die(`unknown argument: ${arg}`);
+  }
+  opts.positional.push(arg);
+}
+function listFeedback(opts) {
+  if (opts.positional.length > 0) {
+    die("machinen feedback --list takes no positional arguments");
+  }
+  const entries = readFeedback();
+  if (opts.json) {
+    emitJson({ schema_version: 1, entries });
     return 0;
   }
-  if (positional.length === 0) {
+  printFeedbackEntries(entries);
+  return 0;
+}
+function printFeedbackEntries(entries) {
+  if (entries.length === 0) {
+    process.stdout.write("(no feedback recorded)\n");
+    return;
+  }
+  for (const entry of entries) {
+    process.stdout.write(`${entry.timestamp}  ${entry.text}
+`);
+  }
+}
+async function recordFeedback(opts) {
+  if (opts.positional.length === 0) {
     die('usage: machinen feedback "<text>" | machinen feedback --list');
   }
-  const text = positional.join(" ");
   const path = feedbackPath();
-  const entry = {
+  const entry = newFeedbackEntry(opts.positional.join(" "));
+  appendFeedback(entry, path);
+  const upstream = await postUpstream(entry);
+  reportFeedbackRecorded(opts, path, upstream);
+  return 0;
+}
+function newFeedbackEntry(text) {
+  return {
     timestamp: (/* @__PURE__ */ new Date()).toISOString(),
     cli_version: VERSION,
     text
   };
-  appendFeedback(entry, path);
-  const upstream = await postUpstream(entry);
-  if (json) {
-    emitJson({
-      schema_version: 1,
-      recorded: true,
-      path,
-      upstream_status: upstream.status
-    });
-    return 0;
+}
+function reportFeedbackRecorded(opts, path, upstream) {
+  if (opts.json) {
+    emitJson({ schema_version: 1, recorded: true, path, upstream_status: upstream.status });
+    return;
   }
+  process.stdout.write(feedbackRecordedMessage(upstream));
+}
+function feedbackRecordedMessage(upstream) {
   if (upstream.attempted && upstream.status !== null) {
-    process.stdout.write(
-      `feedback recorded locally and sent upstream (status: ${upstream.status})
-`
-    );
-  } else if (upstream.attempted) {
-    process.stdout.write(`feedback recorded locally; upstream POST failed: ${upstream.error}
-`);
-  } else {
-    process.stdout.write("feedback recorded locally (1 entry)\n");
+    return `feedback recorded locally and sent upstream (status: ${upstream.status})
+`;
   }
-  return 0;
+  if (upstream.attempted) {
+    return `feedback recorded locally; upstream POST failed: ${upstream.error}
+`;
+  }
+  return "feedback recorded locally (1 entry)\n";
 }
 async function cmdCompletion(args) {
   const shell = args[0] ?? "bash";
-  if (shell === "bash") {
-    process.stdout.write(BASH_COMPLETION);
-    return 0;
-  }
-  if (shell === "zsh") {
-    process.stdout.write(ZSH_COMPLETION);
-    return 0;
-  }
-  if (shell === "fish") {
-    process.stdout.write(FISH_COMPLETION);
-    return 0;
+  const completion = completionForShell(shell);
+  if (completion === void 0) {
+    die(`unsupported shell: ${shell} (expected bash | zsh | fish)`);
   }
-  die(`unsupported shell: ${shell} (expected bash | zsh | fish)`);
+  process.stdout.write(completion);
+  return 0;
+}
+function completionForShell(shell) {
+  return (/* @__PURE__ */ new Map([
+    ["bash", BASH_COMPLETION],
+    ["zsh", ZSH_COMPLETION],
+    ["fish", FISH_COMPLETION]
+  ])).get(shell);
 }
 function resolveTarget(args, cmd) {
   try {
@@ -2630,6 +3233,8 @@ Usage:
     --env KEY=VALUE                              Set an env var inside the guest.
     --cwd <abs-path>                             Start the guest cmd in this directory
                                                  (must be absolute).
+    --nested                                     Expose arm64 EL2 / /dev/kvm to the guest
+                                                 when the host supports it.
     -p <hostPort>:<guestPort>                    Forward host:hostPort \u2192 guest:guestPort.
 
   machinen restore <snap-dir> [--image <tar.gz>] [--name <name>] [-p ...]
@@ -2664,12 +3269,11 @@ Usage:
                                                  Example:
                                                    machinen exec <name|pid> --tty -- bash -i
   machinen snapshot <name|pid> <out-dir> [--keep-alive]
-                                                 CRIU-snapshot a running VM into <d>.
-                                                 Default: source VM exits as part of the
-                                                 dump. --keep-alive leaves it running
-                                                 (and closes inherited TCP sockets to
-                                                 avoid two live copies racing on shared
-                                                 connection state).
+                                                 Checkpoint a running VM into <d>.
+                                                 Default vmstate snapshots are incremental
+                                                 and non-destructive. CRIU snapshots stay
+                                                 non-incremental; --keep-alive leaves them
+                                                 running and closes inherited TCP sockets.
   machinen fork     <name|pid> [--new-name <n>] [--out-dir <d>] [--tcp-keep] [--detach]
                     [-p ...] [--mount ...] [--mount-live ...] [--env KEY=VALUE]...
                     [--cwd <abs>] [--memory <mib>]
@@ -2736,61 +3340,94 @@ Environment:
   MACHINEN_VMM                             Override the VMM binary path (dev)
   MACHINEN_ASSETS_DIR                      Use base assets from this directory
                                            instead of the cache / GH Releases
+  MACHINEN_GUEST_ARCH                      Guest asset arch: arm64 or amd64
+  MACHINEN_SNAPSHOT_ENGINE                Snapshot engine: vmstate (default),
+                                           criu, or portable (experimental;
+                                           unsupported workload today)
   MACHINEN_REGISTRY_DIR                    Override registry location (default
                                            ~/.machinen/vms)
 
 Cache:
-  ~/.machinen/<tag>/bases/debian-arm64/
+  ~/.machinen/<tag>/bases/debian-arm64/ or debian-amd64/
 `
   );
 }
+var COMMAND_HANDLERS = /* @__PURE__ */ new Map([
+  ["boot", cmdBoot],
+  ["restore", cmdRestore],
+  ["install", cmdInstall],
+  ["list", cmdLs],
+  ["ls", cmdLs],
+  ["ps", cmdLs],
+  ["exec", cmdExec],
+  ["snapshot", cmdSnapshot],
+  ["fork", cmdFork],
+  ["attach", cmdAttach],
+  ["repl", cmdRepl],
+  ["completion", cmdCompletion],
+  ["gc", cmdGc],
+  ["stop", cmdStop],
+  ["feedback", cmdFeedback],
+  ["agent-context", cmdAgentContext]
+]);
 async function main() {
   const [sub, ...rest] = process.argv.slice(2);
-  debug("dispatch sub=%s argc=%d", sub ?? "<empty>", rest.length);
-  if (!sub || sub === "-h" || sub === "--help") {
+  debug("dispatch sub=%s argc=%d", commandLabel(sub), rest.length);
+  const topLevelCode = maybeHandleTopLevelCommand(sub);
+  if (topLevelCode !== void 0) {
+    return topLevelCode;
+  }
+  return dispatchSubcommand(sub, rest);
+}
+function commandLabel(sub) {
+  if (sub === void 0) {
+    return "<empty>";
+  }
+  return sub;
+}
+function maybeHandleTopLevelCommand(sub) {
+  const helpCode = maybePrintTopLevelHelp(sub);
+  if (helpCode !== void 0) {
+    return helpCode;
+  }
+  return maybePrintVersion(sub);
+}
+function dispatchSubcommand(sub, rest) {
+  const handler = COMMAND_HANDLERS.get(sub);
+  if (handler) {
+    return handler(rest);
+  }
+  die(`unknown command: ${sub}
+Run 'machinen --help' for usage.`);
+}
+function maybePrintTopLevelHelp(sub) {
+  if (!sub) {
     printHelp();
-    return sub ? 0 : 1;
+    return 1;
   }
-  if (sub === "--version" || sub === "-v") {
-    process.stdout.write(`${VERSION}
-`);
+  if (sub === "-h") {
+    printHelp();
     return 0;
   }
-  switch (sub) {
-    case "boot":
-      return cmdBoot(rest);
-    case "restore":
-      return cmdRestore(rest);
-    case "install":
-      return cmdInstall(rest);
-    case "list":
-    case "ls":
-    case "ps":
-      return cmdLs(rest);
-    case "exec":
-      return cmdExec(rest);
-    case "snapshot":
-      return cmdSnapshot(rest);
-    case "fork":
-      return cmdFork(rest);
-    case "attach":
-      return cmdAttach(rest);
-    case "repl":
-      return cmdRepl(rest);
-    case "completion":
-      return cmdCompletion(rest);
-    case "gc":
-      return cmdGc(rest);
-    case "stop":
-      return cmdStop(rest);
-    case "feedback":
-      return cmdFeedback(rest);
-    case "agent-context":
-      return cmdAgentContext(rest);
-    default:
-      die(`unknown command: ${sub}
-Run 'machinen --help' for usage.`);
+  if (sub === "--help") {
+    printHelp();
+    return 0;
   }
+  return void 0;
+}
+function maybePrintVersion(sub) {
+  if (sub === "--version") {
+    return printVersion();
+  }
+  if (sub === "-v") {
+    return printVersion();
+  }
+  return void 0;
+}
+function printVersion() {
+  process.stdout.write(`${VERSION}
+`);
+  return 0;
 }
 main().then(
   (code) => process.exit(code),