@celilo/cli 0.6.0 → 0.7.0

package/drizzle/0012_module_systems_sizing.sql

@@ -0,0 +1,3 @@
+ALTER TABLE `module_systems` ADD `cpu` integer;--> statement-breakpoint
+ALTER TABLE `module_systems` ADD `memory` integer;--> statement-breakpoint
+ALTER TABLE `module_systems` ADD `disk` integer;

package/drizzle/meta/_journal.json

@@ -85,6 +85,13 @@
       "when": 1781481660000,
       "tag": "0011_backups_name",
       "breakpoints": true
+    },
+    {
+      "idx": 12,
+      "version": "6",
+      "when": 1781481720000,
+      "tag": "0012_module_systems_sizing",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celilo/cli",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Celilo — home lab orchestration CLI",
   "type": "module",
   "bin": {

package/src/cli/command-registry.ts

@@ -1090,7 +1090,7 @@ export const COMMANDS: CommandDef[] = [
   },
   {
     name: 'proxmox',
-    description: 'Proxmox cluster introspection (nodes, capacity)',
+    description: 'Proxmox cluster introspection (nodes, capacity, instance sizing)',
     subcommands: [
       {
         name: 'node',
@@ -1103,6 +1103,70 @@ export const COMMANDS: CommandDef[] = [
           },
         ],
       },
+      {
+        name: 'vm',
+        description: 'celilo-provisioned VM sizing',
+        subcommands: [
+          {
+            name: 'list',
+            description: 'List celilo VMs with desired vs actual size',
+            args: [{ name: 'service-id', description: 'Proxmox service (optional if only one)' }],
+          },
+          {
+            name: 'resize',
+            description: 'Resize a celilo VM (canonical size + reconcile)',
+            args: [{ name: 'name', description: 'Instance name (module/hostname)' }],
+            flags: [
+              { name: 'memory', description: 'New RAM in MB', takesValue: true },
+              { name: 'cpu', description: 'New vCPU count', takesValue: true },
+              { name: 'force', description: 'Override the node capacity check', takesValue: false },
+              {
+                name: 'allow-reboot',
+                description: 'Approve the stop/start a resize needs',
+                takesValue: false,
+              },
+              { name: 'skip-backup', description: 'Skip the pre-resize backup', takesValue: false },
+              {
+                name: 'yes',
+                description: 'Auto-approve reboot + backup (headless)',
+                takesValue: false,
+              },
+            ],
+          },
+        ],
+      },
+      {
+        name: 'ct',
+        description: 'celilo-provisioned container (LXC) sizing',
+        subcommands: [
+          {
+            name: 'list',
+            description: 'List celilo containers with desired vs actual size',
+            args: [{ name: 'service-id', description: 'Proxmox service (optional if only one)' }],
+          },
+          {
+            name: 'resize',
+            description: 'Resize a celilo container (canonical size + reconcile)',
+            args: [{ name: 'name', description: 'Instance name (module/hostname)' }],
+            flags: [
+              { name: 'memory', description: 'New RAM in MB', takesValue: true },
+              { name: 'cpu', description: 'New vCPU count', takesValue: true },
+              { name: 'force', description: 'Override the node capacity check', takesValue: false },
+              {
+                name: 'allow-reboot',
+                description: 'Approve the stop/start a resize needs',
+                takesValue: false,
+              },
+              { name: 'skip-backup', description: 'Skip the pre-resize backup', takesValue: false },
+              {
+                name: 'yes',
+                description: 'Auto-approve reboot + backup (headless)',
+                takesValue: false,
+              },
+            ],
+          },
+        ],
+      },
     ],
   },
   {

package/src/cli/commands/proxmox-instance-list.test.ts

@@ -0,0 +1,77 @@
+import { describe, expect, test } from 'bun:test';
+import type { ProxmoxClusterResource } from '../../api-clients/proxmox';
+import type { ProvisionedSystem } from '../../services/deployed-systems';
+import { joinInstanceRows } from './proxmox-instance-list';
+
+const GB = 1024 * 1024 * 1024;
+const MB = 1024 * 1024;
+
+function sys(p: Partial<ProvisionedSystem> & { vmid: number }): ProvisionedSystem {
+  return {
+    moduleId: 'forgejo-builder',
+    name: 'main',
+    hostname: 'forgejo-builder',
+    ipv4Address: '10.0.10.20',
+    zone: 'dmz',
+    serviceId: 'svc',
+    cpu: 4,
+    memory: 8192,
+    disk: 80,
+    ...p,
+  };
+}
+
+describe('joinInstanceRows (ISS-0150)', () => {
+  test('joins a VM: desired from system, actual from the qemu guest', () => {
+    const systems = [sys({ vmid: 208 })];
+    const resources: ProxmoxClusterResource[] = [
+      {
+        type: 'qemu',
+        vmid: 208,
+        node: 'node3',
+        status: 'running',
+        maxcpu: 4,
+        maxmem: 16 * GB,
+        maxdisk: 100 * GB,
+      },
+    ];
+    const rows = joinInstanceRows(systems, resources, 'vm');
+    expect(rows).toHaveLength(1);
+    expect(rows[0].desired).toEqual({ cpu: 4, memMb: 8192, diskGb: 80 });
+    expect(rows[0].actual).toEqual({ cpu: 4, memMb: 16384, diskGb: 100 });
+    expect(rows[0].node).toBe('node3');
+  });
+
+  test('kind filters by Proxmox guest type — a qemu guest never shows under ct', () => {
+    const systems = [sys({ vmid: 208 })];
+    const resources: ProxmoxClusterResource[] = [
+      { type: 'qemu', vmid: 208, node: 'node3', maxcpu: 4, maxmem: 8 * GB },
+    ];
+    expect(joinInstanceRows(systems, resources, 'ct')).toHaveLength(0);
+    expect(joinInstanceRows(systems, resources, 'vm')).toHaveLength(1);
+  });
+
+  test('an lxc system shows under ct', () => {
+    const systems = [sys({ moduleId: 'caddy', vmid: 202 })];
+    const resources: ProxmoxClusterResource[] = [
+      {
+        type: 'lxc',
+        vmid: 202,
+        node: 'node2',
+        status: 'running',
+        maxcpu: 1,
+        maxmem: 512 * MB,
+        maxdisk: 10 * GB,
+      },
+    ];
+    const rows = joinInstanceRows(systems, resources, 'ct');
+    expect(rows).toHaveLength(1);
+    expect(rows[0].module).toBe('caddy');
+    expect(rows[0].actual).toEqual({ cpu: 1, memMb: 512, diskGb: 10 });
+  });
+
+  test('a system absent from the cluster is omitted', () => {
+    const systems = [sys({ vmid: 999 })];
+    expect(joinInstanceRows(systems, [], 'vm')).toHaveLength(0);
+  });
+});

package/src/cli/commands/proxmox-instance-list.ts

@@ -0,0 +1,137 @@
+/**
+ * `celilo proxmox vm list` / `celilo proxmox ct list` — celilo-provisioned
+ * Proxmox instances with their **desired** size (canonical `module_systems`
+ * state, ISS-0150) next to their **actual** size (live from the Proxmox API). A
+ * desired≠actual row means a resize is pending a reconcile/redeploy.
+ *
+ * Read-only sibling of `proxmox node list`; the foundation the `resize` verb
+ * (ISS-0150 P2) builds on. See apps/celilo/designs/PROXMOX_INSTANCE_SIZING.md.
+ */
+
+import {
+  ProxmoxClient,
+  type ProxmoxClusterResource,
+  type ProxmoxCredentials,
+} from '../../api-clients/proxmox';
+import { getDb } from '../../db/client';
+import { getServiceCredentials, listContainerServices } from '../../services/container-service';
+import { type ProvisionedSystem, getProvisionedSystems } from '../../services/deployed-systems';
+import { celiloIntro } from '../prompts';
+import type { CommandResult } from '../types';
+import { resolveProxmoxService } from './proxmox-service';
+
+const BYTES_PER_MB = 1024 * 1024;
+const BYTES_PER_GB = 1024 * 1024 * 1024;
+
+export type InstanceKind = 'vm' | 'ct';
+
+/** Proxmox `type` for each celilo instance kind. */
+const PROXMOX_TYPE: Record<InstanceKind, string> = { vm: 'qemu', ct: 'lxc' };
+
+export interface InstanceRow {
+  module: string;
+  name: string;
+  vmid: number;
+  node: string;
+  status: string;
+  desired: { cpu: number | null; memMb: number | null; diskGb: number | null };
+  /** null when the instance is in module_systems but not (yet) on the cluster. */
+  actual: { cpu: number; memMb: number; diskGb: number } | null;
+}
+
+/**
+ * Pure join of celilo's provisioned systems against live Proxmox guests, for one
+ * instance kind. Keyed by vmid; the Proxmox guest `type` decides vm vs ct
+ * membership (a celilo system row doesn't itself record the kind).
+ */
+export function joinInstanceRows(
+  systems: ProvisionedSystem[],
+  resources: ProxmoxClusterResource[],
+  kind: InstanceKind,
+): InstanceRow[] {
+  const wantType = PROXMOX_TYPE[kind];
+  const byVmid = new Map<number, ProxmoxClusterResource>();
+  for (const r of resources) {
+    if (r.type === wantType && typeof r.vmid === 'number') byVmid.set(r.vmid, r);
+  }
+  const rows: InstanceRow[] = [];
+  for (const s of systems) {
+    if (s.vmid == null) continue;
+    const guest = byVmid.get(s.vmid);
+    if (!guest) continue; // not a guest of this kind (other kind, or gone from cluster)
+    rows.push({
+      module: s.moduleId,
+      name: s.name,
+      vmid: s.vmid,
+      node: guest.node ?? '—',
+      status: guest.status ?? '—',
+      desired: { cpu: s.cpu, memMb: s.memory, diskGb: s.disk },
+      actual:
+        guest.maxcpu != null && guest.maxmem != null
+          ? {
+              cpu: guest.maxcpu,
+              memMb: Math.round(guest.maxmem / BYTES_PER_MB),
+              diskGb: guest.maxdisk != null ? Math.round(guest.maxdisk / BYTES_PER_GB) : 0,
+            }
+          : null,
+    });
+  }
+  return rows;
+}
+
+function fmtSize(cpu: number | null, memMb: number | null, diskGb: number | null): string {
+  const c = cpu != null ? `${cpu}c` : '—';
+  const m = memMb != null ? `${(memMb / 1024).toFixed(0)}G` : '—';
+  const d = diskGb != null ? `${diskGb}G` : '—';
+  return `${c}/${m}/${d}`;
+}
+
+export async function handleProxmoxInstanceList(
+  kind: InstanceKind,
+  args: string[],
+): Promise<CommandResult> {
+  celiloIntro(kind === 'vm' ? 'Proxmox VMs' : 'Proxmox containers');
+
+  const resolved = resolveProxmoxService(await listContainerServices(), args[0]);
+  if ('error' in resolved) {
+    console.log(`✗ ${resolved.error}`);
+    return { success: false, error: resolved.error };
+  }
+  const { service } = resolved;
+
+  const creds = (await getServiceCredentials(service.id)) as ProxmoxCredentials;
+  const result = await new ProxmoxClient(creds).clusterResources();
+  if (!result.success) {
+    console.log(`✗ Could not reach Proxmox (${service.serviceId}): ${result.message}`);
+    return { success: false, error: result.message };
+  }
+
+  const rows = joinInstanceRows(getProvisionedSystems(getDb()), result.data, kind);
+  if (rows.length === 0) {
+    console.log(`No celilo-provisioned ${kind === 'vm' ? 'VMs' : 'containers'} found.`);
+    return { success: true, message: 'none' };
+  }
+
+  console.log(`Service: ${service.serviceId} (${service.name})\n`);
+  console.log(
+    'MODULE              VMID   NODE     STATUS    DESIRED(c/m/d)   ACTUAL(c/m/d)   DRIFT',
+  );
+  console.log(
+    '────────────────────────────────────────────────────────────────────────────────────',
+  );
+  for (const r of rows) {
+    const desired = fmtSize(r.desired.cpu, r.desired.memMb, r.desired.diskGb);
+    const actual = r.actual ? fmtSize(r.actual.cpu, r.actual.memMb, r.actual.diskGb) : '—';
+    const drift =
+      r.actual &&
+      (r.desired.cpu !== r.actual.cpu ||
+        (r.desired.memMb != null && r.desired.memMb !== r.actual.memMb))
+        ? '⚠ resize pending'
+        : '';
+    console.log(
+      `${r.module.padEnd(19)} ${String(r.vmid).padEnd(6)} ${r.node.padEnd(8)} ${r.status.padEnd(9)} ${desired.padEnd(16)} ${actual.padEnd(15)} ${drift}`,
+    );
+  }
+  console.log('');
+  return { success: true, message: `${rows.length} ${kind}(s)` };
+}

package/src/cli/commands/proxmox-instance-resize.ts

@@ -0,0 +1,219 @@
+/**
+ * `celilo proxmox vm resize <name> --memory <MB> [--cpu <n>]` (and `ct resize`) —
+ * the canonical resize for a celilo-provisioned instance (ISS-0150 P2). Updates
+ * the SYSTEM's canonical size in module_systems, then reconciles declaratively by
+ * redeploying the owning module (its Terraform now reads the system size).
+ *
+ * Guardrails (proxmox-resize-guards.ts): floor = max(requires.system) across
+ * co-hosted modules (hard); node capacity (overridable with --force). Reboot +
+ * pre-resize backup are confirmed via the event-bus interview (CLAUDE.md: no
+ * direct CLI prompts) — flags win: --allow-reboot / --skip-backup / --yes.
+ */
+
+import { and, eq } from 'drizzle-orm';
+import { ProxmoxClient, type ProxmoxCredentials } from '../../api-clients/proxmox';
+import { getDb } from '../../db/client';
+import { moduleSystems, modules } from '../../db/schema';
+import { type ModuleManifest, getSingularSystemSpec } from '../../manifest/schema';
+import { createModuleBackup } from '../../services/backup-create';
+import { askConfirm, withInterviewSession } from '../../services/bus-interview';
+import { getServiceCredentials, listContainerServices } from '../../services/container-service';
+import { getProvisionedSystems } from '../../services/deployed-systems';
+import { deployModule } from '../../services/module-deploy';
+import { celiloIntro } from '../prompts';
+import type { CommandResult } from '../types';
+import type { InstanceKind } from './proxmox-instance-list';
+import { computeFloor, validateResize } from './proxmox-resize-guards';
+import { resolveProxmoxService } from './proxmox-service';
+
+const PROXMOX_TYPE: Record<InstanceKind, string> = { vm: 'qemu', ct: 'lxc' };
+
+function numFlag(v: string | boolean | undefined): number | undefined {
+  if (typeof v !== 'string') return undefined;
+  const n = Number.parseInt(v, 10);
+  return Number.isNaN(n) ? undefined : n;
+}
+
+export async function handleProxmoxInstanceResize(
+  kind: InstanceKind,
+  args: string[],
+  flags: Record<string, string | boolean>,
+): Promise<CommandResult> {
+  celiloIntro(`Resize ${kind === 'vm' ? 'VM' : 'container'}`);
+
+  const name = args[0];
+  if (!name) {
+    const e = `Instance name required: celilo proxmox ${kind} resize <name> --memory <MB> [--cpu <n>]`;
+    console.log(`✗ ${e}`);
+    return { success: false, error: e };
+  }
+
+  if (numFlag(flags.disk) != null) {
+    const e = 'Disk resize is deferred (ISS-0150 D4). Use --memory / --cpu for now.';
+    console.log(`✗ ${e}`);
+    return { success: false, error: e };
+  }
+  const reqCpu = numFlag(flags.cpu);
+  const reqMemory = numFlag(flags.memory);
+  if (reqCpu == null && reqMemory == null) {
+    const e = 'Specify at least one of --memory <MB> or --cpu <n>.';
+    console.log(`✗ ${e}`);
+    return { success: false, error: e };
+  }
+
+  const resolved = resolveProxmoxService(await listContainerServices(), undefined);
+  if ('error' in resolved) {
+    console.log(`✗ ${resolved.error}`);
+    return { success: false, error: resolved.error };
+  }
+  const { service } = resolved;
+  const creds = (await getServiceCredentials(service.id)) as ProxmoxCredentials;
+  const client = new ProxmoxClient(creds);
+
+  const cluster = await client.clusterResources();
+  if (!cluster.success) {
+    console.log(`✗ Could not reach Proxmox: ${cluster.message}`);
+    return { success: false, error: cluster.message };
+  }
+  const wantType = PROXMOX_TYPE[kind];
+  const guestByVmid = new Map<number, (typeof cluster.data)[number]>();
+  for (const r of cluster.data) {
+    if (r.type === wantType && typeof r.vmid === 'number') guestByVmid.set(r.vmid, r);
+  }
+
+  const db = getDb();
+  const systems = getProvisionedSystems(db);
+  const matches = systems.filter(
+    (s) =>
+      s.vmid != null &&
+      guestByVmid.has(s.vmid) &&
+      (s.hostname === name || s.name === name || s.moduleId === name),
+  );
+  if (matches.length === 0) {
+    const e = `No celilo-provisioned ${kind} named '${name}'. Try: celilo proxmox ${kind} list`;
+    console.log(`✗ ${e}`);
+    return { success: false, error: e };
+  }
+  if (matches.length > 1) {
+    const e = `Ambiguous '${name}' — matches ${matches.map((m) => m.moduleId).join(', ')}`;
+    console.log(`✗ ${e}`);
+    return { success: false, error: e };
+  }
+  const target = matches[0];
+  const vmid = target.vmid as number;
+  const guest = guestByVmid.get(vmid);
+  const node = guest?.node;
+
+  // Co-hosted = every module recorded on the same physical instance (vmid).
+  const coHosted = systems.filter((s) => s.vmid === vmid);
+  const mins = coHosted.map((s) => {
+    const mod = db.select().from(modules).where(eq(modules.id, s.moduleId)).get();
+    const spec = mod ? getSingularSystemSpec(mod.manifestData as ModuleManifest) : undefined;
+    return { cpu: spec?.cpu, memory: spec?.memory, disk: spec?.disk };
+  });
+  const floor = computeFloor(mins);
+
+  const nodeCaps = await client.nodeCapacities();
+  const nodeCap = nodeCaps.success ? nodeCaps.data.find((n) => n.node === node) : undefined;
+
+  const decision = validateResize(
+    { cpu: reqCpu, memory: reqMemory },
+    {
+      current: { cpu: target.cpu, memory: target.memory, disk: target.disk },
+      floor,
+      nodeFreeMemMb: nodeCap?.memFreeMb ?? Number.POSITIVE_INFINITY,
+      nodeTotalCores: nodeCap?.cpuCores ?? Number.POSITIVE_INFINITY,
+    },
+    { force: flags.force === true },
+  );
+
+  if (decision.errors.length > 0) {
+    console.log('✗ Resize rejected:');
+    for (const err of decision.errors) console.log(`   - ${err}`);
+    if (decision.capacityOnly) console.log('   (pass --force to override the capacity check)');
+    return { success: false, error: decision.errors.join('; ') };
+  }
+
+  const yes = flags.yes === true;
+  const coHostedIds = coHosted.map((s) => s.moduleId);
+
+  // Pre-resize backup — ON by default; --skip-backup opts out; otherwise the
+  // skip decision is an event-bus interview question (never a direct CLI prompt).
+  let doBackup: boolean;
+  if (flags['skip-backup'] === true) doBackup = false;
+  else if (yes) doBackup = true;
+  else
+    doBackup = await withInterviewSession(() =>
+      askConfirm({
+        scope: 'proxmox-resize',
+        key: 'backup',
+        message: `Take a pre-resize backup of ${coHostedIds.join(', ')} first?`,
+        defaultValue: true,
+      }),
+    );
+
+  if (doBackup) {
+    for (const s of coHosted) {
+      const mod = db.select().from(modules).where(eq(modules.id, s.moduleId)).get();
+      const manifest = mod?.manifestData as ModuleManifest | undefined;
+      if (!manifest?.hooks?.on_backup) {
+        console.log(`  ⚠ ${s.moduleId} has no on_backup hook — skipping its backup`);
+        continue;
+      }
+      const backup = await createModuleBackup(s.moduleId);
+      if (!backup.success) {
+        const e = `Pre-resize backup failed for ${s.moduleId}: ${backup.error}`;
+        console.log(`✗ ${e}`);
+        return { success: false, error: e };
+      }
+      console.log(`  ✓ Backed up ${s.moduleId}`);
+    }
+  }
+
+  // Reboot confirmation — a cpu/memory change needs a Proxmox stop/start.
+  if (decision.needsReboot) {
+    let allowReboot: boolean;
+    if (flags['allow-reboot'] === true || yes) allowReboot = true;
+    else
+      allowReboot = await withInterviewSession(() =>
+        askConfirm({
+          scope: 'proxmox-resize',
+          key: 'reboot',
+          message: `Resizing ${name} (vmid ${vmid}) requires a stop/start — brief downtime. Proceed?`,
+          defaultValue: false,
+        }),
+      );
+    if (!allowReboot) {
+      const e = 'Resize aborted — reboot not approved (re-run with --allow-reboot).';
+      console.log(`✗ ${e}`);
+      return { success: false, error: e };
+    }
+  }
+
+  // Update the canonical size on every module_systems row for this instance.
+  for (const s of coHosted) {
+    const set: { cpu?: number; memory?: number; updatedAt: Date } = { updatedAt: new Date() };
+    if (reqCpu != null) set.cpu = reqCpu;
+    if (reqMemory != null) set.memory = reqMemory;
+    db.update(moduleSystems)
+      .set(set)
+      .where(and(eq(moduleSystems.moduleId, s.moduleId), eq(moduleSystems.name, s.name)))
+      .run();
+  }
+  console.log(
+    `✓ Canonical size updated: ${name} → ${reqCpu ?? target.cpu}c / ${reqMemory ?? target.memory}MB`,
+  );
+
+  // Reconcile declaratively: redeploy the owning module — its Terraform now reads
+  // the updated system size and applies it to the live instance.
+  console.log(`▸ Reconciling ${target.moduleId} (Terraform apply)…`);
+  const deployed = await deployModule(target.moduleId, db, {});
+  if (!deployed.success) {
+    const e = `Size updated but reconcile failed: ${deployed.error}. Re-run: celilo module deploy ${target.moduleId}`;
+    console.log(`✗ ${e}`);
+    return { success: false, error: e };
+  }
+
+  console.log(`✓ Resized ${name} and reconciled ${target.moduleId}.`);
+  return { success: true, message: `resized ${name}` };
+}

package/src/cli/commands/proxmox-node-list.ts

@@ -11,6 +11,7 @@ import { ProxmoxClient, type ProxmoxCredentials } from '../../api-clients/proxmo
 import { getServiceCredentials, listContainerServices } from '../../services/container-service';
 import { celiloIntro } from '../prompts';
 import type { CommandResult } from '../types';
+import { resolveProxmoxService } from './proxmox-service';
 
 function formatUptime(sec: number): string {
   if (sec <= 0) return '—';
@@ -19,40 +20,6 @@ function formatUptime(sec: number): string {
   return days > 0 ? `${days}d${hours}h` : `${hours}h`;
 }
 
-/**
- * Resolve which Proxmox service to introspect: an explicit service-id arg, else
- * the sole Proxmox service. Returns an error message when the choice is
- * ambiguous or the named service doesn't exist.
- */
-function resolveProxmoxService(
-  services: Awaited<ReturnType<typeof listContainerServices>>,
-  requested: string | undefined,
-): { service: (typeof services)[number] } | { error: string } {
-  const proxmox = services.filter((s) => s.providerName === 'proxmox');
-  if (proxmox.length === 0) {
-    return {
-      error: 'No Proxmox container service configured. Add one: celilo service add proxmox',
-    };
-  }
-  if (requested) {
-    const match = proxmox.find((s) => s.serviceId === requested);
-    if (!match) {
-      return {
-        error: `No Proxmox service '${requested}'. Known: ${proxmox.map((s) => s.serviceId).join(', ')}`,
-      };
-    }
-    return { service: match };
-  }
-  if (proxmox.length > 1) {
-    return {
-      error: `Multiple Proxmox services — specify one: celilo proxmox node list <service-id>\n  ${proxmox
-        .map((s) => s.serviceId)
-        .join('\n  ')}`,
-    };
-  }
-  return { service: proxmox[0] };
-}
-
 export async function handleProxmoxNodeList(
   args: string[],
   _flags: Record<string, boolean | string> = {},

package/src/cli/commands/proxmox-resize-guards.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, test } from 'bun:test';
+import { type ResizeContext, computeFloor, validateResize } from './proxmox-resize-guards';
+
+const ctx = (over: Partial<ResizeContext> = {}): ResizeContext => ({
+  current: { cpu: 4, memory: 8192, disk: 80 },
+  floor: { cpu: 4, memory: 8192, disk: 80 },
+  nodeFreeMemMb: 20000,
+  nodeTotalCores: 6,
+  ...over,
+});
+
+describe('validateResize (ISS-0150)', () => {
+  test('a valid memory bump within headroom passes and needs a reboot', () => {
+    const d = validateResize({ memory: 16384 }, ctx());
+    expect(d.errors).toEqual([]);
+    expect(d.needsReboot).toBe(true);
+    expect(d.effective).toEqual({ cpu: 4, memory: 16384, disk: 80 });
+  });
+
+  test('below the floor is rejected (hard, not overridable)', () => {
+    const d = validateResize({ memory: 4096 }, ctx(), { force: true });
+    expect(d.errors.length).toBe(1);
+    expect(d.errors[0]).toContain('below the module minimum');
+  });
+
+  test('memory growth beyond node free RAM is a capacity error, overridable with --force', () => {
+    const tight = ctx({ nodeFreeMemMb: 1000 }); // only 1 GB free; +8 GB requested
+    const blocked = validateResize({ memory: 16384 }, tight, { force: false });
+    expect(blocked.errors.length).toBe(1);
+    expect(blocked.capacityOnly).toBe(true);
+    const forced = validateResize({ memory: 16384 }, tight, { force: true });
+    expect(forced.errors).toEqual([]);
+  });
+
+  test('cpu above physical cores is a capacity error', () => {
+    const d = validateResize({ cpu: 8 }, ctx(), { force: false });
+    expect(d.errors[0]).toContain('exceeds node physical cores');
+    expect(validateResize({ cpu: 8 }, ctx(), { force: true }).errors).toEqual([]);
+  });
+});
+
+describe('computeFloor', () => {
+  test('takes the max of each field across co-hosted modules', () => {
+    expect(
+      computeFloor([
+        { cpu: 2, memory: 4096, disk: 40 },
+        { cpu: 4, memory: 2048, disk: 80 },
+      ]),
+    ).toEqual({ cpu: 4, memory: 4096, disk: 80 });
+  });
+
+  test('treats missing minimums as 0', () => {
+    expect(computeFloor([{ memory: 8192 }, {}])).toEqual({ cpu: 0, memory: 8192, disk: 0 });
+  });
+});

package/src/cli/commands/proxmox-resize-guards.ts

@@ -0,0 +1,102 @@
+/**
+ * Pure guardrails for `celilo proxmox … resize` (ISS-0150 D4). Kept separate from
+ * the command so the floor + capacity logic is unit-testable without Proxmox or a
+ * DB. See apps/celilo/designs/PROXMOX_INSTANCE_SIZING.md.
+ */
+
+export interface ResizeRequest {
+  cpu?: number;
+  memory?: number; // MB
+  disk?: number; // GB
+}
+
+export interface ResizeContext {
+  /** Current canonical size of the system (null where unknown). */
+  current: { cpu: number | null; memory: number | null; disk: number | null };
+  /**
+   * Minimum floor — `max(requires.system.<field>)` across every module co-hosted
+   * on this system. A resize may never drop below any tenant's minimum.
+   */
+  floor: { cpu: number; memory: number; disk: number };
+  /** Free RAM on the target node — memory growth must fit (delta check). */
+  nodeFreeMemMb: number;
+  /** Physical cores on the target node — a VM's vCPU can't exceed this (absolute). */
+  nodeTotalCores: number;
+}
+
+export interface ResizeDecision {
+  /** Hard errors that block the resize (unless overridden where noted). */
+  errors: string[];
+  /** The size that would be applied (requested fields merged over current). */
+  effective: { cpu: number | null; memory: number | null; disk: number | null };
+  /** cpu/memory changes need a Proxmox stop/start; disk-only growth does not. */
+  needsReboot: boolean;
+  /** True when the only blocker is capacity (so `--force` can override). */
+  capacityOnly: boolean;
+}
+
+/**
+ * Validate a resize request against the floor and node capacity. Disk shrink is
+ * rejected (qemu can't shrink safely); disk resize is otherwise deferred
+ * (D4) — callers should reject a disk change until that lands, but the floor/grow
+ * checks are here for when it does.
+ */
+export function validateResize(
+  req: ResizeRequest,
+  ctx: ResizeContext,
+  opts: { force: boolean } = { force: false },
+): ResizeDecision {
+  const effective = {
+    cpu: req.cpu ?? ctx.current.cpu,
+    memory: req.memory ?? ctx.current.memory,
+    disk: req.disk ?? ctx.current.disk,
+  };
+
+  const floorErrors: string[] = [];
+  if (req.cpu != null && req.cpu < ctx.floor.cpu) {
+    floorErrors.push(`cpu ${req.cpu} is below the module minimum (${ctx.floor.cpu})`);
+  }
+  if (req.memory != null && req.memory < ctx.floor.memory) {
+    floorErrors.push(`memory ${req.memory}MB is below the module minimum (${ctx.floor.memory}MB)`);
+  }
+  if (req.disk != null && req.disk < ctx.floor.disk) {
+    floorErrors.push(`disk ${req.disk}GB is below the module minimum (${ctx.floor.disk}GB)`);
+  }
+
+  const capErrors: string[] = [];
+  // cpu: a single VM's vCPU can't usefully exceed the node's physical cores.
+  if (req.cpu != null && req.cpu > ctx.nodeTotalCores) {
+    capErrors.push(`cpu ${req.cpu} exceeds node physical cores (${ctx.nodeTotalCores})`);
+  }
+  // memory: only the GROWTH beyond the current size draws on free RAM.
+  if (req.memory != null && ctx.current.memory != null) {
+    const addedMb = req.memory - ctx.current.memory;
+    if (addedMb > ctx.nodeFreeMemMb) {
+      capErrors.push(`+${addedMb}MB exceeds node free RAM (${ctx.nodeFreeMemMb}MB)`);
+    }
+  }
+
+  const capacityOnly = floorErrors.length === 0 && capErrors.length > 0;
+  // Floor is a hard floor (never overridable). Capacity is overridable with --force.
+  const errors = [...floorErrors, ...(opts.force ? [] : capErrors)];
+
+  const needsReboot = req.cpu != null || req.memory != null;
+
+  return { errors, effective, needsReboot, capacityOnly };
+}
+
+/**
+ * Compute the floor for a system from the requires.system minimums of every
+ * module co-hosted on it. Pure over the extracted minimums.
+ */
+export function computeFloor(
+  mins: Array<{ cpu?: number | null; memory?: number | null; disk?: number | null }>,
+): { cpu: number; memory: number; disk: number } {
+  const maxOf = (pick: (m: (typeof mins)[number]) => number | null | undefined): number =>
+    mins.reduce((acc, m) => Math.max(acc, pick(m) ?? 0), 0);
+  return {
+    cpu: maxOf((m) => m.cpu),
+    memory: maxOf((m) => m.memory),
+    disk: maxOf((m) => m.disk),
+  };
+}

package/src/cli/commands/proxmox-service.ts

@@ -0,0 +1,38 @@
+/**
+ * Shared Proxmox-service resolution for the `celilo proxmox …` command tree
+ * (node list, vm/ct list|show|resize). Resolves an explicit service-id arg, else
+ * the sole Proxmox service; errors when ambiguous or unknown.
+ */
+
+import type { listContainerServices } from '../../services/container-service';
+
+type Services = Awaited<ReturnType<typeof listContainerServices>>;
+
+export function resolveProxmoxService(
+  services: Services,
+  requested: string | undefined,
+): { service: Services[number] } | { error: string } {
+  const proxmox = services.filter((s) => s.providerName === 'proxmox');
+  if (proxmox.length === 0) {
+    return {
+      error: 'No Proxmox container service configured. Add one: celilo service add proxmox',
+    };
+  }
+  if (requested) {
+    const match = proxmox.find((s) => s.serviceId === requested);
+    if (!match) {
+      return {
+        error: `No Proxmox service '${requested}'. Known: ${proxmox.map((s) => s.serviceId).join(', ')}`,
+      };
+    }
+    return { service: match };
+  }
+  if (proxmox.length > 1) {
+    return {
+      error: `Multiple Proxmox services — specify one with <service-id>:\n  ${proxmox
+        .map((s) => s.serviceId)
+        .join('\n  ')}`,
+    };
+  }
+  return { service: proxmox[0] };
+}

package/src/cli/completion.ts

@@ -248,13 +248,21 @@ export async function getCompletions(words: string[], current: number): Promise<
   // Service subcommands
   // Proxmox subcommands
   if (command === 'proxmox' && currentIndex === 1) {
-    return filterSuggestions(['node'], args[1] || '');
+    return filterSuggestions(['node', 'vm', 'ct'], args[1] || '');
   }
   if (command === 'proxmox' && args[1] === 'node' && currentIndex === 2) {
     return filterSuggestions(['list'], args[2] || '');
   }
-  // proxmox node list <service-id> — proxmox services only
-  if (command === 'proxmox' && args[1] === 'node' && args[2] === 'list' && currentIndex === 3) {
+  if (command === 'proxmox' && (args[1] === 'vm' || args[1] === 'ct') && currentIndex === 2) {
+    return filterSuggestions(['list', 'resize'], args[2] || '');
+  }
+  // proxmox <node|vm|ct> list <service-id> — proxmox services only
+  if (
+    command === 'proxmox' &&
+    (args[1] === 'node' || args[1] === 'vm' || args[1] === 'ct') &&
+    args[2] === 'list' &&
+    currentIndex === 3
+  ) {
     const services = await listContainerServices();
     const serviceIds = services.filter((s) => s.providerName === 'proxmox').map((s) => s.serviceId);
     return filterSuggestions(serviceIds, args[3] || '');

package/src/cli/index.ts

@@ -67,6 +67,8 @@ import { handleModuleUpdate } from './commands/module-update';
 import { handleModuleUpgrade } from './commands/module-upgrade';
 import { moduleVerify } from './commands/module-verify';
 import { handlePackage } from './commands/package';
+import { handleProxmoxInstanceList } from './commands/proxmox-instance-list';
+import { handleProxmoxInstanceResize } from './commands/proxmox-instance-resize';
 import { handleProxmoxNodeList } from './commands/proxmox-node-list';
 import { main as runPublish } from './commands/publish';
 import { handleSecretList } from './commands/secret-list';
@@ -1816,6 +1818,19 @@ export async function runCli(argv: string[]): Promise<CommandResult> {
         error: 'Proxmox node action required (list)\n\nRun "celilo proxmox --help" for usage',
       };
     }
+    if (parsed.subcommand === 'vm' || parsed.subcommand === 'ct') {
+      const action = parsed.args[0];
+      if (action === 'list') {
+        return handleProxmoxInstanceList(parsed.subcommand, parsed.args.slice(1));
+      }
+      if (action === 'resize') {
+        return handleProxmoxInstanceResize(parsed.subcommand, parsed.args.slice(1), parsed.flags);
+      }
+      return {
+        success: false,
+        error: `Proxmox ${parsed.subcommand} action required (list, resize)\n\nRun "celilo proxmox --help" for usage`,
+      };
+    }
     return {
       success: false,
       error: `Unknown proxmox subcommand: ${parsed.subcommand}\n\nRun "celilo proxmox --help" for usage`,

package/src/db/schema.ts

@@ -392,6 +392,17 @@ export const moduleSystems = sqliteTable(
     serviceId: text('service_id').references(() => containerServices.id),
     /** Proxmox VMID — set only for proxmox containers. */
     vmid: integer('vmid'),
+    // Canonical deployed SIZE of this system (ISS-0150). For celilo-provisioned
+    // VM/LXC instances only (null for machine-pool systems celilo doesn't size).
+    // Seeded from the module's `requires.system` at first provision, then owned
+    // by `celilo proxmox … resize` — `requires.system` is only the minimum floor,
+    // never the live size. See CLAUDE.md "requires.system is the MINIMUM".
+    /** vCPU cores. */
+    cpu: integer('cpu'),
+    /** RAM in MB. */
+    memory: integer('memory'),
+    /** Root disk in GB. */
+    disk: integer('disk'),
     createdAt: integer('created_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
     updatedAt: integer('updated_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
   },

package/src/services/deployed-systems.test.ts

@@ -1,6 +1,7 @@
 import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
 import { existsSync } from 'node:fs';
 import { rm } from 'node:fs/promises';
+import { and, eq } from 'drizzle-orm';
 import { type DbClient, createDbClient } from '../db/client';
 import {
   containerServices,
@@ -10,7 +11,7 @@ import {
   moduleSystems,
   modules,
 } from '../db/schema';
-import { backfillModuleSystems, getModuleSystems } from './deployed-systems';
+import { backfillModuleSystems, getModuleSystems, upsertDeployedSystem } from './deployed-systems';
 
 const TEST_DB_PATH = './test-deployed-systems.db';
 
@@ -233,3 +234,74 @@ describe('backfillModuleSystems', () => {
     expect(getModuleSystems('namecheap', db)).toHaveLength(0);
   });
 });
+
+/**
+ * Canonical instance sizing (ISS-0150): sizing is seeded onto module_systems
+ * once at first provision and then OWNED by `celilo proxmox … resize` — a routine
+ * re-deploy must never reset a resized instance back to its manifest minimum.
+ */
+describe('upsertDeployedSystem sizing — seed-once (ISS-0150)', () => {
+  let db: DbClient;
+
+  beforeEach(() => {
+    db = createDbClient({ path: TEST_DB_PATH });
+    db.insert(modules)
+      .values({
+        id: 'm1',
+        name: 'm1',
+        version: '1.0.0',
+        manifestData: {},
+        sourcePath: '/tmp/m1',
+        state: 'VERIFIED',
+      })
+      .run();
+  });
+
+  afterEach(async () => {
+    db.$client.close();
+    for (const suffix of ['', '-shm', '-wal']) {
+      const p = `${TEST_DB_PATH}${suffix}`;
+      if (existsSync(p)) await rm(p);
+    }
+  });
+
+  const sizeArgs = (memory: number) => ({
+    name: 'main',
+    hostname: 'h',
+    ipv4Address: '10.0.0.5/24',
+    zone: 'app' as const,
+    infraType: 'container_service' as const,
+    vmid: 200,
+    cpu: 4,
+    memory,
+    disk: 80,
+  });
+
+  const row = () =>
+    db
+      .select()
+      .from(moduleSystems)
+      .where(and(eq(moduleSystems.moduleId, 'm1'), eq(moduleSystems.name, 'main')))
+      .get();
+
+  test('seeds sizing on first insert', () => {
+    upsertDeployedSystem(db, 'm1', sizeArgs(8192));
+    const r = row();
+    expect(r?.cpu).toBe(4);
+    expect(r?.memory).toBe(8192);
+    expect(r?.disk).toBe(80);
+  });
+
+  test('a re-deploy does NOT reset a resized instance to the manifest minimum', () => {
+    upsertDeployedSystem(db, 'm1', sizeArgs(8192)); // first provision: seed 8 GB
+    // Simulate `celilo proxmox vm resize` bumping the canonical size to 16 GB.
+    db.update(moduleSystems)
+      .set({ memory: 16384 })
+      .where(and(eq(moduleSystems.moduleId, 'm1'), eq(moduleSystems.name, 'main')))
+      .run();
+    // Re-deploy passes the manifest minimum (8 GB) again — must be ignored.
+    upsertDeployedSystem(db, 'm1', sizeArgs(8192));
+    expect(row()?.memory).toBe(16384);
+    expect(row()?.cpu).toBe(4);
+  });
+});

package/src/services/deployed-systems.ts

@@ -52,6 +52,52 @@ export function getModuleSystems(moduleId: string, db: DbClient): DeployedSystem
   return rows.map(rowToSystem).sort((a, b) => a.name.localeCompare(b.name));
 }
 
+/**
+ * A celilo-provisioned instance with its canonical size (ISS-0150). CLI-internal
+ * shape (NOT the `DeployedSystem` capability type) for the `celilo proxmox
+ * vm/ct …` surface, which needs the sizing columns the capability type omits.
+ */
+export interface ProvisionedSystem {
+  moduleId: string;
+  name: string;
+  hostname: string;
+  ipv4Address: string;
+  zone: NetworkZone;
+  serviceId: string | null;
+  vmid: number | null;
+  /** Canonical desired size (null until seeded / for non-Proxmox). */
+  cpu: number | null;
+  memory: number | null;
+  disk: number | null;
+}
+
+/**
+ * Every celilo-provisioned (container_service) system with a Proxmox vmid, across
+ * all modules, including its canonical sizing — the read model behind
+ * `celilo proxmox vm/ct list|show`. Ordered by vmid for stable output.
+ */
+export function getProvisionedSystems(db: DbClient): ProvisionedSystem[] {
+  return db
+    .select()
+    .from(moduleSystems)
+    .where(eq(moduleSystems.infraType, 'container_service'))
+    .all()
+    .filter((r) => r.vmid != null)
+    .map((r) => ({
+      moduleId: r.moduleId,
+      name: r.name,
+      hostname: r.hostname,
+      ipv4Address: r.ipv4Address,
+      zone: r.zone,
+      serviceId: r.serviceId,
+      vmid: r.vmid,
+      cpu: r.cpu,
+      memory: r.memory,
+      disk: r.disk,
+    }))
+    .sort((a, b) => (a.vmid ?? 0) - (b.vmid ?? 0));
+}
+
 /**
  * All container_service systems (Proxmox LXCs, droplets, …) whose zone is in
  * `zones`, across every module — the LXC complement to machine-pool's
@@ -93,6 +139,15 @@ export interface DeployedSystemInput {
   machineId?: string | null;
   serviceId?: string | null;
   vmid?: number | null;
+  /**
+   * Canonical deployed size (ISS-0150), seeded from the module's
+   * `requires.system` at first provision. Seed-once: written on INSERT only and
+   * preserved across re-deploys (omitted from the conflict update), so a later
+   * `celilo proxmox … resize` is not reset back to the manifest minimum.
+   */
+  cpu?: number | null;
+  memory?: number | null;
+  disk?: number | null;
 }
 
 /**
@@ -117,6 +172,11 @@ export function upsertDeployedSystem(
       machineId: system.machineId ?? null,
       serviceId: system.serviceId ?? null,
       vmid: system.vmid ?? null,
+      // Seed-once (ISS-0150): set on insert; deliberately omitted from the
+      // conflict update below so a resize survives re-deploys.
+      cpu: system.cpu ?? null,
+      memory: system.memory ?? null,
+      disk: system.disk ?? null,
       updatedAt: new Date(),
     })
     .onConflictDoUpdate({
@@ -129,6 +189,9 @@ export function upsertDeployedSystem(
         machineId: system.machineId ?? null,
         serviceId: system.serviceId ?? null,
         vmid: system.vmid ?? null,
+        // NOTE: cpu/memory/disk intentionally NOT updated here — sizing is
+        // canonical state owned by `celilo proxmox … resize`, not reset by a
+        // routine re-deploy (seed-once). See ISS-0150 / CLAUDE.md.
         updatedAt: new Date(),
       },
     })
@@ -207,6 +270,11 @@ export async function recordDeployedSystemForModule(
     machineId: infrastructure?.machineId ?? null,
     serviceId: infrastructure?.serviceId ?? null,
     vmid: Number.isNaN(vmid as number) ? null : vmid,
+    // Seed canonical size from requires.system (seed-once; preserved across
+    // re-deploys). Only meaningful for celilo-provisioned instances.
+    cpu: decl.resources.cpu ?? null,
+    memory: decl.resources.memory ?? null,
+    disk: decl.resources.disk ?? null,
   });
 
   return getModuleSystems(moduleId, db);
@@ -279,6 +347,10 @@ export function backfillModuleSystems(db: DbClient): string[] {
       machineId: infra.machineId ?? null,
       serviceId: infra.serviceId ?? null,
       vmid: vmid != null && !Number.isNaN(vmid) ? vmid : null,
+      // Seed canonical size from requires.system for upgraded deployments.
+      cpu: decl.resources.cpu ?? null,
+      memory: decl.resources.memory ?? null,
+      disk: decl.resources.disk ?? null,
     });
     backfilled.push(infra.moduleId);
   }

package/src/variables/context.ts

@@ -8,6 +8,7 @@ import {
   machines,
   moduleConfigs,
   moduleInfrastructure,
+  moduleSystems,
   modules,
   secrets,
   systemConfig,
@@ -264,20 +265,48 @@ export async function buildResolutionContext(
     const systemResources = getSingularSystemSpec(manifest);
 
     if (systemResources) {
-      // Map manifest fields to module variable names and apply defaults
+      // The DEPLOYED size is the SYSTEM's canonical state (ISS-0150), seeded from
+      // requires.system at first provision and thereafter owned by
+      // `celilo proxmox … resize`. So sizing flows: module_systems → these config
+      // vars → `$self:{cores,memory,disk}` in the instance Terraform.
+      //
+      // Precedence: the recorded system size WINS and overwrites the cached
+      // config (a resize must propagate on the next generate); only when this
+      // module has no recorded system size yet (the very first provision, before
+      // recordDeployedSystemForModule runs below) do we fall back to
+      // requires.system — and seed-when-unset, matching the prior behavior so the
+      // first-deploy / golden output is unchanged. `requires.system` stays the
+      // minimum floor, never the canonical size. (CLAUDE.md / ISS-0150.)
+      const sizedRow = db
+        .select({
+          cpu: moduleSystems.cpu,
+          memory: moduleSystems.memory,
+          disk: moduleSystems.disk,
+        })
+        .from(moduleSystems)
+        .where(eq(moduleSystems.moduleId, moduleId))
+        .all()
+        .find((r) => r.cpu != null || r.memory != null || r.disk != null);
+
       const resourceMappings: Array<{
         manifestKey: keyof typeof systemResources;
         configKey: string;
+        systemValue: number | null | undefined;
       }> = [
-        { manifestKey: 'cpu', configKey: 'cores' }, // manifest.requires.system.cpu → cores variable
-        { manifestKey: 'memory', configKey: 'memory' },
-        { manifestKey: 'disk', configKey: 'disk' },
-        { manifestKey: 'storage', configKey: 'storage' },
+        { manifestKey: 'cpu', configKey: 'cores', systemValue: sizedRow?.cpu }, // requires.system.cpu → cores
+        { manifestKey: 'memory', configKey: 'memory', systemValue: sizedRow?.memory },
+        { manifestKey: 'disk', configKey: 'disk', systemValue: sizedRow?.disk },
+        { manifestKey: 'storage', configKey: 'storage', systemValue: undefined }, // pool name, not sizing
       ];
 
-      for (const { manifestKey, configKey } of resourceMappings) {
+      for (const { manifestKey, configKey, systemValue } of resourceMappings) {
+        if (systemValue != null) {
+          // Canonical system size — always wins so a resize propagates.
+          upsertModuleConfig(db, moduleId, configKey, systemValue);
+          selfConfig[configKey] = String(systemValue);
+          continue;
+        }
         const value = systemResources[manifestKey];
-
         // Manifest fields are typed (cpu: number, storage: string, etc.).
         // Pass them through unstringified so valueJson preserves the
         // shape — see comment in the variable-defaults block above.