@celilo/cli 0.21.0 → 0.23.0

package/src/cli/prompts.ts

@@ -1,10 +1,32 @@
 /**
  * Prompt Utilities
- * Beautiful interactive prompts using @clack/prompts
+ *
+ * A thin celilo-facing wrapper over the prompt/message primitives in
+ * `@celilo/cli-display`. Roughly 160 `log.*` call sites and every legacy
+ * direct prompt route through this module, which is what made replacing
+ * `@clack/prompts` a one-file change rather than a 160-file one (celilo#699).
+ *
+ * NOTE: new interactive decisions must NOT be added here. They belong on the
+ * event-bus interview (`services/bus-interview`), which a headless responder
+ * can answer; `test-integration/cli/headless-drivable.test.ts` enforces that
+ * no command reaches for these directly. What remains is the terminal renderer
+ * for a bus question, plus the legacy prompts that predate the interview.
  */
 
-import { getActiveDisplay, setActiveDisplay } from '@celilo/cli-display';
-import * as p from '@clack/prompts';
+import {
+  CANCEL,
+  cancel,
+  getActiveDisplay,
+  intro,
+  isCancel,
+  log,
+  note,
+  outro,
+  password,
+  setActiveDisplay,
+  text,
+  confirm as uiConfirm,
+} from '@celilo/cli-display';
 
 // Re-export so existing imports from `../cli/prompts` keep working.
 // The singleton itself lives in @celilo/cli-display so module code
@@ -12,25 +34,26 @@ import * as p from '@clack/prompts';
 // it via @celilo/capabilities's re-export.
 export { getActiveDisplay, setActiveDisplay };
 
