@celilo/cli 0.5.0-alpha.0 → 0.5.0-alpha.10

package/src/api-clients/proxmox.ts

@@ -28,7 +28,7 @@ interface ProxmoxError {
   details?: Record<string, unknown>;
 }
 
-type ProxmoxResult<T> = { success: true; data: T } | ProxmoxError;
+export type ProxmoxResult<T> = { success: true; data: T } | ProxmoxError;
 
 /**
  * Make an authenticated API request to Proxmox
@@ -114,6 +114,18 @@ async function makeProxmoxRequest<T>(
         });
       });
 
+      // Fail fast instead of hanging on an unreachable host (no implicit timeout
+      // on https.request). Callers treat a failed result as "couldn't reach
+      // Proxmox" and fall back accordingly.
+      req.setTimeout(15_000, () => {
+        req.destroy();
+        resolve({
+          success: false,
+          message: 'Request timed out',
+          details: { timeoutMs: 15_000 },
+        });
+      });
+
       req.end();
     } catch (error) {
       resolve({
@@ -486,6 +498,146 @@ export async function listNodeStorage(
   return makeProxmoxRequest(credentials, `/nodes/${nodeName}/storage`);
 }
 
+/**
+ * Find which Proxmox node a given VMID currently lives on.
+ *
+ * Queries the cluster resource inventory (`/cluster/resources`), which lists
+ * every guest across all nodes with its current node, and matches by VMID
+ * (unique cluster-wide). Returns the node name, or `null` if the VMID isn't
+ * present — i.e. the container hasn't been created yet (a first deploy).
+ *
+ * ISS-0090: this is celilo's source of truth for WHERE a system currently is.
+ * A redeploy must target the node Proxmox reports here, NOT re-derive placement
+ * from the service's `default_target_node` (which only governs new placement) —
+ * otherwise a changed default tries to relocate every running container.
+ */
+export async function getNodeForVmid(
+  credentials: ProxmoxCredentials,
+  vmid: number,
+): Promise<ProxmoxResult<string | null>> {
+  // makeProxmoxRequest sends only url.pathname, so a `?type=vm` filter would be
+  // dropped — fetch the full inventory and match by vmid client-side instead.
+  const result = await makeProxmoxRequest<Array<{ vmid?: number; node?: string }>>(
+    credentials,
+    '/cluster/resources',
+  );
+
+  if (!result.success) {
+    return result;
+  }
+
+  return { success: true, data: findNodeForVmid(result.data, vmid) };
+}
+
+/**
+ * Find the node a VMID lives on within a Proxmox cluster-resource list. Pure
+ * matching logic, split out from the network call for testability (Rule 10).
+ * Non-guest entries (storage/node rows) have no `vmid` and are skipped. Returns
+ * the node name, or `null` when the VMID isn't present.
+ */
+export function findNodeForVmid(
+  resources: Array<{ vmid?: number; node?: string }>,
+  vmid: number,
+): string | null {
+  const match = resources.find((r) => typeof r.vmid === 'number' && r.vmid === vmid);
+  return match?.node ?? null;
+}
+
+/**
+ * One row from `GET /cluster/resources`. The list is heterogeneous — `type`
+ * discriminates node / storage / guest rows. For `type: 'node'`, `status` is
+ * 'online'/'offline' and the mem/cpu/disk fields describe the node's capacity;
+ * for guests it's 'running'/'stopped' and `vmid` is set.
+ */
+export interface ProxmoxClusterResource {
+  type: string;
+  node?: string;
+  status?: string;
+  vmid?: number;
+  maxmem?: number; // bytes (node total RAM)
+  mem?: number; // bytes (node RAM in use)
+  maxcpu?: number; // cores
+  cpu?: number; // load fraction 0..1
+  maxdisk?: number; // bytes (node total disk on the relevant storage)
+  disk?: number; // bytes (disk in use)
+  uptime?: number; // seconds
+}
+
+/** Per-node capacity reconciled from Proxmox (reality, never a cached DB value). */
+export interface ProxmoxNodeCapacity {
+  node: string;
+  online: boolean;
+  memTotalMb: number;
+  memFreeMb: number;
+  cpuCores: number;
+  cpuUsedPct: number; // 0..100
+  diskTotalGb: number;
+  diskFreeGb: number;
+  uptimeSec: number;
+}
+
+const BYTES_PER_MB = 1024 * 1024;
+const BYTES_PER_GB = 1024 * 1024 * 1024;
+
+/**
+ * Summarize per-node capacity from a `/cluster/resources` list. Pure (Rule 10) —
+ * split from the network call for unit testing. Only `type: 'node'` rows count;
+ * guest and storage rows are ignored. Sorted by node name for stable output.
+ */
+export function summarizeNodeCapacities(
+  resources: ProxmoxClusterResource[],
+): ProxmoxNodeCapacity[] {
+  return resources
+    .filter((r): r is ProxmoxClusterResource & { node: string } => r.type === 'node' && !!r.node)
+    .map((r) => {
+      const maxmem = r.maxmem ?? 0;
+      const mem = r.mem ?? 0;
+      const maxdisk = r.maxdisk ?? 0;
+      const disk = r.disk ?? 0;
+      return {
+        node: r.node,
+        online: r.status === 'online',
+        memTotalMb: Math.round(maxmem / BYTES_PER_MB),
+        memFreeMb: Math.round((maxmem - mem) / BYTES_PER_MB),
+        cpuCores: r.maxcpu ?? 0,
+        cpuUsedPct: Math.round((r.cpu ?? 0) * 100),
+        diskTotalGb: Math.round(maxdisk / BYTES_PER_GB),
+        diskFreeGb: Math.round((maxdisk - disk) / BYTES_PER_GB),
+        uptimeSec: r.uptime ?? 0,
+      };
+    })
+    .sort((a, b) => a.node.localeCompare(b.node));
+}
+
+/**
+ * Cohesive Proxmox introspection client (ISS-0060). Wraps the credentials so
+ * callers don't thread them through every call, and centralizes the live reads
+ * that let celilo treat Proxmox — not a cached DB row — as the source of truth
+ * for where containers live and how much room each node has.
+ */
+export class ProxmoxClient {
+  constructor(private readonly credentials: ProxmoxCredentials) {}
+
+  /** Raw cluster resource inventory (node + guest + storage rows). */
+  async clusterResources(): Promise<ProxmoxResult<ProxmoxClusterResource[]>> {
+    return makeProxmoxRequest<ProxmoxClusterResource[]>(this.credentials, '/cluster/resources');
+  }
+
+  /** Live per-node capacity (RAM/CPU/disk/online), reconciled from Proxmox. */
+  async nodeCapacities(): Promise<ProxmoxResult<ProxmoxNodeCapacity[]>> {
+    const result = await this.clusterResources();
+    if (!result.success) return result;
+    return { success: true, data: summarizeNodeCapacities(result.data) };
+  }
+
+  /** The node a VMID currently lives on, or null if it isn't created yet. */
+  async nodeForVmid(vmid: number): Promise<ProxmoxResult<string | null>> {
+    const result = await this.clusterResources();
+    if (!result.success) return result;
+    return { success: true, data: findNodeForVmid(result.data, vmid) };
+  }
+}
+
 /**
  * List available LXC templates in storage
  */
