@celilo/cli 0.22.0 → 0.24.0

package/src/cli/commands/backup-list.test.ts

@@ -0,0 +1,83 @@
+/**
+ * The per-module recovery summary under `celilo backup list`.
+ *
+ * The listing itself is a log of attempts, and on celilo-mgr a column of
+ * `✗ 0 B` rows on a tidy hourly rhythm was true for a day while forgejo had no
+ * usable backup at all (celilo#685). These assert the two facts that column
+ * structurally cannot carry: `never`, and how much has failed since.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import type { Backup } from '../../db/schema';
+import { backedUpModuleIds, lastSuccessSummaryLines } from './backup-list';
+
+const NOW = Date.UTC(2026, 7, 13, 12, 0, 0);
+const ago = (ms: number) => new Date(NOW - ms);
+const HOUR = 60 * 60 * 1000;
+
+function backup(partial: Partial<Backup>): Backup {
+  return { backupType: 'module_data', moduleId: 'forgejo', ...partial } as Backup;
+}
+
+describe('backedUpModuleIds', () => {
+  test('deduplicates and sorts the modules a listing names', () => {
+    expect(
+      backedUpModuleIds([
+        backup({ moduleId: 'forgejo' }),
+        backup({ moduleId: 'authentik' }),
+        backup({ moduleId: 'forgejo' }),
+      ]),
+    ).toEqual(['authentik', 'forgejo']);
+  });
+
+  test('ignores system backups, which have no module and no cadence', () => {
+    expect(
+      backedUpModuleIds([
+        backup({ backupType: 'system_state', moduleId: null }),
+        backup({ moduleId: 'forgejo' }),
+      ]),
+    ).toEqual(['forgejo']);
+  });
+});
+
+describe('lastSuccessSummaryLines', () => {
+  test('says never, out loud, when a module has never been captured', () => {
+    // `signal` on celilo-mgr. A listing of its attempts shows rows on a
+    // schedule; none of them is a backup.
+    const [line] = lastSuccessSummaryLines(
+      [{ moduleId: 'signal', lastSuccessAt: null, consecutiveFailures: 8 }],
+      NOW,
+    );
+    expect(line).toContain('signal');
+    expect(line).toContain('never');
+    expect(line).toContain('8 failed attempts since');
+  });
+
+  test('reports how stale a real success is, with the failures since it', () => {
+    const [line] = lastSuccessSummaryLines(
+      [{ moduleId: 'forgejo', lastSuccessAt: ago(7 * 24 * HOUR), consecutiveFailures: 20 }],
+      NOW,
+    );
+    // The existing relative formatter buckets 7 days as "last week".
+    expect(line).toContain('last week');
+    expect(line).toContain('20 failed attempts since');
+  });
+
+  test('a healthy module carries no failure clause at all', () => {
+    const [line] = lastSuccessSummaryLines(
+      [{ moduleId: 'authentik', lastSuccessAt: ago(3 * HOUR), consecutiveFailures: 0 }],
+      NOW,
+    );
+    expect(line).toContain('3h ago');
+    expect(line).not.toContain('failed');
+  });
+
+  test('counts one failure in the singular', () => {
+    const [line] = lastSuccessSummaryLines(
+      [{ moduleId: 'caddy', lastSuccessAt: ago(2 * HOUR), consecutiveFailures: 1 }],
+      NOW,
+    );
+    expect(line).toContain('1 failed attempt since');
+    expect(line).not.toContain('attempts');
+  });
+});

package/src/cli/commands/backup-list.ts

@@ -3,7 +3,13 @@
  * Lists available backups with metadata.
  */
 
-import { formatSize, getBackup, listBackups } from '../../services/backup-metadata';
+import type { Backup } from '../../db/schema';
+import {
+  formatSize,
+  getBackup,
+  listBackups,
+  loadBackupHistory,
+} from '../../services/backup-metadata';
 import { getBackupStorage } from '../../services/backup-storage';
 import { celiloIntro } from '../prompts';
 import type { CommandResult } from '../types';
