@pellux/goodvibes-daemon 1.28.0

package/src/cluster/daemon-ws-call.ts

@@ -0,0 +1,235 @@
+/**
+ * daemon-ws-call.ts — invoking a verb that has no REST binding.
+ *
+ * Most control-plane verbs answer on a plain HTTP path and `callDaemonVerb` in
+ * @pellux/goodvibes-terminal-shell is all a subcommand needs. Some do not: the
+ * `sessions.hosted.*` family is declared ws-only in the method catalog (no
+ * `http` binding at all), because a hosted session's whole point is the event
+ * stream that comes with it. A GET against a path they do not have returns 404,
+ * which reads exactly like an out-of-date daemon.
+ *
+ * So this is the second half of the SAME convention: the target is resolved by
+ * `resolveRemoteDaemonTarget` (the --host/--port/--token flags, defaulting to
+ * this machine), the credential is the same operator token, and only the
+ * transport differs. Nothing here knows what any verb MEANS.
+ *
+ * The frames are the ones the operator contract declares for
+ * `/api/control-plane/ws`:
+ *   -> {"type":"auth","token":"…"}          <- {"type":"auth","ok":true,…}
+ *   -> {"type":"call","id":"…","methodId":"…","body":{…}}
+ *                                            <- {"type":"response","id":"…","ok":…,"status":…,"body":…}
+ *
+ * The Authorization header is sent on the upgrade as well as in the auth frame.
+ * The daemon requires it on the upgrade (an unauthenticated upgrade is a 401
+ * before any frame is read) and re-reads it from the frame; sending both is
+ * what makes one connection work for both checks.
+ */
+import type { DaemonVerbOutcome, RemoteDaemonTarget } from '@pellux/goodvibes-terminal-shell';
+
+/** How long a single verb call may take, upgrade included. */
+export const DAEMON_WS_TIMEOUT_MS = 15_000;
+
+/**
+ * The socket shape this module uses.
+ *
+ * Narrower than the platform `WebSocket` on purpose: a test double has no
+ * business implementing `binaryType`, `extensions` or the EventTarget surface,
+ * and requiring them would push every test into a cast.
+ */
+export interface DaemonWebSocket {
+  send(data: string): void;
+  close(): void;
+  onopen: ((event: unknown) => void) | null;
+  onmessage: ((event: { data: unknown }) => void) | null;
+  onerror: ((event: unknown) => void) | null;
+  onclose: ((event: unknown) => void) | null;
+}
+
+export type DaemonWebSocketFactory = (
+  url: string,
+  init: { readonly headers: Readonly<Record<string, string>> },
+) => DaemonWebSocket;
+
+/** The real one. Bun's WebSocket takes headers on the constructor; browsers' does not. */
+const realWebSocketFactory: DaemonWebSocketFactory = (url, init) =>
+  new WebSocket(url, init as unknown as string[]) as unknown as DaemonWebSocket;
+
+export interface CallDaemonWsVerbOptions {
+  readonly body?: unknown;
+  readonly timeoutMs?: number | undefined;
+  /** Injected in tests so nothing opens a socket. */
+  readonly socketFactory?: DaemonWebSocketFactory | undefined;
+}
+
+function wsUrlFor(baseUrl: string): string {
+  return `${baseUrl.replace(/^http/, 'ws')}/api/control-plane/ws`;
+}
+
+interface ParsedFrame {
+  readonly type?: unknown;
+  readonly ok?: unknown;
+  readonly id?: unknown;
+  readonly status?: unknown;
+  readonly body?: unknown;
+  readonly error?: unknown;
+}
+
+function parseFrame(data: unknown): ParsedFrame | null {
+  const text = typeof data === 'string'
+    ? data
+    : data instanceof Uint8Array
+      ? new TextDecoder().decode(data)
+      : null;
+  if (text === null) return null;
+  try {
+    const parsed = JSON.parse(text) as unknown;
+    return parsed && typeof parsed === 'object' ? (parsed as ParsedFrame) : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Call one ws-only verb and close.
+ *
+ * One connection per call. A CLI command asks one question and exits, so a
+ * pooled connection would only be a lifetime to get wrong; the cost is one
+ * upgrade against a daemon that is, in the default case, on this machine.
+ *
+ * Every failure shape becomes an `error`/`fix` pair in the same vocabulary
+ * `callDaemonVerb` produces, so a caller renders both the same way.
+ */
+export async function callDaemonWsVerb<T>(
+  target: RemoteDaemonTarget,
+  methodId: string,
+  options: CallDaemonWsVerbOptions = {},
+): Promise<DaemonVerbOutcome<T>> {
+  const where = target.isLocal ? 'the daemon on this machine' : `the daemon at ${target.baseUrl}`;
+  const factory = options.socketFactory ?? realWebSocketFactory;
+  const timeoutMs = options.timeoutMs ?? DAEMON_WS_TIMEOUT_MS;
+  const callId = `cli-${methodId}-${Date.now()}`;
+
+  let socket: DaemonWebSocket;
+  try {
+    socket = factory(wsUrlFor(target.baseUrl), {
+      headers: { Authorization: `Bearer ${target.token}` },
+    });
+  } catch (error) {
+    return {
+      ok: false,
+      error: `could not reach ${where}`,
+      fix: target.isLocal
+        ? 'check the daemon is running: goodvibes-daemon service-status'
+        : `check that machine is reachable and its daemon is listening on ${target.baseUrl} `
+          + `(${error instanceof Error ? error.message : 'no further detail'})`,
+    };
+  }
+
+  return new Promise<DaemonVerbOutcome<T>>((resolve) => {
+    let settled = false;
+    const timer = setTimeout(() => {
+      finish({
+        ok: false,
+        error: `${where} did not answer within ${Math.round(timeoutMs / 1000)}s`,
+        fix: target.isLocal
+          ? 'check the daemon is running and not wedged: goodvibes-daemon status'
+          : 'check that machine is reachable and its daemon is not overloaded',
+      });
+    }, timeoutMs);
+
+    const finish = (outcome: DaemonVerbOutcome<T>): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      try {
+        socket.close();
+      } catch {
+        // A socket that is already gone is exactly the state we wanted.
+      }
+      resolve(outcome);
+    };
+
+    socket.onopen = (): void => {
+      socket.send(JSON.stringify({ type: 'auth', token: target.token }));
+    };
+
+    socket.onmessage = (event): void => {
+      const frame = parseFrame(event.data);
+      if (!frame) return;
+
+      if (frame.type === 'auth') {
+        if (frame.ok === true) {
+          socket.send(JSON.stringify({
+            type: 'call',
+            id: callId,
+            methodId,
+            ...(options.body === undefined ? {} : { body: options.body }),
+          }));
+          return;
+        }
+        finish({
+          ok: false,
+          error: `${where} refused the operator token`,
+          fix: target.isLocal
+            ? 'the token may be stale — restart the daemon, or pass --token'
+            : 'pass --token with the operator token from that machine (its <daemon home>/operator-tokens.json)',
+        });
+        return;
+      }
+
+      if (frame.type === 'error') {
+        finish({
+          ok: false,
+          error: typeof frame.error === 'string' ? frame.error : `${where} refused the request`,
+          fix: 'run `goodvibes-daemon status` to see what that daemon is doing',
+        });
+        return;
+      }
+
+      if (frame.type !== 'response' || frame.id !== callId) return;
+
+      if (frame.ok === true) {
+        finish({ ok: true, data: frame.body as T });
+        return;
+      }
+      const body = (frame.body ?? {}) as { error?: unknown; fix?: unknown };
+      if (frame.status === 404) {
+        finish({
+          ok: false,
+          error: `${where} does not know the verb ${methodId}`,
+          fix: 'that daemon is running a build without this capability — update it, then try again',
+        });
+        return;
+      }
+      finish({
+        ok: false,
+        error: typeof body.error === 'string' ? body.error : `${where} refused ${methodId}`,
+        fix: typeof body.fix === 'string'
+          ? body.fix
+          : 'run `goodvibes-daemon status` to see what that daemon is doing',
+      });
+    };
+
+    socket.onerror = (): void => {
+      finish({
+        ok: false,
+        error: `could not reach ${where}`,
+        fix: target.isLocal
+          ? 'check the daemon is running: goodvibes-daemon service-status'
+          : `check that machine is switched on and its daemon is listening on ${target.baseUrl}`,
+      });
+    };
+
+    socket.onclose = (): void => {
+      // A close before an answer is a refusal too — most often the upgrade
+      // itself was rejected, which happens before any frame is sent.
+      finish({
+        ok: false,
+        error: `${where} closed the connection before answering`,
+        fix: target.isLocal
+          ? 'check the daemon is running: goodvibes-daemon service-status'
+          : 'check the operator token for that machine — an upgrade with no valid token is closed immediately',
+      });
+    };
+  });
+}

package/src/cluster/raw-reply-route.ts

@@ -0,0 +1,111 @@
+/**
+ * raw-reply-route.ts — invoking a route that answers with its payload itself.
+ *
+ * `callDaemonVerb` in @pellux/goodvibes-terminal-shell reads the wrapped
+ * convention every `/api/cluster/*` route follows: `{ ok: true, data }` on
+ * success, `{ ok: false, error, fix }` on a refusal. Three routes this daemon
+ * serves do not — `/status`, `/api/health` and `/api/channels/status` answer
+ * with the payload ITSELF and put the verdict in the HTTP status. Reading one
+ * as the other is not a subtle failure: a raw payload has no `ok` field, so the
+ * wrapped reader called a perfectly healthy 200 "the daemon refused the
+ * request".
+ *
+ * So this is the second half of the SAME convention, next to daemon-ws-call.ts:
+ * the target is resolved by `resolveRemoteDaemonTarget`, the credential is the
+ * same operator token, the reachability / stale-credential / unreadable-reply
+ * refusals are the shared reader's — only the shape of a successful body
+ * differs. `rawReplyReader` restates a raw reply in the wrapped convention
+ * before the shared reader sees it, so there is one request path rather than
+ * two.
+ *
+ * Which routes are raw is stated per call, never sniffed: a payload is free to
+ * contain a field called `ok` and no sniffing rule could be honest about that.
+ */
+import { callDaemonVerb, type DaemonFetch, type DaemonVerbOutcome, type RemoteDaemonTarget } from '@pellux/goodvibes-terminal-shell';
+
+/** How a route's reply is shaped. */
+export type DaemonReplyEnvelope = 'wrapped' | 'raw';
+
+/**
+ * The status a restated reply carries.
+ *
+ * The shared reader looks at the status for exactly three verdicts — 401, 403
+ * and 404 — and those are passed through untouched below, before any body is
+ * read. Everything else it decides from the body, so a restated reply names a
+ * status that is legal to attach a body to (a 204 or a 304 is not) rather than
+ * echoing one that would make `new Response` throw.
+ */
+const RESTATED_OK = 200;
+const RESTATED_REFUSAL = 500;
+
+/**
+ * Wrap a fetch so a raw-answering route reads as a wrapped one.
+ *
+ * A reply the shared reader short-circuits on (a credential refusal, an
+ * unknown path) is handed back exactly as it arrived. A body that is not JSON
+ * is handed back unparsed, so the shared reader produces its own
+ * "reply this build could not read" refusal rather than a second wording for
+ * the same thing.
+ */
+export function rawReplyReader(target: RemoteDaemonTarget, fetchImpl: DaemonFetch = fetch): DaemonFetch {
+  const where = target.isLocal ? 'the daemon on this machine' : `the daemon at ${target.baseUrl}`;
+  return async (input, init) => {
+    const response = await fetchImpl(input, init);
+    if (response.status === 401 || response.status === 403 || response.status === 404) return response;
+
+    const text = await response.text();
+    let payload: unknown;
+    try {
+      payload = JSON.parse(text) as unknown;
+    } catch {
+      return new Response(text, { status: RESTATED_OK });
+    }
+
+    if (response.ok) {
+      return new Response(JSON.stringify({ ok: true, data: payload }), { status: RESTATED_OK });
+    }
+    const body = payload as { error?: unknown; fix?: unknown };
+    return new Response(JSON.stringify({
+      ok: false,
+      error: typeof body.error === 'string'
+        ? body.error
+        : `${where} answered ${response.status} for ${pathOf(input)}`,
+      fix: typeof body.fix === 'string'
+        ? body.fix
+        : 'run `goodvibes-daemon status` to see what that daemon is doing',
+    }), { status: RESTATED_REFUSAL });
+  };
+}
+
+/** The path portion of a request URL, for a refusal that names what was asked for. */
+function pathOf(url: string): string {
+  try {
+    return new URL(url).pathname;
+  } catch {
+    return url;
+  }
+}
+
+/**
+ * Call a daemon route, saying which envelope it answers in.
+ *
+ * `wrapped` is the shared reader unchanged. `raw` is the shared reader with the
+ * restating fetch above in front of it, so both envelopes reach the same
+ * refusals in the same words.
+ */
+export function callDaemonRoute<T>(
+  target: RemoteDaemonTarget,
+  path: string,
+  init: { method: 'GET' | 'POST'; body?: unknown; envelope?: DaemonReplyEnvelope } = { method: 'GET' },
+  fetchImpl: DaemonFetch = fetch,
+): Promise<DaemonVerbOutcome<T>> {
+  const request = init.body === undefined
+    ? { method: init.method }
+    : { method: init.method, body: init.body };
+  return callDaemonVerb<T>(
+    target,
+    path,
+    request,
+    (init.envelope ?? 'wrapped') === 'raw' ? rawReplyReader(target, fetchImpl) : fetchImpl,
+  );
+}

package/src/config/checkpoint-settings.ts

@@ -0,0 +1,113 @@
+import type { ConfigManager } from '@pellux/goodvibes-sdk/platform/config';
+
+/**
+ * Checkpoint guard settings (`checkpoints.*` namespace).
+ *
+ * The SDK's WorkspaceCheckpointManager exposes root/retention guard options that
+ * decide which directory it is safe to snapshot and how the first sweep and
+ * retention behave:
+ *
+ *   - `checkpoints.preferGitRoot` (boolean, SDK default true) — prefer the
+ *     enclosing git repository's top level over the raw working directory.
+ *   - `checkpoints.allowBroadRoot` (boolean, SDK default false) — opt in to
+ *     snapshotting a broad root (filesystem root, home directory, ~/.goodvibes).
+ *   - `checkpoints.allowLargeFirstSnapshot` (boolean, SDK default false) — opt
+ *     in to a first snapshot whose full sweep exceeds `maxFirstSnapshotFiles`.
+ *   - `checkpoints.maxFirstSnapshotFiles` (number, SDK default) — ceiling for
+ *     the first-ever snapshot's file sweep.
+ *   - `checkpoints.autoRetention` (boolean, SDK default true) — run a retention
+ *     sweep automatically after each successful create and once at init.
+ *
+ * A sixth key, `checkpoints.unregisteredWorkspaces`, is read separately by
+ * `readCheckpointRegistrationSetting` below (kept out of `CheckpointGuardSettings`
+ * because it is a daemon-owned enforcement switch, not an SDK manager
+ * constructor option, and must never be spread into the manager's options).
+ *
+ * The shared SDK config schema (GoodVibesConfig) has no `checkpoints` category,
+ * so these are read directly from a user-supplied `checkpoints` block in
+ * settings.json. The SDK ConfigManager deep-merges loaded settings onto the
+ * default config and preserves unknown top-level blocks, so a hand-added
+ * `checkpoints` object survives to `getRaw()`. Only these five passthrough keys
+ * are read here; each absent key falls back to the SDK manager's own default.
+ *
+ * settings.json example:
+ *
+ *   "checkpoints": {
+ *     "preferGitRoot": true,
+ *     "allowBroadRoot": false,
+ *     "allowLargeFirstSnapshot": false,
+ *     "maxFirstSnapshotFiles": 20000,
+ *     "autoRetention": true,
+ *     "unregisteredWorkspaces": "off"
+ *   }
+ */
+export interface CheckpointGuardSettings {
+  readonly preferGitRoot?: boolean;
+  readonly allowBroadRoot?: boolean;
+  readonly allowLargeFirstSnapshot?: boolean;
+  readonly maxFirstSnapshotFiles?: number;
+  readonly autoRetention?: boolean;
+}
+
+/**
+ * Read the `checkpoints.*` guard passthrough keys from the loaded config. Only
+ * keys present with the right primitive type are returned; everything else is
+ * omitted so the SDK manager applies its own default. `maxFirstSnapshotFiles`
+ * must be a finite positive number to be accepted.
+ */
+export function readCheckpointGuardSettings(
+  configManager: Pick<ConfigManager, 'getRaw'>,
+): CheckpointGuardSettings {
+  const raw = configManager.getRaw() as unknown as Record<string, unknown>;
+  const block = raw.checkpoints;
+  if (block === null || typeof block !== 'object' || Array.isArray(block)) return {};
+  const cp = block as Record<string, unknown>;
+
+  const out: {
+    preferGitRoot?: boolean;
+    allowBroadRoot?: boolean;
+    allowLargeFirstSnapshot?: boolean;
+    maxFirstSnapshotFiles?: number;
+    autoRetention?: boolean;
+  } = {};
+
+  if (typeof cp.preferGitRoot === 'boolean') out.preferGitRoot = cp.preferGitRoot;
+  if (typeof cp.allowBroadRoot === 'boolean') out.allowBroadRoot = cp.allowBroadRoot;
+  if (typeof cp.allowLargeFirstSnapshot === 'boolean') out.allowLargeFirstSnapshot = cp.allowLargeFirstSnapshot;
+  if (
+    typeof cp.maxFirstSnapshotFiles === 'number'
+    && Number.isFinite(cp.maxFirstSnapshotFiles)
+    && cp.maxFirstSnapshotFiles > 0
+  ) {
+    out.maxFirstSnapshotFiles = cp.maxFirstSnapshotFiles;
+  }
+  if (typeof cp.autoRetention === 'boolean') out.autoRetention = cp.autoRetention;
+
+  return out;
+}
+
+/**
+ * The registered-workspaces-only override (owner ruling, 2026-07-10):
+ *
+ *   - `checkpoints.unregisteredWorkspaces` (`'off' | 'guarded'`, default `'off'`)
+ *     — `'off'` is the ruling's default: automatic (turn-end/lifecycle)
+ *     checkpoints, and explicit checkpoint creation through the ws-only
+ *     `checkpoints.create` gateway verb, both refuse when the resolved
+ *     workspace root is not covered by the shared registration store
+ *     (the SDK's workspace registration, platform/workspace).
+ *     `'guarded'` opts back into the pre-ruling behavior for an unregistered
+ *     workspace: automatic snapshots subscribe and explicit create proceeds,
+ *     subject only to the SDK's own root/size guards above — never a silent
+ *     re-enable, an explicit per-workspace opt-out of the registration gate.
+ *
+ * Any other value (including absence) reads as `'off'`.
+ */
+export function readCheckpointRegistrationSetting(
+  configManager: Pick<ConfigManager, 'getRaw'>,
+): 'off' | 'guarded' {
+  const raw = configManager.getRaw() as unknown as Record<string, unknown>;
+  const block = raw.checkpoints;
+  if (block === null || typeof block !== 'object' || Array.isArray(block)) return 'off';
+  const value = (block as Record<string, unknown>).unregisteredWorkspaces;
+  return value === 'guarded' ? 'guarded' : 'off';
+}

package/src/config/run-daemon-config-migration.ts

@@ -0,0 +1,47 @@
+/**
+ * run-daemon-config-migration.ts — the one call every composition root in
+ * this daemon makes before constructing its `ConfigManager`.
+ *
+ * Daemon-owned configuration now has exactly one home:
+ * `~/.goodvibes/daemon/settings.json`. Before this migration, every product
+ * wrote every key (including daemon-only ones like `surfaces.telegram.*`)
+ * into its own per-surface silo, and the daemon only ever read
+ * `~/.goodvibes/tui/settings.json` — so a value written by, say, the agent
+ * surface reported a successful save and configured nothing the daemon could
+ * see.
+ *
+ * `migrateDaemonOwnedConfig` (SDK, `platform/config`) is idempotent and cheap
+ * on the fast path (one file read + JSON parse), so it is safe and correct to
+ * call this at every composition root that is about to construct a
+ * `ConfigManager` — not just the first one to run in a given process. It
+ * must never abort startup: any failure is caught, logged with the marker
+ * path so the failure is diagnosable, and startup continues on whatever
+ * config state already exists.
+ */
+import {
+  migrateDaemonOwnedConfig,
+  daemonConfigPath,
+  daemonConfigMovedPath,
+  type DaemonConfigMigrationResult,
+} from '@pellux/goodvibes-sdk/platform/config';
+import { logger, summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
+import { GOODVIBES_DAEMON_SURFACE_ROOT } from './surface.ts';
+
+/**
+ * Run the daemon-owned-config migration for `homeDir`, tolerating any
+ * failure. Returns the migration result on success, or `null` when the
+ * migration itself threw (logged as a warning naming the marker path;
+ * startup proceeds either way).
+ */
+export function runDaemonConfigMigration(homeDir: string): DaemonConfigMigrationResult | null {
+  try {
+    return migrateDaemonOwnedConfig({ homeDir, primarySurface: GOODVIBES_DAEMON_SURFACE_ROOT });
+  } catch (error) {
+    const markerPath = daemonConfigMovedPath(daemonConfigPath(homeDir));
+    logger.warn('daemon-owned config migration failed; continuing with existing config state', {
+      markerPath,
+      error: summarizeError(error),
+    });
+    return null;
+  }
+}

package/src/config/secret-config.ts

@@ -0,0 +1,175 @@
+import { isSecretRefInput, isDaemonOwnedConfigKey } from '@pellux/goodvibes-sdk/platform/config';
+import type { ConfigKey } from '@pellux/goodvibes-sdk/platform/config';
+import type { SecretScope, SecretStorageMedium } from './secrets.ts';
+
+export const SECRET_CONFIG_KEYS = new Set<ConfigKey>([
+  // Mailbox and CalDAV credentials. Their own CONFIG_SCHEMA descriptions read
+  // "Stored in the daemon secret tier, never in config" — and until they were
+  // listed here that sentence was aspirational: the settings modal wrote them
+  // as plain strings into a config JSON file, because membership in this set is
+  // the thing that routes an edit through the secret manager instead.
+  //
+  // The daemon reads each of these back with
+  // resolveConfigSecret('<key>') → GOODVIBES_<KEY>, which is exactly the store
+  // key buildGoodVibesSecretKey() writes — see
+  // daemon/handlers/inbox/providers/email.ts.
+  'surfaces.email.password',
+  'surfaces.email.imapPassword',
+  'surfaces.email.imap.password',
+  'surfaces.email.smtp.password',
+  'surfaces.calendar.caldavPassword',
+  // Telephony delivery credentials — same shape, same file, same gap.
+  'surfaces.telephony.authToken',
+  'surfaces.telephony.token',
+  'surfaces.telephony.webhookSecret',
+  'surfaces.slack.signingSecret',
+  'surfaces.slack.botToken',
+  'surfaces.slack.appToken',
+  'surfaces.discord.botToken',
+  'surfaces.ntfy.token',
+  'surfaces.webhook.secret',
+  'surfaces.homeassistant.accessToken',
+  'surfaces.homeassistant.webhookSecret',
+  'surfaces.telegram.botToken',
+  'surfaces.telegram.webhookSecret',
+  'surfaces.googleChat.verificationToken',
+  'surfaces.signal.token',
+  'surfaces.whatsapp.accessToken',
+  'surfaces.whatsapp.verifyToken',
+  'surfaces.whatsapp.signingSecret',
+  'surfaces.imessage.token',
+  'surfaces.msteams.appPassword',
+  'surfaces.bluebubbles.password',
+  'surfaces.mattermost.botToken',
+  'surfaces.matrix.accessToken',
+  // Local synthetic sub-keys, one level under the SDK's real `payments`
+  // section (not yet a scalar CONFIG_SCHEMA entry — same situation as
+  // tts.speed, behavior.notifyAfterSeconds, etc. in settings-modal-data.ts),
+  // hence the cast. See input/payments-config.ts for why these are named flat
+  // (payments.cardNumber, not payments.card.number): a flat one-level leaf is
+  // the shape the real ConfigManager tolerates for an undeclared key.
+  'payments.cardNumber' as ConfigKey,
+  'payments.cardExpiry' as ConfigKey,
+  'payments.cardCvv' as ConfigKey,
+  'payments.cardholderName' as ConfigKey,
+]);
+
+export interface SecretBackedConfigUpdate {
+  readonly configValue: string;
+  readonly secretKey?: string;
+  readonly secretValue?: string;
+  readonly clearSecretKey?: string;
+}
+
+export interface SecretBackedConfigManager {
+  readonly get: (key: ConfigKey) => unknown;
+  readonly setDynamic: (key: ConfigKey, value: unknown) => void;
+}
+
+export interface SecretBackedSecretStore {
+  readonly set: (key: string, value: string, options?: { readonly scope?: SecretScope; readonly medium?: SecretStorageMedium }) => Promise<void>;
+  readonly delete?: (key: string, options?: { readonly scope?: SecretScope; readonly medium?: SecretStorageMedium }) => Promise<void>;
+}
+
+export function isSecretConfigKey(key: string): key is ConfigKey {
+  return SECRET_CONFIG_KEYS.has(key as ConfigKey);
+}
+
+export function normalizeSecretKeyPart(value: string): string {
+  return value
+    .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+    .replace(/[^a-zA-Z0-9]+/g, '_')
+    .replace(/^_+|_+$/g, '')
+    .toUpperCase();
+}
+
+export function buildGoodVibesSecretKey(configKey: string): string {
+  return `GOODVIBES_${configKey.split('.').map(normalizeSecretKeyPart).filter(Boolean).join('_')}`;
+}
+
+export function buildGoodVibesSecretRef(secretKey: string): string {
+  return `goodvibes://secrets/goodvibes/${encodeURIComponent(secretKey)}`;
+}
+
+export function isSecretReferenceValue(value: string): boolean {
+  const normalized = value.trim();
+  return normalized.startsWith('goodvibes://secrets/') && isSecretRefInput(normalized);
+}
+
+export function isMalformedGoodVibesSecretReferenceValue(value: string): boolean {
+  const normalized = value.trim();
+  return normalized.startsWith('goodvibes://') && !isSecretReferenceValue(normalized);
+}
+
+export function getSecretWriteMedium(policy: unknown): SecretStorageMedium {
+  if (policy === 'plaintext_allowed') return 'plaintext';
+  return 'secure';
+}
+
+export function buildSecretBackedConfigUpdate(configKey: ConfigKey, rawValue: string): SecretBackedConfigUpdate {
+  const value = rawValue.trim();
+  const secretKey = buildGoodVibesSecretKey(configKey);
+  if (value.length === 0) {
+    return {
+      configValue: '',
+      clearSecretKey: secretKey,
+    };
+  }
+  if (isSecretReferenceValue(value)) {
+    return { configValue: value };
+  }
+  return {
+    configValue: buildGoodVibesSecretRef(secretKey),
+    secretKey,
+    secretValue: rawValue,
+  };
+}
+
+/**
+ * Where a secret-backed write lands when the caller did not name a scope.
+ *
+ * A daemon-owned config key (`surfaces.*`, `payments.*`, `controlPlane.*`, ...)
+ * names a credential the DAEMON executes with, not this interactive client, so
+ * its secret material belongs in the daemon-scoped tier the daemon actually
+ * reads — the same rule the SDK's config-ownership.ts already applies to the
+ * `goodvibes://` reference that points at it.
+ *
+ * Defaulting these to 'user' (the historical behavior here) split the pair: the
+ * reference landed in the daemon's own settings file, because ConfigManager
+ * routes daemon-owned keys there, while the value it pointed at sat in a tier
+ * the daemon never resolves. The surface reported success and the daemon found
+ * nothing. For the mailbox password that is the whole feature failing silently —
+ * the daemon is the process that polls IMAP and answers over Telegram, and it
+ * does so with every surface closed. A payment card entered through
+ * /payments card is the same shape of failure at purchase time.
+ */
+export function defaultSecretBackedScope(configKey: ConfigKey): SecretScope {
+  return isDaemonOwnedConfigKey(configKey) ? 'daemon' : 'user';
+}
+
+export async function persistSecretBackedConfigValue(
+  configManager: SecretBackedConfigManager,
+  secretsManager: SecretBackedSecretStore | null | undefined,
+  configKey: ConfigKey,
+  rawValue: string,
+  options: { readonly scope?: SecretScope } = {},
+): Promise<string> {
+  const update = buildSecretBackedConfigUpdate(configKey, rawValue);
+  const scope = options.scope ?? defaultSecretBackedScope(configKey);
+  const medium = getSecretWriteMedium(configManager.get('storage.secretPolicy'));
+
+  // 1. Validate config write first. If setDynamic throws, no secret is written (avoids orphans).
+  configManager.setDynamic(configKey, update.configValue);
+
+  // 2. Write new secret only after config accepted it.
+  if (update.secretKey && update.secretValue !== undefined && secretsManager) {
+    await secretsManager.set(update.secretKey, update.secretValue, { scope, medium });
+  }
+
+  // 3. Clear old secret — pass the same medium so plaintext-medium secrets are found for deletion.
+  if (update.clearSecretKey && secretsManager?.delete) {
+    await secretsManager.delete(update.clearSecretKey, { scope, medium });
+  }
+
+  return update.configValue;
+}