@lamalibre/install-portlama-e2e-mcp 0.1.2 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lamalibre/install-portlama-e2e-mcp",
-  "version": "0.1.2",
+  "version": "0.2.1",
   "description": "MCP server for Portlama E2E test infrastructure — VM lifecycle, snapshots, test execution",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE.md",
@@ -18,7 +18,7 @@
     "build": "echo 'No build step for e2e-mcp'"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.27.1",
+    "@modelcontextprotocol/sdk": "^1.28.0",
     "chalk": "^5.3.0",
     "execa": "^9.6.1",
     "listr2": "^8.0.0",

package/src/config.js

@@ -31,6 +31,21 @@ export const TEST_DOMAIN = 'test.portlama.local';
 /** VM short-name → full multipass name mapping. */
 export const VM_NAME_MAP = { host: VM_HOST, agent: VM_AGENT, visitor: VM_VISITOR };
 
+/**
+ * Static IPs for deterministic VM networking.
+ * Uses 10.13.37.0/24 — a private subnet completely outside the Multipass DHCP range
+ * (192.168.2.0/24), eliminating any collision risk. Added as secondary addresses
+ * alongside DHCP, so Multipass connectivity and internet access are unaffected.
+ * These survive snapshot restores via a systemd oneshot service, ensuring provisioned
+ * configs (nginx, /etc/hosts, agent enrollment) remain valid.
+ */
+export const VM_STATIC_IPS = {
+  [VM_HOST]: '10.13.37.1',
+  [VM_AGENT]: '10.13.37.2',
+  [VM_VISITOR]: '10.13.37.3',
+};
+export const STATIC_SUBNET = '10.13.37.0/24';
+
 /** VM profiles — resource allocation tiers. */
 export const PROFILES = {
   production: {
@@ -58,3 +73,31 @@ export const CHECKPOINTS = {
   'post-create': 'VMs exist but no setup has run',
   'post-setup': 'All VMs provisioned, onboarding complete, services running',
 };
+
+/** Snapshot tier definitions — layered provisioning stages. */
+export const TIERS = {
+  'node-ready': {
+    level: 1,
+    description: 'Node.js 22.x installed, apt cache warm',
+    appliesTo: ['host', 'agent', 'visitor'],
+    coordinated: false,
+  },
+  'installed': {
+    level: 2,
+    description: 'Portlama installed (create-portlama completed)',
+    appliesTo: ['host'],
+    coordinated: false,
+  },
+  'provisioned': {
+    level: 3,
+    description: 'Onboarding complete, agent enrolled, visitor configured',
+    appliesTo: ['host', 'agent', 'visitor'],
+    coordinated: true,
+  },
+};
+
+/** Ordered tier names from lowest to highest. */
+export const TIER_ORDER = ['node-ready', 'installed', 'provisioned'];
+
+/** Snapshot name prefix for tier snapshots. */
+export const TIER_SNAPSHOT_PREFIX = 'tier-';

package/src/index.js

@@ -17,6 +17,7 @@
 //   snapshot_create     — snapshot VMs at a checkpoint
 //   snapshot_restore    — restore VMs to a checkpoint
 //   snapshot_list       — list available snapshots
+//   provision           — smart tier-aware provisioning with layered snapshots
 //   provision_host      — full host provisioning pipeline
 //   provision_agent     — agent setup with cert transfer
 //   provision_visitor   — visitor setup
@@ -41,6 +42,7 @@ import {
   snapshotListTool,
 } from './tools/snapshots.js';
 import {
+  provisionTool,
   provisionHostTool,
   provisionAgentTool,
   provisionVisitorTool,
@@ -70,6 +72,7 @@ const tools = [
   snapshotCreateTool,
   snapshotRestoreTool,
   snapshotListTool,
+  provisionTool,
   provisionHostTool,
   provisionAgentTool,
   provisionVisitorTool,

package/src/lib/deps.js

@@ -79,7 +79,6 @@ export const SINGLE_VM_DEPS = {
   11: [3], // input-validation
   12: [3], // user-invitations
   13: [3], // site-lifecycle
-  14: [3], // shell-lifecycle
   15: [3], // plugin-lifecycle
   16: [3], // enrollment-tokens
 };
@@ -99,7 +98,6 @@ export const THREE_VM_DEPS = {
   7: [1], // site-visitor-journey
   8: [1], // invitation-journey
   9: [1], // agent-site-deploy
-  10: [1], // shell-lifecycle
   11: [1], // plugin-lifecycle
   12: [1], // enrollment-lifecycle
 };

package/src/lib/multipass.js

@@ -39,7 +39,7 @@ export async function launch(name, { cpus, memory, disk }) {
     memory,
     '--disk',
     disk,
-  ]);
+  ], { timeout: 300_000 });
 }
 
 /** Delete a VM and purge only that VM (not other users' deleted VMs). */

package/src/lib/state.js

@@ -25,6 +25,8 @@ function defaultState() {
     credentials: null,
     lastRun: null,
     runs: [],
+    tiers: {},
+    tierSnapshots: {},
   };
 }
 
@@ -68,6 +70,47 @@ export function removeVmState(name) {
   saveState(state);
 }
 
