@pellux/goodvibes-tui 0.21.0 → 0.23.0

package/src/renderer/agent-detail-modal.ts

@@ -8,18 +8,25 @@ import { formatDuration } from './modal-utils.ts';
 import { logger } from '@pellux/goodvibes-sdk/platform/utils';
 import { getOverlaySurfaceMetrics, getStableOverlayContentRows } from './overlay-viewport.ts';
 import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
+import { handleConfirmInput, type ConfirmState } from '../panels/confirm-state.ts';
+import { AGENT_TERMINAL_STATUSES as MODAL_TERMINAL_STATUSES, AGENT_STALL_THRESHOLD_MS as MODAL_STALL_THRESHOLD_MS } from '../panels/agent-inspector-shared.ts';
 
 // ─── Constants ────────────────────────────────────────────────────────────────
 
 const MAX_LOG_ENTRIES = 10;
 const AGENT_ID_DISPLAY_LENGTH = 16;
 
+// MODAL_TERMINAL_STATUSES and MODAL_STALL_THRESHOLD_MS are re-exported aliases
+// from agent-inspector-shared.ts (imported above alongside ConfirmState).
+
 export interface AgentDetailModalDeps {
-  readonly agentManager: Pick<AgentManager, 'getStatus'>;
+  readonly agentManager: Pick<AgentManager, 'getStatus' | 'list'>;
   readonly agentMessageBus: Pick<AgentMessageBus, 'getMessages'>;
   readonly sessionLogPathResolver: (agentId: string) => string;
   /** Optional — when supplied, constraint data from the agent's WRFC chain is shown (SDK 0.23.0). */
   readonly wrfcController?: Pick<WrfcController, 'getChain'>;
+  /** Cancel the agent by id using the same orphan-free path as WRFC. Returns true if cancelled. */
+  readonly cancelAgent: (agentId: string) => boolean;
 }
 
 // ─── AgentDetailModal ─────────────────────────────────────────────────────────
