@pellux/goodvibes-agent 1.4.4 → 1.5.1

package/src/input/commands/calendar-runtime.ts

@@ -0,0 +1,209 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { AgentCalendarRegistry } from '../../agent/calendar-registry.ts';
+import { parseIcs } from '../../agent/ics-calendar.ts';
+import type { CommandContext, CommandRegistry } from '../command-registry.ts';
+import { parseAgentLocalLibraryArgs } from './agent-local-library-args.ts';
+import { requireShellPaths } from './runtime-services.ts';
+
+const CALENDAR_VALUE_FLAGS = ['title', 'start', 'end', 'location', 'notes', 'dest', 'path', 'days'] as const;
+
+function parseCalendarArgs(args: readonly string[]) {
+  return parseAgentLocalLibraryArgs(args, { valueFlags: CALENDAR_VALUE_FLAGS });
+}
+
+function registryFromContext(ctx: CommandContext): AgentCalendarRegistry {
+  return AgentCalendarRegistry.fromShellPaths(requireShellPaths(ctx));
+}
+
+function printError(ctx: CommandContext, error: unknown): void {
+  ctx.print([
+    'Error',
+    `  message ${error instanceof Error ? error.message : String(error)}`,
+  ].join('\n'));
+}
+
+function formatEventLine(e: { readonly id: string; readonly title: string; readonly start: string; readonly end?: string; readonly allDay: boolean; readonly location?: string }): string {
+  const when = e.allDay ? e.start : e.start.slice(0, 16).replace('T', ' ');
+  const loc = e.location ? `  at ${e.location}` : '';
+  return `  ${e.id}  ${when}  ${e.title}${loc}`;
+}
+
+function renderEventList(events: readonly Parameters<typeof formatEventLine>[0][], path: string): string {
+  if (events.length === 0) {
+    return [
+      'Local calendar events',
+      `  store ${path}`,
+      '  No events yet. Add one with /calendar add --title <title> --start <ISO> --yes',
+    ].join('\n');
+  }
+  return [
+    `Local calendar events (${events.length})`,
+    `  store ${path}`,
+    ...events.map(formatEventLine),
+  ].join('\n');
+}
+
+export function runCalendarRuntimeCommand(args: readonly string[], ctx: CommandContext): void {
+  const sub = (args[0] ?? 'list').toLowerCase();
+  const registry = registryFromContext(ctx);
+
+  try {
+    // list / upcoming
+    if (sub === 'list' || sub === 'all') {
+      const snap = registry.snapshot();
+      ctx.print(renderEventList([...snap.events], snap.path));
+      return;
+    }
+
+    if (sub === 'upcoming') {
+      const parsed = parseCalendarArgs(args.slice(1));
+      const days = parsed.flags.has('days') ? Math.max(1, parseInt(parsed.flags.get('days') ?? '7', 10) || 7) : 7;
+      const snap = registry.snapshot();
+      const events = registry.upcoming(days);
+      ctx.print(renderEventList([...events], snap.path));
+      return;
+    }
+
+    // import <path> [--yes]
+    if (sub === 'import') {
+      const parsed = parseCalendarArgs(args.slice(1));
+      const filePath = parsed.rest[0] ?? parsed.flags.get('path');
+      if (!filePath) {
+        ctx.print('Usage: /calendar import <path-to-ics> [--yes]');
+        return;
+      }
+      if (!existsSync(filePath)) {
+        ctx.print(`File not found: ${filePath}`);
+        return;
+      }
+      const content = readFileSync(filePath, 'utf-8');
+      if (!parsed.yes) {
+        const preview = parseIcs(content);
+        ctx.print([
+          'Calendar import preview',
+          `  file ${filePath}`,
+          `  events found ${preview.length}`,
+          ...preview.slice(0, 5).map((e) => `  - ${e.summary} (${e.dtstart})`),
+          preview.length > 5 ? `  ... and ${preview.length - 5} more` : '',
+          '  rerun with --yes to import',
+        ].filter(Boolean).join('\n'));
+        return;
+      }
+      const { imported, skipped, secretSkipped } = registry.importIcs(content);
+      ctx.print([
+        `Imported ${imported.length} event${imported.length === 1 ? '' : 's'} from ${filePath}`,
+        ...imported.slice(0, 10).map((e) => `  ${e.id}  ${e.start}  ${e.title}`),
+        imported.length > 10 ? `  ... and ${imported.length - 10} more` : '',
+        skipped > 0 ? `Skipped ${skipped} event${skipped === 1 ? '' : 's'} that already exist.` : '',
+        secretSkipped > 0 ? `Skipped ${secretSkipped} event${secretSkipped === 1 ? '' : 's'} for safety.` : '',
+      ].filter(Boolean).join('\n'));
+      return;
+    }
+
+    // export [--dest <path>] [--yes]
+    if (sub === 'export') {
+      const parsed = parseCalendarArgs(args.slice(1));
+      const dest = parsed.flags.get('dest') ?? parsed.rest[0];
+      if (!parsed.yes) {
+        const events = registry.list();
+        ctx.print([
+          'Calendar export preview',
+          `  events ${events.length}`,
+          dest ? `  dest ${dest}` : '  output to stdout (no --dest given)',
+          '  rerun with --yes to export',
+        ].join('\n'));
+        return;
+      }
+      const ics = registry.exportIcs(undefined, dest);
+      if (!dest) {
+        ctx.print(ics);
+      } else {
+        ctx.print(`Exported calendar to ${dest}`);
+      }
+      return;
+    }
+
+    // add --title <title> --start <ISO> [--end <ISO>] [--location <loc>] [--notes <notes>] --yes
+    if (sub === 'add' || sub === 'create') {
+      const parsed = parseCalendarArgs(args.slice(1));
+      const title = parsed.flags.get('title')?.trim() ?? parsed.rest.join(' ').trim();
+      const start = parsed.flags.get('start')?.trim();
+      if (!title || !start) {
+        ctx.print('Usage: /calendar add --title <title> --start <ISO-date-or-datetime> [--end <ISO>] [--location <loc>] [--notes <notes>] --yes');
+        return;
+      }
+      if (!parsed.yes) {
+        ctx.print([
+          'Calendar event preview',
+          `  title ${title}`,
+          `  start ${start}`,
+          parsed.flags.get('end') ? `  end   ${parsed.flags.get('end')}` : '',
+          parsed.flags.get('location') ? `  location ${parsed.flags.get('location')}` : '',
+          parsed.flags.get('notes') ? `  notes ${parsed.flags.get('notes')}` : '',
+          '  rerun with --yes to save',
+        ].filter(Boolean).join('\n'));
+        return;
+      }
+      const event = registry.create({
+        title,
+        start,
+        end: parsed.flags.get('end')?.trim(),
+        location: parsed.flags.get('location')?.trim(),
+        notes: parsed.flags.get('notes')?.trim(),
+      });
+      ctx.print([
+        `Added calendar event ${event.id}`,
+        `  id    ${event.id}`,
+        `  title ${event.title}`,
+        `  start ${event.start}`,
+        event.end ? `  end   ${event.end}` : '',
+      ].filter(Boolean).join('\n'));
+      return;
+    }
+
+    // delete <id> --yes
+    if (sub === 'delete' || sub === 'remove') {
+      const parsed = parseCalendarArgs(args.slice(1));
+      const id = parsed.rest[0];
+      if (!id) {
+        ctx.print('Usage: /calendar delete <id> --yes');
+        return;
+      }
+      if (!parsed.yes) {
+        const event = registry.get(id);
+        if (!event) {
+          ctx.print(`Unknown calendar event ${id}`);
+          return;
+        }
+        ctx.print([
+          `Delete calendar event preview`,
+          `  id    ${event.id}`,
+          `  title ${event.title}`,
+          `  start ${event.start}`,
+          '  rerun with --yes to delete',
+        ].join('\n'));
+        return;
+      }
+      const removed = registry.delete(id);
+      ctx.print(`Deleted calendar event ${removed.id}  ${removed.title}`);
+      return;
+    }
+
+    ctx.print('Usage: /calendar [list|upcoming [--days N]|import <path> [--yes]|export [--dest <path>] [--yes]|add --title <title> --start <ISO> --yes|delete <id> --yes]');
+  } catch (error) {
+    printError(ctx, error);
+  }
+}
+
+export function registerCalendarRuntimeCommands(registry: CommandRegistry): void {
+  registry.register({
+    name: 'calendar',
+    aliases: ['cal'],
+    description: 'Manage local calendar events',
+    hidden: true,
+    usage: '[list|upcoming [--days N]|import <path> [--yes]|export [--dest <path>] [--yes]|add --title <title> --start <ISO> [--end <ISO>] [--location <loc>] [--notes <notes>] --yes|delete <id> --yes]',
+    handler: async (args: readonly string[], ctx: CommandContext) => {
+      runCalendarRuntimeCommand(args, ctx);
+    },
+  });
+}