+/** Update the current tier for a VM. */
+export function setVmTier(vmName, tier) {
+  const state = loadState();
+  if (!state.tiers) state.tiers = {};
+  state.tiers[vmName] = tier;
+  saveState(state);
+}
+
+/** Get the current tier for a VM. Returns null if not set. */
+export function getVmTier(vmName) {
+  const state = loadState();
+  return state.tiers?.[vmName] || null;
+}
+
+/** Record that a tier snapshot was created. */
+export function recordTierSnapshot(tierName, vmNames) {
+  const state = loadState();
+  if (!state.tierSnapshots) state.tierSnapshots = {};
+  state.tierSnapshots[tierName] = {
+    vms: Object.fromEntries(vmNames.map((vm) => [vm, true])),
+    createdAt: new Date().toISOString(),
+  };
+  saveState(state);
+}
+
+/** Check if a tier snapshot exists for all required VMs. */
+export function hasTierSnapshot(tierName, requiredVms) {
+  const state = loadState();
+  const snap = state.tierSnapshots?.[tierName];
+  if (!snap) return false;
+  return requiredVms.every((vm) => snap.vms?.[vm]);
+}
+
+/** Clear all tier snapshot records (called when VMs are recreated/deleted). */
+export function clearTierSnapshots() {
+  const state = loadState();
+  state.tierSnapshots = {};
+  state.tiers = {};
+  saveState(state);
+}
+
 /** Record a test run result. */
 export function recordRun(run) {
   const state = loadState();

package/src/tools/provision.js

@@ -1,5 +1,6 @@
 // ============================================================================
-// Provisioning Tools — provision_host, provision_agent, provision_visitor, hot_reload
+// Provisioning Tools — provision, provision_host, provision_agent,
+//                      provision_visitor, hot_reload
 // ============================================================================
 
 import { z } from 'zod';
@@ -11,11 +12,28 @@ import {
   VM_HOST,
   VM_AGENT,
   VM_VISITOR,
+  ALL_VMS,
   REPO_ROOT,
   THREE_VM_DIR,
   TEST_DOMAIN,
+  VM_NAME_MAP,
+  VM_STATIC_IPS,
+  TIERS,
+  TIER_SNAPSHOT_PREFIX,
 } from '../config.js';
-import { loadState, updateState, setVmState } from '../lib/state.js';
+import {
+  loadState,
+  updateState,
+  setVmState,
+  setVmTier,
+  getVmTier,
+  recordTierSnapshot,
+  hasTierSnapshot,
+} from '../lib/state.js';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
 
 /** Pack a workspace package and return the tarball path. */
 async function packPackage(packageName) {
@@ -27,205 +45,492 @@ async function packPackage(packageName) {
   return `/tmp/${tarballName}`;
 }
 
-/** Transfer test scripts to a VM. */
+/** Transfer test scripts to a VM (sequential to avoid SSH overload). */
 async function transferTestScripts(vmName) {
   await mp.exec(vmName, 'mkdir -p /tmp/e2e && chmod 777 /tmp/e2e', { sudo: true });
 
   const files = fs.readdirSync(THREE_VM_DIR).filter((f) => f.endsWith('.sh'));
-  await Promise.all(
-    files.map((file) =>
-      mp.transfer(path.join(THREE_VM_DIR, file), `${vmName}:/tmp/e2e/${file}`),
-    ),
-  );
+  for (const file of files) {
+    await mp.transfer(path.join(THREE_VM_DIR, file), `${vmName}:/tmp/e2e/${file}`);
+  }
 
-  // Transfer VM-side API helpers in parallel
   const helpers = ['vm-api-helper.sh', 'vm-api-status-helper.sh'];
-  await Promise.all(
-    helpers.map(async (helper) => {
-      const helperPath = path.join(THREE_VM_DIR, helper);
-      try {
-        await mp.transfer(helperPath, `${vmName}:/tmp/${helper}`);
-        await mp.exec(vmName, `chmod +x /tmp/${helper}`, { sudo: true });
-      } catch {
-        // Helper may not exist
-      }
-    }),
-  );
+  for (const helper of helpers) {
+    const helperPath = path.join(THREE_VM_DIR, helper);
+    try {
+      await mp.transfer(helperPath, `${vmName}:/tmp/${helper}`);
+      await mp.exec(vmName, `chmod +x /tmp/${helper}`, { sudo: true });
+    } catch {
+      // Helper may not exist
+    }
+  }
 }
 
-export const provisionHostTool = {
-  name: 'provision_host',
-  description:
-    'Pack create-portlama, transfer to host VM, install, and run setup. ' +
-    'This is the full provisioning pipeline for the host VM.',
-  inputSchema: z.object({
-    domain: z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9.-]+$/).default(TEST_DOMAIN).describe('Test domain'),
-  }),
-  async handler({ domain } = {}) {
-    domain = domain || TEST_DOMAIN;
-    const steps = [];
-
-    // 1. Pack installer
-    const tarball = await packPackage('create-portlama');
-    steps.push(`Packed installer: ${tarball}`);
+// ---------------------------------------------------------------------------
+// Stage functions (internal — called by provisionTool and legacy tools)
+// ---------------------------------------------------------------------------
+
+/** Stage 1: Install Node.js 22.x on a VM via NodeSource. */
+async function stageInstallNode(vmName) {
+  const npmCheck = await mp.exec(vmName, 'npm --version', { allowFailure: true });
+  if (npmCheck.exitCode === 0) {
+    return { skipped: true, message: `npm already available (v${npmCheck.stdout.trim()})` };
+  }
+  await mp.exec(vmName, 'apt-get update', { sudo: true, timeout: 180_000 });
+  await mp.exec(vmName, 'apt-get install -y ca-certificates curl gnupg', {
+    sudo: true,
+    timeout: 180_000,
+  });
+  await mp.exec(
+    vmName,
+    'curl -fsSL https://deb.nodesource.com/setup_22.x | bash -',
+    { sudo: true, timeout: 300_000 },
+  );
+  await mp.exec(vmName, 'apt-get install -y nodejs', {
+    sudo: true,
+    timeout: 180_000,
+  });
+  return { skipped: false, message: 'Node.js 22.x installed via NodeSource' };
+}
 
-    // 2. Install npm on host
-    await mp.exec(VM_HOST, 'apt-get install -y npm', {
-      sudo: true,
-      timeout: 120_000,
-    });
-    steps.push('npm installed on host');
+/** Stage 2: Pack, transfer, install, and run create-portlama on host. */
+async function stageInstallPortlama() {
+  const tarball = await packPackage('create-portlama');
+  await mp.transfer(tarball, `${VM_HOST}:/tmp/create-portlama.tgz`);
+  await mp.exec(VM_HOST, 'npm install -g /tmp/create-portlama.tgz', {
+    sudo: true,
+    timeout: 120_000,
+  });
+  await mp.exec(VM_HOST, 'create-portlama --dev --skip-harden --yes', {
+    sudo: true,
+    timeout: 300_000,
+  });
 
-    // 3. Transfer and install
-    await mp.transfer(tarball, `${VM_HOST}:/tmp/create-portlama.tgz`);
-    await mp.exec(VM_HOST, 'npm install -g /tmp/create-portlama.tgz', {
+  // Patch panel.json to use the static IP instead of the DHCP IP that
+  // create-portlama auto-detected. The static IP is what dnsmasq resolves to
+  // and what agents/visitors use for connectivity.
+  const staticIp = VM_STATIC_IPS[VM_HOST];
+  if (staticIp) {
+    await mp.exec(
+      VM_HOST,
+      `sed -i 's/"ip": *"[^"]*"/"ip": "${staticIp}"/' /etc/portlama/panel.json`,
+      { sudo: true, timeout: 10_000 },
+    );
+    // Restart panel server to pick up the new IP
+    await mp.exec(VM_HOST, 'systemctl restart portlama-panel', {
       sudo: true,
-      timeout: 120_000,
+      timeout: 15_000,
+      allowFailure: true,
     });
-    steps.push('create-portlama installed');
+  }
 
-    // 4. Run installer
-    await mp.exec(VM_HOST, 'create-portlama --dev --skip-harden --yes', {
-      sudo: true,
-      timeout: 300_000,
-    });
-    steps.push('Portlama installed');
+  return { message: 'create-portlama installed and executed' };
+}
 
-    // 5. Transfer test scripts and run setup
-    await transferTestScripts(VM_HOST);
-    const hostIp = await mp.getIp(VM_HOST);
+/** Stage 3a: Run setup-host.sh (onboarding, certs, user creation). */
+async function stageSetupHost(domain) {
+  await transferTestScripts(VM_HOST);
+  const hostIp = VM_STATIC_IPS[VM_HOST] || await mp.getIp(VM_HOST);
 
-    const setupResult = await mp.exec(
-      VM_HOST,
-      `bash /tmp/e2e/setup-host.sh "${hostIp}" "${domain}"`,
-      { sudo: true, timeout: 180_000, allowFailure: true },
-    );
+  const setupResult = await mp.exec(
+    VM_HOST,
+    `bash /tmp/e2e/setup-host.sh "${hostIp}" "${domain}"`,
+    { sudo: true, timeout: 180_000, allowFailure: true },
+  );
 
-    const ok = setupResult.exitCode === 0;
-    steps.push(ok ? 'setup-host.sh completed' : `setup-host.sh failed (exit ${setupResult.exitCode})`);
+  const ok = setupResult.exitCode === 0;
+  let credentials = null;
 
-    // 6. Extract credentials
+  if (ok) {
     const credsResult = await mp.exec(
       VM_HOST,
       'cat /tmp/portlama-test-credentials.json',
       { sudo: true, allowFailure: true },
     );
-
-    let credentials = null;
     if (credsResult.exitCode === 0) {
       try {
         credentials = JSON.parse(credsResult.stdout);
-        updateState({ credentials, domain });
-        steps.push('Credentials extracted');
       } catch {
-        steps.push('Warning: could not parse credentials');
+        // Parse failure handled by caller
       }
     }
+  }
 
-    setVmState(VM_HOST, { provisioned: ok, domain });
+  return { ok, credentials, error: ok ? null : setupResult.stderr.slice(-500) };
+}
 
-    return {
-      content: [
-        {
+/** Stage 3b: Pack agent, transfer tarball + enrollment token, run setup-agent.sh. */
+async function stageSetupAgent(domain, enrollmentToken) {
+  const hostIp = VM_STATIC_IPS[VM_HOST] || await mp.getIp(VM_HOST);
+
+  // Pack and transfer portlama-agent tarball
+  const agentTarball = await packPackage('portlama-agent');
+  await mp.transfer(agentTarball, `${VM_AGENT}:/tmp/portlama-agent.tgz`);
+
+  await transferTestScripts(VM_AGENT);
+
+  // Transfer enrollment token via file (never in process args)
+  const tmpTokenFile = `/tmp/.portlama-enroll-token-${Date.now()}`;
+  try {
+    fs.writeFileSync(tmpTokenFile, enrollmentToken, { mode: 0o600 });
+    await mp.transfer(tmpTokenFile, `${VM_AGENT}:/tmp/.enroll-token`);
+  } finally {
+    try { fs.unlinkSync(tmpTokenFile); } catch { /* may not exist */ }
+  }
+  await mp.exec(VM_AGENT, 'chmod 600 /tmp/.enroll-token', { sudo: true });
+
+  const result = await mp.exec(
+    VM_AGENT,
+    `bash /tmp/e2e/setup-agent.sh "${hostIp}" "${domain}" "$(cat /tmp/.enroll-token)"`,
+    { sudo: true, timeout: 180_000, allowFailure: true },
+  );
+
+  await mp.exec(VM_AGENT, 'rm -f /tmp/.enroll-token', { sudo: true, allowFailure: true });
+
+  return { ok: result.exitCode === 0, error: result.exitCode === 0 ? null : result.stderr.slice(-500) };
+}
+
+/** Stage 3c: Transfer scripts and run setup-visitor.sh. */
+async function stageSetupVisitor(domain) {
+  const hostIp = VM_STATIC_IPS[VM_HOST] || await mp.getIp(VM_HOST);
+  await transferTestScripts(VM_VISITOR);
+
+  const result = await mp.exec(
+    VM_VISITOR,
+    `bash /tmp/e2e/setup-visitor.sh "${hostIp}" "${domain}"`,
+    { sudo: true, timeout: 120_000, allowFailure: true },
+  );
+
+  return { ok: result.exitCode === 0, error: result.exitCode === 0 ? null : result.stderr.slice(-500) };
+}
+
+// ---------------------------------------------------------------------------
+// Tier snapshot helpers
+// ---------------------------------------------------------------------------
+
+/** Create a tier snapshot for the given VMs. Stops, snapshots, restarts. */
+async function createTierSnapshot(tierName, vmNames) {
+  const snapshotName = TIER_SNAPSHOT_PREFIX + tierName;
+
+  // Delete existing tier snapshot if present (overwrite)
+  for (const vm of vmNames) {
+    const existing = await mp.listSnapshots(vm);
+    if (existing.includes(snapshotName)) {
+      await mp.deleteSnapshot(vm, snapshotName);
+    }
+  }
+
+  await Promise.all(vmNames.map((vm) => mp.run(['stop', vm], { allowFailure: true })));
+  await Promise.all(vmNames.map((vm) => mp.snapshot(vm, snapshotName)));
+  await Promise.all(vmNames.map((vm) => mp.run(['start', vm], { timeout: 600_000 })));
+
+  recordTierSnapshot(tierName, vmNames);
+}
+
+/** Restore VMs to a tier snapshot. Stops, restores, restarts. */
+async function restoreTierSnapshot(tierName, vmNames) {
+  const snapshotName = TIER_SNAPSHOT_PREFIX + tierName;
+
+  await Promise.all(vmNames.map((vm) => mp.run(['stop', vm], { allowFailure: true })));
+  await Promise.all(vmNames.map((vm) => mp.restore(vm, snapshotName)));
+  await Promise.all(vmNames.map((vm) => mp.run(['start', vm], { timeout: 600_000 })));
+
+  for (const vm of vmNames) {
+    setVmTier(vm, tierName);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Smart provisioning tool
+// ---------------------------------------------------------------------------
+
+export const provisionTool = {
+  name: 'provision',
+  description:
+    'Smart provisioning with layered snapshots. Restores from cached tier snapshots ' +
+    'when possible, only runs stages that are needed. Auto-snapshots after each tier ' +
+    'for fast future restores. Tiers: node-ready -> installed -> provisioned.',
+  inputSchema: z.object({
+    targetTier: z
+      .enum(['node-ready', 'installed', 'provisioned'])
+      .default('provisioned')
+      .describe('Target tier to reach'),
+    domain: z
+      .string()
+      .regex(/^[a-zA-Z0-9][a-zA-Z0-9.-]+$/)
+      .default(TEST_DOMAIN)
+      .describe('Test domain'),
+    skipSnapshots: z.coerce
+      .boolean()
+      .default(false)
+      .describe('Skip auto-snapshotting after each tier (faster but no cache)'),
+    forceReprovision: z.coerce
+      .boolean()
+      .default(false)
+      .describe('Ignore existing snapshots and reprovision from scratch'),
+  }),
+  async handler({ targetTier, domain, skipSnapshots, forceReprovision } = {}) {
+    targetTier = targetTier || 'provisioned';
+    domain = domain || TEST_DOMAIN;
+    const steps = [];
+    const targetLevel = TIERS[targetTier].level;
+
+    try {
+      // --- TIER 1: node-ready ---
+      if (targetLevel >= 1) {
+        const tier = 'node-ready';
+        const tierDef = TIERS[tier];
+        // Determine which VMs need Node.js (all that apply for the final target)
+        const targetVms = targetLevel >= 3
+          ? tierDef.appliesTo.map((v) => VM_NAME_MAP[v])
+          : [VM_HOST];
+
+        const canRestore = !forceReprovision && hasTierSnapshot(tier, targetVms);
+        if (canRestore) {
+          await restoreTierSnapshot(tier, targetVms);
+          steps.push(`Restored tier "${tier}" from snapshot (${targetVms.length} VMs)`);
+        } else {
+          // Install Node.js on each VM that needs it
+          for (const vm of targetVms) {
+            const currentTier = getVmTier(vm);
+            const currentLevel = currentTier ? (TIERS[currentTier]?.level || 0) : 0;
+            if (currentLevel >= 1) {
+              steps.push(`${vm}: already at tier "${currentTier}" — skipping Node.js install`);
+            } else {
+              const result = await stageInstallNode(vm);
+              steps.push(`${vm}: ${result.message}`);
+              setVmTier(vm, tier);
+            }
+          }
+
+          if (!skipSnapshots) {
+            await createTierSnapshot(tier, targetVms);
+            steps.push(`Snapshot "${TIER_SNAPSHOT_PREFIX}${tier}" created (${targetVms.length} VMs)`);
+          }
+        }
+      }
+
+      // --- TIER 2: installed (host only) ---
+      if (targetLevel >= 2) {
+        const tier = 'installed';
+        const targetVms = [VM_HOST];
+
+        const canRestore = !forceReprovision && hasTierSnapshot(tier, targetVms);
+        if (canRestore) {
+          await restoreTierSnapshot(tier, targetVms);
+          steps.push(`Restored tier "${tier}" from snapshot`);
+        } else {
+          const currentTier = getVmTier(VM_HOST);
+          const currentLevel = currentTier ? (TIERS[currentTier]?.level || 0) : 0;
+          if (currentLevel >= 2) {
+            steps.push(`Host already at tier "${currentTier}" — skipping Portlama install`);
+          } else {
+            const result = await stageInstallPortlama();
+            steps.push(`Host: ${result.message}`);
+            setVmTier(VM_HOST, tier);
+          }
+
+          if (!skipSnapshots) {
+            await createTierSnapshot(tier, targetVms);
+            steps.push(`Snapshot "${TIER_SNAPSHOT_PREFIX}${tier}" created`);
+          }
+        }
+      }
+
+      // --- TIER 3: provisioned (coordinated) ---
+      if (targetLevel >= 3) {
+        const tier = 'provisioned';
+        const targetVms = ALL_VMS;
+
+        const canRestore = !forceReprovision && hasTierSnapshot(tier, targetVms);
+        if (canRestore) {
+          await restoreTierSnapshot(tier, targetVms);
+          // Restore credentials from state (they survive in state.json)
+          steps.push(`Restored tier "${tier}" from snapshot (all 3 VMs)`);
+        } else {
+          // 3a: Setup host
+          const hostResult = await stageSetupHost(domain);
+          if (!hostResult.ok) {
+            return {
+              content: [{
+                type: 'text',
+                text: JSON.stringify({
+                  ok: false,
+                  steps: [...steps, 'setup-host.sh failed'],
+                  error: hostResult.error,
+                }, null, 2),
+              }],
+            };
+          }
+
+          if (hostResult.credentials) {
+            updateState({ credentials: hostResult.credentials, domain });
+          }
+          setVmState(VM_HOST, { provisioned: true, domain });
+          setVmTier(VM_HOST, tier);
+          steps.push('Host: setup completed, credentials extracted');
+
+          // 3b + 3c: Setup agent and visitor in parallel
+          const enrollmentToken = hostResult.credentials?.enrollmentToken;
+          if (!enrollmentToken) {
+            return {
+              content: [{
+                type: 'text',
+                text: JSON.stringify({
+                  ok: false,
+                  steps: [...steps, 'No enrollment token in credentials'],
+                  error: 'Credentials extraction failed',
+                }, null, 2),
+              }],
+            };
+          }
+
+          const [agentResult, visitorResult] = await Promise.all([
+            stageSetupAgent(domain, enrollmentToken),
+            stageSetupVisitor(domain),
+          ]);
+
+          setVmState(VM_AGENT, { provisioned: agentResult.ok });
+          setVmState(VM_VISITOR, { provisioned: visitorResult.ok });
+
+          if (agentResult.ok) {
+            setVmTier(VM_AGENT, tier);
+            steps.push('Agent: setup completed');
+          } else {
+            steps.push(`Agent: setup failed — ${agentResult.error}`);
+          }
+
+          if (visitorResult.ok) {
+            setVmTier(VM_VISITOR, tier);
+            steps.push('Visitor: setup completed');
+          } else {
+            steps.push(`Visitor: setup failed — ${visitorResult.error}`);
+          }
+
+          const allOk = agentResult.ok && visitorResult.ok;
+          if (allOk && !skipSnapshots) {
+            await createTierSnapshot(tier, targetVms);
+            steps.push(`Snapshot "${TIER_SNAPSHOT_PREFIX}${tier}" created (all 3 VMs)`);
+          }
+
+          if (!allOk) {
+            return {
+              content: [{
+                type: 'text',
+                text: JSON.stringify({ ok: false, targetTier, steps }, null, 2),
+              }],
+            };
+          }
+        }
+      }
+
+      return {
+        content: [{
           type: 'text',
-          text: JSON.stringify(
-            {
-              ok,
-              steps,
-              ...(ok ? {} : { error: setupResult.stderr.slice(-500) }),
-            },
-            null,
-            2,
-          ),
-        },
-      ],
-    };
+          text: JSON.stringify({ ok: true, targetTier, steps }, null, 2),
+        }],
+      };
+    } catch (err) {
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            ok: false,
+            targetTier,
+            steps,
+            error: err.message,
+          }, null, 2),
+        }],
+      };
+    }
   },
 };
 
-export const provisionAgentTool = {
-  name: 'provision_agent',
+// ---------------------------------------------------------------------------
+// Legacy provisioning tools (delegate to stage functions)
+// ---------------------------------------------------------------------------
+
+export const provisionHostTool = {
+  name: 'provision_host',
   description:
-    'Transfer agent certificate and run setup on the agent VM. ' +
-    'Requires host to be provisioned first (needs credentials).',
+    'Pack create-portlama, transfer to host VM, install, and run setup. ' +
+    'Consider using "provision" instead for tier-aware smart provisioning.',
   inputSchema: z.object({
     domain: z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9.-]+$/).default(TEST_DOMAIN).describe('Test domain'),
   }),
   async handler({ domain } = {}) {
     domain = domain || TEST_DOMAIN;
-    const state = loadState();
-    const agentP12Password = state.credentials?.agentP12Password;
-    if (!agentP12Password) {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: JSON.stringify({
-              ok: false,
-              error: 'No agent P12 password in state — run provision_host first',
-            }),
-          },
-        ],
-      };
-    }
-
     const steps = [];
