@pellux/goodvibes-tui 1.13.1 → 1.14.0

package/src/core/turn-event-wiring.ts

@@ -1,5 +1,7 @@
-import type { UiRuntimeEvents } from '@/runtime/index.ts';
+import type { UiRuntimeEvents, RuntimeEventBus } from '@/runtime/index.ts';
 import { buildPersistedSessionContext, persistConversation } from '@/runtime/index.ts';
+import { buildCompactionReceiptBlock } from './compaction-receipt.ts';
+import { persistTurnAnchors, recordTurnAnchor, summarizeTurnLabel } from './rewind-turn-anchors.ts';
 import { logger } from '@pellux/goodvibes-sdk/platform/utils';
 import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
 import type { HookDispatcher, HookPhase, HookCategory, HookEventPath } from '@pellux/goodvibes-sdk/platform/hooks';
@@ -32,6 +34,10 @@ interface TurnProviderRegistry {
 /** Minimal config manager surface required by turn-event wiring. */
 interface TurnConfigManager {
   get(key: string): unknown;
+  /** Subscribe to a config-key change; returns an unsubscribe. Used to keep the
+   *  footer permission-mode pill live without polling. Optional so bare test
+   *  doubles that only implement get() still satisfy the type. */
+  subscribe?(key: string, cb: (...args: unknown[]) => void): () => void;
 }
 
 /** Minimal system message router surface required by turn-event wiring. */
@@ -43,6 +49,13 @@ interface TurnSystemMessageRouter {
 
 export interface WireTurnEventHandlersOptions {
   readonly events: UiRuntimeEvents;
+  /**
+   * Raw runtime event bus. Needed for domains NOT surfaced by the grouped
+   * UiRuntimeEvents feed — specifically the 'compaction' domain, whose
+   * mandatory COMPACTION_RECEIPT the transcript renders as a distinct block.
+   * Optional so headless/test callers can omit it.
+   */
+  readonly runtimeBus?: RuntimeEventBus | null;
   readonly conversation: ConversationManager;
   readonly runtime: { sessionId: string; model: string; provider: string };
   readonly orchestrator: TurnOrchestrator;
@@ -74,6 +87,14 @@ export interface WireTurnEventHandlersOptions {
    * to fall back to).
    */
   readonly focusTracker?: Pick<FocusTracker, 'shouldAlertWhenUnfocused'> | null;
+  /**
+   * Optional in-terminal (OSC 9) notifier. When present: a turn finishing emits
+   * a 'turn-end' notification, and a delegated agent blocking on human input
+   * (AGENT_AWAITING_MESSAGE) emits an 'agent-blocked' notification. Each is
+   * gated independently by the notifier's own per-signal config + focus rule.
+   * Absent in tests/headless.
+   */
+  readonly terminalNotifier?: import('./terminal-notifier.ts').TerminalNotifier | null;
   /**
    * Minimal test seam: injectable clock for controlling Date.now() in tests.
    * Defaults to the real Date.now when absent.
@@ -114,6 +135,7 @@ export function wireTurnEventHandlers(
     events, conversation, runtime, configManager, hookDispatcher, orchestrator, providerRegistry,
     workingDir, homeDirectory, sessionManager, gitStatusProvider,
     lastGitInfoRef, buildSessionContinuityHints, render, webhookNotifier, focusTracker,
+    terminalNotifier, runtimeBus, systemMessageRouter,
     _clock = Date.now,
   } = options;
 
@@ -158,6 +180,9 @@ export function wireTurnEventHandlers(
     const notifyThreshold = readNotifyAfterSeconds((k) => configManager.get(k as Parameters<typeof configManager.get>[0]));
     // stopReason 'empty_response' signals a non-successful completion.
     const taskStatus: LongTaskStatus = evt.stopReason === 'completed' ? 'ok' : 'fail';
+    // In-terminal (OSC 9) turn-end notification — fires on its own per-signal
+    // config + focus gate, independent of the long-task duration threshold below.
+    terminalNotifier?.notify('turn-end', taskStatus === 'ok' ? 'Turn finished' : 'Turn finished with errors');
     maybeNotifyLongTask({
       elapsedMs: turnElapsedMs,
       status: taskStatus,
@@ -198,6 +223,22 @@ export function wireTurnEventHandlers(
       } catch { /* best-effort */ }
       logger.debug('auto-save on turn:complete failed', { error: summarizeError(e) });
     }
+    // Record this turn's rewind anchor: pair the turnId (shared with the
+    // workspace checkpoint the turn engine snapshots for this same turn) with
+    // the live conversation message count, so a later message-anchored /rewind
+    // can truncate the conversation to exactly this boundary — the join key
+    // between conversation and files rewind (see core/rewind-turn-anchors.ts).
+    try {
+      recordTurnAnchor(runtime.sessionId, {
+        turnId: evt.turnId,
+        label: summarizeTurnLabel(conversation.getLastUserMessage()),
+        messageCount: conversation.getMessageCount(),
+        at: _clock(),
+      });
+      // Mirror the anchors to the session's sidecar so message-anchored /rewind
+      // survives a resume (the in-memory registry alone is process-local).
+      persistTurnAnchors(runtime.sessionId, workingDir);
+    } catch { /* best-effort; a rewind-anchor miss must never break the turn */ }
     // Auto-compaction is owned by the SDK Orchestrator's post-turn maintenance
     // (handlePostTurnContextMaintenance), which runs on every turn against the
     // resolved context window (getContextWindowForModel) via the SDK's
@@ -206,6 +247,16 @@ export function wireTurnEventHandlers(
     refreshGit();
   }));
 
