@evoclock/pi-agentic-driver 0.4.3 → 0.5.0

package/PROVENANCE.md

@@ -67,3 +67,8 @@ This repository is the public package source for `@evoclock/pi-agentic-driver`.
   native-TUI predicate and remain fail-closed. This release also adds the
   portable `templates/AGENTS.md` repository contract. The release artifact is
   built from this repository revision.
+- Release 0.5.0 adds session-scoped microVM activation. Users enable or disable
+  the switch from the native Pi TUI for the current session. The model cannot
+  change it, the switch is not persisted, and each microVM run still requires
+  native confirmation. Headless sessions fail closed. The existing trusted
+  facts, fixed argv, receipt validation, and cleanup checks remain unchanged.

package/README.md

@@ -1,4 +1,4 @@
-# pi-agentic-driver v0.4.3
+# pi-agentic-driver v0.5.0
 
 <p align="center">
   <img src="assets/Yamagane-origami.png" alt="pi-agentic-driver — Yamagane origami mark" width="140"/>
@@ -6,7 +6,8 @@
 
 <p align="center">
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-AGPL%20v3-blue?style=flat" alt="License: AGPL v3"/></a>
-  <img src="https://img.shields.io/badge/version-0.4.3-blue?style=flat" alt="Version 0.4.3"/>
+  <a href="https://www.npmjs.com/package/@evoclock/pi-agentic-driver"><img src="https://img.shields.io/npm/v/@evoclock/pi-agentic-driver?style=flat" alt="npm version"/></a>
+  <img src="https://img.shields.io/badge/version-0.5.0-blue?style=flat" alt="Version 0.5.0"/>
   <img src="https://img.shields.io/badge/status-active%20development%20%26%20testing-orange?style=flat" alt="Status"/>
   <img src="https://img.shields.io/badge/JavaScript-F7DF1E?style=flat&logo=javascript&logoColor=black" alt="JavaScript"/>
   <img src="https://img.shields.io/badge/TypeScript-3178C6?style=flat&logo=typescript&logoColor=white" alt="TypeScript"/>
@@ -32,12 +33,23 @@ Extensions for [Pi](https://github.com/earendil-works/pi-coding-agent):
 advisory code review, bounded role communication, and governed isolation
 proofs for agentic workflows.
 
+## Shipped features
+
+| Tool | What it does | Status |
+|------|--------------|--------|
+| `code_phage` | Reviews a plan against a stated goal before code is written. | shipped |
+| `agentic_herdr_communication` | Exchanges marked reports with worker agents; never grants authority. | shipped |
+| `agentic_herdr_spawn_worker` | Starts one Pi worker in a pane or tab, with native confirmation. | shipped |
+| `agentic_aidr` | Reviews writing for clarity, simplicity, brevity, and humanity. | shipped |
+| `agentic_linux_microvm_cutover` | Runs one job in a throwaway QEMU/KVM virtual machine on a Linux host. | user-enabled, native confirmation |
+| `agentic_worker_dispatch` | Runs bounded worker journeys and observes worker liveness. | shipped |
+
 **Status: active development and testing.** Each extension ships only after
 it passes fixture-based acceptance, native tests, live-session checks, and
 independent model review. You can install released components. This README
 lists pending components for transparency; pending components are not packaged.
 
-## Keeping work bounded
+## Code review and planning
 
 *Extensions that review, route, and bound what an agent does.*
 
@@ -83,9 +95,9 @@ only, not a runtime dependency).
 - **inventory refresh** — Git-aware codebase inventory regeneration with
   verification receipts, so prior-art matching stays honest.
 
-## Communicating without granting authority
+## Multi-agent communication
 
-*Extensions for bounded coordination between agents and boards.*
+*Extensions for bounded coordination between agents.*
 
 <details>
 <summary><strong>herdr-communication — bounded role communication</strong> <em>(released, 0.2.1)</em></summary>
@@ -119,7 +131,6 @@ configured Pi worker roles running under [Herdr](https://herdr.dev/)
 
 <details>
 <summary><strong>herdr-lifecycle — role-labelled worker dispatch</strong> <em>(released, 0.2.1)</em></summary>
-
 `agentic_herdr_spawn_worker` turns one natural-language request into Herdr's
 native documented lifecycle. Select `right`, `below`, or `tab`; give the
 worker a safe role label; choose a model from the active Pi model roster; and
@@ -161,15 +172,43 @@ for the wider task/model-routing and remote-session workflow.
   affinity is an optimisation, never authority: an incompatible or
   unavailable lane yields an explicit review-required result, never silent
   model substitution. Routing grants no dispatch or shell authority.
-- **worker pulse** — liveness observation and dispatch-eligibility
-  observation across role lanes: which agents are alive, what state they
-  are in, and what is ready for work. This observation grants no authority;
-  the system cannot dispatch planned work without it.
+- **worker pulse** — now part of the shipped `agentic_worker_dispatch` tool
+  (see below). Broader role-lane observation remains future work.
 - **task-ledger integration for planned work** — agents read and act
   within the task ledger's card states (what is dispatchable, in progress,
   blocked) without owning board authority: no admission, completion,
   reconciliation, or migration by the agent itself.
 