-    const hostIp = await mp.getIp(VM_HOST);
 
-    // Transfer P12 from host to agent
-    await mp.exec(
-      VM_HOST,
-      'cp /etc/portlama/pki/agents/test-agent/client.p12 /tmp/agent-export.p12 && chmod 644 /tmp/agent-export.p12',
-      { sudo: true },
-    );
-    const tmpP12 = `/tmp/portlama-agent-${Date.now()}`;
-    try {
-      await mp.transferFrom(`${VM_HOST}:/tmp/agent-export.p12`, tmpP12);
-      await mp.transfer(tmpP12, `${VM_AGENT}:/tmp/agent.p12`);
-      steps.push('Agent P12 transferred');
-    } finally {
-      // Clean up temp P12 from host machine
-      try { fs.unlinkSync(tmpP12); } catch { /* may not exist */ }
-    }
+    const nodeResult = await stageInstallNode(VM_HOST);
+    steps.push(`Node.js: ${nodeResult.message}`);
+    setVmTier(VM_HOST, 'node-ready');
 
-    // Transfer test scripts
-    await transferTestScripts(VM_AGENT);
+    const installResult = await stageInstallPortlama();
+    steps.push(installResult.message);
+    setVmTier(VM_HOST, 'installed');
 
-    // Transfer P12 password via file to avoid process listing exposure
-    const tmpPassFile = `/tmp/.portlama-p12-pass-${Date.now()}`;
-    try {
-      fs.writeFileSync(tmpPassFile, agentP12Password, { mode: 0o600 });
-      await mp.transfer(tmpPassFile, `${VM_AGENT}:/tmp/.agent-p12-pass`);
-    } finally {
-      try { fs.unlinkSync(tmpPassFile); } catch { /* may not exist */ }
+    const setupResult = await stageSetupHost(domain);
+    steps.push(setupResult.ok ? 'setup-host.sh completed' : 'setup-host.sh failed');
+
+    if (setupResult.credentials) {
+      updateState({ credentials: setupResult.credentials, domain });
+      steps.push('Credentials extracted');
     }
-    await mp.exec(VM_AGENT, 'chmod 600 /tmp/.agent-p12-pass', { sudo: true });
 
-    // Run setup — reads password from file via $3
-    const result = await mp.exec(
-      VM_AGENT,
-      `bash /tmp/e2e/setup-agent.sh "${hostIp}" "${domain}" "$(cat /tmp/.agent-p12-pass)"`,
-      { sudo: true, timeout: 120_000, allowFailure: true },
-    );
+    setVmState(VM_HOST, { provisioned: setupResult.ok, domain });
+    if (setupResult.ok) setVmTier(VM_HOST, 'provisioned');
+
+    return {
+      content: [{
+        type: 'text',
+        text: JSON.stringify({
+          ok: setupResult.ok,
+          steps,
+          ...(setupResult.ok ? {} : { error: setupResult.error }),
+        }, null, 2),
+      }],
+    };
+  },
+};
 
