@celilo/cli 0.22.0 → 0.24.0

package/src/services/remove-guard.test.ts

@@ -0,0 +1,175 @@
+import { describe, expect, test } from 'bun:test';
+import type { ModuleManifest } from '../manifest/schema';
+import {
+  type DependentCandidate,
+  describeRemovalRefusal,
+  findRemovalBlockers,
+} from './remove-guard';
+
+function manifest(
+  id: string,
+  opts: { requires?: string[]; optional?: string[] } = {},
+): ModuleManifest {
+  return {
+    id,
+    name: id,
+    version: '1.0.0',
+    celilo_contract: '1.0',
+    provides: { capabilities: [] },
+    requires: { capabilities: (opts.requires ?? []).map((name) => ({ name, version: '1.0.0' })) },
+    optional: opts.optional
+      ? { capabilities: opts.optional.map((name) => ({ name, version: '1.0.0' })) }
+      : undefined,
+  } as unknown as ModuleManifest;
+}
+
+function candidate(
+  id: string,
+  opts: { requires?: string[]; optional?: string[]; paused?: boolean; deployed?: boolean } = {},
+): DependentCandidate {
+  return {
+    id,
+    manifest: manifest(id, opts),
+    paused: opts.paused ?? false,
+    deployed: opts.deployed ?? true,
+  };
+}
+
+/** What `greenwave` provides, and the consumers that wedged its removal. */
+const GREENWAVE_CAPABILITIES = ['firewall', 'dhcp_server'];
+
+describe('findRemovalBlockers — the guard that wedged the greenwave swap', () => {
+  test('a live consumer blocks removal', () => {
+    const blockers = findRemovalBlockers(GREENWAVE_CAPABILITIES, [
+      candidate('caddy', { requires: ['firewall'] }),
+    ]);
+    expect(blockers).toEqual([{ moduleId: 'caddy', capability: 'firewall', kind: 'requires' }]);
+  });
+
+  test('a PAUSED consumer does not block (task 5.1)', () => {
+    // Sound because unpause cannot return it to service without a redeploy, and
+    // a redeploy re-resolves its capabilities against whatever is present then.
+    const blockers = findRemovalBlockers(GREENWAVE_CAPABILITIES, [
+      candidate('caddy', { requires: ['firewall'], paused: true }),
+    ]);
+    expect(blockers).toEqual([]);
+  });
+
+  test('a PARTIALLY paused dependent set still blocks, naming only the live ones', () => {
+    const blockers = findRemovalBlockers(GREENWAVE_CAPABILITIES, [
+      candidate('caddy', { requires: ['firewall'], paused: true }),
+      candidate('authentik', { requires: ['firewall'] }),
+    ]);
+    expect(blockers.map((b) => b.moduleId)).toEqual(['authentik']);
+  });
+});
+
+describe('findRemovalBlockers — the optional-dependency regression (task 5.4)', () => {
+  // technitium consumes dhcp_server under `optional:`, so the old guard —
+  // which read `requires` alone — let a greenwave removal orphan its
+  // DHCP-handed-out DNS silently while correctly blocking on caddy.
+  test('an optional consumer NOW blocks, where it used to be invisible', () => {
+    const blockers = findRemovalBlockers(GREENWAVE_CAPABILITIES, [
+      candidate('technitium', { optional: ['dhcp_server'] }),
+    ]);
+    expect(blockers).toEqual([
+      { moduleId: 'technitium', capability: 'dhcp_server', kind: 'optional' },
+    ]);
+  });
+
+  test('and stops blocking once paused', () => {
+    const blockers = findRemovalBlockers(GREENWAVE_CAPABILITIES, [
+      candidate('technitium', { optional: ['dhcp_server'], paused: true }),
+    ]);
+    expect(blockers).toEqual([]);
+  });
+
+  test('a module depending BOTH ways is reported once, as the stronger claim', () => {
+    const blockers = findRemovalBlockers(GREENWAVE_CAPABILITIES, [
+      candidate('both', { requires: ['firewall'], optional: ['dhcp_server'] }),
+    ]);
+    expect(blockers).toHaveLength(1);
+    expect(blockers[0].kind).toBe('requires');
+  });
+});
+
+describe('findRemovalBlockers — deliberate non-goals', () => {
+  test('another provider existing does NOT by itself permit removal (celilo#683, task 5.5)', () => {
+    // `axon` provides the same capabilities as `greenwave`. The guard still
+    // refuses, because celilo does not reason about provider substitutability —
+    // pausing is the mechanism this change relies on instead.
+    const blockers = findRemovalBlockers(GREENWAVE_CAPABILITIES, [
+      candidate('axon'),
+      candidate('caddy', { requires: ['firewall'] }),
+    ]);
+    expect(blockers.map((b) => b.moduleId)).toEqual(['caddy']);
+  });
+
+  test('a module consuming an unrelated capability is not a dependent', () => {
+    expect(
+      findRemovalBlockers(GREENWAVE_CAPABILITIES, [
+        candidate('blog', { requires: ['public_web'] }),
+      ]),
+    ).toEqual([]);
+  });
+
+  test('a provider of nothing blocks nobody', () => {
+    expect(findRemovalBlockers([], [candidate('caddy', { requires: ['firewall'] })])).toEqual([]);
+  });
+});
+
+describe('describeRemovalRefusal', () => {
+  test('names each blocker AND which declaration makes it one (task 5.3)', () => {
+    const message = describeRemovalRefusal('greenwave', [
+      { moduleId: 'caddy', capability: 'firewall', kind: 'requires' },
+      { moduleId: 'technitium', capability: 'dhcp_server', kind: 'optional' },
+    ]);
+
+    // The operator needs to tell a hard prerequisite from an optional consumer
+    // to judge what pausing it implies.
+    expect(message).toContain("caddy — requires 'firewall'");
+    expect(message).toContain("technitium — optional 'dhcp_server'");
+    // And it must point at the way out, since that is the whole change.
+    expect(message).toContain('celilo module pause --cascade greenwave');
+  });
+});
+
+describe('an undeployed dependent does not block (guard/cascade agreement)', () => {
+  // The spec says removal is refused for another INSTALLED module. An imported
+  // module has never resolved the capability and cannot be orphaned by the
+  // provider going away.
+  //
+  // This is load-bearing for D3's guard/cascade agreement, not a nicety.
+  // `pause --cascade` SKIPS undeployed members — pausing needs a settled
+  // deployed state and there is nothing to quiesce. If the guard still counted
+  // them, the operator would pause the whole cascade and the removal would
+  // still refuse, naming a module that pause is structurally unable to act on.
+  // That is a dead end: no sequence of commands gets the operator out of it.
+  test('an IMPORTED consumer is not a blocker', () => {
+    expect(
+      findRemovalBlockers(GREENWAVE_CAPABILITIES, [
+        candidate('technitium', { optional: ['dhcp_server'], deployed: false }),
+      ]),
+    ).toEqual([]);
+  });
+
+  test('but a DEPLOYED one still is', () => {
+    expect(
+      findRemovalBlockers(GREENWAVE_CAPABILITIES, [
+        candidate('technitium', { optional: ['dhcp_server'], deployed: true }),
+      ]).map((b) => b.moduleId),
+    ).toEqual(['technitium']);
+  });
+
+  test('the guard and the cascade agree on every combination', () => {
+    // Whatever pause can act on, the guard must count; whatever pause skips,
+    // the guard must ignore. Enumerated so a future change to either side
+    // cannot silently break the pairing.
+    const blockers = findRemovalBlockers(GREENWAVE_CAPABILITIES, [
+      candidate('live', { requires: ['firewall'] }),
+      candidate('paused', { requires: ['firewall'], paused: true }),
+      candidate('imported', { requires: ['firewall'], deployed: false }),
+    ]);
+    expect(blockers.map((b) => b.moduleId)).toEqual(['live']);
+  });
+});

