@celilo/cli 0.4.0-alpha.1 → 0.4.0

package/src/services/aspect-runner.test.ts

@@ -20,13 +20,19 @@ import { closeDb, getDb } from '../db/client';
 import { runMigrations } from '../db/migrate';
 import { modules } from '../db/schema';
 import type { BaseModuleAspect, ModuleManifest } from '../manifest/schema';
-import { computeAspectScopeHash, recordAspectApproval } from './aspect-approvals';
+import {
+  computeAspectScopeHash,
+  findAspectApproval,
+  recordAspectApproval,
+  recordAspectConsent,
+} from './aspect-approvals';
 import {
   type AspectRunResult,
   materializeAspectAnsible,
   maybeRunAspectForTrigger,
   planAspectFanOut,
 } from './aspect-runner';
+import { upsertDeployedSystem } from './deployed-systems';
 import { addMachine } from './machine-pool';
 
 const baseAspect: BaseModuleAspect = {
@@ -62,6 +68,37 @@ async function seedMachine(opts: {
   }
 }
 
+/** Seed a container_service LXC (a module + its module_systems row). */
+function seedLxc(opts: {
+  moduleId: string;
+  hostname: string;
+  zone: 'dmz' | 'app' | 'secure' | 'internal';
+  ip: string;
+}) {
+  const db = getDb();
+  db.insert(modules)
+    .values({
+      id: opts.moduleId,
+      name: opts.moduleId,
+      version: '1.0.0',
+      manifestData: {
+        id: opts.moduleId,
+        name: opts.moduleId,
+        version: '1.0.0',
+        celilo_contract: '1.0',
+      },
+      sourcePath: `/tmp/${opts.moduleId}`,
+    })
+    .run();
+  upsertDeployedSystem(db, opts.moduleId, {
+    name: 'main',
+    hostname: opts.hostname,
+    ipv4Address: opts.ip,
+    zone: opts.zone,
+    infraType: 'container_service',
+  });
+}
+
 describe('aspect-runner', () => {
   let dir: string;
 
@@ -131,6 +168,38 @@ describe('aspect-runner', () => {
       const plan = await planAspectFanOut({ ...baseAspect, applicable_zones: ['secure'] });
       expect(plan.targetSystems.map((m) => m.hostname)).toEqual(['celilo-mgmt']);
     });
+
+    it('includes container_service LXCs in the zones, not just machines (ISS-0028)', async () => {
+      // The original machines-only fan-out skipped LXCs — caddy/celilo-registry
+      // never got the aspect. A zone with both a machine and an LXC must yield
+      // both targets.
+      await seedMachine({ hostname: 'knot', zone: 'internal', ip: '192.168.0.10' });
+      seedLxc({ moduleId: 'caddy', hostname: 'caddy', zone: 'dmz', ip: '10.0.10.10' });
+      seedLxc({
+        moduleId: 'celilo-registry',
+        hostname: 'celilo-registry',
+        zone: 'app',
+        ip: '10.0.20.12',
+      });
+
+      const plan = await planAspectFanOut(baseAspect);
+      expect(plan.targetSystems.map((t) => t.hostname).sort()).toEqual([
+        'caddy',
+        'celilo-registry',
+        'knot',
+      ]);
+      // The LXC targets carry no machineId (ambient-key auth); the machine does.
+      const caddy = plan.targetSystems.find((t) => t.hostname === 'caddy');
+      expect(caddy?.machineId).toBeUndefined();
+      expect(caddy?.sshUser).toBe('root');
+      expect(plan.targetSystems.find((t) => t.hostname === 'knot')?.machineId).toBeDefined();
+    });
+
+    it('respects excludeHostnames for LXC targets too', async () => {
+      seedLxc({ moduleId: 'caddy', hostname: 'caddy', zone: 'dmz', ip: '10.0.10.10' });
+      const plan = await planAspectFanOut(baseAspect, { excludeHostnames: ['caddy'] });
+      expect(plan.targetSystems).toEqual([]);
+    });
   });
 
   describe('materializeAspectAnsible', () => {
@@ -201,6 +270,28 @@ describe('aspect-runner', () => {
       rmSync(workDir, { recursive: true, force: true });
     });
 
+    it('emits an LXC inventory row with no ssh key file (ambient auth, ISS-0028)', async () => {
+      await seedMachine({ hostname: 'knot', zone: 'internal', ip: '192.168.0.10' });
+      seedLxc({ moduleId: 'caddy', hostname: 'caddy', zone: 'dmz', ip: '10.0.10.10' });
+      const moduleSourcePath = join(dir, 'module-src-lxc');
+      makeFakeRole(moduleSourcePath, 'dns-client-config');
+
+      const plan = await planAspectFanOut(baseAspect);
+      const workDir = await materializeAspectAnsible({
+        aspect: baseAspect,
+        moduleSourcePath,
+        targetSystems: plan.targetSystems,
+      });
+      const hostsIni = readFileSync(join(workDir, 'ansible', 'inventory', 'hosts.ini'), 'utf-8');
+      // The machine row pins a key file; the LXC row does not (ambient key).
+      const knotLine = hostsIni.split('\n').find((l) => l.startsWith('knot '));
+      const caddyLine = hostsIni.split('\n').find((l) => l.startsWith('caddy '));
+      expect(knotLine).toContain('ansible_ssh_private_key_file=');
+      expect(caddyLine).toContain('caddy ansible_host=10.0.10.10 ansible_user=root');
+      expect(caddyLine).not.toContain('ansible_ssh_private_key_file=');
+      rmSync(workDir, { recursive: true, force: true });
+    });
+
     it('throws a clear error when the aspect role directory is missing', async () => {
       await seedMachine({ hostname: 'caddy', zone: 'dmz', ip: '10.0.10.10' });
       const moduleSourcePath = join(dir, 'module-src-without-role');
@@ -393,9 +484,58 @@ describe('aspect-runner', () => {
       expect(calls).toHaveLength(0);
     });
 
-    it('skips with "no_approval" when the operator never approved', async () => {
+    it('interviews when undecided and runs on consent (persists the approval)', async () => {
+      seedModuleRow({ id: 'knot-unbound-internal', version: '1.0.0' });
+      const { fake, calls } = makeFakeRunner();
+      const asked: string[] = [];
+      const result = await maybeRunAspectForTrigger({
+        moduleId: 'knot-unbound-internal',
+        manifest: manifestWithAspect,
+        trigger: 'on_install',
+        db: getDb(),
+        runner: fake,
+        requestConsent: async (a) => {
+          asked.push(a.reason);
+          return true;
+        },
+      });
+      expect(asked).toEqual(['no_approval']); // it interviewed, didn't silently skip
+      expect(result.ran).toBe(true);
+      expect(calls).toHaveLength(1);
+      const row = findAspectApproval('knot-unbound-internal', '1.0.0', getDb());
+      expect(row?.consented).toBe(true); // approval recorded
+    });
+
+    it('interviews when undecided and skips on refusal (persists the denial)', async () => {
+      seedModuleRow({ id: 'knot-unbound-internal', version: '1.0.0' });
+      const { fake, calls } = makeFakeRunner();
+      const result = await maybeRunAspectForTrigger({
+        moduleId: 'knot-unbound-internal',
+        manifest: manifestWithAspect,
+        trigger: 'on_install',
+        db: getDb(),
+        runner: fake,
+        requestConsent: async () => false,
+      });
+      expect(result.ran).toBe(false);
+      expect(result.reason).toBe('denied');
+      expect(calls).toHaveLength(0);
+      const row = findAspectApproval('knot-unbound-internal', '1.0.0', getDb());
+      expect(row?.consented).toBe(false); // refusal recorded so it won't be re-asked
+    });
+
+    it('does NOT re-prompt once consent was refused', async () => {
       seedModuleRow({ id: 'knot-unbound-internal', version: '1.0.0' });
-      // No recordAspectApproval call.
+      recordAspectConsent({
+        moduleId: 'knot-unbound-internal',
+        version: '1.0.0',
+        scopeHash: computeAspectScopeHash(
+          manifestWithAspect.base_module_aspect as BaseModuleAspect,
+        ),
+        approver: null,
+        consented: false,
+        db: getDb(),
+      });
       const { fake, calls } = makeFakeRunner();
       const result = await maybeRunAspectForTrigger({
         moduleId: 'knot-unbound-internal',
@@ -403,13 +543,16 @@ describe('aspect-runner', () => {
         trigger: 'on_install',
         db: getDb(),
         runner: fake,
+        requestConsent: async () => {
+          throw new Error('must not re-prompt an already-refused aspect');
+        },
       });
       expect(result.ran).toBe(false);
-      expect(result.reason).toBe('no_approval');
+      expect(result.reason).toBe('denied');
       expect(calls).toHaveLength(0);
     });
 
-    it('skips with "scope_changed" when manifest scope diverged from approval', async () => {
+    it('re-interviews when the approved scope diverged, then runs on consent', async () => {
       seedModuleRow({ id: 'knot-unbound-internal', version: '1.0.0' });
       // Approve under a narrower scope than the manifest now declares.
       const oldScope: BaseModuleAspect = {
@@ -425,16 +568,26 @@ describe('aspect-runner', () => {
         db: getDb(),
       });
       const { fake, calls } = makeFakeRunner();
+      const asked: string[] = [];
       const result = await maybeRunAspectForTrigger({
         moduleId: 'knot-unbound-internal',
         manifest: manifestWithAspect,
         trigger: 'on_install',
         db: getDb(),
         runner: fake,
+        requestConsent: async (a) => {
+          asked.push(a.reason);
+          return true;
+        },
       });
-      expect(result.ran).toBe(false);
-      expect(result.reason).toBe('scope_changed');
-      expect(calls).toHaveLength(0);
+      expect(asked).toEqual(['scope_changed']);
+      expect(result.ran).toBe(true);
+      expect(calls).toHaveLength(1);
+      // The single (module, version) row now reflects the new, wider scope.
+      const row = findAspectApproval('knot-unbound-internal', '1.0.0', getDb());
+      expect(row?.scopeHash).toBe(
+        computeAspectScopeHash(manifestWithAspect.base_module_aspect as BaseModuleAspect),
+      );
     });
 
     it('dispatches to the runner when everything checks out', async () => {

package/src/services/aspect-runner.ts

@@ -11,9 +11,12 @@
  * machinery does the actual SSH + playbook execution; the runner
  * only sets up the per-aspect Ansible workspace.
  *
- * Scope NOT covered in SC3:
- *  - Container_service (Proxmox LXC) systems are deferred to a
- *    follow-up — `getSystemsByZone` covers the machines table only.
+ * Fan-out covers BOTH machine-pool systems and container_service
+ * LXCs in the aspect's zones (ISS-0028): machines come from
+ * `getSystemsByZone`, LXCs from `getContainerSystemsInZones`. LXCs
+ * authenticate via the ambient operator key (no per-host key).
+ *
+ * Scope NOT covered here:
  *  - Proxmox `nameserver` reconciliation is SC5.
  *  - Trigger wiring (when `on_install` / `on_new_system_in_zone`
  *    etc. fire) is SC4. SC3 ships the pure execution surface so
@@ -28,23 +31,53 @@ import { join } from 'node:path';
 import { eq } from 'drizzle-orm';
 import { type InventoryHost, generateHostsIni } from '../ansible/inventory';
 import { log } from '../cli/prompts';
-import type { getDb } from '../db/client';
-import { modules } from '../db/schema';
+import { getDb } from '../db/client';
+import { type NetworkZone, modules } from '../db/schema';
 import type { BaseModuleAspect, BaseModuleAspectTrigger, ModuleManifest } from '../manifest/schema';
 import type { Machine } from '../types/infrastructure';
-import { checkAspectApproval } from './aspect-approvals';
+import {
+  checkAspectApproval,
+  computeAspectScopeHash,
+  recordAspectConsent,
+} from './aspect-approvals';
 import { resolveAspectTemplateRecord } from './aspect-template-resolver';
+import {
+  type AspectConsentReply,
+  type AspectRequiredPayload,
+  EVENT_TYPES,
+  busInterviewGuarded,
+} from './bus-interview';
 import { executeAnsible } from './deploy-ansible';
+import { getContainerSystemsInZones } from './deployed-systems';
 import { getSystemsByZone } from './machine-pool';
 import { executeProxmoxReconcile, planProxmoxReconcile } from './proxmox-reconcile';
 import { writeTemporarySshKey } from './ssh-key-manager';
 
 type DbClient = ReturnType<typeof getDb>;
 
+/**
+ * A single host an aspect fans out to — a machine-pool box OR a
+ * container_service LXC (ISS-0028). The two differ only in SSH auth:
+ *
+ *   - machine: `machineId` is set; its per-machine key is materialized via
+ *     `writeTemporarySshKey(machineId)` and pinned in the inventory row.
+ *   - LXC: `machineId` is undefined; it authenticates via the ambient operator
+ *     key (the one terraform injected at provision time), exactly as a normal
+ *     LXC module deploy does — so the inventory row carries no key file.
+ */
+export interface AspectTarget {
+  hostname: string;
+  ipAddress: string;
+  sshUser: string;
+  zone: NetworkZone;
+  /** Set for machine-pool targets only. Drives per-machine SSH key staging. */
+  machineId?: string;
+}
+
 export interface AspectFanOutPlan {
-  /** Systems the aspect will run on. */
-  targetSystems: Machine[];
-  /** Systems that matched the zones but were excluded (api_only, etc.). */
+  /** Systems the aspect will run on (machines + container_service LXCs). */
+  targetSystems: AspectTarget[];
+  /** Machines that matched the zones but were excluded (api_only, etc.). */
   skipped: Array<{ machine: Machine; reason: string }>;
 }
 
@@ -86,21 +119,45 @@ export async function planAspectFanOut(
   aspect: BaseModuleAspect,
   options: Pick<AspectRunOptions, 'excludeHostnames'> = {},
 ): Promise<AspectFanOutPlan> {
-  // Pull the candidate set with api_only already filtered out so
-  // we can record the skips separately for observability.
+  // Machine-pool systems in the zones (api_only recorded as skips for
+  // observability). excludeHostnames is applied by getSystemsByZone.
   const allInZones = await getSystemsByZone(aspect.applicable_zones, {
     excludeApiOnly: false,
     excludeHostnames: options.excludeHostnames,
   });
 
-  const targetSystems: Machine[] = [];
+  const targetSystems: AspectTarget[] = [];
   const skipped: AspectFanOutPlan['skipped'] = [];
+  const seen = new Set<string>();
   for (const m of allInZones) {
     if (m.apiOnly) {
       skipped.push({ machine: m, reason: 'api_only' });
-    } else {
-      targetSystems.push(m);
+      continue;
     }
+    targetSystems.push({
+      hostname: m.hostname,
+      ipAddress: m.ipAddress,
+      sshUser: m.sshUser,
+      zone: m.zone,
+      machineId: m.id,
+    });
+    seen.add(m.hostname);
+  }
+
+  // Container_service LXCs in the same zones (ISS-0028). The machines-only
+  // fan-out skipped these; without them an aspect like dns-client-config can't
+  // reach caddy/celilo-registry. They auth via the ambient operator key, so no
+  // machineId / per-host key.
+  const exclude = new Set(options.excludeHostnames ?? []);
+  for (const sys of getContainerSystemsInZones(aspect.applicable_zones, getDb())) {
+    if (exclude.has(sys.hostname) || seen.has(sys.hostname)) continue;
+    targetSystems.push({
+      hostname: sys.hostname,
+      ipAddress: sys.ipv4_address,
+      sshUser: 'root',
+      zone: sys.zone as NetworkZone,
+    });
+    seen.add(sys.hostname);
   }
 
   return { targetSystems, skipped };
@@ -133,7 +190,7 @@ export async function materializeAspectAnsible(args: {
   /** Absolute path to the module's imported source dir. The aspect
    *  role is expected at `<moduleSourcePath>/base-module-aspect/ansible/roles/<aspect.ansible_role>`. */
   moduleSourcePath: string;
-  targetSystems: Machine[];
+  targetSystems: AspectTarget[];
   /** Provider module ID — used to resolve $self / $capability /
    *  $system references in ansible_vars. */
   providerModuleId?: string;
@@ -163,23 +220,25 @@ export async function materializeAspectAnsible(args: {
   await mkdir(hostVarsDir, { recursive: true });
   await mkdir(rolesDir, { recursive: true });
 
-  // Stage each system's SSH key and build inventory rows.
+  // Stage each target's SSH access and build inventory rows. Machines pin
+  // their per-machine key; LXCs (machineId undefined) leave it off and use the
+  // ambient operator key — same as a normal LXC deploy (ISS-0028).
   const inventoryHosts: InventoryHost[] = [];
-  for (const m of targetSystems) {
-    const keyPath = await writeTemporarySshKey(m.id);
+  for (const t of targetSystems) {
+    const keyPath = t.machineId ? await writeTemporarySshKey(t.machineId) : undefined;
     inventoryHosts.push({
-      hostname: m.hostname,
-      ansibleHost: m.ipAddress,
-      ansibleUser: m.sshUser,
-      groups: ['aspect_targets', m.zone],
+      hostname: t.hostname,
+      ansibleHost: t.ipAddress,
+      ansibleUser: t.sshUser,
+      groups: ['aspect_targets', t.zone],
       ansibleSshPrivateKeyFile: keyPath,
     });
 
     // Per-host vars: target_zone is the only fact the framework
     // guarantees today (per D3). Capability-data / module-config
     // injection is Phase 2+.
-    const hostVars = `---\n# Aspect host vars for ${m.hostname}\ntarget_zone: ${m.zone}\n`;
-    await writeFile(join(hostVarsDir, `${m.hostname}.yml`), hostVars, 'utf-8');
+    const hostVars = `---\n# Aspect host vars for ${t.hostname}\ntarget_zone: ${t.zone}\n`;
+    await writeFile(join(hostVarsDir, `${t.hostname}.yml`), hostVars, 'utf-8');
   }
 
   // hosts.ini groups every target under 'aspect_targets' and the
@@ -340,8 +399,47 @@ export type AspectSkipReason =
   | 'no_aspect' // module didn't declare base_module_aspect
   | 'trigger_not_declared' // aspect.triggers doesn't include this trigger
   | 'no_approval' // operator hasn't approved (D2)
+  | 'denied' // operator explicitly refused consent (ISS-0027)
   | 'scope_changed'; // approval exists but applicable_zones/triggers diverged (D7)
 
+/**
+ * Asks the operator to approve (true) or refuse (false) a module's
+ * base-module aspect. Injectable so unit tests don't drive the bus;
+ * the default (`requestAspectConsentViaBus`) emits an
+ * `aspect.required.<module>.<role>` interview question and waits for
+ * a responder (terminal, `celilo events reply`, the celilo-deploy
+ * skill). See ISS-0027.
+ */
+export type AspectConsentRequest = (args: {
+  moduleId: string;
+  version: string;
+  aspect: BaseModuleAspect;
+  trigger: BaseModuleAspectTrigger;
+  reason: 'no_approval' | 'scope_changed';
+}) => Promise<boolean>;
+
+async function requestAspectConsentViaBus(args: {
+  moduleId: string;
+  version: string;
+  aspect: BaseModuleAspect;
+  trigger: BaseModuleAspectTrigger;
+  reason: 'no_approval' | 'scope_changed';
+}): Promise<boolean> {
+  const payload: AspectRequiredPayload = {
+    module: args.moduleId,
+    role: args.aspect.ansible_role,
+    zones: args.aspect.applicable_zones,
+    triggers: args.aspect.triggers,
+    trigger: args.trigger,
+    reason: args.reason,
+  };
+  const reply = await busInterviewGuarded<AspectConsentReply>(
+    EVENT_TYPES.aspectRequired(args.moduleId, args.aspect.ansible_role),
+    payload,
+  );
+  return reply.consented === true;
+}
+
 export interface AspectGlueResult {
   ran: boolean;
   /** Populated when `ran === true`. */
@@ -388,6 +486,8 @@ export async function maybeRunAspectForTrigger(args: {
   db: DbClient;
   runner?: typeof runAspectFanOut;
   excludeHostnames?: string[];
+  /** Injectable consent prompt (default: bus interview). See ISS-0027. */
+  requestConsent?: AspectConsentRequest;
 }): Promise<AspectGlueResult> {
   const { moduleId, manifest, trigger, db } = args;
   const aspect = manifest.base_module_aspect;
@@ -410,17 +510,39 @@ export async function maybeRunAspectForTrigger(args: {
   }
 
   const approvalStatus = checkAspectApproval(moduleId, moduleRow.version, aspect, db);
-  if (approvalStatus === 'no_approval') {
-    log.warn(
-      `Aspect for '${moduleId}' is declared but not approved. Re-import the module to grant consent; aspect skipped.`,
-    );
-    return { ran: false, reason: 'no_approval' };
+
+  // Already-approved → run. Already-DENIED → skip silently: the operator
+  // made a durable decision; re-prompting every deploy would be nagging
+  // (ISS-0027). Only the undecided ('no_approval') and stale ('scope_changed')
+  // states warrant an interview.
+  if (approvalStatus === 'denied') {
+    return { ran: false, reason: 'denied' };
   }
-  if (approvalStatus === 'scope_changed') {
-    log.warn(
-      `Aspect for '${moduleId}@${moduleRow.version}' has scope changes from the prior approval. Re-import to re-approve; aspect skipped.`,
-    );
-    return { ran: false, reason: 'scope_changed' };
+  if (approvalStatus === 'no_approval' || approvalStatus === 'scope_changed') {
+    // ISS-0027: don't silently skip a declared aspect. Interview the operator
+    // for consent on the bus and WAIT. A responder (terminal, `events reply`,
+    // the celilo-deploy skill) approves or denies. We persist the decision —
+    // either way — so a denial isn't re-asked next deploy.
+    const requestConsent = args.requestConsent ?? requestAspectConsentViaBus;
+    const consented = await requestConsent({
+      moduleId,
+      version: moduleRow.version,
+      aspect,
+      trigger,
+      reason: approvalStatus,
+    });
+    recordAspectConsent({
+      moduleId,
+      version: moduleRow.version,
+      scopeHash: computeAspectScopeHash(aspect),
+      approver: process.env.USER ?? null,
+      consented,
+      db,
+    });
+    if (!consented) {
+      log.warn(`Aspect for '${moduleId}' consent refused; aspect skipped (will not re-prompt).`);
+      return { ran: false, reason: 'denied' };
+    }
   }
 
   const runner = args.runner ?? runAspectFanOut;

package/src/services/backup-create.ts

@@ -26,7 +26,12 @@ import { getOrCreateMasterKey } from '../secrets/master-key';
 import { shellEscape } from '../utils/shell';
 import { buildManifest } from './backup-manifest';
 import { completeBackup, createBackupRecord, failBackup, listBackups } from './backup-metadata';
-import { createStorageProvider, getBackupStorage, getDefaultBackupStorage } from './backup-storage';
+import {
+  createStorageProvider,
+  getBackupStorage,
+  getBackupStorageByStorageId,
+  getDefaultBackupStorage,
+} from './backup-storage';
 import { materializeCrossModuleRoot, moduleHasCrossModuleRead } from './cross-module-read';
 import { getModuleSystems } from './deployed-systems';
 import {
@@ -57,7 +62,11 @@ export type BackupSchedule = 'hourly' | 'daily' | 'weekly' | 'monthly' | 'manual
  */
 export function resolveStorage(storageId?: string) {
   if (storageId) {
-    const storage = getBackupStorage(storageId);
+    // Accept the human storageId NAME (what `storage list` shows and what the
+    // operator passes to --storage, e.g. "aws-backups") first, falling back to
+    // the internal UUID. Users never see UUIDs (CLAUDE.md), so name-first is
+    // the correct resolution order.
+    const storage = getBackupStorageByStorageId(storageId) ?? getBackupStorage(storageId);
     if (!storage) {
       throw new Error(`Storage not found: ${storageId}`);
     }

package/src/services/bus-ensure-flow.test.ts

@@ -119,7 +119,25 @@ function startEnsureResponder(
     });
   });
 
-  return { seen, close: () => handle.close() };
+  // Real responders answer `responder.probe` so the deploy's fail-fast guard
+  // (ISS-0025) knows a responder is listening. A bespoke fixture must too, or
+  // busInterviewGuarded throws before the ensure prompt is ever emitted.
+  const probeHandle = bus.watch('responder.probe', (event) => {
+    if (event.replyFor !== null) return;
+    bus.emitRaw(
+      `${event.type}.reply`,
+      { kind: 'programmatic', emittedBy: 'test-responder' },
+      { replyFor: event.id, emittedBy: 'test-responder' },
+    );
+  });
+
+  return {
+    seen,
+    close: () => {
+      handle.close();
+      probeHandle.close();
+    },
+  };
 }
 
 describe('bus-mediated interviewForEnsureInputs', () => {

package/src/services/bus-interview.ts

@@ -14,6 +14,7 @@
 
 import { type Bus, defineEvents, openBus } from '@celilo/event-bus';
 import { getEventBusPath } from '../config/paths';
+import { ensureResponderForInterview } from './responder-probe';
 
 const NO_SCHEMAS = defineEvents({});
 
@@ -21,8 +22,42 @@ export const EVENT_TYPES = {
   configRequired: (module: string, key: string) => `config.required.${module}.${key}`,
   secretRequired: (module: string, key: string) => `secret.required.${module}.${key}`,
   ensureRequired: (provider: string, ensureId: string) => `ensure.required.${provider}.${ensureId}`,
+  aspectRequired: (module: string, role: string) => `aspect.required.${module}.${role}`,
 } as const;
 
+/**
+ * Payload for `aspect.required.<module>.<role>`. Emitted when a deploy is
+ * about to fan out a module's `base_module_aspect` but the operator has not
+ * granted consent (no approval recorded, or the approved scope diverged). The
+ * deploy WAITS for a responder to approve/deny instead of silently skipping —
+ * see ISS-0027. The reply (`AspectConsentReply`) carries only the decision; the
+ * deploy process records the approval (it holds module/version/scope), exactly
+ * as `module import --accept-aspects` would.
+ *
+ * The scope (`ansible_role`, `zones`, `triggers`) is included so the responder
+ * can show the operator what running the aspect means — informed consent,
+ * mirroring the interactive import prompt.
+ */
+export interface AspectRequiredPayload {
+  module: string;
+  /** The aspect's `ansible_role` — doubles as the role segment of the type. */
+  role: string;
+  zones: string[];
+  triggers: string[];
+  /** The trigger currently firing (e.g. `on_install`). */
+  trigger: string;
+  /**
+   * Why consent is needed: `no_approval` (never approved) or `scope_changed`
+   * (approved before, but `applicable_zones`/`triggers` diverged → re-consent).
+   */
+  reason: 'no_approval' | 'scope_changed';
+  description?: string;
+}
+
+export interface AspectConsentReply {
+  consented: boolean;
+}
+
 /**
  * Payload for `config.required.<module>.<key>`. The deploy emits this
  * when a non-secret variable is missing AND has no default to fall
@@ -181,3 +216,24 @@ export async function busInterview<TReply>(
     if (ownsBus) bus.close();
   }
 }
+
+/**
+ * `busInterview` with a fail-fast guard for headless deploys (ISS-0025).
+ *
+ * Same contract as `busInterview`, but first calls
+ * `ensureResponderForInterview` — so a non-TTY deploy with no responder
+ * listening throws an actionable error instead of waiting forever. This is the
+ * variant deploy-time interview sites (config / secret / ensure / aspect) use;
+ * raw `busInterview` stays for callers that guarantee a responder (tests,
+ * internal probes). The guard runs per prompt, so it also catches a responder
+ * that dies mid-deploy, and it never fires for auto-derived / auto-generated
+ * values (those never reach an interview query).
+ */
+export async function busInterviewGuarded<TReply>(
+  type: string,
+  payload: object,
+  ownerBus?: Bus,
+): Promise<TReply> {
+  await ensureResponderForInterview(type);
+  return busInterview<TReply>(type, payload, ownerBus);
+}

package/src/services/bus-secret-flow.test.ts

@@ -79,7 +79,25 @@ function startTestResponder(
     );
   });
 
-  return { seen, close: () => handle.close() };
+  // Real responders answer `responder.probe` so the deploy's fail-fast guard
+  // (ISS-0025) knows a responder is listening. A bespoke fixture must too, or
+  // busInterviewGuarded throws before the secret prompt is ever emitted.
+  const probeHandle = bus.watch('responder.probe', (event) => {
+    if (event.replyFor !== null) return;
+    bus.emitRaw(
+      `${event.type}.reply`,
+      { kind: 'programmatic', emittedBy: 'test-responder' },
+      { replyFor: event.id, emittedBy: 'test-responder' },
+    );
+  });
+
+  return {
+    seen,
+    close: () => {
+      handle.close();
+      probeHandle.close();
+    },
+  };
 }
 
 function writeSecretsSchema(