@@ -12,8 +18,7 @@ import type { CommandResult } from '../types';
  * Format a timestamp as a human-friendly relative string.
  * Uses relative terms for recent backups and dates for older ones.
  */
-function formatRelativeDate(date: Date): string {
-  const now = Date.now();
+function formatRelativeDate(date: Date, now: number = Date.now()): string {
   const diffMs = now - date.getTime();
   const diffMins = Math.floor(diffMs / 60_000);
   const diffHours = Math.floor(diffMs / 3_600_000);
@@ -73,6 +78,64 @@ function showBackupDetail(backupId: string): CommandResult {
   return { success: true, message: `Backup detail: ${backupId}` };
 }
 
+/**
+ * Say, per module, when its data was last actually captured.
+ *
+ * The listing above is a log of ATTEMPTS, and an attempt log is the one thing
+ * that cannot answer the question an operator is really asking. On celilo-mgr
+ * the forgejo rows read:
+ *
+ *   ✗ 17cedba4  forgejo      0 B        1h ago
+ *   ✗ 99a9f819  forgejo      0 B        2h ago
+ *   ✗ fbb4d355  forgejo      0 B        3h ago
+ *
+ * — a tidy hourly cadence, every row on time, and not one byte of backup
+ * anywhere in it. Regular failure and regular success have the same silhouette
+ * at a glance; the `✗` is one character wide and the rhythm is what the eye
+ * reads. That listing was true for a day while production had no forgejo
+ * backup at all (celilo#685).
+ *
+ * So the recovery question gets answered directly rather than left to be
+ * inferred from a column of marks. `never` and a failure count are the two
+ * facts a column of attempts structurally cannot show.
+ *
+ * System backups are skipped: they are not per-module and have no cadence.
+ */
+function printLastSuccessSummary(backupList: Backup[]): void {
+  const moduleIds = backedUpModuleIds(backupList);
+  if (moduleIds.length === 0) return;
+
+  const lines = lastSuccessSummaryLines(
+    moduleIds.map((moduleId) => ({ moduleId, ...loadBackupHistory(moduleId) })),
+    Date.now(),
+  );
+  console.log('\nLast successful backup:');
+  for (const line of lines) console.log(line);
+}
+
+/** The modules named by a listing, deduplicated. System rows have no module. */
+export function backedUpModuleIds(backupList: Backup[]): string[] {
+  const ids = backupList
+    .filter((b) => b.backupType === 'module_data' && b.moduleId)
+    .map((b) => b.moduleId as string);
+  return [...new Set(ids)].sort();
+}
+
+/** One line per module: when it was last captured, and what has failed since. */
+export function lastSuccessSummaryLines(
+  entries: Array<{ moduleId: string; lastSuccessAt: Date | null; consecutiveFailures: number }>,
+  now: number,
+): string[] {
+  return entries.map(({ moduleId, lastSuccessAt, consecutiveFailures }) => {
+    const when = lastSuccessAt ? formatRelativeDate(lastSuccessAt, now) : 'never';
+    const since =
+      consecutiveFailures > 0
+        ? `  (${consecutiveFailures} failed attempt${consecutiveFailures === 1 ? '' : 's'} since)`
+        : '';
+    return `  ${moduleId.padEnd(20)} ${when}${since}`;
+  });
+}
+
 export async function handleBackupList(
   args: string[],
   flags: Record<string, boolean | string> = {},
@@ -120,6 +183,7 @@ export async function handleBackupList(
     }
 
     console.log(`\n${backupList.length} backup${backupList.length === 1 ? '' : 's'} shown.`);
+    printLastSuccessSummary(backupList);
     console.log('Run "celilo backup list <id>" for details.\n');
 
     return { success: true, message: `Found ${backupList.length} backup(s)` };

package/src/cli/commands/backup-prune.ts

@@ -8,7 +8,12 @@ import { getDb } from '../../db/client';
 import { modules } from '../../db/schema';
 import type { ModuleManifest } from '../../manifest/schema';
 import { findBackupEligibleModules } from '../../services/backup-create';
-import { pruneBackupsForModule } from '../../services/backup-retention';
+import {
+  effectiveBackupRetention,
+  pruneBackupsForModule,
+  prunesNothing,
+} from '../../services/backup-retention';
+import { loadModuleConfigs } from '../../services/module-config';
 import { celiloIntro, celiloOutro } from '../prompts';
 import type { CommandResult } from '../types';
 
@@ -37,17 +42,16 @@ export async function handleBackupPrune(
       }
 
       const manifest = mod.manifestData as unknown as ModuleManifest;
-      const retention = manifest.backup?.retention;
-      if (!retention) {
-        console.log(`Module '${specificModule}' has no retention policy defined.`);
+      const policy = effectiveBackupRetention(manifest, loadModuleConfigs(db, specificModule));
+      if (prunesNothing(policy)) {
+        console.log(
+          `Module '${specificModule}' has no retention policy — every backup is kept.\n` +
+            `Set one with: celilo module config set ${specificModule} backup_retention_count <n>`,
+        );
         return { success: true, message: 'No retention policy' };
       }
 
-      const result = await pruneBackupsForModule(
-        specificModule,
-        { count: retention.count, maxAgeDays: retention.max_age_days },
-        dryRun,
-      );
+      const result = await pruneBackupsForModule(specificModule, policy, dryRun);
 
       if (result.deleted > 0) {
         const verb = dryRun ? 'Would delete' : 'Deleted';
@@ -63,15 +67,11 @@ export async function handleBackupPrune(
       // Prune all modules with retention policies
       const eligible = findBackupEligibleModules();
 
-      for (const { module: mod, manifest } of eligible) {
-        const retention = manifest.backup?.retention;
-        if (!retention) continue;
+      for (const { module: mod, manifest, configs } of eligible) {
+        const policy = effectiveBackupRetention(manifest, configs);
+        if (prunesNothing(policy)) continue;
 
-        const result = await pruneBackupsForModule(
-          mod.id,
-          { count: retention.count, maxAgeDays: retention.max_age_days },
-          dryRun,
-        );
+        const result = await pruneBackupsForModule(mod.id, policy, dryRun);
 
         if (result.deleted > 0) {
           const verb = dryRun ? 'Would delete' : 'Deleted';

package/src/cli/commands/backup-sweep.ts

@@ -18,13 +18,19 @@ import {
   isBackupDue,
 } from '../../services/backup-create';
 import { failBackup, getBackup, listInProgressBackups } from '../../services/backup-metadata';
-import { pruneBackupsForModule } from '../../services/backup-retention';
+import {
+  effectiveBackupRetention,
+  pruneBackupsForModule,
+  prunesNothing,
+} from '../../services/backup-retention';
+import { BACKUP_SCHEDULE_CONFIG_KEY } from '../../services/backup-schedule';
 import {
   STAGING_PREFIX,
   reapOrphanedStaging,
   resolveAbandonedBackups,
 } from '../../services/backup-staging';
 import { type BackupSweepReport, runBackupSweep } from '../../services/backup-sweep';
+import { configOverride } from '../../services/module-config';
 import { isPidRunnable } from '../../services/module-operations';
 import type { CommandResult } from '../types';
 
@@ -79,20 +85,26 @@ function resolveAbandonedRecords() {
 }
 
 export async function handleBackupSweep(): Promise<CommandResult> {
+  // Read once, so the cadence the sweep schedules on and the retention it
+  // prunes with come from the same snapshot of the operator's config.
+  const eligible = findBackupEligibleModules();
+  const configsByModule = new Map(eligible.map(({ module, configs }) => [module.id, configs]));
+
   const report = await runBackupSweep({
     reapStaging,
     resolveAbandonedRecords,
     listEligible: () =>
-      findBackupEligibleModules().map(({ module, manifest }) => ({ id: module.id, manifest })),
+      eligible.map(({ module, manifest, configs }) => ({
+        id: module.id,
+        manifest,
+        scheduleOverride: configOverride(configs, BACKUP_SCHEDULE_CONFIG_KEY),
+      })),
     isDue: (moduleId, schedule) => isBackupDue(moduleId, schedule),
     backup: (moduleId) => createModuleBackup(moduleId),
     prune: async ({ id, manifest }) => {
-      const retention = manifest.backup?.retention;
-      if (!retention) return;
-      await pruneBackupsForModule(id, {
-        count: retention.count,
-        maxAgeDays: retention.max_age_days,
-      });
+      const policy = effectiveBackupRetention(manifest, configsByModule.get(id));
+      if (prunesNothing(policy)) return;
+      await pruneBackupsForModule(id, policy);
     },
   });
 

package/src/cli/commands/events.ts

@@ -55,7 +55,7 @@ import {
   unitInstalledInAnyScope,
 } from '../../services/events-daemon';
 import { getArg, hasFlag } from '../parser';
-import type { CommandResult } from '../types';
+import type { CommandResult, CommandSuccess } from '../types';
 
 const NO_SCHEMAS = defineEvents({});
 
@@ -63,10 +63,16 @@ function openCliBus() {
   return openBus({ dbPath: getEventBusPath(), events: NO_SCHEMAS });
 }
 
+/**
+ * Every `celilo events` JSON verb returns through here, so `rawOutput` is set
+ * once: without it the payload goes through the CLI's decorating renderer and
+ * reaches stdout prefixed and re-wrapped, and no longer parses.
+ */
 function jsonResult(data: unknown): CommandResult {
   return {
     success: true,
     message: JSON.stringify(data, null, 2),
+    rawOutput: true,
     data,
   };
 }
@@ -123,6 +129,26 @@ export async function handleEventsRunHook(args: string[]): Promise<CommandResult
   const module = db.select().from(modules).where(eq(modules.id, moduleId)).get();
   if (!module) return { success: false, error: `Module not found: ${moduleId}` };
 
+  // Quiescence (openspec/changes/module-pause-lifecycle, task 2.1/2.2). Pausing
+  // drops the module's bus subscriptions, so ordinarily nothing reaches here at
+  // all; this is the second line, and it is load-bearing rather than belt-and-
+  // braces. The subscribers table lives in a DIFFERENT database (events.db) to
+  // the module state, so the two can disagree — `events resync-subscriptions`
+  // rebuilds subscribers from celilo.db, a restore starts events.db empty, and
+  // a hand-written row is always possible. Every one of those paths ends here,
+  // where the module's actual state is readable.
+  //
+  // Success, not failure: the event was delivered correctly and the module is
+  // deliberately not listening. Reporting a failure would retry it up to
+  // max_attempts and then surface as an alert about the pause the operator
+  // themselves took.
+  if (module.state === 'PAUSED') {
+    return {
+      success: true,
+      message: `Skipped ${moduleId}.${subName}: module is paused`,
+    };
+  }
+
   const manifest = module.manifestData as ModuleManifest;
   const sub = (manifest.subscriptions ?? []).find((s) => s.name === subName);
   if (!sub) {
@@ -882,7 +908,7 @@ async function runProgrammaticResponder(
 
   let stopping = false;
   let stopReason: 'idle' | 'max-duration' | 'signal' = 'idle';
-  const buildSummary = (): { success: true; message: string; data: unknown } => {
+  const buildSummary = (): CommandSuccess => {
     if (!stopping) {
       stopping = true;
       handle.close();
@@ -893,7 +919,12 @@ async function runProgrammaticResponder(
       answered: handle.answered(),
       missed: handle.missed(),
     };
-    return { success: true, message: JSON.stringify(summary, null, 2), data: summary };
+    return {
+      success: true,
+      message: JSON.stringify(summary, null, 2),
+      rawOutput: true,
+      data: summary,
+    };
   };
 
   process.on('SIGINT', () => {

package/src/cli/commands/firewall-interface-list.test.ts

@@ -0,0 +1,85 @@
+/**
+ * §8.2 — the classification, on demand.
+ *
+ * The value of this command is entirely in what it SAYS, so that is what these
+ * assert: the role of every interface, and — for anything unaccounted for —
+ * what the next converge will actually do about it. "1 alien interface" with no
+ * further guidance would repeat the failure this whole change is about, which
+ * was never a lack of information but a lack of celilo saying it.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+let testDir: string;
+let logs: string[];
+const originalLog = console.log;
+
+/** Capture stdout — the command's output IS its contract. */
+function captureLogs() {
+  logs = [];
+  console.log = (...args: unknown[]) => {
+    logs.push(args.map(String).join(' '));
+  };
+}
+
+beforeEach(() => {
+  testDir = mkdtempSync(join(tmpdir(), 'celilo-fw-iface-'));
+  process.env.CELILO_DB_PATH = join(testDir, 'test.db');
+  process.env.CELILO_DATA_DIR = testDir;
+  captureLogs();
+});
+
+afterEach(() => {
+  console.log = originalLog;
+  rmSync(testDir, { recursive: true, force: true });
+  process.env.CELILO_DB_PATH = undefined;
+});
+
+describe('celilo firewall interface list', () => {
+  test('an empty pool says so, and says what makes a machine a firewall', async () => {
+    const { handleFirewallInterfaceList } = await import('./firewall-interface-list');
+    const result = await handleFirewallInterfaceList([], {});
+
+    expect(result.success).toBe(false);
+    if (result.success) throw new Error('unreachable — asserted above');
+    expect(result.error).toContain('No firewalls');
+    // Not a dead end: it explains the rule rather than leaving the operator to
+    // guess why their box is not listed.
+    expect(result.error).toContain('router');
+  });
+
+  test('a named machine that does not exist names it, and points at machine list', async () => {
+    const { handleFirewallInterfaceList } = await import('./firewall-interface-list');
+    const result = await handleFirewallInterfaceList(['no-such-box'], {});
+
+    expect(result.success).toBe(false);
+    if (result.success) throw new Error('unreachable — asserted above');
+    expect(result.error).toContain('no-such-box');
+    expect(result.error).toContain('celilo machine list');
+  });
+});
+
+/**
+ * The classification itself is `@celilo/capabilities`' job and is tested there
+ * against far more cases than a CLI test should duplicate.
+ *
+ * What is worth pinning here is STRUCTURAL. Asserting the wording of the output
+ * by grepping this command's own source would just be reading my strings back to
+ * me — it would pass no matter what they said. The property below is different:
+ * it is a claim about what the command may DO, and it can genuinely fail.
+ */
+describe('read-only by construction', () => {
+  test('never touches the box', async () => {
+    // Safe to run against a firewall whose converge is currently refusing —
+    // which is exactly when an operator reaches for it. If this ever grows an
+    // SSH call it is a different command and should be named like one.
+    const src = await Bun.file(join(import.meta.dir, 'firewall-interface-list.ts')).text();
+
+    expect(src).not.toContain('runAppCommand');
+    expect(src).not.toContain('execFileSync');
+    expect(src).not.toContain('ssh ');
+  });
+});

package/src/cli/commands/firewall-interface-list.ts

@@ -0,0 +1,123 @@
+/**
+ * `celilo firewall interface list [<hostname>]`
+ *
+ * The interface classification, on demand, with no side effects.
+ *
+ * A converge already refuses or isolates on what it finds — but only when it
+ * runs, and only in the middle of a deploy's output. An operator about to
+ * onboard a firewall, or wondering why one refused, needs to be able to ASK.
+ * The condition that produced `fw-keeper.sh` was not that celilo lacked the
+ * information; it was that celilo never said it.
+ *
+ * Read-only by construction: it reads the stored interface table and the
+ * declarations, and classifies in memory. It never touches the box, so it is
+ * safe to run against a firewall that is currently refusing.
+ */
+
+import { classifyInterfaces, isPubliclyRoutable } from '@celilo/capabilities';
+import { getDb } from '../../db/client';
+import { listFirewallIps, readDeclaredNetworks } from '../../hooks/capability-loader';
+import { listMachines } from '../../services/machine-pool';
+import { celiloIntro } from '../prompts';
+import type { CommandResult } from '../types';
+
+/**
+ * Every network a subnet is declared for — THE same reader the converge uses.
+ *
+ * This command's whole value is telling an operator what the next converge will
+ * do, so reading declarations a second way is not a duplication smell, it is a
+ * correctness bug: this file walked `NETWORK_ZONES` and so could not see
+ * `network.control-plane-vpn.subnet`. It would have reported `wg0` as ALIEN —
+ * "this will be isolated" — about an interface the converge attributes and
+ * leaves alone. The operator's most likely response to that reading is to go
+ * and remove their own admin VPN.
+ */
+async function declaredZones(): Promise<Array<{ zone: string; subnet: string }>> {
+  return readDeclaredNetworks(getDb());
+}
+
+/** One line per interface, explaining the role rather than just naming it. */
+function describe(role: string, zone: string | undefined, ip: string): string {
+  if (role === 'zone') return `zone:${zone}`;
+  if (role === 'external') return 'external — the WAN edge';
+  return isPubliclyRoutable(ip)
+    ? 'ALIEN — publicly routable but no declared zone claims it'
+    : 'ALIEN — no declared subnet contains it';
+}
+
+export async function handleFirewallInterfaceList(
+  args: string[],
+  _flags: Record<string, boolean | string> = {},
+): Promise<CommandResult> {
+  celiloIntro('Firewall interfaces');
+
+  const wanted = args[0];
+  const machines = await listMachines();
+  // A firewall is a machine a firewall provider MANAGES. `role === 'router'` is
+  // kept as a second way in, but it cannot be the only one: the role is decided
+  // by `machine add` from the zones declared at that moment, and the normal
+  // order is to add the machine and THEN deploy iptables, whose `on_install`
+  // writes the zone subnets. So a working firewall is recorded as a plain host,
+  // and this command — whose entire purpose is to report on firewalls — answered
+  // "No firewalls in the machine pool" on a fleet that had one.
+  //
+  // Named explicitly, the hostname wins, so an operator can inspect any box.
+  const firewallIps = new Set(await listFirewallIps(getDb()));
+  const targets = wanted
+    ? machines.filter((m) => m.hostname === wanted)
+    : machines.filter((m) => firewallIps.has(m.ipAddress) || m.role === 'router');
+
+  if (targets.length === 0) {
+    return {
+      success: false,
+      error: wanted
+        ? `No machine named "${wanted}". Run \`celilo machine list\` to see the pool.`
+        : 'No firewalls in the machine pool. celilo looks for a machine managed by a firewall provider, or one it classified as a router.',
+    };
+  }
+
+  const zones = await declaredZones();
+  if (zones.length === 0) {
+    console.log(
+      'No zone subnets are declared, so every interface will read as unaccounted for.\n' +
+        'Declare them with: celilo system config set network.<zone>.subnet <cidr>\n',
+    );
+  }
+
+  let alienTotal = 0;
+  for (const machine of targets) {
+    console.log(`\n${machine.hostname} (${machine.ipAddress})`);
+
+    const interfaces = (machine.interfaces ?? []).map((i) => ({
+      name: i.name,
+      ip: i.ipAddress,
+    }));
+    if (interfaces.length === 0) {
+      console.log('  no interfaces recorded — re-run `celilo machine add` to detect them');
+      continue;
+    }
+
+    for (const c of classifyInterfaces(interfaces, zones)) {
+      if (c.role === 'alien') alienTotal += 1;
+      console.log(`  ${c.name.padEnd(8)} ${c.ip.padEnd(16)} ${describe(c.role, c.zone, c.ip)}`);
+    }
+  }
+
+  console.log('');
+  if (alienTotal > 0) {
+    // Say what will HAPPEN, not merely what was found — the answer differs by
+    // whether celilo has a baseline for the box, and that is the thing an
+    // operator most needs to know before the next converge.
+    const consequence = [
+      'On a firewall celilo has not yet converged cleanly, the next converge will REFUSE and change nothing.',
+      'On one with a recorded baseline, an interface that appeared since will be isolated.',
+      'Resolve either by declaring a zone: celilo system config set network.<zone>.subnet <cidr>',
+    ].join('\n');
+    console.log(`${alienTotal} interface(s) celilo cannot attribute.\n${consequence}`);
+  }
+
+  return {
+    success: true,
+    message: alienTotal === 0 ? 'every interface accounted for' : `${alienTotal} unaccounted`,
+  };
+}

package/src/cli/commands/machine-add.ts

@@ -6,6 +6,7 @@
 import { existsSync } from 'node:fs';
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { isPubliclyRoutable } from '@celilo/capabilities';
 import { getDb } from '../../db/client';
 import type { NetworkZone } from '../../db/schema';
 import { askText, withInterviewSession } from '../../services/bus-interview';
@@ -16,6 +17,7 @@ import {
   detectNetworkInterfacesLocal,
   testSshConnection,
 } from '../../services/machine-detector';
+import { describeInterfaceZone } from '../../services/machine-detector';
 import { addMachine, getMachineByIp } from '../../services/machine-pool';
 import { loadExistingConfiguration } from '../../services/system-init';
 import { detectZoneFromIp } from '../../services/zone-detector';
@@ -242,8 +244,34 @@ export async function handleMachineAdd(
         console.log(`  Disk: ${detectedInfo.hardware.disk_gb} GB\n`);
 
         // Zone: explicit override, else infer from IP.
+        //
+        // `detectZoneFromIp` answers containment only, and now says `'unknown'`
+        // rather than claiming `external` when nothing matches. Resolving that
+        // is a SECOND question — is this address one the internet can route to?
+        // — and the two were conflated before, which is how a private address in
+        // no declared subnet got labelled as facing the internet.
         console.log('Detecting network zone...');
-        zone = zoneOverride ?? (await detectZoneFromIp(ipAddress));
+        if (zoneOverride) {
+          zone = zoneOverride;
+        } else {
+          const detected = await detectZoneFromIp(ipAddress);
+          if (detected !== 'unknown') {
+            zone = detected;
+          } else if (isPubliclyRoutable(ipAddress)) {
+            // No declared subnet contains it and the internet can route to it:
+            // that is what `external` means — a cloud/VPS box.
+            zone = 'external';
+          } else {
+            // A private address in no declared subnet is UN-ZONEABLE, not
+            // external. Guessing here is the original defect; ask instead.
+            const fix =
+              'Fix: pass --zone <zone>, or declare the subnet with `celilo system config set network.<zone>.subnet <cidr>` and retry.';
+            return {
+              success: false,
+              error: `Cannot infer a zone for ${ipAddress}: it is not publicly routable and no declared network.<zone>.subnet contains it.\n${fix}`,
+            };
+          }
+        }
         console.log(`✓ Zone: ${zone}\n`);
 
         // Detect network interfaces and classify machine
@@ -254,7 +282,7 @@ export async function handleMachineAdd(
 
         console.log(`✓ Role: ${role}`);
         for (const iface of interfaces) {
-          console.log(`  ${iface.name}: ${iface.ipAddress} (${iface.zone})`);
+          console.log(`  ${iface.name}: ${iface.ipAddress} (${describeInterfaceZone(iface)})`);
         }
         console.log('');
       }