@celilo/cli 0.21.0 → 0.23.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/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');

package/src/services/update/dep-graph.test.ts

@@ -80,13 +80,42 @@ describe('buildModuleGraph', () => {
     expect(g.edges.get('weird')?.size).toBe(0);
   });
 
-  test('first declared provider wins when multiple modules provide the same capability', () => {
+  // Previously asserted "first declared provider wins". That was the behaviour,
+  // and it was a defect: `capability-loader.ts` resolves a `firewall` consumer
+  // through `buildFirewallChain()`, which wires a chain across EVERY provider —
+  // the edge device that owns egress plus the downstream layers. First-wins made
+  // the others invisible, so `module pause --cascade greenwave` omitted `caddy`
+  // even though caddy requires `firewall` and greenwave provides it, and the
+  // remove guard (which reads all providers) then refused the removal the
+  // cascade was supposed to enable.
+  test('a consumer depends on EVERY provider of a capability, not just the first', () => {
     const g = buildModuleGraph([
-      makeManifest('a', { provides: ['firewall'] }),
-      makeManifest('b', { provides: ['firewall'] }),
+      makeManifest('iptables', { provides: ['firewall'] }),
+      makeManifest('greenwave', { provides: ['firewall'] }),
+      makeManifest('caddy', { requires: ['firewall'] }),
+    ]);
+    expect([...(g.edges.get('caddy') ?? [])].sort()).toEqual(['greenwave', 'iptables']);
+  });
+
+  test('and every provider sees that consumer in its reverse index', () => {
+    // This is the half `transitiveConsumers` walks, so it is what decides
+    // whether a cascade reaches the module at all.
+    const g = buildModuleGraph([
+      makeManifest('iptables', { provides: ['firewall'] }),
+      makeManifest('greenwave', { provides: ['firewall'] }),
       makeManifest('caddy', { requires: ['firewall'] }),
     ]);
-    expect([...(g.edges.get('caddy') ?? [])]).toEqual(['a']);
+    expect([...(g.reverseEdges.get('greenwave') ?? [])]).toEqual(['caddy']);
+    expect([...(g.reverseEdges.get('iptables') ?? [])]).toEqual(['caddy']);
+  });
+
+  test('an optional consumer also edges to every provider', () => {
+    const g = buildModuleGraph([
+      makeManifest('greenwave', { provides: ['dhcp_server'] }),
+      makeManifest('router2', { provides: ['dhcp_server'] }),
+      makeManifest('technitium', { optional: ['dhcp_server'] }),
+    ]);
+    expect([...(g.edges.get('technitium') ?? [])].sort()).toEqual(['greenwave', 'router2']);
   });
 });
 

package/src/services/update/dep-graph.ts

@@ -45,15 +45,36 @@ export interface ModuleGraph {
   reverseEdges: Map<ModuleId, Set<ModuleId>>;
 }
 