-    // Clean up password file inside VM
-    await mp.exec(VM_AGENT, 'rm -f /tmp/.agent-p12-pass', { sudo: true, allowFailure: true });
+export const provisionAgentTool = {
+  name: 'provision_agent',
+  description:
+    'Transfer agent tarball and run enrollment on the agent VM. ' +
+    'Requires host to be provisioned first (needs enrollment token).',
+  inputSchema: z.object({
+    domain: z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9.-]+$/).default(TEST_DOMAIN).describe('Test domain'),
+  }),
+  async handler({ domain } = {}) {
+    domain = domain || TEST_DOMAIN;
+    const state = loadState();
+    const enrollmentToken = state.credentials?.enrollmentToken;
+    if (!enrollmentToken) {
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            ok: false,
+            error: 'No enrollment token in state — run provision_host first',
+          }),
+        }],
+      };
+    }
 
-    const ok = result.exitCode === 0;
-    steps.push(ok ? 'setup-agent.sh completed' : `setup-agent.sh failed (exit ${result.exitCode})`);
-    setVmState(VM_AGENT, { provisioned: ok });
+    const result = await stageSetupAgent(domain, enrollmentToken);
+    setVmState(VM_AGENT, { provisioned: result.ok });
+    if (result.ok) setVmTier(VM_AGENT, 'provisioned');
 
     return {
-      content: [
-        {
-          type: 'text',
-          text: JSON.stringify(
-            { ok, steps, ...(ok ? {} : { error: result.stderr.slice(-500) }) },
-            null,
-            2,
-          ),
-        },
-      ],
+      content: [{
+        type: 'text',
+        text: JSON.stringify({
+          ok: result.ok,
+          steps: [result.ok ? 'setup-agent.sh completed' : 'setup-agent.sh failed'],
+          ...(result.ok ? {} : { error: result.error }),
+        }, null, 2),
+      }],
     };
   },
 };
