@celilo/cli 2.2.1 → 3.0.0

package/src/cli/commands/module-upgrade.ts

@@ -22,6 +22,7 @@ import type { ModuleManifest } from '../../manifest/schema';
 import { RegistryClient } from '../../registry/client';
 import { createModuleBackup, createSystemStateBackup } from '../../services/backup-create';
 import { getDefaultBackupStorage } from '../../services/backup-storage';
+import { capabilityBlockersForManifest } from '../../services/capability-compat';
 import {
   type DeployPosture,
   type UpgradePolicy,
@@ -33,6 +34,7 @@ import { deployModule } from '../../services/module-deploy';
 import { getArg, getFlag } from '../parser';
 import { log } from '../prompts';
 import type { CommandResult } from '../types';
+import { fetchTargetManifest } from './module-update';
 import { classifyVersionChange, fetchAndUpdate } from './module-update';
 
 const VALID_POLICIES: readonly UpgradePolicy[] = ['by-semver', 'always-safe', 'always-fast'];
@@ -127,6 +129,8 @@ export interface PollCandidate {
   /** Latest registry version, or null when the module isn't on the registry. */
   latest: string | null;
   autoUpgrade: boolean;
+  /** True when the module row carries state ERROR (a failed upgrade, celilo#1363). */
+  inError: boolean;
 }
 
 export interface PollTarget {
@@ -144,6 +148,10 @@ export function selectPollTargets(candidates: PollCandidate[]): PollTarget[] {
   const targets: PollTarget[] = [];
   for (const c of candidates) {
     if (!c.autoUpgrade || !c.latest) continue;
+    // A module in ERROR failed an upgrade already. Retrying it on every poll
+    // redeploys the same broken version indefinitely (celilo#1363), so skip it
+    // until an attended health check clears the state (healthy → VERIFIED).
+    if (c.inError) continue;
     const change = classifyVersionChange(c.installed, c.latest);
     if (change === 'up-to-date' || change === 'ahead') continue;
     targets.push({ moduleId: c.moduleId, from: c.installed, to: c.latest });
@@ -163,8 +171,10 @@ function resolveAutoUpgrade(moduleId: string): boolean {
  * Upgrade ONE module to a known target version: posture → update → backup →
  * deploy → verify. The shared core for both the single-module command and the
  * poll. `mod` is the current DB row; `targetVersion` is the registry latest.
+ * Exported for tests: the failure paths here are where the store diverges from
+ * reality (celilo#1363).
  */
-async function upgradeOneModule(
+export async function upgradeOneModule(
   mod: typeof modules.$inferSelect,
   targetVersion: string,
   client: RegistryClient,
@@ -173,6 +183,28 @@ async function upgradeOneModule(
 ): Promise<CommandResult> {
   const moduleId = mod.id;
 
+  // GATE (celilo#1361): read the TARGET manifest BEFORE anything mutates, and
+  // refuse an upgrade whose capability requirements no deployed provider
+  // serves. Deploying first and failing in the module's publish hook is how
+  // celilo-website burned six release revisions (+1 through +6): each failure
+  // recorded the new version, re-triggered the poll, and changed nothing.
+  // A deferral changes no state and retries once the provider lands.
+  const targetManifestCheck = await fetchTargetManifest(client, moduleId, targetVersion);
+  if (targetManifestCheck.ok) {
+    const blockers = capabilityBlockersForManifest(db, targetManifestCheck.manifest);
+    if (blockers.length > 0) {
+      const why = blockers.map((b) => b.message).join('; ');
+      return {
+        success: false,
+        deferred: true,
+        error: `${moduleId} upgrade to ${targetVersion} deferred: the deployed providers cannot serve its capability requirements: ${why}. Upgrade the provider module first; the registry poll retries automatically.`,
+        details: blockers,
+      };
+    }
+  }
+  // A failed fetch here is NOT deferred — `fetchAndUpdate` below reports the
+  // same failure through its own channel with the real error text.
+
   // Update FIRST (refresh stored def). Every downstream decision — the
   // backup gate and the posture policy — must consult the TARGET version's
   // manifest, not the installed one. Gating on the pre-update manifest skipped
@@ -237,6 +269,19 @@ async function upgradeOneModule(
   // Deploy (idempotent).
   const deployed = await deployModule(moduleId, db, {});
   if (!deployed.success) {
+    // fetchAndUpdate already swapped the files and wrote the new version to
+    // the store, so the recorded version no longer matches anything verified.
+    // Record the failure in the state rather than leaving a stale VERIFIED
+    // beside the new version (celilo#1363, option A). An attended health check
+    // that passes moves ERROR → VERIFIED and clears the record.
+    db.update(modules)
+      .set({
+        state: 'ERROR',
+        errorMessage: `Upgrade to ${targetVersion} failed to deploy: ${deployed.error}`,
+        updatedAt: new Date(),
+      })
+      .where(eq(modules.id, moduleId))
+      .run();
     return {
       success: false,
       error: `Deploy failed for ${moduleId} (now at ${targetVersion}): ${deployed.error}`,
@@ -288,6 +333,7 @@ async function runRegistryPoll(
       installed: mod.version,
       latest: await latestRegistryVersion(client, mod.id),
       autoUpgrade: resolveAutoUpgrade(mod.id),
+      inError: mod.state === 'ERROR',
     });
   }
 
@@ -298,6 +344,7 @@ async function runRegistryPoll(
 
   log.info(`Registry poll: ${targets.length} module(s) to upgrade.`);
   const upgraded: string[] = [];
+  const deferred: string[] = [];
   const failed: string[] = [];
   // Serial, in installed order. (Strict provider-before-consumer ordering via
   // topologicalOrder is a refinement; the poll is idempotent + re-runs.)
@@ -305,14 +352,29 @@ async function runRegistryPoll(
     const mod = rowById.get(t.moduleId);
     if (!mod) continue;
     const result = await upgradeOneModule(mod, t.to, client, db, flags);
-    if (result.success) upgraded.push(`${t.moduleId}→${t.to}`);
-    else failed.push(`${t.moduleId}: ${result.error}`);
+    if (result.success) {
+      upgraded.push(`${t.moduleId}→${t.to}`);
+    } else if (result.deferred) {
+      // Expected steady state while a provider upgrade is still pending: the
+      // consumer retries next tick. Not a failure — celilo#1361.
+      deferred.push(`${t.moduleId}: ${result.error}`);
+    } else {
+      failed.push(`${t.moduleId}: ${result.error}`);
+    }
   }
 
   if (failed.length > 0) {
     return {
       success: false,
-      error: `Registry poll: upgraded ${upgraded.length}, FAILED ${failed.length}:\n  ${failed.join('\n  ')}`,
+      error:
+        `Registry poll: upgraded ${upgraded.length}, deferred ${deferred.length}, FAILED ${failed.length}:\n` +
+        `  ${[...failed, ...(deferred.length > 0 ? [`(deferred) ${deferred.join('\n  (deferred) ')}`] : [])].join('\n  ')}`,
+    };
+  }
+  if (deferred.length > 0) {
+    return {
+      success: true,
+      message: `Registry poll: upgraded ${upgraded.length}, deferred ${deferred.length} (capability requirements not yet served — retries next poll):\n  ${deferred.join('\n  ')}`,
     };
   }
   return {

package/src/cli/commands/module-verify.test.ts

@@ -30,7 +30,7 @@ describe('moduleAudit (deprecation alias)', () => {
   afterEach(() => {
     rmSync(dataDir, { recursive: true, force: true });
     resetTestDbPath();
-    if (originalDataDir === undefined) process.env.CELILO_DATA_DIR = undefined;
+    if (originalDataDir === undefined) delete process.env.CELILO_DATA_DIR;
     else process.env.CELILO_DATA_DIR = originalDataDir;
   });
 

package/src/cli/commands/publish/execute.ts

@@ -63,7 +63,10 @@ export async function executePlan(input: ExecutePlanInput): Promise<PublishResul
   }
 
   if (plan.modulePublish.length > 0) {
-    executeModulePublish(plan.modulePublish, { allowStale: plan.options.allowStale });
+    executeModulePublish(plan.modulePublish, {
+      allowStale: plan.options.allowStale,
+      skippedModules: plan.options.skippedModules,
+    });
   }
 
   return result;

package/src/cli/commands/publish/helpers.ts

@@ -91,8 +91,9 @@ export function buildWorkspaceVersionMap(): WorkspaceVersionMap {
 }
 
 /**
- * List every publishable module under modules/. Excludes `archive/`
- * (operator-confirmed: not publishable) and any dir lacking a
+ * List every publishable module under modules/. Excludes `__archive__/`
+ * (operator-confirmed: not publishable, and renamed with the dunder prefix so
+ * nothing mistakes it for a module) and any dir lacking a
  * manifest.yml.
  */
 export function listModuleDirs(): string[] {
@@ -100,7 +101,7 @@ export function listModuleDirs(): string[] {
   if (!existsSync(modulesRoot)) return [];
   const out: string[] = [];
   for (const name of readdirSync(modulesRoot)) {
-    if (name === 'archive') continue;
+    if (name === '__archive__') continue;
     const dir = join(modulesRoot, name);
     let st: ReturnType<typeof statSync>;
     try {

package/src/cli/commands/publish/index.ts

@@ -20,6 +20,7 @@
  *   celilo publish --release-touch                  # auto-fix module stale-drift
  *   celilo publish --allow-stale                    # skip stale-version safeguards
  *   celilo publish -y / --yes                       # auto-confirm prompts
+ *   celilo publish --skip-module <id>               # leave a module out of the registry sweep
  *   celilo publish --alpha                          # X.Y.Z-alpha.N to @alpha
  *   celilo publish --alpha --track-alpha            # also force-pin alphas globally
  *   celilo publish --alpha --alpha-modules          # also publish module +N
@@ -119,7 +120,22 @@ export function parseOptions(argv: string[]): ParsedFlags {
   const trackAlphaFlag = argv.includes('--track-alpha');
   const alphaModulesFlag = argv.includes('--alpha-modules');
   const skipChangesets = argv.includes('--skip-changesets');
+  const skipModulesFlag = argv.includes('--skip-modules');
+  const modulesOnlyFlag = argv.includes('--modules-only');
+  if (skipModulesFlag && modulesOnlyFlag) {
+    console.error('✗ --skip-modules and --modules-only are mutually exclusive.');
+    process.exit(1);
+  }
   const promoteArg = takeFlagValue('--promote');
+  const skippedModules: string[] = [];
+  for (let i = argv.indexOf('--skip-module'); i >= 0; i = argv.indexOf('--skip-module', i + 1)) {
+    const id = argv[i + 1];
+    if (id === undefined || id.startsWith('-')) {
+      console.error('✗ --skip-module requires a module id (e.g. --skip-module homebridge)');
+      process.exit(1);
+    }
+    skippedModules.push(id);
+  }
 
   if (alphaFlag && promoteArg) {
     console.error('✗ --alpha and --promote are mutually exclusive.');
@@ -152,7 +168,13 @@ export function parseOptions(argv: string[]): ParsedFlags {
   }
 
   return {
-    options: { allowStale, autoYes: yes, mode },
+    options: {
+      allowStale,
+      autoYes: yes,
+      mode,
+      skippedModules,
+      modulePhase: modulesOnlyFlag ? 'only' : skipModulesFlag ? 'skip' : 'run',
+    },
     dryRun,
     releaseTouch,
     skipChangesets,

package/src/cli/commands/publish/module-registry.test.ts

@@ -8,7 +8,7 @@
  */
 
 import { describe, expect, test } from 'bun:test';
-import { mapModuleDirsToItems } from './module-registry';
+import { applyModuleSkips, mapModuleDirsToItems } from './module-registry';
 
 describe('mapModuleDirsToItems', () => {
   test('empty input → empty plan', () => {
@@ -38,3 +38,26 @@ describe('mapModuleDirsToItems', () => {
     ]);
   });
 });
+
+describe('applyModuleSkips', () => {
+  const items = mapModuleDirsToItems([
+    '/repo/modules/caddy',
+    '/repo/modules/burner',
+    '/repo/modules/homebridge',
+  ]);
+
+  test('no skips leaves the plan unchanged', () => {
+    expect(applyModuleSkips(items, [])).toEqual(items);
+  });
+
+  test('drops each named module and keeps the order of the rest', () => {
+    expect(applyModuleSkips(items, ['burner']).map((m) => m.moduleDir)).toEqual([
+      '/repo/modules/caddy',
+      '/repo/modules/homebridge',
+    ]);
+  });
+
+  test('a name that matches no module directory throws and names it', () => {
+    expect(() => applyModuleSkips(items, ['burnr'])).toThrow('burnr');
+  });
+});

package/src/cli/commands/publish/module-registry.ts

@@ -11,7 +11,7 @@
 
 import { spawnSync } from 'node:child_process';
 import { existsSync } from 'node:fs';
-import { join, relative } from 'node:path';
+import { basename, join, relative } from 'node:path';
 import { REPO_ROOT, listModuleDirs } from './helpers';
 import type { ModuleItem } from './types';
 
@@ -28,13 +28,31 @@ export function mapModuleDirsToItems(dirs: string[]): ModuleItem[] {
   return dirs.map((moduleDir) => ({ moduleDir }));
 }
 
-export function planModulePublish(): ModuleItem[] {
-  return mapModuleDirsToItems(listModuleDirs());
+/**
+ * Leave the modules named by `--skip-module` out of the sweep. A name
+ * that matches no module directory throws, so a typo cannot skip
+ * nothing and publish the module it meant to hold back.
+ */
+export function applyModuleSkips(items: ModuleItem[], skippedModules: string[]): ModuleItem[] {
+  const known = new Set(items.map((m) => basename(m.moduleDir)));
+  const unknown = skippedModules.filter((id) => !known.has(id));
+  if (unknown.length > 0) {
+    throw new Error(`--skip-module names no module directory: ${unknown.join(', ')}`);
+  }
+  const skipped = new Set(skippedModules);
+  return items.filter((m) => !skipped.has(basename(m.moduleDir)));
+}
+
+export function planModulePublish(skippedModules: string[]): ModuleItem[] {
+  return applyModuleSkips(mapModuleDirsToItems(listModuleDirs()), skippedModules);
 }
 
 // ─── Executor ──────────────────────────────────────────────────────
 
-export function executeModulePublish(items: ModuleItem[], opts: { allowStale: boolean }): void {
+export function executeModulePublish(
+  items: ModuleItem[],
+  opts: { allowStale: boolean; skippedModules: string[] },
+): void {
   if (items.length === 0) {
     console.log('\nNo modules with manifest.yml found — skipping module-publish phase.');
     return;
@@ -49,6 +67,7 @@ export function executeModulePublish(items: ModuleItem[], opts: { allowStale: bo
   console.log('\n──────────────────────────────────────────────');
   console.log(' Publishing modules to celilo registry');
   console.log('──────────────────────────────────────────────');
+  for (const id of opts.skippedModules) console.log(`  modules/${id}  (skipped: --skip-module)`);
   for (const m of items) console.log(`  ${relative(REPO_ROOT, m.moduleDir)}`);
   console.log();
 

package/src/cli/commands/publish/plan.test.ts

@@ -0,0 +1,64 @@
+/**
+ * decidePhases — the pure phase-gating decision behind `celilo publish`.
+ *
+ * The module-phase flags (`--skip-modules` / `--modules-only`) exist so
+ * the release pipeline can deliver the CLI independently of the module
+ * sweep (celilo#1369). Their gating lives in one pure function so the
+ * combinations are testable without npm, git or the registry.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { decidePhases } from './plan';
+
+describe('decidePhases', () => {
+  test('normal mode, default phase: everything runs', () => {
+    expect(decidePhases({ kind: 'normal' }, 'run')).toEqual({
+      workspace: true,
+      consumerPins: true,
+      globalUpdate: true,
+      modulePublish: true,
+    });
+  });
+
+  test('--skip-modules plans no module sweep, keeps the npm phases', () => {
+    expect(decidePhases({ kind: 'normal' }, 'skip')).toEqual({
+      workspace: true,
+      consumerPins: true,
+      globalUpdate: true,
+      modulePublish: false,
+    });
+  });
+
+  test('--modules-only plans the module sweep and nothing else', () => {
+    expect(decidePhases({ kind: 'normal' }, 'only')).toEqual({
+      workspace: false,
+      consumerPins: false,
+      globalUpdate: false,
+      modulePublish: true,
+    });
+  });
+
+  test('promote is a real release — same shape as normal', () => {
+    expect(
+      decidePhases({ kind: 'promote', target: { name: '@celilo/cli', version: '1.0.0' } }, 'run'),
+    ).toEqual(decidePhases({ kind: 'normal' }, 'run'));
+  });
+
+  test('alpha still suppresses pins and the sweep without --alpha-modules', () => {
+    expect(decidePhases({ kind: 'alpha', trackAlpha: false, alphaModules: false }, 'run')).toEqual({
+      workspace: true,
+      consumerPins: false,
+      globalUpdate: false,
+      modulePublish: false,
+    });
+  });
+
+  test('alpha with --track-alpha and --alpha-modules runs its phases', () => {
+    expect(decidePhases({ kind: 'alpha', trackAlpha: true, alphaModules: true }, 'run')).toEqual({
+      workspace: true,
+      consumerPins: false,
+      globalUpdate: true,
+      modulePublish: true,
+    });
+  });
+});

package/src/cli/commands/publish/plan.ts

@@ -17,9 +17,48 @@ import { planGlobalUpdate } from './global-install';
 import { buildWorkspaceVersionMap, currentGitHead, getPublishPackages } from './helpers';
 import { planModulePublish } from './module-registry';
 import { runPreflight } from './preflight';
-import type { PublishOptions, PublishPlan } from './types';
+import type { PublishMode, PublishOptions, PublishPlan } from './types';
 import { planWorkspace } from './workspace';
 
+/**
+ * Which publish phases run, from the mode and the module-phase flag.
+ * Pure so the flag combinations stay testable without npm, git or the
+ * registry.
+ *
+ * `modulePhase` only moves the module sweep: `skip` plans no sweep (the
+ * npm phases run alone), `only` plans the sweep alone (celilo#1369's
+ * release-pipeline split — CLI delivery must not depend on the sweep,
+ * so the sweep is run as its own invocation after delivery).
+ */
+export interface PlannedPhases {
+  workspace: boolean;
+  consumerPins: boolean;
+  globalUpdate: boolean;
+  modulePublish: boolean;
+}
+
+export function decidePhases(
+  mode: PublishMode,
+  modulePhase: PublishOptions['modulePhase'],
+): PlannedPhases {
+  if (modulePhase === 'only') {
+    return { workspace: false, consumerPins: false, globalUpdate: false, modulePublish: true };
+  }
+  const runPhase2 = mode.kind !== 'alpha';
+  const runPhase3 = mode.kind !== 'alpha' || mode.trackAlpha;
+  const runModulePublish =
+    (mode.kind === 'normal' ||
+      mode.kind === 'promote' ||
+      (mode.kind === 'alpha' && mode.alphaModules)) &&
+    modulePhase !== 'skip';
+  return {
+    workspace: true,
+    consumerPins: runPhase2,
+    globalUpdate: runPhase3,
+    modulePublish: runModulePublish,
+  };
+}
+
 /**
  * Build the full publish plan. Reads from the world (preflight, npm,
  * git, fs); doesn't mutate.
@@ -40,15 +79,16 @@ import { planWorkspace } from './workspace';
  */
 export function planPublish(opts: PublishOptions): PublishPlan {
   const preflight = runPreflight();
-  const baseWorkspaceVersions = buildWorkspaceVersionMap();
-  const gitHead = currentGitHead();
+  const phases = decidePhases(opts.mode, opts.modulePhase);
 
-  const workspaceResult = planWorkspace({
-    mode: opts.mode,
-    packages: getPublishPackages(),
-    baseWorkspaceVersions,
-    gitHead,
-  });
+  const workspaceResult = phases.workspace
+    ? planWorkspace({
+        mode: opts.mode,
+        packages: getPublishPackages(),
+        baseWorkspaceVersions: buildWorkspaceVersionMap(),
+        gitHead: currentGitHead(),
+      })
+    : { items: [] };
 
   // PROJECTED publish list — what executeWorkspace would land on
   // npm if no per-package skips happen at execution time. Used to
@@ -57,26 +97,19 @@ export function planPublish(opts: PublishOptions): PublishPlan {
     .filter((item) => !item.skipReason)
     .map((item) => ({ name: item.name, version: item.versionToPublish }));
 
-  const runPhase2 = opts.mode.kind !== 'alpha';
-  const runPhase3 = opts.mode.kind !== 'alpha' || opts.mode.trackAlpha;
-  const runPhase4 =
-    opts.mode.kind === 'normal' ||
-    opts.mode.kind === 'promote' ||
-    (opts.mode.kind === 'alpha' && opts.mode.alphaModules);
-
   return {
     mode: opts.mode,
     options: opts,
     preflight,
     workspace: workspaceResult.items,
-    consumerPins: runPhase2 ? planConsumerPins() : [],
-    globalUpdate: runPhase3
+    consumerPins: phases.consumerPins ? planConsumerPins() : [],
+    globalUpdate: phases.globalUpdate
       ? planGlobalUpdate({
           justPublished: projectedPublishes,
           trackAlpha: opts.mode.kind === 'alpha' && opts.mode.trackAlpha,
         })
       : [],
-    modulePublish: runPhase4 ? planModulePublish() : [],
+    modulePublish: phases.modulePublish ? planModulePublish(opts.skippedModules) : [],
   };
 }
 

package/src/cli/commands/publish/types.ts

@@ -61,6 +61,26 @@ export interface PublishOptions {
   allowStale: boolean;
   autoYes: boolean;
   mode: PublishMode;
+  /**
+   * Module ids to leave out of the module-registry sweep (`--skip-module
+   * <id>`, repeatable). For a module that cannot publish yet. A failed
+   * module no longer stops the sweep (celilo#1369), but it still fails
+   * the run at the end, so a module that cannot publish yet is held
+   * back with this instead.
+   */
+  skippedModules: string[];
+  /**
+   * Which part of the publish touches the module registry (`--modules-only`
+   * / `--skip-modules`). `run` is the default whole publish. `skip` runs
+   * the npm phases only; `only` runs the module sweep only.
+   *
+   * The release pipeline uses the split so CLI delivery (the .deb, the
+   * apt upload, the Forgejo release) does not depend on the module sweep
+   * succeeding: npm publishes first, the fleet delivery happens, and the
+   * module sweep runs last, where its failure reds the run without
+   * withholding the CLI (celilo#1369).
+   */
+  modulePhase: 'run' | 'skip' | 'only';
 }
 
 /**

package/src/cli/commands/registry-owner.test.ts

@@ -45,7 +45,7 @@ describe('registry owner commands', () => {
   afterEach(async () => {
     fetchSpy.mockRestore();
     closeDb();
-    process.env.CELILO_DATA_DIR = undefined;
+    delete process.env.CELILO_DATA_DIR;
     resetTestDbPath();
     if (existsSync(dataDir)) await rm(dataDir, { recursive: true, force: true });
   });

package/src/cli/commands/registry-token.test.ts

@@ -50,7 +50,7 @@ describe('registry token add/rm (F2 clobber fix)', () => {
 
   afterEach(async () => {
     closeDb();
-    process.env.CELILO_DATA_DIR = undefined;
+    delete process.env.CELILO_DATA_DIR;
     resetTestDbPath();
     if (existsSync(dataDir)) {
       await rm(dataDir, { recursive: true, force: true });

package/src/cli/commands/subscribers-install-daemon.test.ts

@@ -0,0 +1,44 @@
+import { afterAll, describe, expect, it } from 'bun:test';
+import { mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { handleSubscribersInstallDaemon } from './subscribers-install-daemon';
+
+// resolveCeliloPath existence-checks explicit overrides, so the render
+// needs a celilo path that exists — a fake binary in a temp dir.
+const FAKE_CELOLILO = join(mkdtempSync(join(tmpdir(), 'celilo-fake-bin-')), 'celilo');
+writeFileSync(FAKE_CELOLILO, '#!/bin/sh\n', { mode: 0o755 });
+
+// --print renders without writing, so these tests never touch unit paths.
+const PRINT_FLAGS = { print: true, 'celilo-path': FAKE_CELOLILO };
+
+const SAVED_ENV = process.env.CELILO_BUS_SECRET;
+afterAll(() => {
+  if (SAVED_ENV === undefined) delete process.env.CELILO_BUS_SECRET;
+  else process.env.CELILO_BUS_SECRET = SAVED_ENV;
+});
+
+describe('handleSubscribersInstallDaemon secret resolution', () => {
+  it('falls back to CELILO_BUS_SECRET when --secret is absent — the doctor remediation and the rendered unit both lean on that env var', async () => {
+    process.env.CELILO_BUS_SECRET = 'env-secret';
+    const result = await handleSubscribersInstallDaemon([], { ...PRINT_FLAGS });
+    if (!result.success) throw new Error(`expected success: ${result.error}`);
+  });
+
+  it('prefers the --secret flag over the environment', async () => {
+    process.env.CELILO_BUS_SECRET = 'env-secret';
+    const result = await handleSubscribersInstallDaemon([], {
+      ...PRINT_FLAGS,
+      secret: 'flag-secret',
+    });
+    if (!result.success) throw new Error(`expected success: ${result.error}`);
+    expect((result.data as { unitContent: string }).unitContent).toContain('flag-secret');
+  });
+
+  it('refuses to render when neither source has a secret', async () => {
+    delete process.env.CELILO_BUS_SECRET;
+    const result = await handleSubscribersInstallDaemon([], { ...PRINT_FLAGS });
+    if (result.success) throw new Error('expected failure');
+    expect(result.error).toContain('secret is required');
+  });
+});