@pellux/goodvibes-tui 1.24.2 → 1.26.0

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/handlers/index.ts

@@ -56,10 +56,6 @@ export interface DaemonHandlerSurfaceProviders {
   readonly registerInbox: (ctx: HandlerContext, routing: RoutingRegistration) => Unregister;
   /** channels.drafts.* */
   readonly registerDrafts: SurfaceRegister;
-  /** calendar.* */
-  readonly registerCalendar: SurfaceRegister;
-  /** email.* */
-  readonly registerEmail: SurfaceRegister;
   /** remote.peers.* — supplies the host DistributedRuntimeRouteService + dispatch adapter. */
   readonly registerRemote: (ctx: HandlerContext) => RemoteSurfaceRegistration;
 }
@@ -82,8 +78,13 @@ export function registerDaemonHandlers(
 
   teardowns.push(providers.registerInbox(ctx, routing));
   teardowns.push(providers.registerDrafts(ctx));
-  teardowns.push(providers.registerCalendar(ctx));
-  teardowns.push(providers.registerEmail(ctx));
+  // calendar.* and email.* are NOT registered here any more. Both are served
+  // by the SDK (control-plane/routes/{calendar,email}.ts over the platform
+  // CalDAV/Google and IMAP/SMTP implementations), registered through
+  // registerGatewayVerbGroups in runtime/services.ts. This product used to
+  // carry its own handlers for the same descriptor ids and, registering later,
+  // won — two implementations behind one path, which is the drift the hoist
+  // exists to end.
 
   const remote = providers.registerRemote(ctx);
   teardowns.push(remote.unregister);

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 };
+}

package/src/daemon/send/command.ts

