@pellux/goodvibes-tui 1.25.0 → 1.27.0

package/src/core/workstream-notification.ts

@@ -0,0 +1,69 @@
+/**
+ * workstream-notification.ts — the desktop notification a finished workstream
+ * pushes, in words rather than identifiers.
+ *
+ * These three notifications used to read:
+ *
+ *     GoodVibes — WRFC chain failed
+ *     chain 7f3a91c02b4e failed: review rejected
+ *
+ * A desktop notification is a message TO a person, so the standing rule applies
+ * to it the same way it applies to a chat message: no internal name for the
+ * machinery, and no register id. `WRFC` is the first; `7f3a91c02b4e` is the
+ * second, and it is not something the reader can do anything with — it is not
+ * the commit, not the branch, not the session.
+ *
+ * What the reader can act on is why the work stopped, so that is what the body
+ * now leads with. Two workstreams that end at the same moment are told apart by
+ * their reasons, which is the same principle the channel renderer follows: in
+ * plain words, never by an opaque identifier.
+ *
+ * Split out of turn-event-wiring.ts as a pure function so the text is testable
+ * on its own — the wiring itself cannot be asserted against without mocking a
+ * process-global notifier.
+ */
+import { formatTurnBudgetOutcome } from './turn-budget-outcome.ts';
+
+/** The fields of WORKFLOW_CHAIN_FAILED this narration reads. */
+export interface WorkstreamFailureNarrationInput {
+  readonly reason: string;
+  readonly failureKind?: 'transport' | 'other' | 'cancelled' | 'max_turns' | undefined;
+  readonly turnLimit?: number | undefined;
+  readonly turnLimitSource?: 'default' | 'spawn-override' | 'policy-bound' | undefined;
+}
+
+export interface WorkstreamNotification {
+  readonly title: string;
+  readonly body: string;
+}
+
+/**
+ * Title and body for a workstream that reached a terminal state.
+ *
+ * An operator cancellation is an intended stop, not a failure — it is narrated
+ * as cancelled (the reason already carries the landed-work count from the
+ * workstream's edit ledger) so the notification never contradicts the cancelled
+ * workstream/owner/cohort surfaces. A turn-budget exhaustion is a spent ceiling
+ * rather than an infrastructure error, and its limit and source are read from
+ * the typed event fields, never from a regex of the prose reason.
+ */
+export function workstreamFailureNotification(
+  payload: WorkstreamFailureNarrationInput,
+): WorkstreamNotification {
+  if (payload.failureKind === 'cancelled') {
+    return {
+      title: 'GoodVibes — workstream cancelled',
+      body: `Cancelled: ${payload.reason}`,
+    };
+  }
+  if (payload.failureKind === 'max_turns') {
+    return {
+      title: 'GoodVibes — workstream hit its turn budget',
+      body: `The workstream ${formatTurnBudgetOutcome({ limit: payload.turnLimit, source: payload.turnLimitSource })}`,
+    };
+  }
+  return {
+    title: 'GoodVibes — workstream failed',
+    body: `Failed: ${payload.failureKind === 'transport' ? 'transient transport error' : payload.reason}`,
+  };
+}

package/src/daemon/cli.ts

@@ -7,11 +7,12 @@ import {
 } from '@pellux/goodvibes-sdk/platform/config';
 import type { ConfigKey } from '@pellux/goodvibes-sdk/platform/config';
 import { formatProviderModel, getModelIdFromProviderModel, getProviderIdFromModel } from '../config/provider-model.ts';
-import { resolveGoodVibesHomeOwnership, hasOverriddenGoodVibesHome } from '../config/goodvibes-home.ts';
-import { RuntimeEventBus, GlobalNetworkTransportInstaller } from '@/runtime/index.ts';
+import { resolveGoodVibesHomeOwnership } from '../config/goodvibes-home.ts';
+import { RuntimeEventBus, GlobalNetworkTransportInstaller, configureRuntimeEventBusDefaults, runtimeEventBusOptionsFrom } from '@/runtime/index.ts';
 import { bindFeatureSettingsBridge, createFeatureFlagManager, deriveFeatureStates } from '@/runtime/index.ts';
 import { createRuntimeStore } from '../runtime/store/index.ts';
 import { createRuntimeServices } from '../runtime/services.ts';