+  // In-terminal (OSC 9) agent-blocked notification: a delegated agent parked
+  // waiting for a human message (AGENT_AWAITING_MESSAGE) is "blocked on you".
+  // Gated by the notifier's own per-signal config + focus rule. PRIVACY: the
+  // short agent id only — never task text.
+  if (terminalNotifier) {
+    unsubs.push(events.agents.on('AGENT_AWAITING_MESSAGE', (payload) => {
+      terminalNotifier.notify('agent-blocked', `agent ${payload.agentId.slice(0, 8)} is waiting for your input`);
+    }));
+  }
+
   unsubs.push(events.tools.on('TOOL_SUCCEEDED', () => {
     refreshGit();
   }));
@@ -249,5 +300,33 @@ export function wireTurnEventHandlers(
     }));
   }
 
+  // Live footer permission-mode pill: re-render whenever the SDK config
+  // surface reports permissions.mode changed. Mode changes are made through
+  // configManager.set('permissions.mode', ...) (the SDK-owned surface the
+  // PermissionManager reads), so this covers our own Shift+Tab / /plan toggles
+  // as well as any other in-process writer. No polling.
+  if (typeof configManager.subscribe === 'function') {
+    unsubs.push(configManager.subscribe('permissions.mode', () => { render(); }));
+  }
+
+  // Post-compaction receipt (never-silent): the SDK emits a mandatory
+  // COMPACTION_RECEIPT on the 'compaction' domain after every automatic (and
+  // the manual) compaction. That domain is NOT in the grouped UiRuntimeEvents
+  // feed, so we subscribe on the raw bus and render the receipt as a distinct
+  // [Compaction] block. Automatic compaction previously left no transcript
+  // trace; this makes the audit visible.
+  if (runtimeBus) {
+    unsubs.push(runtimeBus.on('COMPACTION_RECEIPT', (envelope) => {
+      try {
+        const payload = envelope.payload;
+        if (payload.type !== 'COMPACTION_RECEIPT') return;
+        systemMessageRouter.high(buildCompactionReceiptBlock(payload));
+        render();
+      } catch (err) {
+        logger.debug('turn-event-wiring: compaction-receipt render error', { error: String(err) });
+      }
+    }));
+  }
+
   return { refreshGit, unsubs, transcriptJournal };
 }

package/src/input/command-reference.ts