@@ -501,12 +653,11 @@ export async function listAvailableTemplates(
 }
 
 /**
- * Make an authenticated POST request to the Proxmox API.
- * Shares connection/auth handling with makeProxmoxRequest; the only differences
- * are the verb and the form-encoded body.
+ * Make an authenticated form-encoded request (POST or PUT) to the Proxmox API.
  */
-async function makeProxmoxPost<T>(
+async function makeProxmoxFormRequest<T>(
   credentials: ProxmoxCredentials,
+  method: 'POST' | 'PUT',
   path: string,
   params: Record<string, string>,
 ): Promise<ProxmoxResult<T>> {
@@ -519,7 +670,7 @@ async function makeProxmoxPost<T>(
       const postData = new URLSearchParams(params).toString();
 
       if (process.env.DEBUG) {
-        console.log(`[Proxmox] POST: ${fullUrl}`);
+        console.log(`[Proxmox] ${method}: ${fullUrl}`);
         console.log(`[Proxmox] Body: ${postData}`);
       }
 
@@ -530,7 +681,7 @@ async function makeProxmoxPost<T>(
           hostname: url.hostname,
           port: url.port || 443,
           path: url.pathname,
-          method: 'POST',
+          method,
           headers: {
             Authorization: authHeader,
             'Content-Type': 'application/x-www-form-urlencoded',
@@ -548,7 +699,7 @@ async function makeProxmoxPost<T>(
 
             if (statusCode < 200 || statusCode >= 300) {
               if (process.env.DEBUG || statusCode >= 400) {
-                console.error(`[Proxmox] POST ${path} failed (${statusCode}): ${body}`);
+                console.error(`[Proxmox] ${method} ${path} failed (${statusCode}): ${body}`);
               }
               resolve({
                 success: false,
@@ -592,6 +743,14 @@ async function makeProxmoxPost<T>(
   });
 }
 
+async function makeProxmoxPost<T>(
+  credentials: ProxmoxCredentials,
+  path: string,
+  params: Record<string, string>,
+): Promise<ProxmoxResult<T>> {
+  return makeProxmoxFormRequest(credentials, 'POST', path, params);
+}
+
 /**
  * Entry from Proxmox's appliance catalog (`pveam available`). The `template`
  * field is the canonical filename (revision included) that should be passed to
@@ -685,3 +844,292 @@ export function buildTemplatePath(storageName: string, templateFilename: string)
 export function buildProxmoxApiUrl(ipAddress: string, port = 8006): string {
   return `https://${ipAddress}:${port}/api2/json`;
 }
+
+// ── VM template build API ─────────────────────────────────────────────────────
+// Used by proxmox-vm-template-build.ts to build a cloud-init template via the
+// Proxmox API (no SSH to the node required).
+//
+// Version requirements (the build needs the HIGHER of the two — i.e. PVE 8.0+):
+//   - the storage `download-url` endpoint (downloadCloudImage)      → PVE 7.2+
+//   - `import-from=` on a disk in the VM-create call                → PVE 8.0+
+// On PVE 7.x the create call rejects `import-from`; the older two-step
+// `qm importdisk` flow would be needed there (not implemented — 8.x is current).
+// @psbanka - 2026-06: revisit only if a 7.x node must be supported.
+
+export interface ProxmoxVmTemplate {
+  vmid: number;
+  name: string;
+}
+
+/** Raw `/nodes/{node}/qemu` guest row (only the fields we read). */
+interface ProxmoxQemuGuestRow {
+  vmid: number;
+  name: string;
+  template?: number;
+}
+
+/**
+ * Extract VM templates (guests with `template === 1`) from a `/nodes/{node}/qemu`
+ * listing. Pure filtering logic, split from the network call for testability
+ * (Rule 10) — mirrors findNodeForVmid.
+ */
+export function filterVmTemplates(guests: ProxmoxQemuGuestRow[]): ProxmoxVmTemplate[] {
+  return guests.filter((vm) => vm.template === 1).map((vm) => ({ vmid: vm.vmid, name: vm.name }));
+}
+
+/** List existing VM templates on a node. */
+export async function listVmTemplates(
+  credentials: ProxmoxCredentials,
+  nodeName: string,
+): Promise<ProxmoxResult<ProxmoxVmTemplate[]>> {
+  const result = await makeProxmoxRequest<ProxmoxQemuGuestRow[]>(
+    credentials,
+    `/nodes/${nodeName}/qemu`,
+  );
+  if (!result.success) return result;
+  return { success: true, data: filterVmTemplates(result.data) };
+}
+
+/** Storage row shape (subset) used when picking import-capable storage. */
+type ProxmoxStorageRow = { storage: string; content: string; active: number; enabled: number };
+
+/**
+ * Pick the first active, enabled storage that accepts `import` content. Pure
+ * selection logic, split from the network call for testability (Rule 10).
+ * Returns the storage name, or null when none qualifies.
+ *
+ * Must be `import`, NOT `iso`: the cloud image is consumed via the VM-create
+ * `import-from=` parameter, which Proxmox only accepts from a source on a
+ * storage whose content type is `images` or `import`. A `.img` downloaded to
+ * the `iso/` namespace is rejected with `has wrong type 'iso'`. The
+ * `download-url` endpoint accepts `content=import` on PVE 8.2+, so we download
+ * straight into the import namespace. (PVE 8.2+; node fleet is 9.x.)
+ */
+export function selectImportStorage(storages: ProxmoxStorageRow[]): string | null {
+  const match = storages.find((s) => s.active && s.enabled && s.content.includes('import'));
+  return match?.storage ?? null;
+}
+
+/**
+ * Find a storage on the node that accepts `import` content (for downloading
+ * cloud images that will be imported as a VM disk). Returns the storage name,
+ * or null if none found.
+ */
+export async function findImportStorage(
+  credentials: ProxmoxCredentials,
+  nodeName: string,
+): Promise<ProxmoxResult<string | null>> {
+  const result = await listNodeStorage(credentials, nodeName);
+  if (!result.success) return result;
+  return { success: true, data: selectImportStorage(result.data) };
+}
+
+/**
+ * Pick the first free VMID >= minVmid given the set of in-use VMIDs. Pure
+ * selection logic, split from the network call for testability (Rule 10).
+ * Template VMIDs must stay outside celilo's IPAM range (200+) so they can
+ * never collide with deployed systems — hence minVmid defaults to 9000.
+ */
+export function selectFreeVmid(usedVmids: Iterable<number>, minVmid = 9000): number {
+  const used = new Set(usedVmids);
+  let candidate = minVmid;
+  while (used.has(candidate)) {
+    candidate++;
+  }
+  return candidate;
+}
+
+/**
+ * Find a free VMID >= minVmid (default 9000) across the cluster.
+ * Template VMIDs must stay outside celilo's IPAM range (200+) so they can
+ * never collide with deployed systems.
+ */
+export async function findFreeTemplateVmid(
+  credentials: ProxmoxCredentials,
+  _nodeName: string,
+  minVmid = 9000,
+): Promise<ProxmoxResult<number>> {
+  const result = await makeProxmoxRequest<Array<{ vmid?: number }>>(
+    credentials,
+    '/cluster/resources',
+  );
+  if (!result.success) return result;
+  const usedVmids = result.data
+    .map((r) => r.vmid)
+    .filter((vmid): vmid is number => typeof vmid === 'number');
+  return { success: true, data: selectFreeVmid(usedVmids, minVmid) };
+}
+
+/**
+ * Download a cloud image URL to `import` storage on the node. Returns a UPID
+ * for status polling. Requires PVE 8.2+ (`download-url` with `content=import`).
+ * The image MUST land in the import namespace (not iso) so the VM-create
+ * `import-from=` accepts it — see selectImportStorage.
+ */
+export async function downloadCloudImage(
+  credentials: ProxmoxCredentials,
+  nodeName: string,
+  importStorage: string,
+  url: string,
+  filename: string,
+): Promise<ProxmoxResult<string>> {
+  return makeProxmoxPost<string>(
+    credentials,
+    `/nodes/${nodeName}/storage/${importStorage}/download-url`,
+    { url, filename, content: 'import' },
+  );
+}
+
+/**
+ * Poll a task UPID until it reaches `stopped` status. Resolves with the
+ * exitstatus string (typically `'OK'` on success). Throws on timeout or a
+ * non-OK exitstatus.
+ *
+ * An empty/missing UPID means the API call completed synchronously (some PVE
+ * endpoints — e.g. converting a diskless VM to a template — return `null` data
+ * instead of a worker UPID). There is nothing to poll, so treat it as an
+ * immediate success rather than encoding the empty string and 404-ing on the
+ * task-status lookup.
+ */
+export async function pollTaskUntilDone(
+  credentials: ProxmoxCredentials,
+  nodeName: string,
+  upid: string,
+  timeoutMs = 600_000,
+): Promise<string> {
+  if (!upid) return 'OK';
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    await new Promise<void>((r) => setTimeout(r, 3_000));
+    const status = await checkTaskStatus(credentials, nodeName, upid);
+    if (!status.success) throw new Error(`Task poll failed: ${status.message}`);
+    if (status.data.status === 'stopped') {
+      const exit = status.data.exitstatus ?? 'unknown';
+      if (exit !== 'OK') throw new Error(`Task ${upid} failed with exitstatus: ${exit}`);
+      return exit;
+    }
+  }
+  throw new Error(`Task ${upid} timed out after ${timeoutMs / 1000}s`);
+}
+
+/**
+ * Build the volid for a cloud image downloaded to `import` storage. Pure path
+ * construction, split out for testability (Rule 10) — mirrors buildTemplatePath.
+ * Proxmox's `download-url` with `content=import` stores the `.img` under the
+ * storage's `import/` namespace, so the volid is `<storage>:import/<filename>`.
+ * This is the namespace the VM-create `import-from=` accepts (iso/ is rejected).
+ */
+export function buildCloudImageVolid(importStorage: string, filename: string): string {
+  return `${importStorage}:import/${filename}`;
+}
+
+export interface CreateVmFromCloudImageParams {
+  credentials: ProxmoxCredentials;
+  nodeName: string;
+  vmid: number;
+  name: string;
+  /** Volume ID of the downloaded cloud image, e.g. `local:import/noble-server-cloudimg-amd64.img` */
+  imageVolid: string;
+  /** Storage for the imported VM disk and the cloud-init drive */
+  diskStorage: string;
+}
+
+/**
+ * Create a VM and import the cloud image as its boot disk in one API call.
+ * Also attaches the cloud-init CDROM drive so terraform can inject credentials
+ * at clone time. Returns a UPID — poll with pollTaskUntilDone.
+ *
+ * `import-from=` in the disk spec requires PVE 8.0+ (see the version note at the
+ * top of this section). The `net0` bridge is hardcoded to `vmbr0` (the Proxmox
+ * default); it only governs the template's own NIC, which terraform overrides
+ * with `$system:network.bridge` at clone time — so it never reaches a deployed
+ * guest. @psbanka - 2026-06: parameterize if a non-vmbr0 node ever blocks the
+ * template build itself.
+ */
+export async function createVmFromCloudImage(
+  params: CreateVmFromCloudImageParams,
+): Promise<ProxmoxResult<string>> {
+  const { credentials, nodeName, vmid, name, imageVolid, diskStorage } = params;
+  return makeProxmoxPost<string>(credentials, `/nodes/${nodeName}/qemu`, {
+    vmid: String(vmid),
+    name,
+    memory: '2048',
+    cores: '2',
+    scsihw: 'virtio-scsi-pci',
+    net0: 'virtio,bridge=vmbr0',
+    agent: 'enabled=1',
+    serial0: 'socket',
+    vga: 'serial0',
+    boot: 'order=scsi0',
+    scsi0: `${diskStorage}:0,import-from=${imageVolid}`,
+    ide2: `${diskStorage}:cloudinit`,
+  });
+}
+
+/**
+ * Convert an existing VM to a template. Returns a UPID — the VM must be
+ * powered off. Poll with pollTaskUntilDone.
+ */
+export async function convertVmToTemplate(
+  credentials: ProxmoxCredentials,
+  nodeName: string,
+  vmid: number,
+): Promise<ProxmoxResult<string>> {
+  return makeProxmoxPost<string>(credentials, `/nodes/${nodeName}/qemu/${vmid}/template`, {});
+}
+
+/**
+ * Delete a VM (cleanup on build failure). Returns a UPID.
+ * Passes `purge=1` so storage volumes are also removed.
+ */
+export async function deleteVm(
+  credentials: ProxmoxCredentials,
+  nodeName: string,
+  vmid: number,
+): Promise<ProxmoxResult<string>> {
+  return new Promise((resolve) => {
+    try {
+      const { api_url, api_token_id, api_token_secret } = credentials;
+      const authHeader = `PVEAPIToken=${api_token_id}=${api_token_secret}`;
+      const fullUrl = `${api_url}/nodes/${nodeName}/qemu/${vmid}`;
+      const url = new URL(fullUrl);
+      const agent = new https.Agent({ rejectUnauthorized: false });
+      const req = https.request(
+        {
+          hostname: url.hostname,
+          port: url.port || 443,
+          path: `${url.pathname}?purge=1`,
+          method: 'DELETE',
+          headers: { Authorization: authHeader },
+          agent,
+        },
+        (res) => {
+          let body = '';
+          res.on('data', (chunk) => {
+            body += chunk;
+          });
+          res.on('end', () => {
+            const statusCode = res.statusCode || 0;
+            if (statusCode < 200 || statusCode >= 300) {
+              resolve({
+                success: false,
+                message: `Delete failed with status ${statusCode}: ${body}`,
+              });
+              return;
+            }
+            try {
+              const data = JSON.parse(body) as ProxmoxApiResponse<string>;
+              resolve({ success: true, data: data.data });
+            } catch {
+              resolve({ success: true, data: '' });
+            }
+          });
+        },
+      );
+      req.on('error', (error) => resolve({ success: false, message: error.message }));
+      req.end();
+    } catch (error) {
+      resolve({ success: false, message: error instanceof Error ? error.message : String(error) });
+    }
+  });
+}

package/src/cli/command-registry.ts

@@ -106,6 +106,11 @@ export const COMMANDS: CommandDef[] = [
         ],
       },
       { name: 'list-subscribers', description: 'List persistent bus subscribers' },
+      {
+        name: 'resync-subscriptions',
+        description:
+          "Rebuild subscribers from deployed modules' manifests (after a restore/migration)",
+      },
       {
         name: 'list-pending',
         description: 'List pending deliveries',
@@ -227,7 +232,7 @@ export const COMMANDS: CommandDef[] = [
       },
       {
         name: 'install-daemon',
-        description: 'Write a systemd/launchd user unit for the dispatcher',
+        description: 'Write a systemd/launchd unit for the dispatcher',
         flags: [
           {
             name: 'celilo-path',
@@ -237,15 +242,47 @@ export const COMMANDS: CommandDef[] = [
           },
           { name: 'poll-ms', description: 'Polling interval in ms', takesValue: true },
           { name: 'concurrency', description: 'Max parallel handlers', takesValue: true },
+          {
+            name: 'system',
+            description:
+              'System scope: /etc/systemd/system unit or /Library/LaunchDaemons plist, run as the celilo state-dir owner (management-plane shape)',
+            takesValue: false,
+          },
+          {
+            name: 'print',
+            description:
+              'Render the unit to stdout without writing it (used by the celilo-mgmt role)',
+            takesValue: false,
+          },
         ],
       },
       {
         name: 'uninstall-daemon',
         description: 'Remove the installed supervisor unit',
+        flags: [{ name: 'system', description: 'Target the system-scope unit', takesValue: false }],
       },
       {
         name: 'show-daemon',
         description: 'Print the currently installed unit file',
+        flags: [{ name: 'system', description: 'Target the system-scope unit', takesValue: false }],
+      },
+    ],
+  },
+  {
+    name: 'dns',
+    description: 'View DNS bookkeeping (registrations ledger)',
+    subcommands: [
+      {
+        name: 'registrations',
+        description: 'List the DNS registration ledger',
+        flags: [
+          {
+            name: 'provider',
+            description: 'Only show registrations owned by one provider module',
+            takesValue: true,
+            valueHint: 'module_ids',
+          },
+        ],
       },
     ],
   },
@@ -629,8 +666,16 @@ export const COMMANDS: CommandDef[] = [
             description: 'Add Proxmox container service',
             flags: [
               { name: 'api-url', description: 'Proxmox API URL', takesValue: true },
-              { name: 'token-id', description: 'API token ID', takesValue: true },
-              { name: 'token-secret', description: 'API token secret', takesValue: true },
+              {
+                name: 'api-token-id',
+                description: 'API token ID (or $PROXMOX_API_TOKEN_ID)',
+                takesValue: true,
+              },
+              {
+                name: 'api-token-secret',
+                description: 'API token secret (or $PROXMOX_API_TOKEN_SECRET)',
+                takesValue: true,
+              },
               { name: 'node', description: 'Target node', takesValue: true },
               {
                 name: 'zone',
@@ -645,7 +690,11 @@ export const COMMANDS: CommandDef[] = [
             name: 'digitalocean',
             description: 'Add DigitalOcean container service',
             flags: [
-              { name: 'api-token', description: 'DigitalOcean API token', takesValue: true },
+              {
+                name: 'api-token',
+                description: 'DigitalOcean API token (or $DIGITALOCEAN_API_TOKEN)',
+                takesValue: true,
+              },
               { name: 'region', description: 'Region', takesValue: true },
               {
                 name: 'zone',
@@ -919,14 +968,25 @@ export const COMMANDS: CommandDef[] = [
           },
         ],
       },
+      {
+        name: 'migrate',
+        description: 'Apply pending database migrations (idempotent; safe to re-run)',
+      },
       {
         name: 'doctor',
-        description: 'Diagnose system prerequisites and @celilo/* version drift',
+        description:
+          'Diagnose system prerequisites, @celilo/* version drift, and (on a management plane) fleet-runtime drift',
         flags: [
           {
             name: 'fix',
             description:
-              'Repair drift by `bun link`-ing each drifted @celilo/* package from the workspace',
+              'Repair the auto-fixable findings: `bun link` drifted @celilo/* packages and resync bus subscribers',
+            takesValue: false,
+          },
+          {
+            name: 'fleet',
+            description:
+              'Force the fleet-runtime section (dispatcher, subscribers, capability chains) even without a celilo DB',
             takesValue: false,
           },
         ],
@@ -1009,6 +1069,23 @@ export const COMMANDS: CommandDef[] = [
       },
     ],
   },
+  {
+    name: 'proxmox',
+    description: 'Proxmox cluster introspection (nodes, capacity)',
+    subcommands: [
+      {
+        name: 'node',
+        description: 'Proxmox node operations',
+        subcommands: [
+          {
+            name: 'list',
+            description: 'List cluster nodes with live capacity (RAM/CPU/disk)',
+            args: [{ name: 'service-id', description: 'Proxmox service (optional if only one)' }],
+          },
+        ],
+      },
+    ],
+  },
   {
     name: 'subscribers',
     description: 'Manage build-bus subscribers (cross-machine publish-event delivery)',