@@ -0,0 +1,332 @@
+/**
+ * command.ts — `goodvibes-daemon send`, the shell's way to put a message on one
+ * of the owner's channels.
+ *
+ * ## Why this exists
+ *
+ * Nothing on this machine could send the owner a message from a script. The
+ * three binaries exposed no send verb, the daemon's HTTP API answers
+ * `401 AUTH_REQUIRED` to the operator token as stored, and driving the agent to
+ * do it failed with `Missing Telegram bot token` — because the credential lives
+ * in the DAEMON tier (`~/.goodvibes/daemon/settings.json`) and the agent was
+ * reading its own surface silo. So the one process that could always send was
+ * the daemon, and only while it was running.
+ *
+ * ## Three properties this command is built around
+ *
+ * 1. **It uses the delivery path, it is not a second sender.** Everything below
+ *    ends in `ChannelDeliveryRouter.deliver()` — the same call
+ *    `AutomationDeliveryManager.sendTarget` makes, reaching the same
+ *    per-surface strategies in `strategies-core.ts`. Nothing here talks to a
+ *    provider API directly.
+ *
+ * 2. **It never exits 0 on a send that did not happen.** The router throws with
+ *    the provider's own error text and that error is printed and exits non-zero.
+ *    `AutomationDeliveryManager.deliverText` was the alternative entry point and
+ *    was NOT used, deliberately: it returns an empty array when a feature gate
+ *    is off and returns failed attempts rather than throwing, so a caller that
+ *    did not inspect its result would report success for a message that never
+ *    left the machine — the exact false-green this command exists to avoid. The
+ *    gate check it would have done is done here instead, explicitly, and a gate
+ *    that is off produces a refusal naming the settings key rather than silence.
+ *
+ * 3. **Every message it sends arrives as literal text.** The body is passed
+ *    through `inertBodyFor` for the target surface before it reaches the router,
+ *    and there is no flag, env var or code path that skips that. The message
+ *    normally comes from the operator's own shell, but the command must not
+ *    become the way something else's text — a log line, a captured error, a
+ *    remote agent's output piped in — arrives on the owner's phone rendered as
+ *    live markup with a clickable link in it. See inert-text.ts.
+ */
+
+import type { ConfigManager } from '../../config/index.ts';
+import type { ChannelDeliveryRequest } from '@pellux/goodvibes-sdk/platform/channels';
+import { getMissingSurfaceFeatureFlags, surfaceFeatureGateSettingsKeys } from '../../runtime/surface-feature-flags.ts';
+import { findSendChannel, readChannelReadiness, resolveDefaultChannel, SEND_CHANNELS, type SendChannel } from './channels.ts';
+import { describeSendFailure } from './failure-text.ts';
+import { inertBodyFor } from './inert-text.ts';
+
+/** What the router needs to actually send; injected so tests never reach the network. */
+export type SendDeliver = (request: ChannelDeliveryRequest) => Promise<string | undefined>;
+
+export interface SendCommandDeps {
+  /** Built with a `homeDir` so the daemon tier overlays — see channels.ts. */
+  readonly configManager: Pick<ConfigManager, 'get'>;
+  readonly deliver: SendDeliver;
+  /** Reads the whole of stdin; only called when no message argument was given. */
+  readonly readStdin: () => Promise<string>;
+  /** Whether stdin is a terminal. A TTY means there is no piped message to wait for. */
+  readonly stdinIsTty: boolean;
+  /** Injected so the run id in the delivery request is deterministic under test. */
+  readonly newRunId?: (() => string) | undefined;
+}
+
+export interface SendCommandResult {
+  readonly lines: readonly string[];
+  readonly exitCode: number;
+}
+
+interface ParsedSendArgs {
+  readonly channel: string | null;
+  readonly to: string | null;
+  readonly title: string | null;
+  readonly list: boolean;
+  readonly help: boolean;
+  readonly words: readonly string[];
+  readonly errors: readonly string[];
+}
+
+const USAGE = [
+  'Usage: goodvibes-daemon send [OPTIONS] [MESSAGE...]',
+  '',
+  'Send a message to one of your configured channels. With no MESSAGE, the',
+  'message is read from stdin, so this composes with other tooling.',
+  '',
+  'Options:',
+  '      --channel <id>   Channel to send to. With none named, your configured',
+  '                       channel is used and the output says which one.',
+  '      --to <address>   Where within that channel: an ntfy topic, a Telegram chat',
+  '                       id, a Slack or Mattermost channel id, a Matrix room id.',
+  '                       Without it the channel\'s configured destination is used.',
+  '      --title <text>   Title for channels that show one (ntfy).',
+  '      --list           Show every channel, whether it is on, and where it sends.',
+  '  -h, --help           Print this help',
+  '',
+  'A channel that is switched off is refused by name and NOTHING is sent — the',
+  'command never quietly falls back to the default, so a message meant for a',
+  'quiet channel cannot end up on a noisy one.',
+  '',
+  'The message is always delivered as literal text: markup a channel would',
+  'otherwise render — a Discord masked link, a Slack mention — arrives inert.',
+].join('\n');
+
+function parseSendArgs(argv: readonly string[]): ParsedSendArgs {
+  let channel: string | null = null;
+  let to: string | null = null;
+  let title: string | null = null;
+  let list = false;
+  let help = false;
+  const words: string[] = [];
+  const errors: string[] = [];
+  let optionsEnded = false;
+
+  const takeValue = (flag: string, value: string | undefined): string | null => {
+    if (value === undefined || value.length === 0) {
+      errors.push(`${flag} needs a value.`);
+      return null;
+    }
+    return value;
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index]!;
+    if (optionsEnded) { words.push(arg); continue; }
+    // Everything after `--` is message text, so a message that starts with a
+    // dash is still sendable.
+    if (arg === '--') { optionsEnded = true; continue; }
+    if (arg === '-h' || arg === '--help') { help = true; continue; }
+    if (arg === '--list') { list = true; continue; }
+    if (arg === '--channel' || arg === '-c') { channel = takeValue(arg, argv[++index]); continue; }
+    if (arg.startsWith('--channel=')) { channel = takeValue('--channel', arg.slice('--channel='.length)); continue; }
+    if (arg === '--to') { to = takeValue(arg, argv[++index]); continue; }
+    if (arg.startsWith('--to=')) { to = takeValue('--to', arg.slice('--to='.length)); continue; }
+    if (arg === '--title') { title = takeValue(arg, argv[++index]); continue; }
+    if (arg.startsWith('--title=')) { title = takeValue('--title', arg.slice('--title='.length)); continue; }
+    if (arg.startsWith('-') && arg.length > 1) {
+      errors.push(`Unknown option: ${arg}`);
+      continue;
+    }
+    words.push(arg);
+  }
+  return { channel, to, title, list, help, words, errors };
+}
+
+/**
+ * The channels that are actually usable right now, named. Every refusal ends
+ * with this: telling someone their channel is not configured without telling
+ * them which ones are just moves the guessing to them.
+ */
+function describeConfiguredChannels(config: Pick<ConfigManager, 'get'>): string {
+  const usable = readChannelReadiness(config)
+    .filter((entry) => entry.enabled && entry.destination !== null)
+    .map((entry) => entry.channel.id);
+  return usable.length > 0
+    ? `Configured and ready: ${usable.join(', ')}.`
+    : 'No channel is currently both switched on and given a destination — run: goodvibes-daemon send --list';
+}
+
+function renderChannelList(config: Pick<ConfigManager, 'get'>): string[] {
+  const readiness = readChannelReadiness(config);
+  const idWidth = Math.max(...SEND_CHANNELS.map((channel) => channel.id.length), 7);
+  const lines = ['Channels goodvibes-daemon send can reach:', ''];
+  for (const entry of readiness) {
+    const state = entry.enabled ? 'on ' : 'off';
+    const destination = entry.destination ?? `not set (${entry.channel.destinationKey})`;
+    lines.push(`  ${entry.channel.id.padEnd(idWidth)}  ${state}  ${entry.channel.addressLabel}: ${destination}`);
+  }
+  lines.push('');
+  lines.push('Override any channel\'s destination for one message with --to <address>.');
+  lines.push('');
+  const resolution = resolveDefaultChannel(config);
+  if (resolution.kind === 'resolved') {
+    lines.push(`Default with no --channel: ${resolution.channel.id} (${resolution.reason}).`);
+  } else if (resolution.kind === 'none') {
+    lines.push('There is no default: no channel is both switched on and given a destination.');
+  } else {
+    const names = resolution.candidates.map((entry) => entry.channel.id).join(', ');
+    lines.push(`There is no default: ${names} all qualify, so --channel is required.`);
+  }
+  return lines;
+}
+
+/** Refusals that must happen before anything is sent, in the order they matter. */
+function checkChannelUsable(
+  config: Pick<ConfigManager, 'get'>,
+  channel: SendChannel,
+): readonly string[] {
+  if (config.get(channel.enabledKey) !== true) {
+    // No fallback to the default channel, deliberately. Falling back is how a
+    // message meant for a quiet channel lands on a noisy one, and how a caller
+    // that named a channel because it mattered never finds out it was ignored.
+    return [
+      `${channel.label} is switched off, so nothing was sent.`,
+      `Switch it on with: goodvibes surfaces enable ${channel.id}   (settings key ${channel.enabledKey})`,
+      describeConfiguredChannels(config),
+    ];
+  }
+  // The same capability gates the daemon's own delivery honours. Checked here
+  // rather than left to AutomationDeliveryManager, which answers a disabled
+  // gate with an empty result and no reason.
+  const missing = getMissingSurfaceFeatureFlags(config, channel.id);
+  if (missing.length > 0) {
+    return [
+      `${channel.label} is switched on but the capabilities delivery needs are off, so nothing was sent.`,
+      `Turn these settings on: ${surfaceFeatureGateSettingsKeys(missing).join(', ')}`,
+      describeConfiguredChannels(config),
+    ];
+  }
+  return [];
+}
+
+export async function runSendCommand(
+  argv: readonly string[],
+  deps: SendCommandDeps,
+): Promise<SendCommandResult> {
+  const parsed = parseSendArgs(argv);
+  if (parsed.errors.length > 0) {
+    return { lines: [...parsed.errors, '', USAGE], exitCode: 2 };
+  }
+  if (parsed.help) return { lines: [USAGE], exitCode: 0 };
+  if (parsed.list) return { lines: renderChannelList(deps.configManager), exitCode: 0 };
+
+  // --- which channel -------------------------------------------------------
+  let channel: SendChannel;
+  let usedDefault = false;
+  let defaultReason = '';
+  if (parsed.channel !== null) {
+    const named = findSendChannel(parsed.channel);
+    if (!named) {
+      return {
+        lines: [
+          `Unknown channel: ${parsed.channel}`,
+          `Known channels: ${SEND_CHANNELS.map((entry) => entry.id).join(', ')}`,
+          describeConfiguredChannels(deps.configManager),
+        ],
+        exitCode: 2,
+      };
+    }
+    channel = named;
+  } else {
+    const resolution = resolveDefaultChannel(deps.configManager);
+    if (resolution.kind === 'none') {
+      return {
+        lines: [
+          'No channel was named and none is configured to be the default, so nothing was sent.',
+          'A channel qualifies when it is switched on AND has a destination set.',
+          '',
+          ...renderChannelList(deps.configManager),
+        ],
+        exitCode: 2,
+      };
+    }
+    if (resolution.kind === 'ambiguous') {
+      return {
+        lines: [
+          `No channel was named and more than one qualifies (${resolution.candidates.map((entry) => entry.channel.id).join(', ')}), so nothing was sent.`,
+          'Name one with --channel <id> rather than have this command guess which of your channels to message.',
+        ],
+        exitCode: 2,
+      };
+    }
+    channel = resolution.channel;
+    usedDefault = true;
+    defaultReason = resolution.reason;
+  }
+
+  // --- what to send --------------------------------------------------------
+  let message = parsed.words.join(' ');
+  if (message.trim().length === 0) {
+    if (deps.stdinIsTty) {
+      return {
+        lines: ['No message given. Pass it as an argument or pipe it on stdin.', '', USAGE],
+        exitCode: 2,
+      };
+    }
+    message = (await deps.readStdin()).replace(/\n+$/, '');
+  }
+  if (message.trim().length === 0) {
+    return { lines: ['The message was empty, so nothing was sent.'], exitCode: 2 };
+  }
+
+  const refusal = checkChannelUsable(deps.configManager, channel);
+  if (refusal.length > 0) return { lines: refusal, exitCode: 1 };
+
+  // --- send ----------------------------------------------------------------
+  const runId = deps.newRunId?.() ?? `cli-send-${Date.now().toString(36)}`;
+  const title = parsed.title ?? 'GoodVibes';
+  const body = inertBodyFor(channel.surfaceKind, message);
+  const request: ChannelDeliveryRequest = {
+    target: {
+      kind: 'surface',
+      surfaceKind: channel.surfaceKind,
+      ...(parsed.to === null ? {} : { address: parsed.to }),
+      label: title,
+    },
+    body,
+    title,
+    jobId: 'goodvibes-daemon-send',
+    runId,
+    // A message typed at a shell has no artifacts and no control-plane session
+    // to link back to; a link appended here would point at a page the reader
+    // did not ask for.
+    includeLinks: false,
+  };
+
+  const preamble = usedDefault
+    ? [`No channel named — using ${channel.id}: ${defaultReason}.`]
+    : [];
+  try {
+    const responseId = await deps.deliver(request);
+    return {
+      lines: [
+        ...preamble,
+        `Sent to ${channel.label}${responseId ? ` (${responseId})` : ''}.`,
+      ],
+      exitCode: 0,
+    };
+  } catch (error) {
+    // The provider's own words, not a paraphrase: "Missing Telegram chat id"
+    // and "HTTP 401: Unauthorized" are different problems with different fixes,
+    // and flattening them into "delivery failed" is what makes a failed send
+    // take an hour to diagnose. See failure-text.ts for what is stripped
+    // (credentials) and what is deliberately kept (everything else).
+    return {
+      lines: [
+        ...preamble,
+        `Sending to ${channel.label} failed, so the message did NOT go out.`,
+        describeSendFailure(error),
+      ],
+      exitCode: 1,
+    };
+  }
+}