@celilo/cli 0.22.0 → 0.23.0

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/fleet-checks.ts

@@ -38,6 +38,7 @@ import {
   readInstalledUnit,
   unitMainPid,
 } from './events-daemon';
+import { describePausedModule, listPausedModules } from './module-pause';
 import { resolveSubscription } from './module-subscriptions';
 
 /**
@@ -854,6 +855,52 @@ export function checkControlPlaneNetwork(db: DbClient): FleetFinding {
   };
 }
 
+/**
+ * Any paused module is a doctor failure — no threshold, whatever its age
+ * (openspec/changes/module-pause-lifecycle, design D7, closed at review).
+ *
+ * A pause deliberately switches OFF the alerting that would otherwise report
+ * the module as down, so the paused-ness itself has to be the signal. A
+ * duration threshold was considered and dropped: there is no number of hours
+ * after which a deliberate outage becomes acceptable, and a configurable one is
+ * just an invitation to tune the detector until it stops firing.
+ *
+ * The fleet had just run 20 hours of failing forgejo backups whose only symptom
+ * was a column of `0 B` rows that read as healthy hourly cadence. Same failure
+ * shape; this is the check that would have named it.
+ */
+export function checkPausedModules(db: DbClient): FleetFinding {
+  const paused = listPausedModules(db);
+
+  if (paused.length === 0) {
+    return {
+      id: 'paused-modules',
+      title: 'No module is paused (a pause suppresses its own alerting)',
+      status: 'ok',
+      summary: 'nothing paused',
+      detail: [],
+      remediation: null,
+      autoFixable: false,
+    };
+  }
+
+  const names = paused.map((m) => describePausedModule(m));
+  return {
+    id: 'paused-modules',
+    title: 'No module is paused (a pause suppresses its own alerting)',
+    status: 'fail',
+    summary: `${paused.length} module(s) paused: ${paused.map((m) => m.id).join(', ')}`,
+    detail: [
+      ...names.map((n) => `paused: ${n}`),
+      'a paused module receives no dispatched work, runs no health checks, and has its alerts suppressed',
+      'it is still deployed and may still be serving traffic — pause does not stop the data plane',
+    ],
+    remediation:
+      'bring each back with "celilo module unpause <id>" (which redeploys it, rebinding its capabilities), or remove it if the pause was permanent',
+    autoFixable: false,
+  };
+}
+
 export async function runFleetChecks(
   bus: Bus,
   db: DbClient,
@@ -865,6 +912,7 @@ export async function runFleetChecks(
     checkSubscribers(bus, db),
     checkCapabilityProviders(db),
     checkControlPlaneNetwork(db),
+    checkPausedModules(db),
     await checkServiceDns(db),
   ];
 }

package/src/services/module-deploy.ts

