@pellux/goodvibes-agent 1.5.5 → 1.5.6

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

@@ -1,9 +1,51 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { AgentCalendarRegistry } from '../../agent/calendar-registry.ts';
 import { parseIcs } from '../../agent/ics-calendar.ts';
+import { parseIcs as parseIcsHonest } from '@pellux/goodvibes-sdk/platform/calendar';
 import type { CommandContext, CommandRegistry } from '../command-registry.ts';
 import { parseAgentLocalLibraryArgs } from './agent-local-library-args.ts';
 import { requireShellPaths } from './runtime-services.ts';
+import {
+  CALENDAR_SUBSCRIPTION_VERBS,
+  renderSubscribedSection,
+  runCalendarSubscriptionCommand,
+  subscriptionRegistryForRead,
+} from './calendar-subscription-runtime.ts';
+import {
+  fetchProviderUpcoming,
+  runCalendarAccounts,
+  runCalendarConnect,
+  runCalendarDisconnect,
+  sourceLabel,
+} from './calendar-connect-runtime.ts';
+
+/** Today's date as 'YYYY-MM-DD' (UTC), for windowed occurrence expansion. */
+function todayIsoDate(): string {
+  return new Date().toISOString().slice(0, 10);
+}
+
+function addDaysIsoDate(days: number): string {
+  return new Date(Date.now() + days * 86_400_000).toISOString().slice(0, 10);
+}
+
+/** Append the merged, source-labeled subscribed section to a local-events block. */
+function withSubscribedSection(localBlock: string, subscribed: string): string {
+  return subscribed ? `${localBlock}\n\n${subscribed}` : localBlock;
+}
+
+/**
+ * F7b: the old unknown-subcommand usage line was one 13-verb run-on
+ * ("list|upcoming ...|connect ...|disconnect ...|accounts|import ...|export
+ * ...|add ...|delete ...|subscribe ...|unsubscribe ...|subscriptions|refresh
+ * ..."), unreadable at a glance. Grouped by what each verb is FOR instead.
+ */
+const CALENDAR_USAGE_MESSAGE = [
+  'Usage: /calendar <command>',
+  '  Viewing         list | upcoming [--days N]',
+  '  Connecting      connect <google|outlook> [--device] | disconnect <google|outlook> | accounts',
+  '  Subscriptions   subscribe <ics-url> [--name N] [--every MIN] [--yes] | unsubscribe <name> --yes | subscriptions | refresh [name]',
+  '  Local events    add --title <title> --start <ISO> --yes | delete <id> --yes | import <path> [--yes] | export [--dest <path>] [--yes]',
+].join('\n');
 
 const CALENDAR_VALUE_FLAGS = ['title', 'start', 'end', 'location', 'notes', 'dest', 'path', 'days'] as const;
 
@@ -43,15 +85,40 @@ function renderEventList(events: readonly Parameters<typeof formatEventLine>[0][
   ].join('\n');
 }
 
