@evoclock/pi-agentic-driver 0.4.3 → 0.6.0

package/scripts/enforcement/linux_microvm_cutover_pi.js

@@ -2,20 +2,57 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 
 import { createHash, randomBytes } from "node:crypto";
-import { readFileSync } from "node:fs";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawnSync } from "node:child_process";
+import { homedir } from "node:os";
 import { isNativeTuiContext } from "./native_tui_context.js";
 
 export const LINUX_MICROVM_CUTOVER_TOOL = "agentic_linux_microvm_cutover";
 export const LINUX_MICROVM_CUTOVER_SCHEMA = "agentic-driver.linux-microvm-cutover.v1";
+// Containment variant (design section 5): same receipt shape plus one closed
+// `containment` sub-object. v1 consumers stay safe; v2 is required whenever a
+// containment run was requested (fail-closed otherwise).
+export const LINUX_MICROVM_CUTOVER_SCHEMA_V2 = "agentic-driver.linux-microvm-cutover.v2";
+const RECEIPT_SCHEMAS = new Set([LINUX_MICROVM_CUTOVER_SCHEMA, LINUX_MICROVM_CUTOVER_SCHEMA_V2]);
+// Envelope-only relaxation (design sections 5, 6): on the console pty the
+// guest may emit the framed containment envelope after the marker; those
+// lines are parsed separately and never count as unbound output. Everything
+// else remains "unbound output = failure".
+const CONTAINMENT_MARKER_LINE = /^AGENTIC_CONTAINMENT_(BEGIN|END):[A-Za-z0-9._-]+$/;
+export const GUEST_CONTAINMENT_LOG_SCHEMA = "agentic-driver.guest-containment.log.v1";
 const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
 const REMOTE_FIXTURE = join(SCRIPT_DIR, "linux_microvm_remote_fixture.sh");
+const TARGET_EXAMPLE = join(SCRIPT_DIR, "..", "..", "config", "microvm-target.v1.example.json");
+const TARGET_PACKAGE_CONFIG = join(SCRIPT_DIR, "..", "..", "config", "microvm-target.v1.json");
+// The saved target config lives in the Pi coding-agent config directory
+// (PI_CODING_AGENT_DIR when set, otherwise ~/.pi/agent), matching how Pi
+// resolves its own config.
+function resolveTargetUserConfigPath(env = process.env) {
+  const agentDir = env.PI_CODING_AGENT_DIR?.trim()
+    ? join(env.PI_CODING_AGENT_DIR.trim(), "config")
+    : join(homedir(), ".pi", "agent", "config");
+  return join(agentDir, "microvm-target.v1.json");
+}
+const TARGET_USER_CONFIG = resolveTargetUserConfigPath();
+const TARGET_SCHEMA = "agentic-driver.microvm-target.v1";
 const REGISTRATIONS = new WeakSet();
-const PLANNED_ISOLATION_MODES = new Set(["planned", "planned-interactive", "planned-autonomous"]);
+const SWITCH_REGISTRATIONS = new WeakSet();
 const HASH = /^[0-9a-f]{64}$/;
 const MAX_DETAIL = 512;
+// Isolation switch state is per-registration: each registerIsolationSwitchCommands
+// call creates a fresh flag in the registration closure, so a new extension
+// registration (session) starts disabled. It is held in memory only, never
+// read from or written to settings, and never settable by the model (no tool
+// exposes it; only the native TUI enable/disable commands mutate it).
+export function createIsolationSwitch() {
+  let enabled = false;
+  return {
+    get() { return enabled === true; },
+    set(value) { enabled = value === true; },
+  };
+}
 let inFlight = false;
 
 function boundedText(value, fallback = "unknown failure") {
@@ -61,7 +98,109 @@ function fixtureDomainForId(fixtureId) {
   }
   return `agentic-driver-${fixtureId}`;
 }
