@celilo/cli 2.1.0 → 2.2.1

package/drizzle/0031_module_config_source.sql

@@ -0,0 +1,20 @@
+-- Who owns a `module_configs` row (hook-owned-state design D7).
+--
+-- One column, two changes: hook-owned-state needs it to enforce "only a hook
+-- writes source: hook", and `derived-value-recomputation` needs it to tell an
+-- operator row from a derived-seeded one. Whichever change landed first owns
+-- the migration; this is it.
+--
+-- Purely additive and NULLABLE on purpose. NULL means "written before the
+-- column existed" — operator intent, interview writes, legacy derived seeds,
+-- framework keys alike — and stays the value for operator writes until
+-- derived-value-recomputation lands its own classification. There is no
+-- backfill: nothing in an existing row can prove who wrote it, and a guess
+-- backfilled as fact is worse than an honest NULL.
+--
+-- The first writer of a non-NULL value is the hook config store
+-- (`hooks/hook-store.ts`), whose `set` writes 'hook' through
+-- `upsertModuleConfig`. The manifest refuses `module config set` on any
+-- `source: hook` variable, so only a hook can produce the value.
+
+ALTER TABLE `module_configs` ADD `source` text;

package/drizzle/meta/_journal.json

@@ -218,6 +218,13 @@
       "when": 1784400000000,
       "tag": "0030_drop_module_builds_environment",
       "breakpoints": true