@@ -39,6 +46,9 @@ export class AgentDetailModal {
   public logEntries: Record<string, unknown>[] = [];
   public logTotal = 0;
 
+  /** Pending cancel confirmation. Subject is the agent id to cancel. */
+  public confirmCancel: ConfirmState<string> | null = null;
+
   private refreshTimer: ReturnType<typeof setInterval> | null = null;
   private onRefresh: (() => void) | null = null;
 
@@ -67,12 +77,88 @@ export class AgentDetailModal {
     this.agentId = null;
     this.logEntries = [];
     this.logTotal = 0;
+    this.confirmCancel = null;
     if (this.refreshTimer) {
       clearInterval(this.refreshTimer);
       this.refreshTimer = null;
     }
   }
 
+  /**
+   * Handle a key press while the modal is active.
+   * Must be called BEFORE the Esc handler closes the modal.
+   *
+   * Routes:
+   *   - 'c' initiates cancel confirm (if agent is non-terminal)
+   *   - confirm keys (Enter/y/n/Esc) are forwarded to handleConfirmInput
+   *
+   * Returns true when the key was consumed (caller should NOT propagate).
+   */
+  handleKey(key: string): boolean {
+    if (!this.active) return false;
+
+    if (this.confirmCancel) {
+      const result = handleConfirmInput(this.confirmCancel, key);
+      if (result === 'confirmed') {
+        if (this.agentId) {
+          const rec = this.deps.agentManager.getStatus(this.agentId);
+          if (rec && !MODAL_TERMINAL_STATUSES.has(rec.status)) {
+            this.deps.cancelAgent(rec.id);
+          }
+        }
+        this.confirmCancel = null;
+        this.onRefresh?.();
+        return true;
+      }
+      if (result === 'cancelled') {
+        this.confirmCancel = null;
+        this.onRefresh?.();
+        return true;
+      }
+      // absorbed — key swallowed while confirm is pending
+      return true;
+    }
+
+    if (key === 'c') {
+      if (this.agentId) {
+        const rec = this.deps.agentManager.getStatus(this.agentId);
+        if (rec && !MODAL_TERMINAL_STATUSES.has(rec.status)) {
+          const label = rec.task.split('\n')[0]?.slice(0, 40) ?? rec.id.slice(-8);
+          this.confirmCancel = { subject: rec.id, label };
+          this.onRefresh?.();
+          return true;
+        }
+      }
+      // Non-cancellable — absorb key silently
+      return true;
+    }
+
+    return false;
+  }
+
+  /**
+   * Returns whether the current agent is considered stalled.
+   * Non-terminal agent with elapsed time exceeding MODAL_STALL_THRESHOLD_MS.
+   */
+  isCurrentAgentStalled(): boolean {
+    if (!this.agentId) return false;
+    const rec = this.deps.agentManager.getStatus(this.agentId);
+    if (!rec || MODAL_TERMINAL_STATUSES.has(rec.status)) return false;
+    return (Date.now() - rec.startedAt) >= MODAL_STALL_THRESHOLD_MS;
+  }
+
+  /**
+   * Count of all stalled agents across the agentManager list.
+   * Non-terminal agents with elapsed time >= MODAL_STALL_THRESHOLD_MS.
+   */
+  getStalledAgentCount(): number {
+    const now = Date.now();
+    return this.deps.agentManager.list().filter(rec => {
+      if (MODAL_TERMINAL_STATUSES.has(rec.status)) return false;
+      return (now - rec.startedAt) >= MODAL_STALL_THRESHOLD_MS;
+    }).length;
+  }
+
   async loadLog(): Promise<void> {
     if (!this.agentId) { this.logEntries = []; this.logTotal = 0; return; }
     try {
@@ -161,7 +247,8 @@ export function renderAgentDetailModal(
   const modelStr = rec.model ? `${rec.provider ?? ''}/${rec.model}` : (rec.provider ?? '(default)');
   sections.push({ type: 'text', content: `Template : ${rec.template}` });
   sections.push({ type: 'text', content: `Model    : ${modelStr}` });
-  sections.push({ type: 'text', content: `Status   : ${rec.status}` });
+  const isStalled = !MODAL_TERMINAL_STATUSES.has(rec.status) && (now - rec.startedAt) >= MODAL_STALL_THRESHOLD_MS;
+  sections.push({ type: 'text', content: `Status   : ${rec.status}${isStalled ? '  [STALLED — 5+ min no activity]' : ''}` });
   sections.push({ type: 'text', content: `Duration : ${formatDuration(elapsedMs)}` });
   sections.push({ type: 'separator' });
 
@@ -321,12 +408,29 @@ export function renderAgentDetailModal(
     }
   }
 
+  // Cancel confirm overlay (when pending)
+  const cancellable = !MODAL_TERMINAL_STATUSES.has(rec.status);
+  if (modal.confirmCancel) {
+    sections.push({ type: 'separator' });
+    sections.push({
+      type: 'text',
+      content: `Cancel agent "${modal.confirmCancel.label}"?`,
+      style: { fg: '#f59e0b' },
+    });
+    sections.push({
+      type: 'text',
+      content: 'y / Enter  confirm     n / Esc  cancel',
+      style: { dim: true },
+    });
+  }
+
+  const cancelHint = cancellable ? '[c] Cancel  ' : '';
   return ModalFactory.createModal({
     title: `Agent: ${rec.id.slice(0, AGENT_ID_DISPLAY_LENGTH)}`,
     width: metrics.boxWidth,
     margin: metrics.margin,
     targetContentRows,
     sections,
-    hints: ['[Esc] Close'],
+    hints: [cancelHint + '[Esc] Close'],
   }, width);
 }

package/src/renderer/compaction-history-modal.ts

@@ -0,0 +1,55 @@
+/**
+ * Compaction history text builder.
+ *
+ * Renders a read-only list of past compaction events sourced from the SDK's
+ * module-level compaction event log (`getCompactionEvents()`).
+ *
+ * The SDK records CompactionEvent data (timestamps, token counts,
+ * trigger, message counts) but does not expose a snapshot restore API.
+ * Restore is list-only; users can view what compactions ran but cannot roll back.
+ */
+
+import { getCompactionEvents } from '@pellux/goodvibes-sdk/platform/core';
+import type { CompactionEvent } from '@pellux/goodvibes-sdk/platform/core';
+
+// ─── formatCompactionEvent ────────────────────────────────────────────────────
+
+function formatCompactionEvent(ev: CompactionEvent, n: number): string {
+  const date = new Date(ev.timestamp);
+  const timeStr = date.toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' });
+  const savings = Math.max(0, ev.tokensBeforeEstimate - ev.tokensAfterEstimate);
+  const savingsPct = ev.tokensBeforeEstimate > 0
+    ? Math.round((savings / ev.tokensBeforeEstimate) * 100)
+    : 0;
+  const trigger = ev.trigger === 'auto' ? 'auto' : 'manual';
+  return (
+    `#${n} ${timeStr} [${trigger}]  ` +
+    `${ev.messagesBeforeCompaction}→${ev.messagesAfterCompaction} msgs  ` +
+    `~${fmtN(ev.tokensBeforeEstimate)}→~${fmtN(ev.tokensAfterEstimate)} tok  ` +
+    `saved ${savingsPct}%`
+  );
+}
+
+function fmtN(n: number): string {
+  return n.toLocaleString();
+}
+
+/**
+ * Build a plain-text compaction history summary suitable for ctx.print().
+ * Useful as the output of /compact-history when not in overlay mode.
+ */
+export function buildCompactionHistoryText(): string {
+  const events = getCompactionEvents();
+  if (events.length === 0) {
+    return '[Context] No compactions recorded this session. (Restore is not available — the SDK does not yet expose a snapshot restore API.)';
+  }
+  const lines: string[] = [
+    `[Context] Compaction history (${events.length} total, most recent first):`,
+  ];
+  const ordered = [...events].reverse();
+  for (let i = 0; i < ordered.length; i++) {
+    lines.push('  ' + formatCompactionEvent(ordered[i], ordered.length - i));
+  }
+  lines.push('  (Restore not available — the SDK does not yet expose a snapshot restore API.)');
+  return lines.join('\n');
+}

package/src/renderer/compaction-preview.ts

@@ -0,0 +1,146 @@
+/**
+ * Compaction preview and after-notice builders.
+ *
+ * Pre-compact: shows an honest estimate of what compaction will do
+ * (message count and token estimate before → after). The SDK has no dry-run
+ * API; we derive the after-estimate from the DEFAULT_COMPACTION_CONFIG
+ * totalCeiling (6500 tokens) — clearly labelled as an ESTIMATE.
+ *
+ * Post-compact: shows a before/after notice using the CompactionEvent
+ * data returned by compactMessages(), which contains the real
+ * tokensBeforeEstimate and tokensAfterEstimate figures.
+ *
+ * Honest wording policy:
+ *  - Pre-compact notice says "estimate" every time; never claims certainty.
+ *  - Post-compact notice uses "~N" prefix on every token figure.
+ *  - Pinned session memories that survive are mentioned by count.
+ */
+
+import { estimateConversationTokens } from '@pellux/goodvibes-sdk/platform/core';
+import type { CompactionEvent } from '@pellux/goodvibes-sdk/platform/core';
+import type { ProviderMessage } from '@pellux/goodvibes-sdk/platform/providers';
+
+/**
+ * Default compaction totalCeiling from context-compaction DEFAULT_COMPACTION_CONFIG.
+ * Kept local so we don't take a runtime dependency on the internal config object.
+ * Used only for the pre-compact ESTIMATE; the real figure comes from CompactionEvent.
+ */
+const COMPACTION_OUTPUT_CEILING_ESTIMATE = 6500;
+
+export interface CompactionPreviewOptions {
+  /** Messages currently in the conversation. */
+  readonly messages: readonly ProviderMessage[];
+  /** Context window size for the current model (0 if unknown). */
+  readonly contextWindow: number;
+  /** Number of session memories that will survive compaction. */
+  readonly pinnedMemoryCount: number;
+  /** Whether this is triggered automatically or manually. */
+  readonly trigger: 'auto' | 'manual';
+}
+
+export interface CompactionAfterOptions {
+  /** The CompactionEvent returned by the SDK after compaction completes. */
+  readonly event: CompactionEvent;
+  /** Number of session memories that survived compaction. */
+  readonly pinnedMemoryCount: number;
+}
+
+/**
+ * Build the pre-compaction notice string.
+ *
+ * Returned as a plain string intended for `ctx.print()` or `systemMessageRouter`.
+ * Always labelled as an estimate; uses the SDK totalCeiling as the after-estimate.
+ */
+export function buildCompactionPreview(opts: CompactionPreviewOptions): string {
+  const { messages, contextWindow, pinnedMemoryCount, trigger } = opts;
+  const msgCount = messages.length;
+  const tokensBefore = estimateConversationTokens(messages as ProviderMessage[]);
+  const tokensAfterEstimate = COMPACTION_OUTPUT_CEILING_ESTIMATE;
+
+  const contextStr = contextWindow > 0
+    ? ` (${Math.round((tokensBefore / contextWindow) * 100)}% of ${fmtN(contextWindow)} context window)`
+    : '';
+
+  const pinStr = pinnedMemoryCount > 0
+    ? ` ${pinnedMemoryCount} pinned session memor${pinnedMemoryCount === 1 ? 'y' : 'ies'} will be preserved.`
+    : '';
+
+  const triggerStr = trigger === 'auto' ? 'Auto-compacting' : 'Compacting';
+
+  return (
+    `[Context] ${triggerStr} conversation: ~${fmtN(tokensBefore)} tokens across ${msgCount} message${msgCount === 1 ? '' : 's'}${contextStr}.` +
+    ` Estimated result: ~${fmtN(tokensAfterEstimate)} tokens (estimate — actual depends on content).` +
+    (pinStr ? ` ${pinStr.trim()}` : '')
+  );
+}
+
+/**
+ * Build the post-compaction before/after notice string.
+ *
+ * Uses the real CompactionEvent figures (not estimates) for both before and
+ * after token counts. The trigger field controls wording.
+ */
+export function buildCompactionAfterNotice(opts: CompactionAfterOptions): string {
+  const { event, pinnedMemoryCount } = opts;
+  const {
+    messagesBeforeCompaction,
+    messagesAfterCompaction,
+    tokensBeforeEstimate,
+    tokensAfterEstimate,
+    trigger,
+  } = event;
+
+  const savings = Math.max(0, tokensBeforeEstimate - tokensAfterEstimate);
+  const savingsPct = tokensBeforeEstimate > 0
+    ? Math.round((savings / tokensBeforeEstimate) * 100)
+    : 0;
+
+  const pinStr = pinnedMemoryCount > 0
+    ? ` ${pinnedMemoryCount} pinned memor${pinnedMemoryCount === 1 ? 'y' : 'ies'} preserved.`
+    : '';
+
+  const triggerStr = trigger === 'auto' ? 'Auto-compact complete' : 'Compact complete';
+
+  return (
+    `[Context] ${triggerStr}: ${messagesBeforeCompaction} → ${messagesAfterCompaction} messages,` +
+    ` ~${fmtN(tokensBeforeEstimate)} → ~${fmtN(tokensAfterEstimate)} tokens` +
+    ` (saved ~${fmtN(savings)}, ${savingsPct}%).` +
+    (pinStr ? ` ${pinStr.trim()}` : '')
+  );
+}
+
+/** Format a number with thousands separators. */
+function fmtN(n: number): string {
+  return n.toLocaleString();
+}
+
+/**
+ * Build the /keep command usage text (shown when no args are provided).
+ *
+ * Exported for testability — the shell-core handler renders this string directly.
+ */
+export function buildPinUsageText(): string {
+  return (
+    '[Pin] Usage: /keep <text>\n' +
+    'Pinned entries are stored as session memories and included in the compaction handoff as pinned memories.\n' +
+    'What pinning guarantees: the text survives the next compaction.\n' +
+    'What pinning does NOT guarantee: recovery after process restart (session memories are in-memory only).'
+  );
+}
+
+/**
+ * Build the /keep command success text.
+ *
+ * @param id - The assigned memory ID (e.g. "mem-1")
+ * @param text - The pinned text
+ * @param count - Total pinned memory count after adding
+ *
+ * Exported for testability — the shell-core handler renders this string directly.
+ */
+export function buildPinSuccessText(id: string, text: string, count: number): string {
+  return (
+    `[Pin] Pinned as ${id}: "${text.slice(0, 60)}${text.length > 60 ? '...' : ''}"\n` +
+    `  ${count} pinned memor${count === 1 ? 'y' : 'ies'} will survive the next compaction.\n` +
+    '  Note: session memories are in-memory only and do not persist across restarts.'
+  );
+}

package/src/renderer/context-status-hint.ts

@@ -0,0 +1,54 @@
+/**
+ * Context status hint — TASK-056.
+ *
+ * Produces a short, dismissible status-line hint when the session maintenance
+ * level indicates compaction is recommended or repair is needed.  The hint is
+ * passive and non-blocking: it appears in the footer status row and disappears
+ * once the pressure signal clears.
+ *
+ * Honest wording policy:
+ *  - suggest-compact → describes the situation and offers /compact
+ *  - needs-repair    → names the failure state honestly without alarming
+ *  - compacting      → shows in-progress text so the user knows something is running
+ *  - watch           → no hint (not yet actionable)
+ *  - stable/unknown  → no hint
+ */
+
+import type { PanelSessionMaintenanceLevel } from '../panels/session-maintenance.ts';
+
+export interface ContextStatusHintOptions {
+  /** Maintenance level from evaluateSessionMaintenance. */
+  readonly level: PanelSessionMaintenanceLevel;
+  /** Whether auto-compaction is active (threshold > 0 in config). */
+  readonly autoCompactEnabled: boolean;
+  /** Current usage percent 0–100. */
+  readonly usagePct: number;
+}
+
+/**
+ * Build the passive status-line hint text for context pressure.
+ *
+ * Returns null when no hint is warranted (stable / watch / unknown).
+ * The caller renders this as a dim informational line — no prompts, no
+ * blocking, no confirmation required.
+ */
+export function buildContextStatusHint(options: ContextStatusHintOptions): string | null {
+  const { level, autoCompactEnabled, usagePct } = options;
+
+  switch (level) {
+    case 'needs-repair':
+      return `  Context pressure critical (${usagePct}% used) — compaction needs attention. Run /compact or /health review.`;
+
+    case 'suggest-compact':
+      if (autoCompactEnabled) {
+        return `  Context high (${usagePct}% used) — auto-compact will run before the next turn.`;
+      }
+      return `  Context high (${usagePct}% used) — run /compact to recover headroom.`;
+
+    case 'compacting':
+      return `  Compacting context — freeing headroom...`;
+
+    default:
+      return null;
+  }
+}

package/src/renderer/settings-modal-helpers.ts

@@ -4,8 +4,8 @@
  * architecture cap. No layout logic lives here.
  */
 
-import type { SettingEntry, McpEntry, SubscriptionEntry } from '../input/settings-modal.ts';
-import { SETTINGS_CATEGORIES } from '../input/settings-modal.ts';
+import type { SettingEntry, McpEntry, SubscriptionEntry } from '../input/settings-modal-types.ts';
+import { SETTINGS_CATEGORIES } from '../input/settings-modal-types.ts';
 import { isSecretConfigKey, isSecretReferenceValue } from '../config/secret-config.ts';
 
 function maskSecretValue(value: string): string {

package/src/renderer/settings-modal.ts

@@ -539,14 +539,25 @@ function rowColorForSetting(modal: SettingsModal, rowText: string): string {
   return valueColor(selected);
 }
 
-function footerText(modal: SettingsModal): string {
+function footerText(modal: SettingsModal, width: number): string {
+  // Armed reset gate takes priority over all other footer states.
+  if (modal.resetCategoryConfirm !== null || modal.resetAllConfirm !== null)
+    return 'Reset armed · Enter/y confirm · Esc/n cancel';
   if (modal.searchFocused) return 'Search · type to filter · Up/Down navigate results · Enter select · Esc exit search';
   if (modal.editingMode) return 'Enter Confirm edit · Esc Cancel edit · text keys edit the selected field';
   if (modal.focusPane === 'categories') return 'Focus categories · Up/Down choose · Right/Enter settings · Tab pane · / search · Esc close';
   if (modal.currentCategory === 'subscriptions') return 'Focus settings · Up/Down provider · Left categories · Tab pane · / search · Enter review/sign out · Esc close';
   if (modal.currentCategory === 'mcp') return 'Focus settings · Up/Down server · Left categories · Tab pane · / search · Enter edit trust · Esc close';
   if (modal.currentCategory === 'flags') return 'Focus feature flags · Up/Down flag · Left categories · Tab pane · / search · Enter/Space toggle · Esc close';
-  return 'Focus settings · Up/Down setting · Left categories · Tab pane · / search · Enter/Space edit/toggle · R reset · Esc close';
+  // Default settings pane: tier the reset affordances by available width.
+  // W<80:  minimal — only the most critical action survives.
+  // W<160: compact but still shows both reset affordances.
+  // W≥160: standard with all navigation tokens.
+  if (width < 80)
+    return 'R reset · Esc';
+  if (width < 160)
+    return 'Up/Down · Enter/Space edit · ⇧R reset cat · ^⇧R reset all · Esc';
+  return 'Focus settings · Up/Down setting · Left · Enter/Space edit/toggle · ⇧R reset cat · ^⇧R reset all · Esc close';
 }
 
 export function renderSettingsModal(
@@ -601,6 +612,6 @@ export function renderSettingsModal(
     })),
     contextRows,
     controlRows,
-    footer: footerText(modal),
+    footer: footerText(modal, width),
   });
 }