@@ -238,36 +543,28 @@ export const provisionVisitorTool = {
   }),
   async handler({ domain } = {}) {
     domain = domain || TEST_DOMAIN;
-    const steps = [];
-    const hostIp = await mp.getIp(VM_HOST);
-
-    await transferTestScripts(VM_VISITOR);
 
-    const result = await mp.exec(
-      VM_VISITOR,
-      `bash /tmp/e2e/setup-visitor.sh "${hostIp}" "${domain}"`,
-      { sudo: true, timeout: 120_000, allowFailure: true },
-    );
-
-    const ok = result.exitCode === 0;
-    steps.push(ok ? 'setup-visitor.sh completed' : `setup-visitor.sh failed (exit ${result.exitCode})`);
-    setVmState(VM_VISITOR, { provisioned: ok });
+    const result = await stageSetupVisitor(domain);
+    setVmState(VM_VISITOR, { provisioned: result.ok });
+    if (result.ok) setVmTier(VM_VISITOR, 'provisioned');
 
     return {
-      content: [
-        {
-          type: 'text',
-          text: JSON.stringify(
-            { ok, steps, ...(ok ? {} : { error: result.stderr.slice(-500) }) },
-            null,
-            2,
-          ),
-        },
-      ],
+      content: [{
+        type: 'text',
+        text: JSON.stringify({
+          ok: result.ok,
+          steps: [result.ok ? 'setup-visitor.sh completed' : 'setup-visitor.sh failed'],
+          ...(result.ok ? {} : { error: result.error }),
+        }, null, 2),
+      }],
     };
   },
 };
 