package/src/input/commands/channels-runtime.ts

@@ -378,6 +378,7 @@ export function registerChannelsRuntimeCommands(registry: CommandRegistry): void
     name: 'channels',
     aliases: ['channel'],
     description: 'Inspect Agent channel readiness or send an explicitly confirmed delivery message',
+    hidden: true,
     usage: '[list|readiness|ready|attention|triage [limit]|guide [id]|show <id>|deliveries [limit]|send --channel <id> --message <text> --yes|accounts|policies|status|doctor <id>|setup <id>]',
     argsHint: 'list|readiness|ready|attention|triage|guide|show|deliveries|send|accounts|policies|status|doctor|setup',
     async handler(args, ctx) {

package/src/input/commands/command-error.ts

@@ -0,0 +1,9 @@
+/**
+ * summarizeCommandError - format a thrown value into a plain-language message
+ * suitable for printing directly to the conversation. Matches the style used
+ * by routines, personas, and vibe (short prefix + colon + reason).
+ */
+export function summarizeCommandError(error: unknown): string {
+  const reason = error instanceof Error ? error.message : String(error);
+  return `Command failed: ${reason}`;
+}

package/src/input/commands/compat-runtime.ts

@@ -9,6 +9,7 @@ export function registerCompatRuntimeCommands(registry: CommandRegistry): void {
     name: 'compat',
     aliases: ['compatibility'],
     description: 'Inspect connected-host compatibility and Agent Knowledge route readiness',
+    hidden: true,
     usage: '[--json]',
     argsHint: '[--json]',
     async handler(args, ctx) {

package/src/input/commands/config.ts

@@ -5,6 +5,7 @@ export function registerConfigCommand(registry: CommandRegistry): void {
     name: 'config',
     aliases: ['cfg'],
     description: 'Open the fullscreen configuration workspace',
+    hidden: true,
     usage: '[category|key]',
     argsHint: '[category|key]',
     handler(args, ctx) {

package/src/input/commands/conversation-runtime.ts

@@ -79,7 +79,6 @@ function buildComposerReview(ctx: CommandContext): string[] {
   const composer = deriveComposerState({
     text: '',
     commandMode: false,
-    panelFocused: false,
     pendingApproval: session.pendingApproval,
     hasAttachments: false,
     turnState: session.turnState,
@@ -137,6 +136,7 @@ export function registerConversationRuntimeCommands(registry: CommandRegistry):
     name: 'conversation',
     aliases: ['transcript', 'composer'],
     description: 'Review conversation structure, transcript hotspots, and composer posture',
+    hidden: true,
     usage: '[review|events [kind]|groups [kind]|hotspots|composer|find <query> [kind]|next [kind]|prev [kind]|restore]',
     handler(args, ctx) {
       const sub = (args[0] ?? 'review').toLowerCase();

package/src/input/commands/delegation-runtime.ts

@@ -93,12 +93,10 @@ function buildDelegationBody(input: DelegationCommandInput): string {
 }
 
 export function registerDelegationRuntimeCommands(registry: CommandRegistry): void {
-  const makeHandler = (defaultReview: boolean) => async (args: string[], ctx: CommandContext): Promise<void> => {
-    const input = parseDelegationArgs(args, defaultReview);
+  const makeHandler = () => async (args: string[], ctx: CommandContext): Promise<void> => {
+    const input = parseDelegationArgs(args, false);
     if (!input.task) {
-      ctx.print(defaultReview
-        ? 'Usage: /delegate --review [--reason <why>] [--success <evidence>] [--workspace <hint>] [--priority <priority>] <build/fix/review task>'
-        : 'Usage: /delegate [--review] [--reason <why>] [--success <evidence>] [--workspace <hint>] [--priority <priority>] <build/fix/review task>');
+      ctx.print('Usage: /delegate [--review] [--reason <why>] [--success <evidence>] [--workspace <hint>] [--priority <priority>] <build/fix/review task>');
       return;
     }
     const operator = ctx.clients?.operator;
@@ -183,8 +181,9 @@ export function registerDelegationRuntimeCommands(registry: CommandRegistry): vo
     name: 'delegate',
     aliases: ['build'],
     description: 'Explicitly delegate build/fix/review work to GoodVibes TUI through shared-session routes',
+    hidden: true,
     usage: '[--review] [--reason <why>] [--success <evidence>] [--workspace <hint>] [--priority <priority>] <task>',
     argsHint: '[--review] [--reason <why>] [--success <evidence>] [--workspace <hint>] [--priority <priority>] <task>',
-    handler: makeHandler(false),
+    handler: makeHandler(),
   });
 }

package/src/input/commands/email-runtime.ts

@@ -0,0 +1,387 @@
+/**
+ * /email command — direct email access via IMAP/SMTP.
+ *
+ * Subcommands:
+ *   status                                        Show config readiness (redacted, no secrets)
+ *   config                                        Show current email config (keys redacted)
+ *   set <key> <value> [--yes]                     Set an email config key; --yes required for passwordRef
+ *   check [n]                                     List up to n unread inbox summaries (default 10);
+ *                                                  includes a 2-line body preview of the newest message
+ *   send <to> <subject words> -- <body words> --yes  Send a plain-text email; preview without --yes
+ *
+ * Settable keys:
+ *   email.enabled, email.imapHost, email.imapPort, email.smtpHost, email.smtpPort,
+ *   email.smtpSecurity, email.username, email.passwordRef (requires --yes), email.fromAddress
+ *
+ * Safety policy:
+ *   - All inbox reads use EXAMINE (read-only); unread status is never modified.
+ *   - Sending requires explicit --yes; previews are shown without it.
+ *   - No credential values are ever printed; passwordRef is displayed as [configured].
+ *   - email.passwordRef is always stored as a goodvibes:// secret reference; the raw value
+ *     is passed to SecretsManager and never written to settings.json.
+ */
+
+import type { CommandRegistry } from '../command-registry.ts';
+import type { CommandContext } from '../command-registry.ts';
+import { requireYesFlag, stripYesFlag } from './confirmation.ts';
+import {
+  EmailService,
+  readEmailConfig,
+  validateEmailConfig,
+  ensureEmailConfigDefaults,
+} from '../../agent/email/email-service.ts';
+import { requireSecretsManager } from './runtime-services.ts';
+import type { ConfigKey } from '../../config/index.ts';
+import { persistSecretBackedConfigValue } from '../../config/secret-config.ts';
+
+/**
+ * Whitelist of settable email config fields (without the 'email.' prefix).
+ * Reject any key not in this set to prevent accidental writes to unknown paths.
+ */
+const KNOWN_EMAIL_FIELDS = new Set([
+  'enabled',
+  'imapHost',
+  'imapPort',
+  'smtpHost',
+  'smtpPort',
+  'smtpSecurity',
+  'username',
+  'passwordRef',
+  'fromAddress',
+]);
+
+function readLimitArg(arg: string | undefined, fallback: number): number {
+  if (!arg) return fallback;
+  const n = parseInt(arg, 10);
+  return isFinite(n) && n > 0 ? Math.min(n, 100) : fallback;
+}
+
+function getConfigManager(ctx: CommandContext): { get: (key: string) => unknown } {
+  ensureEmailConfigDefaults(ctx.platform.configManager);
+  return ctx.platform.configManager as unknown as { get: (key: string) => unknown };
+}
+
+function buildEmailService(ctx: CommandContext): EmailService {
+  const secretsManager = requireSecretsManager(ctx);
+  const cm = getConfigManager(ctx);
+  return new EmailService({
+    getConfig: (key: string) => cm.get(key),
+    secretsManager,
+  });
+}
+
+function formatStatus(ctx: CommandContext): void {
+  const cm = getConfigManager(ctx);
+  const config = readEmailConfig((key) => cm.get(key));
+  const errors = validateEmailConfig(config);
+  const lines = [
+    'Email Status',
+    `  enabled: ${config.enabled ? 'yes' : 'no'}`,
+    `  imap: ${config.imapHost || '[not set]'}:${config.imapPort}`,
+    `  smtp: ${config.smtpHost || '[not set]'}:${config.smtpPort}`,
+    `  username: ${config.username || '[not set]'}`,
+    `  password: ${config.passwordRef ? '[configured]' : '[missing]'}`,
+    `  from: ${config.fromAddress || '[not set]'}`,
+    `  ready: ${errors.length === 0 && config.enabled ? 'yes' : 'no'}`,
+  ];
+  if (errors.length > 0) {
+    lines.push(`  issues (${errors.length}):`);
+    for (const err of errors) lines.push(`    - ${err}`);
+  }
+  lines.push('  policy: credentials are never printed; passwordRef displays as [configured]');
+  lines.push('  Usage: /email set email.<key> <value> [--yes] — see /email config');
+  ctx.print(lines.join('\n'));
+}
+
+async function handleCheck(
+  args: readonly string[],
+  ctx: CommandContext,
+): Promise<void> {
+  const limit = readLimitArg(args[0], 10);
+  const service = buildEmailService(ctx);
+  const summaries = await service.checkInbox(limit);
+
+  if (summaries.length === 0) {
+    ctx.print('Inbox: no unread messages.');
+    return;
+  }
+
+  const lines = [
+    `Inbox: ${summaries.length} unread message${summaries.length !== 1 ? 's' : ''}`,
+    '  policy: read-only; messages are not marked read',
+  ];
+  for (let i = 0; i < summaries.length; i += 1) {
+    const msg = summaries[i];
+    if (!msg) continue;
+    lines.push(`  ${i + 1}. from=${msg.from || '(unknown)'} subject=${msg.subject || '(none)'} date=${msg.date || '(none)'}`);
+  }
+
+  // Wire in body preview for the newest message (MIN-2)
+  const newest = summaries[0];
+  if (newest?.bodyPreview) {
+    const preview = newest.bodyPreview
+      .split('\n')
+      .map((l) => l.trim())
+      .filter((l) => l.length > 0)
+      .slice(0, 2)
+      .join(' … ');
+    if (preview) lines.push(`  preview: ${preview}`);
+  }
+
+  ctx.print(lines.join('\n'));
+}
+
+/**
+ * Parse send args with optional body separator.
+ * Format: <to> <subject words...> [-- <body words...>]
+ * Returns { to, subject, body } or null if to/subject are missing.
+ */
+function parseSendArgs(args: readonly string[]): { to: string; subject: string; body: string } | null {
+  const to = args[0];
+  if (!to) return null;
+
+  const rest = args.slice(1);
+  const sepIdx = rest.indexOf('--');
+
+  let subjectParts: string[];
+  let bodyParts: string[];
+
+  if (sepIdx === -1) {
+    subjectParts = rest;
+    bodyParts = [];
+  } else {
+    subjectParts = rest.slice(0, sepIdx);
+    bodyParts = rest.slice(sepIdx + 1);
+  }
+
+  const subject = subjectParts.join(' ').trim();
+  if (!subject) return null;
+
+  const body = bodyParts.join(' ').trim();
+  return { to, subject, body };
+}
+
+function formatConfig(ctx: CommandContext): void {
+  const cm = getConfigManager(ctx);
+  const config = readEmailConfig((key) => cm.get(key));
+  const lines = [
+    'Email Config',
+    `  email.enabled:       ${String(config.enabled)}`,
+    `  email.imapHost:      ${config.imapHost || '[not set]'}`,
+    `  email.imapPort:      ${config.imapPort}`,
+    `  email.smtpHost:      ${config.smtpHost || '[not set]'}`,
+    `  email.smtpPort:      ${config.smtpPort}`,
+    `  email.smtpSecurity:  ${config.smtpSecurity} (tls|starttls|auto)`,
+    `  email.username:      ${config.username || '[not set]'}`,
+    `  email.passwordRef:   ${config.passwordRef ? '[configured]' : '[not set]'}`,
+    `  email.fromAddress:   ${config.fromAddress || '[not set]'}`,
+    '',
+    '  Settable keys: email.enabled, email.imapHost, email.imapPort, email.smtpHost,',
+    '                 email.smtpPort, email.smtpSecurity, email.username,',
+    '                 email.passwordRef (--yes required), email.fromAddress',
+    '  Usage: /email set email.<key> <value> [--yes]',
+  ];
+  ctx.print(lines.join('\n'));
+}
+
+async function handleSet(
+  args: readonly string[],
+  ctx: CommandContext,
+): Promise<void> {
+  const parsed = stripYesFlag(args);
+  const rawArgs = [...parsed.rest];
+
+  const rawKey = rawArgs[0];
+  const rawValue = rawArgs.slice(1).join(' ');
+
+  if (!rawKey) {
+    ctx.print(
+      'Usage: /email set email.<key> <value> [--yes]\n' +
+      'Keys: email.enabled, email.imapHost, email.imapPort, email.smtpHost,\n' +
+      '      email.smtpPort, email.username, email.passwordRef (--yes required),\n' +
+      '      email.fromAddress',
+    );
+    return;
+  }
+
+  // Accept both "email.imapHost" and "imapHost" forms
+  const fieldName = rawKey.startsWith('email.') ? rawKey.slice('email.'.length) : rawKey;
+  const configKey = `email.${fieldName}`;
+
+  if (!KNOWN_EMAIL_FIELDS.has(fieldName)) {
+    ctx.print(
+      `Unknown email config key: ${rawKey}\n` +
+      'Valid keys: email.enabled, email.imapHost, email.imapPort, email.smtpHost,\n' +
+      '            email.smtpPort, email.username, email.passwordRef (--yes required),\n' +
+      '            email.fromAddress',
+    );
+    return;
+  }
+
+  if (rawValue === '') {
+    ctx.print(`Usage: /email set ${configKey} <value>\nValue is required.`);
+    return;
+  }
+
+  // Ensure the email section exists in the config manager before any writes
+  ensureEmailConfigDefaults(ctx.platform.configManager);
+  const cm = ctx.platform.configManager as unknown as {
+    get: (key: string) => unknown;
+    setDynamic: (key: string, value: unknown) => void;
+    save: () => void;
+  };
+
+  if (fieldName === 'passwordRef') {
+    // Secret path: --yes is required; raw value is routed through SecretsManager
+    if (!parsed.yes) {
+      const lines = [
+        'Email Password Set Preview',
+        `  key: ${configKey}`,
+        '  value: [redacted — raw password will be stored as a secure secret]',
+        '  policy: the raw password is never written to settings.json; only a',
+        '          goodvibes:// reference is stored there',
+      ];
+      ctx.print(lines.join('\n'));
+      requireYesFlag(ctx, 'set email.passwordRef secret', '/email set email.passwordRef <password> --yes');
+      return;
+    }
+
+    const secretsManager = requireSecretsManager(ctx);
+    const configKeyTyped = configKey as unknown as ConfigKey;
+    const storedRef = await persistSecretBackedConfigValue(
+      cm as unknown as Parameters<typeof persistSecretBackedConfigValue>[0],
+      secretsManager,
+      configKeyTyped,
+      rawValue,
+      { scope: 'user' },
+    );
+    cm.save();
+    ctx.print(
+      `Email config updated\n` +
+      `  key:  ${configKey}\n` +
+      `  value: [stored as secret; reference: ${storedRef.slice(0, 40)}...]\n` +
+      '  policy: raw password stored in secrets manager; settings.json contains only the goodvibes:// ref',
+    );
+    return;
+  }
+
+  // Non-secret path: coerce value and persist
+  let coerced: unknown = rawValue;
+  if (fieldName === 'imapPort' || fieldName === 'smtpPort') {
+    const n = parseInt(rawValue, 10);
+    if (!isFinite(n) || n < 1 || n > 65535) {
+      ctx.print(`Invalid port number: ${rawValue}. Must be an integer between 1 and 65535.`);
+      return;
+    }
+    coerced = n;
+  } else if (fieldName === 'smtpSecurity') {
+    // MIN-2: validate at set time so invalid values never reach the socket factory
+    if (rawValue !== 'tls' && rawValue !== 'starttls' && rawValue !== 'auto') {
+      ctx.print(
+        `Invalid smtpSecurity value: "${rawValue}".\n` +
+        'Valid values: tls (direct TLS, e.g. port 465), starttls (STARTTLS upgrade, e.g. port 587), auto (port-based default).',
+      );
+      return;
+    }
+    coerced = rawValue;
+  } else if (fieldName === 'enabled') {
+    const lower = rawValue.toLowerCase();
+    if (lower === 'true' || lower === '1' || lower === 'yes') {
+      coerced = true;
+    } else if (lower === 'false' || lower === '0' || lower === 'no') {
+      coerced = false;
+    } else {
+      ctx.print(`Invalid boolean value: ${rawValue}. Use true or false.`);
+      return;
+    }
+  }
+
+  cm.setDynamic(configKey as unknown as ConfigKey, coerced);
+  cm.save();
+  ctx.print(`Email config updated\n  key:   ${configKey}\n  value: ${String(coerced)}`);
+}
+
+async function handleSend(
+  args: readonly string[],
+  ctx: CommandContext,
+): Promise<void> {
+  const parsed = stripYesFlag(args);
+  const remaining = [...parsed.rest];
+
+  const sendArgs = parseSendArgs(remaining);
+  if (!sendArgs) {
+    ctx.print('Usage: /email send <to> <subject words...> [-- <body words...>] --yes\nRecipient and subject are required.');
+    return;
+  }
+
+  const { to, subject, body } = sendArgs;
+
+  if (!parsed.yes) {
+    const lines = [
+      'Email Send Preview',
+      `  to: ${to}`,
+      `  subject: ${subject}`,
+      `  body: ${body || '(empty)'}`,
+      '  policy: this is a preview; rerun with --yes to send',
+    ];
+    ctx.print(lines.join('\n'));
+    requireYesFlag(ctx, `send email to ${to}`, `/email send ${to} ${subject}${body ? ` -- ${body}` : ''} --yes`);
+    return;
+  }
+
+  const service = buildEmailService(ctx);
+  await service.sendMail({
+    to,
+    subject,
+    body,
+    confirm: true,
+  });
+  ctx.print(`Email sent to ${to} with subject "${subject}"`);
+}
+
+export function registerEmailRuntimeCommands(registry: CommandRegistry): void {
+  registry.register({
+    name: 'email',
+    aliases: [],
+    description: 'Direct IMAP/SMTP email: configure, check inbox, or send a confirmed message',
+    hidden: true,
+    usage: 'status | config | set <key> <value> [--yes] | check [n] | send <to> <subject...> [-- <body...>] --yes',
+    argsHint: 'status|config|set|check|send',
+    async handler(args, ctx) {
+      const sub = (args[0] ?? 'status').trim().toLowerCase();
+
+      try {
+        if (sub === 'status') {
+          formatStatus(ctx);
+          return;
+        }
+
+        if (sub === 'config') {
+          formatConfig(ctx);
+          return;
+        }
+
+        if (sub === 'set') {
+          await handleSet(args.slice(1), ctx);
+          return;
+        }
+
+        if (sub === 'check') {
+          await handleCheck(args.slice(1), ctx);
+          return;
+        }
+
+        if (sub === 'send') {
+          await handleSend(args.slice(1), ctx);
+          return;
+        }
+
+        ctx.print('Usage: /email status | config | set <key> <value> [--yes] | check [n] | send <to> <subject...> [-- <body...>] --yes');
+      } catch (err) {
+        // MIN-3: print config/validation errors as plain language, never a raw exception
+        const msg = err instanceof Error ? err.message : String(err);
+        ctx.print(`Email error: ${msg}`);
+      }
+    },
+  });
+}