+import { startDeviceHousekeeping } from '../runtime/device-posture-composition.ts';
 import { DaemonServer, HttpListener } from '@pellux/goodvibes-sdk/platform/daemon';
 import { createHostPowerSeam } from '@pellux/goodvibes-sdk/platform/power';
 import { flushActivityLogSync, logger } from '@pellux/goodvibes-sdk/platform/utils';
@@ -34,6 +35,10 @@ import {
   persistProviders,
 } from '@pellux/goodvibes-sdk/platform/discovery';
 import { createSafeHostServeFactory } from './safe-serve.ts';
+import { runProvisionWakeModelCommand } from './provision-wake-model.ts';
+import { runSendCommand } from './send/command.ts';
+import { createSendStack } from './send/composition.ts';
+import { readAllStdin } from './send/stdin.ts';
 import { isDaemonServiceSubcommand, resolveInstalledDaemonBinary, runDaemonServiceCli } from './service-commands.ts';
 import { runClusterCommand } from '../cluster/commands.ts';
 import { resolveConfiguredServiceName } from '../runtime/legacy-daemon-migration.ts';
@@ -59,6 +64,8 @@ type DaemonCliOwnership = {
   readonly homeDirectory: string;
   /** The daemon's OWN identity home (auth users, operator tokens, daemon settings). */
   readonly daemonHomeDirectory: string;
+  /** True when GOODVIBES_HOME or GOODVIBES_DAEMON_HOME named an override — see goodvibes-home.ts. */
+  readonly isOverridden: boolean;
 };
 
 // CLI flag parsing delegated to shared module — see src/cli-flags.ts
@@ -87,11 +94,12 @@ function resolveDaemonCliOwnership(): DaemonCliOwnership {
   // point also uses. They were resolved independently, and the client's copy
   // simply did not read GOODVIBES_HOME — so a redirected client wrote into the
   // real tree while the daemon honoured the redirect.
-  const { homeDirectory, daemonHomeDirectory } = resolveGoodVibesHomeOwnership();
+  const { homeDirectory, daemonHomeDirectory, isOverridden } = resolveGoodVibesHomeOwnership();
   return {
     workingDirectory: process.env['GOODVIBES_WORKING_DIR'] ?? process.cwd(),
     homeDirectory,
     daemonHomeDirectory,
+    isOverridden,
   };
 }
 
@@ -137,6 +145,63 @@ async function main(): Promise<void> {
     process.exit(result.exitCode);
   }
 
