@celilo/cli 0.8.2 → 0.9.1

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/0013_dns_view_overrides.sql

@@ -0,0 +1 @@
+ALTER TABLE `dns_internal_records` ADD `zone_routable_ip` text;

package/drizzle/meta/_journal.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celilo/cli",
-  "version": "0.8.2",
+  "version": "0.9.1",
   "description": "Celilo — home lab orchestration CLI",
   "type": "module",
   "bin": {
@@ -13,15 +13,10 @@
     "schemas/",
     "tsconfig.json",
     "AGENTS.md",
-    "CLI_USAGE.md"
-  ],
-  "keywords": [
-    "celilo",
-    "homelab",
-    "orchestration",
-    "ansible",
-    "terraform"
+    "CELILO_SUBSYSTEMS.md",
+    "CELILO_CORE_MODULES.md"
   ],
+  "keywords": ["celilo", "homelab", "orchestration", "ansible", "terraform"],
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -54,7 +49,7 @@
   },
   "dependencies": {
     "@aws-sdk/client-s3": "^3.1024.0",
-    "@celilo/capabilities": "^0.5.0",
+    "@celilo/capabilities": "^0.6.0",
     "@celilo/cli-display": "^0.1.9",
     "@celilo/event-bus": "^0.1.7",
     "@clack/prompts": "^1.1.0",

package/src/capabilities/well-known.test.ts

@@ -1,7 +1,6 @@
 import { describe, expect, test } from 'bun:test';
 import {
   WELL_KNOWN_CAPABILITIES,
-  getCapabilityDataSchema,
   getSupportedCapabilities,
   getWellKnownCapability,
   isWellKnown,
@@ -27,7 +26,9 @@ describe('Well-Known Capabilities Registry', () => {
     test('should have dns_internal capability', () => {
       expect(WELL_KNOWN_CAPABILITIES.dns_internal).toBeDefined();
       expect(WELL_KNOWN_CAPABILITIES.dns_internal.canonical_hostname).toBe('dns-int');
-      expect(WELL_KNOWN_CAPABILITIES.dns_internal.required_zone).toBe('internal');
+      // ISS-0156: the resolver moved to a protected zone (dmz) so it can see
+      // protected-zone query sources for split-horizon views.
+      expect(WELL_KNOWN_CAPABILITIES.dns_internal.required_zone).toBe('dmz');
       expect(WELL_KNOWN_CAPABILITIES.dns_internal.zone_enforced).toBe(true);
     });
 
@@ -140,10 +141,11 @@ describe('Well-Known Capabilities Registry', () => {
       expect(result.error).toContain("Capability 'auth' requires zone='secure'");
     });
 
-    test('should validate correct zone for dns_internal', () => {
-      const result = validateZoneRequirement('dns_internal', 'internal');
-
-      expect(result.valid).toBe(true);
+    test('should validate correct zone for dns_internal (dmz — ISS-0156)', () => {
+      expect(validateZoneRequirement('dns_internal', 'dmz').valid).toBe(true);
+      // The old `internal` placement is now rejected — the resolver must be in a
+      // protected zone to see protected-zone query sources for split-horizon.
+      expect(validateZoneRequirement('dns_internal', 'internal').valid).toBe(false);
     });
 
     test('should allow dns_registrar in any zone (zone_enforced=false)', () => {
@@ -163,64 +165,6 @@ describe('Well-Known Capabilities Registry', () => {
     });
   });
 
-  describe('getCapabilityDataSchema', () => {
-    test('should return data schema for public_web', () => {
-      const schema = getCapabilityDataSchema('public_web');
-
-      expect(schema).toEqual({
-        server: {
-          ip: {
-            primary: '$self:target_ip',
-          },
-          port: 443,
-        },
-      });
-    });
-
-    test('should return data schema for dns_registrar', () => {
-      const schema = getCapabilityDataSchema('dns_registrar');
-
-      expect(schema).toEqual({
-        provider: 'namecheap',
-        domains: '$self:domains',
-        supports: ['dynamic_dns_a_record'],
-      });
-    });
-
-    test('should return data schema for auth', () => {
-      const schema = getCapabilityDataSchema('auth');
-
-      // Note: oidc.issuer_url was removed in MANIFEST_V2 D9 — auth providers
-      // (e.g. authentik) now derive their issuer URL in their own manifest
-      // and expose it through provides.capabilities[].data.
-      expect(schema).toEqual({
-        server: {
-          ip: {
-            primary: '$self:target_ip',
-          },
-          port: 9000,
-        },
-      });
-    });
-
-    test('should return cloned schema (not reference)', () => {
-      const schema1 = getCapabilityDataSchema('public_web');
-      const schema2 = getCapabilityDataSchema('public_web');
-
-      // Modify one schema to test cloning
-      // biome-ignore lint/suspicious/noExplicitAny: intentionally mutating to verify independent copies
-      (schema1 as any).server.port = 8080;
-
-      // Other schema should be unchanged
-      // biome-ignore lint/suspicious/noExplicitAny: accessing mutated property for comparison
-      expect((schema2 as any).server.port).toBe(443);
-    });
-
-    test('should throw error for unknown capability', () => {
-      expect(() => getCapabilityDataSchema('unknown')).toThrow('Unknown capability: unknown');
-    });
-  });
-
   describe('Security zone requirements', () => {
     test('home lab public-facing services must be in DMZ', () => {
       expect(WELL_KNOWN_CAPABILITIES.public_web.required_zone).toBe('dmz');
@@ -231,8 +175,10 @@ describe('Well-Known Capabilities Registry', () => {
       expect(WELL_KNOWN_CAPABILITIES.database.required_zone).toBe('secure');
     });
 
-    test('internal services must be in internal zone', () => {
-      expect(WELL_KNOWN_CAPABILITIES.dns_internal.required_zone).toBe('internal');
+    test('the internal DNS resolver lives in the dmz (ISS-0156)', () => {
+      // Moved out of `internal`: the resolver must see protected-zone query
+      // sources for source-based split-horizon views (v2/INTERNAL_DNS_ZONE_VIEWS.md).
+      expect(WELL_KNOWN_CAPABILITIES.dns_internal.required_zone).toBe('dmz');
     });
   });
 });

package/src/capabilities/well-known.ts

@@ -74,12 +74,20 @@ export const WELL_KNOWN_CAPABILITIES: Record<string, WellKnownCapability> = {
 
   /**
    * dns_internal - Internal DNS resolver
-   * Example: Technitium DNS server for split-horizon LAN resolution
-   * Security: Internal zone (backbone service reachable from all zones)
+   * Example: Technitium / knot-unbound for split-horizon DNS
+   * Security: a PROTECTED zone (dmz), NOT `internal` (ISS-0156,
+   * v2/INTERNAL_DNS_ZONE_VIEWS.md). The resolver must see each querying client's
+   * real source IP to serve source-based split-horizon views; fw-main NATs
+   * protected↔`internal`, so an `internal`-placed resolver sees every protected
+   * query as fw-main's address and can't tell the zones apart. Placed in `dmz`
+   * (a protected zone — protected↔protected is not NAT'd) it sees real
+   * protected-zone sources; `internal` devices reach it via a firewall
+   * DNS-ingress DNAT. The operator accepted the modest posture change (the
+   * `internal` zone is itself un-managed). zone_enforced stays true — just to dmz.
    */
   dns_internal: {
     canonical_hostname: 'dns-int',
-    required_zone: 'internal',
+    required_zone: 'dmz',
     zone_enforced: true,
     data_schema: {
       server: {
@@ -219,12 +227,3 @@ export function validateZoneRequirement(
 
   return { valid: true };
 }
-
-/**
- * Get capability data schema with variables resolved
- * Note: This returns the template schema - actual variable resolution happens during generation
- */
-export function getCapabilityDataSchema(capabilityName: string): Record<string, unknown> {
-  const capability = getWellKnownCapability(capabilityName);
-  return structuredClone(capability.data_schema);
-}

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/module-upgrade.test.ts

@@ -1,11 +1,20 @@
 import { describe, expect, test } from 'bun:test';
+import type { ModuleManifest } from '../../manifest/schema';
 import {
   type PollCandidate,
+  needsPreUpgradeBackup,
   pickAutoUpgrade,
   pickUpgradePolicy,
   selectPollTargets,
 } from './module-upgrade';
 
+/** Minimal manifest fixture; only `hooks` matters for the backup gate. */
+function manifest(hooks?: ModuleManifest['hooks']): ModuleManifest {
+  return { id: 'forgejo', name: 'Forgejo', version: '0.3.0', hooks } as ModuleManifest;
+}
+const withBackupHook = manifest({ on_backup: { script: './scripts/backup.ts', timeout: 300000 } });
+const noBackupHook = manifest({ on_install: { script: './scripts/setup.ts', timeout: 180000 } });
+
 describe('pickUpgradePolicy (ISS-0138 — config override > manifest default > by-semver)', () => {
   test('operator config wins over the manifest default', () => {
     expect(pickUpgradePolicy('always-safe', 'always-fast')).toBe('always-safe');
@@ -80,3 +89,23 @@ describe('selectPollTargets (ISS-0139 — opted-in + a newer registry version)',
     expect(targets.map((t) => t.moduleId)).toEqual(['a']);
   });
 });
+
+describe('needsPreUpgradeBackup (ISS-0168 — gate on the TARGET version manifest)', () => {
+  // The regression: the upgrade that FIRST adds on_backup must still back up.
+  // The installed version lacked the hook; the target (passed here) adds it.
+  test('safe posture + target adds on_backup → backs up', () => {
+    expect(needsPreUpgradeBackup('safe', withBackupHook)).toBe(true);
+  });
+
+  test('safe posture + target has no on_backup → does not back up', () => {
+    expect(needsPreUpgradeBackup('safe', noBackupHook)).toBe(false);
+  });
+
+  test('fast posture (patch/revision) never backs up, even with on_backup', () => {
+    expect(needsPreUpgradeBackup('fast', withBackupHook)).toBe(false);
+  });
+
+  test('safe posture + no hooks block at all → does not back up', () => {
+    expect(needsPreUpgradeBackup('safe', manifest(undefined))).toBe(false);
+  });
+});

package/src/cli/commands/module-upgrade.ts

@@ -21,7 +21,11 @@ import { modules } from '../../db/schema';
 import type { ModuleManifest } from '../../manifest/schema';
 import { RegistryClient } from '../../registry/client';
 import { createModuleBackup } from '../../services/backup-create';
-import { type UpgradePolicy, resolveDeployPosture } from '../../services/deploy-posture';
+import {
+  type DeployPosture,
+  type UpgradePolicy,
+  resolveDeployPosture,
+} from '../../services/deploy-posture';
 import { runModuleHealthCheck } from '../../services/health-runner';
 import { getModuleConfigValue } from '../../services/module-config';
 import { deployModule } from '../../services/module-deploy';
@@ -62,6 +66,23 @@ export function pickAutoUpgrade(
   return fromManifest ?? false;
 }
 
+/**
+ * Pure (Rule 10): does this upgrade need a pre-deploy backup? Yes IFF the
+ * posture is "safe" (a minor/major bump) AND the TARGET version's manifest
+ * declares an on_backup hook.
+ *
+ * The `targetManifest` MUST be the version being upgraded TO (read back after
+ * the def is refreshed), never the installed one — gating on the installed
+ * manifest skips the backup on the very upgrade that introduces the hook
+ * (ISS-0168).
+ */
+export function needsPreUpgradeBackup(
+  posture: DeployPosture,
+  targetManifest: ModuleManifest,
+): boolean {
+  return posture === 'safe' && Boolean(targetManifest.hooks?.on_backup);
+}
+
 export interface PollCandidate {
   moduleId: string;
   installed: string;
@@ -116,13 +137,34 @@ async function upgradeOneModule(
   flags: Record<string, string | boolean>,
 ): Promise<CommandResult> {
   const moduleId = mod.id;
-  const manifest = mod.manifestData as ModuleManifest;
 
-  // Posture.
+  // Update FIRST (refresh stored def). Every downstream decision — the
+  // backup gate and the posture policy — must consult the TARGET version's
+  // manifest, not the installed one. Gating on the pre-update manifest skipped
+  // the on_backup hook on the very upgrade that INTRODUCES it (e.g. a stateful
+  // module that first ships backup support doesn't protect its own next
+  // upgrade) — ISS-0168.
+  const updated = await fetchAndUpdate(client, moduleId, targetVersion, db, flags);
+  if (updated.status !== 'success') {
+    const why = updated.status === 'failed' ? updated.error : updated.reason;
+    return { success: false, error: `Update failed for ${moduleId}: ${why}` };
+  }
+
+  // Read the target def back: fetchAndUpdate persisted it but doesn't return
+  // the manifest. Fall back to the pre-update manifest only if the row somehow
+  // vanished (it won't on the success path).
+  const updatedRow = db.select().from(modules).where(eq(modules.id, moduleId)).get();
+  const targetManifest =
+    (updatedRow?.manifestData as ModuleManifest | undefined) ??
+    (mod.manifestData as ModuleManifest);
+
+  // Posture. Version delta is installed→target; the policy comes from the
+  // TARGET manifest (the version being installed declares its upgrade risk),
+  // with an operator config override still winning.
   const configPolicy = getModuleConfigValue(moduleId, 'upgrade_policy');
   const modulePolicy = pickUpgradePolicy(
     typeof configPolicy?.value === 'string' ? configPolicy.value : undefined,
-    (manifest as ModuleManifest & { upgrade_policy?: string }).upgrade_policy,
+    (targetManifest as ModuleManifest & { upgrade_policy?: string }).upgrade_policy,
   );
   // Per-release deploy_posture override lives in the .netapp release metadata;
   // reading it requires fetching the package first. Deferred — the classifier
@@ -135,27 +177,18 @@ async function upgradeOneModule(
   });
   log.info(`Upgrading ${moduleId} ${mod.version} → ${targetVersion} (${posture} — ${reason})`);
 
-  // Update (refresh stored def).
-  const updated = await fetchAndUpdate(client, moduleId, targetVersion, db, flags);
-  if (updated.status !== 'success') {
-    const why = updated.status === 'failed' ? updated.error : updated.reason;
-    return { success: false, error: `Update failed for ${moduleId}: ${why}` };
-  }
-
-  // Safe → back up first (when there's a backup hook).
-  if (posture === 'safe') {
-    if (manifest.hooks?.on_backup) {
-      const backup = await createModuleBackup(moduleId);
-      if (!backup.success) {
-        return {
-          success: false,
-          error: `Pre-upgrade backup failed for ${moduleId}: ${backup.error}`,
-        };
-      }
-      log.success(`Backed up ${moduleId} before deploy`);
-    } else {
-      log.warn(`${moduleId} has no on_backup hook — proceeding without a pre-upgrade backup`);
+  // Safe → back up first, gated on the TARGET manifest's on_backup hook.
+  if (needsPreUpgradeBackup(posture, targetManifest)) {
+    const backup = await createModuleBackup(moduleId);
+    if (!backup.success) {
+      return {
+        success: false,
+        error: `Pre-upgrade backup failed for ${moduleId}: ${backup.error}`,
+      };
     }
+    log.success(`Backed up ${moduleId} before deploy`);
+  } else if (posture === 'safe') {
+    log.warn(`${moduleId} has no on_backup hook — proceeding without a pre-upgrade backup`);
   }
 
   // Deploy (idempotent).

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,140 @@
+/**
+ * `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) : '—';
+    // Only flag drift on a real mismatch — a null desired dimension means
+    // "unset / not yet seeded", not a pending resize.
+    const drift =
+      r.actual &&
+      ((r.desired.cpu != null && r.desired.cpu !== r.actual.cpu) ||
+        (r.desired.memMb != null && r.desired.memMb !== r.actual.memMb) ||
+        (r.desired.diskGb != null && r.desired.diskGb !== r.actual.diskGb))
+        ? '⚠ 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)` };
+}