elanous 0.2.22 → 0.2.24

package/src/nexus/api/missions.ts

@@ -35,6 +35,18 @@ import {
   type MissionStatus,
 } from '../../task-orchestrator/mission.js';
 import type { Task } from '../../task-orchestrator/types.js';
+import {
+  openSchedulesDb,
+  listSchedules,
+  scheduleHealth,
+} from '../../domains/schedule-registry.js';
+import {
+  cronRowsToDerived,
+  rollupDerived,
+  taskStatusToDerived,
+  type DerivedJob,
+  type MissionRollup,
+} from '../../autopilot/mission-trace.js';
 
 import { checkAuth, type MetaApiOpts } from './meta-api.js';
 import { jsonResponse } from './http-server.js';
@@ -68,12 +80,63 @@ export interface MissionCardWire {
    *  Mission. 자율 Mission 이면 실행모델·apm 상태·계보 키를 담아 통합 Missions
    *  표면이 autopilot 여부와 lineage 를 한눈에 렌더한다. */
   autopilot: MissionAutopilot | null;
+  /** 파생 작업 롤업(태스크 + 크론). ⛔ **결손 수리(MISSIONS-STALE-MARK · 2026-10-11)**:
+   *  이 칸이 없어 PWA 미션 카드의 `RollupChips` 는 항상 `undefined` 를 받아
+   *  «아무것도» 안 그렸다 — 그래서 «파생 0»과 «파생 미측정»을 화면이 «구분 못 했다».
+   *  카드는 목록 엔드포인트만 보므로(미션별 `traceAutopilotMission` 을 안 부름)
+   *  여기서 «이미 로드한 태스크» ⊕ «요청당 한 번 읽은 schedule_registry」로
+   *  계산한다. 자율행동(surface_events)·자식 미션은 상세 트레이스
+   *  (`ops_status action=mission`)의 몫으로 남는다(목록에서 N× 무거운 조인 금지).
+   *  매핑은 `rollupDerived`·`taskStatusToDerived`·`cronRowsToDerived` — «단일 소유»라
+   *  트레이스와 갈림이 없다. `total: 0` = «파생이 정말 0». */
+  derived: MissionRollup;
   createdAt: number;
   updatedAt: number;
   closedAt: number | null;
 }
 
