elanous 0.2.6 → 0.2.7

package/src/policy/llm-policy.ts

@@ -0,0 +1,268 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { isScalar, parseDocument } from 'yaml';
+import { getElanousConfigDir } from '../elanous-config-dir.js';
+import { DEFAULT_FALLBACK_CHAIN, isFallbackStep, type FallbackStep } from '../oauth/fallback-chain.js';
+import { isCodexQuotaPolicy } from '../oauth/codex-quota-policy.js';
+import { DEFAULT_BUDGET_GATE_MAX_USED_PERCENT, MODEL_ROLES, RUNTIME_LLM_PROVIDER_NAMES, parseRoleLlmEntry, type RoleLlmConfig } from '../user-config.js';
+
+export interface LlmPolicy {
+  version: 1;
+  default: { provider: string; model?: string };
+  roles: RoleLlmConfig;
+  fallback: FallbackStep[];
+  accounts: { codex: {
+    order: string[];
+    rotateAtPercent: number;
+    perAccount: Record<string, { rotateAtPercent: number; until?: string; why?: string }>;
+    rotationEnabled: boolean;
+  } };
+  credits: {
+    codex: 'use' | 'fallback' | 'never';
+    grants: Array<{ account: string; amount: number; expires: string; source: string }>;
+    pace?: { targetPerDay: number; until: string; why?: string };
+  };
+  caps: { codex: { harness: number; pod: number; tox: number; intake: number; headroom: number }; grok: { weekly: number; tox: number; intake: number } };
+  resetCredits: { redeem: 'human' };
+  alerts: { lowRemainingPercent: number; resetCreditExpiryDays: number; creditsStep: number };
+}
+
+export type LlmPolicySource = 'default' | 'legacy-config' | 'file';
+export interface LlmPolicyValidation {
+  valid: boolean;
+  errors: string[];
+  warnings: string[];
+}
+export interface LoadedLlmPolicy extends LlmPolicyValidation {
+  policy: LlmPolicy;
+  sources: Record<string, LlmPolicySource>;
+  path: string;
+  filePresent: boolean;
+}
+export interface LoadLlmPolicyOptions {
+  /** All file IO remains scoped to this directory; tests can pass a temporary directory. */
+  configDir?: string;
+  path?: string;
+  /** An already-read legacy config; when omitted the sibling config.json is read directly. */
+  legacyConfig?: unknown;
+  now?: Date;
+}
+
+type Obj = Record<string, unknown>;
+const object = (v: unknown): v is Obj => v !== null && typeof v === 'object' && !Array.isArray(v);
+const percent = (v: unknown): v is number => typeof v === 'number' && Number.isFinite(v) && v >= 0 && v <= 100;
+const nonempty = (v: unknown): v is string => typeof v === 'string' && v.trim().length > 0;
+const positive = (v: unknown): v is number => typeof v === 'number' && Number.isFinite(v) && v > 0;
+const date = (v: unknown): v is string => typeof v === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(v) && !Number.isNaN(Date.parse(`${v}T00:00:00Z`)) && new Date(`${v}T00:00:00Z`).toISOString().slice(0, 10) === v;
+
+function setOwn(target: Obj, key: string, value: unknown): void {
+  Object.defineProperty(target, key, { value, configurable: true, enumerable: true, writable: true });
+}
+
+/** Today's code defaults, not a snapshot of one machine's user config. */
+export function defaultLlmPolicy(): LlmPolicy {
+  return {
+    version: 1,
+    default: { provider: 'auto' },
+    roles: {},
+    fallback: [...DEFAULT_FALLBACK_CHAIN],
+    accounts: { codex: { order: [], rotateAtPercent: 95, perAccount: { default: { rotateAtPercent: 60 } }, rotationEnabled: true } },
+    credits: { codex: 'fallback', grants: [] },
+    caps: {
+      codex: { harness: DEFAULT_BUDGET_GATE_MAX_USED_PERCENT['openai-codex']!, pod: 95, tox: 60, intake: 80, headroom: 15 },
+      grok: { weekly: DEFAULT_BUDGET_GATE_MAX_USED_PERCENT.grok!, tox: 50, intake: 48 },
+    },
+    resetCredits: { redeem: 'human' },
+    alerts: { lowRemainingPercent: 10, resetCreditExpiryDays: 7, creditsStep: 5000 },
+  };
+}
+
+function leafPaths(value: unknown, prefix = ''): string[] {
+  if (!object(value) || Object.keys(value).length === 0) return prefix ? [prefix] : [];
+  return Object.entries(value).flatMap(([key, item]) => leafPaths(item, prefix ? `${prefix}.${key}` : key));
+}
+
+/** Validate the partial policy document. Unknown fields and invalid values are errors, not silent overrides. */
+export function validateLlmPolicy(input: unknown): LlmPolicyValidation {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+  if (!object(input)) return { valid: false, errors: ['policy must be a mapping'], warnings };
+  const check = (node: unknown, path: string, schema: Obj): void => {
+    if (!object(node)) { errors.push(`${path} must be a mapping`); return; }
+    for (const [key, value] of Object.entries(node)) {
+      if (!Object.hasOwn(schema, key)) { errors.push(`unknown field ${path}.${key}`); continue; }
+      const rule = schema[key];
+      if (object(rule)) check(value, `${path}.${key}`, rule);
+      else if (typeof rule === 'function' && !(rule as (v: unknown) => boolean)(value)) errors.push(`${path}.${key} is invalid`);
+    }
+  };
+  const dateField = (v: unknown) => date(v);
+  const perAccount = (v: unknown) => object(v) && Object.entries(v).every(([key, row]) => nonempty(key) && object(row)
+    && Object.keys(row).every(k => ['rotateAtPercent', 'until', 'why'].includes(k))
+    && percent(row.rotateAtPercent) && (row.until === undefined || date(row.until)) && (row.why === undefined || nonempty(row.why)));
+  const grants = (v: unknown) => Array.isArray(v) && v.every(g => object(g)
+    && Object.keys(g).every(k => ['account', 'amount', 'expires', 'source'].includes(k))
+    && nonempty(g.account) && positive(g.amount) && date(g.expires) && nonempty(g.source));
+  const roles = (v: unknown) => object(v) && Object.entries(v).every(([role, spec]) => MODEL_ROLES.some(r => r === role)
+    && object(spec) && Object.keys(spec).every(k => ['provider', 'tier', 'model'].includes(k)) && parseRoleLlmEntry(spec).ok);
+  check(input, 'policy', {
+    version: (v: unknown) => v === 1,
+    default: { provider: (v: unknown) => nonempty(v) && RUNTIME_LLM_PROVIDER_NAMES.some(p => p === v), model: nonempty },
+    roles,
+    fallback: (v: unknown) => Array.isArray(v) && v.length > 0 && v.every(isFallbackStep) && new Set(v).size === v.length,
+    accounts: { codex: {
+      order: (v: unknown) => Array.isArray(v) && v.every(nonempty) && new Set(v).size === v.length,
+      rotateAtPercent: percent, perAccount, rotationEnabled: (v: unknown) => typeof v === 'boolean',
+    } },
+    credits: {
+      codex: (v: unknown) => v === 'use' || v === 'fallback' || v === 'never',
+      grants,
+      pace: (v: unknown) => object(v) && positive(v.targetPerDay) && dateField(v.until)
+        && (v.why === undefined || nonempty(v.why))
+        && Object.keys(v).every(k => ['targetPerDay', 'until', 'why'].includes(k)),
+    },
+    caps: { codex: { harness: percent, pod: percent, tox: percent, intake: percent, headroom: percent },
+      grok: { weekly: percent, tox: percent, intake: percent } },
+    resetCredits: { redeem: (v: unknown) => v === 'human' },
+    alerts: { lowRemainingPercent: percent, resetCreditExpiryDays: positive, creditsStep: positive },
+  });
+  if (input.version !== undefined && input.version !== 1) warnings.push('unsupported policy version');
+  return { valid: errors.length === 0, errors, warnings };
+}
+
+function merge(base: Obj, overlay: Obj, sources: Record<string, LlmPolicySource>, source: LlmPolicySource, prefix = ''): void {
+  for (const [key, value] of Object.entries(overlay)) {
+    const path = prefix ? `${prefix}.${key}` : key;
+    if (object(value) && Object.hasOwn(base, key) && object(base[key])) merge(base[key] as Obj, value, sources, source, path);
+    else {
+      setOwn(base, key, value !== null && typeof value === 'object' ? structuredClone(value) : value);
+      for (const leaf of leafPaths(value, path)) setOwn(sources, leaf, source);
+    }
+  }
+}
+
+/** The date is inclusive: a rule with until=2026-10-29 remains active through that UTC day. */
+function removeExpired(input: Obj, now: Date, warnings: string[], prefix = ''): void {
+  for (const [key, value] of Object.entries(input)) {
+    const path = prefix ? `${prefix}.${key}` : key;
+    if (path === 'credits.grants' && Array.isArray(value)) {
+      input[key] = value.filter(grant => {
+        if ((grant as { expires: string }).expires >= now.toISOString().slice(0, 10)) return true;
+        warnings.push(`${path} ${String((grant as { account: string }).account)} expired on ${String((grant as { expires: string }).expires)}; ignored`);
+        return false;
+      });
+      continue;
+    }
+    if (!object(value)) continue;
+    if (typeof value.until === 'string' && date(value.until) && value.until < now.toISOString().slice(0, 10)) {
+      delete input[key];
+      warnings.push(`${path} expired on ${value.until}; ignored`);
+    } else removeExpired(value, now, warnings, path);
+  }
+}
+
+export function loadLlmPolicy(opts: LoadLlmPolicyOptions = {}): LoadedLlmPolicy {
+  const configDir = opts.configDir ?? getElanousConfigDir();
+  const path = opts.path ?? join(configDir, 'policy', 'llm.yaml');
+  const policy = defaultLlmPolicy();
+  const sources: Record<string, LlmPolicySource> = Object.fromEntries(leafPaths(policy).map(p => [p, 'default']));
+  const warnings: string[] = [];
+  const errors: string[] = [];
+  let legacy: unknown = opts.legacyConfig;
+  if (legacy === undefined) {
+    const legacyPath = join(configDir, 'config.json');
+    try { legacy = JSON.parse(readFileSync(legacyPath, 'utf8')); }
+    catch (error) {
+      if (!(error instanceof Error && 'code' in error && error.code === 'ENOENT')) {
+        warnings.push(`legacy config ${legacyPath} could not be loaded: ${error instanceof Error ? error.message : String(error)}`);
+      }
+      legacy = {};
+    }
+  }
+  if (object(legacy)) {
+    const llm = object(legacy.llm) ? legacy.llm : {};
+    const overlay: Obj = {};
+    const add = (key: string, value: unknown, target: Obj, targetKey: string, valid: (v: unknown) => boolean): void => {
+      if (value === undefined) return;
+      if (valid(value)) { setOwn(target, targetKey, value); warnings.push(`legacy config ${key} applies; migrate to policy/llm.yaml`); }
+      else warnings.push(`legacy config ${key} is invalid; ignored`);
+    };
+    const base: Obj = {};
+    add('llm.provider', llm.provider, base, 'provider', v => nonempty(v) && RUNTIME_LLM_PROVIDER_NAMES.some(p => p === v));
+    add('llm.model', llm.model, base, 'model', nonempty);
+    if (Object.keys(base).length) overlay.default = base;
+    add('roleLlm', legacy.roleLlm, overlay, 'roles', v => object(v) && Object.entries(v).every(([r, spec]) => MODEL_ROLES.some(k => k === r) && parseRoleLlmEntry(spec).ok));
+    add('llm.fallbackChain', llm.fallbackChain, overlay, 'fallback', v => Array.isArray(v) && v.length > 0 && v.every(isFallbackStep) && new Set(v).size === v.length);
+    const codex: Obj = {};
+    add('llm.codexAccountOrder', llm.codexAccountOrder, codex, 'order', v => Array.isArray(v) && v.every(nonempty));
+    add('llm.codexAccountRotation', llm.codexAccountRotation, codex, 'rotationEnabled', v => typeof v === 'boolean');
+    add('llm.codexAccountRotationThresholdPercent', llm.codexAccountRotationThresholdPercent, codex, 'rotateAtPercent', percent);
+    if (object(llm.codexAccountRotationThresholdPercentByAccount)) {
+      const rows: Obj = {};
+      for (const [account, value] of Object.entries(llm.codexAccountRotationThresholdPercentByAccount)) {
+        add(`llm.codexAccountRotationThresholdPercentByAccount.${account}`, value, rows, account, percent);
+        if (Object.hasOwn(rows, account)) setOwn(rows, account, { rotateAtPercent: rows[account] });
+      }
+      if (Object.keys(rows).length) codex.perAccount = rows;
+    }
+    if (Object.keys(codex).length) overlay.accounts = { codex };
+    const credits: Obj = {};
+    if (llm.codexQuotaPolicy !== undefined) {
+      if (isCodexQuotaPolicy(llm.codexQuotaPolicy)) {
+        credits.codex = { credits: 'use', fallback: 'fallback', 'within-quota': 'never' }[llm.codexQuotaPolicy];
+        warnings.push('legacy config llm.codexQuotaPolicy applies; migrate to policy/llm.yaml');
+      } else warnings.push('legacy config llm.codexQuotaPolicy is invalid; ignored');
+    }
+    if (credits.codex === undefined && llm.codexCreditsAllowed === true) {
+      credits.codex = 'use';
+      warnings.push('legacy config llm.codexCreditsAllowed applies; migrate to policy/llm.yaml');
+    }
+    if (Object.keys(credits).length) overlay.credits = credits;
+    const gate = object(legacy.harness) && object(legacy.harness.budgetGate) ? legacy.harness.budgetGate : {};
+    const caps: Obj = {};
+    const harness: Obj = {};
+    add('harness.budgetGate.minHeadroomPercent', gate.minHeadroomPercent, harness, 'headroom', percent);
+    if (object(gate.maxUsedPercent)) {
+      add('harness.budgetGate.maxUsedPercent.openai-codex', gate.maxUsedPercent['openai-codex'], harness, 'harness', percent);
+      const grok: Obj = {};
+      add('harness.budgetGate.maxUsedPercent.grok', gate.maxUsedPercent.grok, grok, 'weekly', percent);
+      if (Object.keys(grok).length) caps.grok = grok;
+    }
+    if (Object.keys(harness).length) caps.codex = harness;
+    if (Object.keys(caps).length) overlay.caps = caps;
+    merge(policy as unknown as Obj, overlay, sources, 'legacy-config');
+  }
+  // Read directly: `existsSync` is also false when the folder cannot be searched (EACCES), which would
+  // report an unreadable policy as «no file · valid». Only ENOENT/ENOTDIR mean the file is absent.
+  let raw: string | undefined;
+  let filePresent = false;
+  try {
+    raw = readFileSync(path, 'utf8');
+    filePresent = true;
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code !== 'ENOENT' && code !== 'ENOTDIR') {
+      filePresent = true;
+      errors.push(`cannot read policy file ${path}: ${code ?? (error instanceof Error ? error.message : String(error))}`);
+    }
+  }
+  if (raw !== undefined) {
+    try {
+      const doc = parseDocument(raw, { uniqueKeys: true });
+      if (doc.errors.length) throw new Error(doc.errors.map(e => e.message).join('; '));
+      const emptyDocument = doc.contents === null || (isScalar(doc.contents) && doc.contents.type === 'PLAIN' && doc.contents.source === '');
+      const parsed: unknown = emptyDocument ? {} : doc.toJS();
+      const validation = validateLlmPolicy(parsed);
+      errors.push(...validation.errors);
+      warnings.push(...validation.warnings);
+      if (validation.valid && object(parsed)) {
+        const filtered = structuredClone(parsed);
+        removeExpired(filtered, opts.now ?? new Date(), warnings);
+        merge(policy as unknown as Obj, filtered, sources, 'file');
+      }
+    } catch (error) {
+      errors.push(`invalid policy file ${path}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  return { policy, sources, path, filePresent, valid: errors.length === 0, errors, warnings };
+}

package/src/prompt-library/session-guidance.ts

@@ -115,9 +115,15 @@ export function buildSessionGuidanceAddendum(
   }
 
   if (items.length === 0) return [];
+  // B4 — 파일 수 규칙. 명령을 실제로 돌릴 도구(Bash·PtyShellStart·WebTerminal*)가 있을 때만 `git ls-files` 로 세라고 하고,
+  // Read 만 켜진 세션에선 셀 수 없으니 추측하지 말고 확인 불가라고 답하게 한다(EVAL q09 «959» vs 실측 778 · 리뷰 3라운드 must-fix).
+  const canRunCommands = enabledTools.some(name => /^(Bash|PtyShellStart|WebTerminal)/.test(name));
+  const fileCountRule = canRunCommands
+    ? '저장소의 파일 수·목록은 저장소 루트에서 `git ls-files <경로>`로 추적 파일 기준으로 센다 — 하위 디렉터리에서 실행 중이면 저장소 루트로 이동해서 세고, 다른 기준이면 그 기준을 답에 적는다.'
+    : '이 세션에는 명령을 실행할 도구가 없다 — 저장소의 파일 수는 추측하지 말고 «이 모드에서는 셀 수 없다»고 답한다(도구로 센 목록이 대화에 있으면 그 기준을 밝히고 쓴다).';
   return [{
     role: 'system',
-    content: '# Session-specific guidance\n\n' +
+    content: `${fileCountRule}\n\n` + '# Session-specific guidance\n\n' +
       items.map(s => `- ${s}`).join('\n'),
   }];
 }

package/src/prompt-library/universal-preamble.ts

@@ -60,8 +60,8 @@ export const PROJECT_TREE_MAX_CHARS = 8 * 1024;
 export const PROJECT_TREE_DIR_ENTRY_LIMIT = 20;
 
 const NO_TOOLS_VERIFICATION_GUIDANCE = `## Chat without tools — verify rather than guess
-This conversation has tools disabled. Do not guess repository or real-time facts that require verification, such as file counts, file contents, commits, or the current time. Say you cannot check them here. The project tree above is for navigation, not evidence for counts.
-To check these facts, enable tools with \`elanous agent …\` or \`elanous chat --tools …\`.`;
+This conversation has tools disabled. Do not guess repository or real-time facts that require verification, such as file counts, file contents, commits, or the current date or time. When asked for facts you cannot verify here (including repository state, files, and dates), explicitly say you cannot check them in this mode. The project tree above is for navigation, not evidence for counts.
+Give one line explaining how to enable tools: \`elanous agent "<your question>"\`.`;
 
 // P4 (2026-05-03) — Family-agnostic coding-agent lifecycle. Maps the
 // three user-facing pipelines to an explicit tool-batch sequence so every

package/src/relay/relay-cli.ts

@@ -0,0 +1,20 @@
+import type { Command } from 'commander';
+
+/** `elanous relay serve` — 릴레이 서버(R2 · 내부 문서 `RFC-mobile-relay-without-tailscale-2026-09-30` A5).
+ *  index.ts 원문을 잘라 보는 시험(첫 `.command('serve')` = mcp)을 흔들지 않게 등록을 여기 둔다. */
+export function registerRelayCommand(program: Command): void {
+  const relayCmd = program.command('relay').description('Encrypted WebSocket relay');
+  relayCmd.command('serve')
+    .description('Serve paired relay connections using operator-provisioned host signing keys')
+    .requiredOption('--trusted-host-keys <file>', 'JSON object of X25519-derived serverId to Ed25519 public key (base64url)')
+    .option('--port <port>', 'Listening port', '8765')
+    .action(async (opts: { trustedHostKeys: string; port: string }) => {
+      const port = Number(opts.port);
+      if (!Number.isInteger(port) || port < 0 || port > 65535) throw new Error('invalid relay port');
+      const { loadTrustedHostKeys, startRelayServer } = await import('./relay-server.js');
+      const relay = startRelayServer({ port, trustedHostKeys: loadTrustedHostKeys(opts.trustedHostKeys) });
+      console.log(`relay listening on 127.0.0.1:${relay.port}`);
+      process.once('SIGINT', () => { relay.stop(); });
+      process.once('SIGTERM', () => { relay.stop(); });
+    });
+}

package/src/relay/relay-server.ts

@@ -0,0 +1,220 @@
+import { createPublicKey, randomBytes, verify } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import type { ServerWebSocket } from 'bun';
+import { MAX_FRAME_BYTES } from './channel.js';
+
+const ED25519_SPKI_PREFIX = Buffer.from('302a300506032b6570032100', 'hex');
+const MAX_CLIENTS_PER_SERVER = 8;
+const BYTES_PER_SECOND = 1024 * 1024;
+const BURST_BYTES = 2 * BYTES_PER_SECOND;
+const PING_INTERVAL_MS = 30_000;
+const DEAD_PEER_MS = 90_000;
+const AUTH_TIMEOUT_MS = 10_000;
+
+type SocketData = { role: 'host' | 'client'; serverId: string; clientId?: number; challenge?: string; authenticated: boolean; lastSeen: number; tokens: number; refillAt: number; authTimer?: ReturnType<typeof setTimeout> };
+type Socket = ServerWebSocket<SocketData>;
+type Room = { host?: Socket; clients: Map<number, Socket>; nextId: number; bytes: number; failures: Record<string, number> };
+
+export interface RelayServerOptions {
+  port?: number;
+  hostname?: string;
+  /** Ed25519 signing public keys (base64url raw 32 bytes), pinned by X25519-derived serverId. */
+  trustedHostKeys?: ReadonlyMap<string, string>;
+}
+
+/** Load operator-provisioned pins, never keys claimed by connecting hosts. */
+export function loadTrustedHostKeys(file: string): ReadonlyMap<string, string> {
+  const raw: unknown = JSON.parse(readFileSync(file, 'utf8'));
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) throw new Error('invalid relay trusted host keys');
+  const result = new Map<string, string>();
+  for (const [id, key] of Object.entries(raw)) {
+    if (!/^[a-f0-9]{64}$/.test(id) || typeof key !== 'string' || !decodeKey(key)) {
+      throw new Error('invalid relay trusted host key entry');
+    }
+    result.set(id, key);
+  }
+  return result;
+}
+
+export function challengeMessage(serverId: string, nonce: string): Uint8Array {
+  return Buffer.from(`elanous-relay-v1:${serverId}:${nonce}`, 'utf8');
+}
+
+function decodeKey(value: string): Buffer | undefined {
+  if (!/^[A-Za-z0-9_-]{43}$/.test(value)) return undefined;
+  const decoded = Buffer.from(value, 'base64url');
+  return decoded.length === 32 && decoded.toString('base64url') === value ? decoded : undefined;
+}
+
+function encodeClientId(id: number, payload: Uint8Array): Uint8Array {
+  const result = new Uint8Array(payload.length + 4);
+  new DataView(result.buffer).setUint32(0, id, false);
+  result.set(payload, 4);
+  return result;
+}
+
+/** The relay never parses or logs encrypted channel payloads. Host binary frames carry a
+ * four-byte big-endian clientId prefix; phone binary frames are raw ciphertext. */
+export function startRelayServer(options: RelayServerOptions = {}) {
+  if (!options.trustedHostKeys?.size) throw new Error('relay trusted host keys required');
+  const trustedHostKeys = new Map(options.trustedHostKeys);
+  for (const [id, key] of trustedHostKeys) {
+    if (!/^[a-f0-9]{64}$/.test(id) || !decodeKey(key)) throw new Error('invalid relay trusted host key entry');
+  }
+  const rooms = new Map<string, Room>();
+  const sockets = new Set<Socket>();
+  const roomFor = (id: string): Room => {
+    let room = rooms.get(id);
+    if (!room) { room = { clients: new Map(), nextId: 1, bytes: 0, failures: {} }; rooms.set(id, room); }
+    return room;
+  };
+  const fail = (room: Room, reason: string) => { room.failures[reason] = (room.failures[reason] ?? 0) + 1; };
+  const sendControl = (ws: Socket, value: object) => { if (ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify(value)); };
+  const drop = (ws: Socket) => {
+    const data = ws.data;
+    if (data.authTimer) clearTimeout(data.authTimer);
+    sockets.delete(ws);
+    const room = rooms.get(data.serverId);
+    if (!room) return;
+    if (!data.authenticated) {
+      if (!room.host && room.clients.size === 0 &&
+          !Array.from(sockets).some(peer => peer.data.serverId === data.serverId)) rooms.delete(data.serverId);
+      return;
+    }
+    if (data.role === 'host' && room.host === ws) {
+      room.host = undefined;
+      const clients = [...room.clients.values()];
+      room.clients.clear();
+      for (const client of clients) client.close(1012, 'host disconnected');
+    } else if (data.role === 'client' && data.clientId !== undefined && room.clients.get(data.clientId) === ws) {
+      room.clients.delete(data.clientId);
+      if (room.host) sendControl(room.host, { type: 'client-disconnected', clientId: data.clientId });
+    }
+    if (!room.host && room.clients.size === 0 &&
+        !Array.from(sockets).some(peer => peer.data.serverId === data.serverId)) rooms.delete(data.serverId);
+  };
+  const capacity = (ws: Socket, length: number): boolean => {
+    const data = ws.data;
+    const now = Date.now();
+    data.tokens = Math.min(BURST_BYTES, data.tokens + (now - data.refillAt) * BYTES_PER_SECOND / 1000);
+    data.refillAt = now;
+    if (length > data.tokens) return false;
+    data.tokens -= length;
+    return true;
+  };
+  const server = Bun.serve<SocketData>({
+    hostname: options.hostname ?? '127.0.0.1', port: options.port ?? 0,
+    fetch(req, server) {
+      const url = new URL(req.url);
+      if (url.pathname !== '/host' && url.pathname !== '/client') return new Response('not found', { status: 404 });
+      const serverId = url.searchParams.get('serverId');
+      if (!serverId || !/^[a-f0-9]{64}$/.test(serverId)) return new Response('invalid serverId', { status: 400 });
+      if (!trustedHostKeys.has(serverId)) return new Response('unknown serverId', { status: 403 });
+      if (req.headers.get('upgrade')?.toLowerCase() !== 'websocket') return new Response('upgrade required', { status: 426 });
+      const role = url.pathname === '/host' ? 'host' : 'client';
+      const now = Date.now();
+      if (!server.upgrade(req, { data: { role, serverId, authenticated: false, lastSeen: now, tokens: BURST_BYTES, refillAt: now } })) {
+        return new Response('upgrade required', { status: 426 });
+      }
+      return undefined;
+    },
+    websocket: {
+      maxPayloadLength: MAX_FRAME_BYTES + 4,
+      open(ws) {
+        sockets.add(ws);
+        const data = ws.data;
+        const room = roomFor(data.serverId);
+        if (data.role === 'host') {
+          if (room.host) { fail(room, 'duplicate-host'); ws.close(1008, 'host already connected'); return; }
+          data.challenge = randomBytes(32).toString('base64url');
+          sendControl(ws, { type: 'challenge', nonce: data.challenge });
+        } else {
+          if (!room.host || room.clients.size >= MAX_CLIENTS_PER_SERVER) {
+            fail(room, !room.host ? 'host-offline' : 'client-limit');
+            ws.close(1008, !room.host ? 'host offline' : 'client limit reached');
+            return;
+          }
+          const id = room.nextId++;
+          data.clientId = id;
+          data.authenticated = true;
+          room.clients.set(id, ws);
+          sendControl(ws, { type: 'connected', clientId: id });
+          sendControl(room.host, { type: 'client-connected', clientId: id });
+        }
+        if (!data.authenticated) data.authTimer = setTimeout(() => ws.close(1008, 'authentication timeout'), AUTH_TIMEOUT_MS);
+      },
+      message(ws, message) {
+        const data = ws.data;
+        const room = rooms.get(data.serverId);
+        if (!room) { ws.close(1008, 'room missing'); return; }
+        data.lastSeen = Date.now();
+        if (!data.authenticated) {
+          if (data.role !== 'host' || typeof message !== 'string') { fail(room, 'invalid-auth'); ws.close(1008, 'authentication required'); return; }
+          let auth: unknown;
+          try { auth = JSON.parse(message); } catch { /* reject below */ }
+          const value = auth as { type?: unknown; publicKey?: unknown; signature?: unknown } | undefined;
+          const key = typeof value?.publicKey === 'string' ? decodeKey(value.publicKey) : undefined;
+          const signature = typeof value?.signature === 'string' && /^[A-Za-z0-9_-]{86}$/.test(value.signature)
+            ? Buffer.from(value.signature, 'base64url') : undefined;
+          const expected = trustedHostKeys.get(data.serverId);
+          let valid = false;
+          if (value?.type === 'auth' && key && signature?.length === 64 && data.challenge &&
+              value.publicKey === expected) {
+            try {
+              valid = verify(null, challengeMessage(data.serverId, data.challenge),
+                createPublicKey({ key: Buffer.concat([ED25519_SPKI_PREFIX, key]), format: 'der', type: 'spki' }), signature);
+            } catch { /* invalid public key */ }
+          }
+          if (!valid || (room.host && room.host !== ws)) { fail(room, 'invalid-auth'); ws.close(1008, 'invalid host signature'); return; }
+          data.authenticated = true;
+          data.challenge = undefined;
+          if (data.authTimer) clearTimeout(data.authTimer);
+          room.host = ws;
+          sendControl(ws, { type: 'authenticated' });
+          return;
+        }
+        if (typeof message === 'string') { fail(room, 'plaintext-data'); ws.close(1003, 'binary ciphertext required'); return; }
+        const bytes = new Uint8Array(message);
+        if (bytes.length > MAX_FRAME_BYTES + (data.role === 'host' ? 4 : 0) || bytes.length < (data.role === 'host' ? 5 : 1)) {
+          fail(room, 'invalid-frame'); ws.close(1009, 'invalid frame size'); return;
+        }
+        if (!capacity(ws, bytes.length)) { fail(room, 'rate-limit'); ws.close(1008, 'rate limit exceeded'); return; }
+        if (data.role === 'client') {
+          if (!room.host || data.clientId === undefined) { ws.close(1012, 'host offline'); return; }
+          room.bytes += bytes.length;
+          room.host.send(encodeClientId(data.clientId, bytes));
+        } else {
+          if (room.host !== ws) { ws.close(1008, 'host replaced'); return; }
+          const clientId = new DataView(bytes.buffer, bytes.byteOffset, 4).getUint32(0, false);
+          const client = room.clients.get(clientId);
+          if (!client) { fail(room, 'unknown-client'); return; }
+          room.bytes += bytes.length - 4;
+          client.send(bytes.subarray(4));
+        }
+      },
+      pong(ws) { ws.data.lastSeen = Date.now(); },
+      close(ws) { drop(ws); },
+    },
+  });
+  const heartbeat = setInterval(() => {
+    for (const ws of sockets) {
+      if (Date.now() - ws.data.lastSeen > DEAD_PEER_MS) ws.close(1001, 'heartbeat timeout');
+      else ws.ping();
+    }
+  }, PING_INTERVAL_MS);
+  heartbeat.unref();
+  return {
+    server,
+    get port() { return server.port; },
+    stats(serverId: string) {
+      const room = rooms.get(serverId);
+      return room ? { host: !!room.host, clients: room.clients.size, bytes: room.bytes, failures: { ...room.failures } } :
+        { host: false, clients: 0, bytes: 0, failures: {} as Record<string, number> };
+    },
+    stop() {
+      clearInterval(heartbeat);
+      for (const ws of sockets) ws.close(1001, 'relay stopping');
+      server.stop(true);
+    },
+  };
+}

package/src/release-loop/checklist.ts

@@ -4,6 +4,7 @@ import { dirname, join } from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { debug } from '../debug/log.js';
 import { releaseLedgerRoot } from '../instance/resolve.js';
+import { CliUserError } from '../cli/cli-user-error.js';
 
 export type ChecklistStatus = 'green' | 'yellow' | 'red' | 'done';
 export type ChecklistDisposition = 'move' | 'known-issue' | 'block';
@@ -54,7 +55,7 @@ function releasedVersion(): string {
 }
 
 function pathFor(v: string): string {
-  if (!/^\d+\.\d+\.\d+(?:-(?:rc|alpha|beta)\.\d+)?$/.test(v)) throw new Error(`체크리스트 판이 아니다: ${v}`);
+  if (!/^\d+\.\d+\.\d+(?:-(?:rc|alpha|beta)\.\d+)?$/.test(v)) throw new CliUserError(`체크리스트 판이 아니다: ${v}`);
   return join(releaseLedgerRoot(), 'release', v, 'checklist.json');
 }
 
@@ -110,10 +111,10 @@ function change(data: Checklist, id: string, field: string, from: unknown, to: u
 function refresh(data: Checklist): void { data.released = releasedVersion(); data.dev = devVersion(); }
 
 export function addItem(v: string, input: { id: string; title: string; owner?: string }): Checklist {
-  if (!input.id.trim()) throw new Error('칸 id 가 비었다');
-  if (!input.title.trim()) throw new Error('칸 제목이 비었다');
+  if (!input.id.trim()) throw new CliUserError('칸 id 가 비었다');
+  if (!input.title.trim()) throw new CliUserError('칸 제목이 비었다');
   return mutate(v, (data) => {
-    if (data.items.some((item) => item.id === input.id)) throw new Error(`이미 있는 칸: ${input.id}`);
+    if (data.items.some((item) => item.id === input.id)) throw new CliUserError(`이미 있는 칸: ${input.id}`, 'set <id> 로 고친다');
     const by = process.env.ELANOUS_TRACK || 'cli';
     const at = new Date().toISOString();
     const item: ChecklistItem = { id: input.id, title: input.title, status: 'yellow', ...(input.owner !== undefined ? { owner: input.owner } : {}), updatedAt: at, updatedBy: by };
@@ -126,9 +127,9 @@ export function addItem(v: string, input: { id: string; title: string; owner?: s
 export function setItem(v: string, id: string, patch: { status?: ChecklistStatus; evidence?: string; owner?: string; disposition?: ChecklistDisposition }, by: string): Checklist {
   return mutate(v, (data) => {
     const item = data.items.find((i) => i.id === id);
-    if (!item) throw new Error(`없는 칸: ${id}`);
-    if (patch.status !== undefined && !['green', 'yellow', 'red', 'done'].includes(patch.status)) throw new Error(`잘못된 상태: ${patch.status}`);
-    if (patch.disposition !== undefined && !['move', 'known-issue', 'block'].includes(patch.disposition)) throw new Error(`잘못된 처분: ${patch.disposition}`);
+    if (!item) throw new CliUserError(`없는 칸: ${id}`, 'list 로 칸 목록을 본다');
+    if (patch.status !== undefined && !['green', 'yellow', 'red', 'done'].includes(patch.status)) throw new CliUserError(`잘못된 상태: ${patch.status}`);
+    if (patch.disposition !== undefined && !['move', 'known-issue', 'block'].includes(patch.disposition)) throw new CliUserError(`잘못된 처분: ${patch.disposition}`);
     const fields = (['evidence', 'owner', 'status', 'disposition'] as const).filter((field) => patch[field] !== undefined && patch[field] !== item[field]);
     if (fields.length === 0) return false;
     const at = new Date().toISOString();
@@ -147,7 +148,7 @@ export function setItem(v: string, id: string, patch: { status?: ChecklistStatus
 export function removeItem(v: string, id: string, by: string): Checklist {
   return mutate(v, (data) => {
     const index = data.items.findIndex((i) => i.id === id);
-    if (index < 0) throw new Error(`없는 칸: ${id}`);
+    if (index < 0) throw new CliUserError(`없는 칸: ${id}`, 'list 로 칸 목록을 본다');
     const at = new Date().toISOString();
     const [item] = data.items.splice(index, 1);
     change(data, id, 'remove', item, null, by, at);

package/src/self-dev/decompose.ts

@@ -341,6 +341,7 @@ export function buildSelfDevDecomposePrompt(feature: string, maxTasks = DEFAULT_
     '## Rules',
     `- Emit at most ${maxTasks} sub-features. Fewer is better — do NOT over-split, except when a sub-feature mixes ${SELF_DEV_CONCERN_SPLIT_THRESHOLD} or more concern classes — ${SELF_DEV_CONCERN_CLASSES.join(' / ')} — split it into sibling sub-features.`,
     '- SEPARATE DEFINE FROM WIRE: adding a new function/type/export is a SEPARATE task from wiring it into an existing runtime call site. A task that both defines a new symbol AND integrates it across modules tends to leave dead-code (defined but never called) that fails integration gates. Pattern: (a) add the function + its unit test; then (b) a dependent task that wires it into the specific existing call site — name the exact `file.ts:function` to modify.',
+    '- Exception to SEPARATE DEFINE FROM WIRE: Keep a definition and its registration/wiring in the same sub-feature — a handler with its route, a command with its CLI registration, a node with its graph/recipe entry.',
     '- Each sub-feature must be a self-contained, mergeable unit of work.',
     '- `dependsOn`: list the `id`s of sub-features that MUST land first (e.g. a shared',
     '  type/interface before its consumers). Independent sub-features share NO dependency',

package/src/self-dev/dev-pipeline.ts

@@ -1871,7 +1871,10 @@ async function runDevPipelineDispatch(
   observeDevSelection('completion', plan.completion, plan.completionSource, plan.completionSource === 'request' ? spec.completion : undefined, entryRoute, spec.runId, plan.entrance, plan.entranceUnstamped);
   observeDevSelection('autoReview', plan.autoReview, plan.autoReviewSource, plan.autoReviewSource === 'request' ? spec.autoReview : undefined, entryRoute, spec.runId, plan.entrance, plan.entranceUnstamped);
   assertDispatchHonorsOptions(plan); // 미이행 옵션 거부(수락 후 무시 금지)
-  emitHumanProgress(completionAnnouncement(plan.completion), spec.humanReadableOutput !== false, deps.progress);
+  // CHAT1 — a plain chat turn (`interactive`) is not a dev run: its completion/base lines are noise to a person.
+  //   The selection is still observed above; only the human-facing lines are dev-run-only.
+  const devRunLines = plan.dispatch !== 'interactive';
+  if (devRunLines) emitHumanProgress(completionAnnouncement(plan.completion), spec.humanReadableOutput !== false, deps.progress);
   if (spec.notice) emitHumanProgress(spec.notice, spec.humanReadableOutput !== false, deps.progress);
 
   if (plan.dispatch === 'parallel') {
@@ -1899,8 +1902,8 @@ async function runDevPipelineDispatch(
     rule: plan.baseSelection?.rule ?? 'unspecified',
     evidence: plan.baseSelection?.evidence ?? 'not applicable',
   });
-  emitHumanProgress(formatDevBaseSelectionAnnouncement(plan), spec.humanReadableOutput !== false, deps.progress);
-  const nonDefaultBaseWarning = formatDevNonDefaultBaseWarning(plan);
+  if (devRunLines) emitHumanProgress(formatDevBaseSelectionAnnouncement(plan), spec.humanReadableOutput !== false, deps.progress);
+  const nonDefaultBaseWarning = devRunLines ? formatDevNonDefaultBaseWarning(plan) : undefined;
   if (nonDefaultBaseWarning) {
     emitHumanProgress(nonDefaultBaseWarning, spec.humanReadableOutput !== false, deps.progress);
   }