+export { log };
+
 /**
  * Interactive prompt wrapper with celilo branding
  */
 export async function celiloIntro(title: string): Promise<void> {
-  p.intro(title);
+  intro(title);
 }
 
 export async function celiloOutro(message: string): Promise<void> {
-  p.outro(message);
+  outro(message);
 }
 
 /**
- * Prompt for text input with validation and help text
+ * Prompt for text input with validation and help text.
  *
- * Displays:
- * - Question/prompt message
- * - Input field with placeholder
- * - Help text below (muted) - like @clack/prompts screenshot
- * - Validation errors inline
+ * Displays the question, an input field with the placeholder, and any
+ * validation error inline. A cancel (Ctrl-C / Escape) exits the process, which
+ * is the behaviour every existing caller is written against: they treat the
+ * return as an unconditional `string`.
  */
 export async function promptText(options: {
   message: string;
@@ -38,19 +61,14 @@ export async function promptText(options: {
   placeholder?: string;
   validate?: (value: string | undefined) => string | Error | undefined;
 }): Promise<string> {
-  const result = await p.text({
-    message: options.message,
-    defaultValue: options.defaultValue,
-    placeholder: options.placeholder,
-    validate: options.validate,
-  });
-
-  if (p.isCancel(result)) {
-    p.cancel('Operation cancelled');
+  const result = await text(options);
+
+  if (isCancel(result)) {
+    cancel('Operation cancelled');
     process.exit(0);
   }
 
-  return result as string;
+  return result;
 }
 
 /**
@@ -62,30 +80,25 @@ export async function promptPassword(options: {
   validate?: (value: string | undefined) => string | Error | undefined;
 }): Promise<string> {
   while (true) {
-    const result = await p.password({
-      message: options.message,
-      validate: options.validate,
-    });
+    const result = await password(options);
 
-    if (p.isCancel(result)) {
-      p.cancel('Operation cancelled');
+    if (isCancel(result)) {
+      cancel('Operation cancelled');
       process.exit(0);
     }
 
-    const confirm = await p.password({
-      message: `Confirm ${options.message}`,
-    });
+    const confirmation = await password({ message: `Confirm ${options.message}` });
 
-    if (p.isCancel(confirm)) {
-      p.cancel('Operation cancelled');
+    if (isCancel(confirmation)) {
+      cancel('Operation cancelled');
       process.exit(0);
     }
 
-    if (result === confirm) {
-      return result as string;
+    if (result === confirmation) {
+      return result;
     }
 
-    p.log.warning('Passwords do not match. Please try again.');
+    log.warn('Passwords do not match. Please try again.');
   }
 }
 
@@ -96,53 +109,19 @@ export async function promptConfirm(options: {
   message: string;
   initialValue?: boolean;
 }): Promise<boolean> {
-  const result = await p.confirm({
-    message: options.message,
-    initialValue: options.initialValue,
-  });
+  const result = await uiConfirm(options);
 
-  if (p.isCancel(result)) {
-    p.cancel('Operation cancelled');
+  if (result === CANCEL) {
+    cancel('Operation cancelled');
     process.exit(0);
   }
 
-  return result as boolean;
+  return result;
 }
 
 /**
  * Show note/information box
  */
 export function showNote(message: string, title?: string): void {
-  p.note(message, title);
+  note(message, title);
 }
-
-/**
- * Show log messages
- */
-export const log = {
-  success: (message: string) => {
-    const d = getActiveDisplay();
-    if (d) return d.subEvent(`\x1b[32m✔\x1b[0m ${message}`);
-    p.log.success(message);
-  },
-  error: (message: string) => {
-    const d = getActiveDisplay();
-    if (d) return d.subEvent(`\x1b[31m✗\x1b[0m ${message}`);
-    p.log.error(message);
-  },
-  warn: (message: string) => {
-    const d = getActiveDisplay();
-    if (d) return d.subEvent(`\x1b[33m⚠\x1b[0m ${message}`);
-    p.log.warn(message);
-  },
-  info: (message: string) => {
-    const d = getActiveDisplay();
-    if (d) return d.instantEvent(message);
-    p.log.info(message);
-  },
-  message: (message: string) => {
-    const d = getActiveDisplay();
-    if (d) return d.subEvent(message);
-    p.log.message(message);
-  },
-};

package/src/cli/service-credential.ts

@@ -8,10 +8,10 @@
  * 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
+ * a TTY) a local masked `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
+ * direct prompt the recurrence gate (D6) tolerates — precisely because a
  * flag/env path always exists alongside it.
  */
 
@@ -29,7 +29,7 @@ export interface ServiceCredentialSpec {
 }
 
 /**
- * Resolve a service-credential secret from flag → env → (TTY) clack password →
+ * Resolve a service-credential secret from flag → env → (TTY) password prompt →
  * error. Returns the secret value as a string. Throws an actionable error when
  * no value is available on a non-TTY run.
  */

package/src/cli/stdout-is-undecorated.test.ts

@@ -0,0 +1,94 @@
+/**
+ * Recurrence gate for celilo#699 — ordinary stdout carries no decoration, and
+ * diagnostics do not share the stream with results.
+ *
+ * The CLI used to render every successful message through `@clack/prompts`,
+ * which prefixed each line with `│  ` and coloured it. Two costs followed, and
+ * this file pins both shut:
+ *
+ *  1. `line.startsWith('<module-id> ')` over `celilo module list` matched
+ *     nothing, because the line actually began `│  caddy (v2.2.0) - …`. In
+ *     celilo#695 that read as a MISSING MODULE rather than as a parse failure,
+ *     and cost a full e2e run to find. `e2e/tests/module-pause.test.ts` asserts
+ *     the same property against the real fleet topology; this is its fast
+ *     equivalent, so a regression is caught in seconds rather than in Docker.
+ *
+ *  2. clack wrote errors to stdout, so no caller could tell a result from a
+ *     complaint about producing one — `src/test-utils/cli.ts` carried a comment
+ *     saying exactly that, twice, and merged both streams to cope.
+ *
+ * Spawns the real CLI rather than using `CLIContext`: that harness runs the CLI
+ * in `CLI_SERVER_MODE`, which returns `result.message` over a protocol and
+ * never reaches the stdout writer under test here.
+ */
+
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import { spawnSync } from 'node:child_process';
+import { type IntegrationTestContext, setupIntegrationTest } from '@/test-utils/integration';
+
+let ctx: IntegrationTestContext;
+
+function celilo(command: string): { stdout: string; stderr: string; status: number | null } {
+  const result = spawnSync('bun', ['run', 'src/cli/index.ts', ...command.split(' ')], {
+    encoding: 'utf8',
+    env: {
+      ...process.env,
+      CELILO_DB_PATH: ctx.dbPath,
+      CELILO_DATA_DIR: ctx.dataDir,
+      CELILO_SUPPRESS_DEPRECATION: '1',
+    },
+    stdio: ['ignore', 'pipe', 'pipe'],
+    timeout: 60_000,
+  });
+  return { stdout: result.stdout, stderr: result.stderr, status: result.status };
+}
+
+/** The `│` clack used to open every rendered line with. */
+const BOX_DRAWING = /[│┌└├─]/;
+const ANSI = /\x1b\[[0-9;]*m/;
+
+describe('celilo#699 — stdout is undecorated', () => {
+  beforeAll(async () => {
+    ctx = await setupIntegrationTest();
+    // A module has to exist for `module list` to print a roster line at all —
+    // an empty roster would pass every assertion below without testing them.
+    const imported = celilo('module import ../../modules/celilo-mgmt');
+    expect(imported.status, `module import failed:\n${imported.stderr}`).toBe(0);
+  });
+
+  afterAll(async () => {
+    await ctx.cleanup();
+  });
+
+  test('module list lines start with the module id, with no preprocessing', () => {
+    const { stdout, status, stderr } = celilo('module list');
+    expect(status, `module list failed:\n${stderr}`).toBe(0);
+
+    // The exact shape celilo#695 tried and failed to match. No ANSI stripping,
+    // no prefix trimming — if this needs either, the bug is back.
+    const line = stdout.split('\n').find((l) => l.startsWith('celilo-mgmt '));
+
+    expect(
+      line,
+      `No line began with "celilo-mgmt ". stdout was:\n${JSON.stringify(stdout)}`,
+    ).toBeDefined();
+  });
+
+  test('module list stdout carries no box-drawing or ANSI', () => {
+    const { stdout } = celilo('module list');
+    expect(BOX_DRAWING.test(stdout), `box-drawing in stdout:\n${JSON.stringify(stdout)}`).toBe(
+      false,
+    );
+    expect(ANSI.test(stdout), `ANSI in stdout:\n${JSON.stringify(stdout)}`).toBe(false);
+  });
+
+  test('a failing command writes its diagnostic to stderr, not stdout', () => {
+    const { stdout, stderr, status } = celilo('module where no-such-module-exists');
+
+    expect(status).not.toBe(0);
+    expect(stderr).toContain('Error');
+    // The whole point: stdout stays empty so a caller parsing it is not handed
+    // an error message where a result belongs.
+    expect(stdout.trim(), `error text leaked to stdout: ${JSON.stringify(stdout)}`).toBe('');
+  });
+});

package/src/cli/types.ts

@@ -20,8 +20,13 @@ export interface CommandSuccess {
   message: string;
   data?: unknown;
   /**
-   * When true, the CLI writes `message` directly to stdout (no clack formatting).
-   * Use for commands designed to be consumed by scripts (e.g. `module secret get`).
+   * Marks a command whose `message` is a machine-readable payload (JSON, a
+   * unit file, a secret) rather than prose for a human.
+   *
+   * Every successful message now reaches stdout verbatim, so this no longer
+   * selects a different destination. It is kept as the contract: these are the
+   * commands a script parses, and nothing may ever decorate them (celilo#698,
+   * where ten JSON payloads were rendered unparseable by the formatter).
    */
   rawOutput?: boolean;
 }

package/src/db/schema.ts

@@ -11,7 +11,17 @@ import {
 
 /**
  * Module lifecycle states
- * IMPORTED, VALIDATED, CONFIGURED, GENERATING, ERROR, DEPLOYING, INSTALLED, VERIFIED, UNINSTALLING
+ * IMPORTED, VALIDATED, CONFIGURED, GENERATING, ERROR, DEPLOYING, INSTALLED, VERIFIED, UNINSTALLING, PAUSED
+ *
+ * `PAUSED` is a real member of this union rather than a side flag, and that is
+ * the point (openspec/changes/module-pause-lifecycle/design.md D1): adding it
+ * makes the type-checker enumerate every site that must now consider
+ * paused-ness. A `pausedAt`-only flag would leave every `state === 'VERIFIED'`
+ * comparison silently compiling while quietly reading a paused module as live.
+ *
+ * There is deliberately no `prePauseState`: pause is legal only from a settled
+ * state and unpause redeploys, so the deploy path decides the resulting state
+ * and there is nothing to restore.
  */
 export type ModuleState =
   | 'IMPORTED'
@@ -22,23 +32,65 @@ export type ModuleState =
   | 'INSTALLED'
   | 'VERIFIED'
   | 'ERROR'
-  | 'UNINSTALLING';
+  | 'UNINSTALLING'
+  | 'PAUSED';
+
+/**
+ * States a module may be paused FROM (design D1). `ERROR` is deliberately
+ * included: quiescing a broken module to stop alert noise while working on it
+ * is legitimate, and refusing would push the operator toward silencing those
+ * alerts by some less visible route.
+ */
+export const PAUSABLE_STATES = [
+  'INSTALLED',
+  'VERIFIED',
+  'ERROR',
+] as const satisfies readonly ModuleState[];
+
+/**
+ * States that mean "a lifecycle transition is under way". Pausing one of these
+ * would strand the transition, so pause is refused with a distinct message from
+ * the never-deployed case.
+ */
+export const IN_FLIGHT_STATES = [
+  'GENERATING',
+  'DEPLOYING',
+  'UNINSTALLING',
+] as const satisfies readonly ModuleState[];
 
 /**
  * Modules table - stores module metadata and manifest data
  */
-export const modules = sqliteTable('modules', {
-  id: text('id').primaryKey(),
-  name: text('name').notNull(),
-  version: text('version').notNull(),
-  description: text('description'),
-  state: text('state').$type<ModuleState>().notNull().default('IMPORTED'),
-  manifestData: text('manifest_data', { mode: 'json' }).$type<Record<string, unknown>>().notNull(),
-  sourcePath: text('source_path').notNull(),
-  importedAt: integer('imported_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
-  updatedAt: integer('updated_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
-  errorMessage: text('error_message'),
-});
+export const modules = sqliteTable(
+  'modules',
+  {
+    id: text('id').primaryKey(),
+    name: text('name').notNull(),
+    version: text('version').notNull(),
+    description: text('description'),
+    state: text('state').$type<ModuleState>().notNull().default('IMPORTED'),
+    manifestData: text('manifest_data', { mode: 'json' })
+      .$type<Record<string, unknown>>()
+      .notNull(),
+    sourcePath: text('source_path').notNull(),
+    importedAt: integer('imported_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
+    updatedAt: integer('updated_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
+    errorMessage: text('error_message'),
+    /**
+     * When the module was paused. Null unless `state = 'PAUSED'`. The state alone
+     * cannot answer "how long", and the DURATION is what makes a forgotten pause
+     * detectable (design D7) — every paused-module report carries the age.
+     */
+    pausedAt: integer('paused_at', { mode: 'timestamp' }),
+    /** Operator-supplied explanation, so the row explains itself. */
+    pauseReason: text('pause_reason'),
+  },
+  (table) => ({
+    // Every management-API response asks "is anything paused?" (design D7), so
+    // that lookup must stay a single indexed hit rather than a table scan.
+    stateIdx: index('modules_state_idx').on(table.state),
+  }),
+);
 
 /**
  * Module configuration - user-provided key-value pairs.
@@ -807,7 +859,13 @@ export const backups = sqliteTable('backups', {
  * pid is no longer alive is treated as abandoned (the process crashed before
  * the completion update landed) and ignored by in-flight checks.
  */
-export type ModuleOperationKind = 'deploy' | 'uninstall' | 'backup' | 'restore';
+export type ModuleOperationKind =
+  | 'deploy'
+  | 'uninstall'
+  | 'backup'
+  | 'restore'
+  | 'pause'
+  | 'unpause';
 export type ModuleOperationStatus = 'in_progress' | 'completed' | 'failed';
 
 export const moduleOperations = sqliteTable('module_operations', {

package/src/hooks/run-named-hook.ts

@@ -49,6 +49,13 @@ export interface RunNamedHookResult extends HookResult {
    * gracefully when a module has no `on_uninstall` defined.
    */
   notDefined?: boolean;
+  /**
+   * True when the hook was not run because the module is PAUSED. Reported as
+   * success rather than failure: the module is deliberately quiesced, and a
+   * failure here would be retried by the bus and then alerted on — paging the
+   * operator about the pause they took themselves.
+   */
+  skippedPaused?: boolean;
 }
 
 /**
@@ -82,6 +89,27 @@ export async function runNamedHook(
     };
   }
 
+  // Quiescence for a paused module (openspec/changes/module-pause-lifecycle,
+  // tasks 2.1/2.2). This is the chokepoint every non-lifecycle invocation
+  // funnels through — bus dispatch, timer fan-out, aspect fan-out,
+  // public-web republish, the dns-provider backfill, and `module run-hook` —
+  // so guarding here covers the paths individually rather than each caller
+  // remembering to.
+  //
+  // The exemptions are decided from the hook NAME, not a caller-supplied flag
+  // (Rule 10.3): `on_install` is how unpause redeploys the module back to life,
+  // and `on_uninstall` is how a paused module is removed — which is the entire
+  // point of pausing it. Both must run while `state` is still PAUSED.
+  const LIFECYCLE_HOOKS: readonly HookName[] = ['on_install', 'on_uninstall'];
+  if (module.state === 'PAUSED' && !LIFECYCLE_HOOKS.includes(hookName)) {
+    return {
+      success: true,
+      outputs: {},
+      duration: Date.now() - startedAt,
+      skippedPaused: true,
+    };
+  }
+
   const manifest = module.manifestData as ModuleManifest;
   const hookDef = manifest.hooks?.[hookName as keyof typeof manifest.hooks];
   if (!hookDef) {

package/src/services/alerting/suppression.test.ts

@@ -35,6 +35,7 @@ const TOPOLOGY: SuppressionTopology = {
 const noSuppression = {
   suppressible: true,
   modulesInDeployWindow: new Set<string>(),
+  pausedModules: new Set<string>(),
   topology: TOPOLOGY,
 };
 
@@ -185,6 +186,7 @@ describe('findSuppressor — guards', () => {
         firingKeys,
         suppressible: false,
         modulesInDeployWindow: new Set(),
+        pausedModules: new Set(),
         topology: TOPOLOGY,
       }),
     ).toBeNull();
@@ -197,6 +199,7 @@ describe('findSuppressor — guards', () => {
         firingKeys: new Set(),
         suppressible: true,
         modulesInDeployWindow: new Set(['forgejo']),
+        pausedModules: new Set(),
         topology: TOPOLOGY,
       }),
     ).toEqual({ kind: 'deploy_window', moduleId: 'forgejo' });
@@ -209,6 +212,7 @@ describe('findSuppressor — guards', () => {
         firingKeys: new Set(),
         suppressible: true,
         modulesInDeployWindow: new Set(['forgejo']),
+        pausedModules: new Set(),
         topology: TOPOLOGY,
       }),
     ).toBeNull();
@@ -221,6 +225,7 @@ describe('findSuppressor — guards', () => {
         firingKeys: new Set([machineAlertKey('iot')]),
         suppressible: true,
         modulesInDeployWindow: new Set(['homebridge']),
+        pausedModules: new Set(),
         topology: TOPOLOGY,
       }),
     ).toEqual({ kind: 'deploy_window', moduleId: 'homebridge' });

package/src/services/alerting/suppression.ts

@@ -106,12 +106,20 @@ export interface SuppressorLookup {
   suppressible: boolean;
   /** Modules currently inside a deploy window. */
   modulesInDeployWindow: ReadonlySet<string>;
+  /**
+   * Modules currently PAUSED. A pause is a deliberate quiescing, so its alerts
+   * are explained by the pause itself (openspec/changes/module-pause-lifecycle,
+   * task 2.3) — same mechanism as a deploy window, with the pause as the source
+   * instead of an ancestor alert.
+   */
+  pausedModules: ReadonlySet<string>;
   topology: SuppressionTopology;
 }
 
 export type Suppressor =
   | { kind: 'alert'; key: string }
-  | { kind: 'deploy_window'; moduleId: string };
+  | { kind: 'deploy_window'; moduleId: string }
+  | { kind: 'paused'; moduleId: string };
 
 /**
  * Find what is suppressing `key`, or null if it should be reported.
@@ -128,6 +136,15 @@ export function findSuppressor(lookup: SuppressorLookup): Suppressor | null {
 
   const parsed = parseAlertKey(lookup.key);
 
+  // A pause is checked before a deploy window because it is the longer-lived
+  // and more consequential explanation: a paused module may also be inside a
+  // deploy window (unpause redeploys), and "paused" is the fact the operator
+  // needs to see. Attributed to the pause rather than suppressed anonymously —
+  // silently dropping the alert is what turns a pause into an invisible outage.
+  if (parsed?.source === 'module' && lookup.pausedModules.has(parsed.moduleId)) {
+    return { kind: 'paused', moduleId: parsed.moduleId };
+  }
+
   // A deploy is the same mechanism with a window as the source instead of an
   // ancestor alert — which is why deploy auto-silencing is not a second feature.
   if (parsed?.source === 'module' && lookup.modulesInDeployWindow.has(parsed.moduleId)) {

package/src/services/alerting/sweep-runner.test.ts

@@ -50,6 +50,7 @@ describe('runSweep', () => {
       monitorDeps: monitorDeps(result, now),
       loadTopology: () => TOPOLOGY,
       loadDeployWindowModules: () => new Set(),
+      loadPausedModules: () => new Set(),
       isSuppressible: () => true,
       // No routes configured: the sweep must still run everything else.
       notifyDepsFor: () => null,

package/src/services/alerting/sweep-runner.ts

@@ -43,6 +43,8 @@ export interface SweepDeps {
   loadTopology(): SuppressionTopology;
   /** Modules currently inside a deploy window. */
   loadDeployWindowModules(): Set<string>;
+  /** Ids of modules currently PAUSED — a pause explains its own module's alerts. */
+  loadPausedModules(): Set<string>;
   /** Whether the monitor owning an alert may be suppressed at all. */
   isSuppressible(alert: Alert): boolean;
   /** Compose the per-alert notification context. Null when nothing can page. */
@@ -156,6 +158,7 @@ export async function runSweep(
   );
   const topology = deps.loadTopology();
   const deployWindows = deps.loadDeployWindowModules();
+  const paused = deps.loadPausedModules();
 
   for (const alert of live) {
     const suppressor = findSuppressor({
@@ -163,13 +166,20 @@ export async function runSweep(
       firingKeys,
       suppressible: deps.isSuppressible(alert),
       modulesInDeployWindow: deployWindows,
+      pausedModules: paused,
       topology,
     });
     const wasSuppressed = alert.state === 'suppressed';
     if (suppressor && !wasSuppressed) {
       markSuppressed(db, alert.id, {
         alertId: suppressor.kind === 'alert' ? suppressor.key : undefined,
-        windowId: suppressor.kind === 'deploy_window' ? suppressor.moduleId : undefined,
+        // A pause is recorded on the same column as a deploy window: both are
+        // "a module-scoped condition explains this", and the operator reads the
+        // module id either way.
+        windowId:
+          suppressor.kind === 'deploy_window' || suppressor.kind === 'paused'
+            ? suppressor.moduleId
+            : undefined,
       });
       report.suppressed++;
     } else if (!suppressor && wasSuppressed) {

package/src/services/bus-interview.ts

@@ -314,7 +314,7 @@ export async function busInterviewGuarded<TReply>(
  * 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.
+ * its prompts headlessly drivable instead of prompting on stdin directly.
  *
  * The return type is `unknown` because the runtime shape depends on
  * `payload.kind`; prefer the typed wrappers (`askText`, `askSelect`,
@@ -345,7 +345,7 @@ export async function askInterview(
  *
  * 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.
+ * import keeps the terminal renderer out of the non-TTY path's module graph.
  */
 export async function withInterviewSession<T>(fn: () => Promise<T>): Promise<T> {
   const responder = process.stdin.isTTY

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

@@ -3,7 +3,7 @@
  *
  * Drives `interviewForMissingSecrets` against a real sqlite bus + real
  * encrypted store + a programmatic test responder. No fixture modules,
- * no machines, no clack — the responder is just a `bus.watch` that
+ * no machines, no terminal — the responder is just a `bus.watch` that
  * mimics what `terminal-responder.ts` does.
  *
  * Covers what stage 3 introduced:

package/src/services/dns-registrations.ts

@@ -40,8 +40,20 @@ export interface DnsRegistrationRow {
  * triggers for FK-cascaded deletes only when `recursive_triggers` is on,
  * and reads are the only thing that consumes the ledger. Move it into a
  * trigger if something ever reads these rows without going through here.
+ *
+ * It CHECKS before deleting, so the overwhelmingly common case (nothing
+ * orphaned) stays a pure read. The first version ran the DELETE
+ * unconditionally, which took a write lock on every list — including the
+ * refresh hook's, and `celilo dns registrations`. A read that quietly writes
+ * is a surprise on its own, and on SQLite it is a surprise that serialises
+ * against every other writer for no benefit.
  */
 function pruneOrphanedRegistrations(db: DbClient): void {
+  const orphaned = sql`SELECT 1 FROM dns_registrations WHERE NOT EXISTS (
+      SELECT 1 FROM dns_registration_consumers c WHERE c.registration_id = dns_registrations.id
+    ) LIMIT 1`;
+  if (!db.get(orphaned)) return;
+
   db.run(
     sql`DELETE FROM dns_registrations WHERE NOT EXISTS (
       SELECT 1 FROM dns_registration_consumers c WHERE c.registration_id = dns_registrations.id