+<details>
+<summary><strong>herdr-dispatch — continuous worker journeys</strong> <em>(released, 0.5.0)</em></summary>
+
+`agentic_worker_dispatch` runs bounded worker journeys and observes worker
+liveness. Two actions:
+
+- **pulse** reports whether a worker role is alive, its current state, and
+  whether it is dispatch-eligible.
+- **dispatch** runs one journey. The worker works through the existing task
+  sequence (pending, unblocked, unowned items) and handles one
+  prompt-and-report exchange per task. A journey runs at most `maxSteps`
+  steps (default 50, cap 200).
+
+Continuous mode is the default: the journey keeps going until the worker
+finishes the queue or reaches the step bound. Turn-by-turn mode stops after
+each step and is explicit opt-in. Each journey emits one collated marked
+report that covers every step.
+
+A hung worker ends the journey with an explicit `worker-hung` state. A
+worker hangs when it never reaches `idle` across the observed exchange
+cycle, or when its exchange stalls. You can then spawn a replacement agent
+through the guarded lifecycle boundary. The replacement resumes the same
+pending tasks; the journey reuses existing task cards and never duplicates
+them. The stuck exchange is never resent to the same worker.
+
+Journeys never create, own, or complete task cards themselves, never retry
+silently, and return results as untrusted evidence.
+
+</details>
+
 ## Writing clearly
 
 *AI;DR (AI; Didn't Read) keeps technical writing clear without flattening the writer's voice.*
@@ -205,23 +244,47 @@ bounded inputs, atomic replacement, drift checks, and exact write verification.
 
 </details>
 
-## Executing in isolation
+## Sandboxed execution
 
-*Extensions that prove automation ran — and stopped — exactly as declared.*
+*Extensions that run agent jobs in a sealed environment and prove it.*
 
-**In development:**
+**Available in this release:**
 
 <details>
-<summary><strong>microVM-isolation proof</strong> <em>(qualified, activation deferred)</em></summary>
-
-`agentic_linux_microvm_cutover` is the reviewed native proof for a transient
-QEMU/KVM guest on `linux-backend`. It returns a non-authorizing receipt with
-the marker, hashes, isolation context, checked domain teardown, and ACL
-restoration. The live qualification returned `VERIFIED`.
-
-The system reserves runtime isolation for planned and automated execution
-paths. It excludes runtime isolation from ordinary ad-hoc work. Public
-activation remains deferred until the system enables those paths.
+<summary><strong>microVM isolation</strong> <em>(user-enabled, native confirmation)</em></summary>
+
+The `agentic_linux_microvm_cutover` tool runs a single job inside a throwaway
+QEMU/KVM virtual machine on a Linux host. The job cannot reach the host, the
+network, or anything else outside the machine. The system deletes the machine
+after the job ends.
+
+Each session starts with isolation disabled. To enable it, run
+`/agentic-isolation-enable` in the interactive Pi TUI and confirm. The model
+cannot run this command. Each microVM run asks for its own confirmation. To
+turn isolation off, run `/agentic-isolation-disable`. The switch never saves
+to settings. Headless sessions stay blocked.
+
+**Setup and run.** You choose where the microVM runs. The model cannot choose
+it silently — it only relays your words, and every target choice requires your
+native confirmation dialog before anything is saved or run.
+
+1. Ask your agent to run the microVM cutover and tell it which machine to use
+   (e.g. "run the microVM proof on deploy@192.168.1.50", or "...on this
+   machine"). The first run asks you to confirm natively: it names the
+   machine and states that your choice is saved to your Pi config. On your
+   Yes, the choice is saved and the run continues in the same invocation.
+2. Run `/agentic-isolation-enable` to enable isolation for this session
+   (native confirmation; not saved to settings).
+3. Each cutover run asks for its own confirmation. Saved targets are reused
+   without asking again where the microVM runs.
+
+The tool discovers the technical details from the machine itself. It reads the
+architecture, kernel, and libvirt URI at probe time. You configure nothing.
+Before any run, the probe checks three requirements: `/dev/kvm` exists and is
+accessible. Libvirt reports the system-level driver (`qemu:///system`). A
+matching `qemu-system-<arch>` binary is present. A failed check denies the run
+before anything happens. Note: the shipped fixture guest is x86_64-built, so
+the full proof currently needs an x86_64 KVM host.
 
 </details>
 
@@ -241,9 +304,9 @@ activation remains deferred until the system enables those paths.
   headless runs where no human can confirm, the system refuses destructive
   commands rather than silently allowing them.
 
-## Managing context pressure, compaction, and avoiding lossy handover
+## Session continuity
 
-*Extensions for session continuity when context runs out or a session ends.*
+*Managing context pressure, compaction, and avoiding lossy handover.*
 
 **In development:**
 
@@ -283,7 +346,7 @@ activation remains deferred until the system enables those paths.
   to a verified assignment, so consequential Git operations carry their
   own recorded provenance.
 
-## Trust in the extension set itself
+## Package integrity
 
 *Extensions that keep the installed set honest and the record bounded.*
 
@@ -306,19 +369,50 @@ acceptance with all prohibited effects absent.
 
 ### Portable repository contract
 
-`templates/AGENTS.md` is a portable starting contract for repositories that
-use Pi agents. It keeps routine work low-friction, requires bounded tasks and
-realistic tests, and treats reports as non-authorizing evidence. It does not
-overwrite repository-specific instructions or create a second authority store.
+`templates/AGENTS.md` is a starting contract you can copy into any repository
+that uses Pi agents. It asks for bounded tasks and realistic tests, and
+treats agent reports as untrusted evidence. It never overwrites an existing
+`AGENTS.md`; add your project rules below it.
 
 ## Install
 
+From npm:
+
 ```sh
-pi install <tarball-or-npm-package>
+pi install npm:@evoclock/pi-agentic-driver
+```
+
+Or from Git at a pinned tag:
+
+```sh
+pi install git:github.com/evoclock/pi-agentic-driver@v0.5.0
 ```
 
 Released extensions load standalone; neither requires the other.
 
+### Choose which extensions load
+
+A normal install loads all five extensions by default. You can load only the
+extensions you want by using the object form in your Pi settings:
+
+```json
+{
+  "packages": [
+    {
+      "source": "npm:@evoclock/pi-agentic-driver@0.5.0",
+      "extensions": [
+        "extensions/aidr.ts",
+        "extensions/code-phage.js"
+      ]
+    }
+  ]
+}
+```
+
+The package also includes `herdr-communication.ts`, `herdr-lifecycle.ts`, and
+`linux-microvm.ts`. Use `pi config` to enable or disable individual resources
+from an installed package. You are not required to use every extension.
+
 ## License
 
 AGPL-3.0-or-later with author-attribution additional terms (Section 7(b));

package/config/microvm-target.v1.example.json

@@ -0,0 +1,5 @@
+{
+  "_comment": "One decision: where the microVM runs. The target is configured through the cutover tool's native confirmation (the optional target parameter: user@host, ip, or local) and saved into the resolved Pi config directory. Arch, libvirt URI, and kernel are auto-discovered from the target at probe time; only honest safety checks are enforced (/dev/kvm accessible, system-level libvirt driver, qemu-system binary matching the discovered arch). Note: the shipped fixture guest is built for x86_64, so the full proof currently requires an x86_64 KVM host.",
+  "schema": "agentic-driver.microvm-target.v1",
+  "sshTarget": "REPLACE-WITH-user@host-or-ip"
+}

package/config/microvm-target.v1.json

@@ -0,0 +1,5 @@
+{
+  "_comment": "One decision: where the microVM runs. The target is configured through the cutover tool's native confirmation (the optional target parameter: user@host, ip, or local) and saved into the resolved Pi config directory. Arch, libvirt URI, and kernel are auto-discovered from the target at probe time; only honest safety checks are enforced (/dev/kvm accessible, system-level libvirt driver, qemu-system binary matching the discovered arch). Note: the shipped fixture guest is built for x86_64, so the full proof currently requires an x86_64 KVM host.",
+  "schema": "agentic-driver.microvm-target.v1",
+  "sshTarget": "REPLACE-WITH-user@host-or-ip"
+}

package/extensions/herdr-dispatch.ts

@@ -0,0 +1,27 @@
+// SPDX-FileCopyrightText: 2026 Julen Gamboa <j.a.r.gamboa@gmail.com>
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+export default async function herdrDispatchPi(pi) {
+  const dispatch = await import(new URL("../scripts/enforcement/herdr_async_dispatch_pi.js", import.meta.url).href);
+  const lifecycle = await import(new URL("../scripts/enforcement/herdr_lifecycle_pi.js", import.meta.url).href);
+
+  // Production replacement seam: an unresponsive-session handoff spawns through the
+  // existing guarded herdr-lifecycle boundary only — executeHerdrSpawnWorker
+  // performs native confirmation, trusted-repository resolution, installed
+  // model-roll resolution, fixed argv, and shell:false. No raw pane/agent
+  // management is added; the receipt is observed state, never authority.
+  const spawnReplacement = ({ role, repository, model, context, signal }) =>
+    lifecycle.executeHerdrSpawnWorker(
+      {
+        placement: "tab",
+        role,
+        model,
+        repository,
+      },
+      context,
+      {},
+      signal,
+    );
+
+  return dispatch.registerWorkerDispatchInterface(pi, { spawnReplacement });
+}

package/extensions/linux-microvm.ts

@@ -1,10 +1,14 @@
-import { registerLinuxMicroVMCutoverInterface } from "../scripts/enforcement/linux_microvm_cutover_pi.js";
+// SPDX-FileCopyrightText: 2026 Julen Gamboa <j.a.r.gamboa@gmail.com>
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+import { registerLinuxMicroVMCutoverInterface, registerIsolationSwitchCommands, createIsolationSwitch } from "../scripts/enforcement/linux_microvm_cutover_pi.js";
 
 export default function registerLinuxMicroVMCutover(pi: any) {
-  // Registration is limited to the activation-deferred cutover interface:
-  // native confirmation, trusted facts, and fixed boundaries are preserved by
-  // the interface itself; the transient runtime is local to this
-  // registration and only carries adapter state it observes at cutover time.
-  const runtime: { workMode?: string; workContext?: unknown; isolationEnabled?: boolean } = {};
-  return registerLinuxMicroVMCutoverInterface(pi, { runtime });
+  // Registration is limited to the activation-deferred cutover interface and
+  // the session-scoped isolation switch commands. The legacy work-mode
+  // lifecycle is not registered: agentic_work_mode is not exposed.
+  // The isolation switch state is created per registration, so each fresh
+  // extension registration (session) starts disabled.
+  const isolationSwitch = registerIsolationSwitchCommands(pi, { isolationSwitch: createIsolationSwitch() });
+  registerLinuxMicroVMCutoverInterface(pi, { isolationSwitch });
 }

package/package.json

@@ -1,17 +1,42 @@
 {
   "name": "@evoclock/pi-agentic-driver",
-  "version": "0.4.3",
+  "version": "0.5.0",
   "description": "Guardrail extensions for Agentic Driver: advisory review, bounded Herdr communication, and guarded worker lifecycle.",
   "type": "module",
   "license": "AGPL-3.0-or-later",
   "keywords": [
     "pi-package",
     "pi-extension",
-    "agentic-driver"
+    "pi",
+    "pi-coding-agent",
+    "agentic-driver",
+    "agentic-workflows",
+    "multi-agent",
+    "sub-agents",
+    "agent-coordination",
+    "worker-dispatch",
+    "continuous-agents",
+    "task-orchestration",
+    "herdr",
+    "code-review",
+    "writing-review",
+    "ai-dr",
+    "microvm",
+    "isolation",
+    "containers",
+    "git-workflow",
+    "git-safety",
+    "context-management",
+    "compaction",
+    "checkpoint-recovery",
+    "developer-tools",
+    "automation",
+    "governance"
   ],
   "files": [
     "extensions/code-phage.js",
     "extensions/herdr-communication.ts",
+    "extensions/herdr-dispatch.ts",
     "lib/adapters/diff-scope.mjs",
     "lib/adapters/evidence.mjs",
     "lib/adapters/narrative.mjs",
@@ -21,10 +46,13 @@
     "lib/python_ast_metrics.py",
     "lib/typescript_ast_metrics.mjs",
     "scripts/enforcement/herdr_communication_pi.js",
+    "scripts/enforcement/herdr_async_dispatch_pi.js",
     "README.md",
     "LICENSE",
     "extensions/herdr-lifecycle.ts",
     "scripts/enforcement/herdr_lifecycle_pi.js",
+    "config/microvm-target.v1.example.json",
+    "config/microvm-target.v1.json",
     "config/herdr-worker-repositories.v1.json",
     "extensions/linux-microvm.ts",
     "scripts/enforcement/linux_microvm_cutover_pi.js",

package/scripts/enforcement/herdr_async_dispatch_pi.js

@@ -0,0 +1,402 @@
+// SPDX-FileCopyrightText: 2026 Julen Gamboa <j.a.r.gamboa@gmail.com>
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+// Async continuous worker dispatch and pulse. One bounded step on top of the
+// shipped herdr-communication interface: a worker progresses through an
+// existing task sequence (observed, never created) and emits one collated
+// marked report. Continuous mode is the default; interactive turn-by-turn is
+// explicit opt-in. Journeys are bounded by step count, never by a wall-clock
+// timeout; cancellation and terminal failure are explicit and there are no
+// invisible retries or resends.
+
+import {
+  executeHerdrCommunication,
+  HERDR_REPORT_MARKERS,
+  HERDR_COMMUNICATION_SCHEMA,
+  HERDR_COMMUNICATION_ACTIONS,
+} from "./herdr_communication_pi.js";
+import { isNativeTuiContext } from "./native_tui_context.js";
+
+export const WORKER_DISPATCH_TOOL = "agentic_worker_dispatch";
+export const WORKER_DISPATCH_SCHEMA = "agentic-driver.worker-dispatch.v1";
+export const WORKER_DISPATCH_MODES = Object.freeze(["continuous", "turn-by-turn"]);
+export const DEFAULT_MODE = "continuous";
+const DEFAULT_JOURNEY_STEPS = 50;
+const MAX_JOURNEY_STEPS = 200;
+const MAX_REPORT_BYTES = 32 * 1024;
+const REGISTRATIONS = new WeakSet();
+
+// Terminal journey states. Only `cancelled` and `failed` are failures; every
+// other terminal state is an observed outcome, and no state is retried.
+export const WORKER_DISPATCH_TERMINAL_STATES = Object.freeze([
+  "completed", "exhausted", "role-blocked", "cancelled", "failed", "waiting-approval", "worker-unresponsive",
+]);
+
+export const WORKER_DISPATCH_PARAMETERS = Object.freeze({
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    action: { type: "string", enum: ["dispatch", "pulse"] },
+    role: { type: "string", pattern: "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$", maxLength: 64 },
+    mode: { type: "string", enum: WORKER_DISPATCH_MODES },
+    maxSteps: { type: "integer", minimum: 1, maximum: MAX_JOURNEY_STEPS },
+    stepPrompt: { type: "string", minLength: 1, maxLength: 8192 },
+    model: { type: "string", pattern: "^[a-z0-9][a-z0-9._-]{0,63}(?:\\/[a-z0-9][a-z0-9._-]{0,127})*$", maxLength: 192 },
+  },
+  required: ["action", "role"],
+  allOf: [
+    {
+      if: { properties: { action: { const: "dispatch" } }, required: ["action"] },
+      then: { required: ["stepPrompt"] },
+    },
+  ],
+});
+
+class WorkerDispatchError extends Error {
+  constructor(code, message, status = "blocked") {
+    super(message);
+    this.name = "WorkerDispatchError";
+    this.code = code;
+    this.status = status;
+  }
+}
+
+function dispatchError(code, message, status = "blocked") {
+  return new WorkerDispatchError(code, message, status);
+}
+
+function result(details) {
+  return { ok: details.ok === true, ...details };
+}
+
+function failure(action, error) {
+  const code = error?.code || "dispatch-failed";
+  return {
+    schema: WORKER_DISPATCH_SCHEMA,
+    ok: false,
+    action,
+    status: error?.status || "blocked",
+    code,
+    error: String(error?.message || error).slice(0, 512),
+    nonAuthorizing: true,
+    persisted: false,
+  };
+}
+
+// Worker pulse: liveness, current state, and dispatch eligibility, observed
+// through the existing non-authorizing get seam. Grants no authority.
+export async function workerPulse(role, context, options = {}, signal) {
+  if (typeof role !== "string" || !/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/.test(role) || role.length > 64) {
+    throw dispatchError("role-invalid", "worker pulse requires a valid non-coordinator role name", "denied");
+  }
+  const observation = await executeHerdrCommunication(
+    { action: "get", role },
+    context,
+    options.communication ?? options,
+    signal,
+  );
+  if (observation.ok !== true) {
+    throw dispatchError(observation.code || "pulse-failed",
+      observation.reason || observation.error || "worker pulse could not observe the role",
+      observation.status || "blocked");
+  }
+  const agent = observation.observation ?? {};
+  const status = typeof agent.status === "string" ? agent.status : "unknown";
+  return {
+    role,
+    alive: status !== "unknown" && status !== "gone",
+    status,
+    dispatchEligible: status === "idle",
+    observed: true,
+  };
+}
+
+// Queue progression observes the next dispatchable item without creating
+// duplicate task cards. The injected task store is read-only here; marking a
+// dispatched task done is the worker's job through its own task tools.
+export function nextDispatchableTask(taskStore) {
+  if (!taskStore || typeof taskStore.list !== "function") {
+    throw dispatchError("task-store-invalid", "a read-only task store is required to observe the queue", "denied");
+  }
+  const tasks = taskStore.list();
+  if (!Array.isArray(tasks)) throw dispatchError("task-store-invalid", "the task store did not return a task list", "denied");
+  return tasks.find((task) => task
+    && task.status === "pending"
+    && !(Array.isArray(task.blockedBy) && task.blockedBy.length > 0)
+    && !task.owner) ?? null;
+}
+
+// Tasks already dispatched during this journey are excluded from re-selection
+// without mutating the store: the journey keeps its own dispatched set.
+function selectNextTask(taskStore, dispatched) {
+  for (let attempt = 0; attempt < 32; attempt += 1) {
+    const task = nextDispatchableTask(taskStore);
+    if (!task) return null;
+    if (!dispatched.has(task.id)) return task;
+    // The observed head is already dispatched on this journey; ask the store
+    // to advance by observing its next state. If the store never changes, the
+    // loop exits via the attempt bound and the journey ends as exhausted.
+    if (typeof taskStore.observeAdvance === "function") taskStore.observeAdvance(task.id);
+    else return null;
+  }
+  return null;
+}
+
+function journeyReceipt(journey) {
+  const body = [
+    "[WORKER_JOURNEY_REPORT_BEGIN]",
+    `mode: ${journey.mode}`,
+    `role: ${journey.role}`,
+    `steps: ${journey.steps.length}`,
+    `status: ${journey.status}`,
+    ...(journey.handoff ? [`handoff: attempted=${journey.handoff.attempted} ok=${journey.handoff.ok ?? false} role=${journey.handoff.role ?? journey.role} reason=${journey.handoff.reason ?? "none"}`] : []),
+    ...journey.steps.map((step, index) =>
+      `step ${index + 1}: task=${step.taskId ?? "none"} status=${step.status} report=${step.report ?? "(none)"}`),
+    "[WORKER_JOURNEY_REPORT_END]",
+  ].join("\n");
+  if (Buffer.byteLength(body, "utf8") > MAX_REPORT_BYTES) {
+    return `${body.slice(0, MAX_REPORT_BYTES)}\n[WORKER_JOURNEY_REPORT_TRUNCATED]`;
+  }
+  return body;
+}
+
+// One continuous journey. Each step: pulse (liveness + eligibility), observe
+// the next dispatchable item, one prompt exchange (no retry on any failure),
+// read the marked report, collate. Bounded by maxSteps, never wall-clock.
+// A worker that is not idle within an observed exchange cycle is unresponsive for
+// dispatch purposes and ends the journey explicitly as worker-unresponsive.
+export async function runWorkerJourney(params, context, options = {}, signal) {
+  const mode = params.mode ?? DEFAULT_MODE;
+  const maxSteps = params.maxSteps ?? DEFAULT_JOURNEY_STEPS;
+  if (!Number.isInteger(maxSteps) || maxSteps < 1 || maxSteps > MAX_JOURNEY_STEPS) {
+    return failure("dispatch", dispatchError("max-steps-invalid",
+      `maxSteps must be an integer between 1 and ${MAX_JOURNEY_STEPS}`, "denied"));
+  }
+  const role = params.role;
+  const stepPrompt = params.stepPrompt;
+  const taskStore = options.taskStore;
+  const spawnReplacement = typeof options.spawnReplacement === "function" ? options.spawnReplacement : null;
+  const journey = { mode, role, steps: [], status: "failed", code: null, handoff: null };
+  const dispatched = new Set();
+  const communicationOptions = options.communication ?? options;
+
+  const finish = (status) => ({
+    schema: WORKER_DISPATCH_SCHEMA,
+    ok: status === "completed" || status === "exhausted" || status === "waiting-approval",
+    action: "dispatch",
+    mode,
+    role,
+    status,
+    steps: journey.steps,
+    stepCount: journey.steps.filter((step) => step.status === "done").length,
+    code: journey.code,
+    report: journeyReceipt(journey),
+    reportMarkers: { open: "[WORKER_JOURNEY_REPORT_BEGIN]", close: "[WORKER_JOURNEY_REPORT_END]" },
+    handoff: journey.handoff,
+    nonAuthorizing: true,
+    persisted: false,
+  });
+
+  // Explicit unstuck path: with native confirmation, spin up a replacement
+  // worker for the same trusted repository/role through the existing
+  // herdr-lifecycle spawn boundary (fixed argv, shell:false) and resume the
+  // pending task sequence. Reuses the same task cards; never duplicates them.
+  const handoffToReplacement = async (reason, taskId = null) => {
+    journey.status = "worker-unresponsive";
+    journey.code = "worker-unresponsive";
+    journey.steps.push({ step: journey.steps.length + 1, taskId, status: "worker-unresponsive", error: reason });
+    if (!spawnReplacement) {
+      journey.handoff = { attempted: false, reason: "replacement spawn is not available in this context" };
+      return finish("worker-unresponsive");
+    }
+    if (!isNativeTuiContext(context) || typeof context?.ui?.confirm !== "function") {
+      journey.handoff = { attempted: false, reason: "native TUI confirmation unavailable for replacement spawn" };
+      return finish("worker-unresponsive");
+    }
+    let confirmed;
+    try {
+      confirmed = await context.ui.confirm("Spin up replacement worker", [
+        `Agent session for role ${role} became unresponsive (${reason}).`,
+        "Spin up one replacement worker through the guarded herdr-lifecycle spawn boundary?",
+        "The replacement resumes the same pending task sequence; existing task cards are reused, never duplicated.",
+      ].join("\n"));
+    } catch (error) {
+      journey.handoff = { attempted: false, reason: `confirmation failed: ${error.message}` };
+      return finish("worker-unresponsive");
+    }
+    if (confirmed !== true) {
+      journey.handoff = { attempted: false, reason: "native confirmation was not granted for the replacement spawn" };
+      return finish("worker-unresponsive");
+    }
+    let spawned;
+    try {
+      spawned = await spawnReplacement({ role, repository: options.repository, model: options.model, context, signal });
+    } catch (error) {
+      journey.handoff = { attempted: true, ok: false, error: String(error?.message || error).slice(0, 256) };
+      return finish("worker-unresponsive");
+    }
+    journey.handoff = {
+      attempted: true,
+      ok: spawned?.ok === true,
+      role: spawned?.role ?? role,
+      repository: spawned?.repository,
+      modelArgv: spawned?.modelArgv,
+      nonAuthorizing: true,
+    };
+    return finish("worker-unresponsive");
+  };
+
+  if (!HERDR_COMMUNICATION_ACTIONS.includes) { /* unreachable guard */ }
+  if (mode !== "continuous" && mode !== "turn-by-turn") {
+    return failure("dispatch", dispatchError("mode-invalid", "dispatch mode must be continuous or turn-by-turn", "denied"));
+  }
+  if (!taskStore || typeof taskStore.list !== "function") {
+    return failure("dispatch", dispatchError("task-store-invalid", "a read-only task store is required", "denied"));
+  }
+  if (signal?.aborted) return finish("cancelled");
+
+  for (let stepIndex = 1; stepIndex <= maxSteps; stepIndex += 1) {
+    if (signal?.aborted) { journey.status = "cancelled"; return finish("cancelled"); }
+
+    // Pulse: liveness and dispatch eligibility, no authority.
+    let pulse;
+    try {
+      pulse = await workerPulse(role, context, communicationOptions, signal);
+    } catch (error) {
+      journey.status = error?.code === "role_blocked" ? "role-blocked" : "failed";
+      journey.code = error?.code || "pulse-failed";
+      journey.steps.push({ step: stepIndex, taskId: null, status: journey.status, error: String(error?.message || error).slice(0, 256) });
+      return finish(journey.status);
+    }
+    if (!pulse.alive) {
+      return handoffToReplacement("worker role is not alive");
+    }
+    if (!pulse.dispatchEligible) {
+      if (pulse.status === "blocked") {
+        journey.status = "role-blocked";
+        journey.code = "role_blocked";
+        journey.steps.push({ step: stepIndex, taskId: null, status: "role-blocked", workerStatus: pulse.status });
+        return finish("role-blocked");
+      }
+      // Not idle within an observed exchange cycle: unresponsive for dispatch.
+      return handoffToReplacement(`worker not idle in the observed exchange cycle (status: ${pulse.status})`);
+    }
+
+    // Observe the next dispatchable item; never create or mutate cards.
+    let task;
+    try {
+      task = selectNextTask(taskStore, dispatched);
+    } catch (error) {
+      journey.status = "failed";
+      journey.steps.push({ step: stepIndex, taskId: null, status: "failed", error: String(error?.message || error).slice(0, 256) });
+      return finish("failed");
+    }
+    if (!task) {
+      journey.status = "exhausted";
+      journey.steps.push({ step: stepIndex, taskId: null, status: "exhausted" });
+      return finish("exhausted");
+    }
+
+    // Interactive opt-in: stop after each step for explicit approval.
+    if (mode === "turn-by-turn" && stepIndex > 1) {
+      journey.status = "waiting-approval";
+      journey.steps.push({ step: stepIndex, taskId: task.id, status: "waiting-approval" });
+      return finish("waiting-approval");
+    }
+
+    // Consequential dispatch requires native confirmation, once per step.
+    if (!isNativeTuiContext(context) || typeof context?.ui?.confirm !== "function") {
+      journey.status = "failed";
+      journey.steps.push({ step: stepIndex, taskId: task.id, status: "failed", error: "native TUI confirmation unavailable" });
+      return finish("failed");
+    }
+    let confirmed;
+    try {
+      confirmed = await context.ui.confirm("Dispatch task to worker", [
+        `Dispatch one bounded step to role ${role}?`,
+        `Task: ${task.id}${task.subject ? ` — ${task.subject}` : ""}`,
+        `Mode: ${mode} (step ${stepIndex} of at most ${maxSteps})`,
+        "One prompt exchange, no retries; the worker returns one marked report.",
+      ].join("\n"));
+    } catch (error) {
+      journey.status = "failed";
+      journey.steps.push({ step: stepIndex, taskId: task.id, status: "failed", error: `confirmation failed: ${error.message}` });
+      return finish("failed");
+    }
+    if (confirmed !== true) {
+      journey.status = "cancelled";
+      journey.steps.push({ step: stepIndex, taskId: task.id, status: "cancelled", error: "native confirmation was not granted" });
+      return finish("cancelled");
+    }
+
+    // One prompt exchange. Any failure is terminal for the journey; there is
+    // no invisible retry or resend.
+    const exchange = await executeHerdrCommunication(
+      { action: "prompt", role, prompt: `${stepPrompt}\nTask: ${task.id}${task.subject ? ` — ${task.subject}` : ""}`, timeoutMs: 120000 },
+      context,
+      communicationOptions,
+      signal,
+    );
+    if (exchange.ok !== true) {
+      const unresponsive = exchange.code === "prompt_stalled" || exchange.code === "process_timeout";
+      if (unresponsive) {
+        return handoffToReplacement(`exchange ended with ${exchange.code}`, task.id);
+      }
+      journey.status = exchange.code === "role_blocked" ? "role-blocked" : "failed";
+      journey.code = exchange.code || "exchange-failed";
+      journey.steps.push({ step: stepIndex, taskId: task.id, status: journey.status, error: exchange.reason || exchange.error || exchange.code });
+      return finish(journey.status);
+    }
+    journey.steps.push({
+      step: stepIndex,
+      taskId: task.id,
+      status: "done",
+      workerStatus: exchange.agentStatus,
+      report: exchange.report,
+    });
+    dispatched.add(task.id);
+  }
+
+  journey.status = "completed";
+  return finish("completed");
+  // Unreachable in correct use: every step either dispatches one pending
+  // task, or the queue observation returns null and the journey ends with
+  // "exhausted". A task store that never drains hits maxSteps and lands here;
+  // "completed" then reflects the step bound, and callers inspect stepCount.
+}
+
+export function registerWorkerDispatchInterface(pi, options = {}) {
+  if (typeof pi?.registerTool !== "function" || REGISTRATIONS.has(pi)) return;
+  REGISTRATIONS.add(pi);
+  pi.registerTool({
+    name: WORKER_DISPATCH_TOOL,
+    label: "Worker Dispatch And Pulse",
+    description: "Observe worker liveness (pulse) or run one bounded continuous worker journey over the existing task sequence. Continuous mode is the default; turn-by-turn is explicit opt-in. Journeys emit one collated marked report, never create task cards, never retry, and are bounded by step count, not wall-clock.",
+    promptSnippet: "Use agentic_worker_dispatch to pulse a worker or run one bounded continuous journey over the existing task sequence; it observes dispatchable tasks without creating cards and grants no authority.",
+    promptGuidelines: [
+      "agentic_worker_dispatch pulse observes liveness, state, and dispatch eligibility without granting authority.",
+      "agentic_worker_dispatch dispatch runs at most maxSteps single-exchange steps; any exchange failure ends the journey explicitly with no retry or resend.",
+    ],
+    parameters: WORKER_DISPATCH_PARAMETERS,
+    async execute(_id, params, signal, _update, context) {
+      let value;
+      if (params?.action === "pulse") {
+        try {
+          const pulse = await workerPulse(params.role, context, options, signal);
+          value = { schema: WORKER_DISPATCH_SCHEMA, ok: true, action: "pulse", ...pulse, nonAuthorizing: true, persisted: false };
+        } catch (error) {
+          value = failure("pulse", error);
+        }
+      } else {
+        value = await runWorkerJourney(params ?? {}, context, options, signal);
+      }
+      return {
+        content: [{ type: "text", text: JSON.stringify(value, null, 2) }],
+        details: value,
+      };
+    },
+  });
+}
+
+export { HERDR_REPORT_MARKERS, HERDR_COMMUNICATION_SCHEMA };
+export default registerWorkerDispatchInterface;

package/scripts/enforcement/linux_microvm_cutover_pi.js

@@ -2,20 +2,46 @@
 // 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";
 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 +87,84 @@ 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", "_comment"]);
+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;
+  return Object.freeze(hasSshTarget
+    ? { mode: "ssh", sshTarget: parsed.sshTarget.trim() }
+    : { mode: "local" });
+}
+
+// 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 +178,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,18 +263,6 @@ 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) {
   const candidates = [];
   const unexpected = [];
@@ -236,15 +366,62 @@ function normalizedForwardedStderr(result, fallbackPhase, fallbackCode, fallback
 }
 
 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."));
+  }
+  // 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."));
+    }
+    const saved = targetParam === "local"
+      ? { schema: TARGET_SCHEMA, local: true }
+      : { schema: TARGET_SCHEMA, 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}`));
+    }
   }
-  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."));
+  // 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) || typeof context?.ui?.confirm !== "function") {
-    return denied("blocked", reason("policy", "native-tui-required", "Open the Linux microVM cutover in the interactive Pi TUI."));
+  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."));
   }
   if (inFlight) return denied("denied", reason("execution", "already-active", "another Linux microVM cutover is active in this host session"));
 
@@ -259,13 +436,13 @@ 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}`,
@@ -288,7 +465,9 @@ export async function runLinuxMicroVMCutover(context, options = {}) {
   }
   inFlight = true;
   try {
-    const result = execute("ssh", ["linux-backend", "bash", "-s", "--", fixtureId, scriptHash], { input: script, timeout: 180000 });
+    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 });
     if (!result || result.code !== 0) {
       return denied("blocked", normalizedForwardedStderr(result, "fixture", "execution-failed", "fixed microVM fixture failed"));
     }
@@ -307,22 +486,132 @@ 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 };
+    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;