@celilo/cli 0.3.11 → 0.3.13

package/src/db/client.ts

@@ -1,5 +1,5 @@
 import { Database } from 'bun:sqlite';
-import { existsSync } from 'node:fs';
+import { existsSync, mkdirSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { drizzle } from 'drizzle-orm/bun-sqlite';
@@ -166,6 +166,13 @@ export function createDbClient(config?: Partial<DatabaseConfig>) {
   const dbPath = config?.path ?? getDbPath();
   const readonly = config?.readonly ?? false;
 
+  // bun:sqlite's `create: true` makes the file but not the parent directory.
+  // First-run after a fresh install hits this — without recursive mkdir we
+  // get SQLITE_CANTOPEN before init can write its config.
+  if (!readonly) {
+    mkdirSync(dirname(dbPath), { recursive: true });
+  }
+
   const sqlite = new Database(dbPath, {
     readonly,
     create: true,

package/src/hooks/logger.ts

@@ -72,7 +72,12 @@ export function createGaugeLogger(
         // pushStep nests under the FuelGauge step that wraps the hook,
         // so inner log calls (logger.info within the capability impl)
         // are sub-events of this nested step.
-        display.pushStep(`→ ${name}`, `✓ ${name}`);
+        //
+        // No `→`/`✓` glyph in the message — the display's spinner
+        // (in-progress) and green ✔ (done) already convey the state.
+        // Sticking a literal `✓` into the doneMsg produced a double-
+        // checkmark line on completion (`✔ ✓ name`).
+        display.pushStep(name, name);
       } else {
         // Without a display, fall back to a plain info-style marker so
         // the line still appears in raw log output.

package/src/module/import.ts

@@ -429,62 +429,100 @@ async function installScriptDependencies(
 export async function importModule(options: ModuleImportOptions): Promise<ModuleImportResult> {
   const { sourcePath, targetBasePath = getDefaultTargetBase(), db = getDb(), flags = {} } = options;
 
-  let actualSourcePath = sourcePath;
+  // Directory imports route through the packager: build a temporary .netapp
+  // and re-enter through the package path. This makes the .netapp pipeline
+  // the single import path — no second flow that drifts. The packager is
+  // also the only place a manifest build runs, with CELILO_MODULE_SOURCE_DIR
+  // pointing at the unstaged source so sibling-package paths in a monorepo
+  // resolve (e.g. celilo-registry's `cd $CELILO_MODULE_SOURCE_DIR/../../packages/registry-server`).
+  // After this point the module is detached from the source tree, so a
+  // deploy-time rebuild can't work — bake the artifacts in here, once.
+  if (!sourcePath.endsWith('.netapp')) {
+    const dirError = validateModuleDirectory(sourcePath);
+    if (dirError) return { success: false, error: dirError };
+
+    const manifestResult = await readModuleManifest(sourcePath);
+    if (!manifestResult.success) return { success: false, error: manifestResult.error };
+
+    if (moduleExists(manifestResult.manifest.id, db)) {
+      return {
+        success: false,
+        error: `Module '${manifestResult.manifest.id}' already exists. Use update or remove it first.`,
+      };
+    }
+
+    const { mkdtempSync, rmSync } = await import('node:fs');
+    const { tmpdir } = await import('node:os');
+    const tempPkgDir = mkdtempSync(join(tmpdir(), 'celilo-import-pkg-'));
+    const tempPkgPath = join(tempPkgDir, `${manifestResult.manifest.id}.netapp`);
+
+    try {
+      const { buildModule } = await import('./packaging/build');
+      const buildResult = await buildModule({ sourceDir: sourcePath, outputPath: tempPkgPath });
+      if (!buildResult.success) {
+        return {
+          success: false,
+          error: buildResult.error || 'Failed to package module for import',
+        };
+      }
+      return await importModule({ ...options, sourcePath: tempPkgPath });
+    } finally {
+      rmSync(tempPkgDir, { recursive: true, force: true });
+    }
+  }
+
   let tempDir: string | null = null;
   let checksums: Record<string, string> | null = null;
   let signature: string | null = null;
 
   try {
-    // Check if source is a .netapp package
-    if (sourcePath.endsWith('.netapp')) {
-      // Extract and verify package
-      const extractResult = await extractPackage(sourcePath);
-      if (!extractResult.success || !extractResult.tempDir) {
-        return { success: false, error: extractResult.error || 'Failed to extract package' };
-      }
+    // sourcePath always ends with .netapp at this point — directory inputs
+    // were re-routed through the packager above and recursed back in here.
+    const extractResult = await extractPackage(sourcePath);
+    if (!extractResult.success || !extractResult.tempDir) {
+      return { success: false, error: extractResult.error || 'Failed to extract package' };
+    }
 
-      tempDir = extractResult.tempDir;
-
-      // Verify package integrity (unless --skip-verify)
-      const skipVerify = flags['skip-verify'] === true;
-      if (skipVerify) {
-        log.warn('Skipping package signature verification (--skip-verify)');
-      } else {
-        const verifyResult = await verifyPackageIntegrity(tempDir);
-        if (!verifyResult.success) {
-          await cleanupTempDir(tempDir);
-          return {
-            success: false,
-            error: verifyResult.error || 'Package integrity verification failed',
-          };
-        }
-      }
+    tempDir = extractResult.tempDir;
 
-      // Read checksums and signature for database storage (both optional with --skip-verify)
-      try {
-        const checksumsJson = await readFile(join(tempDir, 'checksums.json'), 'utf-8');
-        const ChecksumsFileSchema = z.object({
-          files: z.record(z.string(), z.string()),
-        });
-        const checksumsData = parseJsonWithValidation(
-          checksumsJson,
-          ChecksumsFileSchema,
-          'package checksums.json',
-        );
-        checksums = checksumsData.files;
-      } catch (err) {
-        if (!skipVerify) throw err;
-      }
-      try {
-        signature = await readFile(join(tempDir, 'signature.sig'), 'utf-8');
-      } catch (err) {
-        if (!skipVerify) throw err;
+    // Verify package integrity (unless --skip-verify)
+    const skipVerify = flags['skip-verify'] === true;
+    if (skipVerify) {
+      log.warn('Skipping package signature verification (--skip-verify)');
+    } else {
+      const verifyResult = await verifyPackageIntegrity(tempDir);
+      if (!verifyResult.success) {
+        await cleanupTempDir(tempDir);
+        return {
+          success: false,
+          error: verifyResult.error || 'Package integrity verification failed',
+        };
       }
+    }
 
-      // Use extracted directory as source
-      actualSourcePath = tempDir;
+    // Read checksums and signature for database storage (both optional with --skip-verify)
+    try {
+      const checksumsJson = await readFile(join(tempDir, 'checksums.json'), 'utf-8');
+      const ChecksumsFileSchema = z.object({
+        files: z.record(z.string(), z.string()),
+      });
+      const checksumsData = parseJsonWithValidation(
+        checksumsJson,
+        ChecksumsFileSchema,
+        'package checksums.json',
+      );
+      checksums = checksumsData.files;
+    } catch (err) {
+      if (!skipVerify) throw err;
+    }
+    try {
+      signature = await readFile(join(tempDir, 'signature.sig'), 'utf-8');
+    } catch (err) {
+      if (!skipVerify) throw err;
     }
 
+    const actualSourcePath = tempDir;
+
     // Policy: Validate directory structure
     const dirError = validateModuleDirectory(actualSourcePath);
     if (dirError) {
@@ -639,29 +677,14 @@ export async function importModule(options: ModuleImportOptions): Promise<Module
       );
     }
 
-    // Execution: Store integrity data
-    // For .netapp packages: store checksums + signature
-    // For directory imports: calculate and store checksums (no signature)
+    // Execution: Store integrity data from the package's checksums + signature.
+    // Directory imports go through the packager too (see top of importModule),
+    // so by the time we reach this point we always have these.
     try {
-      let finalChecksums: Record<string, string>;
-      let finalSignature: string | null = null;
-
-      if (checksums && signature) {
-        // From .netapp package - already verified
-        finalChecksums = checksums;
-        finalSignature = signature.trim();
-      } else {
-        // From directory - calculate checksums now
-        const { computeChecksums } = await import('./packaging/build');
-        const checksumsData = await computeChecksums(targetPath);
-        finalChecksums = checksumsData.files;
-        // No signature for directory imports
-      }
-
       const integrityData: NewModuleIntegrity = {
         moduleId: manifest.id,
-        checksums: finalChecksums,
-        signature: finalSignature,
+        checksums: checksums ?? {},
+        signature: signature?.trim() ?? null,
       };
       db.insert(moduleIntegrity).values(integrityData).run();
     } catch (error) {
@@ -669,21 +692,22 @@ export async function importModule(options: ModuleImportOptions): Promise<Module
       console.warn('Warning: Failed to store module integrity data', error);
     }
 
-    // For .netapp packages with build artifacts: record a successful build
-    // so that `module generate` doesn't require a rebuild
-    if (sourcePath.endsWith('.netapp') && manifest.build?.artifacts) {
-      const { existsSync: fileExists } = await import('node:fs');
-      const artifactPaths = manifest.build.artifacts
+    // Record a successful build entry so deploy-time validation sees the
+    // artifacts in place and skips rebuild. The packager runs the manifest
+    // build into the staged tree before tar, so any declared artifacts are
+    // already on disk under targetPath at this point.
+    if (manifest.build?.artifacts) {
+      const recordedArtifactPaths = manifest.build.artifacts
         .map((a: string) => join(targetPath, a))
-        .filter((p: string) => fileExists(p));
+        .filter((p: string) => existsSync(p));
 
-      if (artifactPaths.length > 0) {
+      if (recordedArtifactPaths.length > 0) {
         const { moduleBuilds } = await import('../db/schema');
         db.insert(moduleBuilds)
           .values({
             moduleId: manifest.id,
             version: manifest.version,
-            artifacts: artifactPaths,
+            artifacts: recordedArtifactPaths,
             status: 'success',
             buildLog: 'Pre-built artifacts from .netapp package',
           })

package/src/services/deploy-validation.ts

@@ -4,6 +4,8 @@
  * Validates module readiness and auto-prepares (generate/build) if needed
  */
 
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
 import { compareConsumerToProvider } from '@celilo/capabilities';
 import { and, eq } from 'drizzle-orm';
 import type { DbClient } from '../db/client';
@@ -123,10 +125,22 @@ export async function validateAndPrepareDeployment(
   // Auto-build if required and not built
   if (manifest.build) {
     const buildStatus = await getModuleBuildStatus(moduleId, db);
+    // Cross-check the manifest's declared artifacts against the actual
+    // filesystem in addition to whatever's in the build record. A "success"
+    // record with an empty artifact list (e.g. from a build that exited 0
+    // but produced nothing, or a synthetic record from a partial .netapp
+    // import) would otherwise pass `verifyArtifactsExist([])` trivially and
+    // let the deploy run on without binaries — exactly how Ansible ends up
+    // failing on a missing `src:` file.
+    const declaredArtifacts = manifest.build.artifacts ?? [];
+    const declaredArtifactsOk = declaredArtifacts.every((rel) =>
+      existsSync(join(module.sourcePath, rel)),
+    );
     const needsBuild =
       !buildStatus ||
       buildStatus.status !== 'success' ||
-      !verifyArtifactsExist(buildStatus.artifacts);
+      !verifyArtifactsExist(buildStatus.artifacts) ||
+      (declaredArtifacts.length > 0 && !declaredArtifactsOk);
 
     if (needsBuild) {
       const buildResult = await buildModuleFromSource(moduleId, db);

package/src/services/module-build.test.ts

@@ -207,6 +207,44 @@ describe('Module Build Service', () => {
       expect(buildRecord?.status).toBe('success');
       expect(buildRecord?.environment).toBe('system'); // No flake.nix
     }, 10000); // 10 second timeout for ansible execution
+
+    // Regression: a build.command that references $CELILO_MODULE_SOURCE_DIR
+    // (the variable celilo-registry's manifest uses to find sibling packages
+    // in the monorepo) must work the same at deploy time as at packaging
+    // time. Before the fix, executeBuildCommand didn't set the env var, so
+    // any module that imported from a local directory and relied on it
+    // would silently fail before producing artifacts.
+    test('build.command receives CELILO_MODULE_SOURCE_DIR pointing at modulePath', async () => {
+      await mkdir(TEST_MODULE_DIR, { recursive: true });
+
+      db.insert(modules)
+        .values({
+          id: 'env-test',
+          name: 'Env Test',
+          version: '1.0.0',
+          sourcePath: TEST_MODULE_DIR,
+          manifestData: {
+            id: 'env-test',
+            name: 'Env Test',
+            version: '1.0.0',
+            build: {
+              // Write the env var's value to a file. The build runs with
+              // cwd=modulePath, so a bare relative `built.marker` always
+              // lands there — but we want to prove the env var itself was
+              // set, so we fail explicitly if it's empty.
+              command:
+                'test -n "$CELILO_MODULE_SOURCE_DIR" && echo "$CELILO_MODULE_SOURCE_DIR" > built.marker',
+              artifacts: ['built.marker'],
+            },
+          },
+        })
+        .run();
+
+      const result = await buildModuleFromSource('env-test', db);
+
+      expect(result.success).toBe(true);
+      expect(existsSync(`${TEST_MODULE_DIR}/built.marker`)).toBe(true);
+    }, 10000);
   });
 
   describe('getModuleBuildStatus', () => {

package/src/services/module-build.ts

@@ -104,6 +104,11 @@ async function executeBuildCommand(
     command,
     args: [],
     cwd: modulePath,
+    // Match packaging/build.ts so deploy-time builds work the same as
+    // package-time builds. celilo-registry's manifest.build.command uses
+    // $CELILO_MODULE_SOURCE_DIR to find sibling packages in the monorepo;
+    // without this, that cd resolves to "/" and the build silently fails.
+    env: { CELILO_MODULE_SOURCE_DIR: modulePath },
   });
 
   return { success: result.success, output: result.output, error: result.error };
@@ -143,6 +148,7 @@ async function executeBuildScript(
     command,
     args,
     cwd: modulePath,
+    env: { CELILO_MODULE_SOURCE_DIR: modulePath },
   });
 
   return { success: result.success, output: result.output, error: result.error };

package/src/services/module-deploy.ts

@@ -35,6 +35,7 @@ import { executeTerraform, parseTerraformOutputs } from './deploy-terraform';
 import { validateAndPrepareDeployment } from './deploy-validation';
 import { resolveInfrastructureVariables } from './infrastructure-variable-resolver';
 import { findMachineForModule } from './machine-pool';
+import { checkProxmoxReachable, formatProxmoxUnreachableError } from './proxmox-preflight';
 import { deleteTemporarySshKey, writeTemporarySshKey } from './ssh-key-manager';
 import { buildTerraformEnvForService } from './terraform-env';
 
@@ -814,6 +815,20 @@ async function deployModuleImpl(
           };
         }
         terraformEnvVars = await buildTerraformEnvForService(plan.infrastructure.serviceId);
+
+        // Fail fast if the proxmox API host is unreachable (e.g. VPN
+        // down). The terraform provider would otherwise stall on a
+        // SYN_SENT connect for ~60s with no visible feedback.
+        if (service.providerName === 'proxmox' && terraformEnvVars.TF_VAR_proxmox_api_url) {
+          const probe = await checkProxmoxReachable(terraformEnvVars.TF_VAR_proxmox_api_url);
+          if (!probe.reachable) {
+            return {
+              success: false,
+              error: formatProxmoxUnreachableError(probe),
+              phases,
+            };
+          }
+        }
       }
 
       const terraformResult = await executeTerraform(generatedPath, phases, terraformEnvVars, {
@@ -1219,12 +1234,23 @@ async function deployModuleImpl(
         }
       }
 
-      // Auto-register module hostname in internal DNS (if available)
+      // Auto-register module hostname in internal DNS (if available).
+      // Wrapped in a FuelGauge with a gauge logger so the capability calls
+      // inside (`dns_internal.registerRecord`, etc.) nest as sub-events
+      // under a single step rather than leaking to scrollback as
+      // unindented top-level lines via cli/prompts.log.instantEvent.
       let dnsRegistered = true;
+      const dnsGauge = new FuelGauge(`Registering ${moduleId} in DNS`, {
+        skipAnimation: !process.stdout.isTTY,
+      });
+      dnsGauge.start();
       try {
+        const dnsLogger = createGaugeLogger(dnsGauge, moduleId, 'auto_register_dns');
         const { autoRegisterDns } = await import('./dns-auto-register');
-        await autoRegisterDns(moduleId, db, log);
+        await autoRegisterDns(moduleId, db, dnsLogger);
+        dnsGauge.stop(true);
       } catch (error) {
+        dnsGauge.stop(false);
         const msg = error instanceof Error ? error.message : String(error);
         log.warn(`DNS auto-registration failed: ${msg}`);
         dnsRegistered = false;

package/src/services/programmatic-responder.ts

@@ -276,6 +276,20 @@ export function startProgrammaticResponder(
     answered.push({ type: event.type, key: lookupKey });
   });
 
+  // Liveness probe: a non-interactive caller (e.g. `module generate`
+  // with no TTY) emits `responder.probe` to detect whether any
+  // responder is listening before calling busInterview (which waits
+  // forever). We reply with our kind so the caller's probe completes
+  // and the deploy/generate proceeds.
+  const probeWatch = bus.watch('responder.probe', async (event) => {
+    if (event.replyFor !== null) return;
+    bus.emitRaw(
+      `${event.type}.reply`,
+      { kind: 'programmatic', emittedBy: me },
+      { replyFor: event.id, emittedBy: me },
+    );
+  });
+
   return {
     lastActivityAt: () => lastActivityAt,
     eventCount: () => answered.length + missed.length,
@@ -288,6 +302,7 @@ export function startProgrammaticResponder(
       configWatch.close();
       secretWatch.close();
       ensureWatch.close();
+      probeWatch.close();
       bus.close();
     },
   };

package/src/services/proxmox-preflight.test.ts

@@ -0,0 +1,63 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+import { type AddressInfo, type Server, createServer } from 'node:net';
+import { checkProxmoxReachable, formatProxmoxUnreachableError } from './proxmox-preflight';
+
+describe('checkProxmoxReachable', () => {
+  let server: Server | null = null;
+
+  afterEach(async () => {
+    if (server) {
+      await new Promise<void>((resolve) => server?.close(() => resolve()));
+      server = null;
+    }
+  });
+
+  test('returns reachable=true when the host accepts the connection', async () => {
+    server = createServer();
+    await new Promise<void>((resolve) => server?.listen(0, '127.0.0.1', () => resolve()));
+    const port = (server.address() as AddressInfo).port;
+
+    const result = await checkProxmoxReachable(`https://127.0.0.1:${port}/api2/json`, 1000);
+    expect(result.reachable).toBe(true);
+    expect(result.host).toBe('127.0.0.1');
+    expect(result.port).toBe(port);
+    expect(result.error).toBeUndefined();
+  });
+
+  test('returns reachable=false on connection refused', async () => {
+    // Port 1 is reserved and reliably refuses on loopback.
+    const result = await checkProxmoxReachable('https://127.0.0.1:1/api2/json', 1000);
+    expect(result.reachable).toBe(false);
+    expect(result.host).toBe('127.0.0.1');
+    expect(result.port).toBe(1);
+    expect(result.error).toBeDefined();
+  });
+
+  test('returns reachable=false with timeout error on stalled connect', async () => {
+    // 192.0.2.1 is in TEST-NET-1 (RFC 5737) — guaranteed unroutable.
+    // SYN_SENT will hang until our timeout fires.
+    const result = await checkProxmoxReachable('https://192.0.2.1:8006/api2/json', 200);
+    expect(result.reachable).toBe(false);
+    expect(result.error).toMatch(/timed out/i);
+  }, 5000);
+
+  test('returns error for an invalid URL', async () => {
+    const result = await checkProxmoxReachable('not-a-url', 100);
+    expect(result.reachable).toBe(false);
+    expect(result.error).toMatch(/invalid/i);
+  });
+});
+
+describe('formatProxmoxUnreachableError', () => {
+  test('mentions VPN and the host:port in the message', () => {
+    const message = formatProxmoxUnreachableError({
+      reachable: false,
+      host: '10.0.30.102',
+      port: 8006,
+      error: 'Connection refused',
+    });
+    expect(message).toContain('10.0.30.102:8006');
+    expect(message).toContain('VPN');
+    expect(message).toContain('Connection refused');
+  });
+});

package/src/services/proxmox-preflight.ts

@@ -0,0 +1,100 @@
+/**
+ * Proxmox preflight reachability check.
+ *
+ * The Proxmox Terraform provider, when given an unreachable api_url,
+ * sits in TCP `SYN_SENT` until the kernel-level connect timeout fires
+ * — typically 30–75s on macOS. During that window the user sees a
+ * frozen progress display and no clue what's wrong (common cause: VPN
+ * is down). We probe the api_url's host:port with a short timeout
+ * before invoking terraform so we can fail fast with an actionable
+ * message instead of letting the provider hang.
+ *
+ * Scoped intentionally to the proxmox container-service deploy path —
+ * other terraform invocations (DigitalOcean, system audit) talk to
+ * different endpoints with their own failure modes.
+ */
+
+import { Socket } from 'node:net';
+
+export interface ProxmoxReachabilityResult {
+  reachable: boolean;
+  host: string;
+  port: number;
+  /** Populated when `reachable` is false. */
+  error?: string;
+}
+
+/**
+ * Probe `host:port` with a TCP connect attempt. Resolves on connect,
+ * timeout, or socket error — never rejects. Caller decides what to do
+ * with the result.
+ */
+export async function checkProxmoxReachable(
+  apiUrl: string,
+  timeoutMs = 3000,
+): Promise<ProxmoxReachabilityResult> {
+  let host: string;
+  let port: number;
+  try {
+    const url = new URL(apiUrl);
+    host = url.hostname;
+    port = url.port ? Number(url.port) : url.protocol === 'https:' ? 443 : 80;
+  } catch {
+    return {
+      reachable: false,
+      host: apiUrl,
+      port: 0,
+      error: `Invalid Proxmox API URL: ${apiUrl}`,
+    };
+  }
+
+  return await new Promise<ProxmoxReachabilityResult>((resolve) => {
+    const socket = new Socket();
+    let settled = false;
+
+    const finish = (result: ProxmoxReachabilityResult) => {
+      if (settled) return;
+      settled = true;
+      socket.destroy();
+      resolve(result);
+    };
+
+    socket.setTimeout(timeoutMs);
+    socket.once('connect', () => finish({ reachable: true, host, port }));
+    socket.once('timeout', () =>
+      finish({
+        reachable: false,
+        host,
+        port,
+        error: `Connection to ${host}:${port} timed out after ${timeoutMs}ms`,
+      }),
+    );
+    socket.once('error', (err) =>
+      finish({
+        reachable: false,
+        host,
+        port,
+        error: err.message,
+      }),
+    );
+
+    socket.connect(port, host);
+  });
+}
+
+/**
+ * Format an unreachable result into a multi-line error message
+ * suitable for display in the deploy progress panel.
+ */
+export function formatProxmoxUnreachableError(result: ProxmoxReachabilityResult): string {
+  return [
+    `Proxmox unreachable at ${result.host}:${result.port}`,
+    '',
+    'Check:',
+    '  - VPN connection (if Proxmox is on a private network)',
+    '  - Is the Proxmox host running and reachable from this machine?',
+    `  - Try: nc -zv ${result.host} ${result.port}`,
+    '',
+    `(${result.error ?? 'no further detail'})`,
+  ].join('\n');
+}

package/src/services/responder-probe.ts

@@ -0,0 +1,45 @@
+/**
+ * Responder liveness probe.
+ *
+ * busInterview waits forever for a reply (timeoutMs: 0 by design). For
+ * non-interactive callers (no TTY, no piped responder) that means a
+ * silent hang. The probe gives those callers a way to fail fast: emit
+ * a short-timeout query on the bus, return whether any responder was
+ * listening.
+ *
+ * Responders register a `responder.probe` watch and reply with their
+ * kind. As long as one is running on the same bus DB, the probe sees
+ * a reply and returns true.
+ */
+
+import { defineEvents, openBus } from '@celilo/event-bus';
+
+const NO_SCHEMAS = defineEvents({});
+
+export const RESPONDER_PROBE_EVENT = 'responder.probe' as const;
+
+export interface ResponderProbeReply {
+  kind: 'terminal' | 'programmatic' | 'daemon';
+  emittedBy: string;
+}
+
+/**
+ * Probe the bus for a live responder.
+ *
+ * @param busDbPath sqlite path the bus and any responder share
+ * @param timeoutMs how long to wait for a reply (default 1500ms)
+ * @returns true if at least one responder replied within the window
+ */
+export async function probeForResponder(busDbPath: string, timeoutMs = 1500): Promise<boolean> {
+  const bus = openBus({ dbPath: busDbPath, events: NO_SCHEMAS });
+  try {
+    const replies = await bus.query(RESPONDER_PROBE_EVENT as never, {} as never, {
+      timeoutMs,
+      pollIntervalMs: 100,
+      expect: 'first',
+    });
+    return replies.length > 0;
+  } finally {
+    bus.close();
+  }
+}

package/src/services/terminal-responder.ts

@@ -283,11 +283,24 @@ export function startTerminalResponder(): TerminalResponderHandle {
     });
   });
 
+  // Liveness probe: lets a non-interactive caller in another shell
+  // (e.g. `module generate`) detect that a terminal-responder is
+  // running here and that calling busInterview is safe.
+  const probeWatch = bus.watch('responder.probe', async (event) => {
+    if (event.replyFor !== null) return;
+    bus.emitRaw(
+      `${event.type}.reply`,
+      { kind: 'terminal', emittedBy: me },
+      { replyFor: event.id, emittedBy: me },
+    );
+  });
+
   return {
     close() {
       configWatch.close();
       secretWatch.close();
       ensureWatch.close();
+      probeWatch.close();
       bus.close();
     },
   };