@celilo/cli 5.0.1 → 5.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celilo/cli",
-  "version": "5.0.1",
+  "version": "5.1.1",
   "description": "Celilo — home lab orchestration CLI",
   "type": "module",
   "bin": {
@@ -59,7 +59,7 @@
   "dependencies": {
     "@aws-sdk/client-s3": "^3.1109.0",
     "@aws-sdk/lib-storage": "^3.1101.0",
-    "@celilo/capabilities": "^6.0.0",
+    "@celilo/capabilities": "^6.1.0",
     "@celilo/cli-display": "^0.2.0",
     "@celilo/core": "^0.14.0",
     "@celilo/event-bus": "^0.7.0",

package/src/hooks/capability-loader-orchestrator-state.test.ts

@@ -0,0 +1,158 @@
+/**
+ * `orchestrator_state` reaches a module through the loader, and only when the
+ * manifest declares it.
+ *
+ * INV-2 (module-orchestrator-primitives design.md): the declaration is the
+ * authorization. Like `control_plane_api`, this capability is framework-granted
+ * — no provider module exists — so the ordinary "inject everything buildable"
+ * loop does not apply and the loader must gate the injection on the `requires`
+ * line. Modeled on `capability-loader-control-plane-api.test.ts`, which proves
+ * the same property for `control_plane_api` through the loader rather than on
+ * the builder, because the loader is where a wrong argument would be passed.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import type { HookLogger } from '@celilo/capabilities';
+import type { DbClient } from '../db/client';
+import { cleanupTestDatabase, setupTestDatabase } from '../test-utils/database';
+import { loadCapabilityFunctions } from './capability-loader';
+
+const noopLogger: HookLogger = {
+  info() {},
+  warn() {},
+  error() {},
+  success() {},
+};
+
+function installModule(db: DbClient, moduleId: string, manifest: Record<string, unknown>): void {
+  db.$client.run(
+    `INSERT INTO modules (id, name, version, source_path, manifest_data) VALUES (?, ?, '1.0.0', '/tmp/${moduleId}', ?)`,
+    [moduleId, moduleId, JSON.stringify(manifest)],
+  );
+}
+
+const DECLARES = {
+  requires: { capabilities: [{ name: 'orchestrator_state', version: '1.0.0' }] },
+};
+
+describe('orchestrator_state injection', () => {
+  let db: DbClient;
+
+  beforeEach(async () => {
+    db = await setupTestDatabase();
+  });
+
+  afterEach(async () => {
+    await cleanupTestDatabase(db);
+  });
+
+  test('a module that declares it gets it, with no provider module deployed', async () => {
+    installModule(db, 'wireguard', DECLARES);
+
+    const capabilities = await loadCapabilityFunctions('wireguard', db, noopLogger);
+
+    expect(capabilities.orchestrator_state).toBeTruthy();
+    const state = capabilities.orchestrator_state as Record<string, unknown>;
+    expect(typeof state.get_system_config).toBe('function');
+  });
+
+  test('a module that declares it as optional gets it too', async () => {
+    installModule(db, 'someday-consumer', {
+      optional: { capabilities: [{ name: 'orchestrator_state', version: '1.0.0' }] },
+    });
+
+    const capabilities = await loadCapabilityFunctions('someday-consumer', db, noopLogger);
+
+    expect(capabilities.orchestrator_state).toBeTruthy();
+  });
+
+  test('a module that declares nothing does NOT get it', async () => {
+    installModule(db, 'hello-foo', { requires: { capabilities: [] } });
+
+    const capabilities = await loadCapabilityFunctions('hello-foo', db, noopLogger);
+
+    expect(capabilities.orchestrator_state).toBeUndefined();
+  });
+
+  test('a module that requires something ELSE does NOT get it', async () => {
+    installModule(db, 'hello-bar', {
+      requires: { capabilities: [{ name: 'firewall', version: '1.0.0' }] },
+    });
+
+    const capabilities = await loadCapabilityFunctions('hello-bar', db, noopLogger);
+
+    expect(capabilities.orchestrator_state).toBeUndefined();
+  });
+
+  test('the injected read works end to end through the loader', async () => {
+    // Through the loader, not only on the builder: the loader is where a
+    // wrong db handle or a wrong module id would be passed.
+    installModule(db, 'wireguard', DECLARES);
+    db.$client.run(
+      `INSERT INTO system_config (key, value) VALUES ('network.control-plane-vpn.subnet', '10.255.255.0/24')`,
+    );
+
+    const capabilities = await loadCapabilityFunctions('wireguard', db, noopLogger);
+    const state = capabilities.orchestrator_state as {
+      get_system_config(request: { key: string }): Promise<{ value: string | null }>;
+    };
+
+    await expect(
+      state.get_system_config({ key: 'network.control-plane-vpn.subnet' }),
+    ).resolves.toEqual({ value: '10.255.255.0/24' });
+  });
+
+  test('the injected table refuses a request naming a module (INV-1 through the loader)', async () => {
+    installModule(db, 'wireguard', DECLARES);
+
+    const capabilities = await loadCapabilityFunctions('wireguard', db, noopLogger);
+    const state = capabilities.orchestrator_state as {
+      get_system_config(request: object): Promise<unknown>;
+    };
+    const smuggled = { key: 'k', module: 'celilo-mgmt' } as never;
+
+    await expect(state.get_system_config(smuggled)).rejects.toThrow(/'wireguard'/);
+  });
+
+  test('an allow-listed module gets the privileged list_machines verb', async () => {
+    // list_machines is a per-module trust decision (design INV-2): the pool
+    // goes only to the modules the allow-list names, even though both modules
+    // here declare the same capability for their config reads.
+    installModule(db, 'celilo-mgmt', DECLARES);
+
+    const capabilities = await loadCapabilityFunctions('celilo-mgmt', db, noopLogger);
+    const state = capabilities.orchestrator_state as Record<string, unknown>;
+
+    expect(typeof state.get_system_config).toBe('function');
+    expect(typeof state.list_machines).toBe('function');
+  });
+
+  test('a module declaring the capability but not allow-listed does NOT get list_machines', async () => {
+    installModule(db, 'wireguard', DECLARES);
+
+    const capabilities = await loadCapabilityFunctions('wireguard', db, noopLogger);
+    const state = capabilities.orchestrator_state as Record<string, unknown>;
+
+    expect(typeof state.get_system_config).toBe('function');
+    expect(state.list_machines).toBeUndefined();
+  });
+
+  test('the privileged list reads end to end through the loader', async () => {
+    // Through the loader, not only on the builder: the loader is where a
+    // wrong allow-list lookup or a wrong db handle would be passed.
+    installModule(db, 'celilo-mgmt', DECLARES);
+    db.$client.run(
+      `INSERT INTO machines (id, hostname, zone, ip_address, ssh_user, ssh_key_encrypted, hardware, role, interfaces)
+       VALUES ('m-1', 'pibox-1', 'dmz', '10.0.20.11', 'peba', 'enc:x', '{"cpu_cores":4,"memory_mb":8192,"disk_gb":64}', 'host', '[]')`,
+    );
+
+    const capabilities = await loadCapabilityFunctions('celilo-mgmt', db, noopLogger);
+    const state = capabilities.orchestrator_state as {
+      list_machines(request: object): Promise<{ machines: Array<Record<string, unknown>> }>;
+    };
+
+    const { machines } = await state.list_machines({});
+    expect(machines).toHaveLength(1);
+    expect(machines[0]).toMatchObject({ hostname: 'pibox-1', zone: 'dmz', role: 'host' });
+  });
+});

package/src/hooks/capability-loader.ts

@@ -41,6 +41,7 @@ import {
   systemConfig,
   webRoutes,
 } from '../db/schema';
+import { allowedPrivilegedVerbs } from '../manifest/validate';
 import { resolveModuleStateWebRoot, resolveModuleWebRoot } from '../module/web-root';
 import { decryptSecret } from '../secrets/encryption';
 import { getOrCreateMasterKey } from '../secrets/master-key';
@@ -53,6 +54,7 @@ import {
 import { CONTROL_PLANE_MODULE_ID, getModuleSystems } from '../services/deployed-systems';
 import { withDnsInternalLedger } from '../services/dns-internal-records';
 import { withDnsRegistrationLedger } from '../services/dns-registrations';
+import { buildOrchestratorState } from '../services/orchestrator-state';
 import { buildPortForwardStore } from '../services/port-forwards';
 import {
   TRUSTED_SUBNETS_CONFIG_KEY,
@@ -940,6 +942,28 @@ export async function loadCapabilityFunctions(
     debugLog(`control_plane_api: framework-granted, injected for ${consumingModuleId}`);
   }
 
+  // orchestrator_state: framework-granted like control_plane_api, and gated on
+  // the DECLARATION for the same reason (INV-2). The verbs read celilo's own
+  // tables — system_config, and for allow-listed modules the machine pool — so
+  // the requires line is the authorization, and a module that never declared
+  // the capability holds no table at all. Built for the calling module (INV-1):
+  // the db this function already holds is the store the verbs read, passed
+  // explicitly so the service tests can pin the closure against an isolated
+  // database. The privileged verbs come from the allow-list map, not the
+  // declaration: declaring the capability buys the config reads, not the pool.
+  if (consumerDeclares(db, consumingModuleId, 'orchestrator_state')) {
+    result.orchestrator_state = wrapWithLogging(
+      buildOrchestratorState(
+        consumingModuleId,
+        db,
+        allowedPrivilegedVerbs('orchestrator_state', consumingModuleId),
+      ),
+      logger,
+      'orchestrator_state',
+    );
+    debugLog(`orchestrator_state: framework-granted, injected for ${consumingModuleId}`);
+  }
+
   // celilo#1072: the CALL is the binding, not the resolution. Everything above
   // is injected whether or not the consumer declared it — the loop's own
   // comment says "not just required ones" — so recording what was resolved

package/src/manifest/validate-privileged.test.ts

@@ -6,7 +6,7 @@
 
 import { describe, expect, it } from 'bun:test';
 import type { ModuleManifest } from './schema';
-import { validatePrivilegedCapabilities } from './validate';
+import { isPrivilegedCapability, validatePrivilegedCapabilities } from './validate';
 
 function buildManifest(overrides: Partial<ModuleManifest>): ModuleManifest {
   return {
@@ -81,4 +81,43 @@ describe('validatePrivilegedCapabilities', () => {
     );
     expect(result?.errors).toHaveLength(2);
   });
+
+  describe('framework-granted capabilities that any module may declare', () => {
+    // `control_plane_api` and `orchestrator_state` are framework-granted but NOT
+    // allow-listed: the `requires` line is the authorization (web-ui-console
+    // D7b, module-orchestrator-primitives D3). The registration that matters is
+    // `isPrivilegedCapability` — when it returns false for one of these, three
+    // call sites (`capabilities/validation.ts:50`, `services/deploy-
+    // validation.ts:182`, `hooks/executor.ts:720`) go looking for a provider
+    // module that can never exist and refuse the module with "no module
+    // provides this capability". `validatePrivilegedCapabilities` alone cannot
+    // see that failure, which is why the predicate is asserted directly.
+    it('treats orchestrator_state as framework-granted', () => {
+      expect(isPrivilegedCapability('orchestrator_state')).toBe(true);
+    });
+
+    it('treats control_plane_api as framework-granted', () => {
+      expect(isPrivilegedCapability('control_plane_api')).toBe(true);
+    });
+
+    it('accepts any module requiring orchestrator_state', () => {
+      const result = validatePrivilegedCapabilities(
+        buildManifest({
+          id: 'wireguard',
+          requires: { capabilities: [{ name: 'orchestrator_state', version: '1.0.0' }] },
+        }),
+      );
+      expect(result).toBeNull();
+    });
+
+    it('still refuses a privilege that IS allow-listed, so the two categories stay distinct', () => {
+      const result = validatePrivilegedCapabilities(
+        buildManifest({
+          id: 'wireguard',
+          requires: { capabilities: [{ name: 'cross_module_read', version: '1.0.0' }] },
+        }),
+      );
+      expect(result).not.toBeNull();
+    });
+  });
 });

package/src/manifest/validate.ts

@@ -213,8 +213,32 @@ export function validateCapabilityNames(manifest: ModuleManifest): ValidationErr
  */
 const PRIVILEGED_CAPABILITY_ALLOW_LIST: Record<string, readonly string[]> = {
   cross_module_read: ['celilo-mgmt'],
+  // A PRIVILEGED VERB, not a capability: `orchestrator_state` itself stays in
+  // FRAMEWORK_GRANTED_CAPABILITIES (any module may read system_config), and
+  // this verb-scoped key names the only module trusted with the machine pool
+  // (design INV-2). The key never matches a declared capability name, so
+  // import-time validation is untouched; the capability loader consults it
+  // through allowedPrivilegedVerbs when it builds the table.
+  'orchestrator_state.list_machines': ['celilo-mgmt'],
 };
 
+/**
+ * The privileged verbs of one capability a module may hold, from the
+ * allow-list above. Verb-scoped keys are `<capability>.<verb>`; a module not
+ * named for a verb gets no entry, and the builder omits the method.
+ */
+export function allowedPrivilegedVerbs(capability: string, moduleId: string): string[] {
+  const verbs: string[] = [];
+  for (const key of Object.keys(PRIVILEGED_CAPABILITY_ALLOW_LIST)) {
+    const [keyCapability, keyVerb] = key.split('.');
+    if (keyCapability === capability && keyVerb) {
+      const allowed = PRIVILEGED_CAPABILITY_ALLOW_LIST[key];
+      if (allowed.includes(moduleId)) verbs.push(keyVerb);
+    }
+  }
+  return verbs;
+}
+
 /**
  * Framework-granted capabilities that any module may declare.
  *
@@ -235,7 +259,17 @@ const PRIVILEGED_CAPABILITY_ALLOW_LIST: Record<string, readonly string[]> = {
  * ids in core, so every new console-shaped consumer would need a core change
  * and a `.deb` release before it could be imported at all.
  */
-const FRAMEWORK_GRANTED_CAPABILITIES: ReadonlySet<string> = new Set(['control_plane_api']);
+const FRAMEWORK_GRANTED_CAPABILITIES: ReadonlySet<string> = new Set([
+  'control_plane_api',
+  // module-orchestrator-primitives slice 2: reads of celilo's own state
+  // (`system_config`, and the privileged `list_machines` verb for
+  // allow-listed modules). The table is built for the calling module and the
+  // declaration is the authorization, like `control_plane_api` — no
+  // capability-level allow-list, because the config reads are not a per-module
+  // trust decision. The pool snapshot verb is, and its allow-list lives in
+  // PRIVILEGED_CAPABILITY_ALLOW_LIST as a verb-scoped key.
+  'orchestrator_state',
+]);
 
 /**
  * Whether `name` is a framework-granted privilege rather than a normal

package/src/policy/capability-shape-baseline.ts

@@ -155,4 +155,10 @@ export const CAPABILITY_SHAPE_BASELINE: Readonly<Record<string, CapabilityShape>
     requests:
       '[{kind:"interface",members:[{name:"all",optional:false,type:"Promise<PrivateWebRoute[]>"},{name:"replaceAll",optional:false,type:"Promise<void>"}],name:"PrivateRouteView"},{kind:"interface",members:[{name:"hostname",optional:false,type:"string"},{name:"module_id",optional:false,type:"string"},{name:"path",optional:false,type:"string"},{name:"slug",optional:false,type:"string"},{name:"target_host",optional:true,type:"string"},{name:"target_port",optional:true,type:"number"},{name:"type",optional:false,type:"\'static\' | \'reverse_proxy\'"},{name:"websocket",optional:true,type:"boolean"}],name:"PrivateWebRoute"}]',
   },
+  orchestrator_state: {
+    version: '1.0.0',
+    hash: '5127c0aa524cdd03bbcfa080a220307dfe6742143d76f3a50d7fa4870519b0c4',
+    requests:
+      '[{kind:"interface",members:[{name:"key",optional:false,type:"string"}],name:"GetSystemConfigRequest"},{kind:"interface",members:[{name:"value",optional:false,type:"string | null"}],name:"GetSystemConfigResult"},{kind:"alias",members:[{name:"_self",optional:false,type:"Record<string, never>"}],name:"ListMachinesRequest"},{kind:"interface",members:[{name:"machines",optional:false,type:"MachineSnapshot[]"}],name:"ListMachinesResult"},{kind:"interface",members:[{name:"arch",optional:true,type:"string"},{name:"cpu_cores",optional:false,type:"number"},{name:"disk_gb",optional:false,type:"number"},{name:"memory_mb",optional:false,type:"number"}],name:"MachineHardwareSnapshot"},{kind:"interface",members:[{name:"ip_address",optional:false,type:"string"},{name:"name",optional:false,type:"string"},{name:"zone",optional:false,type:"string"}],name:"MachineInterfaceSnapshot"},{kind:"interface",members:[{name:"earmarked_module",optional:false,type:"string | null"},{name:"hardware",optional:false,type:"MachineHardwareSnapshot"},{name:"hostname",optional:false,type:"string"},{name:"id",optional:false,type:"string"},{name:"interfaces",optional:false,type:"MachineInterfaceSnapshot[]"},{name:"ip_address",optional:false,type:"string"},{name:"role",optional:false,type:"\'host\' | \'router\'"},{name:"ssh_user",optional:false,type:"string"},{name:"zone",optional:false,type:"string"}],name:"MachineSnapshot"},{kind:"interface",members:[{name:"get_system_config",optional:false,type:"Promise<GetSystemConfigResult>"},{name:"list_machines",optional:true,type:"Promise<ListMachinesResult>"}],name:"OrchestratorStateCapability"}]',
+  },
 };

package/src/policy/module-business-baseline.ts

@@ -261,6 +261,12 @@ export const CAPABILITY_NAME_BASELINE: readonly CapabilityNameRow[] = [
     count: 1,
     why: 'L1-L12 — core branches on the capability NAME; becomes a provider declaration in Phase 3 (#938)',
   },
+  {
+    file: 'apps/celilo/src/manifest/validate.ts',
+    capability: 'orchestrator_state',
+    count: 1,
+    why: "PERMANENT — orchestrator_state is framework-granted, not module-provided: its verbs read celilo's own tables, so celilo builds the method table and no module can (module-orchestrator-primitives)",
+  },
   {
     file: 'apps/celilo/src/manifest/validate.ts',
     capability: 'cross_module_read',
@@ -273,6 +279,12 @@ export const CAPABILITY_NAME_BASELINE: readonly CapabilityNameRow[] = [
     count: 1,
     why: 'PERMANENT — framework-granted, so celilo satisfies it and no module provides it; the resolver has to be told that by name (web-ui-console D7b)',
   },
+  {
+    file: 'apps/celilo/src/hooks/capability-loader.ts',
+    capability: 'orchestrator_state',
+    count: 5,
+    why: "PERMANENT — orchestrator_state is framework-granted, not module-provided: its verbs read celilo's own tables, so celilo builds the method table and no module can (module-orchestrator-primitives)",
+  },
   {
     file: 'apps/celilo/src/hooks/capability-loader.ts',
     capability: 'control_plane_api',
@@ -375,6 +387,12 @@ export const CAPABILITY_NAME_BASELINE: readonly CapabilityNameRow[] = [
     count: 1,
     why: 'PERMANENT — X10, a contract declaration with no implementation; this is the package doing its job',
   },
+  {
+    file: 'packages/capabilities/src/capability-contract.ts',
+    capability: 'orchestrator_state',
+    count: 1,
+    why: 'PERMANENT — X10, a contract declaration with no implementation; this is the package doing its job',
+  },
   {
     file: 'packages/capabilities/src/capability-contract.ts',
     capability: 'cross_module_read',
@@ -507,6 +525,11 @@ export const SERVICE_FILENAME_BASELINE: readonly ServiceFilenameRow[] = [
     capability: 'cross_module_read',
     why: 'PERMANENT — cross_module_read is a framework privilege, not a module capability',
   },
+  {
+    file: 'apps/celilo/src/services/orchestrator-state.ts',
+    capability: 'orchestrator_state',
+    why: "PERMANENT — orchestrator_state is framework-granted, not module-provided: its verbs read celilo's own tables, so celilo builds the method table and no module can (module-orchestrator-primitives)",
+  },
   {
     file: 'apps/celilo/src/services/provider-converge.ts',
     capability: 'provider_converge',

package/src/services/infrastructure-selector.test.ts

@@ -272,6 +272,52 @@ describe('infrastructure-selector', () => {
     });
   });
 
+  describe('the no-infrastructure error names what IS configured', () => {
+    it("names the service and the zones it covers when none covers the module's zone", async () => {
+      const db = createDbClient({ path: testDbPath });
+      await db.insert(modules).values({
+        id: 'needs-dmz',
+        name: 'Needs DMZ',
+        version: '1.0.0',
+        manifestData: {
+          requires: { system: { cpu: 1, memory: 512, disk: 5, zone: 'dmz' } },
+        },
+        sourcePath: '/test',
+        state: 'CONFIGURED',
+      });
+      const module = (await db.select().from(modules).limit(1))[0] as Module;
+
+      // A service exists — it just does not list 'dmz'. This is the case the
+      // old message described as having no service at all.
+      const service = await addContainerService({
+        name: 'Proxmox E2E',
+        providerName: 'proxmox',
+        zones: ['app', 'secure-mgmt'],
+        providerConfig: {},
+        apiCredentials: { api_url: 'https://test' },
+      });
+      const { updateVerificationStatus } = await import('./container-service');
+      await updateVerificationStatus(service.id, { success: true, message: 'ok' });
+
+      let message = '';
+      try {
+        await selectInfrastructure(module);
+        throw new Error('expected selectInfrastructure to throw');
+      } catch (err) {
+        expect(err).toBeInstanceOf(InfrastructureError);
+        message = (err as Error).message;
+      }
+
+      expect(message).toContain("zone 'dmz'");
+      expect(message).toContain('Proxmox E2E');
+      expect(message).toContain("'app'");
+      expect(message).toContain("'secure-mgmt'");
+      // The misleading half: do not tell the operator to configure a service
+      // they already have.
+      expect(message).not.toContain('celilo service add');
+    });
+  });
+
   describe('hardware validation', () => {
     it('rejects machine with insufficient CPU', async () => {
       const db = createDbClient({ path: testDbPath });

package/src/services/infrastructure-selector.ts

@@ -1,6 +1,7 @@
 import type { Module } from '../db/schema';
 import { type ModuleManifest, getSingularSystemSpec } from '../manifest/schema';
 import type {
+  ContainerService,
   InfrastructureSelection,
   Machine,
   MachineRole,
@@ -79,9 +80,30 @@ interface RejectionReason {
 /**
  * Build a detailed error message explaining why no infrastructure was selected
  */
-function buildInfrastructureErrorMessage(zone: string, rejections: RejectionReason[]): string {
+function buildInfrastructureErrorMessage(
+  zone: string,
+  rejections: RejectionReason[],
+  allServices: ContainerService[],
+): string {
   if (rejections.length === 0) {
-    return `No infrastructure available for zone '${zone}'. Configure a container service with 'celilo service add' or add a machine with 'celilo machine add'.`;
+    // Naming the services that DO exist is the whole value of this branch.
+    // "Configure a container service" is actively misleading when one is
+    // already configured and simply does not list this zone — it sends the
+    // reader to `machine add`, which is the wrong fix and, in an e2e fixture,
+    // a forbidden one (a machine-pool deploy never renders `main.tf.tpl`,
+    // celilo#879). Measured 2026-09-25: a suite whose Proxmox service covered
+    // `app` and `secure-mgmt` failed to place caddy in `dmz`, and this
+    // sentence described the situation as having no service at all.
+    const covering = allServices
+      .map(
+        (svc) =>
+          `'${svc.name}' covers ${svc.zones.length > 0 ? svc.zones.map((z) => `'${z}'`).join(', ') : 'no zones'}`,
+      )
+      .join('; ');
+    const have = covering
+      ? ` Configured container services do not cover it: ${covering}. Add '${zone}' to one with 'celilo service reconfigure', or add a machine with 'celilo machine add'.`
+      : ` Configure a container service with 'celilo service add' or add a machine with 'celilo machine add'.`;
+    return `No infrastructure available for zone '${zone}'.${have}`;
   }
 
   const details = rejections
@@ -246,5 +268,7 @@ export async function selectInfrastructure(module: Module): Promise<Infrastructu
   }
 
   // 3. No infrastructure available
-  throw new InfrastructureError(buildInfrastructureErrorMessage(zone, rejections));
+  throw new InfrastructureError(
+    buildInfrastructureErrorMessage(zone, rejections, await listContainerServices()),
+  );
 }

package/src/services/module-validator/bundled-deps.test.ts

@@ -1,4 +1,7 @@
 import { describe, expect, test } from 'bun:test';
+import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
 import { findStaleBundledDeps, refreshAndVerifyBundledDeps } from './bundled-deps';
 
 describe('findStaleBundledDeps (ISS-0104)', () => {
@@ -52,4 +55,45 @@ describe('refreshAndVerifyBundledDeps (ISS-0104)', () => {
     expect(result).toEqual({ refreshed: false, mismatches: [] });
     expect(installs).toBe(0);
   });
+
+  // celilo#1447: the release run's sweep installs seconds after the same run
+  // published the packages it resolves, so bun's cached packument 404s them.
+  describe('just-published dep (celilo#1447)', () => {
+    function moduleWithScripts(): string {
+      const dir = mkdtempSync(join(tmpdir(), 'bundled-deps-'));
+      mkdirSync(join(dir, 'scripts'), { recursive: true });
+      writeFileSync(join(dir, 'scripts', 'package.json'), '{"name":"m"}');
+      return dir;
+    }
+
+    test('retries with --no-cache when the first install cannot resolve it', () => {
+      const cmds: string[] = [];
+      const slept: number[] = [];
+      refreshAndVerifyBundledDeps(
+        moduleWithScripts(),
+        (cmd) => {
+          cmds.push(cmd);
+          if (cmds.length === 1) throw new Error('failed to resolve (but package exists)');
+        },
+        (ms) => void slept.push(ms),
+      );
+      expect(cmds).toEqual(['bun install', 'bun install --no-cache']);
+      expect(slept).toEqual([2_000]);
+    });
+
+    test('rethrows once the retries are exhausted', () => {
+      const cmds: string[] = [];
+      expect(() =>
+        refreshAndVerifyBundledDeps(
+          moduleWithScripts(),
+          (cmd) => {
+            cmds.push(cmd);
+            throw new Error('still unresolvable');
+          },
+          () => {},
+        ),
+      ).toThrow('still unresolvable');
+      expect(cmds).toHaveLength(3);
+    });
+  });
 });

package/src/services/module-validator/bundled-deps.ts

@@ -65,6 +65,44 @@ function findWorkspaceRoot(start: string): string | undefined {
   return undefined;
 }
 
+/**
+ * celilo#1447: in a release run this install happens SECONDS after the same
+ * run published the workspace packages it must resolve. bun has already cached
+ * the pre-publish packument (the workspace install at the top of the job), so
+ * it fails with "@celilo/capabilities@^6.1.0 failed to resolve ... but package
+ * exists" — and the whole module sweep aborts AFTER npm and the CLI shipped,
+ * which is exactly the half-shipped release #1369 reordered the steps to
+ * prevent. `--no-cache` re-reads the registry; the backoff covers the case
+ * where npm's own metadata has not propagated yet.
+ *
+ * ponytail: fixed 3 attempts, no jitter. If propagation ever needs longer,
+ * raise RETRY_DELAYS_MS rather than adding a scheduler.
+ */
+const RETRY_DELAYS_MS = [2_000, 8_000];
+
+function installWithRetry(
+  run: (cmd: string, cwd: string) => void,
+  sleep: (ms: number) => void,
+  scriptsDir: string,
+): void {
+  try {
+    run('bun install', scriptsDir);
+    return;
+  } catch (err) {
+    let lastErr = err;
+    for (const delay of RETRY_DELAYS_MS) {
+      sleep(delay);
+      try {
+        run('bun install --no-cache', scriptsDir);
+        return;
+      } catch (retryErr) {
+        lastErr = retryErr;
+      }
+    }
+    throw lastErr;
+  }
+}
+
 export interface RefreshResult {
   /** Whether the module had a scripts/ package to refresh. */
   refreshed: boolean;
@@ -84,6 +122,7 @@ export function refreshAndVerifyBundledDeps(
   moduleDir: string,
   run: (cmd: string, cwd: string) => void = (cmd, cwd) =>
     void execSync(cmd, { cwd, stdio: 'pipe' }),
+  sleep: (ms: number) => void = (ms) => Bun.sleepSync(ms),
 ): RefreshResult {
   const scriptsDir = join(moduleDir, 'scripts');
   if (!existsSync(join(scriptsDir, 'package.json'))) {
@@ -92,7 +131,7 @@ export function refreshAndVerifyBundledDeps(
 
   // Reconcile node_modules with the lockfile + package.json pins so the pack
   // bundles a CURRENT closure, not whatever the operator last installed.
-  run('bun install', scriptsDir);
+  installWithRetry(run, sleep, scriptsDir);
 
   const workspaceRoot = findWorkspaceRoot(moduleDir);
   if (!workspaceRoot) {

package/src/services/orchestrator-state.test.ts

@@ -0,0 +1,211 @@
+/**
+ * `orchestrator_state` — the framework-built method table.
+ *
+ * INV-1 (module-orchestrator-primitives design.md) is what these tests exist to
+ * pin: the module a verb acts on is a CONSTRUCTION argument, never a field in
+ * the request. The jail cannot be trusted to name itself honestly, so a request
+ * that arrives carrying a module field is refused even though the contract type
+ * has no such field — the broker hands the implementation whatever JSON the
+ * hook process sent, and the runtime check is the only thing standing between a
+ * hook and a neighbour's data once the shape has crossed the process boundary.
+ *
+ * The refusal message names the calling module, which is also how the closure
+ * itself is observable: two instances built for different modules read the same
+ * table but each names its OWN module when it refuses.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import type { DbClient } from '../db/client';
+import { machines, systemConfig } from '../db/schema';
+import { cleanupTestDatabase, setupTestDatabase } from '../test-utils/database';
+import { buildOrchestratorState } from './orchestrator-state';
+
+const VPN_SUBNET_KEY = 'network.control-plane-vpn.subnet';
+
+/**
+ * Pull the privileged verb off the table with a guard that fails clearly.
+ * The method is optional on the contract (the allow-list decides), so a test
+ * that calls it unguarded reads as possibly-undefined rather than as the
+ * assertion it is: these tests granted the verb, and its absence is what the
+ * test should report.
+ */
+function requireListMachines(state: ReturnType<typeof buildOrchestratorState>) {
+  const { list_machines } = state;
+  if (!list_machines) {
+    throw new Error('list_machines was not injected; the verbs argument did not grant it');
+  }
+  return list_machines;
+}
+
+describe('buildOrchestratorState', () => {
+  let db: DbClient;
+
+  beforeEach(async () => {
+    db = await setupTestDatabase();
+  });
+
+  afterEach(async () => {
+    await cleanupTestDatabase(db);
+  });
+
+  test('reads the value of a set system-config key', async () => {
+    db.insert(systemConfig).values({ key: VPN_SUBNET_KEY, value: '10.255.255.0/24' }).run();
+    const state = buildOrchestratorState('wireguard', db);
+
+    await expect(state.get_system_config({ key: VPN_SUBNET_KEY })).resolves.toEqual({
+      value: '10.255.255.0/24',
+    });
+  });
+
+  test('an unset key is value null, not an error', async () => {
+    // The case the replaced CLI call mangled: `celilo system config get`
+    // exits non-zero for an unset key, so the caller had to catch the spawn
+    // failure AND parse stdout. Here the normal absence is a typed result.
+    const state = buildOrchestratorState('wireguard', db);
+
+    await expect(state.get_system_config({ key: 'no.such.key' })).resolves.toEqual({
+      value: null,
+    });
+  });
+
+  test('a request carrying a module field is refused (INV-1)', async () => {
+    // The contract type has no `module` field, so this only arrives as a
+    // smuggled extra property across the broker. Refused, not ignored: an
+    // ignored field means a hook testing the water learns nothing.
+    const state = buildOrchestratorState('wireguard', db);
+    const smuggled = { key: VPN_SUBNET_KEY, module: 'celilo-mgmt' } as never;
+
+    await expect(state.get_system_config(smuggled)).rejects.toThrow(/module/);
+  });
+
+  test('the refusal names the module the table was built for (the closure, observed)', async () => {
+    // Two instances over the same db, built for different modules. The reads
+    // are identical; the refusals are not, and the difference is the proof
+    // that each instance closed over its own module id.
+    const wireguard = buildOrchestratorState('wireguard', db);
+    const impostor = buildOrchestratorState('celilo-mgmt', db);
+
+    const smuggled = { key: 'k', module: 'someone-else' } as never;
+    await expect(wireguard.get_system_config(smuggled)).rejects.toThrow(/'wireguard'/);
+    await expect(impostor.get_system_config(smuggled)).rejects.toThrow(/'celilo-mgmt'/);
+  });
+
+  test('a request carrying any unexpected field is refused, not just module-named ones', async () => {
+    // The general shape of INV-1: the request is exactly the contract, and
+    // anything extra is a jail trying to widen the surface. Refusing on the
+    // general rule covers the next smuggled field nobody thought to name.
+    const state = buildOrchestratorState('wireguard', db);
+    const widened = { key: 'k', value: '10.0.0.0/8' } as never;
+
+    await expect(state.get_system_config(widened)).rejects.toThrow(/value/);
+  });
+});
+
+describe('buildOrchestratorState list_machines', () => {
+  let db: DbClient;
+
+  beforeEach(async () => {
+    db = await setupTestDatabase();
+  });
+
+  afterEach(async () => {
+    await cleanupTestDatabase(db);
+  });
+
+  function insertMachine(overrides: Partial<typeof machines.$inferInsert> = {}): void {
+    db.insert(machines)
+      .values({
+        id: 'm-1',
+        hostname: 'pibox-1',
+        zone: 'dmz',
+        ipAddress: '10.0.20.11',
+        sshUser: 'peba',
+        sshKeyEncrypted: 'enc:never-read-back',
+        hardware: { cpu_cores: 4, memory_mb: 8192, disk_gb: 64 },
+        role: 'host',
+        interfaces: [{ name: 'eth0', ipAddress: '10.0.20.11', zone: 'dmz' }],
+        ...overrides,
+      })
+      .run();
+  }
+
+  test('an allowed module gets the pool, as the snapshot type carries it', async () => {
+    // The list_machines allow-list (design INV-2) is the loader's decision;
+    // the builder takes the allowed verbs as an argument so the service tests
+    // can pin the closure without importing the trust map.
+    insertMachine({ earmarkedModule: null });
+    insertMachine({
+      id: 'm-2',
+      hostname: 'gw-1',
+      role: 'router',
+      earmarkedModule: 'celilo-mgmt',
+    });
+    const state = buildOrchestratorState('celilo-mgmt', db, ['list_machines']);
+
+    const { machines: pool } = await requireListMachines(state)({});
+    expect(pool).toEqual([
+      {
+        id: 'm-1',
+        hostname: 'pibox-1',
+        zone: 'dmz',
+        ip_address: '10.0.20.11',
+        ssh_user: 'peba',
+        role: 'host',
+        interfaces: [{ name: 'eth0', ip_address: '10.0.20.11', zone: 'dmz' }],
+        hardware: { cpu_cores: 4, memory_mb: 8192, disk_gb: 64 },
+        earmarked_module: null,
+      },
+      {
+        id: 'm-2',
+        hostname: 'gw-1',
+        zone: 'dmz',
+        ip_address: '10.0.20.11',
+        ssh_user: 'peba',
+        role: 'router',
+        interfaces: [{ name: 'eth0', ip_address: '10.0.20.11', zone: 'dmz' }],
+        hardware: { cpu_cores: 4, memory_mb: 8192, disk_gb: 64 },
+        earmarked_module: 'celilo-mgmt',
+      },
+    ]);
+  });
+
+  test('an empty pool is an empty list, not an error', async () => {
+    // A fresh management box has no machines yet. The backup writes an empty
+    // inventory because the pool IS empty — a real result, not the swallow
+    // the replaced CLI spawn produced.
+    const state = buildOrchestratorState('celilo-mgmt', db, ['list_machines']);
+
+    const { machines: pool } = await requireListMachines(state)({});
+    expect(pool).toEqual([]);
+  });
+
+  test('the encrypted key column never reaches the snapshot', async () => {
+    // The one column the snapshot must not carry. Asserting on the VALUE (not
+    // just the type) because a pass-through of the row would ship the secret
+    // inside a correctly-shaped envelope.
+    insertMachine();
+    const state = buildOrchestratorState('celilo-mgmt', db, ['list_machines']);
+
+    const { machines: pool } = await requireListMachines(state)({});
+    expect(JSON.stringify(pool)).not.toContain('enc:never-read-back');
+  });
+
+  test('a request carrying any field is refused (INV-1)', async () => {
+    // The list_machines contract is empty, so ANY field is a smuggled
+    // widening — including the module id the jail cannot be trusted to name.
+    const state = buildOrchestratorState('celilo-mgmt', db, ['list_machines']);
+    const smuggled = { module: 'wireguard' } as never;
+
+    await expect(requireListMachines(state)(smuggled)).rejects.toThrow(/module/);
+  });
+
+  test('a table built without the verb allowed does not carry it', async () => {
+    // Deny by default (Rule 6.4): the loader passes the allow-list decision,
+    // and a builder that defaulted to generous would hand the pool to any
+    // module declaring orchestrator_state for the config reads.
+    insertMachine();
+    const state = buildOrchestratorState('wireguard', db);
+
+    expect((state as unknown as Record<string, unknown>).list_machines).toBeUndefined();
+  });
+});

package/src/services/orchestrator-state.ts

@@ -0,0 +1,122 @@
+/**
+ * The `orchestrator_state` method table celilo builds for one consuming module.
+ *
+ * Framework-granted like `control_plane_api` (`api-principal-enrolment.ts`,
+ * whose shape this copies): the verbs answer questions about celilo's own
+ * tables, so no module script can implement them, and a module script may
+ * import nothing but `@celilo/capabilities`. celilo builds the table for the
+ * calling module and `capability-loader.ts` injects it when the manifest
+ * declares the capability — the `requires` line is the authorization.
+ *
+ * ## INV-1: the module is a construction argument, never a request field
+ *
+ * `buildOrchestratorState(moduleId)` closes over the module id, exactly as
+ * `buildControlPlaneApi` does. A request that arrives carrying any field the
+ * contract does not declare is REFUSED, not ignored: the broker hands this
+ * table whatever JSON the hook process sent, the contract type has no way to
+ * reject extra properties at compile time, and an ignored field would let a
+ * jail probe the surface while learning nothing. The refusal message names the
+ * calling module, so the log shows who tried to widen what.
+ *
+ * ## Reads through the existing store
+ *
+ * Both verbs read the tables the CLI reads, through drizzle, with the same
+ * injectable `db` (defaulting to the process-wide `getDb()`) so the INV-1
+ * tests can pin the closure against an isolated database instead of the
+ * operator's real fleet. `get_system_config` reads `system_config`;
+ * `list_machines` reads `machines` — the same rows `celilo machine list`
+ * renders, minus the encrypted key column, which no snapshot carries (the
+ * fleet keypair is staged into the backup envelope by the framework).
+ *
+ * `list_machines` is a PRIVILEGED verb: handing out the pool is a per-module
+ * trust decision (design INV-2), so the loader passes the verbs the calling
+ * module is allow-listed for and the table omits the rest. Deny by default:
+ * a builder that defaulted to generous would hand the pool to every module
+ * declaring `orchestrator_state` for its config reads.
+ */
+
+import type { OrchestratorStateCapability } from '@celilo/capabilities';
+import { eq } from 'drizzle-orm';
+import { type DbClient, getDb } from '../db/client';
+import { machines, systemConfig } from '../db/schema';
+
+/**
+ * The fields `get_system_config`'s contract declares, and therefore the only
+ * fields a request may carry. Anything else is a smuggled widening and is
+ * refused with the offending field named.
+ */
+const GET_SYSTEM_CONFIG_FIELDS = ['key'] as const;
+
+/**
+ * Refuse a request carrying any field the contract does not declare.
+ *
+ * INV-1's runtime half. `as never` call sites are expected: a hook process
+ * sends JSON, and JSON has no compile-time shape once it crosses the broker.
+ */
+function requireExactRequest(
+  moduleId: string,
+  verb: string,
+  request: object,
+  allowedFields: readonly string[],
+): void {
+  const unexpected = Object.keys(request).filter((field) => !allowedFields.includes(field));
+  if (unexpected.length === 0) return;
+  throw new Error(
+    `Module '${moduleId}' called orchestrator_state.${verb} with unexpected field(s): ${unexpected.join(', ')}. The calling module is a construction argument of this capability, never a request field; allowed fields for ${verb}: ${allowedFields.join(', ')}.`,
+  );
+}
+
+/**
+ * Build the `orchestrator_state` table for one module.
+ *
+ * `db` is injectable for tests; production callers (the capability loader)
+ * let it default to the process-wide client, the same way the enrolment
+ * service resolves its store.
+ *
+ * `allowPrivilegedVerbs` names the privileged verbs the calling module may
+ * hold, as computed by the loader from the allow-list in
+ * `manifest/validate.ts`. It defaults to empty (deny by default): a module
+ * declaring `orchestrator_state` gets `get_system_config` and nothing else
+ * unless the trust map names it.
+ */
+export function buildOrchestratorState(
+  moduleId: string,
+  db: DbClient = getDb(),
+  allowPrivilegedVerbs: readonly string[] = [],
+): OrchestratorStateCapability {
+  const table: OrchestratorStateCapability = {
+    async get_system_config(request) {
+      requireExactRequest(moduleId, 'get_system_config', request, GET_SYSTEM_CONFIG_FIELDS);
+      const row = db.select().from(systemConfig).where(eq(systemConfig.key, request.key)).get();
+      return { value: row?.value ?? null };
+    },
+  };
+
+  if (allowPrivilegedVerbs.includes('list_machines')) {
+    table.list_machines = async (request) => {
+      // The contract is empty, so the allowed-field set is empty and any
+      // field at all — including a module id — is a smuggled widening.
+      requireExactRequest(moduleId, 'list_machines', request, []);
+      const rows = db.select().from(machines).all();
+      return {
+        machines: rows.map((row) => ({
+          id: row.id,
+          hostname: row.hostname,
+          zone: row.zone,
+          ip_address: row.ipAddress,
+          ssh_user: row.sshUser,
+          role: row.role,
+          interfaces: row.interfaces.map((iface) => ({
+            name: iface.name,
+            ip_address: iface.ipAddress,
+            zone: iface.zone,
+          })),
+          hardware: row.hardware,
+          earmarked_module: row.earmarkedModule ?? null,
+        })),
+      };
+    };
+  }
+
+  return table;
+}