package/src/services/remove-guard.ts

@@ -0,0 +1,109 @@
+/**
+ * The dependency guard on `module remove`.
+ *
+ * Extracted from `cli/commands/module-remove.ts` so it can be unit-tested
+ * without a database, and so the two behaviour changes it carries are visible
+ * in one place (openspec/changes/module-pause-lifecycle, design D3):
+ *
+ *   1. A PAUSED module is not a dependent. Sound rather than a loosening: a
+ *      paused module cannot return to service without a redeploy, and that
+ *      redeploy re-resolves its capabilities against whatever providers exist
+ *      at the time. The invariant is "paused implies not currently bound, and
+ *      guaranteed to rebind before going live".
+ *
+ *   2. A dependent is one that declares the capability under `requires` OR
+ *      `optional`, which is what `services/update/dep-graph.ts` already means
+ *      by an edge. The guard used to consider `requires` alone, and the two
+ *      definitions disagreeing was silently harmful: `technitium` consumes
+ *      `dhcp_server` under `optional:`, so removing its provider orphaned its
+ *      DHCP-handed-out DNS without a word while correctly blocking on `caddy`.
+ *      The guard and the cascade MUST agree on the set, or `pause --cascade`
+ *      pauses a set the guard still rejects.
+ *
+ * Note (2) makes the guard STRICTER for optional consumers while (1) makes it
+ * looser for paused ones. Both directions are intended.
+ */
+
+import type { ModuleManifest } from '../manifest/schema';
+
+/** How a module came to depend on the capability — reported, not just counted. */
+export type DependencyKind = 'requires' | 'optional';
+
+export interface Blocker {
+  moduleId: string;
+  capability: string;
+  kind: DependencyKind;
+}
+
+export interface DependentCandidate {
+  id: string;
+  manifest: ModuleManifest;
+  paused: boolean;
+  /**
+   * Has this module actually been deployed? The spec says removal is refused
+   * when another **installed** module depends on the capability, and an
+   * imported-but-never-deployed module is not installed: it has never resolved
+   * the capability, holds no state derived from it, and cannot be orphaned by
+   * the provider going away.
+   *
+   * This is not a nicety — it is required for the guard and the cascade to
+   * agree (design D3). `pause --cascade` skips undeployed members, because
+   * pausing requires a settled deployed state and there is nothing to quiesce.
+   * If the guard still counted them, the operator would pause the full cascade
+   * and the removal would STILL refuse, naming a module that pause cannot act
+   * on — a dead end with no way forward.
+   */
+  deployed: boolean;
+}
+
+/**
+ * Modules that block removal of a provider of `providedCapabilities`.
+ *
+ * Pure. Paused candidates are excluded; a candidate depending via both
+ * `requires` and `optional` is reported once, as `requires` (the stronger
+ * claim, and the one whose removal consequence is worse).
+ */
+export function findRemovalBlockers(
+  providedCapabilities: Iterable<string>,
+  candidates: DependentCandidate[],
+): Blocker[] {
+  const provided = new Set(providedCapabilities);
+  if (provided.size === 0) return [];
+
+  const blockers: Blocker[] = [];
+  for (const candidate of candidates) {
+    if (candidate.paused) continue;
+    if (!candidate.deployed) continue;
+
+    const required = (candidate.manifest.requires?.capabilities ?? []).map((c) => c.name);
+    const optional = (candidate.manifest.optional?.capabilities ?? []).map((c) => c.name);
+
+    const hit =
+      required.find((name) => provided.has(name)) ?? optional.find((name) => provided.has(name));
+    if (!hit) continue;
+
+    blockers.push({
+      moduleId: candidate.id,
+      capability: hit,
+      kind: required.includes(hit) ? 'requires' : 'optional',
+    });
+  }
+
+  return blockers.sort((a, b) => a.moduleId.localeCompare(b.moduleId));
+}
+
+/**
+ * The refusal an operator reads. Names each blocker AND which declaration makes
+ * it one, so a hard prerequisite is distinguishable from an optional consumer —
+ * the operator needs that to judge what pausing it implies.
+ */
+export function describeRemovalRefusal(moduleId: string, blockers: Blocker[]): string {
+  const lines = blockers.map((b) => `  • ${b.moduleId} — ${b.kind} '${b.capability}'`);
+  return [
+    `Cannot remove '${moduleId}': the following installed modules depend on its capabilities:`,
+    ...lines,
+    '',
+    'Pause them first so they rebind on their next deploy:',
+    `  celilo module pause --cascade ${moduleId}`,
+  ].join('\n');
+}