+// ---------------------------------------------------------------------------
+// Hot reload tool (unchanged)
+// ---------------------------------------------------------------------------
+
 export const hotReloadTool = {
   name: 'hot_reload',
   description:

package/src/tools/snapshots.js

@@ -4,31 +4,72 @@
 
 import { z } from 'zod';
 import * as mp from '../lib/multipass.js';
-import { ALL_VMS, VM_NAME_MAP, CHECKPOINTS } from '../config.js';
+import {
+  ALL_VMS,
+  VM_NAME_MAP,
+  CHECKPOINTS,
+  TIERS,
+  TIER_SNAPSHOT_PREFIX,
+} from '../config.js';
+import {
+  loadState,
+  setVmTier,
+  recordTierSnapshot,
+} from '../lib/state.js';
 
 export const snapshotCreateTool = {
   name: 'snapshot_create',
   description:
     'Create a named snapshot of one or all VMs. Use checkpoint names like ' +
-    '"post-create" or "post-setup" for standard save-points, or any custom name.',
+    '"post-create" or "post-setup" for standard save-points, a tier name for ' +
+    'tier snapshots, or any custom name.',
   inputSchema: z.object({
-    name: z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/).describe('Snapshot name (e.g. "post-setup", "before-plugin-fix")'),
+    name: z
+      .string()
+      .regex(/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/)
+      .optional()
+      .describe('Snapshot name (e.g. "post-setup", "before-plugin-fix"). Required unless tier is set.'),
+    tier: z
+      .enum(['node-ready', 'installed', 'provisioned'])
+      .optional()
+      .describe('Tier name — auto-generates snapshot name as "tier-<tierName>" and records in state'),
     vms: z
       .array(z.enum(['host', 'agent', 'visitor']))
       .optional()
       .describe('Which VMs to snapshot (default: all three)'),
   }),
-  async handler({ name, vms } = {}) {
+  async handler({ name, tier, vms } = {}) {
+    if (!name && !tier) {
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({ ok: false, error: 'Either "name" or "tier" must be provided' }, null, 2),
+        }],
+      };
+    }
+
+    const snapshotName = tier ? TIER_SNAPSHOT_PREFIX + tier : name;
     const targets = vms ? vms.map((v) => VM_NAME_MAP[v]) : ALL_VMS;
     const results = [];
 