package/src/renderer/shell-surface.ts

@@ -29,6 +29,11 @@ export interface ShellFooterBuildOptions {
   readonly composerStatus?: string;
   readonly composerFlags?: readonly string[];
   readonly composerPendingRisk?: 'none' | 'approval-wait' | 'shell' | 'command' | 'remote';
+  /**
+   * Passive context pressure hint from buildContextStatusHint.
+   * Rendered as a dim informational line above the prompt when non-null.
+   */
+  readonly contextStatusHint?: string | null;
 }
 
 export interface ShellFooterBuildResult {
@@ -84,5 +89,10 @@ export function buildShellFooter(
   );
   const inputBoxRows = Math.max(1, options.promptLineCount) + 2;
   lines.splice(inputBoxRows, 0, ...processIndicator);
+  // Passive context status hint — rendered as a dim informational line before the prompt.
+  if (options.contextStatusHint) {
+    const hintLine = UIFactory.stringToLine(options.contextStatusHint, options.width, { fg: '#64748b' });
+    lines.unshift(hintLine);
+  }
   return { lines, height: lines.length };
 }

package/src/runtime/bootstrap-command-parts.ts

@@ -160,6 +160,7 @@ export function createBootstrapCommandActions(
   | 'openMcpWorkspace'
   | 'openSecurityPanel'
   | 'openKnowledgePanel'
+  | 'openMemoryPanel'
   | 'openRemotePanel'
   | 'openSubscriptionPanel'
   | 'openLocalAuthMaskedEntry'
@@ -273,6 +274,9 @@ export function createBootstrapCommandActions(
     openKnowledgePanel: () => {
       showPanel('knowledge');
     },
+    openMemoryPanel: () => {
+      showPanel('memory');
+    },
     openRemotePanel: () => {
       showPanel('remote');
     },

package/src/runtime/bootstrap-core.ts

@@ -123,6 +123,88 @@ export interface BootstrapCoreState {
 
 export type CompanionMessagePayload = Extract<SessionEvent, { type: 'COMPANION_MESSAGE_RECEIVED' }>;
 
+// ---------------------------------------------------------------------------
+// Operator narration of inbound channel events
+// ---------------------------------------------------------------------------
+
+/**
+ * Narrate an inbound channel event to the operator via the SystemMessageRouter.
+ *
+ * When an external surface (GitHub, Slack, ntfy, etc.) triggers an agent turn,
+ * this function produces a human-readable system message so the operator can
+ * observe which event caused the turn. Returns null for internal/companion
+ * sources that do not need operator narration.
+ *
+ * @param event - The normalized inbound event descriptor.
+ * @returns A narration string, or null if no narration is appropriate.
+ */
+export function narrateInboundEvent(event: {
+  source: string;
+  metadata: Readonly<Record<string, unknown>> | undefined;
+}): string | null {
+  const { source, metadata } = event;
+  if (!source) return null;
+
+  // Derive the effective surface — prefer metadata.surface, fall back to source.
+  const surface = typeof metadata?.surface === 'string' ? metadata.surface : source;
+
+  // Internal / companion sources do not need operator narration.
+  if (surface === 'companion' || source === 'companion') return null;
+  if (surface === 'internal' || source === 'internal') return null;
+
+  // Build a surface label for the log prefix.
+  const label = ((): string => {
+    switch (surface) {
+      case 'github':        return '[GitHub]';
+      case 'slack':         return '[Slack]';
+      case 'discord':       return '[Discord]';
+      case 'ntfy':          return '[ntfy]';
+      case 'homeassistant': return '[HomeAssistant]';
+      case 'telegram':      return '[Telegram]';
+      case 'google-chat':   return '[Google Chat]';
+      case 'signal':        return '[Signal]';
+      case 'whatsapp':      return '[WhatsApp]';
+      case 'msteams':       return '[Teams]';
+      case 'imessage':      return '[iMessage]';
+      case 'bluebubbles':   return '[BlueBubbles]';
+      case 'mattermost':    return '[Mattermost]';
+      case 'matrix':        return '[Matrix]';
+      case 'webhook':       return '[Webhook]';
+      default:              return `[${surface[0]!.toUpperCase()}${surface.slice(1)}]`;
+    }
+  })();
+
+  const eventType   = typeof metadata?.eventType   === 'string' ? metadata.eventType   : null;
+  const eventAction = typeof metadata?.eventAction  === 'string' ? metadata.eventAction : null;
+  const topic       = typeof metadata?.topic        === 'string' ? metadata.topic       : null;
+  const prNumber    = typeof metadata?.prNumber     === 'number' ? metadata.prNumber    : null;
+  const issueNumber = typeof metadata?.issueNumber  === 'number' ? metadata.issueNumber : null;
+  const repo        = typeof metadata?.repo         === 'string' ? metadata.repo        : null;
+
+  // Build event-specific detail for GitHub events.
+  if (surface === 'github' && eventType) {
+    const actionPart = eventAction ? ` ${eventAction}` : '';
+    let detail = `${eventType}${actionPart} → agent triggered`;
+    if (prNumber !== null) {
+      detail = `PR #${prNumber}${repo ? ` (${repo})` : ''} ${eventAction ?? eventType} → agent triggered`;
+    } else if (issueNumber !== null) {
+      detail = `Issue #${issueNumber}${repo ? ` (${repo})` : ''} ${eventAction ?? eventType} → agent triggered`;
+    } else if (repo) {
+      detail = `${eventType}${actionPart} in ${repo} → agent triggered`;
+    }
+    return `${label} ${detail}`;
+  }
+
+  // ntfy: include topic when available.
+  if (surface === 'ntfy' && topic) {
+    return `${label} inbound message on topic '${topic}' → agent triggered`;
+  }
+
+  // Generic narration for all other surfaces.
+  const eventDetail = eventType ? ` ${eventType}${eventAction ? ` ${eventAction}` : ''}` : '';
+  return `${label}${eventDetail} inbound event → agent triggered`;
+}
+
 export function companionMessageToOrchestratorInputOptions(
   payload: CompanionMessagePayload,
 ): OrchestratorUserInputOptions {
@@ -426,6 +508,30 @@ export async function initializeBootstrapCore(
     }
   };
 
+  // Startup TLS banner — emitted via wrfcBuffer.push() because the
+  // SystemMessageRouter is not attached yet at this point in bootstrap. The
+  // smart-ref setter on systemMessageRouterRef auto-flushes the buffer when
+  // the router attaches, so the message will appear in the WRFC panel on startup.
+  {
+    const cpEnabled = Boolean(configManager.get('controlPlane.enabled'));
+    const cpHostMode = String(configManager.get('controlPlane.hostMode') ?? 'local');
+    const cpTlsMode = String(configManager.get('controlPlane.tls.mode') ?? 'off');
+    const hlEnabled = Boolean(configManager.get('danger.httpListener'));
+    const hlHostMode = String(configManager.get('httpListener.hostMode') ?? 'local');
+    const hlTlsMode = String(configManager.get('httpListener.tls.mode') ?? 'off');
+    const cpNetworkPlaintext = cpEnabled && cpHostMode !== 'local' && cpTlsMode === 'off';
+    const hlNetworkPlaintext = hlEnabled && hlHostMode !== 'local' && hlTlsMode === 'off';
+    if (cpNetworkPlaintext || hlNetworkPlaintext) {
+      const affected: string[] = [];
+      if (cpNetworkPlaintext) affected.push('control plane');
+      if (hlNetworkPlaintext) affected.push('HTTP listener');
+      wrfcBuffer.push(
+        `[SECURITY] TLS is off for the ${affected.join(' and ')} but it is network-reachable. All traffic (credentials, tokens, conversation content) travels in plaintext. Enable TLS (controlPlane.tls.mode / httpListener.tls.mode) or restrict to loopback before exposing to untrusted networks.`,
+        'high',
+      );
+    }
+  }
+
   runtimeUnsubs.push(
     runtimeBus.on<Extract<import('@/runtime/index.ts').WorkflowEvent, { type: 'WORKFLOW_CONSTRAINTS_ENUMERATED' }>>(
       'WORKFLOW_CONSTRAINTS_ENUMERATED',
@@ -501,6 +607,16 @@ export async function initializeBootstrapCore(
   runtimeUnsubs.push(runtimeBus.on<Extract<SessionEvent, { type: 'COMPANION_MESSAGE_RECEIVED' }>>(
     'COMPANION_MESSAGE_RECEIVED',
     ({ payload }) => {
+      // Narrate inbound external events to the operator so they can observe
+      // which channel event triggered the agent turn.
+      const narration = narrateInboundEvent({
+        source: payload.source,
+        metadata: payload.metadata,
+      });
+      if (narration) {
+        routeOrBuffer(narration, 'low');
+      }
+
       if (orchestratorHandleUserInputRef.value) {
         // Delegate to the orchestrator: adds user message + fires a real LLM turn.
         // Preserve surface origin metadata so the SDK can correlate replies back