-export function runCalendarRuntimeCommand(args: readonly string[], ctx: CommandContext): void {
+export async function runCalendarRuntimeCommand(args: readonly string[], ctx: CommandContext): Promise<void> {
   const sub = (args[0] ?? 'list').toLowerCase();
+
+  // Connected-provider verbs (OAuth). Handled before the local-store registry so a
+  // connect/accounts call never touches the local .ics file.
+  if (sub === 'connect' || sub === 'disconnect' || sub === 'accounts') {
+    try {
+      if (sub === 'connect') await runCalendarConnect(args, ctx);
+      else if (sub === 'disconnect') await runCalendarDisconnect(args, ctx);
+      else await runCalendarAccounts(ctx);
+    } catch (error) {
+      printError(ctx, error);
+    }
+    return;
+  }
+
   const registry = registryFromContext(ctx);
+  // A read-only subscription registry merges subscribed feed events into the
+  // views below. Tolerant of a missing secret manager (seeds/occurrences read
+  // only the on-disk cache), so a failure to build it never breaks local views.
+  let subs: ReturnType<typeof subscriptionRegistryForRead> | null = null;
+  try {
+    subs = subscriptionRegistryForRead(ctx);
+  } catch {
+    subs = null;
+  }
 
   try {
     // list / upcoming
     if (sub === 'list' || sub === 'all') {
       const snap = registry.snapshot();
-      ctx.print(renderEventList([...snap.events], snap.path));
+      const local = renderEventList([...snap.events], snap.path);
+      const subscribed = subs ? renderSubscribedSection(subs.seeds()) : '';
+      ctx.print(withSubscribedSection(local, subscribed));
       return;
     }
 
@@ -60,7 +127,24 @@ export function runCalendarRuntimeCommand(args: readonly string[], ctx: CommandC
       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));
+      const local = renderEventList([...events], snap.path);
+      // A9's subscribed-feed section (ics-feed source), merged read-only.
+      const subscribed = subs ? renderSubscribedSection(subs.occurrencesInWindow(todayIsoDate(), addDaysIsoDate(days))) : '';
+      // A10: connected-provider events (google-api / microsoft-graph), best-effort.
+      const now = new Date();
+      const to = new Date(now.getTime() + days * 24 * 60 * 60 * 1000);
+      const { events: providerEvents, notes } = await fetchProviderUpcoming(ctx, {
+        timeMin: now.toISOString(),
+        timeMax: to.toISOString(),
+      });
+      const providerLines = providerEvents.map((e) =>
+        `  [${sourceLabel(e.source)}] ${e.start.value.slice(0, 16).replace('T', ' ')}  ${e.summary}${e.calendarLabel ? `  (${e.calendarLabel})` : ''}`,
+      );
+      const providerBlock = providerEvents.length > 0
+        ? [`Connected calendars (${providerEvents.length})`, ...providerLines].join('\n')
+        : '';
+      const notesBlock = notes.length > 0 ? ['Notes', ...notes].join('\n') : '';
+      ctx.print([withSubscribedSection(local, subscribed), providerBlock, notesBlock].filter(Boolean).join('\n\n'));
       return;
     }
 
@@ -90,12 +174,21 @@ export function runCalendarRuntimeCommand(args: readonly string[], ctx: CommandC
         return;
       }
       const { imported, skipped, secretSkipped } = registry.importIcs(content);
+      // Honest recurrence/skip report from the SDK reader: events the local store
+      // could not use, and recurring events whose RRULE this build does not fully
+      // expand (imported as a single seed, never silently dropped or mis-expanded).
+      const honest = parseIcsHonest(content);
+      const unsupportedRecurring = honest.events.filter((e) => e.recurrence?.expansion === 'unsupported');
       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.` : '',
+        honest.skipped.length > 0 ? `Could not parse ${honest.skipped.length} entr${honest.skipped.length === 1 ? 'y' : 'ies'}: ${honest.skipped[0]?.message ?? ''}` : '',
+        unsupportedRecurring.length > 0
+          ? `${unsupportedRecurring.length} recurring event${unsupportedRecurring.length === 1 ? '' : 's'} imported as a single date only (recurrence not fully expanded): ${unsupportedRecurring.slice(0, 3).map((e) => e.summary).join(', ')}${unsupportedRecurring.length > 3 ? ', ...' : ''}`
+          : '',
       ].filter(Boolean).join('\n'));
       return;
     }
@@ -169,6 +262,11 @@ export function runCalendarRuntimeCommand(args: readonly string[], ctx: CommandC
         ctx.print('Usage: /calendar delete <id> --yes');
         return;
       }
+      if (id.startsWith('sub:')) {
+        const subName = id.split(':')[1] ?? 'a subscription';
+        ctx.print(`Cannot delete ${id}: it is a read-only event from the '${subName}' subscription. Edit it in the source calendar, or run /calendar unsubscribe ${subName} --yes to remove the whole feed.`);
+        return;
+      }
       if (!parsed.yes) {
         const event = registry.get(id);
         if (!event) {
@@ -189,7 +287,7 @@ export function runCalendarRuntimeCommand(args: readonly string[], ctx: CommandC
       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]');
+    ctx.print(CALENDAR_USAGE_MESSAGE);
   } catch (error) {
     printError(ctx, error);
   }
@@ -199,11 +297,16 @@ export function registerCalendarRuntimeCommands(registry: CommandRegistry): void
   registry.register({
     name: 'calendar',
     aliases: ['cal'],
-    description: 'Manage local calendar events',
+    description: 'Manage local calendar events, external calendar subscriptions, and connected calendar accounts',
     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]',
+    usage: '[list|upcoming [--days N]|connect <google|outlook> [--device]|disconnect <google|outlook>|accounts|import <path> [--yes]|export [--dest <path>] [--yes]|add --title <title> --start <ISO> [--end <ISO>] [--location <loc>] [--notes <notes>] --yes|delete <id> --yes|subscribe <ics-url> [--name N] [--every MIN] [--yes]|unsubscribe <name> --yes|subscriptions|refresh [name]]',
     handler: async (args: readonly string[], ctx: CommandContext) => {
-      runCalendarRuntimeCommand(args, ctx);
+      const sub = (args[0] ?? 'list').toLowerCase();
+      if (CALENDAR_SUBSCRIPTION_VERBS.has(sub)) {
+        await runCalendarSubscriptionCommand(sub, args.slice(1), ctx);
+        return;
+      }
+      await runCalendarRuntimeCommand(args, ctx);
     },
   });
 }

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

@@ -0,0 +1,225 @@
+import {
+  CalendarSubscriptionRegistry,
+  createHttpFeedFetcher,
+  type SubscribedOccurrence,
+  type SubscriptionStatus,
+  type SubscriptionSecretStore,
+} from '../../agent/calendar-subscription-registry.ts';
+import type { FeedFetcher } from '@pellux/goodvibes-sdk/platform/calendar';
+import type { CommandContext } from '../command-registry.ts';
+import { parseAgentLocalLibraryArgs } from './agent-local-library-args.ts';
+import { requireShellPaths } from './runtime-services.ts';
+
+/**
+ * External-calendar SUBSCRIPTION verbs for /calendar — the no-OAuth read path
+ * (W4-A9). Subscriptions are iCalendar feeds (Google secret address, Outlook
+ * published .ics, or any .ics URL). The parse/RRULE/fetch-status engine is the
+ * SDK's platform/calendar; this file is the /calendar command surface over the
+ * agent-side CalendarSubscriptionRegistry.
+ *
+ * A feed URL is secrets-adjacent (a Google secret address grants read access),
+ * so it is only ever stored through the secret manager and shown masked; the
+ * subscribe verb refuses to run without a secret manager present.
+ */
+
+const SUBSCRIPTION_VALUE_FLAGS = ['name', 'every'] as const;
+export const CALENDAR_SUBSCRIPTION_VERBS = new Set(['subscribe', 'unsubscribe', 'subscriptions', 'subs', 'refresh']);
+
+/** A no-op secret store for the read-only merged view, where no secret is ever read. */
+const READ_ONLY_SECRET_STUB: SubscriptionSecretStore = {
+  get: async () => null,
+  set: async () => { throw new Error('read-only'); },
+};
+
+function secretStoreFrom(ctx: CommandContext): SubscriptionSecretStore | null {
+  const sm = ctx.platform.secretsManager;
+  if (!sm) return null;
+  return sm as unknown as SubscriptionSecretStore;
+}
+
+/**
+ * Build a registry for a WRITE/network verb — requires a secret manager. Returns
+ * null (and the caller prints the honest reason) when none is available.
+ */
+export function subscriptionRegistryForWrite(ctx: CommandContext, fetcher?: FeedFetcher): CalendarSubscriptionRegistry | null {
+  const secrets = secretStoreFrom(ctx);
+  if (!secrets) return null;
+  return CalendarSubscriptionRegistry.create(requireShellPaths(ctx), secrets, fetcher ?? createHttpFeedFetcher());
+}
+
+/** Build a registry for the READ-ONLY merged view — tolerant of a missing secret manager. */
+export function subscriptionRegistryForRead(ctx: CommandContext): CalendarSubscriptionRegistry {
+  const secrets = secretStoreFrom(ctx) ?? READ_ONLY_SECRET_STUB;
+  return CalendarSubscriptionRegistry.create(requireShellPaths(ctx), secrets, createHttpFeedFetcher());
+}
+
+function parseArgs(args: readonly string[]) {
+  return parseAgentLocalLibraryArgs(args, { valueFlags: SUBSCRIPTION_VALUE_FLAGS });
+}
+
+function formatHealth(s: SubscriptionStatus): string {
+  const base = `${s.health}`;
+  return s.detail ? `${base} — ${s.detail}` : base;
+}
+
+/** Render the subscribed-events section merged into /calendar list & upcoming. */
+export function renderSubscribedSection(occurrences: readonly SubscribedOccurrence[]): string {
+  if (occurrences.length === 0) return '';
+  const lines = occurrences.map((o) => {
+    const when = o.allDay ? o.start : o.start.slice(0, 16).replace('T', ' ');
+    const loc = o.location ? `  at ${o.location}` : '';
+    const marker = o.recurrenceNotFullyExpanded ? '  [recurrence not fully expanded]' : '';
+    return `  [${o.subscription}] ${when}  ${o.title}${loc}${marker}  (read-only)`;
+  });
+  return [`Subscribed calendar events (${occurrences.length})`, ...lines].join('\n');
+}
+
+/**
+ * Handle a subscription verb. Returns true if it handled the sub-command (so the
+ * caller's local-store path is skipped).
+ */
+export async function runCalendarSubscriptionCommand(
+  sub: string,
+  args: readonly string[],
+  ctx: CommandContext,
+  /** Injectable for tests — production callers pass undefined and get the real HTTP fetcher. */
+  fetcher?: FeedFetcher,
+): Promise<boolean> {
+  if (!CALENDAR_SUBSCRIPTION_VERBS.has(sub)) return false;
+
+  if (sub === 'subscribe') {
+    await handleSubscribe(args, ctx, fetcher);
+    return true;
+  }
+  if (sub === 'unsubscribe') {
+    await handleUnsubscribe(args, ctx, fetcher);
+    return true;
+  }
+  if (sub === 'subscriptions' || sub === 'subs') {
+    await handleList(ctx, fetcher);
+    return true;
+  }
+  if (sub === 'refresh') {
+    await handleRefresh(args, ctx, fetcher);
+    return true;
+  }
+  return false;
+}
+
+function requireRegistry(ctx: CommandContext, fetcher: FeedFetcher | undefined, action: string): CalendarSubscriptionRegistry | null {
+  const registry = subscriptionRegistryForWrite(ctx, fetcher);
+  if (!registry) {
+    ctx.print(`Cannot ${action}: no secret manager is available in this runtime, and feed URLs are stored only as secrets.`);
+    return null;
+  }
+  return registry;
+}
+
+async function handleSubscribe(args: readonly string[], ctx: CommandContext, fetcher?: FeedFetcher): Promise<void> {
+  const parsed = parseArgs(args);
+  const url = parsed.rest[0] ?? parsed.flags.get('url');
+  if (!url) {
+    ctx.print('Usage: /calendar subscribe <ics-url> [--name <name>] [--every <minutes>] [--yes]');
+    return;
+  }
+  const requestedName = parsed.flags.get('name')?.trim() || undefined;
+  const everyMin = parsed.flags.has('every') ? Math.max(15, parseInt(parsed.flags.get('every') ?? '', 10) || 60) : undefined;
+  const refreshIntervalMs = everyMin !== undefined ? everyMin * 60_000 : undefined;
+
+  const registry = requireRegistry(ctx, fetcher, 'subscribe');
+  if (!registry) return;
+
+  // Consent-at-add preview: validate by fetching and state exactly what will be
+  // fetched and how often, before anything is saved.
+  if (!parsed.yes) {
+    const check = await registry.validate(url, requestedName);
+    if (!check.ok) {
+      ctx.print([`Subscription preview failed at the ${check.stage} stage.`, `  ${check.detail}`].join('\n'));
+      return;
+    }
+    const intervalMin = Math.round((refreshIntervalMs ?? 60 * 60_000) / 60_000);
+    ctx.print([
+      'Calendar subscription preview',
+      `  calendar ${check.calendarName ?? '(unnamed feed)'}`,
+      `  name     ${check.derivedName}`,
+      `  events   ${check.eventCount} found`,
+      `  refresh  every ${intervalMin} min (read-only; the feed URL is stored as a secret)`,
+      '  This will fetch the calendar from the URL you provided, now and on each refresh.',
+      '  rerun with --yes to subscribe',
+    ].join('\n'));
+    return;
+  }
+
+  const result = await registry.subscribe(url, requestedName, refreshIntervalMs);
+  if (!result.ok) {
+    ctx.print([`Could not subscribe (${result.stage}).`, `  ${result.detail}`].join('\n'));
+    return;
+  }
+  const intervalMin = Math.round(result.refreshIntervalMs / 60_000);
+  ctx.print([
+    `Subscribed to '${result.name}'.`,
+    `  events   ${result.eventCount} loaded`,
+    `  refresh  every ${intervalMin} min — run /calendar refresh to update now`,
+    '  These events are read-only and appear source-labeled in /calendar list.',
+  ].join('\n'));
+}
+
+async function handleUnsubscribe(args: readonly string[], ctx: CommandContext, fetcher?: FeedFetcher): Promise<void> {
+  const parsed = parseArgs(args);
+  const name = parsed.rest.join(' ').trim() || parsed.flags.get('name')?.trim();
+  if (!name) {
+    ctx.print('Usage: /calendar unsubscribe <name> [--yes]');
+    return;
+  }
+  const registry = requireRegistry(ctx, fetcher, 'unsubscribe');
+  if (!registry) return;
+  if (!parsed.yes) {
+    ctx.print([`Unsubscribe preview`, `  name ${name}`, '  This removes the subscription, its cached events, and its stored feed URL.', '  rerun with --yes to unsubscribe'].join('\n'));
+    return;
+  }
+  const removed = await registry.unsubscribe(name);
+  ctx.print(removed ? `Unsubscribed from '${name}'.` : `No subscription named '${name}'.`);
+}
+
+async function handleList(ctx: CommandContext, fetcher?: FeedFetcher): Promise<void> {
+  const registry = subscriptionRegistryForWrite(ctx, fetcher) ?? subscriptionRegistryForRead(ctx);
+  const statuses = await registry.statuses();
+  if (statuses.length === 0) {
+    ctx.print(['Calendar subscriptions', '  None. Add one with /calendar subscribe <ics-url> --yes'].join('\n'));
+    return;
+  }
+  ctx.print([
+    `Calendar subscriptions (${statuses.length})`,
+    ...statuses.map((s) => [
+      `  ${s.name}`,
+      `    url     ${s.maskedUrl}`,
+      `    status  ${formatHealth(s)}`,
+      `    events  ${s.eventCount}`,
+      `    refresh every ${Math.round(s.refreshIntervalMs / 60_000)} min`,
+    ].join('\n')),
+  ].join('\n'));
+}
+
+async function handleRefresh(args: readonly string[], ctx: CommandContext, fetcher?: FeedFetcher): Promise<void> {
+  const parsed = parseArgs(args);
+  const name = parsed.rest.join(' ').trim() || undefined;
+  const registry = requireRegistry(ctx, fetcher, 'refresh subscriptions');
+  if (!registry) return;
+  if (!registry.hasAny()) {
+    ctx.print('No calendar subscriptions to refresh. Add one with /calendar subscribe <ics-url> --yes');
+    return;
+  }
+  const outcomes = await registry.refresh(name, { force: true });
+  if (outcomes.length === 0) {
+    ctx.print(name ? `No subscription named '${name}'.` : 'No calendar subscriptions to refresh.');
+    return;
+  }
+  ctx.print([
+    `Refreshed ${outcomes.length} subscription${outcomes.length === 1 ? '' : 's'}`,
+    ...outcomes.map((o) => {
+      const detail = o.detail ? ` — ${o.detail}` : '';
+      const count = o.eventCount !== undefined ? ` (${o.eventCount} events)` : '';
+      return `  ${o.name}: ${o.outcome}${count}${detail}`;
+    }),
+  ].join('\n'));
+}

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

@@ -61,6 +61,93 @@ function getConfigManager(ctx: CommandContext): { get: (key: string) => unknown
   return ctx.platform.configManager as unknown as { get: (key: string) => unknown };
 }
 
+/** Config manager surface needed to persist one email field. Matches ctx.platform.configManager. */
+export interface EmailConfigManagerLike {
+  get: (key: string) => unknown;
+  setDynamic: (key: string, value: unknown) => void;
+}
+
+/**
+ * SecretsManager surface needed to store the raw password. The real
+ * ctx.platform.secretsManager (SDK SecretsManager) has more methods;
+ * persistSecretBackedConfigValue is called through an opaque cast, matching
+ * the existing /email set pattern.
+ */
+export interface EmailSecretsManagerLike {
+  readonly get: (key: string) => Promise<string | null>;
+}
+
+export interface PersistEmailConfigFieldResult {
+  readonly ok: boolean;
+  readonly error?: string;
+  readonly configKey?: string;
+  /** Set only for the passwordRef field — the stored goodvibes:// reference (never the raw value). */
+  readonly secretRef?: string;
+}
+
+/**
+ * Persist one `email.<field>` config value through the single reviewed path:
+ * non-secret fields go through cm.setDynamic after per-field validation; the
+ * password field (fieldName 'passwordRef', rawValue is the RAW password) is
+ * routed through persistSecretBackedConfigValue so only a goodvibes:// secret
+ * reference ever reaches settings.json. Never logs or returns the raw value.
+ *
+ * Reused by both the /email set CLI subcommand (handleSet, below) and the
+ * Agent workspace connect wizard editor — one persistence path, no fork.
+ */
+export async function persistEmailConfigField(
+  cm: EmailConfigManagerLike,
+  secretsManager: EmailSecretsManagerLike,
+  fieldName: string,
+  rawValue: string,
+): Promise<PersistEmailConfigFieldResult> {
+  if (!KNOWN_EMAIL_FIELDS.has(fieldName)) {
+    return { ok: false, error: `Unknown email config key: ${fieldName}` };
+  }
+  const configKey = `email.${fieldName}`;
+
+  if (fieldName === 'passwordRef') {
+    const storedRef = await persistSecretBackedConfigValue(
+      cm as unknown as Parameters<typeof persistSecretBackedConfigValue>[0],
+      secretsManager as unknown as Parameters<typeof persistSecretBackedConfigValue>[1],
+      configKey as unknown as ConfigKey,
+      rawValue,
+      { scope: 'user' },
+    );
+    return { ok: true, configKey, secretRef: storedRef };
+  }
+
+  let coerced: unknown = rawValue;
+  if (fieldName === 'imapPort' || fieldName === 'smtpPort') {
+    const n = parseInt(rawValue, 10);
+    if (!isFinite(n) || n < 1 || n > 65535) {
+      return { ok: false, error: `Invalid port number: ${rawValue}. Must be an integer between 1 and 65535.`, configKey };
+    }
+    coerced = n;
+  } else if (fieldName === 'smtpSecurity') {
+    if (rawValue !== 'tls' && rawValue !== 'starttls' && rawValue !== 'auto') {
+      return {
+        ok: false,
+        error: `Invalid smtpSecurity value: "${rawValue}". Valid values: tls, starttls, auto.`,
+        configKey,
+      };
+    }
+    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 {
+      return { ok: false, error: `Invalid boolean value: ${rawValue}. Use true or false.`, configKey };
+    }
+  }
+
+  cm.setDynamic(configKey, coerced);
+  return { ok: true, configKey };
+}
+
 function buildEmailService(ctx: CommandContext): EmailService {
   const secretsManager = requireSecretsManager(ctx);
   const cm = getConfigManager(ctx);
@@ -247,58 +334,31 @@ async function handleSet(
     }
 
     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' },
-    );
+    const result = await persistEmailConfigField(cm, secretsManager, fieldName, rawValue);
+    if (!result.ok) {
+      ctx.print(result.error ?? `Could not store ${configKey}.`);
+      return;
+    }
     cm.save();
     ctx.print(
       `Email config updated\n` +
       `  key:  ${configKey}\n` +
-      `  value: [stored as secret; reference: ${storedRef.slice(0, 40)}...]\n` +
+      `  value: [stored as secret; reference: ${(result.secretRef ?? '').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;
-    }
+  // Non-secret path: coerce, validate, and persist through the shared field helper
+  const secretsManager = requireSecretsManager(ctx);
+  const result = await persistEmailConfigField(cm, secretsManager, fieldName, rawValue);
+  if (!result.ok) {
+    ctx.print(result.error ?? `Could not update ${configKey}.`);
+    return;
   }
 
-  cm.setDynamic(configKey as unknown as ConfigKey, coerced);
   cm.save();
-  ctx.print(`Email config updated\n  key:   ${configKey}\n  value: ${String(coerced)}`);
+  ctx.print(`Email config updated\n  key:   ${configKey}\n  value: ${String(cm.get(configKey))}`);
 }
 
 async function handleSend(

package/src/input/commands/knowledge.ts

@@ -128,7 +128,7 @@ function requireAgentKnowledgeAsk(context: CommandContext): ((input: KnowledgeAs
 
 export const knowledgeCommand: SlashCommand = {
   name: 'knowledge',
-  aliases: ['know', 'kb'],
+  aliases: ['know'],
   description: 'Agent Knowledge: isolated Agent-owned status, ask/search, source/node/issue lists, item lookup, map, connectors, ingest, and review queue.',
   hidden: true,
   usage: '<subcommand> [args]',

package/src/input/commands/network-scan-runtime.ts

@@ -0,0 +1,75 @@
+import type { CommandRegistry } from '../command-registry.ts';
+import { requireShellPaths } from './runtime-services.ts';
+import { GOODVIBES_AGENT_SURFACE_ROOT } from '../../config/surface.ts';
+import {
+  discoveredProvidersFilePath,
+  loadLanScanConsent,
+  saveLanScanConsent,
+  NETWORK_SCAN_DISABLE_COMMAND,
+  NETWORK_SCAN_ENABLE_COMMAND,
+} from '../../runtime/lan-scan-consent.ts';
+
+function statusText(storePath: string, decision: ReturnType<typeof loadLanScanConsent>): string {
+  if (!decision || decision.decision === 'declined') {
+    return [
+      'Local network scanning: off',
+      '  What it would do   Check other devices on your local network (your subnet only — nothing beyond it) for model servers such as Ollama or LM Studio.',
+      `  What it stores     Found servers would be saved to ${storePath}.`,
+      `  Turn it on         ${NETWORK_SCAN_ENABLE_COMMAND}`,
+    ].join('\n');
+  }
+  return [
+    'Local network scanning: on',
+    `  Turned on           ${decision.decidedAt}`,
+    '  What it does        Checks other devices on your local network (your subnet only — nothing beyond it) for model servers such as Ollama or LM Studio, each time the agent starts.',
+    `  What it stores      Found servers are saved to ${storePath}.`,
+    '  See discovered      /provider',
+    `  Turn it off         ${NETWORK_SCAN_DISABLE_COMMAND}`,
+  ].join('\n');
+}
+
+/**
+ * /network-scan — the consent + status surface for the Phase-8 LAN provider
+ * discovery scan (see src/runtime/lan-scan-consent.ts). Declining or never
+ * deciding is a first-class, fully supported path: the scan simply never
+ * runs until this command turns it on.
+ */
+export function registerNetworkScanRuntimeCommands(registry: CommandRegistry): void {
+  registry.register({
+    name: 'network-scan',
+    aliases: ['discover-lan'],
+    description: 'Turn local-network scanning for model servers on or off, or check its status',
+    usage: '[on|off|status]',
+    argsHint: '[on|off|status]',
+    handler(args, ctx) {
+      const shellPaths = requireShellPaths(ctx);
+      const storePath = discoveredProvidersFilePath(shellPaths, GOODVIBES_AGENT_SURFACE_ROOT);
+      const sub = (args[0] ?? 'status').toLowerCase();
+
+      if (sub === 'status' || sub === '') {
+        ctx.print(statusText(storePath, loadLanScanConsent(shellPaths, GOODVIBES_AGENT_SURFACE_ROOT)));
+        return;
+      }
+
+      if (sub === 'on' || sub === 'enable') {
+        saveLanScanConsent(shellPaths, GOODVIBES_AGENT_SURFACE_ROOT, 'granted');
+        ctx.print(
+          'Local network scanning is now on. Starting next launch, the agent will check other devices on your ' +
+          `local network (your subnet only) for model servers such as Ollama or LM Studio, and save what it finds to ${storePath}. ` +
+          'Run /provider to see discovered servers. Turn it off anytime with /network-scan off.',
+        );
+        return;
+      }
+
+      if (sub === 'off' || sub === 'disable') {
+        saveLanScanConsent(shellPaths, GOODVIBES_AGENT_SURFACE_ROOT, 'declined');
+        ctx.print(
+          `Local network scanning is now off. Nothing on your network will be probed. Turn it back on anytime with ${NETWORK_SCAN_ENABLE_COMMAND}.`,
+        );
+        return;
+      }
+
+      ctx.print(`Usage: /network-scan [on|off|status]\n${statusText(storePath, loadLanScanConsent(shellPaths, GOODVIBES_AGENT_SURFACE_ROOT))}`);
+    },
+  });
+}