package/src/services/storage-providers/s3.test.ts

@@ -1,17 +1,26 @@
 /**
- * Recurrence gate for ISS-0016: the S3 provider's upload() must send a
- * self-describing, replayable Buffer body — NOT a one-shot Node read stream.
+ * Recurrence gates for the two ways this provider's upload has been wrong.
  *
- * The original bug passed `createReadStream(localPath)` as PutObject Body with
- * no ContentLength; AWS SDK v3 fell back to aws-chunked streaming and failed
- * with "The request body terminated unexpectedly" (and couldn't replay the
- * stream across S3's retries/redirects). The verify path used a string body
- * (length known) and so never exercised the broken path — every real S3 backup
- * silently failed. These tests upload a REAL on-disk file and assert the body
- * is a Buffer, so a regression back to a stream is caught here.
+ * ISS-0016 — a one-shot `createReadStream` passed straight to PutObject as
+ * `Body` with no ContentLength. AWS SDK v3 fell back to aws-chunked streaming
+ * and failed with "The request body terminated unexpectedly", and could not
+ * replay the stream across S3's retries and redirects. The verify path used a
+ * string body (length known) and so never exercised the broken path, which is
+ * why every real S3 backup silently failed.
+ *
+ * celilo#685 — the fix for ISS-0016 was `readFileSync` into one Buffer, which
+ * is replayable and was fine for the system envelopes this provider carried at
+ * the time. Module backups then started using the same provider at a thousand
+ * times the size, and a ~1.9 GB Buffer on a 3784 MB management server was
+ * OOM-killed every hour for a day.
+ *
+ * The two constrain opposite things — replayable versus not resident — so
+ * neither test is meaningful alone, and satisfying one by breaking the other is
+ * exactly the history here. `Upload` (multipart) satisfies both: each PART is a
+ * replayable buffer, and only a bounded number of parts exist at once.
  *
  * No live S3 / MinIO harness exists, so we intercept S3Client.prototype.send
- * and inspect the command the provider builds.
+ * and inspect the commands the provider builds.
  */
 
 import { type Mock, afterEach, describe, expect, it, spyOn } from 'bun:test';
