elanous 0.2.22 → 0.2.23

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

@@ -36,6 +36,7 @@ import { parseDiscordEndpoint, isOwnInstanceEndpoint } from '../../session/sessi
 import { createDiscordStreamSink } from '../../session/streaming/discord-stream-sink.js';
 import { splitForDiscord } from '../../discord.js';
 import { formatForDiscord } from '../../discord-markdown.js';
+import { receiveChannelEvent } from '../outbound/router.js';
 
 export interface NexusDiscordTriggerBotOpts {
   /** Bot token (without `Bot ` prefix). Production reads
@@ -109,11 +110,13 @@ export function createDiscordTriggerLogger(
  *  (`src/discord.ts:160-172` comment) so the wire is a near-identity
  *  with `raw` carrying the full gateway payload for debugging. */
 export function toDiscordEvent(tap: DcTriggerEvent): DiscordEvent {
+  const envelope = receiveChannelEvent('discord', tap);
+  if (!envelope || envelope instanceof Promise) throw new Error('discord connector cannot normalize accepted tap');
   return {
     kind: tap.kind,
-    channel: tap.channel,
-    user: tap.user,
-    body: tap.body,
+    channel: envelope.channel ?? tap.channel,
+    user: envelope.senderId ?? tap.user,
+    body: envelope.text,
     raw: tap,
   };
 }

package/src/nexus/api/error-reports.ts

@@ -25,19 +25,21 @@ function storeDir(root: string): string { return join(root, 'error-reports'); }
 /** Removes day folders older than the keep window. Returns how many days were removed. */
 export function pruneErrorReports(root: string, now: number): number {
   const base = storeDir(root);
-  if (!existsSync(base)) return 0;
   let removed = 0;
-  for (const year of readdirSync(base).filter((n) => /^\d{4}$/.test(n))) {
-    for (const month of readdirSync(join(base, year)).filter((n) => /^\d{2}$/.test(n))) {
-      for (const day of readdirSync(join(base, year, month)).filter((n) => /^\d{2}$/.test(n))) {
-        const at = Date.parse(`${year}-${month}-${day}T00:00:00Z`);
-        if (Number.isFinite(at) && now - at > ERROR_REPORT_KEEP_DAYS * DAY_MS + DAY_MS) {
-          rmSync(join(base, year, month, day), { recursive: true, force: true });
-          removed++;
+  if (existsSync(base)) {
+    for (const year of readdirSync(base).filter((n) => /^\d{4}$/.test(n))) {
+      for (const month of readdirSync(join(base, year)).filter((n) => /^\d{2}$/.test(n))) {
+        for (const day of readdirSync(join(base, year, month)).filter((n) => /^\d{2}$/.test(n))) {
+          const at = Date.parse(`${year}-${month}-${day}T00:00:00Z`);
+          if (Number.isFinite(at) && now - at > ERROR_REPORT_KEEP_DAYS * DAY_MS + DAY_MS) {
+            rmSync(join(base, year, month, day), { recursive: true, force: true });
+            removed++;
+          }
         }
       }
     }
   }
+  debug.log('error-report.prune', 'done', { pruned: removed });
   return removed;
 }
 
@@ -77,6 +79,26 @@ function count24h(root: string, dedupe: string, now: number): number {
   return n;
 }
 
+/** Retention without a receipt: prune once at daemon boot and then once a day (the ingest path still prunes too). */
+export function startErrorReportPruneTick(deps: {
+  root?: () => string;
+  now?: () => number;
+  schedule?: (tick: () => void, ms: number) => { unref?: () => void };
+} = {}): { stop(): void } {
+  const root = deps.root ?? effectiveInstanceRoot;
+  const now = deps.now ?? Date.now;
+  const run = (trigger: 'boot' | 'tick') => {
+    // pruneErrorReports emits error-report.prune/done { pruned }; only a failure is logged here.
+    try { pruneErrorReports(root(), now()); }
+    catch (error) { debug.log('error-report.prune', 'failed', { trigger, reason: error instanceof Error ? error.message : String(error) }); }
+  };
+  run('boot');
+  let stopped = false;
+  const handle = (deps.schedule ?? ((tick, ms) => setInterval(tick, ms)))(() => { if (!stopped) run('tick'); }, DAY_MS);
+  handle.unref?.();
+  return { stop: () => { stopped = true; if (!deps.schedule) clearInterval(handle as ReturnType<typeof setInterval>); } };
+}
+
 /** POST /v1/reports/ingest — the caller (router) has already checked the ingest token. */
 export async function handleErrorReportIngest(req: Request, deps: ErrorReportIngestDeps = {}): Promise<Response> {
   const root = (deps.root ?? effectiveInstanceRoot)();

package/src/nexus/api/http-server.ts

@@ -170,6 +170,7 @@ import { handleBuildsGet, parseBuildsPath } from './builds-api.js';
 import { handleHarnessAskPost, handleHarnessAskStatusGet, handleHarnessRunEventsGet, handleHarnessRunScreenGet, handleHarnessRunsGet, handleHarnessStopPost } from './harness-api.js';
 import { handleHarnessRunTraversalGet } from './harness-traversal.js';
 import { handleLoopEdgesGet } from './loop-edges.js';
+import { handleLoopResourcesGet } from './loop-resources.js';
 import { handleFabricPlans, type FabricPlansRouteOpts } from './fabric-plans.js';
 import { dispatchPersonaRoute } from './personas.js';
 import { handleMe, operatorSignal } from './operator.js';
@@ -498,6 +499,8 @@ export interface NexusHttpServerOpts {
   outputs?: OutputsDeps;
   /** Read-only grid measurement seam; omitted in production for live HQ and Pod pool reads. */
   grid?: GridDeps;
+  /** Resource observation seam; production reads the same ORCH traffic decision. */
+  loopResources?: Parameters<typeof handleLoopResourcesGet>[0];
   /** DRAFT-METRIC cached source seam; omitted in production for the process-wide TTL cache. */
   draftMetrics?: DraftMetricsSource;
   decisions?: Pick<DecisionsRouteDeps, 'ledger'>;
@@ -1396,6 +1399,11 @@ export async function routeRequest(
 
   // Same owner auth as the neighbouring GETs (short-lived owner tokens · same-origin PWA); #23932 compared the admin
   // bearer only, so a PWA on a short-lived token got 401 and the loop map stayed empty.
+  if (pathname === '/v1/loops/resources' && method === 'GET') {
+    if (!opts.metaApi) return jsonResponse({ error: 'meta-api-runtime-not-wired' }, 503);
+    if (!checkAuth(req, opts.metaApi)) return jsonResponse({ error: 'unauthorized' }, 401);
+    return handleLoopResourcesGet(opts.loopResources);
+  }
   if (pathname === '/v1/loops/edges' && method === 'GET') {
     if (!opts.metaApi) return jsonResponse({ error: 'meta-api-runtime-not-wired' }, 503);
     if (!checkAuth(req, opts.metaApi)) return jsonResponse({ error: 'unauthorized' }, 401);

package/src/nexus/api/loop-resources.ts

@@ -0,0 +1,42 @@
+import { defaultListHarnessProcesses } from '../../harness/harness-cli-command.js';
+import { devVersion, listChecklist } from '../../release-loop/checklist.js';
+import { listSchedules } from '../../release-loop/release-schedule.js';
+import { releaseLedgerRoot } from '../../instance/resolve.js';
+import { getUserConfig, ORCHESTRATOR_DEFAULTS } from '../../user-config.js';
+import { seatOfTree, trafficTick, TRAFFIC_SEATS, type TrafficCell, type TrafficResult } from '../../loops/orchestrator/traffic.js';
+import { finishAdvice, measureFinish } from '../../loops/orchestrator/finish-rate.js';
+import { jsonResponse } from './json-response.js';
+
+/** Read-only snapshot of the same ORCH traffic decision used by the scheduled tick. */
+export function observeLoopResources(deps: {
+  now?: Date;
+  processes?: ReturnType<typeof defaultListHarnessProcesses>;
+  version?: string;
+  openCells?: readonly TrafficCell[];
+  nextRound?: readonly TrafficCell[];
+  totalSlots?: number;
+} = {}): TrafficResult {
+  const now = deps.now ?? new Date();
+  const cfg = getUserConfig().loops?.orchestrator ?? ORCHESTRATOR_DEFAULTS;
+  const observation = deps.processes ?? defaultListHarnessProcesses();
+  if (observation.status !== 'ok') throw new Error(`process observation ${observation.status}`);
+  const version = deps.version ?? devVersion().replace(/-dev\.\d+$/, '');
+  const upcoming = deps.nextRound === undefined ? listSchedules(releaseLedgerRoot()).filter(row => Date.parse(row.cutAt) > now.getTime())
+    .sort((a, b) => Date.parse(a.cutAt) - Date.parse(b.cutAt)) : [];
+  const currentIndex = upcoming.findIndex(row => row.version === version);
+  const nextVersion = currentIndex < 0 ? upcoming[0]?.version : upcoming[currentIndex + 1]?.version;
+  const totalSlots = deps.totalSlots ?? finishAdvice(measureFinish({}, now),
+    TRAFFIC_SEATS.reduce((sum, seat) => sum + cfg.seatCaps[seat], 0)).launchSlots;
+  return trafficTick({
+    processes: observation.records.map(process => ({ ...process, seat: seatOfTree(process.cwdStatus === 'unknown' ? undefined : process.cwd, cfg) })),
+    now, caps: cfg.seatCaps, openCells: deps.openCells ?? listChecklist(version).items, totalSlots,
+    ...(deps.nextRound !== undefined ? { nextRound: deps.nextRound }
+      : nextVersion ? { nextRound: listChecklist(nextVersion).items } : {}),
+    retainQueuedCells: true,
+  });
+}
+
+export function handleLoopResourcesGet(observe: () => TrafficResult = observeLoopResources): Response {
+  try { return jsonResponse({ resource: observe() }); }
+  catch { return jsonResponse({ error: 'resource-unavailable' }, 503); }
+}

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()

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) {

package/src/oauth/codex-account-rotation.ts

@@ -4,7 +4,7 @@
 //   주간 창이 찬 계정으로 계속 쏘면 런이 「구현 결손」으로 죽는다(그 어휘는 `#7123` 이 냈다).
 //
 // ⛔⭐⭐ **결정 다섯** (대표):
-//   ① 계정 «전환»만 자동이다 — 리셋 크레딧의 실제 소비는 이 판정 밖의 기존 경로가 맡는다.
+//   ① 리셋권 소비는 순수 판정 밖의 적용 경로가 기존 소비 연산으로 맡는다.
 //   ② 기본 ON. config `llm.codexAccountRotation: false` 로 끈다.
 //   ③ 사람이 «명시»한 계정은 전환하지 않는다 — 의도가 이긴다.
 //   ④ 현재 사용률을 모르면 안전한 기본 계정에 고정하지 않는다 — 쓸 후보가 있으면 넘긴다.
@@ -185,23 +185,6 @@ export function decideCodexRotation(input: RotationInput): RotationDecision {
   });
   if (input.explicit) return { reason: 'explicit', candidateCount, accountThresholds };
   if (!input.enabled) return { reason: 'disabled', candidateCount, accountThresholds, ...(input.disabledProvenance ? { disabledProvenance: input.disabledProvenance } : {}) };
-  if (input.creditPace?.active) {
-    const self = input.candidates.find((candidate) => candidate.name === input.current.name);
-    const eligible = (name: string, balance: number | undefined, hasCredits: boolean | undefined, home: string | undefined): boolean =>
-      !!home?.trim() && typeof balance === 'number' && Number.isFinite(balance) && balance > 0
-      && hasCredits !== false && accountThresholds.some((row) => row.name === name
-        && (row.status === 'reached' || row.status === 'threshold-reached'));
-    const currentBalance = input.currentCreditBalance ?? self?.creditBalance;
-    const currentHas = input.currentHasCredits ?? self?.hasCredits;
-    const to = otherCandidates.filter((candidate) => eligible(candidate.name, candidate.creditBalance, candidate.hasCredits, candidate.home))
-      .sort((a, b) => (b.creditBalance! - a.creditBalance!) || (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))[0];
-    if (eligible(input.current.name, currentBalance, currentHas, self?.home ?? input.current.home)) {
-      return { reason: 'credit-pace', candidateCount, accountThresholds };
-    }
-    if (to) {
-      return { reason: 'credit-pace', candidateCount, accountThresholds, to };
-    }
-  }
   const currentUsageUnknown = input.currentReached === undefined && input.currentUsedPercent == null;
   if (input.currentReached !== true && !currentUsageUnknown && accountThresholds[0]?.status !== 'threshold-reached') {
     return { reason: 'not-reached', candidateCount, accountThresholds };
@@ -232,6 +215,21 @@ export function decideCodexRotation(input: RotationInput): RotationDecision {
   const to = usable[0];
   if (!to) {
     if (input.resetCreditAvailability === 'available') return { reason: 'reset-credit-available', candidateCount, accountThresholds };
+    if (input.creditPace?.active) {
+      const self = input.candidates.find((candidate) => candidate.name === input.current.name);
+      const eligible = (name: string, balance: number | undefined, hasCredits: boolean | undefined, home: string | undefined): boolean =>
+        !!home?.trim() && typeof balance === 'number' && Number.isFinite(balance) && balance > 0
+        && hasCredits !== false && accountThresholds.some((row) => row.name === name
+          && (row.status === 'reached' || row.status === 'threshold-reached'));
+      const currentBalance = input.currentCreditBalance ?? self?.creditBalance;
+      const currentHas = input.currentHasCredits ?? self?.hasCredits;
+      const richest = otherCandidates.filter((candidate) => eligible(candidate.name, candidate.creditBalance, candidate.hasCredits, candidate.home))
+        .sort((a, b) => (b.creditBalance! - a.creditBalance!) || (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))[0];
+      if (eligible(input.current.name, currentBalance, currentHas, self?.home ?? input.current.home)) {
+        return { reason: 'credit-pace', candidateCount, accountThresholds };
+      }
+      if (richest) return { reason: 'credit-pace', candidateCount, accountThresholds, to: richest };
+    }
     // 대표 크레딧 허가: 구독 잔량이 남은 계정이 없으면 크레딧으로 계속 — 한도가 찬 요청은 서버가 선불 크레딧으로 넘긴다.
     // 🩸 09-28 실측: default 크레딧만 시간당 ~5,200 씩 줄고 team·third(합 ~5.5만)는 0 — «지금 계정에 머문다»만으로는
     //   한 계정 크레딧이 바닥나면 남은 크레딧을 두고 폴백(grok)으로 갔다. ⇒ 크레딧이 «더 많이» 남은 계정으로 옮긴다.