+  // `send …` is intercepted here for both of the reasons `cluster` is, plus one
+  // of its own.
+  //
+  // Before the parser, because the message is arbitrary operator text: a
+  // message beginning with a dash, or one carrying `--port` inside it, must
+  // reach the channel rather than be eaten as a daemon flag.
+  //
+  // Before the runtime, because this composes only the services a delivery
+  // needs (see send/composition.ts) and must not start a second copy of the
+  // pollers, cluster election and LAN scan a running daemon already owns.
+  //
+  // And it must work when NO daemon is running, which is much of the point: the
+  // reason to message the owner is usually that something stopped.
+  if (rawArgs[0] === 'send') {
+    const ownership = resolveDaemonCliOwnership();
+    runDaemonConfigMigration(ownership.homeDirectory);
+    const stack = createSendStack({
+      workingDirectory: ownership.workingDirectory,
+      homeDirectory: ownership.homeDirectory,
+      daemonHomeDirectory: ownership.daemonHomeDirectory,
+    });
+    const result = await runSendCommand(rawArgs.slice(1), {
+      configManager: stack.configManager,
+      deliver: stack.deliver,
+      readStdin: readAllStdin,
+      stdinIsTty: process.stdin.isTTY === true,
+    });
+    for (const line of result.lines) {
+      // eslint-disable-next-line no-console
+      if (result.exitCode === 0) console.log(line);
+      else console.error(line);
+    }
+    // The activity log holds the OUTBOUND_HTTP record for the send that just
+    // happened (or did not); a process exiting this promptly would drop it.
+    flushActivityLogSync();
+    process.exit(result.exitCode);
+  }
+
+  // `provision-wake-model …` is intercepted here for the same two reasons, plus
+  // its own: the curl installer runs it on the binary it has just placed, before
+  // any daemon exists, and it must reach the SDK's pinned manifest rather than
+  // have install.sh carry a second copy of the pins. It composes no runtime — it
+  // resolves a home directory, derives the managed voice root the running daemon
+  // uses, and calls one SDK function. See provision-wake-model.ts for why it
+  // exits 0 on a failed download.
+  if (rawArgs[0] === 'provision-wake-model') {
+    const ownership = resolveDaemonCliOwnership();
+    const result = await runProvisionWakeModelCommand(rawArgs.slice(1), {
+      homeDirectory: ownership.homeDirectory,
+    });
+    for (const line of result.lines) {
+      // eslint-disable-next-line no-console
+      console.log(line);
+    }
+    process.exit(result.exitCode);
+  }
+
   // Parse CLI flags first so --daemon-home and --working-dir env vars are set
   // before resolveDaemonCliOwnership() reads them.
   const cli = parseGoodVibesCli(process.argv.slice(2), 'goodvibes-daemon');
@@ -169,7 +234,7 @@ async function main(): Promise<void> {
     logger.info('daemon: --working-dir flag applied', { workingDir: cliFlags.workingDir });
   }
 
-  const { workingDirectory: workingDir, homeDirectory, daemonHomeDirectory } = resolveDaemonCliOwnership();
+  const { workingDirectory: workingDir, homeDirectory, daemonHomeDirectory, isOverridden: hasOverriddenHome } = resolveDaemonCliOwnership();
   runDaemonConfigMigration(homeDirectory);
   const config = new ConfigManager({ workingDir, homeDir: homeDirectory, surfaceRoot: 'tui' });
   new GlobalNetworkTransportInstaller().install(config);
@@ -299,6 +364,9 @@ async function main(): Promise<void> {
     }
   }
 
+  // Point the bus listener cap at runtime.eventBus.maxListeners before the
+  // first bus exists, so every bus this process builds later uses it.
+  configureRuntimeEventBusDefaults(runtimeEventBusOptionsFrom((key) => config.get(key)));
   const runtimeBus = new RuntimeEventBus();
   const runtimeStore = createRuntimeStore();
   // Gate states derive from the domain settings keys; the bridge keeps live
@@ -330,6 +398,13 @@ async function main(): Promise<void> {
     // the non-spawning unavailable seam; only daemon compositions opt in. Mirrors
     // the SDK daemon cli's createHostPowerSeam() (sdk commit 3a5ea26d).
     powerSeam: createHostPowerSeam(),
+    // The wake-word model ships with the installation, and this is the retry: at
+    // every daemon start, sweep the managed wake tree and fetch whatever the
+    // install could not (an offline install, a killed download, a changed pin).
+    // It never blocks startup and never fails it — see the SDK's
+    // voice/wake/install-provision.ts. The webui reads the model bytes from THIS
+    // process, so a provisioned daemon is what makes the browser path work too.
+    provisionWakeModelsAtBoot: true,
   });
 
   // Load persisted providers from disk so the provider registry is pre-populated