-function parseFacts(stdout, fixtureId) {
+// --- User-configured trusted target (deny-by-default) -----------------------
+// The user makes one decision: where the microVM runs. Either
+// { "sshTarget": "user@host-or-ip" } for a remote machine, or { "local": true }
+// when this session runs directly on a Linux machine. Nothing else is
+// user-supplied: arch, libvirt URI, and kernel are auto-discovered from the
+// target at probe time (informational, not configured). The model cannot
+// choose or change the target. Read order: the user's own config
+// (~/.pi/pi/config/microvm-target.v1.json) first, then the package-local
+// config/microvm-target.v1.json (shipped as a REPLACE-WITH template).
+const TARGET_FIELDS = new Set(["schema", "sshTarget", "local", "vcpu", "memoryMiB", "jobPayload", "_comment"]);
+// Elastic resource allocation bounds (design section 6.1). User-configured
+// through the target config only; the model-visible tool surface stays closed.
+const VCPU_MIN = 1, VCPU_MAX = 64;
+const MEMORY_MIN = 64, MEMORY_MAX = 1048576;
+function validVcpu(value) { return Number.isInteger(value) && value >= VCPU_MIN && value <= VCPU_MAX; }
+function validMemory(value) { return Number.isInteger(value) && value >= MEMORY_MIN && value <= MEMORY_MAX; }
+export function loadMicroVMTarget(options = {}) {
+  if (options.target && typeof options.target === "object") {
+    return normalizeTarget(options.target);
+  }
+  const paths = [
+    ...(typeof options.targetPath === "string" ? [options.targetPath] : []),
+    ...(typeof options.targetUserConfigPath === "string" ? [options.targetUserConfigPath] : []),
+    // A test/override seam can replace the default user-config location so
+    // tests stay hermetic regardless of the developer's own machine.
+    ...(typeof options.userConfigPath === "string" ? [options.userConfigPath] : [TARGET_USER_CONFIG]),
+    TARGET_PACKAGE_CONFIG,
+  ];
+  for (const path of paths) {
+    try {
+      const parsed = JSON.parse(readFileSync(path, "utf8"));
+      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) continue;
+      if (Object.keys(parsed).some((key) => !TARGET_FIELDS.has(key))) continue;
+      if (parsed.schema !== TARGET_SCHEMA) continue;
+      const normalized = normalizeTarget(parsed);
+      if (!normalized) continue;
+      return Object.freeze({ ...normalized, __path: path });
+    } catch {
+      // Missing or unreadable candidate: fall through to the next path.
+    }
+  }
+  return null;
+}
+
+// Exactly one user decision: sshTarget XOR local:true. Returns the frozen
+// normalized target or null when the decision is absent, ambiguous, or a
+// REPLACE-WITH template placeholder.
+function normalizeTarget(parsed) {
+  const hasSshTarget = typeof parsed.sshTarget === "string" && parsed.sshTarget.trim()
+    && !parsed.sshTarget.includes("REPLACE-WITH-");
+  const hasLocal = parsed.local === true;
+  if (hasSshTarget === hasLocal) return null;
+  // Optional elastic allocation: any invalid value rejects the whole config
+  // (fail-closed) rather than silently falling back.
+  if (parsed.vcpu !== undefined && !validVcpu(parsed.vcpu)) return null;
+  if (parsed.memoryMiB !== undefined && !validMemory(parsed.memoryMiB)) return null;
+  // Containment job payload (design sections 1.3, 3; M6 wiring): a
+  // user-configured job command/script. Present = containment mode; absent =
+  // plain proof mode (backward compatible). Placeholder or invalid shape
+  // rejects the whole config fail-closed. Never model-set.
+  if (parsed.jobPayload !== undefined) {
+    if (typeof parsed.jobPayload !== "string" || !parsed.jobPayload.trim()
+        || parsed.jobPayload.includes("REPLACE-WITH-") || parsed.jobPayload.length > 8192) {
+      return null;
+    }
+  }
+  const extras = {
+    ...(parsed.vcpu !== undefined ? { vcpu: parsed.vcpu } : {}),
+    ...(parsed.memoryMiB !== undefined ? { memoryMiB: parsed.memoryMiB } : {}),
+    ...(parsed.jobPayload !== undefined ? { jobPayload: parsed.jobPayload } : {}),
+  };
+  return Object.freeze(hasSshTarget
+    ? { mode: "ssh", sshTarget: parsed.sshTarget.trim(), ...extras }
+    : { mode: "local", ...extras });
+}
+
+// Shape validation for the user-relayed target parameter (untrusted input).
+// Accepts user@host, an ip (optionally :port), a plain hostname, or "local".
+export function targetArgumentError(value) {
+  const text = typeof value === "string" ? value.trim() : "";
+  if (!text) {
+    return { code: "target-argument-required", detail: "Provide the target: user@host, an ip, or local." };
+  }
+  if (text.includes("REPLACE-WITH-")) {
+    return { code: "target-argument-placeholder", detail: "Placeholder values are not valid targets." };
+  }
+  if (text === "local") return null;
+  // Accepts a bare hostname/ssh-config alias, user@host, user@ip, ip[:port].
+  // ssh config resolves aliases; the string is passed verbatim in fixed argv.
+  const pattern = /^(?:[a-zA-Z0-9._-]+@)?(?:\d{1,3}(?:\.\d{1,3}){3}|[a-zA-Z0-9]([a-zA-Z0-9.-]*[a-zA-Z0-9])?)(?::\d{1,5})?$/;
+  const bareToken = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
+  if (/\s/.test(text) || (!pattern.test(text) && !bareToken.test(text))) {
+    return { code: "target-argument-invalid", detail: `${JSON.stringify(text)} is not a plausible ssh target (alias, user@host, or ip) or the literal 'local'.` };
+  }
+  return null;
+}
+
+function targetNotConfigured() {
+  return denied("blocked", reason("policy", "target-not-configured",
+    "No trusted microVM target is configured. Copy config/microvm-target.v1.example.json to ~/.pi/pi/config/microvm-target.v1.json and set either sshTarget (user@host or ip of the machine that runs the microVM) or local:true (this session runs on a Linux machine). The model cannot choose the target."));
+}
+
+function parseFacts(stdout, fixtureId, target) {
   const values = {};
   for (const line of String(stdout || "").split("\n")) {
     if (!line) continue;
@@ -75,37 +214,76 @@ function parseFacts(stdout, fixtureId) {
     kernel: values.kernel,
     libvirt: values.libvirt,
     qemu: values.qemu,
+    qemuBinaryPath: values.qemu_binary_path,
     fixtureDomain: values.fixture_domain_name,
     fixtureDomainState: values.fixture_domain_state,
+    kvmAccessible: values.kvm_accessible === "yes",
   };
   const domain = fixtureDomainForId(fixtureId);
-  if (facts.host !== "ubuntu-backend" || facts.arch !== "x86_64" || facts.libvirt !== "qemu:///system"
-      || facts.fixtureDomain !== domain || facts.fixtureDomainState !== "absent"
-      || typeof facts.kernel !== "string" || !facts.kernel
-      || typeof facts.qemu !== "string" || !facts.qemu) {
-    throw phaseError("preflight", "facts-unexpected", "fixed host facts or the exact fixture-domain absence check failed");
+  if (facts.fixtureDomain !== domain || facts.fixtureDomainState !== "absent") {
+    throw phaseError("preflight", "facts-unexpected", "the exact fixture-domain absence check failed");
+  }
+  return validateFacts(facts, fixtureId);
+}
+// Honest safety checks over auto-discovered facts: the target must expose
+// KVM, a system-level libvirt connection, and a qemu-system binary matching
+// the discovered architecture. No user-predicted values are involved.
+function validateFacts(facts, _fixtureId) {
+  if (!facts || typeof facts !== "object" || Array.isArray(facts)) {
+    throw phaseError("preflight", "facts-invalid", "trusted host facts are not an object");
+  }
+  if (typeof facts.host !== "string" || !facts.host || typeof facts.arch !== "string" || !facts.arch
+      || typeof facts.kernel !== "string" || !facts.kernel || typeof facts.qemu !== "string" || !facts.qemu
+      || typeof facts.libvirt !== "string" || !facts.libvirt) {
+    throw phaseError("preflight", "facts-unexpected", "the target did not report a complete set of discoverable facts");
+  }
+  if (facts.kvmAccessible !== true) {
+    throw phaseError("preflight", "kvm-unavailable", "the target does not expose an accessible /dev/kvm; hardware virtualization is required");
+  }
+  if (!facts.libvirt.startsWith("qemu:///system")) {
+    throw phaseError("preflight", "libvirt-user-level",
+      `the target libvirt connection is '${facts.libvirt}', not the system driver (qemu:///system); the microVM proof requires the system-level libvirt driver`);
+  }
+  // The decisive evidence is WHICH binary resolved, not an arch token inside
+  // the version string (Debian builds omit it there).
+  if (typeof facts.qemuBinaryPath !== "string" || !facts.qemuBinaryPath.endsWith(`qemu-system-${facts.arch}`)
+      || !/^QEMU/.test(facts.qemu)) {
+    throw phaseError("preflight", "qemu-binary-missing",
+      `the target did not prove a working qemu-system-${facts.arch}: resolved binary '${facts.qemuBinaryPath || "(none)"}', version output '${facts.qemu.slice(0, 80)}'`);
   }
   return facts;
 }
-function sshProbe(execute = run, fixtureId) {
+function sshProbe(execute = run, fixtureId, target) {
   const domain = fixtureDomainForId(fixtureId);
   const quotedDomain = shellQuote(domain);
+  // All technical expectations are auto-discovered from the target itself;
+  // validation checks honest safety properties (KVM, system libvirt driver,
+  // qemu binary for the discovered arch) with no user-predicted values.
   const command = [
-    "set -eu", "test \"$(uname -m)\" = x86_64", "test -r /dev/kvm -a -w /dev/kvm",
-    "test -x /usr/bin/qemu-system-x86_64", "test -x /usr/bin/busybox",
-    "test -x /usr/bin/cpio", "test -x /usr/bin/gzip", "test -x /usr/bin/setfacl",
-    "test -x /usr/bin/getfacl", "test -n \"$(virsh uri)\"",
+    "set -eu",
+    "test -r /dev/kvm -a -w /dev/kvm",
+    "test -x /usr/bin/qemu-system-$(uname -m)",
+    "test -x /usr/bin/busybox", "test -x /usr/bin/cpio", "test -x /usr/bin/gzip",
+    "test -x /usr/bin/setfacl", "test -x /usr/bin/getfacl", "test -n \"$(virsh uri)\"",
     "printf 'host=%s\\n' \"$(hostname)\"", "printf 'arch=%s\\n' \"$(uname -m)\"",
     "printf 'kernel=%s\\n' \"$(uname -r)\"", "printf 'libvirt=%s\\n' \"$(virsh uri)\"",
-    "printf 'qemu=%s\\n' \"$(qemu-system-x86_64 --version | head -1)\"",
+    `printf 'qemu_binary_path=%s\\n' "$(command -v qemu-system-$(uname -m))"`,
+    `printf 'qemu=%s\\n' "$(qemu-system-$(uname -m) --version | head -1)"`,
+    "printf 'kvm_accessible=%s\\n' \"$( test -r /dev/kvm -a -w /dev/kvm && echo yes || echo no )\"",
     `printf 'fixture_domain_name=%s\\n' ${quotedDomain}`,
     `if virsh dominfo ${quotedDomain} >/dev/null 2>&1; then printf 'fixture_domain_state=present\\n'; else names=$(virsh list --all --name); if printf '%s\\n' \"$names\" | grep -F -x -- ${quotedDomain} >/dev/null; then printf 'fixture_domain_state=present\\n'; else match_status=$?; if [ \"$match_status\" -eq 1 ]; then printf 'fixture_domain_state=absent\\n'; else exit 1; fi; fi; fi`,
   ].join("; ");
-  const result = execute("ssh", ["linux-backend", command], { timeout: 30000 });
+  const result = target.mode === "local"
+    ? execute("bash", ["-c", command], { timeout: 30000 })
+    : execute("ssh", [target.sshTarget, command], { timeout: 30000 });
   if (result.code !== 0) {
-    throw phaseError("preflight", "probe-failed", result.stderr || result.error || "fixed linux-backend capability probe failed");
+    const text = result.stderr || result.error || "";
+    if (/\/dev\/kvm/i.test(text)) {
+      throw phaseError("preflight", "kvm-unavailable", "the target does not expose an accessible /dev/kvm; hardware virtualization is required");
+    }
+    throw phaseError("preflight", "probe-failed", text || "configured microVM target capability probe failed");
   }
-  return parseFacts(result.stdout, fixtureId);
+  return parseFacts(result.stdout, fixtureId, target);
 }
 function exactKeys(value, keys, label) {
   if (!value || typeof value !== "object" || Array.isArray(value)
@@ -121,19 +299,7 @@ function requireHash(value, label) {
 function requireBoolean(value, label) {
   if (typeof value !== "boolean") throw phaseError("evidence", "receipt-invalid", `${label} is not boolean evidence`);
 }
-function validateFacts(facts, fixtureId) {
-  const domain = fixtureDomainForId(fixtureId);
-  if (!facts || typeof facts !== "object" || Array.isArray(facts)) {
-    throw phaseError("preflight", "facts-invalid", "trusted host facts are not an object");
-  }
-  if (facts.host !== "ubuntu-backend" || facts.arch !== "x86_64" || facts.libvirt !== "qemu:///system"
-      || facts.fixtureDomain !== domain || facts.fixtureDomainState !== "absent"
-      || typeof facts.kernel !== "string" || !facts.kernel || typeof facts.qemu !== "string" || !facts.qemu) {
-    throw phaseError("preflight", "facts-unexpected", "fixed host facts or the exact fixture-domain absence check failed");
-  }
-  return facts;
-}
-function parseReceipt(stdout) {
+export function parseReceipt(stdout) {
   const candidates = [];
   const unexpected = [];
   for (const line of String(stdout || "").split(/\r?\n/)) {
@@ -147,7 +313,7 @@ function parseReceipt(stdout) {
     }
     try {
       const value = JSON.parse(payload);
-      if (value?.schema === LINUX_MICROVM_CUTOVER_SCHEMA) candidates.push(value);
+      if (value?.schema && RECEIPT_SCHEMAS.has(value.schema)) candidates.push(value);
       else unexpected.push(trimmed);
     } catch {
       unexpected.push(trimmed);
@@ -159,16 +325,84 @@ function parseReceipt(stdout) {
     throw phaseError("evidence", "receipt-missing", detail);
   }
   if (candidates.length !== 1) throw phaseError("evidence", "receipt-ambiguous", "multiple structured microVM receipts were returned");
-  if (unexpected.length) throw phaseError("evidence", "receipt-extra-output", `unbound fixture output: ${unexpected.join(" ")}`);
+  if (unexpected.length) {
+    // Relax receipt-extra-output ONLY for the containment envelope marker
+    // lines, and only when a v2 (containment) receipt is in force. Any other
+    // unbound output still fails closed.
+    const envelopeLines = unexpected.filter((line) => CONTAINMENT_MARKER_LINE.test(line));
+    if (!(envelopeLines.length === unexpected.length
+        && candidates[0]?.schema === LINUX_MICROVM_CUTOVER_SCHEMA_V2)) {
+      throw phaseError("evidence", "receipt-extra-output", `unbound fixture output: ${unexpected.join(" ")}`);
+    }
+  }
   return candidates[0];
 }
-export function validateLinuxMicroVMReceipt(receipt, facts, fixtureId, scriptHash) {
-  exactKeys(receipt, ["schema", "ok", "status", "authorityCreated", "runtimeActivated", "persisted",
-    "identity", "marker", "scriptHash", "initramfsSha256", "teardown", "context"], "receipt");
-  if (receipt.schema !== LINUX_MICROVM_CUTOVER_SCHEMA || receipt.ok !== true || receipt.status !== "VERIFIED"
+function requireCount(value, label) {
+  if (!Number.isInteger(value) || value < 0) {
+    throw phaseError("evidence", "receipt-invalid", `${label} is not a non-negative integer count`);
+  }
+}
+// Closed containment sub-object (design section 5). A verified killswitch
+// trip with a verified log digest is still the success state for the
+// containment proof: the proof is that the killswitch worked.
+function validateContainmentBlock(receipt) {
+  const block = receipt.containment;
+  // Durable kill report (design section 5): the report path is present only
+  // on a tripped killswitch; a clean session must not carry one.
+  const blockKeys = ["schema", "taxonomySha256", "logSha256", "events", "denials", "probes", "concealmentIndex", "histogram", "killswitch"];
+  const trippedEarly = block?.killswitch?.tripped === true;
+  if (trippedEarly) blockKeys.push("killReportPath");
+  exactKeys(block, blockKeys, "containment block");
+  if (block.schema !== GUEST_CONTAINMENT_LOG_SCHEMA) {
+    throw phaseError("evidence", "receipt-invalid", "containment log schema is unexpected");
+  }
+  requireHash(block.taxonomySha256, "containment taxonomy digest");
+  requireHash(block.logSha256, "containment log digest");
+  requireCount(block.events, "containment event count");
+  requireCount(block.denials, "containment denial count");
+  requireCount(block.probes, "containment probe count");
+  requireCount(block.concealmentIndex, "containment concealment index");
+  // Compact class histogram (design section 4): class -> non-negative count.
+  if (!block.histogram || typeof block.histogram !== "object" || Array.isArray(block.histogram)
+      || Object.values(block.histogram).some((count) => !Number.isInteger(count) || count < 0)) {
+    throw phaseError("evidence", "receipt-invalid", "containment histogram is not a class-count map");
+  }
+  exactKeys(block.killswitch, ["tripped", "rule", "class", "tier", "guestPoweroff", "final"], "containment killswitch");
+  requireBoolean(block.killswitch.tripped, "killswitch tripped");
+  if (block.killswitch.guestPoweroff !== true || block.killswitch.final !== true) {
+    throw phaseError("evidence", "receipt-invalid", "killswitch guest poweroff or final flag is unexpected");
+  }
+  if (block.killswitch.tripped) {
+    if (typeof block.killswitch.rule !== "string" || !block.killswitch.rule
+        || typeof block.killswitch.class !== "string" || !block.killswitch.class
+        || typeof block.killswitch.tier !== "string" || !block.killswitch.tier) {
+      throw phaseError("evidence", "receipt-invalid", "killswitch tripped without rule, class, or tier");
+    }
+    if (typeof block.killReportPath !== "string" || !block.killReportPath.endsWith("kill-report.json")) {
+      throw phaseError("evidence", "receipt-invalid", "killswitch trip without a kill report path");
+    }
+  } else if (block.killswitch.rule !== null || block.killswitch.class !== null || block.killswitch.tier !== null) {
+    throw phaseError("evidence", "receipt-invalid", "killswitch rule, class, and tier must be null when not tripped");
+  }
+  return block;
+}
+export function validateLinuxMicroVMReceipt(receipt, facts, fixtureId, scriptHash, options = {}) {
+  const containmentRun = options.containment === true;
+  // Fail-closed: a containment run without the v2 receipt and its evidence is
+  // containment-evidence-missing, never silently downgraded.
+  if (containmentRun && receipt.schema !== LINUX_MICROVM_CUTOVER_SCHEMA_V2) {
+    throw phaseError("evidence", "containment-evidence-missing",
+      "containment run returned no v2 containment receipt");
+  }
+  const expectedKeys = ["schema", "ok", "status", "authorityCreated", "runtimeActivated", "persisted",
+    "identity", "marker", "scriptHash", "initramfsSha256", "teardown", "context"];
+  if (containmentRun || receipt.schema === LINUX_MICROVM_CUTOVER_SCHEMA_V2) expectedKeys.push("containment");
+  exactKeys(receipt, expectedKeys, "receipt");
+  if (!RECEIPT_SCHEMAS.has(receipt.schema) || receipt.ok !== true || receipt.status !== "VERIFIED"
       || receipt.authorityCreated !== false || receipt.runtimeActivated !== false || receipt.persisted !== false) {
     throw phaseError("evidence", "receipt-invalid", "receipt status or non-authorizing flags are unexpected");
   }
+  if (receipt.schema === LINUX_MICROVM_CUTOVER_SCHEMA_V2) validateContainmentBlock(receipt);
   const domain = fixtureDomainForId(fixtureId);
   exactKeys(receipt.identity, ["remoteHost", "fixtureId", "domain"], "receipt identity");
   if (receipt.identity.remoteHost !== facts.host || receipt.identity.fixtureId !== fixtureId || receipt.identity.domain !== domain) {
@@ -220,6 +454,16 @@ export function validateLinuxMicroVMReceipt(receipt, facts, fixtureId, scriptHas
   }
   return receipt;
 }
+// Elastic resource allocation (design section 6.1): user-configured through
+// the target config only (never model-set); the model-visible tool surface
+// stays closed. Defaults are the existing proof values.
+function resourceAllocation(target) {
+  return { vcpu: target?.vcpu ?? 1, memoryMiB: target?.memoryMiB ?? 128 };
+}
+function resourceLine(target) {
+  const allocation = resourceAllocation(target);
+  return `${allocation.vcpu} vCPU, ${allocation.memoryMiB} MiB, BusyBox initramfs, no disk, network, host share, credentials, GPU, or serving access.`;
+}
 function normalizedForwardedStderr(result, fallbackPhase, fallbackCode, fallbackDetail) {
   const text = String(result?.stderr || "");
   const lines = text.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
@@ -235,17 +479,93 @@ function normalizedForwardedStderr(result, fallbackPhase, fallbackCode, fallback
     primary?.[2] || (cleanup.length ? "cleanup-failed" : fallbackCode), details.join("; "));
 }
 
+// Containment run mode (design sections 1.3, 5, 6; M6 wired): the
+// user-configured `jobPayload` in the target config is the only source of
+// containment mode — present payload = containment run (v2 receipt with the
+// containment block), absent = plain proof mode (v1, backward compatible).
+// The model cannot set or alter it: the tool schema stays closed (target
+// relay only) and the payload never crosses the model-visible surface.
+function payloadRedacted(payload) {
+  return boundedText(String(payload).replace(/\s+/g, " ").trim(), "payload").slice(0, 160);
+}
 export async function runLinuxMicroVMCutover(context, options = {}) {
-  if (!PLANNED_ISOLATION_MODES.has(options.workMode)) {
-    return denied("blocked", reason("policy", "planned-isolation-required", "Linux microVM execution is reserved for planned or automated work."));
+  // Session-scoped user switch: only the explicit enable command can set this
+  // flag in memory; it never persists to settings and the model cannot set it.
+  if (options.isolationSwitch?.get() !== true) {
+    return denied("blocked", reason("policy", "isolation-not-enabled",
+      "Isolation activation is not enabled in this session. Run the agentic-isolation-enable command in the Pi TUI."));
   }
-  const isolationEnabled = options.isolationEnabled ?? options.runtime?.isolationEnabled;
-  if (isolationEnabled !== true) {
-    return denied("blocked", reason("policy", "planned-isolation-not-enabled", "The planned isolation execution path is not enabled yet."));
+  // Target selection: the only way user intent reaches setup is the optional
+  // `target` parameter, relayed by the agent from the user's words. It is
+  // untrusted: nothing is written or run without the user's native
+  // confirmation dialog naming the target explicitly.
+  const targetParam = typeof options.target === "string" ? options.target.trim() : "";
+  if (targetParam) {
+    const shapeError = targetArgumentError(targetParam);
+    if (shapeError) return denied("denied", reason("input", shapeError.code, shapeError.detail));
+    // Headless setups are refused: only pre-configured targets run.
+    if (!isNativeTuiContext(context) || typeof context?.ui?.confirm !== "function") {
+      return denied("blocked", reason("policy", "native-tui-required",
+        "Configuring a new microVM target requires the interactive Pi TUI; headless sessions may only use a pre-configured target."));
+    }
+    const writePath = options.targetUserConfigPath?.trim() || TARGET_USER_CONFIG;
+    let confirmed;
+    try {
+      confirmed = await context.ui.confirm("Use this microVM host?", [
+        `Use ${targetParam === "local" ? "THIS machine (local)" : targetParam} as the microVM host? This saves it to your Pi config.`,
+        `Config file: ${writePath}`,
+        "The model relayed your words; this confirmation is what authorizes the choice.",
+      ].join("\n"));
+    } catch (error) {
+      return denied("blocked", reason("confirmation", "confirmation-failed", `Native confirmation failed: ${error.message}`));
+    }
+    if (confirmed !== true) {
+      return denied("stopped", reason("confirmation", "not-granted", "No target was saved; native confirmation was not granted."));
+    }
+    // Read-modify-write: the confirmation authorizes changing WHERE the
+    // microVM runs — nothing else. A fresh narrow object here would silently
+    // drop the user's other configured fields (jobPayload above all: a
+    // re-save stripped it and flipped the next run to plain proof mode).
+    // Preserve every schema field the existing config carries; the decision
+    // under confirmation replaces exactly one of sshTarget/local. Preserved
+    // fields are still fully validated fail-closed by loadMicroVMTarget.
+    let existing = {};
+    try {
+      const parsed = JSON.parse(readFileSync(writePath, "utf8"));
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) existing = parsed;
+    } catch {
+      // Absent or unreadable config: fresh write below.
+    }
+    const saved = { ...existing, schema: TARGET_SCHEMA };
+    if (targetParam === "local") {
+      delete saved.sshTarget;
+      saved.local = true;
+    } else {
+      delete saved.local;
+      saved.sshTarget = targetParam;
+    }
+    try {
+      mkdirSync(dirname(writePath), { recursive: true });
+      writeFileSync(writePath, `${JSON.stringify(saved, null, 2)}\n`);
+    } catch (error) {
+      return denied("blocked", reason("policy", "target-write-failed", `Could not write ${writePath}: ${error.message}`));
+    }
   }
-  if (!isNativeTuiContext(context) || typeof context?.ui?.confirm !== "function") {
-    return denied("blocked", reason("policy", "native-tui-required", "Open the Linux microVM cutover in the interactive Pi TUI."));
+  // Saved config (possibly just written above) drives the run; deny-by-default
+  // when neither a target param nor saved config exists.
+  const target = loadMicroVMTarget({
+    ...options,
+    ...(options.userConfigPath ? {} : { userConfigPath: options.userConfigPath }),
+  });
+  if (!target) {
+    return denied("blocked", reason("policy", "target-not-configured",
+      "No microVM target is configured. Ask the user which machine the microVM should run on and pass it as the `target` parameter (user@host, ip, or local)."));
   }
+  if (!isNativeTuiContext(context)) {
+    return denied("blocked", reason("policy", "native-tui-required",
+      "Open the Linux microVM cutover in the interactive Pi TUI; headless runs are denied."));
+  }
+  const containmentRun = typeof target.jobPayload === "string";
   if (inFlight) return denied("denied", reason("execution", "already-active", "another Linux microVM cutover is active in this host session"));
 
   const fixtureId = `microvm-${randomBytes(12).toString("hex")}`;
@@ -259,18 +579,24 @@ export async function runLinuxMicroVMCutover(context, options = {}) {
     return denied("denied", reasonFromError(error, "payload", "payload-read-failed"));
   }
   const execute = options.execute || run;
-  const observe = options.observeFacts || ((executeArg, id) => sshProbe(executeArg, id));
+  const observe = options.observeFacts || ((executeArg, id) => sshProbe(executeArg, id, target));
   let facts;
   try { facts = validateFacts(observe(execute, fixtureId), fixtureId); }
   catch (error) { return denied("denied", reasonFromError(error, "preflight", "facts-observation-failed")); }
   const body = [
-    "Run one live transient QEMU/KVM microVM proof on linux-backend?",
-    `Remote host: ${facts.host} (${facts.arch}, kernel ${facts.kernel})`,
+    "Run one live transient QEMU/KVM microVM proof on the configured trusted target?",
+    `Target: ${target.mode === "local" ? "this machine (local)" : target.sshTarget} — discovered host: ${facts.host} (${facts.arch}, kernel ${facts.kernel})`,
     `Backend: ${facts.libvirt}; ${facts.qemu}`,
     `Fixture: ${fixtureId}; domain: ${fixtureDomain} (preflight absent)`,
     `Versioned fixture SHA-256: ${scriptHash}`,
     "Writes: one generated fixture below ~/agentic-driver-state/cutover-fixtures/microvm/.",
-    "Guest: 1 vCPU, 128 MiB, BusyBox initramfs, no disk, network, host share, credentials, GPU, or serving access.",
+    ...(containmentRun
+      ? [
+          "Guest runs a deny-by-default containment monitor; any kill decision kills the guest session and tears down the VM.",
+          `Guest job payload (user-configured): ${payloadRedacted(target.jobPayload)}`,
+        ]
+      : []),
+    `Guest: ${resourceLine(target)}`,
     "A temporary traverse-only ACL for libvirt-qemu is added to the remote home directory and the exact prior ACL is restored after exit or failure.",
     "The transient domain prints one marker, powers off, and must disappear from libvirt.",
     "No install, download, repository mutation, runtime authority, staging, commit, or push.",
@@ -288,12 +614,23 @@ export async function runLinuxMicroVMCutover(context, options = {}) {
   }
   inFlight = true;
   try {
-    const result = execute("ssh", ["linux-backend", "bash", "-s", "--", fixtureId, scriptHash], { input: script, timeout: 180000 });
+    const allocation = resourceAllocation(target);
+    const fixtureArgs = [fixtureId, scriptHash, String(allocation.vcpu), String(allocation.memoryMiB)];
+    // The payload travels base64-encoded: ssh concatenates argv into one
+    // command string parsed by the remote login shell, so a raw payload
+    // (newlines, quotes, semicolons are allowed by design) would be word-
+    // split, reinterpreted, or injected as remote commands. Base64 is
+    // shell-safe (no whitespace/metacharacters) and round-trips exactly;
+    // the fixture decodes and validates it. Local mode benefits identically.
+    if (containmentRun) fixtureArgs.push(Buffer.from(target.jobPayload, "utf8").toString("base64"));
+    const result = target.mode === "local"
+      ? execute("bash", ["-c", "bash -s -- " + fixtureArgs.map(shellQuote).join(" ")], { input: script, timeout: 180000 })
+      : execute("ssh", [target.sshTarget, "bash", "-s", "--", ...fixtureArgs], { input: script, timeout: 180000 });
     if (!result || result.code !== 0) {
       return denied("blocked", normalizedForwardedStderr(result, "fixture", "execution-failed", "fixed microVM fixture failed"));
     }
     const receipt = parseReceipt(result.stdout);
-    return validateLinuxMicroVMReceipt(receipt, facts, fixtureId, scriptHash);
+    return validateLinuxMicroVMReceipt(receipt, facts, fixtureId, scriptHash, { containment: containmentRun });
   } catch (error) {
     return denied("blocked", reasonFromError(error, "execution", "fixture-failed"));
   } finally { inFlight = false; }
@@ -307,22 +644,141 @@ function commandArgumentsPresent(args) {
 export function registerLinuxMicroVMCutoverInterface(pi, options = {}) {
   if (typeof pi?.registerTool !== "function" || REGISTRATIONS.has(pi)) return;
   REGISTRATIONS.add(pi);
+  // Prominent outcome presentation. The first line of the tool output is a
+  // concise final status (VERIFIED / DENIED / STOPPED / BLOCKED) with fixture
+  // id and one-line evidence or reason summary; the full JSON receipt follows
+  // unchanged. When the interactive TUI exposes the notify surface, the same
+  // status is raised as a fire-and-forget notification.
+  const outcomeLine = (value) => {
+    if (value?.ok === true && value?.status === "VERIFIED") {
+      return `MICROVM CUTOVER: VERIFIED — fixture ${value.identity?.fixtureId ?? "unknown"} on ${value.identity?.remoteHost ?? "unknown host"}; domain ${value.identity?.domain ?? "?"} transient+gone, teardown proofed, isolation context closed.`;
+    }
+    const status = String(value?.status ?? "DENIED").toUpperCase();
+    const code = value?.reason?.code ?? value?.code ?? "unknown";
+    const detail = value?.reason?.detail ?? value?.error ?? "";
+    return `MICROVM CUTOVER: ${status} — reason ${code}${detail ? `: ${detail}` : ""}`;
+  };
+  const notifyOutcome = (context, value) => {
+    const notify = context?.ui?.notify;
+    if (typeof notify !== "function") return;
+    const line = outcomeLine(value);
+    notify(line, value?.ok === true ? "info" : value?.status === "stopped" ? "warning" : "error");
+  };
   const execute = async (_id, params, _signal, _update, context) => {
-    const value = params && Object.keys(params).length
-      ? denied("denied", reason("input", "model-parameters-not-allowed", "Linux microVM cutover accepts no model parameters"))
+    const closedParams = params && typeof params === "object" && !Array.isArray(params)
+      ? Object.keys(params).filter((key) => key !== "target")
+      : [];
+    const value = closedParams.length
+      ? denied("denied", reason("input", "model-parameters-not-allowed", "Linux microVM cutover accepts only the optional target parameter"))
       : await runLinuxMicroVMCutover(context, {
           ...options,
-          workMode: options.runtime?.workMode,
-          isolationEnabled: options.runtime?.isolationEnabled,
+          ...(typeof params?.target === "string" ? { target: params.target } : {}),
         });
-    return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }], details: value };
+    // M2 (design section 5): a killswitch trip raises an error-severity
+    // notification naming the rule, class, and severity tier.
+    const killswitch = value?.containment?.killswitch;
+    if (value?.ok === true && killswitch?.tripped === true && typeof context?.ui?.notify === "function") {
+      context.ui.notify(
+        `MICROVM CONTAINMENT: KILLSWITCH TRIPPED — rule ${killswitch.rule}, class ${killswitch.class}, tier ${killswitch.tier}; guest session killed and VM torn down. Kill report: ${value?.containment?.killReportPath ?? "(unavailable)"}`,
+        "error",
+      );
+    }
+    notifyOutcome(context, value);
+    return { content: [{ type: "text", text: `${outcomeLine(value)}\n${JSON.stringify(value, null, 2)}` }], details: value };
   };
   pi.registerTool({ name: LINUX_MICROVM_CUTOVER_TOOL, label: "Verify Linux microVM",
-    description: "Run one native-confirmed transient QEMU/KVM microVM proof on linux-backend.",
-    parameters: { type: "object", additionalProperties: false, properties: {} }, execute });
+    description: "Run one native-confirmed transient QEMU/KVM microVM proof on the trusted target. The optional target parameter (user@host, ip, or local) relays the user's machine choice; saving a new target requires the user's native confirmation. Requires the session isolation switch.",
+    parameters: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        target: { type: "string", maxLength: 255, description: "Where the microVM runs: user@host, an ip, or the literal local. Relays the user's explicit choice; a new target is saved only after the user's native confirmation." },
+      },
+    }, execute });
   pi.registerCommand?.("agentic-linux-microvm-cutover", { description: "Run the native-confirmed Linux microVM proof",
     handler: async (args, context) => commandArgumentsPresent(args)
       ? denied("denied", reason("input", "command-arguments-not-allowed", "Linux microVM cutover accepts no command arguments"))
       : (await execute("command", {}, undefined, undefined, context)).details });
 }
+
+// Session-scoped isolation switch commands. The flag lives only in this
+// module's memory: the model has no tool to set or read it, it is never
+// written to settings, and each command itself requires a native TUI
+// confirmation. Disabling always succeeds once confirmed; enabling requires
+// the interactive Pi TUI.
+const ISOLATION_ENABLE_COMMAND = "agentic-isolation-enable";
+const ISOLATION_DISABLE_COMMAND = "agentic-isolation-disable";
+export const ISOLATION_COMMANDS = { enable: ISOLATION_ENABLE_COMMAND, disable: ISOLATION_DISABLE_COMMAND };
+
+export function registerIsolationSwitchCommands(pi, options = {}) {
+  if (typeof pi?.registerCommand !== "function" || SWITCH_REGISTRATIONS.has(pi)) return;
+  SWITCH_REGISTRATIONS.add(pi);
+  // Fresh, registration-scoped switch state: a new registration starts disabled.
+  const isolationSwitch = options.isolationSwitch ?? createIsolationSwitch();
+  const switchNotice = () => isolationSwitch.get()
+    ? "Isolation activation is ENABLED for this session only. It does not persist to settings and resets when the session ends."
+    : "Isolation activation is DISABLED. No microVM proof can run in this session until it is enabled.";
+  const switchResult = (ok, status, code, detail) => ({
+    schema: LINUX_MICROVM_CUTOVER_SCHEMA, ok, status,
+    reason: ok ? undefined : reason("policy", code, detail),
+    isolationEnabled: isolationSwitch.get(),
+    persisted: false,
+  });
+  const rejectArguments = () => switchResult(false, "denied", "command-arguments-not-allowed",
+    "The isolation switch commands accept no command arguments.");
+  pi.registerCommand(ISOLATION_ENABLE_COMMAND, {
+    description: "Enable the Linux microVM isolation switch for this session (native confirmation required)",
+    handler: async (args, context) => {
+      if (commandArgumentsPresent(args)) return rejectArguments();
+      if (!isNativeTuiContext(context) || typeof context?.ui?.confirm !== "function") {
+        return switchResult(false, "blocked", "native-tui-required",
+          "Open the interactive Pi TUI to enable isolation; headless sessions cannot enable it.");
+      }
+      if (isolationSwitch.get()) {
+        return switchResult(true, "ALREADY_ENABLED", "", "");
+      }
+      let confirmed;
+      try {
+        confirmed = await context.ui.confirm("Enable Linux microVM isolation", [
+          "Enable the isolation-activation switch for this session?",
+          switchNotice(),
+          "Effect: the agentic_linux_microvm_cutover tool may run one native-confirmed transient QEMU/KVM microVM proof on the configured trusted target per invocation.",
+          "The switch is session-scoped: it never persists to settings and the model cannot change it.",
+        ].join("\n"));
+      } catch (error) {
+        return switchResult(false, "blocked", "confirmation-failed", `Native confirmation failed: ${error.message}`);
+      }
+      if (confirmed !== true) {
+        return switchResult(false, "stopped", "not-granted", "Isolation activation was not enabled; native confirmation was not granted.");
+      }
+      isolationSwitch.set(true);
+      return switchResult(true, "ENABLED", "", "");
+    },
+  });
+  pi.registerCommand(ISOLATION_DISABLE_COMMAND, {
+    description: "Disable the Linux microVM isolation switch for this session (native confirmation required)",
+    handler: async (args, context) => {
+      if (commandArgumentsPresent(args)) return rejectArguments();
+      if (!isNativeTuiContext(context) || typeof context?.ui?.confirm !== "function") {
+        return switchResult(false, "blocked", "native-tui-required",
+          "Open the interactive Pi TUI to disable isolation; headless sessions cannot change the switch.");
+      }
+      let confirmed;
+      try {
+        confirmed = await context.ui.confirm("Disable Linux microVM isolation", [
+          "Disable the isolation-activation switch for this session?",
+          switchNotice(),
+        ].join("\n"));
+      } catch (error) {
+        return switchResult(false, "blocked", "confirmation-failed", `Native confirmation failed: ${error.message}`);
+      }
+      if (confirmed !== true) {
+        return switchResult(false, "stopped", "not-granted", "Isolation activation remains enabled; native confirmation was not granted.");
+      }
+      isolationSwitch.set(false);
+      return switchResult(true, "DISABLED", "", "");
+    },
+  });
+  return isolationSwitch;
+}
 export default registerLinuxMicroVMCutoverInterface;