+    // Delete existing snapshot if overwriting a tier
+    if (tier) {
+      for (const vm of targets) {
+        const existing = await mp.listSnapshots(vm);
+        if (existing.includes(snapshotName)) {
+          await mp.deleteSnapshot(vm, snapshotName);
+          results.push(`${vm}: deleted existing "${snapshotName}"`);
+        }
+      }
+    }
+
     // Stop all VMs in parallel (required for snapshots)
     await Promise.all(targets.map((vm) => mp.run(['stop', vm], { allowFailure: true })));
     results.push(`Stopped ${targets.length} VMs`);
 
     // Snapshot all VMs in parallel
-    await Promise.all(targets.map((vm) => mp.snapshot(vm, name)));
-    results.push(`Created snapshot "${name}" on ${targets.length} VMs`);
+    await Promise.all(targets.map((vm) => mp.snapshot(vm, snapshotName)));
+    results.push(`Created snapshot "${snapshotName}" on ${targets.length} VMs`);
 
     // Restart all VMs in parallel
     await Promise.all(
@@ -38,6 +79,12 @@ export const snapshotCreateTool = {
       }),
     );
 
+    // Record tier snapshot in state
+    if (tier) {
+      recordTierSnapshot(tier, targets);
+      results.push(`Recorded tier "${tier}" in state`);
+    }
+
     return {
       content: [
         {
@@ -53,15 +100,34 @@ export const snapshotRestoreTool = {
   name: 'snapshot_restore',
   description:
     'Restore one or all VMs to a named snapshot. This resets the VM to the ' +
-    'exact state when the snapshot was taken — much faster than reprovisioning.',
+    'exact state when the snapshot was taken — much faster than reprovisioning. ' +
+    'Use "tier" param for tier-aware restores that update VM tier state.',
   inputSchema: z.object({
-    name: z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/).describe('Snapshot name to restore'),
+    name: z
+      .string()
+      .regex(/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/)
+      .optional()
+      .describe('Snapshot name to restore. Required unless tier is set.'),
+    tier: z
+      .enum(['node-ready', 'installed', 'provisioned'])
+      .optional()
+      .describe('Tier name — uses "tier-<tierName>" as snapshot name and updates VM tier state'),
     vms: z
       .array(z.enum(['host', 'agent', 'visitor']))
       .optional()
       .describe('Which VMs to restore (default: all three)'),
   }),
-  async handler({ name, vms } = {}) {
+  async handler({ name, tier, vms } = {}) {
+    if (!name && !tier) {
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({ ok: false, error: 'Either "name" or "tier" must be provided' }, null, 2),
+        }],
+      };
+    }
+
+    const snapshotName = tier ? TIER_SNAPSHOT_PREFIX + tier : name;
     const targets = vms ? vms.map((v) => VM_NAME_MAP[v]) : ALL_VMS;
     const results = [];
 
@@ -71,8 +137,8 @@ export const snapshotRestoreTool = {
     // Restore all VMs in parallel
     await Promise.all(
       targets.map(async (vm) => {
-        await mp.restore(vm, name);
-        results.push(`${vm}: restored to "${name}"`);
+        await mp.restore(vm, snapshotName);
+        results.push(`${vm}: restored to "${snapshotName}"`);
       }),
     );
 
@@ -88,6 +154,14 @@ export const snapshotRestoreTool = {
       }),
     );
 
+    // Update tier state after restore
+    if (tier) {
+      for (const vm of targets) {
+        setVmTier(vm, tier);
+      }
+      results.push(`Updated tier state to "${tier}" for ${targets.length} VMs`);
+    }
+
     return {
       content: [
         {
@@ -101,9 +175,11 @@ export const snapshotRestoreTool = {
 
 export const snapshotListTool = {
   name: 'snapshot_list',
-  description: 'List all available snapshots across VMs, plus known checkpoint descriptions.',
+  description: 'List all available snapshots across VMs, plus known checkpoint descriptions and tier state.',
   inputSchema: z.object({}),
   async handler() {
+    const state = loadState();
+
     // Query all VMs in parallel
     const entries = await Promise.all(
       ALL_VMS.map(async (vmName) => [vmName, await mp.listSnapshots(vmName)]),
@@ -115,7 +191,12 @@ export const snapshotListTool = {
         {
           type: 'text',
           text: JSON.stringify(
-            { snapshots, checkpoints: CHECKPOINTS },
+            {
+              snapshots,
+              checkpoints: CHECKPOINTS,
+              tierSnapshots: state.tierSnapshots || {},
+              currentTiers: state.tiers || {},
+            },
             null,
             2,
           ),

package/src/tools/status.js

@@ -82,6 +82,8 @@ export const envStatusTool = {
               domain: state.domain,
               services,
               snapshots: Object.keys(snapshots).length > 0 ? snapshots : null,
+              tiers: state.tiers || {},
+              tierSnapshots: state.tierSnapshots || {},
               lastRun: lastRun
                 ? {
                     id: lastRun.runId,

package/src/tools/tests.js

@@ -27,6 +27,7 @@ import {
   VM_HOST,
   VM_AGENT,
   VM_VISITOR,
+  VM_STATIC_IPS,
   REPO_ROOT,
   THREE_VM_DIR,
   SINGLE_VM_DIR,
@@ -55,10 +56,12 @@ async function resetAuthelia() {
 
 /** Build the test environment object with VM IPs and credentials. */
 async function buildTestEnv(state) {
+  // Prefer static IPs from config (deterministic across snapshot restores),
+  // fall back to Multipass query for VMs without static assignments.
   const [hostIp, agentIp, visitorIp] = await Promise.all([
-    mp.getIp(VM_HOST),
-    mp.getIp(VM_AGENT),
-    mp.getIp(VM_VISITOR),
+    VM_STATIC_IPS[VM_HOST] || mp.getIp(VM_HOST),
+    VM_STATIC_IPS[VM_AGENT] || mp.getIp(VM_AGENT),
+    VM_STATIC_IPS[VM_VISITOR] || mp.getIp(VM_VISITOR),
   ]);
   const domain = state.domain || TEST_DOMAIN;
 
@@ -68,7 +71,7 @@ async function buildTestEnv(state) {
     VISITOR_IP: visitorIp || '',
     TEST_DOMAIN: domain,
     ADMIN_PASSWORD: 'not-used-mTLS-only',
-    AGENT_P12_PASSWORD: state.credentials?.agentP12Password || '',
+    AGENT_P12_PASSWORD: state.credentials?.agentP12Password || 'not-used-enrollment-flow',
     TEST_USER: 'testuser',
     TEST_USER_PASSWORD: 'TestPassword-E2E-123',
     LOG_LEVEL: '1',
@@ -236,16 +239,15 @@ export const testRunAllTool = {
     // Single-VM tests
     if (suite === 'single-vm' || suite === 'both') {
       // Transfer single-VM test scripts to host
-      await mp.exec(VM_HOST, 'mkdir -p /tmp/e2e-single', { sudo: true });
+      await mp.exec(VM_HOST, 'mkdir -p /tmp/e2e-single && chmod 777 /tmp/e2e-single', { sudo: true });
       const files = fs.readdirSync(SINGLE_VM_DIR).filter((f) => f.endsWith('.sh'));
-      await Promise.all(
-        files.map((file) =>
-          mp.transfer(
-            path.join(SINGLE_VM_DIR, file),
-            `${VM_HOST}:/tmp/e2e-single/${file}`,
-          ),
-        ),
-      );
+      // Transfer sequentially to avoid overwhelming the VM's SSH daemon
+      for (const file of files) {
+        await mp.transfer(
+          path.join(SINGLE_VM_DIR, file),
+          `${VM_HOST}:/tmp/e2e-single/${file}`,
+        );
+      }
 
       for (const [, file] of Object.entries(getSingleVmTests()).sort(
         ([a], [b]) => Number(a) - Number(b),
@@ -442,7 +444,7 @@ export const testPublishTool = {
             AGENT_IP: env.AGENT_IP,
             VISITOR_IP: env.VISITOR_IP,
             TEST_DOMAIN: env.TEST_DOMAIN,
-            AGENT_P12_PASSWORD: state.credentials?.agentP12Password || '',
+            AGENT_P12_PASSWORD: state.credentials?.agentP12Password || 'not-used-enrollment-flow',
           },
           all: true,
         },

package/src/tools/vm.js

@@ -4,8 +4,52 @@
 
 import { z } from 'zod';
 import * as mp from '../lib/multipass.js';
-import { PROFILES, ALL_VMS, VM_NAME_MAP } from '../config.js';
-import { setVmState, removeVmState, updateState } from '../lib/state.js';
+import { PROFILES, ALL_VMS, VM_NAME_MAP, VM_STATIC_IPS } from '../config.js';
+import { setVmState, removeVmState, updateState, clearTierSnapshots } from '../lib/state.js';
+
+/**
+ * Apply a static IP to a VM post-boot via netplan.
+ * Writes a netplan config, removes the DHCP default, and applies.
+ * Multipass agent stays connected because it communicates via virtio, not IP.
+ */
+async function applyStaticIp(vmName) {
+  const ip = VM_STATIC_IPS[vmName];
+  if (!ip) return null;
+
+  // Add a secondary static IP on 10.13.37.0/24 via `ip addr add`. This subnet is
+  // completely outside the Multipass DHCP range, eliminating collision risk. DHCP
+  // stays untouched — Multipass connectivity and internet access are unaffected.
+  // Inter-VM traffic on 10.13.37.x works at L2 because all VMs share the same bridge.
+  await mp.exec(
+    vmName,
+    `ip addr add ${ip}/24 dev enp0s1 2>/dev/null || true`,
+    { sudo: true, timeout: 10_000 },
+  );
+
+  // Create a systemd service to re-apply on boot (survives snapshot restore)
+  const unitFile = [
+    '[Unit]',
+    'Description=Static IP for E2E testing',
+    'After=network-online.target',
+    'Wants=network-online.target',
+    '',
+    '[Service]',
+    'Type=oneshot',
+    `ExecStart=/sbin/ip addr add ${ip}/24 dev enp0s1`,
+    'RemainAfterExit=yes',
+    '',
+    '[Install]',
+    'WantedBy=multi-user.target',
+  ].join('\\n');
+
+  await mp.exec(
+    vmName,
+    `printf '${unitFile}\\n' > /etc/systemd/system/portlama-static-ip.service && systemctl daemon-reload && systemctl enable portlama-static-ip`,
+    { sudo: true, timeout: 15_000 },
+  );
+
+  return ip;
+}
 
 export const vmCreateTool = {
   name: 'vm_create',
@@ -41,17 +85,23 @@ export const vmCreateTool = {
       }),
     );
 
-    // Create VMs in parallel
+    // Create VMs in parallel (DHCP initially)
     await Promise.all(
       targets.map(async (name) => {
         await mp.launch(name, specs);
-        const ip = await mp.getIp(name);
-        setVmState(name, { ip, profile: p, state: 'running' });
-        results.push(`Created ${name} (${ip}) — ${specs.cpus} CPU, ${specs.memory} RAM`);
       }),
     );
 
+    // Apply static IPs post-boot (sequential — each VM's netplan apply is fast)
+    for (const name of targets) {
+      const staticIp = await applyStaticIp(name);
+      const ip = staticIp || await mp.getIp(name);
+      setVmState(name, { ip, profile: p, state: 'running' });
+      results.push(`Created ${name} (${ip}) — ${specs.cpus} CPU, ${specs.memory} RAM`);
+    }
+
     updateState({ profile: p });
+    clearTierSnapshots();
 
     return {
       content: [
@@ -108,6 +158,11 @@ export const vmDeleteTool = {
       }),
     );
 
+    // Invalidate tier snapshots when deleting all VMs
+    if (!vms || targets.length === 3) {
+      clearTierSnapshots();
+    }
+
     return {
       content: [
         {