+    },
+    {
+      "idx": 31,
+      "version": "6",
+      "when": 1788768000000,
+      "tag": "0031_module_config_source",
+      "breakpoints": true
     }
   ]
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celilo/cli",
-  "version": "2.1.0",
+  "version": "2.2.1",
   "description": "Celilo — home lab orchestration CLI",
   "type": "module",
   "bin": {
@@ -58,9 +58,9 @@
   "dependencies": {
     "@aws-sdk/client-s3": "^3.1109.0",
     "@aws-sdk/lib-storage": "^3.1101.0",
-    "@celilo/capabilities": "^4.1.0",
+    "@celilo/capabilities": "^4.2.0",
     "@celilo/cli-display": "^0.2.0",
-    "@celilo/core": "^0.11.0",
+    "@celilo/core": "^0.11.1",
     "@celilo/event-bus": "^0.6.0",
     "ajv": "^8.18.0",
     "drizzle-orm": "^0.36.4",

package/schemas/system_config.json

@@ -102,7 +102,8 @@
     },
     "firewall.trusted_subnets": {
       "type": "string",
-      "description": "Operator-declared trusted source subnets (comma-separated CIDRs) permitted to reach every managed zone. ADDITIVE to the control-plane subnet celilo derives and to the sources modules register \u2014 it cannot drop control-plane trust, which would block the SSH every hook and converge runs over."
+      "format": "cidr-list",
+      "description": "Operator-declared trusted source subnets permitted to reach every managed zone, as a comma-separated CIDR list (10.0.0.0/24,10.1.0.0/24) or a JSON array ([\"10.0.0.0/24\"]). ADDITIVE to the control-plane subnet celilo derives and to the sources modules register \u2014 it cannot drop control-plane trust, which would block the SSH every hook and converge runs over."
     },
     "dns.primary": {
       "type": "string",
@@ -117,6 +118,11 @@
       "type": "string",
       "description": "SSH public key for container access"
     },
+    "hooks.jail_policy": {
+      "type": "string",
+      "pattern": "^(auto|off|required)$",
+      "description": "Hook jail policy: 'auto' (jail when a backend is available), 'required' (an unavailable jail is a hard failure), or 'off' (hooks run unjailed). Precedence: the CELILO_HOOK_JAIL environment variable wins over this stored value. Run 'celilo system doctor' to see the effective policy and which source it came from."
+    },
     "public_dns.resolver": {
       "type": "string",
       "pattern": "^\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}$",

package/src/ansible/inventory.test.ts

@@ -4,6 +4,7 @@ import { rm } from 'node:fs/promises';
 import { type DbClient, createDbClient } from '../db/client';
 import { systemConfig } from '../db/schema';
 import { upsertModuleConfig } from '../services/module-config';
+import { resetTestDbPath } from '../test-utils/db-path';
 import {
   buildHostVars,
   buildSystemVars,
@@ -286,7 +287,7 @@ describe('Database integration', () => {
   afterEach(async () => {
     db.$client.close();
     // Clean up environment variable
-    process.env.CELILO_DB_PATH = undefined;
+    resetTestDbPath();
     if (existsSync(TEST_DB_PATH)) {
       await rm(TEST_DB_PATH);
     }

package/src/api/sessions.test.ts

@@ -32,6 +32,7 @@ import { handleModuleUpdate } from '../cli/commands/module-update';
 import { getDb } from '../db/client';
 import { modules } from '../db/schema';
 import { RESPONDER_PROBE_EVENT } from '../services/responder-probe';
+import { resetTestDbPath } from '../test-utils/db-path';
 import { SessionWriter, listSessions, reapExpiredSessions } from './sessions';
 
 const NO_SCHEMAS = defineEvents({});
@@ -99,7 +100,7 @@ beforeEach(() => {
 afterEach(() => {
   server.stop(true);
   rmSync(dir, { recursive: true, force: true });
-  process.env.CELILO_DB_PATH = undefined;
+  resetTestDbPath();
   process.env.CELILO_DATA_DIR = undefined;
   process.env.CELILO_ORIGINAL_CWD = undefined;
   process.env.EVENT_BUS_DB = undefined;

package/src/capabilities/public-web-publish.test.ts

@@ -273,6 +273,67 @@ describe('publishStaticSite — clientConfig injection', () => {
   });
 });
 
+describe('the state web overlay (celilo#1265)', () => {
+  beforeEach(() => {
+    execSyncSpy = spyOn(childProcess, 'execSync').mockReturnValue(Buffer.from(''));
+  });
+
+  afterEach(() => {
+    execSyncSpy.mockRestore();
+  });
+
+  // A jailed hook cannot write into its own module tree, so generated site
+  // files land in `<module>/state/site`. The upload's content hash must see
+  // them, or the release directory never refreshes when the overlay changes.
+  test('the upload hash and file count include the state overlay', async () => {
+    const sourceDir = mkdtempSync(join(tmpdir(), 'publish-overlay-'));
+    const overlayDir = join(mkdtempSync(join(tmpdir(), 'publish-overlay-state-')));
+    writeFileSync(join(sourceDir, 'index.html'), '<html></html>', 'utf-8');
+
+    try {
+      const { ops, routes } = makeRouteOps();
+      const cap = createPublicWeb({
+        webRoot: sourceDir,
+        stateWebRoot: overlayDir,
+        moduleId: 'lunacycle',
+        logger: noopLogger,
+        config: {
+          target_ip: '10.0.10.20/24',
+          hostname: 'www',
+          primary_domain: 'example.com',
+          email: 'admin@example.com',
+        },
+        secrets: {},
+        convergeStaticContent: async () => {},
+        routeOps: ops,
+        hostnames: ['www.example.com'],
+        caddyModuleId: 'caddy',
+        dnsManagedDomains: ['www.example.com'],
+      });
+
+      const hashOf = () =>
+        routes.find((r) => r.moduleId === 'lunacycle' && r.path === '/lunacycle')?.contentHash;
+
+      // No overlay yet: one file, and the hash covers only the web root.
+      const before = await cap.publishStaticSite({ path: '/lunacycle' });
+      const hashBefore = hashOf();
+      expect(before.filesUploaded).toBe(1);
+      expect(hashBefore).toBeTruthy();
+
+      // A generated file in state must move the hash, or a rebuilt host's
+      // converge would re-serve the old release and the file would never land.
+      writeFileSync(join(overlayDir, 'ca.crt'), '---CERT---', 'utf-8');
+      const after = await cap.publishStaticSite({ path: '/lunacycle' });
+      expect(after.filesUploaded).toBe(2);
+      expect(hashOf()).toBeTruthy();
+      expect(hashOf()).not.toBe(hashBefore);
+    } finally {
+      rmSync(sourceDir, { recursive: true, force: true });
+      rmSync(overlayDir, { recursive: true, force: true });
+    }
+  });
+});
+
 describe('registerReverseProxy', () => {
   beforeEach(() => {
     execSyncSpy = spyOn(childProcess, 'execSync').mockReturnValue(Buffer.from(''));

package/src/cli/backup-rename.test.ts

@@ -16,6 +16,7 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { closeDb } from '../db/client';
 import { runMigrations } from '../db/migrate';
+import { resetTestDbPath } from '../test-utils/db-path';
 import { runCli } from './index';
 
 describe('celilo module backup (renamed surface)', () => {
@@ -48,7 +49,7 @@ describe('celilo module backup (renamed surface)', () => {
       warnSpy = null;
     }
     closeDb();
-    process.env.CELILO_DB_PATH = undefined;
+    resetTestDbPath();
     process.env.CELILO_MASTER_KEY_PATH = undefined;
     process.env.CELILO_SUPPRESS_DEPRECATION = undefined;
     try {

package/src/cli/cli.test.ts

@@ -8,6 +8,7 @@ import { moduleConfigs, modules, secrets } from '../db/schema';
 import { encryptSecret } from '../secrets/encryption';
 import { generateMasterKey, writeMasterKey } from '../secrets/master-key';
 import { upsertModuleConfig } from '../services/module-config';
+import { resetTestDbPath } from '../test-utils/db-path';
 import { runCli } from './index';
 
 const TEST_DB_PATH = `./test-cli-${Date.now()}-${Math.random()}.db`;
@@ -147,7 +148,7 @@ description: Test module for CLI
 
     // Clear environment variables
     process.env.CELILO_MASTER_KEY_PATH = undefined;
-    process.env.CELILO_DB_PATH = undefined;
+    resetTestDbPath();
   });
 
   describe('help', () => {

package/src/cli/commands/console-get-chain.test.ts

@@ -15,6 +15,7 @@ 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';
+import { resetTestDbPath } from '../../test-utils/db-path';
 
 let testDir: string;
 
@@ -26,7 +27,7 @@ beforeEach(() => {
 
 afterEach(() => {
   rmSync(testDir, { recursive: true, force: true });
-  process.env.CELILO_DB_PATH = undefined;
+  resetTestDbPath();
 });
 
 /** The live fleet's firewall shape: caddy on iptables, iptables on the router. */

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

@@ -8,10 +8,39 @@
  * 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 { afterEach, beforeEach, describe, expect, mock, test } from 'bun:test';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+import { resetTestDbPath } from '../../test-utils/db-path';
+
+// The command reaches boxes ONLY through these two modules, and both are
+// mocked below so the tests can drive the live-read and fallback paths without
+// a real machine. Spreading the actual module keeps every other export intact
+// for anything else that loads them.
+const actualDetector = await import('../../services/machine-detector');
+const actualKeyManager = await import('../../services/ssh-key-manager');
+
+type Detected = {
+  interfaces: Array<{ name: string; ipAddress: string; zone?: string }>;
+  role: string;
+};
+
+let liveRead: (ip: string, user: string, keyPath: string) => Promise<Detected>;
+let localRead: () => Promise<Detected>;
+let tempKeyWriter: (machineId: string) => Promise<string>;
+
+mock.module('../../services/machine-detector', () => ({
+  ...actualDetector,
+  detectNetworkInterfaces: (ip: string, user: string, keyPath: string) =>
+    liveRead(ip, user, keyPath),
+  detectNetworkInterfacesLocal: () => localRead(),
+}));
+mock.module('../../services/ssh-key-manager', () => ({
+  ...actualKeyManager,
+  writeTemporarySshKey: (machineId: string) => tempKeyWriter(machineId),
+  deleteTemporarySshKey: () => {},
+}));
 
 let testDir: string;
 let logs: string[];
@@ -29,13 +58,19 @@ beforeEach(() => {
   testDir = mkdtempSync(join(tmpdir(), 'celilo-fw-iface-'));
   process.env.CELILO_DB_PATH = join(testDir, 'test.db');
   process.env.CELILO_DATA_DIR = testDir;
+  // Key decryption (getMachineSshKey) needs a master key.
+  const masterKeyPath = join(testDir, 'master.key');
+  writeFileSync(masterKeyPath, 'a'.repeat(64));
+  process.env.CELILO_MASTER_KEY_PATH = masterKeyPath;
   captureLogs();
 });
 
 afterEach(() => {
   console.log = originalLog;
   rmSync(testDir, { recursive: true, force: true });
-  process.env.CELILO_DB_PATH = undefined;
+  resetTestDbPath();
+  process.env.CELILO_DATA_DIR = undefined;
+  process.env.CELILO_MASTER_KEY_PATH = undefined;
 });
 
 describe('celilo firewall interface list', () => {
@@ -71,15 +106,130 @@ describe('celilo firewall interface list', () => {
  * 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.
+describe('no side effects on the box', () => {
+  test('reaches a box only through the read-only detectors', async () => {
+    // #1287's CLI half came from the stored-read-only version of this command:
+    // a snapshot taken at machine add kept reading ALIEN after the interface
+    // was gone, so the command contradicted the converge it claims to preview.
+    // The fix reads the box live through the same detectors machine add uses —
+    // read-only by construction. What is still forbidden is any MUTATING
+    // remote primitive, and any hand-built ssh that could grow one silently.
     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 ');
+    // The live read must come from the shared detector, not a private path.
+    expect(src).toContain('detectNetworkInterfaces');
+  });
+});
+
+/**
+ * The live-read contract, against a machine whose STORED snapshot is stale —
+ * the #1287 shape: the alien cable was attached when `machine add` recorded
+ * the interfaces, and nothing refreshes that snapshot afterwards.
+ */
+describe('reads the box live', () => {
+  beforeEach(async () => {
+    liveRead = async () => {
+      throw new Error('liveRead not configured for this test');
+    };
+    localRead = async () => {
+      throw new Error('localRead not configured for this test');
+    };
+    tempKeyWriter = async () => {
+      throw new Error('tempKeyWriter not configured for this test');
+    };
+
+    const { getDb } = await import('../../db/client');
+    const { systemConfig } = await import('../../db/schema');
+    const { addMachine } = await import('../../services/machine-pool');
+
+    await getDb()
+      .insert(systemConfig)
+      .values([
+        { key: 'network.internal.subnet', value: '10.226.1.0/24' },
+        { key: 'network.app.subnet', value: '10.226.20.0/24' },
+        { key: 'network.dmz.subnet', value: '10.226.10.0/24' },
+        { key: 'network.secure.subnet', value: '10.226.30.0/24' },
+      ]);
+
+    await addMachine({
+      hostname: 'fw-main',
+      zone: 'internal',
+      ipAddress: '10.226.1.254',
+      sshUser: 'root',
+      sshKey: 'test-key-material',
+      hardware: { cpu_cores: 2, memory_mb: 2048, disk_gb: 64 },
+      role: 'host',
+      interfaces: [
+        { name: 'eth0', ipAddress: '10.226.20.1', zone: 'app' },
+        { name: 'eth1', ipAddress: '10.226.10.1', zone: 'dmz' },
+        { name: 'eth2', ipAddress: '10.226.1.254', zone: 'internal' },
+        { name: 'eth3', ipAddress: '10.226.30.1', zone: 'secure' },
+        // The cable nobody documented, recorded because it was attached when
+        // the machine was added. It left the box afterwards; the snapshot
+        // never heard about it.
+        { name: 'eth4', ipAddress: '172.31.99.2', zone: 'unknown' },
+      ],
+    });
+  });
+
+  test('an interface removed after machine add no longer reads ALIEN', async () => {
+    let keyWritten = false;
+    tempKeyWriter = async () => {
+      keyWritten = true;
+      return '/tmp/celilo-fw-iface-test.key';
+    };
+    liveRead = async (ip, user) => {
+      // The read went to the box named in the machine record, with its stored
+      // credentials — the same targeting the converge uses.
+      expect(ip).toBe('10.226.1.254');
+      expect(user).toBe('root');
+      return {
+        interfaces: [
+          { name: 'eth0', ipAddress: '10.226.20.1' },
+          { name: 'eth1', ipAddress: '10.226.10.1' },
+          { name: 'eth2', ipAddress: '10.226.1.254' },
+          { name: 'eth3', ipAddress: '10.226.30.1' },
+        ],
+        role: 'router',
+      };
+    };
+
+    const { handleFirewallInterfaceList } = await import('./firewall-interface-list');
+    const result = await handleFirewallInterfaceList(['fw-main'], {});
+
+    expect(result.success).toBe(true);
+    expect(keyWritten).toBe(true);
+    const out = logs.join('\n');
+    // eth4 is gone from the box, so the answer says so — even though the
+    // stored snapshot still carries it.
+    expect(out).not.toContain('172.31.99.2');
+    expect(out).not.toContain('ALIEN');
+    for (const zone of ['app', 'dmz', 'internal', 'secure']) {
+      expect(out).toContain(`zone:${zone}`);
+    }
+    expect(out).not.toContain('could not read the box live');
+  });
+
+  test('a box that cannot be reached says so, and labels the snapshot as stale', async () => {
+    tempKeyWriter = async () => '/tmp/celilo-fw-iface-test.key';
+    liveRead = async () => {
+      throw new Error('SSH command failed after 3 attempts: connection refused');
+    };
+
+    const { handleFirewallInterfaceList } = await import('./firewall-interface-list');
+    const result = await handleFirewallInterfaceList(['fw-main'], {});
+
+    // Unreachable is not a classification result, but the stored snapshot is
+    // still the best available answer — as long as it says what it is.
+    expect(result.success).toBe(true);
+    const out = logs.join('\n');
+    expect(out).toContain('could not read the box live');
+    expect(out).toContain('may be stale');
+    // The stale eth4 is reported, under the label that keeps it from being
+    // mistaken for a current finding.
+    expect(out).toContain('ALIEN');
   });
 });

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

@@ -9,15 +9,34 @@
  * 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.
+ * No side effects: it reads the LIVE interface table the same way the next
+ * converge will — classification is recomputed, never read from a stored copy
+ * (design D4: a stored classification goes stale) — plus the declarations, and
+ * classifies in memory. The only remote operations are the read-only interface
+ * detectors `machine add` uses. When the box cannot be reached it says so, and
+ * falls back to the interface snapshot recorded at machine add, labelled as
+ * what it is.
+ *
+ * The stored-read-only version of this command was the whole of the CLI half
+ * of #1287: the snapshot is taken at machine add, so an interface removed after
+ * it was recorded kept reading ALIEN forever, and an operator who did exactly
+ * what the converge refusal told them to do was told their fix had not worked.
  */
 
 import { classifyInterfaces, isPubliclyRoutable } from '@celilo/capabilities';
 import { getDb } from '../../db/client';
 import { listFirewallIps, readDeclaredNetworks } from '../../hooks/capability-loader';
+import {
+  detectNetworkInterfaces,
+  detectNetworkInterfacesLocal,
+} from '../../services/machine-detector';
 import { listMachines } from '../../services/machine-pool';
+import {
+  LOCAL_MACHINE_IP,
+  deleteTemporarySshKey,
+  writeTemporarySshKey,
+} from '../../services/ssh-key-manager';
+import type { Machine } from '../../types/infrastructure';
 import { celiloIntro } from '../prompts';
 import type { CommandResult } from '../types';
 
@@ -36,6 +55,41 @@ async function declaredZones(): Promise<Array<{ zone: string; subnet: string }>>
   return readDeclaredNetworks(getDb());
 }
 
+/** What the classifier consumes, whatever the source. */
+interface NamedInterface {
+  name: string;
+  ip: string;
+}
+
+/**
+ * The interface table as the box holds it RIGHT NOW, via the same read-only
+ * detectors `machine add` runs. The converge reads the box live too, so this
+ * is the input its classification will see.
+ */
+async function readLiveInterfaces(machine: Machine): Promise<NamedInterface[]> {
+  const toNamed = (list: Array<{ name: string; ipAddress: string }>): NamedInterface[] =>
+    list.map(({ name, ipAddress }) => ({ name, ip: ipAddress }));
+
+  // The management box registers itself as 127.0.0.1 with no stored SSH key
+  // and is reached locally, the same way machine add reaches it.
+  if (machine.ipAddress === LOCAL_MACHINE_IP) {
+    const { interfaces } = await detectNetworkInterfacesLocal();
+    return toNamed(interfaces);
+  }
+
+  const keyPath = await writeTemporarySshKey(machine.id);
+  try {
+    const { interfaces } = await detectNetworkInterfaces(
+      machine.ipAddress,
+      machine.sshUser,
+      keyPath,
+    );
+    return toNamed(interfaces);
+  } finally {
+    deleteTemporarySshKey(machine.id);
+  }
+}
+
 /** 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}`;
@@ -88,10 +142,22 @@ export async function handleFirewallInterfaceList(
   for (const machine of targets) {
     console.log(`\n${machine.hostname} (${machine.ipAddress})`);
 
-    const interfaces = (machine.interfaces ?? []).map((i) => ({
-      name: i.name,
-      ip: i.ipAddress,
-    }));
+    let interfaces: NamedInterface[];
+    try {
+      interfaces = await readLiveInterfaces(machine);
+    } catch (error) {
+      // An unreachable box is not a classification result. Name the fallback
+      // for what it is, so a stale ALIEN is never mistaken for a current one.
+      const reason = error instanceof Error ? error.message : String(error);
+      console.log(
+        '  could not read the box live — classifying the interface snapshot recorded at machine add, which may be stale:',
+      );
+      console.log(`  ${reason}`);
+      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;

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

@@ -5,11 +5,11 @@
 
 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';
+import { findFleetPrivateKey, fleetKeySearchDirs } from '../../services/fleet-key';
 import {
   detectMachineInfo,
   detectMachineInfoLocal,
@@ -30,60 +30,18 @@ import { celiloIntro, celiloOutro } from '../prompts';
 import type { CommandResult } from '../types';
 
 /**
- * Auto-detect SSH private key from system configuration
+ * The private key matching `ssh.public_key`, or null.
  *
- * Reads ssh.public_key from system config and finds matching private key in ~/.ssh/
- *
- * @returns Path to SSH private key, or null if not found
+ * Delegates the search to `findFleetPrivateKey`, which lives beside the mint
+ * so the two cannot name different directories. This function used to derive
+ * its own `join(HOME, '.ssh')`, which meant it could not see the key
+ * `ensureFleetKey` writes into celilo's data directory, so a fleet whose key
+ * celilo minted refused every `machine add` (celilo#1240).
  */
 function findSshPrivateKey(): string | null {
   try {
-    const db = getDb();
-    const config = loadExistingConfiguration(db);
-    const publicKey = config['ssh.public_key'];
-
-    if (!publicKey) {
-      return null;
-    }
-
-    // Extract key type from public key (e.g., "ssh-ed25519", "ssh-rsa")
-    const keyType = publicKey.split(' ')[0];
-
-    const sshDir = join(process.env.HOME || '~', '.ssh');
-    if (!existsSync(sshDir)) {
-      return null;
-    }
-
-    // Common private key filenames based on type
-    const keyFileMap: Record<string, string[]> = {
-      'ssh-ed25519': ['id_ed25519'],
-      'ssh-rsa': ['id_rsa'],
-      'ecdsa-sha2-nistp256': ['id_ecdsa'],
-      'ecdsa-sha2-nistp384': ['id_ecdsa'],
-      'ecdsa-sha2-nistp521': ['id_ecdsa'],
-    };
-
-    const candidateFiles = keyFileMap[keyType] || ['id_rsa', 'id_ed25519', 'id_ecdsa'];
-
-    // Try common key files
-    for (const keyFile of candidateFiles) {
-      const keyPath = join(sshDir, keyFile);
-      if (existsSync(keyPath)) {
-        // Verify this is the matching private key by checking if public key exists
-        const pubKeyPath = `${keyPath}.pub`;
-        if (existsSync(pubKeyPath)) {
-          const pubKeyContent = readFileSync(pubKeyPath, 'utf8').trim();
-          // Check if public keys match (compare key type and key data, ignore comment)
-          const [sysType, sysKey] = publicKey.split(' ');
-          const [fileType, fileKey] = pubKeyContent.split(' ');
-          if (sysType === fileType && sysKey === fileKey) {
-            return keyPath;
-          }
-        }
-      }
-    }
-
-    return null;
+    const publicKey = loadExistingConfiguration(getDb())['ssh.public_key'];
+    return publicKey ? findFleetPrivateKey(publicKey) : null;
   } catch {
     return null;
   }
@@ -200,10 +158,9 @@ export async function handleMachineAdd(
           if (!detectedKeyPath) {
             return {
               success: false,
-              error:
-                'Cannot find SSH private key.\n\n' +
-                'The ssh.public_key system config is set, but no matching private key was found in ~/.ssh/\n\n' +
-                'Specify manually with: --ssh-key-file ~/.ssh/id_ed25519',
+              error: `Cannot find SSH private key.\n\nThe ssh.public_key system config is set, but no private key matching it was found in:\n${fleetKeySearchDirs()
+                .map((dir) => `  ${dir}`)
+                .join('\n')}\n\nSpecify manually with: --ssh-key-file <path>`,
             };
           }
           sshKeyPath = detectedKeyPath;