@@ -0,0 +1,96 @@
+/**
+ * command-reference.ts — pure renderer for the generated slash-command
+ * reference (docs/commands-reference.md).
+ *
+ * The reference is generated from the live command registry (via
+ * {@link categorizeBuiltinCommands} in ./commands.ts), never hand-maintained.
+ * This module is deliberately side-effect free so both the generator
+ * (scripts/project-surfaces.ts) and the drift-check test import the same
+ * rendering logic — the committed file and a fresh render must be byte-identical
+ * or the gate fails.
+ */
+import type { SlashCommand } from './command-registry.ts';
+
+export interface CategorizedCommand {
+  readonly command: SlashCommand;
+  readonly category: string;
+}
+
+/** Escape the pipe and backslash characters that would break a markdown table cell. */
+function escapeCell(text: string): string {
+  return text.replace(/\\/g, '\\\\').replace(/\|/g, '\\|').replace(/\r?\n/g, ' ').trim();
+}
+
+/** Stable anchor slug for a category heading (GitHub-style). */
+function slug(text: string): string {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9\s-]/g, '')
+    .trim()
+    .replace(/\s+/g, '-');
+}
+
+/**
+ * renderCommandReferenceMarkdown — deterministic markdown for the full command
+ * set. Categories are sorted alphabetically and commands alphabetically by
+ * primary name within each category, so the output depends only on the command
+ * set and their metadata — not on registration order — which keeps the drift
+ * check meaningful (a genuinely new/renamed command moves the bytes; a pure
+ * reordering does not).
+ */
+export function renderCommandReferenceMarkdown(entries: readonly CategorizedCommand[]): string {
+  const byCategory = new Map<string, SlashCommand[]>();
+  for (const { command, category } of entries) {
+    const list = byCategory.get(category) ?? [];
+    list.push(command);
+    byCategory.set(category, list);
+  }
+
+  const categories = Array.from(byCategory.keys()).sort((a, b) => a.localeCompare(b));
+  const total = entries.length;
+
+  const lines: string[] = [];
+  lines.push('<!-- GENERATED FILE — DO NOT EDIT BY HAND.');
+  lines.push('     Regenerate with `bun run docs:commands`.');
+  lines.push('     Source of truth: the slash-command registry (src/input/commands.ts).');
+  lines.push('     A drift check (src/test/release-gates/command-reference-gate.test.ts)');
+  lines.push('     fails CI if this file is stale. -->');
+  lines.push('');
+  lines.push('# Command Reference');
+  lines.push('');
+  lines.push(
+    `GoodVibes ships **${total}** built-in slash commands across **${categories.length}** categories. ` +
+      'Every command below is generated directly from the command registry, so this list is always ' +
+      'complete and current. Type a command in the composer prefixed with `/`, or press `Ctrl+K` (or ' +
+      'run `/palette`) to search them all in the command palette.',
+  );
+  lines.push('');
+  lines.push('## Categories');
+  lines.push('');
+  for (const category of categories) {
+    const count = byCategory.get(category)?.length ?? 0;
+    lines.push(`- [${escapeCell(category)}](#${slug(category)}) — ${count}`);
+  }
+  lines.push('');
+
+  for (const category of categories) {
+    const commands = (byCategory.get(category) ?? []).slice().sort((a, b) => a.name.localeCompare(b.name));
+    lines.push(`## ${category}`);
+    lines.push('');
+    lines.push('| Command | Aliases | Usage | Description |');
+    lines.push('| --- | --- | --- | --- |');
+    for (const cmd of commands) {
+      const name = `\`/${escapeCell(cmd.name)}\``;
+      const aliases = (cmd.aliases ?? []).length > 0
+        ? (cmd.aliases ?? []).map((a) => `\`/${escapeCell(a)}\``).join(', ')
+        : '—';
+      const usageText = cmd.usage ?? cmd.argsHint ?? '';
+      const usage = usageText ? `\`${escapeCell(usageText)}\`` : '—';
+      const description = cmd.description ? escapeCell(cmd.description) : '—';
+      lines.push(`| ${name} | ${aliases} | ${usage} | ${description} |`);
+    }
+    lines.push('');
+  }
+
+  return `${lines.join('\n').trimEnd()}\n`;
+}

package/src/input/command-registry.ts

@@ -8,6 +8,7 @@ import type { PermissionRequestHandler } from '@pellux/goodvibes-sdk/platform/pe
 import type { SelectionItem, SelectionResult, SelectionAction } from './selection-modal.ts';
 import type { FileUndoManager } from '@pellux/goodvibes-sdk/platform/state';
 import type { WorkspaceCheckpointManager } from '@pellux/goodvibes-sdk/platform/workspace';
+import type { GatewayMethodCatalog } from '@pellux/goodvibes-sdk/platform/control-plane';
 import type { PanelManager, PanelDeepLinkTarget } from '../panels/panel-manager.ts';
 import type { KeybindingsManager } from './keybindings.ts';
 import type { OnboardingWizardMode } from './onboarding/onboarding-wizard.ts';