@@ -350,7 +350,7 @@ async function deployModuleImpl(
 
   // Terminal-responder: when running on a TTY, this subscribes to
   // `config.required.*` / `secret.required.*` / `ensure.required.*`
-  // events and prompts via clack. Other responder shapes (Claude
+  // events and prompts on the terminal. Other responder shapes (Claude
   // subagent, `celilo events respond` from another shell, autoresponder
   // daemon) compete on the bus; first reply wins. See
   // infra/openspec/changes/interactive-deploys-via-event-bus/proposal.md.

package/src/services/module-pause-observability.test.ts

@@ -0,0 +1,224 @@
+/**
+ * The parts of pause that exist so a pause cannot become a silent outage
+ * (design D7), plus the alerting suppressor.
+ *
+ * Every check here is asserted in BOTH directions per Rule 7.6 — a gate nobody
+ * has seen fail is not a gate, and "no paused module was reported" is exactly
+ * the output a broken detector produces.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { mkdtempSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { type DbClient, createDbClient } from '../db/client';
+import { type ModuleState, modules } from '../db/schema';
+import { moduleAlertKey } from './alerting/keys';
+import { findSuppressor } from './alerting/suppression';
+import { checkPausedModules } from './fleet-checks';
+import {
+  describeMachineStopInfra,
+  describePausedModule,
+  listPausedModules,
+  pausedAmong,
+} from './module-pause';
+
+function makeDb(): DbClient {
+  const dir = mkdtempSync(join(tmpdir(), 'celilo-pause-obs-'));
+  process.env.CELILO_DB_PATH = join(dir, 'celilo.db');
+  return createDbClient({ path: process.env.CELILO_DB_PATH });
+}
+
+function insert(
+  db: DbClient,
+  id: string,
+  state: ModuleState,
+  opts: { pausedAt?: Date; reason?: string } = {},
+): void {
+  db.insert(modules)
+    .values({
+      id,
+      name: id,
+      version: '1.0.0',
+      state,
+      manifestData: { id, name: id, version: '1.0.0' },
+      sourcePath: `/tmp/${id}`,
+      pausedAt: state === 'PAUSED' ? (opts.pausedAt ?? new Date()) : null,
+      pauseReason: state === 'PAUSED' ? (opts.reason ?? null) : null,
+    })
+    .run();
+}
+
+describe('system doctor reports ANY paused module (task 6.2 / 6.4)', () => {
+  test('with nothing paused the check passes', () => {
+    const db = makeDb();
+    insert(db, 'caddy', 'VERIFIED');
+
+    const finding = checkPausedModules(db);
+    expect(finding.status).toBe('ok');
+    expect(finding.summary).toBe('nothing paused');
+  });
+
+  test('PROVE IT FAILS: one paused module is a doctor FAILURE naming it and its age', () => {
+    const db = makeDb();
+    insert(db, 'caddy', 'VERIFIED');
+    insert(db, 'greenwave', 'PAUSED', {
+      pausedAt: new Date(Date.now() - 3 * 24 * 60 * 60 * 1000),
+      reason: 'edge router swap',
+    });
+
+    const finding = checkPausedModules(db);
+
+    expect(finding.status).toBe('fail');
+    expect(finding.summary).toContain('greenwave');
+    // The DURATION is what separates a maintenance window from a forgotten one.
+    expect(finding.detail.join('\n')).toContain('3d');
+    expect(finding.detail.join('\n')).toContain('edge router swap');
+    expect(finding.remediation).toContain('celilo module unpause');
+  });
+
+  test('there is no threshold — a pause taken seconds ago already fails', () => {
+    // Decided at review: a pause is a degraded state, full stop. A threshold is
+    // just something to tune until the detector stops firing.
+    const db = makeDb();
+    insert(db, 'greenwave', 'PAUSED', { pausedAt: new Date() });
+    expect(checkPausedModules(db).status).toBe('fail');
+  });
+});
+
+describe('listPausedModules / pausedAmong', () => {
+  test('reads only PAUSED rows, and reads back the reason', () => {
+    const db = makeDb();
+    insert(db, 'caddy', 'INSTALLED');
+    insert(db, 'greenwave', 'PAUSED', { reason: 'edge router swap' });
+    insert(db, 'authentik', 'ERROR');
+
+    const paused = listPausedModules(db);
+    expect(paused.map((m) => m.id)).toEqual(['greenwave']);
+    expect(paused[0].pauseReason).toBe('edge router swap');
+  });
+
+  test('an ERROR module is NOT paused — the two states are distinct', () => {
+    // Worth pinning: ERROR is *pausable*, which is easy to misread as "errored
+    // counts as paused" and would make the doctor check fire on every failure.
+    const db = makeDb();
+    insert(db, 'authentik', 'ERROR');
+    expect(listPausedModules(db)).toEqual([]);
+  });
+
+  test('pausedAmong filters a candidate set in one query', () => {
+    const db = makeDb();
+    insert(db, 'caddy', 'PAUSED');
+    insert(db, 'authentik', 'INSTALLED');
+    expect(pausedAmong(db, ['caddy', 'authentik', 'absent'])).toEqual(new Set(['caddy']));
+  });
+
+  test('pausedAmong on an empty list does not query at all', () => {
+    const db = makeDb();
+    expect(pausedAmong(db, [])).toEqual(new Set());
+  });
+});
+
+describe('the management-API warning is emitted, and NOT emitted (task 6.5 / 6.6)', () => {
+  // `fleetWarnings()` in api/serve.ts is the production caller; this pins the
+  // query + rendering it depends on. The inverse assertion is the one that
+  // stops the warning becoming noise nobody reads.
+  test('with nothing paused there is nothing to warn about', () => {
+    const db = makeDb();
+    insert(db, 'caddy', 'VERIFIED');
+    expect(listPausedModules(db)).toHaveLength(0);
+  });
+
+  test('with something paused the warning names the module AND its age', () => {
+    const db = makeDb();
+    insert(db, 'greenwave', 'PAUSED', {
+      pausedAt: new Date(Date.now() - 5 * 60 * 60 * 1000),
+      reason: 'edge router swap',
+    });
+
+    const rendered = listPausedModules(db).map((m) => describePausedModule(m));
+    expect(rendered).toEqual(['greenwave (5h, "edge router swap")']);
+  });
+
+  test('a pause with no reason still renders its age', () => {
+    const db = makeDb();
+    insert(db, 'greenwave', 'PAUSED', { pausedAt: new Date(Date.now() - 60 * 60 * 1000) });
+    expect(describePausedModule(listPausedModules(db)[0])).toBe('greenwave (1h)');
+  });
+});
+
+describe('a paused module is suppressed BY THE PAUSE, not anonymously (task 2.3)', () => {
+  const topology = { moduleSystems: [], zoneProviders: [] };
+
+  test('PROVE IT FIRES: an unpaused module with nothing firing is NOT suppressed', () => {
+    expect(
+      findSuppressor({
+        key: moduleAlertKey('caddy'),
+        firingKeys: new Set(),
+        suppressible: true,
+        modulesInDeployWindow: new Set(),
+        pausedModules: new Set(),
+        topology,
+      }),
+    ).toBeNull();
+  });
+
+  test('the same alert IS suppressed once the module is paused, attributed to the pause', () => {
+    expect(
+      findSuppressor({
+        key: moduleAlertKey('caddy'),
+        firingKeys: new Set(),
+        suppressible: true,
+        modulesInDeployWindow: new Set(),
+        pausedModules: new Set(['caddy']),
+        topology,
+      }),
+    ).toEqual({ kind: 'paused', moduleId: 'caddy' });
+  });
+
+  test('a pause does not suppress OTHER modules', () => {
+    expect(
+      findSuppressor({
+        key: moduleAlertKey('authentik'),
+        firingKeys: new Set(),
+        suppressible: true,
+        modulesInDeployWindow: new Set(),
+        pausedModules: new Set(['caddy']),
+        topology,
+      }),
+    ).toBeNull();
+  });
+
+  test('a self-monitor is never suppressed, even by a pause', () => {
+    // A cascading failure must not silence the component reporting the cascade.
+    expect(
+      findSuppressor({
+        key: moduleAlertKey('caddy'),
+        firingKeys: new Set(),
+        suppressible: false,
+        modulesInDeployWindow: new Set(),
+        pausedModules: new Set(['caddy']),
+        topology,
+      }),
+    ).toBeNull();
+  });
+});
+
+describe('--stop-infra acts only on celilo-provisioned infrastructure (design D2, revised)', () => {
+  // The RULING is about ownership, not capability, and the distinction lives in
+  // the message the operator reads — so the message is what gets pinned.
+  //
+  // celilo could SSH into a machine and stop something. It declines to, because
+  // a machine-pool system is operator-pre-provisioned, may predate celilo, and
+  // may run work celilo was never told about. Reporting "celilo cannot identify
+  // the service unit" would imply a capability gap where the truth is that this
+  // is not celilo's to stop.
+  test('the machine-hosted report reads as not-applicable, not as a missing feature', () => {
+    const report = describeMachineStopInfra('iot', 'homebridge');
+
+    expect(report).toContain('not applicable');
+    expect(report).toContain('celilo provisioned');
+    // Must NOT frame it as something celilo would do if only it could.
+    expect(report).not.toMatch(/cannot determine|does not know which|unit/i);
+  });
+});