@@ -371,7 +446,7 @@ async function main(): Promise<void> {
     // found the unit not running, wrote its own scratchpad ExecStart into
     // ~/.config/systemd/user/goodvibes.service and exited, and systemd then
     // supervised the throwaway as the machine's daemon for five hours.
-    hasOverriddenHome: hasOverriddenGoodVibesHome(),
+    hasOverriddenHome,
     // The SAME coordinator this repository's inbox poller registered with (see
     // runtime/cluster-composition.ts). The facade must reuse it rather than
     // compose its own: two coordinators in one process are two nodes in the
@@ -416,6 +491,12 @@ async function main(): Promise<void> {
   // box that has been off for months re-keys itself with no operator action.
   await runtimeServices.startCluster();
 
+  // Grants and captures from paired phones outlive a restart, so the recovery
+  // sweep runs before this daemon serves its first request and the periodic one
+  // keeps a long-running daemon from going days without a sweep. The stop is
+  // registered with the disposal scope, so shutdown clears the timer.
+  startDeviceHousekeeping(runtimeServices.devicePosture);
+
   await Promise.all([
     daemon.start(),
     config.get('danger.httpListener') ? listener.start() : Promise.resolve(),

package/src/daemon/handlers/credentials.ts

@@ -1,5 +1,5 @@
 import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto';
-import type { SecretsManager } from '../../config/secrets.ts';
+import type { SecretsManager, SecretScope } from '../../config/secrets.ts';
 import {
   buildGoodVibesSecretKey,
   isSecretReferenceValue,
@@ -16,11 +16,21 @@ export interface DaemonCredentialStore {
    * (e.g. 'surfaces.slack.botToken' → GOODVIBES_SURFACES_SLACK_BOT_TOKEN).
    */
   resolveConfigSecret(configKey: string): Promise<string | null>;
-  /** Store a daemon-owned credential. scope defaults 'user'. */
+  /**
+   * Store a daemon-owned credential. scope defaults 'daemon'.
+   *
+   * This is the DAEMON's own credential store: every caller is daemon code, and
+   * every value written through it is one the daemon itself has to read back —
+   * including its own generated draft encryption key (createAtRestCipher below,
+   * which calls put() with no scope at all). Defaulting to 'user' filed those
+   * in a surface-scoped tier, so the daemon's own material lived somewhere it
+   * only found by accident, and a value written on one surface's behalf was
+   * invisible to the next.
+   */
   put(
     secretKey: string,
     value: string,
-    opts?: { scope?: 'user' | 'project'; medium?: 'plaintext' | 'secure' },
+    opts?: { scope?: SecretScope; medium?: 'plaintext' | 'secure' },
   ): Promise<void>;
   has(secretKey: string): Promise<boolean>;
 }
@@ -45,10 +55,10 @@ export function createDaemonCredentialStore(secrets: SecretsManager): DaemonCred
     async put(
       secretKey: string,
       value: string,
-      opts?: { scope?: 'user' | 'project'; medium?: 'plaintext' | 'secure' },
+      opts?: { scope?: SecretScope; medium?: 'plaintext' | 'secure' },
     ): Promise<void> {
       await secrets.set(secretKey, value, {
-        scope: opts?.scope ?? 'user',
+        scope: opts?.scope ?? 'daemon',
         medium: opts?.medium ?? 'secure',
       });
     },

package/src/daemon/provision-wake-model.ts

@@ -0,0 +1,81 @@
+// ---------------------------------------------------------------------------
+// provision-wake-model.ts — `goodvibes-daemon provision-wake-model`.
+//
+// WHAT THIS IS FOR
+//
+// The curl installer needs to put the wake-word model on the machine, and it must
+// not hold the pinned URLs, byte counts or checksums to do it. Those live in ONE
+// place — the SDK's wake-word manifest — and a shell script that copied them
+// would be a second copy of a pin, drifting silently the first time the model is
+// retrained. So the installer runs the binary it just installed and lets the SDK
+// do what the SDK owns.
+//
+// IT EXITS 0 EVEN WHEN THE DOWNLOAD FAILS, ON PURPOSE
+//
+// The caller is an installer. A wake-word model is not a reason to fail installing
+// a coding tool, and an installer that aborts half-way through is worse than one
+// that finishes without a wake word. The outcome is printed either way — one plain
+// line naming what happened and how to retry — and a running daemon retries at
+// every boot. `--strict` is there for a caller that genuinely wants the exit code
+// to carry the result (a test, a provisioning script that is checking); the
+// installer does not pass it.
+//
+// It composes NOTHING. No runtime, no config manager, no gateway: this reads a
+// home directory, derives the managed voice root the same way the running daemon
+// does, and calls one SDK function. Composing a runtime here would start a second
+// set of pollers on a machine whose daemon is probably already running.
+// ---------------------------------------------------------------------------
+
+import {
+  provisionWakeWordModelsAtInstall,
+  resolveManagedVoiceRoot,
+} from '@pellux/goodvibes-sdk/platform/voice';
+
+export interface ProvisionWakeModelResult {
+  readonly exitCode: number;
+  readonly lines: readonly string[];
+}
+
+export interface ProvisionWakeModelDeps {
+  /** The home directory whose `.goodvibes/voice` tree receives the artifacts. */
+  readonly homeDirectory: string;
+  readonly env?: Readonly<Record<string, string | undefined>> | undefined;
+  /** Injected in tests: the SDK policy, so nothing downloads. */
+  readonly provisionAtInstall?: typeof provisionWakeWordModelsAtInstall | undefined;
+}
+
+/**
+ * Run the install-time provision and report it.
+ *
+ * `--strict` makes a degraded outcome exit 1. Without it, every outcome exits 0,
+ * because the caller is an installer and the alternative is an aborted install
+ * over an optional model.
+ */
+export async function runProvisionWakeModelCommand(
+  argv: readonly string[],
+  deps: ProvisionWakeModelDeps,
+): Promise<ProvisionWakeModelResult> {
+  const strict = argv.includes('--strict');
+  const provision = deps.provisionAtInstall ?? provisionWakeWordModelsAtInstall;
+  let managedRoot: string;
+  try {
+    managedRoot = resolveManagedVoiceRoot(deps.homeDirectory);
+  } catch (error) {
+    // A home directory this process cannot make sense of is still not a reason to
+    // fail an install, so it is reported on the same terms as a failed download.
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      exitCode: strict ? 1 : 0,
+      lines: [`wake-word model: skipped — ${message}`],
+    };
+  }
+  const outcome = await provision({
+    managedRoot,
+    recoveryHint: '/voice wake setup',
+    ...(deps.env !== undefined ? { env: deps.env } : {}),
+  });
+  return {
+    exitCode: strict && outcome.state === 'degraded' ? 1 : 0,
+    lines: [`wake-word model: ${outcome.message}`],
+  };
+}

package/src/daemon/send/channels.ts

@@ -0,0 +1,200 @@
+/**
+ * channels.ts — which channels `goodvibes-daemon send` can reach, and which one
+ * it uses when the operator names none.
+ *
+ * The surface list, labels and required-setup keys are IMPORTED from
+ * `src/cli/surface-command.ts` rather than restated, so `goodvibes surfaces
+ * list` and `goodvibes-daemon send --list` can never disagree about what a
+ * channel is called or what it needs. What this module adds on top is the two
+ * facts that command needs and `SURFACE_CONFIGS` does not carry: the routable
+ * `ChannelDeliverySurfaceKind` for each surface id (they differ in case —
+ * `googleChat` vs `google-chat`), and the settings key holding each surface's
+ * default destination.
+ */
+
+import type { ConfigKey, ConfigManager } from '../../config/index.ts';
+import type { ChannelDeliverySurfaceKind } from '@pellux/goodvibes-sdk/platform/channels';
+import { SURFACE_CONFIGS } from '../../cli/surface-command.ts';
+import { canRenderInert } from './inert-text.ts';
+
+/**
+ * The settings key holding each supported surface's default destination — the
+ * chat, channel, topic or URL a message goes to when `--to` is not given.
+ *
+ * These are the SAME keys the delivery strategies in the SDK's
+ * `strategies-core.ts` fall back to (`surfaces.telegram.defaultChatId`,
+ * `surfaces.discord.defaultChannelId`, …). Only surfaces with a verified inert
+ * transform appear; see inert-text.ts for why the rest are refused rather than
+ * sent to.
+ */
+const DESTINATION_KEY_BY_SURFACE_ID = {
+  telegram: 'surfaces.telegram.defaultChatId',
+  ntfy: 'surfaces.ntfy.topic',
+  discord: 'surfaces.discord.defaultChannelId',
+  slack: 'surfaces.slack.defaultChannel',
+  googleChat: 'surfaces.googleChat.webhookUrl',
+  webhook: 'surfaces.webhook.defaultTarget',
+  signal: 'surfaces.signal.defaultRecipient',
+  whatsapp: 'surfaces.whatsapp.defaultRecipient',
+  imessage: 'surfaces.imessage.defaultChatId',
+  msteams: 'surfaces.msteams.defaultConversationId',
+  bluebubbles: 'surfaces.bluebubbles.defaultChatGuid',
+  mattermost: 'surfaces.mattermost.defaultChannelId',
+  matrix: 'surfaces.matrix.defaultRoomId',
+  // Not cast: every value is checked against the real ConfigKey union, so a
+  // key that is renamed or misspelled in the schema fails the build here
+  // instead of reading `undefined` at send time and reporting the channel as
+  // unconfigured.
+} as const satisfies Readonly<Record<string, ConfigKey>>;
+
+/** Surface ids whose routable kind is not simply the id itself. */
+const SURFACE_KIND_BY_ID: Readonly<Record<string, ChannelDeliverySurfaceKind>> = {
+  googleChat: 'google-chat',
+};
+
+/**
+ * What `--to` addresses on each channel, in that channel's own vocabulary.
+ *
+ * This is naming, not a scheme: `--to` becomes `ChannelDeliveryTarget.address`,
+ * which is the first thing every strategy in `strategies-core.ts`,
+ * `strategies-bridge.ts` and `strategies-enterprise.ts` already checks before
+ * falling back to its configured default. Nothing new is invented — the label
+ * exists so `--list` and the help can say "topic" where the channel says topic
+ * and "chat id" where it says chat id, rather than making the operator work out
+ * what an "address" is for ntfy.
+ */
+const ADDRESS_LABEL_BY_SURFACE_ID: Readonly<Record<string, string>> = {
+  telegram: 'chat id',
+  ntfy: 'topic',
+  discord: 'channel id',
+  slack: 'channel id',
+  googleChat: 'webhook URL',
+  webhook: 'URL',
+  signal: 'recipient',
+  whatsapp: 'recipient',
+  imessage: 'chat id',
+  msteams: 'conversation id',
+  bluebubbles: 'chat GUID',
+  mattermost: 'channel id',
+  matrix: 'room id',
+};
+
+export interface SendChannel {
+  /** The id an operator types after `--channel`, e.g. `telegram`. */
+  readonly id: string;
+  /** Human label, shared with `goodvibes surfaces list`. */
+  readonly label: string;
+  /** The kind the channel delivery router routes on. */
+  readonly surfaceKind: ChannelDeliverySurfaceKind;
+  /** `surfaces.<id>.enabled`. */
+  readonly enabledKey: ConfigKey;
+  /** The settings key holding this channel's default destination. */
+  readonly destinationKey: ConfigKey;
+  /** What `--to` names on this channel, in the channel's own words ("topic"). */
+  readonly addressLabel: string;
+}
+
+/**
+ * Every channel this command can deliver to. Derived, not restated: a surface
+ * that gains a delivery strategy and an inert transform appears here by adding
+ * its destination key above, and a surface that loses its entry in
+ * `SURFACE_CONFIGS` disappears from both commands at once.
+ */
+const destinationKeys: Readonly<Record<string, ConfigKey>> = DESTINATION_KEY_BY_SURFACE_ID;
+
+export const SEND_CHANNELS: readonly SendChannel[] = SURFACE_CONFIGS
+  .flatMap(([id, label]): SendChannel[] => {
+    const destinationKey = destinationKeys[id];
+    if (!destinationKey) return [];
+    const surfaceKind = SURFACE_KIND_BY_ID[id] ?? (id as ChannelDeliverySurfaceKind);
+    if (!canRenderInert(surfaceKind)) return [];
+    return [{
+      id,
+      label,
+      surfaceKind,
+      enabledKey: `surfaces.${id}.enabled` as ConfigKey,
+      destinationKey,
+      addressLabel: ADDRESS_LABEL_BY_SURFACE_ID[id] ?? 'address',
+    }];
+  });
+
+/**
+ * Look a channel up by the id an operator typed, accepting either the settings
+ * id (`googleChat`) or the routable kind (`google-chat`) — the two spellings
+ * are both visible in this product's own output, and making the operator
+ * remember which one this command wants would be a trap.
+ */
+export function findSendChannel(name: string): SendChannel | undefined {
+  const wanted = name.trim().toLowerCase();
+  return SEND_CHANNELS.find((channel) =>
+    channel.id.toLowerCase() === wanted || channel.surfaceKind.toLowerCase() === wanted);
+}
+
+export interface ChannelReadiness {
+  readonly channel: SendChannel;
+  /** `surfaces.<id>.enabled` is true. */
+  readonly enabled: boolean;
+  /** The configured default destination, or null when the key is blank. */
+  readonly destination: string | null;
+}
+
+function readSetting(config: Pick<ConfigManager, 'get'>, key: ConfigKey): string {
+  const value = config.get(key);
+  return typeof value === 'string' ? value.trim() : value === undefined || value === null ? '' : String(value).trim();
+}
+
+/**
+ * Read every channel's live state from config.
+ *
+ * The `ConfigManager` handed in must be one built with a `homeDir`, because
+ * every `surfaces.*` key is daemon-owned: the manager overlays
+ * `<home>/.goodvibes/daemon/settings.json` LAST, which is the only reason a
+ * client process can see a bot token the daemon owns. A manager built without
+ * that overlay reads a surface silo holding nothing but `setupVersion` and
+ * reports every channel as unconfigured.
+ */
+export function readChannelReadiness(config: Pick<ConfigManager, 'get'>): readonly ChannelReadiness[] {
+  return SEND_CHANNELS.map((channel) => {
+    const destination = readSetting(config, channel.destinationKey);
+    return {
+      channel,
+      enabled: config.get(channel.enabledKey) === true,
+      destination: destination.length > 0 ? destination : null,
+    };
+  });
+}
+
+export type DefaultChannelResolution =
+  | { readonly kind: 'resolved'; readonly channel: SendChannel; readonly destination: string; readonly reason: string }
+  | { readonly kind: 'none'; readonly candidates: readonly ChannelReadiness[] }
+  | { readonly kind: 'ambiguous'; readonly candidates: readonly ChannelReadiness[] };
+
+/**
+ * Which channel a `send` with no `--channel` goes to.
+ *
+ * A channel qualifies when it is switched on AND has a destination configured —
+ * "enabled" alone is not enough, because an enabled surface with a blank
+ * destination is a channel that would throw at the provider rather than deliver.
+ *
+ * **Ambiguity refuses; it never picks.** With two qualifying channels there is
+ * no non-arbitrary winner, and this command has an outward effect: sending the
+ * owner's message to the wrong one of his channels is worse than printing the
+ * list and exiting non-zero. There is deliberately no priority order here to
+ * silently break that tie — a preference ordering baked into this file would be
+ * an invisible decision about where his messages go.
+ */
+export function resolveDefaultChannel(config: Pick<ConfigManager, 'get'>): DefaultChannelResolution {
+  const readiness = readChannelReadiness(config);
+  const qualifying = readiness.filter((entry) => entry.enabled && entry.destination !== null);
+  if (qualifying.length === 1) {
+    const only = qualifying[0]!;
+    return {
+      kind: 'resolved',
+      channel: only.channel,
+      destination: only.destination!,
+      reason: 'the only channel that is switched on and has a destination configured',
+    };
+  }
+  if (qualifying.length === 0) return { kind: 'none', candidates: readiness };
+  return { kind: 'ambiguous', candidates: qualifying };
+}