@evoclock/pi-agentic-driver 0.5.0 → 0.7.0

package/scripts/enforcement/herdr_communication_pi.js

@@ -131,6 +131,7 @@ function errorResult(operation, error) {
     code: known.code,
     reason: known.message,
     ...(known.diagnostic ? { diagnostic: known.diagnostic } : {}),
+    ...(known.deliveryState ? { deliveryState: known.deliveryState } : {}),
     nonAuthorizing: true,
     authorityCreated: false,
   };
@@ -676,7 +677,7 @@ async function invokeHerdr(action, params, context, options = {}, signal) {
         timeoutMs: processTimeout,
         maxOutputBytes: MAX_PROCESS_OUTPUT_BYTES,
       });
-    } catch {
+    } catch (error) {
       return { internalFailure: "spawn_error" };
     }
     raw = await awaitBounded(pending, processTimeout, signal);
@@ -992,15 +993,15 @@ function allMarkerOccurrences(text, standaloneOnly = false, additionalPair = und
   return occurrences.sort((left, right) => left.index - right.index || left.end - right.end);
 }
 
-function promptContractRange(text, marker, occurrenceIndex) {
+function promptContractRange(text, marker, occurrenceIndex, { boundEnd = false } = {}) {
   const anchor = text.lastIndexOf(REPORT_CONTRACT_LINE, occurrenceIndex);
   if (anchor < 0) return undefined;
   const markerStart = anchor + REPORT_CONTRACT_LINE.length;
   const open = text.indexOf(marker.open, markerStart);
   if (open < 0 || open > occurrenceIndex) return undefined;
   const close = text.indexOf(marker.close, open + marker.open.length);
-  if (close < occurrenceIndex) return undefined;
   const end = close + marker.close.length;
+  if (boundEnd && end > occurrenceIndex) return undefined;
   if (Buffer.byteLength(text.slice(anchor, end), "utf8") > MAX_PROMPT_CONTRACT_ECHO_BYTES) return undefined;
   if (!/^\s*$/.test(text.slice(markerStart, open)) || !/^\s*$/.test(text.slice(open + marker.open.length, close))) return undefined;
   const otherMarkers = [...new Set(Object.values(REPORT_MARKERS)
@@ -1053,16 +1054,11 @@ function extractLatestReport(text, role) {
   }
   const prior = relevant.at(-3);
   if (prior?.marker === marker.open) {
-    // `recent-unwrapped` can retain one older unmatched opening before the
-    // newer pair. Ignore that prefix only when it is preceded by terminal
-    // history; an opening at the window boundary remains fail-closed so a
-    // nested/duplicate opening cannot be reclassified as stale history.
-    const prefixOpenCount = relevant.slice(0, -2).filter((item) => item.marker === marker.open).length;
-    const historicalPrefix = prefixOpenCount === 1
-      && text.slice(0, prior.index).trim().length > 0;
-    if (!historicalPrefix) {
-      throw communicationError("report_duplicate_open", "the latest role report contains a duplicate or nested opening marker");
-    }
+    // A duplicate or nested opening before the latest pair is never
+    // reclassified as stale history: stale unmatched opens are surfaced as
+    // bounded evidence in the prompt flow only, and a plain read stays
+    // fail-closed.
+    throw communicationError("report_duplicate_open", "the latest role report contains a duplicate or nested opening marker");
   }
   const rawBody = text.slice(open.end, close.index);
   const nestedMarkers = allMarkerOccurrences(rawBody, false, marker)
@@ -1083,6 +1079,76 @@ function extractLatestReport(text, role) {
   return body;
 }
 
+function lineStarts(text) {
+  const starts = [0];
+  for (let index = 0; index < text.length; index += 1) {
+    if (text[index] === "\n") starts.push(index + 1);
+  }
+  return starts;
+}
+
+function provenancedReportSegment(pre, post, sentPrompt, role) {
+  const marker = reportMarkersForRole(role);
+  const preLines = pre.split("\n");
+  const starts = lineStarts(post);
+  const candidates = [];
+  let from = 0;
+  while (from <= post.length) {
+    const start = post.indexOf(sentPrompt, from);
+    if (start < 0) break;
+    from = start + 1;
+    if (!starts.includes(start)) continue;
+    const range = marker && promptContractRange(post, marker, start + sentPrompt.length, { boundEnd: true });
+    if (!range || range.end !== start + sentPrompt.length) continue;
+    const prefix = post.slice(0, start);
+    const prefixLines = prefix.endsWith("\n") ? prefix.slice(0, -1).split("\n") : prefix.split("\n");
+    const shared = Math.min(prefixLines.length, preLines.length);
+    if (shared < 1) continue;
+    const preFirstLine = preLines[0];
+    const prefixContainsPreSnapshot = prefixLines.some((line) => line === preFirstLine);
+    const preTailMatchesPrefix = preLines.slice(-shared).every((line, index) => line === prefixLines[prefixLines.length - shared + index]);
+    if (prefixContainsPreSnapshot || preTailMatchesPrefix) {
+      candidates.push({ start, end: range.end, aligned: shared });
+    }
+  }
+  if (!candidates.length) throw communicationError("report_scope_unavailable", "the prompted exchange could not be proven from terminal history");
+  const max = Math.max(...candidates.map((candidate) => candidate.aligned));
+  const winners = candidates.filter((candidate) => candidate.aligned === max);
+  if (winners.length !== 1) throw communicationError("report_scope_unavailable", "the prompted exchange boundary is ambiguous");
+  return winners[0];
+}
+
+function extractReportFromSegment(text, role, fromIndex = 0, fullText = text) {
+  const marker = reportMarkersForRole(role);
+  const segment = text.slice(fromIndex);
+  const relevant = allMarkerOccurrences(segment, true, marker)
+    .filter((item) => (item.marker === marker.open || item.marker === marker.close)
+      && !isPromptContractMarker(fullText, { index: item.index + fromIndex, end: item.end + fromIndex }, marker));
+  if (!relevant.length) throw communicationError("report_missing", "no complete role-specific report was observed");
+  const close = relevant.at(-1);
+  if (close.marker === marker.open) {
+    throw communicationError("report_truncated", "the latest role report has no closing marker");
+  }
+  const open = relevant.at(-2);
+  if (!open || open.marker !== marker.open) {
+    throw communicationError("report_reversed", "the latest role report has no matching opening marker");
+  }
+  const rawBody = segment.slice(open.end, close.index);
+  const nestedMarkers = allMarkerOccurrences(rawBody, false, marker)
+    .filter((item) => !isPromptContractMarker(fullText, { index: open.end + item.index, end: open.end + item.end }, marker));
+  if (nestedMarkers.length) {
+    throw communicationError("report_nested", "the latest role report contains a nested report marker");
+  }
+  const body = removePromptContractEchoes(rawBody, marker)
+    .replace(/^[ \t]*\r?\n/, "")
+    .replace(/\r?\n[ \t]*$/, "");
+  if (!body.trim()) throw communicationError("report_empty", "the latest role report is empty");
+  if (Buffer.byteLength(body, "utf8") > MAX_REPORT_BYTES) {
+    throw communicationError("report_oversized", "the latest role report exceeds the bounded report size");
+  }
+  return body;
+}
+
 export function extractLatestHerdrReport(text, role) {
   requireRole(role);
   if (typeof text !== "string") throw communicationError("report_missing", "report history is not text");
@@ -1119,7 +1185,36 @@ export async function executeHerdrCommunication(params, context, options = {}, s
       // change before it accepts settlement. A separate wait command can race
       // and match the role's pre-existing idle state, reading the empty marker
       // template before the new response exists.
-      const prompted = await invokeHerdr(operation, request, context, options, signal);
+      let pre;
+      try {
+        pre = readText(await invokeHerdr("read", { action: "read", role }, context, options, signal));
+      } catch {
+        throw communicationError("report_scope_unavailable", "the pre-prompt terminal snapshot is unavailable");
+      }
+      const revalidated = await invokeHerdr("get", { action: "get", role }, context, options, signal);
+      publicAgentObservation(extractAgent(revalidated, "agent_info"), role, repositories, { requirePromptable: true });
+      let prompted;
+      try {
+        prompted = await invokeHerdr(operation, request, context, options, signal);
+      } catch (error) {
+        if (!(error instanceof HerdrCommunicationError) || error.code !== "prompt_stalled") throw error;
+        try {
+          const recovered = await invokeHerdr("get", { action: "get", role }, context, options, signal);
+          const recovery = publicAgentObservation(extractAgent(recovered, "agent_info"), role, repositories);
+          const recoveredSeq = stateChangeSeq(recovered);
+          const initialSeq = stateChangeSeq(current);
+          if (recovery.status === "idle" && initialSeq !== undefined && recoveredSeq !== undefined && recoveredSeq !== initialSeq) throw error;
+          const unknown = communicationError("prompt_delivery_unknown", "prompt delivery is unknown; the adapter did not retry, and only the caller may issue a new explicit prompt");
+          unknown.deliveryState = "unknown";
+          throw unknown;
+        } catch (recoveryError) {
+          if (recoveryError instanceof HerdrCommunicationError && ["prompt_stalled", "prompt_delivery_unknown"].includes(recoveryError.code)) throw recoveryError;
+          const unknown = communicationError("prompt_delivery_unknown", "prompt delivery is unknown; the adapter did not retry, and only the caller may issue a new explicit prompt");
+          unknown.deliveryState = "unknown";
+          unknown.diagnostic = boundedFailureDiagnostic(recoveryError?.message);
+          throw unknown;
+        }
+      }
       const observation = publicAgentObservation(extractAgent(prompted, "agent_prompted"), role, repositories);
       const waitedStatus = observation.status;
       if (!WAIT_STATUSES.has(waitedStatus)) {
@@ -1129,7 +1224,10 @@ export async function executeHerdrCommunication(params, context, options = {}, s
         return errorResult(operation, communicationError("role_blocked", "the prompted role reached blocked state", "blocked"));
       }
       const rawReport = await invokeHerdr("read", { action: "read", role }, context, options, signal);
-      const report = extractLatestHerdrReport(readText(rawReport), role);
+      const post = readText(rawReport);
+      const sentPrompt = promptWithReportRequirement(role, request.prompt);
+      const boundary = provenancedReportSegment(pre, post, sentPrompt, role);
+      const report = extractReportFromSegment(post, role, boundary.end);
       return successResult(operation, {
         status: "complete",
         role,

package/scripts/enforcement/linux_microvm_cutover_pi.js

@@ -11,6 +11,17 @@ 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");
@@ -96,7 +107,13 @@ function fixtureDomainForId(fixtureId) {
 // 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", "_comment"]);
+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);
@@ -133,9 +150,28 @@ function normalizeTarget(parsed) {
     && !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() }
-    : { mode: "local" });
+    ? { mode: "ssh", sshTarget: parsed.sshTarget.trim(), ...extras }
+    : { mode: "local", ...extras });
 }
 
 // Shape validation for the user-relayed target parameter (untrusted input).
@@ -263,7 +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 parseReceipt(stdout) {
+export function parseReceipt(stdout) {
   const candidates = [];
   const unexpected = [];
   for (const line of String(stdout || "").split(/\r?\n/)) {
@@ -277,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);
@@ -289,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) {
@@ -350,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);
@@ -365,6 +479,15 @@ 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 = {}) {
   // 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.
@@ -399,9 +522,28 @@ export async function runLinuxMicroVMCutover(context, options = {}) {
     if (confirmed !== true) {
       return denied("stopped", reason("confirmation", "not-granted", "No target was saved; native confirmation was not granted."));
     }
-    const saved = targetParam === "local"
-      ? { schema: TARGET_SCHEMA, local: true }
-      : { schema: TARGET_SCHEMA, sshTarget: targetParam };
+    // 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`);
@@ -423,6 +565,7 @@ export async function runLinuxMicroVMCutover(context, options = {}) {
     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")}`;
@@ -447,7 +590,13 @@ export async function runLinuxMicroVMCutover(context, options = {}) {
     `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.",
@@ -465,14 +614,23 @@ export async function runLinuxMicroVMCutover(context, options = {}) {
   }
   inFlight = true;
   try {
+    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 -- " + shellQuote(fixtureId) + " " + shellQuote(scriptHash)], { input: script, timeout: 180000 })
-      : execute("ssh", [target.sshTarget, "bash", "-s", "--", fixtureId, scriptHash], { input: script, timeout: 180000 });
+      ? 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; }
@@ -516,6 +674,15 @@ export function registerLinuxMicroVMCutoverInterface(pi, options = {}) {
           ...options,
           ...(typeof params?.target === "string" ? { target: params.target } : {}),
         });
+    // 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 };
   };