@@ -18,10 +19,12 @@ import type { HookApi } from '@pellux/goodvibes-sdk/platform/hooks';
 import type { McpApi } from '@pellux/goodvibes-sdk/platform/mcp';
 import type { ProviderApi } from '@pellux/goodvibes-sdk/platform/providers';
 import type { OpsApi } from '@/runtime/index.ts';
+import type { FeatureFlagManager } from '@/runtime/index.ts';
 import type { OperatorClient } from '@/runtime/index.ts';
 import type { PeerClient } from '@/runtime/index.ts';
 import type { DirectTransport } from '@/runtime/index.ts';
 import type { VoiceProviderRegistry, VoiceService } from '@pellux/goodvibes-sdk/platform/voice';
+import type { UiPlatformServices } from '../runtime/ui-services.ts';
 import type {
   CommandWorkspaceShellServices,
 } from '@/runtime/index.ts';
@@ -67,6 +70,8 @@ export interface CommandUiActions {
   renderRequest: () => void;
   print: (text: string) => void;
   exit: () => void;
+  /** Open the current composer draft in the user's $EDITOR and load back the edited text. */
+  openComposerEditor?: () => void;
   submitInput?: (text: string, content?: import('@pellux/goodvibes-sdk/platform/providers').ContentPart[]) => void;
   submitSpokenInput?: (text: string, content?: import('@pellux/goodvibes-sdk/platform/providers').ContentPart[]) => void;
   stopSpokenOutput?: () => void;
@@ -96,6 +101,12 @@ export interface CommandUiActions {
    */
   completeEmbeddingProviderSelection?: (providerId: string) => void;
   clearScreen?: () => void;
+  /**
+   * Begin one line of concealed (masked) composer input for a password-like
+   * secret. The typed text is masked in the composer and kept out of input
+   * history and the transcript; the plaintext reaches only request.onSubmit.
+   */
+  beginConcealedInput?: (request: import('./concealed-input.ts').ConcealedInputRequest) => void;
   activatePlan?: (planId: string, task: string) => void;
   requestPermission?: PermissionRequestHandler;
   /**
@@ -139,6 +150,12 @@ export interface CommandShellUiOpeners {
   openShortcutsOverlay?: () => void;
   getScrollTop?: () => number;
   openPanelPicker?: () => void;
+  /**
+   * Open the fuzzy command palette — a searchable picker over every registered
+   * slash command (generated live from the registry). Bound to Ctrl+K and the
+   * /palette command. Selecting a command pre-fills it into the composer.
+   */
+  openCommandPalette?: () => void;
   /**
    * Open (and optionally focus) a panel. UX-C focus rule: the command path is
    * "the user is mid-command-flow" — opening a panel this way leaves keyboard
@@ -226,6 +243,10 @@ export interface CommandWorkspaceUiServices {
   keybindingsManager?: KeybindingsManager;
   fileUndoManager?: FileUndoManager;
   workspaceCheckpointManager?: WorkspaceCheckpointManager;
+  /** In-process gateway catalog — the /review hunk-revert flow invokes checkpoints.revertHunk(Preview) over it. */
+  gatewayMethods?: GatewayMethodCatalog;
+  workspaceTrustManager?: import('../runtime/trust/workspace-trust.ts').WorkspaceTrustManager;
+  workspaceRegistrationManager?: import('../runtime/trust/workspace-registration.ts').WorkspaceRegistrationManager;
   panelManager?: PanelManager;
   profileManager?: import('@pellux/goodvibes-sdk/platform/profiles').ProfileManager;
   bookmarkManager?: import('@pellux/goodvibes-sdk/platform/bookmarks').BookmarkManager;
@@ -241,6 +262,8 @@ export interface CommandWorkspaceServices
 export interface CommandPlatformConfigServices {
   readonly config: DeepReadonly<GoodVibesConfig>;
   readonly configManager: ConfigManager;
+  /** Feature-flag runtime — backs the `/flags` command's listing and runtime toggling. */
+  readonly featureFlagManager?: FeatureFlagManager;
   readonly voiceProviderRegistry?: VoiceProviderRegistry;
   readonly voiceService?: VoiceService;
   /** Direct-command consumer (`/search`) alongside the existing agent-tool consumer. */
@@ -248,6 +271,8 @@ export interface CommandPlatformConfigServices {
   /** Direct-command consumer (`/image`) — first production caller of `.generate()`. */
   readonly mediaProviders?: import('@pellux/goodvibes-sdk/platform/media').MediaProviderRegistry;
   readonly artifactStore?: import('@pellux/goodvibes-sdk/platform/artifacts').ArtifactStore;
+  /** Background daemon/HTTP-listener/relay controller. Mutable: main.ts patches it in post-bootstrap (see bootstrap-command-parts.ts ordering note). */
+  externalServices?: UiPlatformServices['externalServices'];
 }
 
 export interface CommandPlatformServices

package/src/input/commands/channel-pairing.ts

@@ -0,0 +1,245 @@
+/**
+ * channel-pairing.ts — guided `/channel pair` flow.
+ *
+ * Adapters and their credential requirements are driven from the SDK's
+ * getBuiltinSetupSchema — the same setup-schema source every GoodVibes
+ * consumer (TUI, webui, agent) reads, not a hand-maintained list here.
+ * Secret (masked) credentials are stored the same secure way onboarding
+ * stores them, via persistSecretBackedConfigValue (secret manager + a
+ * config reference), so the plaintext never lands in config or the
+ * transcript.
+ *
+ *   /channel pair                  → list adapters + how many credentials are set
+ *   /channel pair <surface>        → show the adapter's declared credentials and
+ *                                     prompt (masked) for each missing secret
+ *   /channel pair <surface> verify → a REAL round-trip: send a test message
+ *                                     through the daemon (channels.test.send)
+ *                                     and report the actual delivered/error
+ *                                     outcome, never a fabricated success.
+ */
+import { getBuiltinSetupSchema } from '@pellux/goodvibes-sdk/platform/channels';
+import type { ChannelSetupFieldDescriptor, ChannelSetupSchema, ChannelSurface } from '@pellux/goodvibes-sdk/platform/channels';
+import type { CommandContext } from '../command-registry.ts';
+import type { ConfigManager, ConfigKey } from '../../config/index.ts';
+import { persistSecretBackedConfigValue } from '../../config/secret-config.ts';
+import { describeOperatorRpcError, getOperatorRpc } from './operator-rpc.ts';
+
+/**
+ * Surfaces pairable through /channel pair — every ChannelSurface except the
+ * two internal render surfaces ('tui', 'web'), which are not externally
+ * paired channels. The `satisfies Record<...>` shape makes this exhaustive:
+ * a new ChannelSurface value that isn't listed here fails to compile.
+ */
+type PairableSurface = Exclude<ChannelSurface, 'tui' | 'web'>;
+const PAIRABLE_SURFACE_SET = {
+  slack: true,
+  discord: true,
+  ntfy: true,
+  webhook: true,
+  homeassistant: true,
+  telegram: true,
+  'google-chat': true,
+  signal: true,
+  whatsapp: true,
+  telephony: true,
+  imessage: true,
+  msteams: true,
+  bluebubbles: true,
+  mattermost: true,
+  matrix: true,
+} satisfies Record<PairableSurface, true>;
+const PAIRABLE_SURFACES: readonly PairableSurface[] = Object.keys(PAIRABLE_SURFACE_SET) as PairableSurface[];
+
+function findSchema(surface: string): ChannelSetupSchema | undefined {
+  return PAIRABLE_SURFACES.includes(surface as PairableSurface) ? getBuiltinSetupSchema(surface as PairableSurface) : undefined;
+}
+
+/** The always-present 'enabled' boolean field's config key, if declared. */
+function enabledConfigKey(schema: ChannelSetupSchema): ConfigKey | undefined {
+  return schema.fields.find((f) => f.id === 'enabled' && f.kind === 'boolean')?.configKey as ConfigKey | undefined;
+}
+
+function fieldValue(field: ChannelSetupFieldDescriptor, configManager: ConfigManager): string {
+  if (!field.configKey) return '';
+  const raw = configManager.get(field.configKey as ConfigKey);
+  return raw === undefined || raw === null ? '' : String(raw);
+}
+
+/** A field counts as configured once it has any stored value; 'select' fields always carry a default. */
+function fieldConfigured(field: ChannelSetupFieldDescriptor, configManager: ConfigManager): boolean {
+  if (field.kind === 'select' || field.kind === 'boolean') return true;
+  return fieldValue(field, configManager).length > 0;
+}
+
+/** Credential fields the user must supply — secret (masked) and plain text; booleans/selects are defaulted. */
+function credentialFields(schema: ChannelSetupSchema): ChannelSetupFieldDescriptor[] {
+  return schema.fields.filter((field) => field.kind === 'secret' || field.kind === 'string' || field.kind === 'url' || field.kind === 'number');
+}
+
+/** A field-level hint: the matching secretTarget's detail for secrets, else the placeholder, else the label. */
+function fieldHint(field: ChannelSetupFieldDescriptor, schema: ChannelSetupSchema): string {
+  if (field.kind === 'secret' && field.secretTargetId) {
+    const target = schema.secretTargets.find((t) => t.id === field.secretTargetId);
+    if (target?.detail) return target.envKeys?.length ? `${target.detail} (env: ${target.envKeys.join(', ')})` : target.detail;
+  }
+  return field.placeholder ? `e.g. ${field.placeholder}` : field.label;
+}
+
+function listAdapters(ctx: CommandContext): void {
+  const configManager = ctx.platform.configManager;
+  const lines: string[] = ['Channel adapters — pair with /channel pair <surface>:', ''];
+  for (const surface of PAIRABLE_SURFACES) {
+    const schema = getBuiltinSetupSchema(surface);
+    const creds = credentialFields(schema);
+    const set = creds.filter((f) => fieldConfigured(f, configManager)).length;
+    const enabledKey = enabledConfigKey(schema);
+    const enabled = enabledKey !== undefined && configManager.get(enabledKey) === true;
+    const state = creds.length === 0 ? 'no credentials' : `${set}/${creds.length} set`;
+    lines.push(`  ${surface.padEnd(14)} ${schema.label.padEnd(22)} ${state.padEnd(12)} ${enabled ? '(enabled)' : ''}`);
+  }
+  lines.push('');
+  lines.push('Run /channel pair <surface> to see and enter its declared credentials.');
+  ctx.print(lines.join('\n'));
+}
+
+function renderSurface(schema: ChannelSetupSchema, configManager: ConfigManager): string[] {
+  const lines = [`${schema.label} (${schema.surface})`, schema.description, '', `Setup mode: ${schema.setupMode}`, '', 'Declared credentials:'];
+  for (const field of credentialFields(schema)) {
+    const configured = fieldConfigured(field, configManager);
+    const kindTag = field.kind === 'secret' ? 'secret' : 'value';
+    const status = configured ? 'set' : 'not set';
+    lines.push(`  - ${field.label} (${kindTag}): ${status} — ${fieldHint(field, schema)}`);
+  }
+  if (schema.externalSteps.length > 0) {
+    lines.push('', 'External setup steps:');
+    for (const step of schema.externalSteps) lines.push(`  - ${step}`);
+  }
+  return lines;
+}
+
+/** Chain a masked prompt for each missing secret field, storing each securely. */
+function promptMissingSecrets(
+  ctx: CommandContext,
+  schema: ChannelSetupSchema,
+  missing: readonly ChannelSetupFieldDescriptor[],
+  index: number,
+): void {
+  const configManager = ctx.platform.configManager;
+  if (index >= missing.length) {
+    const enabledKey = enabledConfigKey(schema);
+    if (enabledKey !== undefined) configManager.setDynamic(enabledKey, true);
+    ctx.print(`\n${schema.label} credentials stored${enabledKey !== undefined ? ' and the surface is enabled' : ''}. Verify with: /channel pair ${schema.surface} verify`);
+    ctx.renderRequest();
+    return;
+  }
+  const field = missing[index]!;
+  if (!field.configKey) {
+    ctx.print(`[pair] ${field.label} has no config key declared; skipping.`);
+    promptMissingSecrets(ctx, schema, missing, index + 1);
+    return;
+  }
+  const configKey = field.configKey as ConfigKey;
+  if (!ctx.beginConcealedInput) {
+    ctx.print('[pair] Concealed input is unavailable on this surface; set credentials via /config and re-run verify.');
+    return;
+  }
+  ctx.print(`[pair] Enter ${field.label} (${field.placeholder || 'value'}) — masked; Enter to store, Esc to stop.`);
+  ctx.beginConcealedInput({
+    label: field.label,
+    onSubmit: (value) => {
+      if (value.length === 0) {
+        ctx.print(`[pair] ${field.label} left unset.`);
+        promptMissingSecrets(ctx, schema, missing, index + 1);
+        return;
+      }
+      void persistSecretBackedConfigValue(configManager, ctx.platform.secretsManager, configKey, value)
+        .then(() => {
+          ctx.print(`[pair] ${field.label} stored securely (hidden).`);
+          promptMissingSecrets(ctx, schema, missing, index + 1);
+        })
+        .catch((error: unknown) => {
+          ctx.print(`[pair] Failed to store ${field.label}: ${error instanceof Error ? error.message : String(error)}`);
+          promptMissingSecrets(ctx, schema, missing, index + 1);
+        });
+    },
+    onCancel: () => {
+      ctx.print(`[pair] Stopped. Re-run /channel pair ${schema.surface} to finish the remaining credentials.`);
+    },
+  });
+}
+
+/**
+ * Verify a surface: report which declared credentials resolve locally, then
+ * perform a REAL round-trip through the daemon (channels.test.send) and
+ * report the actual delivered/error outcome — never a fabricated success.
+ */
+async function verifySurface(ctx: CommandContext, schema: ChannelSetupSchema): Promise<void> {
+  const configManager = ctx.platform.configManager;
+  const creds = credentialFields(schema);
+  const lines: string[] = [`Verifying ${schema.label} (${schema.surface}):`];
+  const missing: ChannelSetupFieldDescriptor[] = [];
+  for (const field of creds) {
+    const ok = fieldConfigured(field, configManager);
+    if (!ok) missing.push(field);
+    lines.push(`  ${ok ? '[ok]  ' : '[fail]'} ${field.label}${ok ? '' : ' — missing'}`);
+  }
+  lines.push('');
+  if (missing.length === 0) {
+    lines.push('All declared credentials resolve.');
+  } else {
+    lines.push(`${missing.length} credential(s) still missing: ${missing.map((f) => f.label).join(', ')}.`);
+    lines.push(`Run /channel pair ${schema.surface} to enter them.`);
+  }
+  ctx.print(lines.join('\n'));
+
+  const rpc = getOperatorRpc(ctx);
+  if (!rpc.available) {
+    ctx.print(`\n[verify] Cannot perform a live round-trip: ${rpc.reason}`);
+    return;
+  }
+  ctx.print(`\n[verify] Sending a real test message through ${schema.surface}...`);
+  try {
+    const result = await rpc.sdk.operator.invoke('channels.test.send', { surface: schema.surface });
+    if (result.delivered) {
+      ctx.print(`[verify] delivered:true${result.responseId ? ` (responseId: ${result.responseId})` : ''}${result.address ? ` → ${result.address}` : ''}`);
+    } else {
+      ctx.print(`[verify] delivered:false — ${result.error ?? 'the daemon returned no error detail'}`);
+    }
+  } catch (error) {
+    ctx.print(`[verify] round-trip request failed: ${describeOperatorRpcError(error)}`);
+  }
+}
+
+/** Entry point for `/channel pair [...]`. */
+export async function runChannelPairing(args: readonly string[], ctx: CommandContext): Promise<void> {
+  const surface = args[0];
+  if (!surface) {
+    listAdapters(ctx);
+    return;
+  }
+  const schema = findSchema(surface);
+  if (!schema) {
+    ctx.print(`Unknown channel "${surface}". Available: ${PAIRABLE_SURFACES.join(', ')}`);
+    return;
+  }
+  const action = (args[1] ?? '').toLowerCase();
+  if (action === 'verify' || action === 'test') {
+    await verifySurface(ctx, schema);
+    return;
+  }
+
+  const configManager = ctx.platform.configManager;
+  ctx.print(renderSurface(schema, configManager).join('\n'));
+  const creds = credentialFields(schema);
+  const missingSecrets = creds.filter((f) => f.kind === 'secret' && !fieldConfigured(f, configManager));
+  const missingText = creds.filter((f) => f.kind !== 'secret' && !fieldConfigured(f, configManager));
+  if (missingText.length > 0) {
+    ctx.print(`\nNon-secret values to set with /config (or accept defaults): ${missingText.map((f) => `${f.label} → ${f.configKey}`).join('; ')}`);
+  }
+  if (missingSecrets.length === 0) {
+    ctx.print(`\nNo missing secrets. Verify with: /channel pair ${schema.surface} verify`);
+    return;
+  }
+  ctx.print(`\nEntering ${missingSecrets.length} secret credential(s) — Esc to stop.`);
+  promptMissingSecrets(ctx, schema, missingSecrets, 0);
+}