@celilo/cli 0.5.0-alpha.8 → 0.5.0-alpha.9

package/src/cli/commands/system-init.ts

@@ -5,8 +5,8 @@
  * or applies defaults for non-interactive use.
  */
 
-import * as p from '@clack/prompts';
 import { getDb } from '../../db/client';
+import { askConfirm, askSelect, askText, withInterviewSession } from '../../services/bus-interview';
 import {
   autoDetectSSHKeys,
   getDefaultConfiguration,
@@ -14,9 +14,8 @@ import {
   isSystemInitialized,
   loadExistingConfiguration,
 } from '../../services/system-init';
-import { celiloIntro, celiloOutro, promptConfirm, promptText } from '../prompts';
+import { celiloIntro, celiloOutro } from '../prompts';
 import type { CommandResult } from '../types';
-import { validateRequired } from '../validators';
 
 /**
  * Parse key=value pairs from positional arguments
@@ -163,139 +162,131 @@ async function initInteractive(cliOverrides: Record<string, string> = {}): Promi
   // Helper: skip prompt if value already provided via CLI
   const has = (key: string) => key in cliOverrides;
 
-  await celiloIntro('🎛️  Welcome to Celilo System Setup');
-
-  // Network and DNS addressing are intentionally NOT prompted here.
-  // Network topology is no longer owned by `system init`
-  // (v2/NETWORK_CONFIG_TO_FIREWALL.md): the `internal` zone and DNS are
-  // discovered when celilo-mgmt is deployed, and `dmz`/`app`/`secure`
-  // come from a firewall module. The only thing left to capture
-  // interactively is the SSH key celilo uses to reach managed machines.
-
-  // SSH Key — skip if provided via CLI
-  if (!has('ssh.public_key')) {
-    const detectedKeys = autoDetectSSHKeys();
-    const existingSshKey = defaults['ssh.public_key'];
-
-    // Fresh box, no key in ~/.ssh and no previously-saved key — point the
-    // user at ssh-keygen rather than making them paste at a blank prompt.
-    // They can also skip this branch by passing ssh.public_key=... on the CLI.
-    if (detectedKeys.length === 0 && !existingSshKey) {
-      p.cancel('No SSH key found in ~/.ssh/');
-      console.log();
-      console.log('Celilo uses an SSH key to reach managed machines');
-      console.log('(Proxmox hosts, VPS, Raspberry Pi, etc.). Generate one:');
-      console.log();
-      console.log('    ssh-keygen -t ed25519 -C "<your-email>"');
-      console.log();
-      console.log('Then re-run:  celilo system init');
-      console.log();
-      console.log('Or, to paste a key from elsewhere without generating one:');
-      console.log('    celilo system init ssh.public_key="ssh-ed25519 AAAA..."');
-      return { success: false, error: 'No SSH key available — run ssh-keygen first' };
-    }
-
-    let keySelected = false;
-
-    if (detectedKeys.length === 1) {
-      // Single key: confirm
-      const key = detectedKeys[0];
-      const keyPreview = `${key.keyType} ...${key.content.slice(-20)}`;
-      const useDetected = await promptConfirm({
-        message: `Auto-detected SSH key (${key.filename}: ${keyPreview}) - Use it?`,
-        initialValue: true,
-      });
-
-      if (useDetected) {
-        overrides['ssh.public_key'] = key.content;
-        keySelected = true;
-      }
-    } else if (detectedKeys.length > 1) {
-      // Multiple keys: selection menu
-      const PASTE_OPTION = '__paste__';
-      const selected = await p.select({
-        message: `Found ${detectedKeys.length} SSH keys in ~/.ssh/`,
-        options: [
-          ...detectedKeys.map((key) => ({
-            value: key.content,
-            label: key.filename,
-            hint: `${key.keyType} ...${key.content.slice(-20)}`,
-          })),
-          { value: PASTE_OPTION, label: 'Paste a different key' },
-        ],
-      });
-
-      if (p.isCancel(selected)) {
-        p.cancel('Operation cancelled');
-        return { success: false, error: 'Cancelled by user' };
+  // Every prompt below is a bus interview (ISS-0127), so `system init` is
+  // drivable headlessly via `celilo events respond --values` / `events reply`.
+  // `withInterviewSession` renders bus questions locally when stdin is a TTY.
+  const scope = 'system-init';
+
+  return withInterviewSession(async () => {
+    await celiloIntro('🎛️  Welcome to Celilo System Setup');
+
+    // Network and DNS addressing are intentionally NOT prompted here.
+    // Network topology is no longer owned by `system init`
+    // (v2/NETWORK_CONFIG_TO_FIREWALL.md): the `internal` zone and DNS are
+    // discovered when celilo-mgmt is deployed, and `dmz`/`app`/`secure`
+    // come from a firewall module. The only thing left to capture
+    // interactively is the SSH key celilo uses to reach managed machines.
+
+    // SSH Key — skip if provided via CLI
+    if (!has('ssh.public_key')) {
+      const detectedKeys = autoDetectSSHKeys();
+      const existingSshKey = defaults['ssh.public_key'];
+
+      // Fresh box, no key in ~/.ssh and no previously-saved key — point the
+      // user at ssh-keygen rather than making them paste at a blank prompt.
+      // They can also skip this branch by passing ssh.public_key=... on the CLI.
+      if (detectedKeys.length === 0 && !existingSshKey) {
+        console.log('No SSH key found in ~/.ssh/');
+        console.log();
+        console.log('Celilo uses an SSH key to reach managed machines');
+        console.log('(Proxmox hosts, VPS, Raspberry Pi, etc.). Generate one:');
+        console.log();
+        console.log('    ssh-keygen -t ed25519 -C "<your-email>"');
+        console.log();
+        console.log('Then re-run:  celilo system init');
+        console.log();
+        console.log('Or, to paste a key from elsewhere without generating one:');
+        console.log('    celilo system init ssh.public_key="ssh-ed25519 AAAA..."');
+        return { success: false, error: 'No SSH key available — run ssh-keygen first' };
       }
 
-      if (selected !== PASTE_OPTION) {
-        overrides['ssh.public_key'] = selected as string;
-        keySelected = true;
+      let keySelected = false;
+
+      if (detectedKeys.length === 1) {
+        // Single key: confirm
+        const key = detectedKeys[0];
+        const keyPreview = `${key.keyType} ...${key.content.slice(-20)}`;
+        const useDetected = await askConfirm({
+          scope,
+          key: 'ssh_use_detected',
+          message: `Auto-detected SSH key (${key.filename}: ${keyPreview}) - Use it?`,
+          defaultValue: true,
+        });
+
+        if (useDetected) {
+          overrides['ssh.public_key'] = key.content;
+          keySelected = true;
+        }
+      } else if (detectedKeys.length > 1) {
+        // Multiple keys: selection menu
+        const PASTE_OPTION = '__paste__';
+        const selected = await askSelect({
+          scope,
+          key: 'ssh_key_choice',
+          message: `Found ${detectedKeys.length} SSH keys in ~/.ssh/`,
+          options: [
+            ...detectedKeys.map((key) => ({
+              value: key.content,
+              label: key.filename,
+              hint: `${key.keyType} ...${key.content.slice(-20)}`,
+            })),
+            { value: PASTE_OPTION, label: 'Paste a different key' },
+          ],
+        });
+
+        if (selected !== PASTE_OPTION) {
+          overrides['ssh.public_key'] = selected;
+          keySelected = true;
+        }
       }
-    }
 
-    // Manual prompt if no key selected from detection
-    if (!keySelected) {
-      overrides['ssh.public_key'] = await promptText({
-        message: existingSshKey
-          ? 'SSH public key (press Enter to keep existing)'
-          : 'SSH public key',
-        defaultValue: String(existingSshKey || ''),
-        // String(undefined) === 'undefined' (truthy), so guard explicitly —
-        // otherwise the prompt shows "undefined" as the placeholder text.
-        placeholder: existingSshKey ? String(existingSshKey) : 'ssh-ed25519 AAAA...',
-        validate: (value) => {
-          if (existingSshKey && !value) {
-            return;
-          }
-          if (!value) {
-            return 'SSH public key is required';
-          }
-        },
-      });
-      if (!overrides['ssh.public_key'] && existingSshKey) {
-        overrides['ssh.public_key'] = existingSshKey;
-      }
-    } else if (existingSshKey) {
-      overrides['ssh.public_key'] = await promptText({
-        message: 'SSH public key (press Enter to keep existing)',
-        defaultValue: String(existingSshKey),
-        placeholder: String(existingSshKey),
-        validate: () => undefined,
-      });
-      if (!overrides['ssh.public_key']) {
-        overrides['ssh.public_key'] = existingSshKey;
+      // Manual prompt if no key selected from detection
+      if (!keySelected) {
+        const entered = await askText({
+          scope,
+          key: 'ssh_public_key',
+          message: existingSshKey
+            ? 'SSH public key (press Enter to keep existing)'
+            : 'SSH public key',
+          defaultValue: existingSshKey ? String(existingSshKey) : undefined,
+          // String(undefined) === 'undefined' (truthy), so guard explicitly —
+          // otherwise the prompt shows "undefined" as the placeholder text.
+          placeholder: existingSshKey ? String(existingSshKey) : 'ssh-ed25519 AAAA...',
+          required: !existingSshKey,
+        });
+        overrides['ssh.public_key'] = entered || existingSshKey;
+      } else if (existingSshKey) {
+        const entered = await askText({
+          scope,
+          key: 'ssh_public_key',
+          message: 'SSH public key (press Enter to keep existing)',
+          defaultValue: String(existingSshKey),
+          placeholder: String(existingSshKey),
+        });
+        overrides['ssh.public_key'] = entered || existingSshKey;
       }
-    } else {
-      overrides['ssh.public_key'] = await promptText({
-        message: 'SSH public key',
-        placeholder: 'ssh-ed25519 AAAA...',
-        validate: validateRequired('SSH public key'),
-      });
     }
-  }
 
-  // Apply configuration (called for its DB side effects).
-  initializeSystem(db, overrides);
+    // Apply configuration (called for its DB side effects).
+    initializeSystem(db, overrides);
 
-  await celiloOutro('✅ System initialization complete!');
+    await celiloOutro('✅ System initialization complete!');
 
-  console.log('\nNext steps:');
-  console.log('  1. Configure infrastructure:');
-  console.log('     Container services:');
-  console.log('       - celilo service add proxmox');
-  console.log('       - celilo service add digitalocean');
-  console.log('     Existing hardware:');
-  console.log('       - celilo machine add');
-  console.log('');
-  console.log('  2. Import a module:    celilo module import <path>');
-  console.log('  3. Configure module:   celilo module config set <module-id> <key> <value>');
-  console.log('  4. Generate infra:     celilo module generate <module-id>');
+    console.log('\nNext steps:');
+    console.log('  1. Configure infrastructure:');
+    console.log('     Container services:');
+    console.log('       - celilo service add proxmox');
+    console.log('       - celilo service add digitalocean');
+    console.log('     Existing hardware:');
+    console.log('       - celilo machine add');
+    console.log('');
+    console.log('  2. Import a module:    celilo module import <path>');
+    console.log('  3. Configure module:   celilo module config set <module-id> <key> <value>');
+    console.log('  4. Generate infra:     celilo module generate <module-id>');
 
-  return {
-    success: true,
-    message: 'System initialized successfully',
-  };
+    return {
+      success: true,
+      message: 'System initialized successfully',
+    };
+  });
 }

package/src/cli/completion.ts

@@ -40,6 +40,7 @@ export async function getCompletions(words: string[], current: number): Promise<
       'machine',
       'module',
       'package',
+      'proxmox',
       'publish',
       'restore',
       'service',
@@ -244,6 +245,20 @@ export async function getCompletions(words: string[], current: number): Promise<
   }
 
   // Service subcommands
+  // Proxmox subcommands
+  if (command === 'proxmox' && currentIndex === 1) {
+    return filterSuggestions(['node'], args[1] || '');
+  }
+  if (command === 'proxmox' && args[1] === 'node' && currentIndex === 2) {
+    return filterSuggestions(['list'], args[2] || '');
+  }
+  // proxmox node list <service-id> — proxmox services only
+  if (command === 'proxmox' && args[1] === 'node' && args[2] === 'list' && currentIndex === 3) {
+    const services = await listContainerServices();
+    const serviceIds = services.filter((s) => s.providerName === 'proxmox').map((s) => s.serviceId);
+    return filterSuggestions(serviceIds, args[3] || '');
+  }
+
   if (command === 'service' && currentIndex === 1) {
     const subcommands = ['add', 'list', 'verify', 'reconfigure', 'remove', 'config'];
     return filterSuggestions(subcommands, args[1] || '');

package/src/cli/index.ts

@@ -66,6 +66,7 @@ import { handleModuleTypesCheck, handleModuleTypesGenerate } from './commands/mo
 import { handleModuleUpgrade } from './commands/module-upgrade';
 import { moduleVerify } from './commands/module-verify';
 import { handlePackage } from './commands/package';
+import { handleProxmoxNodeList } from './commands/proxmox-node-list';
 import { main as runPublish } from './commands/publish';
 import { handleSecretList } from './commands/secret-list';
 import { handleSecretSet } from './commands/secret-set';
@@ -175,6 +176,7 @@ Commands:
   machine                  Manage machine pool (bring-your-own-hardware)
   system                   Manage system configuration
   ipam                     Manage IP address and VMID allocations and reservations
+  proxmox                  Proxmox cluster introspection (proxmox node list)
   publish                  Publish workspace packages to npm and modules to celilo.computer
   subscribers              Manage build-bus subscribers (cross-machine publish-event delivery)
   completion               Generate shell completion scripts (bash/zsh)
@@ -1794,6 +1796,29 @@ export async function runCli(argv: string[]): Promise<CommandResult> {
     };
   }
 
+  if (parsed.command === 'proxmox') {
+    if (!parsed.subcommand) {
+      return {
+        success: false,
+        error: 'Proxmox subcommand required (node)\n\nRun "celilo proxmox --help" for usage',
+      };
+    }
+    if (parsed.subcommand === 'node') {
+      const nodeSubcommand = parsed.args[0];
+      if (nodeSubcommand === 'list') {
+        return handleProxmoxNodeList(parsed.args.slice(1), parsed.flags);
+      }
+      return {
+        success: false,
+        error: 'Proxmox node action required (list)\n\nRun "celilo proxmox --help" for usage',
+      };
+    }
+    return {
+      success: false,
+      error: `Unknown proxmox subcommand: ${parsed.subcommand}\n\nRun "celilo proxmox --help" for usage`,
+    };
+  }
+
   if (parsed.command === 'ipam') {
     // Handle ipam --help
     if (parsed.flags.help || parsed.flags.h) {

package/src/cli/service-credential.ts

@@ -0,0 +1,54 @@
+/**
+ * Service-credential secret resolution (ISS-0127, D7).
+ *
+ * Service credentials (a Proxmox API token, a DigitalOcean API token, an SSH
+ * password) are a special kind of secret: at `service add` time the service
+ * does not exist yet, so there is no encrypted store to write the value to
+ * out-of-band and no safe sink for a bus reply. Per design decision D7 these
+ * secrets therefore travel by **flag or env var**, never over the event bus.
+ *
+ * The resolution order is: explicit `--<flag>` → `$ENV` → (only when stdin is
+ * a TTY) a local clack `password` prompt → otherwise a fail-fast error naming
+ * the flag and env var. This keeps a zero-TTY `service add` possible while the
+ * credential never lands on the bus, and the local password prompt is the one
+ * clack input the recurrence gate (D6) allow-lists — precisely because a
+ * flag/env path always exists alongside it.
+ */
+
+import { promptPassword } from './prompts';
+
+export interface ServiceCredentialSpec {
+  /** Human-readable field name used in the prompt + error, e.g. "API token secret". */
+  field: string;
+  /** The flag value (already resolved from `flags[<flag>]`), if the operator passed `--<flag>`. */
+  flagValue: string | boolean | undefined;
+  /** The CLI flag the operator would pass, e.g. `api-token-secret`. */
+  flag: string;
+  /** The environment variable that supplies the value headlessly, e.g. `PROXMOX_API_TOKEN_SECRET`. */
+  envVar: string;
+}
+
+/**
+ * Resolve a service-credential secret from flag → env → (TTY) clack password →
+ * error. Returns the secret value as a string. Throws an actionable error when
+ * no value is available on a non-TTY run.
+ */
+export async function resolveServiceCredential(spec: ServiceCredentialSpec): Promise<string> {
+  if (typeof spec.flagValue === 'string' && spec.flagValue.trim() !== '') {
+    return spec.flagValue.trim();
+  }
+
+  const fromEnv = process.env[spec.envVar];
+  if (fromEnv && fromEnv.trim() !== '') {
+    return fromEnv.trim();
+  }
+
+  if (process.stdin.isTTY) {
+    return promptPassword({
+      message: `${spec.field}:`,
+      validate: (val) => (!val || val.trim() === '' ? `${spec.field} is required` : undefined),
+    });
+  }
+
+  throw new Error(`${spec.field} required: pass --${spec.flag} or set $${spec.envVar} (no TTY)`);
+}

package/src/services/bus-interview.ts

@@ -23,6 +23,13 @@ export const EVENT_TYPES = {
   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}`,
+  /**
+   * Generic interview family (ISS-0127). Unlike the module-scoped families
+   * above, this carries a free-form `scope` (e.g. `service:proxmox-home-lab`)
+   * so non-deploy operator commands can ask questions over the same bus the
+   * deploy interview uses — making them headlessly drivable.
+   */
+  interviewRequired: (scope: string, key: string) => `interview.required.${scope}.${key}`,
 } as const;
 
 /**
@@ -182,6 +189,58 @@ export interface EnsureReply {
   acknowledged?: true;
 }
 
+/**
+ * The four shapes a generic interview question can take. The responder
+ * renders by `kind`: `text` is a free-text prompt (with type coercion +
+ * pattern validation), `confirm` is a yes/no, `select` is a single choice
+ * from `options`, `multiselect` is zero-or-more choices from `options`.
+ */
+export type InterviewKind = 'text' | 'confirm' | 'select' | 'multiselect';
+
+/**
+ * Payload for `interview.required.<scope>.<key>` (ISS-0127). The generic
+ * counterpart to `ConfigRequiredPayload`: it carries everything a responder
+ * needs to render any of the four `kind`s, plus a `scope`/`key` pair that
+ * gives the question a stable identity a headless responder can answer by.
+ *
+ * Storage of the answer is always the emitting command's job (mirroring the
+ * deploy families), so responders never need to know what `scope:key` means —
+ * they just render and reply.
+ */
+export interface InterviewRequiredPayload {
+  /** Stable namespace for the question, e.g. `service:proxmox-home-lab`. */
+  scope: string;
+  /** Stable identifier within the scope, e.g. `default_target_node`. */
+  key: string;
+  kind: InterviewKind;
+  message: string;
+  required: boolean;
+  description?: string;
+  /** For `text`/`select`: the value used if the operator just hits Enter. For `confirm`: `'true'` | `'false'`. */
+  defaultValue?: string;
+  /** `text` only — grayed-out hint shown in the input field. */
+  placeholder?: string;
+  /** `select`/`multiselect` only — the choices. */
+  options?: Array<{ value: string; label: string; hint?: string }>;
+  /** `text` only — how to coerce the typed value. Defaults to `'string'`. */
+  type?: 'string' | 'integer' | 'number' | 'boolean';
+  /** `text` only — regex the typed value must match. */
+  pattern?: string;
+  /** Set on re-emits after a previous reply failed validation. */
+  previousError?: string;
+  /** 1-indexed attempt counter. Bounds prevent infinite re-emit loops. */
+  attempt?: number;
+}
+
+/**
+ * Reply to an `interview.required.*` query. `value`'s runtime shape follows
+ * the payload's `kind`: `string` (text/select), `string[]` (multiselect),
+ * `boolean` (confirm), or `number` (text with `type: integer|number`).
+ */
+export interface InterviewReply {
+  value: unknown;
+}
+
 /**
  * Emit a query event on the bus and wait for a responder to reply.
  *
@@ -237,3 +296,176 @@ export async function busInterviewGuarded<TReply>(
   await ensureResponderForInterview(type);
   return busInterview<TReply>(type, payload, ownerBus);
 }
+
+/**
+ * Ask a single generic interview question over the bus and return the
+ * responder's answer (ISS-0127). The generic counterpart to the deploy's
+ * config/secret/ensure interview: any operator command can call this to make
+ * its prompts headlessly drivable instead of calling clack directly.
+ *
+ * The return type is `unknown` because the runtime shape depends on
+ * `payload.kind`; prefer the typed wrappers (`askText`, `askSelect`,
+ * `askMultiselect`, `askConfirm`) at call sites — they narrow it for you.
+ *
+ * Guarded like the deploy families: a non-TTY caller with no responder
+ * listening fails fast instead of hanging forever.
+ */
+export async function askInterview(
+  payload: InterviewRequiredPayload,
+  ownerBus?: Bus,
+): Promise<unknown> {
+  const reply = await busInterviewGuarded<InterviewReply>(
+    EVENT_TYPES.interviewRequired(payload.scope, payload.key),
+    payload,
+    ownerBus,
+  );
+  return reply.value;
+}
+
+/**
+ * Run `fn` with a terminal-responder active when stdin is a TTY (ISS-0127).
+ *
+ * Every operator command that asks questions over the bus must, on a TTY,
+ * run a responder itself to render those questions — `askInterview`'s guard
+ * (`ensureResponderForInterview`) assumes one is already up when stdin is a
+ * TTY (it skips the no-responder check). On a non-TTY run no responder is
+ * started; the headless responder (`events respond --values` / `events
+ * reply`) answers instead, and the guard fails fast if none is listening.
+ *
+ * This is the shared lifecycle every migrated command wraps its interview in,
+ * so the start/close boilerplate lives in exactly one place. The dynamic
+ * import keeps clack out of the non-TTY path's module graph.
+ */
+export async function withInterviewSession<T>(fn: () => Promise<T>): Promise<T> {
+  const responder = process.stdin.isTTY
+    ? (await import('./terminal-responder')).startTerminalResponder()
+    : null;
+  try {
+    return await fn();
+  } finally {
+    responder?.close();
+  }
+}
+
+/**
+ * Ask for a free-text value over the bus. Returns the coerced answer as a
+ * string (the responder coerces `integer`/`number`/`boolean` per `type`, but
+ * the value still arrives as a JSON scalar; callers that want a number should
+ * pass `type` and read it as such — here we narrow to the string form that
+ * the existing `promptText` call sites expect).
+ */
+export async function askText(opts: {
+  scope: string;
+  key: string;
+  message: string;
+  description?: string;
+  defaultValue?: string;
+  placeholder?: string;
+  required?: boolean;
+  type?: 'string' | 'integer' | 'number' | 'boolean';
+  pattern?: string;
+}): Promise<string> {
+  const value = await askInterview({
+    scope: opts.scope,
+    key: opts.key,
+    kind: 'text',
+    message: opts.message,
+    required: opts.required ?? false,
+    description: opts.description,
+    defaultValue: opts.defaultValue,
+    placeholder: opts.placeholder,
+    type: opts.type,
+    pattern: opts.pattern,
+  });
+  if (typeof value === 'string') return value;
+  if (typeof value === 'number' || typeof value === 'boolean') return String(value);
+  throw new Error(
+    `askText(${opts.scope}.${opts.key}): expected a string/number/boolean reply, got ${typeof value}`,
+  );
+}
+
+/**
+ * Ask the operator to pick one of `options` over the bus. Returns the chosen
+ * option's `value`.
+ */
+export async function askSelect(opts: {
+  scope: string;
+  key: string;
+  message: string;
+  options: Array<{ value: string; label: string; hint?: string }>;
+  defaultValue?: string;
+  description?: string;
+}): Promise<string> {
+  const value = await askInterview({
+    scope: opts.scope,
+    key: opts.key,
+    kind: 'select',
+    message: opts.message,
+    required: true,
+    options: opts.options,
+    defaultValue: opts.defaultValue,
+    description: opts.description,
+  });
+  if (typeof value !== 'string') {
+    throw new Error(
+      `askSelect(${opts.scope}.${opts.key}): expected a string reply, got ${typeof value}`,
+    );
+  }
+  return value;
+}
+
+/**
+ * Ask the operator to pick zero-or-more of `options` over the bus. Returns the
+ * chosen options' `value`s.
+ */
+export async function askMultiselect(opts: {
+  scope: string;
+  key: string;
+  message: string;
+  options: Array<{ value: string; label: string; hint?: string }>;
+  required?: boolean;
+  description?: string;
+}): Promise<string[]> {
+  const value = await askInterview({
+    scope: opts.scope,
+    key: opts.key,
+    kind: 'multiselect',
+    message: opts.message,
+    required: opts.required ?? false,
+    options: opts.options,
+    description: opts.description,
+  });
+  if (!Array.isArray(value) || value.some((v) => typeof v !== 'string')) {
+    throw new Error(
+      `askMultiselect(${opts.scope}.${opts.key}): expected a string[] reply, got ${typeof value}`,
+    );
+  }
+  return value as string[];
+}
+
+/**
+ * Ask a yes/no question over the bus. Returns the operator's boolean answer.
+ */
+export async function askConfirm(opts: {
+  scope: string;
+  key: string;
+  message: string;
+  defaultValue?: boolean;
+  description?: string;
+}): Promise<boolean> {
+  const value = await askInterview({
+    scope: opts.scope,
+    key: opts.key,
+    kind: 'confirm',
+    message: opts.message,
+    required: true,
+    defaultValue: opts.defaultValue === undefined ? undefined : String(opts.defaultValue),
+    description: opts.description,
+  });
+  if (typeof value !== 'boolean') {
+    throw new Error(
+      `askConfirm(${opts.scope}.${opts.key}): expected a boolean reply, got ${typeof value}`,
+    );
+  }
+  return value;
+}