-export function summarise(mission: Mission, tasks: readonly Task[]): MissionCardWire {
+/** 태스크 행 → 파생물(순수). 트레이스의 `fetchTaskDerived` 와 같은 상태 매핑
+ *  (`taskStatusToDerived`)을 쓴다 — «두 가지 상태 어휘»를 만들지 않는다. */
+export function taskRowsToDerived(tasks: readonly Task[]): DerivedJob[] {
+  return tasks.map((t) => ({
+    kind: 'task',
+    id: t.id,
+    name: t.title,
+    status: taskStatusToDerived(t.status),
+  }));
+}
+
+/** 요청당 «한 번» schedule_registry 를 읽어 apmId 별 크론 파생물을 나눠 담는다.
+ *  ⛔ 미션별로 DB 를 열면 목록 N건 = N× 열기 — 그래서 한 번 읽고 in-process 분배.
+ *  fail-soft: 레지스트리가 없으면 빈 Map(derived 는 태스크만 집계). */
+export function loadCronDerivedByMission(): Map<string, DerivedJob[]> {
+  const out = new Map<string, DerivedJob[]>();
+  try {
+    const db = openSchedulesDb();
+    try {
+      const rows = listSchedules(db);
+      const staleIds = new Set(scheduleHealth(rows).stale.map((s) => s.id));
+      const rowsByMission = new Map<string, typeof rows>();
+      for (const row of rows) {
+        const apmId = row.autopilot_id;
+        if (!apmId) continue;
+        const bucket = rowsByMission.get(apmId);
+        if (bucket) bucket.push(row);
+        else rowsByMission.set(apmId, [row]);
+      }
+      for (const [apmId, missionRows] of rowsByMission) {
+        out.set(apmId, cronRowsToDerived(missionRows, staleIds));
+      }
+    } finally { db.close(); }
+  } catch { /* fail-soft */ }
+  return out;
+}
+
+export function summarise(
+  mission: Mission,
+  tasks: readonly Task[],
+  crons: readonly DerivedJob[] = [],
+): MissionCardWire {
   const taskStatusCounts: Record<string, number> = {};
   const surfaceKindCounts: Record<string, number> = {};
   for (const t of tasks) {
@@ -92,6 +155,7 @@ export function summarise(mission: Mission, tasks: readonly Task[]): MissionCard
     taskStatusCounts,
     surfaceKindCounts,
     autopilot: mission.autopilot ?? null,
+    derived: rollupDerived([...taskRowsToDerived(tasks), ...crons]),
     createdAt: mission.createdAt,
     updatedAt: mission.updatedAt,
     closedAt: mission.closedAt ?? null,
@@ -115,8 +179,15 @@ export function handleMissionsList(
   const store = new TaskStore();
   try {
     const missions = store.listMissions(filter);
+    // 크론 레지스트리는 «요청당 한 번»만 읽고 apmId 로 분배(미션별 DB 열기 금지).
+    const cronsByMission = loadCronDerivedByMission();
     const cards = missions.map((m) =>
-      summarise(m, store.listTasksForMission(m.id)),
+      summarise(
+        m,
+        store.listTasksForMission(m.id),
+        // schedule_registry.autopilot_id 는 계보 키(apmId)다 — TOX 미션 id 와 다를 수 있다.
+        cronsByMission.get(m.autopilot?.apmId ?? m.id) ?? cronsByMission.get(m.id) ?? [],
+      ),
     );
     return jsonResponse({
       total: cards.length,

package/src/nexus/api/ops-api.ts

@@ -9,6 +9,8 @@ import { jsonResponse } from './json-response.js';
 import { operatorSignal } from './operator.js';
 import { createSeatsCache, todayKst } from './ops-seats.js';
 import { liveSeatsSources } from './ops-seats-sources.js';
+import { createOverviewCache } from '../../ops/overview-cache.js';
+import { parseSince } from '../../ops/overview-collect.js';
 import type { MetaApiOpts } from './meta-api.js';
 
 const VERSION = /^\d+\.\d+\.\d+(?:-(?:rc|alpha|beta)\.\d+)?$/;
@@ -17,6 +19,11 @@ const DATE = /^\d{4}-\d{2}-\d{2}$/;
 let seatsCache: ReturnType<typeof createSeatsCache> | null = null;
 /** Tests swap the sources; production builds them lazily on first use. */
 export function setSeatsCacheForTest(cache: ReturnType<typeof createSeatsCache> | null): void { seatsCache = cache; }
+let overviewCache: ReturnType<typeof createOverviewCache> | null = null;
+export function setOverviewCacheForTest(cache: ReturnType<typeof createOverviewCache> | null): void {
+  overviewCache?.stop();
+  overviewCache = cache;
+}
 const LOG_PATH = /^\/v1\/ops\/release\/runs\/([^/]+)\/nodes\/([^/]+)\/log$/;
 
 interface RunNode { nodeId: string; ok?: unknown; output?: unknown; startedAt?: unknown; endedAt?: unknown }
@@ -190,6 +197,17 @@ export function handleOpsApi(req: Request, metaApi: MetaApiOpts | undefined): Re
     response.headers.set('cache-control', 'no-store');
     return response;
   };
+  if (pathname === '/v1/ops/overview') {
+    let since: ReturnType<typeof parseSince>;
+    try { since = parseSince(url.searchParams.get('since') ?? undefined); }
+    catch { return jsonResponse({ error: 'invalid-since' }, 400); }
+    const version = url.searchParams.get('version');
+    if (version !== null && !VERSION.test(version)) return jsonResponse({ error: 'invalid-version' }, 400);
+    overviewCache ??= createOverviewCache();
+    return overviewCache.get({ sinceMs: since.ms, sinceLabel: since.label,
+      ...(version ? { version } : {}), ...(url.searchParams.has('owner') ? { owner: url.searchParams.get('owner')! } : {}) })
+      .then((overview) => served(jsonResponse(overview)), () => jsonResponse({ error: 'overview-unavailable' }, 500));
+  }
   if (pathname === '/v1/ops/seats') {
     const date = url.searchParams.get('date') ?? todayKst();
     if (!DATE.test(date) || Number.isNaN(Date.parse(`${date}T00:00:00+09:00`))) return jsonResponse({ error: 'invalid-date' }, 400);

package/src/nexus/api/outbound-report.ts

@@ -8,7 +8,7 @@
 // so ALL outbound routes through elanous's delivery channels. Send-only;
 // auth via bearer (acp-token).
 //
-// Body: { text: string, markdown?: boolean, kind?: string }
+// Body: { text: string, markdown?: boolean, kind?: string, role?: string }
 //   kind routes per-channel since R6 Phase 1 (2026-07-07): the body is
 //   handed to routeOutbound (src/nexus/outbound/router.ts) which fans out
 //   to telegram/discord/pushcut per the `outbound` user-config section.
@@ -53,6 +53,7 @@ interface OutboundBody {
   text?: string;
   markdown?: boolean;
   kind?: string;
+  role?: string;
 }
 
 function json(body: unknown, status: number): Response {
@@ -85,10 +86,14 @@ export async function handleOutboundReport(req: Request, metaApi: MetaApiOpts, r
   const cfg = getUserConfig();
   const kind = typeof body.kind === 'string' ? body.kind : 'report';
   try {
-    // Router is per-channel fail-soft; `delivered` = any channel ok.
+    // routeOutbound dispatches via the channel adapter registry; legacy fan-out
+    // remains per-channel fail-soft and `delivered` = any channel ok.
     // Producers (outbound-alert.ts deliver()) gate their direct-telegram
     // fallback on this top-level boolean — keep it stable.
-    const result = await routeOutbound(cfg, { text, markdown: body.markdown ?? true, kind }, routerDeps);
+    const role = typeof body.role === 'string' && /^[a-zA-Z0-9_-]{1,80}$/.test(body.role) ? body.role : undefined;
+    // A request that names a role intends that role's recipients — never fall back to the kind route silently.
+    if (body.role !== undefined && role === undefined) return json({ error: 'invalid-role' }, 400);
+    const result = await routeOutbound(cfg, { text, markdown: body.markdown ?? true, kind, ...(role ? { role } : {}) }, routerDeps);
     const clientFallback = req.headers.get('X-Elanous-Client-Fallback') === 'direct';
     const source = req.headers.get('X-Elanous-Outbound-Source') ?? 'daemon-http';
     if (result.delivered || !clientFallback) observeDaemonSend(cfg, text, kind, result, source);

package/src/nexus/api/telegram-trigger-bot.ts

@@ -36,6 +36,7 @@ import { parseTelegramEndpoint, isOwnInstanceEndpoint, matchesBot } from '../../
 import { createTelegramStreamSink } from '../../session/streaming/telegram-stream-sink.js';
 import { splitMarkdownForTelegram } from '../../telegram-format.js';
 import { formatTablesAndRules } from '../../discord-markdown.js';
+import { receiveChannelEvent } from '../outbound/router.js';
 
 export interface NexusTelegramTriggerBotOpts {
   /** Bot token (without `Bot ` prefix). Production reads
@@ -117,11 +118,13 @@ export function createTelegramTriggerLogger(
  *  comment) so the wire is a near-identity with `raw` carrying the
  *  full payload (messageId · isDm) for debugging. */
 export function toTelegramEvent(tap: TgTriggerEvent): TelegramEvent {
+  const envelope = receiveChannelEvent('telegram', tap);
+  if (!envelope || envelope instanceof Promise) throw new Error('telegram connector cannot normalize accepted tap');
   return {
     kind: tap.kind,
-    chat: tap.chat,
-    user: tap.user,
-    body: tap.body,
+    chat: envelope.channel ?? tap.chat,
+    user: envelope.senderId ?? tap.user,
+    body: envelope.text,
     ...(tap.command !== undefined ? { command: tap.command } : {}),
     raw: tap,
   };

package/src/nexus/index.ts

@@ -410,6 +410,8 @@ export interface RunNexusOptions {
    *  detachForTesting; production runs always start the server. Tests
    *  that DO want the server can pass false explicitly. */
   skipHttpServer?: boolean;
+  /** Test seam: replaces the daily error-report prune timer (the boot prune still runs for real). */
+  errorReportPruneScheduleForTesting?: (tick: () => void, ms: number) => { unref?: () => void };
   /** Override starting port for the HTTP server. Defaults to 31415. */
   httpStartPort?: number;
   /** Control-plane port; passing 0 also enables an isolated listener in detached tests. */
@@ -1266,6 +1268,13 @@ export async function runNexus(opts: RunNexusOptions = {}): Promise<RunNexusHand
   // 60s 틱마다 grace 유예 초과 구독자를 left 로 이탈 확정(reconcileSessionPresence).
   // cleared in shutdown hook.
   let presenceSweepHandle: ReturnType<typeof setInterval> | undefined;
+  // ERROR-REPORT-PRUNE-TICK — 30-day error-report retention must not wait for the next receipt:
+  // prune once at boot and once a day (unconditional · fail-soft · unref). Cleared in shutdown hook.
+  let errorReportPrune: { stop(): void } | undefined;
+  try {
+    const { startErrorReportPruneTick } = await import('./api/error-reports.js');
+    errorReportPrune = startErrorReportPruneTick({ ...(opts.errorReportPruneScheduleForTesting ? { schedule: opts.errorReportPruneScheduleForTesting } : {}) });
+  } catch (err) { console.warn(`[nexus] error-report prune wiring failed: ${(err as Error).message}`); }
   // ★ UR4d — 조율자 저지연 push watcher(logs.db tail edge-trigger). opt-in·기본 OFF.
   // cleared in shutdown hook(내부 타이머는 unref 이나 명시 정지).
   let coordinatorPushWatcher: { stop(): void } | undefined;
@@ -3383,6 +3392,7 @@ export async function runNexus(opts: RunNexusOptions = {}): Promise<RunNexusHand
     if (replayArmerHandle) { clearInterval(replayArmerHandle); replayArmerHandle = undefined; }
     // §P2 — stop the session presence grace sweeper.
     if (presenceSweepHandle) { clearInterval(presenceSweepHandle); presenceSweepHandle = undefined; }
+    if (errorReportPrune) { errorReportPrune.stop(); errorReportPrune = undefined; }
     // ★ UR4d — stop the coordinator low-latency push watcher(logs.db tail + debounce).
     if (coordinatorPushWatcher) { try { coordinatorPushWatcher.stop(); } catch { /* ignore */ } coordinatorPushWatcher = undefined; }
     // Phase 2 (2026-05-13) — dispose the TOX boot handle. dispose()
@@ -4011,78 +4021,10 @@ function shouldRegisterWebterm(): boolean {
 // `boot/register-daemon.ts` and re-exported above (line 32) so existing
 // test imports (`from '../src/nexus/index.js'`) keep working.
 
-/** Resolve the active daemon tool surface kind for runNexus.
- *
- *  Resolution order (parity with `deriveChildEnv` for daemon tab spawn —
- *  the same switch fed into a daemon child env should govern the in-
- *  process path too):
- *
- *    1. CLI flag (`opts.tools`)                                     ← 1회 boot
- *    2. `ELANOUS_TOOLS` env                                           ← shell session
- *    3. UserConfig switch `global.tools` (PWA Settings 토글이 여기) ← 영구
- *    4. switch default = `'webterm'` (`builtins/global.ts:12`)       ← fallback
- *
- *  Pre-fix the in-process branch fell back to `'none'` while
- *  `deriveChildEnv` fell back to the switch default `'webterm'`. That
- *  meant a clean-machine `elanous nexus` (no flag/env) gave the in-process
- *  LLM call an empty tool catalog while a separately-launched
- *  `elanous serve` daemon honored the switch default's full surface —
- *  surprising divergence the user had no way to discover.
- *
- *  `'all'` is in the switch enum but has no `toolSurface()` impl yet;
- *  fall back to `'webterm'` (the most-capable wired surface). */
-const daemonToolSurfaceKinds: Record<DaemonToolSurfaceKind, true> = {
-  none: true,
-  readonly: true,
-  chat: true,
-  webterm: true,
-};
-
-function resolveKnownToolsKind(raw: string): DaemonToolSurfaceKind | undefined {
-  return Object.hasOwn(daemonToolSurfaceKinds, raw)
-    ? raw as DaemonToolSurfaceKind
-    : undefined;
-}
-
-export function resolveToolsKind(opts: { tools?: string }): DaemonToolSurfaceKind {
-  let raw: string | undefined = opts.tools;
-  if (!raw) raw = process.env.ELANOUS_TOOLS?.trim();
-  if (!raw) {
-    try {
-      const cfg = readUserConfig();
-      const v = readSwitchValue(cfg, 'global.tools');
-      if (typeof v === 'string') raw = v;
-    } catch { /* swallow — boot must not fail on a malformed config */ }
-  }
-  if (!raw) raw = 'webterm';
-  return resolveKnownToolsKind(raw) ?? 'webterm';
-}
-
-/** Resolve the `:agent` (통합 모드 webterm dock) tool surface kind.
- *
- *  Distinct from {@link resolveToolsKind} because the integrated
- *  webterm-dock chat is **defined by** its PTY surface — WebTerminal*
- *  tools (Snapshot · Input · Screenshot) are what make `:agent`
- *  meaningful next to a live terminal. If the user has narrowed their
- *  user-config (`global.tools chat` / `readonly`) to keep the
- *  standalone `/chat` lighter, that preference must NOT bleed into the
- *  integrated dock — otherwise the `:agent` LLM loses access to the
- *  very terminal it's supposed to drive.
- *
- *  Resolution order:
- *    1. CLI flag (`opts.tools`)         ← explicit operator intent wins
- *    2. **`'webterm'`** (hardcoded)     ← env + global.tools intentionally
- *                                         skipped vs. resolveToolsKind
- *
- *  CLI flag is honored so a developer debugging tool selection
- *  (`elanous nexus run --tools readonly`) still sees a readonly `:agent`;
- *  but a clean-machine boot or a config-narrowed boot always gets
- *  webterm for the integrated dock. */
-export function resolveAgentTurnToolsKind(opts: { tools?: string }): DaemonToolSurfaceKind {
-  const raw = opts.tools?.trim();
-  if (!raw) return 'webterm';
-  // 'all' (or any unrecognized string) → webterm fallback, same as
-  // resolveToolsKind so the two resolvers stay consistent for valid
-  // CLI input.
-  return resolveKnownToolsKind(raw) ?? 'webterm';
-}
+// C-2a (same pattern as `shouldRegisterDaemon` above): the tool-surface
+// resolution block (`daemonToolSurfaceKinds` · `resolveKnownToolsKind` ·
+// `resolveToolsKind` · `resolveAgentTurnToolsKind`) moved to
+// `nexus/tools-kind.ts` and re-exported here so existing test imports
+// (`from '../src/nexus/index.js'`) keep working.
+import { resolveAgentTurnToolsKind, resolveToolsKind } from './tools-kind.js';
+export { resolveToolsKind, resolveAgentTurnToolsKind } from './tools-kind.js';

package/src/nexus/outbound/format.ts

@@ -12,6 +12,8 @@ export interface OutboundMsg {
   text: string;
   markdown: boolean;
   kind: string;
+  /** Optional routing role; absent preserves per-kind fan-out. */
+  role?: string;
 }
 
 export interface FormattedMessage {

package/src/nexus/outbound/router.ts

@@ -43,8 +43,66 @@ import {
 export { chunkForDiscord } from './format.js';
 export type { OutboundChannelType, OutboundMsg } from './format.js';
 
+/** The adapter's capability declaration is explicit: a feature is unavailable unless
+ * the connector implements it. Send-only webhooks must not claim inbound support. */
+export interface ChannelCapabilities {
+  send: boolean;
+  receive: boolean;
+  thread: boolean;
+  topic: boolean;
+  persona: boolean;
+  channelLifecycle: boolean;
+  permissions: boolean;
+  commands: boolean;
+  attachments: boolean;
+  buttons: boolean;
+  choices: boolean;
+  deliveryConfirmation: boolean;
+  rateLimit: boolean;
+}
+
+export interface ChannelEnvelope {
+  text: string;
+  kind: string;
+  channel?: string;
+  senderId?: string;
+  messageId?: string | number;
+  threadId?: string;
+  topicId?: string;
+  persona?: { name: string; avatarUrl?: string };
+  attachments?: readonly { url: string; name?: string }[];
+  buttons?: readonly { label: string; value: string }[];
+  choices?: readonly { label: string; value: string }[];
+}
+
+/** Plugin contract; optional operations may only be advertised when implemented.
+ * `send` returns the same ChannelResult shape used by the existing delivery ledger. */
+export interface ChannelAdapter {
+  readonly type: string;
+  readonly capabilities: ChannelCapabilities;
+  send(config: OutboundChannelConfig, message: OutboundMsg, cfg: UserConfig, deps: RouterDeps): Promise<ChannelResult>;
+  receive?: (payload: unknown) => ChannelEnvelope | null | Promise<ChannelEnvelope | null>;
+  createChannel?: (name: string) => Promise<string>;
+  archiveChannel?: (id: string) => Promise<void>;
+  checkPermission?: (action: string) => Promise<boolean>;
+  registerCommands?: (commands: readonly string[]) => Promise<void>;
+  confirmDelivery?: (messageId: string) => Promise<boolean>;
+  retryAfterMs?: (result: ChannelResult) => number | undefined;
+  /** Validate a plugin's channel entry before it becomes eligible for routing.
+   *  Unknown or invalid entries stay disabled rather than falling back to a different channel. */
+  parseConfig?: (raw: Record<string, unknown>) => OutboundChannelConfig | undefined;
+}
+
+/** Existing bot receive paths can normalize an accepted event through the same
+ * adapter contract before dispatching to their unchanged workflow/chat handlers. */
+export function receiveChannelEvent(type: string, payload: unknown): ChannelEnvelope | null | Promise<ChannelEnvelope | null> {
+  const adapter = outboundAdapters.get(type) ?? installedAdapters.get(type);
+  if (!adapter?.capabilities.receive || !adapter.receive) return null;
+  return adapter.receive(payload);
+}
+
 export interface OutboundChannelConfig {
-  type: OutboundChannelType;
+  type: OutboundChannelType | (string & {});
   /** discord: full webhook URL (required). pushcut: webhook URL — when
    *  omitted the adapter falls back to the API-key client
    *  (~/.elanous/pushcut.json) with `notification`. */
@@ -54,6 +112,24 @@ export interface OutboundChannelConfig {
   notification?: string;
 }
 
+/** Connector providers register while the host is running; unregister on plugin
+ * deactivation. Built-ins cannot be replaced by a plugin or removed. */
+const installedAdapters = new Map<string, ChannelAdapter>();
+export function registerOutboundAdapter(adapter: ChannelAdapter): () => void {
+  if (!/^[a-z][a-z0-9-]*$/.test(adapter.type) || outboundAdapters.has(adapter.type) || installedAdapters.has(adapter.type)
+    || !adapter.capabilities.send || typeof adapter.send !== 'function' || typeof adapter.parseConfig !== 'function'
+    || (adapter.capabilities.receive && typeof adapter.receive !== 'function')
+    || (adapter.capabilities.channelLifecycle && (typeof adapter.createChannel !== 'function' || typeof adapter.archiveChannel !== 'function'))
+    || (adapter.capabilities.permissions && typeof adapter.checkPermission !== 'function')
+    || (adapter.capabilities.commands && typeof adapter.registerCommands !== 'function')
+    || (adapter.capabilities.deliveryConfirmation && typeof adapter.confirmDelivery !== 'function')
+    || (adapter.capabilities.rateLimit && typeof adapter.retryAfterMs !== 'function')) {
+    throw new Error(`invalid or duplicate outbound connector: ${adapter.type}`);
+  }
+  installedAdapters.set(adapter.type, adapter);
+  return () => { if (installedAdapters.get(adapter.type) === adapter) installedAdapters.delete(adapter.type); };
+}
+
 export interface OutboundFanoutConfig {
   channels: OutboundChannelConfig[];
   /** kind → channel types. A kind missing here falls back to
@@ -62,6 +138,11 @@ export interface OutboundFanoutConfig {
   routes?: Record<string, string[]>;
   /** 외출 중 kind → channel types. 미지정 kind는 awayRoutes.default, 이것도 없으면 기존 routes를 유지한다. */
   awayRoutes?: Record<string, string[]>;
+  /** Optional primary/fallback per message kind or role; legacy routes remain fan-out. */
+  primary?: Record<string, string>;
+  fallback?: Record<string, string>;
+  /** Optional role → eligible channel types; no role retains kind routes. */
+  roleRoutes?: Record<string, string[]>;
 }
 
 export interface ChannelResult {
@@ -95,6 +176,8 @@ export interface RouterDeps {
   /** 롱콘텐츠 spill 주입(테스트/대체). 기본 = spillLongContent(S3 게이트·fail-soft).
    *  긴 본문을 S3 업로드+링크로 대체 → 전 메신저가 짧은 링크 버전을 받음. */
   spill?: (text: string) => { text: string; spilled: boolean; url?: string };
+  /** Test/host supplied connector registry; built-ins remain the default. */
+  adapters?: ReadonlyMap<string, ChannelAdapter>;
 }
 
 /** Parse the sparse `outbound` section. Malformed input → undefined
@@ -109,7 +192,16 @@ export function normalizeOutbound(raw: unknown): OutboundFanoutConfig | undefine
     if (!entry || typeof entry !== 'object') continue;
     const ch = entry as Record<string, unknown>;
     const type = ch.type;
-    if (type !== 'telegram' && type !== 'discord' && type !== 'pushcut') continue;
+    if (type !== 'telegram' && type !== 'discord' && type !== 'pushcut') {
+      if (typeof type === 'string') {
+        const connector = installedAdapters.get(type);
+        try {
+          const parsed = connector?.parseConfig?.(ch);
+          if (parsed?.type === type) channels.push(parsed);
+        } catch { /* invalid plugin config is not a routable channel */ }
+      }
+      continue;
+    }
     const webhookUrl = typeof ch.webhookUrl === 'string' && ch.webhookUrl.trim()
       ? ch.webhookUrl.trim() : undefined;
     const notification = typeof ch.notification === 'string' && ch.notification.trim()
@@ -132,7 +224,18 @@ export function normalizeOutbound(raw: unknown): OutboundFanoutConfig | undefine
   };
   const routes = parseRoutes(o.routes);
   const awayRoutes = parseRoutes(o.awayRoutes);
-  return { channels, ...(routes ? { routes } : {}), ...(awayRoutes ? { awayRoutes } : {}) };
+  const roleRoutes = parseRoutes(o.roleRoutes);
+  const parseSelection = (value: unknown): Record<string, string> | undefined => {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) return undefined;
+    return Object.fromEntries(Object.entries(value as Record<string, unknown>)
+      // Keep a selection even when its channel is not configured: an explicit main/backup must
+      // never silently turn back into legacy fan-out (it is reported as not-routed instead).
+      .filter((entry): entry is [string, string] => typeof entry[1] === 'string' && entry[1].trim().length > 0));
+  };
+  const primary = parseSelection(o.primary);
+  const fallback = parseSelection(o.fallback);
+  return { channels, ...(routes ? { routes } : {}), ...(awayRoutes ? { awayRoutes } : {}),
+    ...(roleRoutes ? { roleRoutes } : {}), ...(primary ? { primary } : {}), ...(fallback ? { fallback } : {}) };
 }
 
 /** Resolve the channel list for one message kind. No/empty config →
@@ -148,14 +251,14 @@ export function resolveChannels(
   return outbound.channels.filter(ch => route.includes(ch.type));
 }
 
-async function deliverTelegram(cfg: UserConfig, msg: OutboundMsg, deps: RouterDeps): Promise<ChannelResult> {
+async function deliverTelegram(_ch: OutboundChannelConfig, msg: OutboundMsg, cfg: UserConfig, deps: RouterDeps): Promise<ChannelResult> {
   const fmt = formatForChannel('telegram', msg);
   const send = deps.telegramSend ?? sendTelegramReport;
   const ok = await send(cfg, fmt.text, { markdown: fmt.markdown ?? msg.markdown, fetchImpl: deps.fetchImpl, kind: msg.kind });
   return ok ? { type: 'telegram', ok: true } : { type: 'telegram', ok: false, error: 'not-configured' };
 }
 
-async function deliverDiscord(ch: OutboundChannelConfig, msg: OutboundMsg, deps: RouterDeps): Promise<ChannelResult> {
+async function deliverDiscord(ch: OutboundChannelConfig, msg: OutboundMsg, _cfg: UserConfig, deps: RouterDeps): Promise<ChannelResult> {
   const fetchImpl = deps.fetchImpl ?? fetch;
   // webhookUrl guaranteed by normalizeOutbound; guard for direct callers.
   if (!ch.webhookUrl) return { type: 'discord', ok: false, error: 'missing-webhook-url' };
@@ -172,7 +275,7 @@ async function deliverDiscord(ch: OutboundChannelConfig, msg: OutboundMsg, deps:
   return { type: 'discord', ok: true };
 }
 
-async function deliverPushcut(ch: OutboundChannelConfig, msg: OutboundMsg, deps: RouterDeps): Promise<ChannelResult> {
+async function deliverPushcut(ch: OutboundChannelConfig, msg: OutboundMsg, _cfg: UserConfig, deps: RouterDeps): Promise<ChannelResult> {
   const fmt = formatForChannel('pushcut', msg);
   const title = fmt.title ?? `elanous ${msg.kind}`;
   if (ch.webhookUrl) {
@@ -194,6 +297,40 @@ async function deliverPushcut(ch: OutboundChannelConfig, msg: OutboundMsg, deps:
   return r.ok ? { type: 'pushcut', ok: true } : { type: 'pushcut', ok: false, error: r.reason ?? 'pushcut-failed' };
 }
 
+/** Built-in channel connectors. Telegram and Discord receive adapters normalize
+ * already-authorized trigger taps; the webhook and Pushcut senders do not poll. */
+export const outboundAdapters: ReadonlyMap<string, ChannelAdapter> = new Map<string, ChannelAdapter>([
+  ['telegram', { type: 'telegram', capabilities: {
+    send: true, receive: true, thread: false, topic: false, persona: false,
+    channelLifecycle: false, permissions: false, commands: false, attachments: false,
+    buttons: false, choices: false, deliveryConfirmation: false, rateLimit: false,
+  }, send: deliverTelegram, receive: (payload): ChannelEnvelope | null => {
+    if (!payload || typeof payload !== 'object') return null;
+    const tap = payload as Record<string, unknown>;
+    if (typeof tap.body !== 'string' || typeof tap.kind !== 'string' || typeof tap.chat !== 'string') return null;
+    return { text: tap.body, kind: tap.kind, channel: tap.chat,
+      ...(typeof tap.user === 'string' ? { senderId: tap.user } : {}),
+      ...(typeof tap.messageId === 'number' ? { messageId: tap.messageId } : {}) };
+  } }],
+  ['discord', { type: 'discord', capabilities: {
+    send: true, receive: true, thread: false, topic: false, persona: false,
+    channelLifecycle: false, permissions: false, commands: false, attachments: false,
+    buttons: false, choices: false, deliveryConfirmation: false, rateLimit: false,
+  }, send: deliverDiscord, receive: (payload): ChannelEnvelope | null => {
+    if (!payload || typeof payload !== 'object') return null;
+    const tap = payload as Record<string, unknown>;
+    if (typeof tap.body !== 'string' || typeof tap.kind !== 'string' || typeof tap.channel !== 'string') return null;
+    return { text: tap.body, kind: tap.kind, channel: tap.channel,
+      ...(typeof tap.user === 'string' ? { senderId: tap.user } : {}),
+      ...(typeof tap.messageId === 'string' ? { messageId: tap.messageId } : {}) };
+  } }],
+  ['pushcut', { type: 'pushcut', capabilities: {
+    send: true, receive: false, thread: false, topic: false, persona: false,
+    channelLifecycle: false, permissions: false, commands: false, attachments: false,
+    buttons: false, choices: false, deliveryConfirmation: false, rateLimit: false,
+  }, send: deliverPushcut }],
+]);
+
 /** Fan one message out to every routed channel. Per-channel fail-soft —
  *  a throwing adapter records `{ok:false}` and never blocks siblings.
  *  구조: 채널별 포맷(format.ts) + 중복 발사 제어·배송 원장(delivery-ledger.ts).
@@ -228,27 +365,75 @@ export async function routeOutbound(cfg: UserConfig, msg: OutboundMsg, deps: Rou
 
   // 상태 파일이 없거나 읽기에 실패하면 기존 kind 경로를 그대로 사용한다.
   let list = resolveChannels(outbound, msg.kind);
+  // Whether the route that decided `list` is explicitly empty — that means «suppress», which is
+  // different from a route whose channels are simply not configured.
+  const kindRoute = outbound ? (outbound.routes?.[msg.kind] ?? outbound.routes?.default) : undefined;
+  let explicitlyEmpty = kindRoute !== undefined && kindRoute.length === 0;
+  const role = msg.role;
+  const roleRoute = role ? outbound?.roleRoutes?.[role] : undefined;
+  if (roleRoute && outbound) {
+    list = outbound.channels.filter(ch => roleRoute.includes(ch.type));
+    explicitlyEmpty = roleRoute.length === 0;
+  }
   if (outbound?.awayRoutes) {
     try {
       if (readPresence().away) {
         const awayRoute = outbound.awayRoutes[msg.kind] ?? outbound.awayRoutes.default;
         // kind 도 default 도 없으면 기존 경로로 · 명시적인 빈 배열은 기존 routes 와 같은 규칙(채널 0)을 따른다.
         if (awayRoute !== undefined) {
-          list = outbound.channels.filter(ch => awayRoute.includes(ch.type));
+          // Away mode narrows the route; it never widens a role's allowed channels.
+          list = outbound.channels.filter(ch => awayRoute.includes(ch.type) && (!roleRoute || roleRoute.includes(ch.type)));
+          // A role's explicitly empty route stays suppressed while away.
+          explicitlyEmpty = awayRoute.length === 0 || roleRoute?.length === 0;
           try { debug.log('outbound.send', 'away-route', { kind: msg.kind, channels: list.map(ch => ch.type) }); } catch { /* 관측 실패는 발송 결과에 영향 없음 */ }
         }
       }
     } catch { /* 상태 조회 실패 — 기존 경로 유지 */ }
   }
-  const channels = await Promise.all(list.map(async (ch): Promise<ChannelResult> => {
+  const send = async (ch: OutboundChannelConfig): Promise<ChannelResult> => {
     try {
-      if (ch.type === 'telegram') return await deliverTelegram(cfg, outMsg, deps);
-      if (ch.type === 'discord') return await deliverDiscord(ch, outMsg, deps);
-      return await deliverPushcut(ch, outMsg, deps);
+      const adapter = deps.adapters?.get(ch.type) ?? outboundAdapters.get(ch.type) ?? installedAdapters.get(ch.type);
+      if (!adapter?.capabilities.send) return { type: ch.type, ok: false, error: 'unsupported-channel' };
+      const result = await adapter.send(ch, outMsg, cfg, deps);
+      // A connector may not impersonate another channel or echo credentials
+      // through the response. Legacy built-in result fields stay unchanged.
+      if (!outboundAdapters.has(ch.type)) return { type: ch.type, ok: result.ok,
+        ...(result.ok ? {} : { error: 'delivery-failed' }) };
+      return { ...result, type: ch.type };
     } catch (e) {
-      return { type: ch.type, ok: false, error: e instanceof Error ? e.message : String(e) };
+      // Connector exceptions may include secret-bearing URLs or configuration.
+      // Keep the old built-in error reasons unless they expose the webhook;
+      // a plugin's arbitrary configuration cannot safely be echoed at all.
+      const reason = e instanceof Error ? e.message : String(e);
+      const plugin = !outboundAdapters.has(ch.type);
+      return { type: ch.type, ok: false,
+        error: plugin || (ch.webhookUrl && reason.includes(ch.webhookUrl)) ? 'delivery-failed' : reason };
     }
-  }));
+  };
+  const primaryType = (role ? outbound?.primary?.[role] : undefined) ?? outbound?.primary?.[msg.kind] ?? outbound?.primary?.default;
+  const fallbackType = (role ? outbound?.fallback?.[role] : undefined) ?? outbound?.fallback?.[msg.kind] ?? outbound?.fallback?.default;
+  // Legacy routes still fan out. An explicit primary switches only this kind/role to ordered
+  // failover: main, then the configured backup — never the rest of the route. A selected channel
+  // that the current route does not carry is recorded as not-routed and the backup is tried.
+  // An explicitly empty route stays suppressed (no rows).
+  // Only an explicitly empty route suppresses the selection entirely (no rows).
+  const suppressed = list.length === 0 && explicitlyEmpty;
+  let channels: ChannelResult[];
+  if (suppressed) {
+    channels = [];
+  } else if (primaryType) {
+    channels = [];
+    for (const type of fallbackType && fallbackType !== primaryType ? [primaryType, fallbackType] : [primaryType]) {
+      const ch = list.find(candidate => candidate.type === type);
+      const result = ch ? await send(ch) : { type, ok: false, error: 'not-routed' };
+      channels.push(result);
+      if (result.ok) break;
+    }
+  } else {
+    // A backup without a main has nothing to back up: the allowed route already fans out to every
+    // channel it may reach, and a backup outside that route must not bypass role/away limits.
+    channels = await Promise.all(list.map(send));
+  }
 
   // 배송 기록(리드 동기화·중복 제어 토대) — fail-soft.
   if (ledger) {