@@ -19,8 +28,20 @@ import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { Readable } from 'node:stream';
-import { GetObjectCommand, PutObjectCommand, S3Client } from '@aws-sdk/client-s3';
-import { type S3StorageConfig, createS3StorageProvider } from './s3';
+import {
+  CompleteMultipartUploadCommand,
+  CreateMultipartUploadCommand,
+  GetObjectCommand,
+  PutObjectCommand,
+  S3Client,
+  UploadPartCommand,
+} from '@aws-sdk/client-s3';
+import {
+  type S3StorageConfig,
+  UPLOAD_PART_SIZE,
+  UPLOAD_QUEUE_SIZE,
+  createS3StorageProvider,
+} from './s3';
 
 const CONFIG: S3StorageConfig = {
   bucket: 'test-bucket',
@@ -44,7 +65,7 @@ describe('s3 storage provider (ISS-0016)', () => {
     }
   });
 
-  it('uploads a real on-disk file as a self-describing Buffer body, not a stream', async () => {
+  it('uploads a small file as a self-describing Buffer body, not a stream (ISS-0016)', async () => {
     dir = mkdtempSync(join(tmpdir(), 's3-upload-'));
     const file = join(dir, 'envelope.tar.gz');
     // A multi-KB real file — the case that broke against live S3.
@@ -61,6 +82,8 @@ describe('s3 storage provider (ISS-0016)', () => {
     const provider = createS3StorageProvider(CONFIG);
     await provider.upload(file, 'celilo-mgmt/2026/envelope.tar.gz');
 
+    // Under one part, so no multipart ceremony — a single PutObject, exactly
+    // as before. The bound below is what changed, not the small-file path.
     expect(sent).toHaveLength(1);
     const command = sent[0];
     expect(command).toBeInstanceOf(PutObjectCommand);
@@ -78,6 +101,66 @@ describe('s3 storage provider (ISS-0016)', () => {
     expect(command.input.Bucket).toBe('test-bucket');
   });
 
+  it('never holds more than one part per queue slot, however large the file (celilo#685)', async () => {
+    dir = mkdtempSync(join(tmpdir(), 's3-upload-large-'));
+    const file = join(dir, 'backup.tar.enc');
+
+    // Deliberately larger than one part, so the multipart path runs for real.
+    // It does not need to approach forgejo's 1.87 GB: the property under test
+    // is that peak residency is set by the part size rather than by the file,
+    // and a file that spans several parts demonstrates that at any scale. A
+    // test that had to allocate the failing size to prove the fix would be
+    // reproducing the bug rather than gating it.
+    const parts = 3;
+    const fileSize = UPLOAD_PART_SIZE * parts;
+    writeFileSync(file, Buffer.alloc(fileSize, 0x7a));
+
+    // Deliberately NOT a running total. Parts are uploaded concurrently and can
+    // arrive in any order, so the only way to show the artifact survives is to
+    // keep each part against its number and reassemble.
+    const received = new Map<number, Buffer>();
+    let inFlight = 0;
+    let peakInFlight = 0;
+    sendSpy = spyOn(S3Client.prototype, 'send').mockImplementation(async (command: unknown) => {
+      if (command instanceof CreateMultipartUploadCommand) return { UploadId: 'upload-1' };
+      if (command instanceof CompleteMultipartUploadCommand) return {};
+
+      expect(command).toBeInstanceOf(UploadPartCommand);
+      const part = command as UploadPartCommand;
+      const body = part.input.Body as Buffer;
+      const partNumber = part.input.PartNumber as number;
+
+      // Each part is still a replayable Buffer — ISS-0016 holds per part.
+      expect(Buffer.isBuffer(body)).toBe(true);
+      // A part number reused would silently lose data on reassembly.
+      expect(received.has(partNumber)).toBe(false);
+      received.set(partNumber, Buffer.from(body));
+
+      inFlight += 1;
+      peakInFlight = Math.max(peakInFlight, inFlight);
+      await new Promise((resolve) => setTimeout(resolve, 1));
+      inFlight -= 1;
+      return { ETag: `"etag-${partNumber}"` };
+    });
+
+    const provider = createS3StorageProvider(CONFIG);
+    await provider.upload(file, 'forgejo/2026-08-13/backup.tar.enc');
+
+    // The bound. No single request ever carries the whole artifact, and no more
+    // than the queue depth are resident at once, so peak bytes is
+    // UPLOAD_PART_SIZE * UPLOAD_QUEUE_SIZE no matter how big the file gets.
+    expect(received.size).toBe(parts);
+    for (const body of received.values()) expect(body.length).toBeLessThanOrEqual(UPLOAD_PART_SIZE);
+    expect(peakInFlight).toBeLessThanOrEqual(UPLOAD_QUEUE_SIZE);
+
+    // A bound is only worth having if the artifact still arrives. Reassembled
+    // in part order, the bytes must be the file — sizes summing correctly would
+    // not catch a swapped or duplicated part, and a backup that restores to
+    // scrambled bytes is worse than one that fails loudly.
+    const ordered = [...received.entries()].sort(([a], [b]) => a - b).map(([, body]) => body);
+    expect(Buffer.concat(ordered).equals(readFileSync(file))).toBe(true);
+  });
+
   it('downloads a multi-chunk response body to disk intact (short-read safe)', async () => {
     dir = mkdtempSync(join(tmpdir(), 's3-download-'));
     const out = join(dir, 'restored.bin');

package/src/services/storage-providers/s3.ts

@@ -3,7 +3,7 @@
  * Works with AWS S3, MinIO, Backblaze B2, Wasabi, and any S3-compatible service.
  */
 
-import { createWriteStream, readFileSync } from 'node:fs';
+import { createReadStream, createWriteStream } from 'node:fs';
 import { mkdir } from 'node:fs/promises';
 import { dirname } from 'node:path';
 import { Readable } from 'node:stream';
@@ -15,10 +15,47 @@ import {
   PutObjectCommand,
   S3Client,
 } from '@aws-sdk/client-s3';
+import { Upload } from '@aws-sdk/lib-storage';
 import type { StorageProvider, StorageVerifyResult } from './types';
 
 const BACKUP_PREFIX = 'celilo-backups';
 
+/**
+ * Multipart upload sizing. Peak resident bytes for an upload is
+ * `UPLOAD_PART_SIZE * UPLOAD_QUEUE_SIZE` — 64 MB — and does NOT grow with the
+ * artifact. That bound is the whole point of these two constants.
+ *
+ * `upload` used to `readFileSync` the artifact into one Buffer and hand it to
+ * PutObject. The comment justifying that read:
+ *
+ *   > Upload a Buffer, NOT a read stream (ISS-0016). A streamed Body fails with
+ *   > "The request body terminated unexpectedly" [...] Backup envelopes are
+ *   > small (state + key, not provider binaries — ISS-0015), so buffering is
+ *   > fine.
+ *
+ * The first half is true and still is: a one-shot Node stream as a PutObject
+ * `Body` cannot be replayed across the retries and redirects S3 issues, and
+ * with no ContentLength the SDK falls back to aws-chunked encoding on top.
+ * Passing `createReadStream` straight to PutObject would reintroduce exactly
+ * that bug.
+ *
+ * The second half stopped being true without anyone revisiting it. It was
+ * written when this provider only carried SYSTEM backups (celilo state plus a
+ * key, a few MB). MODULE backups now use the same provider and are three orders
+ * of magnitude larger — forgejo's envelope reached 1.87 GB — so "buffering is
+ * fine" became a ~1.9 GB Buffer on a 3784 MB management server, and the OOM
+ * killer took the backup every hour for a day while the on_backup hook itself
+ * reported success (celilo#685).
+ *
+ * `Upload` resolves the two halves rather than trading one for the other: it
+ * reads the stream a part at a time and each PART is a replayable buffer, so
+ * retries work without the whole object ever being resident. 16 MB parts keep
+ * a 1.87 GB artifact at ~117 requests, well inside S3's 10,000-part limit,
+ * which leaves headroom to ~160 GB.
+ */
+export const UPLOAD_PART_SIZE = 16 * 1024 * 1024;
+export const UPLOAD_QUEUE_SIZE = 4;
+
 export interface S3StorageConfig {
   bucket: string;
   region: string;
@@ -49,22 +86,18 @@ export function createS3StorageProvider(config: S3StorageConfig): StorageProvide
 
   return {
     async upload(localPath: string, remotePath: string): Promise<void> {
-      // Upload a Buffer, NOT a read stream (ISS-0016). A streamed Body fails
-      // with "The request body terminated unexpectedly": the SDK can't replay a
-      // one-shot Node stream across the retries/redirects S3 issues (e.g. a
-      // region 301), and with no ContentLength it falls back to aws-chunked
-      // encoding on top. A Buffer is replayable and self-describing — the same
-      // reason the string-bodied verify write succeeds where the stream upload
-      // did not. Backup envelopes are small (state + key, not provider
-      // binaries — ISS-0015), so buffering is fine.
-      const body = readFileSync(localPath);
-      await client.send(
-        new PutObjectCommand({
+      // Multipart, so peak memory is UPLOAD_PART_SIZE * UPLOAD_QUEUE_SIZE
+      // regardless of how large the artifact is.
+      await new Upload({
+        client,
+        partSize: UPLOAD_PART_SIZE,
+        queueSize: UPLOAD_QUEUE_SIZE,
+        params: {
           Bucket: bucket,
           Key: prefixedKey(remotePath),
-          Body: body,
-        }),
-      );
+          Body: createReadStream(localPath),
+        },
+      }).done();
     },
 
     async download(remotePath: string, localPath: string): Promise<void> {

package/src/services/terminal-responder.ts

@@ -1,8 +1,8 @@
 /**
  * Terminal-responder: when a deploy runs on a TTY, this subscribes
  * to `config.required.*`, `secret.required.*`, and `ensure.required.*`
- * events and prompts the operator via clack for each one, replying
- * on the bus.
+ * events and prompts the operator on the terminal for each one,
+ * replying on the bus.
  *
  * Just one of several responder shapes — the bus query/reply path is
  * a race, and the terminal is one racer. Other racers (Claude
@@ -26,9 +26,9 @@
  */
 
 import { hostname } from 'node:os';
+import { confirm, isCancel, multiselect, select } from '@celilo/cli-display';
 import { type Bus, openBus } from '@celilo/event-bus';
 import { defineEvents } from '@celilo/event-bus';
-import * as p from '@clack/prompts';
 import { log, promptPassword, promptText } from '../cli/prompts';
 import { getEventBusPath } from '../config/paths';
 import { getDb } from '../db/client';
@@ -61,7 +61,7 @@ export interface TerminalResponderHandle {
 
 /**
  * Register transient subscriptions on the three interview event
- * families. For each event, prompt the operator via clack, optionally
+ * families. For each event, prompt the operator on the terminal, optionally
  * inject the secret value out-of-band, and reply on the bus.
  *
  * Returns a handle the caller can close() when the deploy completes.
@@ -103,9 +103,9 @@ export function startTerminalResponder(): TerminalResponderHandle {
 
     if (payload.options && payload.options.length > 0) {
       // Multi-select prompt for vars with options[] declared in the
-      // manifest. clack's multiselect returns an array of selected
-      // values directly — no JSON-typing to coerce.
-      const selected = await p.multiselect({
+      // manifest. multiselect returns an array of selected values
+      // directly — no JSON-typing to coerce.
+      const selected = await multiselect({
         message,
         options: payload.options.map((opt) => ({
           value: opt.value,
@@ -114,7 +114,7 @@ export function startTerminalResponder(): TerminalResponderHandle {
         })),
         required: payload.required,
       });
-      if (p.isCancel(selected)) {
+      if (isCancel(selected)) {
         log.warn(
           `Terminal responder: cancelled prompt for ${payload.module}.${payload.key}; no reply emitted`,
         );
@@ -308,11 +308,11 @@ export function startTerminalResponder(): TerminalResponderHandle {
     let value: unknown;
 
     if (payload.kind === 'confirm') {
-      const answer = await p.confirm({
+      const answer = await confirm({
         message,
         initialValue: payload.defaultValue === 'true',
       });
-      if (p.isCancel(answer)) {
+      if (isCancel(answer)) {
         log.warn(
           `Terminal responder: cancelled prompt for ${payload.scope}.${payload.key}; no reply emitted`,
         );
@@ -320,7 +320,7 @@ export function startTerminalResponder(): TerminalResponderHandle {
       }
       value = answer;
     } else if (payload.kind === 'select') {
-      const answer = await p.select({
+      const answer = await select({
         message,
         options: (payload.options ?? []).map((opt) => ({
           value: opt.value,
@@ -329,7 +329,7 @@ export function startTerminalResponder(): TerminalResponderHandle {
         })),
         initialValue: payload.defaultValue,
       });
-      if (p.isCancel(answer)) {
+      if (isCancel(answer)) {
         log.warn(
           `Terminal responder: cancelled prompt for ${payload.scope}.${payload.key}; no reply emitted`,
         );
@@ -337,7 +337,7 @@ export function startTerminalResponder(): TerminalResponderHandle {
       }
       value = answer;
     } else if (payload.kind === 'multiselect') {
-      const answer = await p.multiselect({
+      const answer = await multiselect({
         message,
         options: (payload.options ?? []).map((opt) => ({
           value: opt.value,
@@ -346,7 +346,7 @@ export function startTerminalResponder(): TerminalResponderHandle {
         })),
         required: payload.required,
       });
-      if (p.isCancel(answer)) {
+      if (isCancel(answer)) {
         log.warn(
           `Terminal responder: cancelled prompt for ${payload.scope}.${payload.key}; no reply emitted`,
         );
@@ -624,8 +624,8 @@ function describeTypeHint(type: ConfigRequiredPayload['type']): string | null {
 }
 
 function coerceValue(raw: string | undefined, type: ConfigRequiredPayload['type']): unknown {
-  // clack returns undefined when the user cancels (Ctrl+C). Bubble
-  // that up as an error so validate sees it and the responder can
+  // The prompt layer yields undefined when the user cancels (Ctrl+C).
+  // Bubble that up as an error so validate sees it and the responder can
   // skip the reply rather than emit a malformed one.
   if (raw === undefined) {
     throw new Error('Cancelled');