-/** Internal: build an index of capability name → providing module id. */
-function indexProviders(modules: ModuleNode[]): Map<string, ModuleId> {
-  const index = new Map<string, ModuleId>();
+/**
+ * Internal: index capability name → EVERY module providing it.
+ *
+ * This used to keep only the first provider, on the reasoning that "one edge per
+ * capability is enough for graph-walking". It is not, and the discrepancy is
+ * not theoretical: `firewall` is provided by BOTH `iptables` and `greenwave`,
+ * and `capability-loader.ts` resolves a consumer's `requires: firewall` through
+ * `buildFirewallChain()`, which wires a chain across ALL providers — the edge
+ * device that owns egress plus the downstream layers. So a consumer genuinely
+ * depends on every one of them.
+ *
+ * With first-wins, whichever provider happened to be inserted first absorbed the
+ * edge and the others became invisible to the graph. `module pause --cascade
+ * greenwave` therefore omitted `caddy` entirely, even though caddy requires
+ * `firewall` and greenwave provides it — so the operator paused an incomplete
+ * set and `module remove` then refused, because the remove guard reads the
+ * capabilities table (all providers) and disagreed. That disagreement is exactly
+ * what openspec/changes/module-pause-lifecycle design D3 forbids.
+ *
+ * Keeping all providers makes the graph agree with how capabilities actually
+ * resolve. For `topologicalOrder` it means a consumer sorts after every provider
+ * of what it consumes, which is strictly more correct for `system update`.
+ */
+function indexProviders(modules: ModuleNode[]): Map<string, ModuleId[]> {
+  const index = new Map<string, ModuleId[]>();
   for (const m of modules) {
     for (const cap of m.provides) {
-      // First provider wins. The capability-loader's chain logic handles
-      // multi-provider scenarios at deploy time; for graph-walking
-      // purposes one edge per capability is enough.
-      if (!index.has(cap)) index.set(cap, m.id);
+      const existing = index.get(cap);
+      if (existing) existing.push(m.id);
+      else index.set(cap, [m.id]);
     }
   }
   return index;
@@ -82,16 +103,17 @@ export function buildModuleGraph(manifests: ModuleManifest[]): ModuleGraph {
     reverseEdges.set(node.id, reverseEdges.get(node.id) ?? new Set());
 
     for (const cap of node.consumes) {
-      const providerId = providerIndex.get(cap);
-      // Skip self-edges (a module that consumes its own capability —
-      // unusual but legal) and missing providers (deploy preflight
-      // handles those; graph just routes around them).
-      if (!providerId || providerId === node.id) continue;
-
-      edges.get(node.id)?.add(providerId);
-      const rev = reverseEdges.get(providerId) ?? new Set();
-      rev.add(node.id);
-      reverseEdges.set(providerId, rev);
+      for (const providerId of providerIndex.get(cap) ?? []) {
+        // Skip self-edges (a module that consumes its own capability —
+        // unusual but legal) and missing providers (deploy preflight
+        // handles those; graph just routes around them).
+        if (providerId === node.id) continue;
+
+        edges.get(node.id)?.add(providerId);
+        const rev = reverseEdges.get(providerId) ?? new Set();
+        rev.add(node.id);
+        reverseEdges.set(providerId, rev);
+      }
     }
   }
 

package/src/services/zone-detector.ts

@@ -3,48 +3,11 @@
  * Auto-detects network zone from IP address by matching against system subnets
  */
 
+import { subnetContains } from '@celilo/capabilities';
 import { eq } from 'drizzle-orm';
 import { getDb } from '../db/client';
 import { type NetworkZone, systemConfig } from '../db/schema';
 
-/**
- * Parse CIDR notation to get network address and prefix length
- */
-function parseCIDR(cidr: string): { network: string; prefixLength: number } {
-  const [ip, prefix] = cidr.split('/');
-  return {
-    network: ip,
-    prefixLength: Number.parseInt(prefix, 10),
-  };
-}
-
-/**
- * Convert IP address string to 32-bit integer
- */
-function ipToInt(ip: string): number {
-  const parts = ip.split('.').map((part) => Number.parseInt(part, 10));
-  return (parts[0] << 24) | (parts[1] << 16) | (parts[2] << 8) | parts[3];
-}
-
-/**
- * Check if an IP address is in a CIDR subnet
- */
-function ipInSubnet(ip: string, cidr: string): boolean {
-  try {
-    const { network, prefixLength } = parseCIDR(cidr);
-    const ipInt = ipToInt(ip);
-    const networkInt = ipToInt(network);
-
-    // Create subnet mask
-    const mask = ~((1 << (32 - prefixLength)) - 1);
-
-    // Check if IP is in subnet
-    return (ipInt & mask) === (networkInt & mask);
-  } catch {
-    return false;
-  }
-}
-
 /**
  * Get system network configuration for a zone
  */
@@ -77,7 +40,7 @@ export async function detectZoneFromIp(ip: string): Promise<NetworkZone> {
 
   for (const zone of zones) {
     const subnet = await getZoneSubnet(zone);
-    if (subnet && ipInSubnet(ip, subnet)) {
+    if (subnet && subnetContains(subnet, ip)) {
       return zone;
     }
   }

package/src/test-utils/cli.ts

@@ -6,13 +6,17 @@ import { execSync } from 'node:child_process';
  * Disconnects stdin to ensure CLI cannot prompt for user input.
  * Any attempt to read from stdin will immediately fail, preventing hanging tests.
  *
- * When command fails, throws error with stderr included in message for test assertions.
+ * When command fails, throws an error carrying stderr — where the CLI writes
+ * its diagnostics. Both helpers used to concatenate stdout and stderr because
+ * `@clack/prompts` put error messages on stdout, which left no way to tell a
+ * result from a complaint about producing one (celilo#699). The streams are
+ * separate now and this reads only the one that carries diagnostics.
  *
  * @param cli - CLI command prefix (includes env vars and path)
  * @param command - Command to execute (e.g., "system config get")
  * @param options - Additional exec options
- * @returns Command output as string
- * @throws Error with stderr message when command fails
+ * @returns Command stdout as string
+ * @throws Error with the stderr message when command fails
  */
 export function runCli(cli: string, command: string, options: { encoding?: 'utf-8' } = {}): string {
   try {
@@ -22,34 +26,31 @@ export function runCli(cli: string, command: string, options: { encoding?: 'utf-
       timeout: 30000, // 30 second timeout to prevent tests hanging indefinitely
     });
   } catch (error: unknown) {
-    // CLI writes errors to stdout (via @clack/prompts), so capture both
-    const stdout = (error as { stdout?: Buffer }).stdout?.toString() || '';
     const stderr = (error as { stderr?: Buffer }).stderr?.toString() || '';
-    // Combine both stdout and stderr (some commands write to both)
-    const output = [stdout, stderr].filter(Boolean).join('\n') || (error as Error).message;
-    throw new Error(output);
+    throw new Error(stderr.trim() || (error as Error).message);
   }
 }
 
 /**
  * Execute CLI command expecting failure
- * Returns combined stdout + stderr for assertion
+ * Returns stderr for assertion — that is where the CLI writes diagnostics.
  *
  * Disconnects stdin to ensure CLI cannot prompt for user input.
  *
  * @param cli - CLI command prefix
  * @param command - Command to execute
- * @returns combined output as string
+ * @returns stderr as string
  * @throws Error if command succeeds (when it should fail)
  */
 export function runCliExpectingFailure(cli: string, command: string): string {
   try {
     execSync(`${cli} ${command}`, { stdio: ['ignore', 'pipe', 'pipe'] });
-    throw new Error('Expected command to fail but it succeeded');
   } catch (error: unknown) {
-    // CLI writes errors to stdout (via @clack/prompts), so capture both
-    const stdout = (error as { stdout?: Buffer }).stdout?.toString() || '';
     const stderr = (error as { stderr?: Buffer }).stderr?.toString() || '';
-    return [stdout, stderr].filter(Boolean).join('\n') || (error as Error).message;
+    return stderr.trim() || (error as Error).message;
   }
+  // Previously thrown from inside the `try`, where the catch below swallowed it
+  // and RETURNED the message — so a command that wrongly succeeded read as a
+  // passing assertion about its own failure.
+  throw new Error('Expected command to fail but it succeeded');
 }

package/src/test-utils/integration-guard.ts

@@ -31,3 +31,29 @@ export function skipIntegration(
   if (req.platform && process.platform !== req.platform) return true;
   return false;
 }
+
+/**
+ * Quarantine a test that FAILS ON THE CI RUNNER for a reason we have not yet
+ * explained, while keeping it running for developers locally.
+ *
+ * This is the `cele2e-ci-unsafe` device (see `--ci-safe` in the cele2e runner)
+ * applied to the integration suite, and it is deliberately uncomfortable to
+ * use: the caller must pass the tracking issue, and the whole point is that the
+ * skip is legible in the log rather than silent.
+ *
+ * Use this ONLY when the failure is not explained by a missing tool — reach for
+ * `skipIntegration({ tools: [...] })` first, because "which tool" is a real
+ * diagnosis and "quarantined" is an admission that we do not have one yet.
+ *
+ * The alternative is worse in both directions: leaving the test in makes a gate
+ * permanently red, which trains everyone to ignore it — the same disease as a
+ * gate that cannot fail. Deleting it loses the coverage and the evidence.
+ *
+ * Keyed on `GITHUB_ACTIONS`, which the Forgejo runner sets (it is what makes
+ * `bun test` emit `::error` annotations there).
+ *
+ * Usage:  test.skipIf(quarantinedInCi('celilo#713'))('...', ...)
+ */
+export function quarantinedInCi(_trackingIssue: string): boolean {
+  return process.env.GITHUB_ACTIONS === 'true';
+}