elanous 0.2.0 → 0.2.5

package/src/dashboard/slash-runtime/design-pick.ts

@@ -0,0 +1,96 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { applyDesignDirection } from '../../design/apply-direction.js';
+import { listAllDesignDirections, parseDeclaredDirection } from '../../design/design-directions.js';
+import { debug } from '../../debug/log.js';
+import { resolveRepositoryRoot } from '../../self-implement/repo-provision.js';
+import { getSessionCwd } from '../../session/working-dir.js';
+
+interface DesignPickDeps {
+  list: typeof listAllDesignDirections;
+  apply: typeof applyDesignDirection;
+  repositoryRoot: (cwd: string) => string | undefined;
+  cwd: () => string;
+  readDocument: (path: string) => string;
+}
+
+const liveDeps: DesignPickDeps = {
+  list: listAllDesignDirections,
+  apply: applyDesignDirection,
+  repositoryRoot: resolveRepositoryRoot,
+  cwd: getSessionCwd,
+  readDocument: (path) => readFileSync(path, 'utf8'),
+};
+
+/** Numbering and selection share one ordered snapshot of the canonical direction list. */
+export function handleDesignPick(
+  args: readonly string[],
+  ctx: { chatLines: string[]; setChatScrollOffset: (offset: number) => void },
+  overrides: Partial<DesignPickDeps> = {},
+): void {
+  const deps = { ...liveDeps, ...overrides };
+  const reply = (line: string) => {
+    ctx.chatLines.push(line);
+    ctx.setChatScrollOffset(-1);
+  };
+  const requested = args[0];
+  const root = deps.repositoryRoot(deps.cwd());
+  if (requested !== undefined && !root) {
+    debug.log('design.pick', 'refused', { id: requested, reason: 'no-repository' });
+    reply('디자인 방향을 적용할 수 없습니다 — 현재 작업 디렉터리가 git 저장소가 아닙니다.');
+    return;
+  }
+
+  const available = deps.list();
+  const ordered = [
+    ...available.filter((d) => d.source === 'design-system'),
+    ...available.filter((d) => d.source !== 'design-system'),
+  ];
+  if (requested === undefined) {
+    let declared: string | null = null;
+    if (root) {
+      try {
+        declared = parseDeclaredDirection(deps.readDocument(join(root, 'DESIGN.md')), ordered).declared;
+      } catch {
+        // A missing DESIGN.md does not hide the available choices.
+      }
+    }
+    for (const [index, direction] of ordered.entries()) {
+      reply(`${index + 1}. ${direction.id} · ${direction.label} · ${direction.mood} · ${direction.isDark ? '어두움' : '밝음'} / ${direction.isPastel ? '파스텔' : '비파스텔'}${declared === direction.id ? ' · 지금 선언' : ''}`);
+    }
+    reply('적용: /design pick <번호|id>');
+    return;
+  }
+
+  const direction = /^\d+$/.test(requested)
+    ? ordered[Number(requested) - 1]
+    : ordered.find((item) => item.id === requested);
+  const id = direction?.id ?? requested;
+  if (!direction || args.length !== 1) {
+    debug.log('design.pick', 'refused', { id, reason: 'unknown-direction' });
+    reply(`디자인 방향을 찾을 수 없습니다: ${requested} — /design pick 으로 목록을 확인하세요.`);
+    return;
+  }
+
+  const result = deps.apply(join(root!, 'DESIGN.md'), id);
+  if (result.ok) {
+    debug.log('design.pick', 'applied', { id });
+    reply(`✅ ${id} 적용 — ${result.documentPath}`);
+    return;
+  }
+  debug.log('design.pick', 'refused', { id, reason: result.reason });
+  switch (result.reason) {
+    case 'conflicting-system-file':
+      reply(`적용 거부: design/system/ 을 사람이 고쳤다 — 덮지 않는다 · ${result.path ?? result.documentPath}`);
+      break;
+    case 'unknown-direction':
+      reply(`적용 거부: 알 수 없는 디자인 방향 ${id} — /design pick 으로 목록을 확인하세요.`);
+      break;
+    case 'cannot-read':
+      reply(`적용 거부: DESIGN.md 를 읽을 수 없습니다 · ${result.documentPath}`);
+      break;
+    case 'cannot-write':
+      reply(`적용 거부: DESIGN.md 를 쓸 수 없습니다 · ${result.documentPath}`);
+      break;
+  }
+}

package/src/dashboard/slash-runtime/help-from-registry.ts

@@ -0,0 +1,77 @@
+import type { SlashCommand } from '../../chat/index.js';
+import { visibleWidth } from '../../tui.js';
+
+const ESSENTIAL_KEYS = [
+  ['Enter', 'Send message'],
+  ['Esc', 'Clear input / close help modal'],
+  ['Ctrl+U', 'Clear text before cursor'],
+  ['Ctrl+W', 'Delete previous word'],
+  ['Ctrl+← / →', 'Move by word'],
+  ['Delete', 'Delete next character'],
+  ['Home / End', 'Move to start / end of line'],
+  ['Ctrl+A / E', 'Move to start / end of line'],
+  ['PgUp / PgDn', 'Scroll chat log'],
+  ['Ctrl+↑', 'Recall sent line while streaming'],
+] as const;
+
+function fitLine(text: string, width: number): string {
+  text = text.replace(/[│╭╮╰╯┌┐└┘─]/g, '');
+  const max = Math.max(0, Math.floor(width));
+  if (visibleWidth(text) <= max) return text;
+  if (max === 0) return '';
+  let fitted = '';
+  for (const { segment } of new Intl.Segmenter(undefined, { granularity: 'grapheme' }).segment(text)) {
+    if (visibleWidth(fitted + segment) > max - 1) break;
+    fitted += segment;
+  }
+  return fitted + '…';
+}
+
+/** Plain content for the dashboard modal; registration, not the picker, decides which slash names exist. */
+export function buildEssentialHelpLines({
+  names,
+  descriptions,
+  width,
+}: {
+  names: readonly string[];
+  descriptions: readonly Pick<SlashCommand, 'name' | 'aliases' | 'description'>[];
+  width: number;
+}): string[] {
+  const descriptionsByName = new Map<string, string>();
+  for (const command of descriptions) {
+    for (const name of [command.name, ...(command.aliases ?? [])]) {
+      descriptionsByName.set(name, command.description);
+    }
+  }
+  const entries = [...new Set(names)]
+    .sort((a, b) => a.localeCompare(b))
+    .flatMap((name) => {
+      // Removing border glyphs from a name would invent a different, unregistered slash.
+      if (/[│╭╮╰╯┌┐└┘─]/.test(name)) return [];
+      const description = descriptionsByName.get(name)?.replace(/\s+/g, ' ').trim();
+      return description ? [{ name, description }] : [];
+    });
+  // Pack alphabetically in reading order across columns; the handler checks
+  // the modal's row budget and uses scrollable chat if the result outgrows it.
+  const longestName = Math.max(22, ...entries.map(({ name }) => visibleWidth(`/${name}  `) + 1));
+  const columns = Math.max(1, Math.min(Math.ceil(entries.length / 20), Math.floor(width / longestName)));
+  const columnWidth = Math.floor(width / columns);
+  const commandLines: string[] = [];
+  for (let start = 0; start < entries.length; start += columns) {
+    const cells = entries.slice(start, start + columns).map(({ name, description }) => {
+      const cellWidth = columnWidth - (columns > 1 ? 1 : 0);
+      if (visibleWidth(`/${name}  `) > cellWidth) return '';
+      return fitLine(`/${name}  ${description}`, cellWidth);
+    });
+    commandLines.push(cells.map((cell, index) =>
+      index === cells.length - 1 ? cell : cell + ' '.repeat(columnWidth - visibleWidth(cell)),
+    ).join('').trimEnd());
+  }
+  return [
+    fitLine('Commands', width),
+    ...commandLines,
+    '',
+    fitLine('Keys', width),
+    ...ESSENTIAL_KEYS.map(([key, description]) => fitLine(`${key}  ${description}`, width)),
+  ];
+}

package/src/dashboard/slash-runtime/unknown-slash-reply.ts

@@ -0,0 +1,78 @@
+// Keep migration and retirement advice separate from the active slash registry:
+// a retired name must never be advertised as an available command.
+export const RETIRED_SLASH_ADVICE: Readonly<Record<string, { kind: 'moved' | 'retired'; use: string }>> = {
+  // These four entry points moved into the harness command.
+  ask: { kind: 'moved', use: '/harness ask <무엇을 왜 고칠지 한 문장>' },
+  say: { kind: 'moved', use: '/harness ask <무엇을 왜 고칠지 한 문장>' },
+  implement: { kind: 'moved', use: '/harness ask <무엇을 왜 고칠지 한 문장>' },
+  dev: { kind: 'moved', use: '/harness dev <무엇을 왜 고칠지 한 문장>' },
+  // Retired rich-UI and auxiliary commands from the slash registration tests.
+  ui: { kind: 'retired', use: '/help' }, workspace: { kind: 'retired', use: '/help' },
+  ws: { kind: 'retired', use: '/help' }, window: { kind: 'retired', use: '/help' },
+  win: { kind: 'retired', use: '/help' }, scratch: { kind: 'retired', use: '/help' },
+  sc: { kind: 'retired', use: '/help' }, 'acp-vw': { kind: 'retired', use: '/help' },
+  'claude-vw': { kind: 'retired', use: '/help' }, 'pty-pane': { kind: 'retired', use: '/help' },
+  'pty-view': { kind: 'retired', use: '/help' }, fullscreen: { kind: 'retired', use: '/help' },
+  fs: { kind: 'retired', use: '/help' }, view: { kind: 'retired', use: '/help' },
+  ctoggle: { kind: 'retired', use: '/help' }, cache: { kind: 'retired', use: '/help' },
+  perf: { kind: 'retired', use: '/help' }, 'pty-list': { kind: 'retired', use: '/help' },
+  ptys: { kind: 'retired', use: '/help' }, 'sweep-tool-results': { kind: 'retired', use: '/help' },
+  budget: { kind: 'retired', use: '/tokens' }, b: { kind: 'retired', use: '/tokens' },
+  route: { kind: 'retired', use: '/help' }, llm: { kind: 'retired', use: '/model' },
+  'browser-cdp': { kind: 'retired', use: '/help' }, bcdp: { kind: 'retired', use: '/help' },
+  dm: { kind: 'retired', use: '/help' }, surf: { kind: 'retired', use: '/help' },
+  'codex-vw': { kind: 'retired', use: '/help' }, 'skill-triggers': { kind: 'retired', use: '/help' },
+  triggers: { kind: 'retired', use: '/help' }, git: { kind: 'retired', use: '/help' },
+  memorize: { kind: 'retired', use: '/memory' }, 'mem-compact': { kind: 'retired', use: '/memory' },
+  sim: { kind: 'retired', use: '/help' }, simulator: { kind: 'retired', use: '/help' },
+  'turn-slider': { kind: 'retired', use: '/help' }, turnslider: { kind: 'retired', use: '/help' },
+  tslider: { kind: 'retired', use: '/help' }, playground: { kind: 'retired', use: '/help' },
+  pg: { kind: 'retired', use: '/help' }, branch: { kind: 'retired', use: '/help' },
+  audit: { kind: 'retired', use: '/help' }, 'substrate-stats': { kind: 'retired', use: '/help' },
+  sst: { kind: 'retired', use: '/help' }, usage: { kind: 'retired', use: '/tokens' },
+  stats: { kind: 'retired', use: '/help' }, 'codex-setup': { kind: 'retired', use: '/help' },
+  'codex-init': { kind: 'retired', use: '/help' }, hint: { kind: 'retired', use: '/help' },
+  media: { kind: 'retired', use: '/help' }, mv: { kind: 'retired', use: '/help' },
+};
+
+function distanceAtMostTwo(a: string, b: string): number {
+  if (Math.abs(a.length - b.length) > 2) return 3;
+  let previous = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i++) {
+    const current = [i];
+    for (let j = 1; j <= b.length; j++) {
+      current[j] = Math.min(
+        current[j - 1]! + 1,
+        previous[j]! + 1,
+        previous[j - 1]! + (a[i - 1] === b[j - 1] ? 0 : 1),
+      );
+    }
+    if (Math.min(...current) > 2) return 3;
+    previous = current;
+  }
+  return previous[b.length]!;
+}
+
+/** Plain lines: the caller applies its existing warning/muted presentation. */
+export function unknownSlashReply(name: string, registered: readonly string[]): string[] {
+  const slashName = name.replace(/^\//, '').toLowerCase();
+  const advice = Object.hasOwn(RETIRED_SLASH_ADVICE, slashName)
+    ? RETIRED_SLASH_ADVICE[slashName] : undefined;
+  if (advice?.kind === 'moved') {
+    return [`/${slashName} has moved; use ${advice.use}`];
+  }
+  if (advice) return [`/${slashName} is retired; use ${advice.use}`];
+
+  const suggestions = [...new Set(registered)]
+    .filter((candidate) => !Object.hasOwn(RETIRED_SLASH_ADVICE, candidate))
+    .map((candidate) => ({ candidate, distance: distanceAtMostTwo(slashName, candidate) }))
+    .filter(({ distance }) => distance <= 2)
+    .sort((a, b) => a.distance - b.distance || a.candidate.localeCompare(b.candidate))
+    .slice(0, 3)
+    .map(({ candidate }) => `/${candidate}`);
+  return [
+    `Unknown command: /${slashName}`,
+    ...(suggestions.length ? [`Did you mean: ${suggestions.join(', ')}?`] : []),
+    'Type /help for the list of commands.',
+  ];
+}

package/src/dashboard/stale-install-check.ts

@@ -0,0 +1,77 @@
+import { realpathSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, dirname, join, resolve } from 'node:path';
+
+import { readInstallMetadataCommit } from '../version/code-revision.js';
+
+export type StaleInstallResult = {
+  state: 'same' | 'changed' | 'unknown' | 'not-installed';
+  bootCommit: string | undefined;
+  installedCommit: string | undefined;
+};
+
+export const STALE_INSTALL_CHECK_INTERVAL_MS = 60_000;
+
+/** Identify the immutable installed version containing this module, never the session cwd. */
+export function versionedDashboardInstallDir(
+  codeRoot: string,
+  installRoot = join(homedir(), '.local', 'share', 'elanous'),
+): string | undefined {
+  try {
+    const packageRoot = realpathSync(codeRoot);
+    if (basename(packageRoot) !== 'elanous' || basename(dirname(packageRoot)) !== 'node_modules') return undefined;
+    const versionDir = dirname(dirname(packageRoot));
+    if (dirname(versionDir) !== resolve(installRoot, 'versions')) return undefined;
+    return versionDir;
+  } catch {
+    return undefined;
+  }
+}
+
+export function createStaleInstallCheck(input: {
+  bootCommit: string | undefined;
+  readInstalledCommit: () => string | undefined;
+  now: () => number;
+  codeRoot?: string;
+  installRoot?: string;
+}) {
+  const installed = input.codeRoot === undefined
+    || versionedDashboardInstallDir(input.codeRoot, input.installRoot) !== undefined;
+  const notifiedCommits = new Set<string>();
+  let lastReadAt = -Infinity;
+  let lastResult: StaleInstallResult | undefined;
+  const check = (): StaleInstallResult => {
+    if (!installed) return { state: 'not-installed', bootCommit: input.bootCommit, installedCommit: undefined };
+    const time = input.now();
+    if (lastResult && time - lastReadAt < STALE_INSTALL_CHECK_INTERVAL_MS) return lastResult;
+    lastReadAt = time;
+    let installedCommit: string | undefined;
+    try { installedCommit = input.readInstalledCommit(); } catch { /* unreadable metadata */ }
+    const result: StaleInstallResult = {
+      state: !input.bootCommit || !installedCommit
+        ? 'unknown'
+        : input.bootCommit === installedCommit ? 'same' : 'changed',
+      bootCommit: input.bootCommit,
+      installedCommit,
+    };
+    lastResult = result;
+    return result;
+  };
+  return {
+    check,
+    shouldNotify(result: StaleInstallResult): boolean {
+      if (result.state !== 'changed' || !result.installedCommit || notifiedCommits.has(result.installedCommit)) return false;
+      notifiedCommits.add(result.installedCommit);
+      return true;
+    },
+  };
+}
+
+/** Only the current pointer is polled; boot metadata is read once from the immutable version. */
+export function readDashboardBootCommit(versionDir: string): string | undefined {
+  return readInstallMetadataCommit(join(versionDir, 'install.json'));
+}
+
+export function readCurrentInstalledCommit(installRoot = join(homedir(), '.local', 'share', 'elanous')): string | undefined {
+  return readInstallMetadataCommit(join(installRoot, 'current', 'install.json'));
+}

package/src/dashboard/surface-registry-wiring.ts

@@ -1,36 +1,23 @@
-import type { SurfaceRegistry, WireWindowSurfacesHandle } from '../surface/index.js';
+import type { SurfaceRegistry } from '../surface/index.js';
 import {
   wireModalSurfaceAdapter,
   wireWidgetSurfaceAdapter,
-  wireWindowSurfaces,
 } from '../surface/index.js';
-import type { WindowRegistry } from '../virtual-windows/window-registry.js';
 import type { WidgetHost } from '../widgets/host.js';
 
 export interface DashboardSurfaceRegistryWiringDeps {
   surfaceRegistry: SurfaceRegistry;
   widgetHost: WidgetHost;
-  windowRegistry: WindowRegistry;
   wireModal?: typeof wireModalSurfaceAdapter;
   wireWidget?: typeof wireWidgetSurfaceAdapter;
-  wireWindows?: typeof wireWindowSurfaces;
-}
-
-export interface DashboardSurfaceRegistryWiringResult {
-  windowHandle?: WireWindowSurfacesHandle;
 }
 
 export function wireDashboardSurfaceRegistry(
   deps: DashboardSurfaceRegistryWiringDeps,
-): DashboardSurfaceRegistryWiringResult {
+): void {
   (deps.wireModal ?? wireModalSurfaceAdapter)({ registry: deps.surfaceRegistry });
   (deps.wireWidget ?? wireWidgetSurfaceAdapter)({
     registry: deps.surfaceRegistry,
     widgetHost: deps.widgetHost,
   });
-  const windowHandle = (deps.wireWindows ?? wireWindowSurfaces)({
-    windowRegistry: deps.windowRegistry,
-    surfaceRegistry: deps.surfaceRegistry,
-  });
-  return { windowHandle };
 }

package/src/dashboard/turn-message-runtime.ts

@@ -15,8 +15,6 @@ export interface DashboardTurnMessageRuntimeDeps {
   contextText: string;
   contextRegistry: ContextRegistry;
   terminalRegistry: unknown;
-  addressBook: unknown;
-  windowRegistry: unknown;
   blockAttach: DashboardTurnBlockAttachLike;
   pushChatLine: (line: string) => void;
 }
@@ -34,8 +32,6 @@ export function buildDashboardTurnMessage(
 ): DashboardTurnMessageRuntimeResult {
   const expandedQuestion = expandPromptReferences(deps.userText, {
     terminalRegistry: deps.terminalRegistry as never,
-    addressBook: deps.addressBook as never,
-    windowRegistry: deps.windowRegistry as never,
   });
   const attachedBanner = deps.blockAttach.banner();
   if (attachedBanner) deps.pushChatLine(C.muted(`  ${attachedBanner}`));

package/src/dashboard/turn-preamble.ts

@@ -59,7 +59,7 @@ export interface DashboardTurnPreambleContext {
   modelFamily?: ModelFamily;
   /** Current request session ID. It is injected only while this preamble is built for the turn. */
   sessionId?: string;
-  /** TUI --rich mode. Kept aligned with the tool catalog selected for this turn. */
+  /** Catalog richness for non-dashboard callers; the essential dashboard passes false. */
   rich?: boolean;
   /** Active tool names for session-specific guidance (Wave 3,
    *  2026-05-04). When provided, the universal preamble emits per-tool

package/src/dashboard/turn-stream-formatter.ts

@@ -133,8 +133,8 @@ export interface TurnStreamFormatterDeps {
   };
   termCols: () => number;
   // chat.rendering.wrap 는 boolean 이 아니라 wrap 옵션 오브젝트로 이관됨.
-  wrapOpts: { urlAware?: boolean; preserveOsc8?: boolean };
-  formatResponse: (full: string, width: number, wrapOpts?: { urlAware?: boolean; preserveOsc8?: boolean }) => string[];
+  wrapOpts: { urlAware?: boolean };
+  formatResponse: (full: string, width: number, wrapOpts?: { urlAware?: boolean }) => string[];
   text: (line: string) => string;
   muted: (text: string) => string;
   ptyCallLine: (name: string, args: Record<string, unknown>) => string | null;

package/src/dashboard/turn-stream-runtime.ts

@@ -41,8 +41,8 @@ export interface DashboardTurnStreamRuntimeDeps {
   pinChatTail: () => void;
   termCols: () => number;
   // chat.rendering.wrap 는 boolean 이 아니라 wrap 옵션 오브젝트로 이관됨.
-  wrapOpts: { urlAware?: boolean; preserveOsc8?: boolean };
-  formatResponse: (full: string, width: number, wrapOpts?: { urlAware?: boolean; preserveOsc8?: boolean }) => string[];
+  wrapOpts: { urlAware?: boolean };
+  formatResponse: (full: string, width: number, wrapOpts?: { urlAware?: boolean }) => string[];
   text: (line: string) => string;
   muted: (text: string) => string;
   ptyCallLine: (name: string, args: Record<string, unknown>) => string | null;

package/src/dashboard-pane-context-menu.ts

@@ -18,12 +18,6 @@ export interface DashboardPaneTitleMenuDeps {
   hasClosedPanes?: () => boolean;
 }
 
-const VW_CAPABLE_PANES = new Set<PaneFocus>([
-  'browser',
-  'preview',
-  'scratch',
-]);
-
 function createDashboardPaneTitleMenuProvider(
   pane: PaneFocus,
   deps: DashboardPaneTitleMenuDeps = {},
@@ -43,14 +37,6 @@ function createDashboardPaneTitleMenuProvider(
         payload,
       },
     ];
-    if (VW_CAPABLE_PANES.has(pane)) {
-      items.push({
-        kind: 'command',
-        id: 'dashboard-pane.open-vw',
-        label: 'Open in virtual window',
-        payload,
-      });
-    }
     if (hasClosedPanes) {
       items.push(
         { kind: 'separator' },

package/src/debug/log.ts

@@ -60,6 +60,7 @@
 
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { mkdirSync } from 'fs';
+import { excludeProjectDotElanous } from '../instance/project-local-exclude.js';
 import { formatClock } from '../time/format.js';
 import { homedir } from 'os';
 import { fileURLToPath } from 'node:url';
@@ -192,6 +193,8 @@ function resolveLogDir(): string {
     : join(getSessionProjectRoot().path, '.elanous', 'debug');
   try {
     mkdirSync(local, { recursive: true });
+    // 사용자 프로젝트면 `.elanous/` 를 그 저장소의 로컬 무시 목록에(UX 13 · 사용자 git status 를 더럽히지 않게).
+    if (!isWithinSourceRoot(sessionCwd)) excludeProjectDotElanous(getSessionProjectRoot().path);
     return local;
   } catch { /* selected location unwritable — fall through */ }
 
@@ -889,7 +892,9 @@ const SECRET_TEXT_RULES: readonly { readonly id: string; readonly re: RegExp; re
   { id: 'private-key', re: /-----BEGIN[ A-Z0-9_-]{0,100}PRIVATE KEY(?: BLOCK)?-----[\s\S]*?-----END[ A-Z0-9_-]{0,100}PRIVATE KEY(?: BLOCK)?-----/gi, to: '<private-key redacted>' },
   { id: 'anthropic-api-key', re: /\b(sk-ant-(?:api|admin)[0-9]{0,2}-)[A-Za-z0-9_-]{8,}/g, to: '$1***' },
   { id: 'openai-api-key-scoped', re: /\b(sk-(?:proj|svcacct|admin)-)[A-Za-z0-9_-]{8,}/g, to: '$1***' },
+  { id: 'openrouter-api-key', re: /\b(sk-or-v1-)[A-Za-z0-9]{16,}/g, to: '$1***' },
   { id: 'openai-api-key', re: /\b(sk-)[A-Za-z0-9]{16,}/g, to: '$1***' },
+  { id: 'xai-api-key', re: /\b(xai-)[A-Za-z0-9]{20,}/g, to: '$1***' },
   { id: 'github-fine-grained-pat', re: /\b(github_pat_)\w{20,}/g, to: '$1***' },
   { id: 'github-token', re: /\b((?:ghp|gho|ghu|ghs|ghr)_)[0-9a-zA-Z]{20,}/g, to: '$1***' },
   { id: 'aws-access-token', re: /\b((?:A3T[A-Z0-9]|AKIA|ASIA|ABIA|ACCA))[A-Z2-7]{16}\b/g, to: '$1***' },
@@ -898,6 +903,8 @@ const SECRET_TEXT_RULES: readonly { readonly id: string; readonly re: RegExp; re
   { id: 'jwt', re: /\b(ey)[A-Za-z0-9_-]{10,}\.ey[A-Za-z0-9._\\/-]{10,}/g, to: '$1***' },
   // gitleaks: generic-api-key 축소판 — `key = value` 형태.
   { id: 'generic-api-key', re: /\b(api[_-]?key|secret|password|passwd|token|credential)\b(\s*[:=]\s*)["']?[^\s"',;)]{4,}/gi, to: '$1$2***' },
+  // 환경변수 형태 `OPENROUTER_API_KEY=…` — 위 규칙은 `_API_KEY` 앞에 단어 경계가 없어 못 잡는다. 값에 글자가 있어야 한다(`MAX_TOKEN=4096` 은 그대로).
+  { id: 'env-secret', re: /\b([A-Z][A-Z0-9]*_(?:[A-Z0-9]+_)*(?:API_KEY|TOKEN|SECRET|PASSWORD|ACCESS_KEY))(\s*[:=]\s*)["']?(?=[^\s"',;)]*[A-Za-z])[^\s"',;)]{8,}/g, to: '$1$2***' },
   // Authorization 헤더(로그에서 흔하다).
   { id: 'authorization-header', re: /\b(Bearer|Basic)\s+[A-Za-z0-9._~+/-]{8,}={0,2}/gi, to: '$1 ***' },
 ];

package/src/decide/boundary-shadow.ts

@@ -0,0 +1,131 @@
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { debug, redactSecretText } from '../debug/log.js';
+import { callJev, resolveJevAccess, type JevRequest, type JevResponse } from './jev.js';
+
+export interface BoundaryShadowConfig {
+  enabled?: boolean;
+  sampleRate?: number;
+  endpoint?: string;
+  keyFile?: string;
+  model?: string;
+  /** «되돌릴 수 없다»로 볼 Jev 확률 하한 — 기본 0.7. */
+  threshold?: number;
+}
+
+export interface BoundaryShadowDeps {
+  random?: () => number;
+  callJev?: (request: JevRequest, key: string | undefined, fetchImpl: typeof fetch, endpoint: string) => Promise<JevResponse>;
+  fetch?: typeof fetch;
+  log?: (category: string, event: string, data: Record<string, unknown>, level?: 'info' | 'warn') => void;
+  /** 사용량 원장(`llm.usage`) 기록 — 기본은 llm.ts 의 logAgentTurnUsage(역할 classify · site jev-boundary-shadow). */
+  logUsage?: (model: string, usage: { inputTokens?: number; outputTokens?: number }) => void;
+  now?: () => number;
+}
+
+const MASK = '[REDACTED]';
+const SECRET_KEY = /(?:authorization|api[-_]?key|password|passwd|secret|private[-_]?key|(?:access|refresh|session|bot)[-_]?token|token|cookie|credentials)/i;
+
+/** Remove credentials from both structured fields and free-form request text before it leaves the process. */
+function maskBoundaryValue(value: unknown, seen = new WeakSet<object>()): unknown {
+  if (typeof value === 'string') {
+    return redactSecretText(value)
+      .replace(/\bBearer\s+[^\s"']+/gi, `Bearer ${MASK}`)
+      .replace(/("(?:api[-_]?key|password|secret|token|authorization)"\s*:\s*")[^"]*(")/gi, `$1${MASK}$2`)
+      .replace(/\b((?:api[-_]?key|password|secret|token|authorization)\s*[:=]\s*)[^\s,"'}]+/gi, `$1${MASK}`)
+      .replace(/\bsk-[a-zA-Z0-9_-]{8,}\b/g, MASK)
+      // 셸 인자 모양(2026-09-28 🅞 누수 탐침): URL 자격 · -u 사용자:비밀 · --token 값(공백·= 둘 다) · 쿠키 값.
+      .replace(/(\b[a-z][a-z0-9+.-]*:\/\/)[^/\s:@'"]+:[^/\s@'"]+@/gi, `$1${MASK}@`)
+      .replace(/(\s(?:-u|--user)(?:\s+|=))(['"]?)[^\s'"]+\2/g, `$1${MASK}`)
+      .replace(/(\s--?(?:[a-z0-9]+-)*(?:token|api-?key|apikey|password|passwd|secret|auth|cookie|credentials?)(?:\s+|=))(['"]?)[^\s'"]+\2/gi, `$1${MASK}`)
+      .replace(/(\s(?:-b|--cookie)\s+)(['"]?)[^'"]*\2/g, `$1${MASK}`);
+  }
+  if (typeof value !== 'object' || value === null) return value;
+  if (seen.has(value)) return '<circular>';
+  seen.add(value);
+  if (Array.isArray(value)) return value.map((item) => maskBoundaryValue(item, seen));
+  return Object.fromEntries(Object.entries(value).map(([key, item]) => {
+    const sensitiveKey = SECRET_KEY.test(key);
+    return [sensitiveKey ? MASK : maskBoundaryValue(key),
+      sensitiveKey ? MASK : maskBoundaryValue(item, seen)];
+  }));
+}
+
+/** Advisory only: never changes the code boundary verdict or the response sent to the caller. */
+export async function shadowBoundaryDecision<T extends { requestId?: string; requestKind?: string }>(
+  request: T,
+  verdict: { wouldApprove?: boolean; approve?: boolean; requestKind?: string; evidenceWhy?: string },
+  config?: BoundaryShadowConfig,
+  deps: BoundaryShadowDeps = {},
+): Promise<void> {
+  if (config?.enabled !== true || request.requestKind !== 'rejected' || verdict.requestKind !== 'rejected') return;
+  const rate = config.sampleRate ?? 1;
+  if (!Number.isFinite(rate) || rate <= 0 || rate > 1 || (rate < 1 && (deps.random ?? Math.random)() >= rate)) return;
+
+  const log = deps.log ?? ((category: string, event: string, data: Record<string, unknown>, level?: 'info' | 'warn') => debug.log(category, event, data, level ? { level } : undefined));
+  const safeRequestId = maskBoundaryValue(request.requestId) as string | undefined;
+  const emit = (event: string, data: Record<string, unknown>, level?: 'info' | 'warn') => {
+    try { log('decide.boundary-shadow', event, maskBoundaryValue({ ...data, requestId: safeRequestId }) as Record<string, unknown>, level); } catch { /* observation must not affect the boundary */ }
+  };
+  const now = deps.now ?? Date.now;
+  const startedAt = now();
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const controller = new AbortController();
+  const fetchWithAbort = ((input: RequestInfo | URL, init?: RequestInit) =>
+    (deps.fetch ?? fetch)(input, { ...init, signal: controller.signal })) as typeof fetch;
+  try {
+    const access = resolveJevAccess({
+      config,
+      env: process.env,
+      readFile: (path) => { try { return readFileSync(path, 'utf8'); } catch { return undefined; } },
+      typesafeCachePath: join(homedir(), '.cache', 'typesafe_api_key'),   // same file as src/index.ts · headless-elanous-driver.ts
+    });
+    if (!access.ok) { emit('failed', { reason: 'credentials-unavailable' }); return; }
+    const state = maskBoundaryValue({ request, verdict: {
+      requestKind: verdict.requestKind, evidenceWhy: verdict.evidenceWhy,
+    } });
+    const response = await Promise.race([
+      (deps.callJev ?? callJev)({
+        state,
+        questions: {
+          irreversible: { type: 'noul', instructions: '이 셸 명령을 실행하면 되돌릴 수 없는 변화(파일·브랜치·원격·데이터 삭제나 덮어쓰기, 강제 푸시 등)가 생기는가?', criteria: {
+            true: '되돌릴 수 없는 변화가 생긴다', false: '되돌릴 수 있다(읽기·재생성 가능한 산출 등)',
+          } },
+        },
+        ...(access.access.model ? { model: access.access.model } : {}),
+      }, access.access.key, fetchWithAbort, access.access.endpoint),
+      new Promise<never>((_, reject) => {
+        timer = setTimeout(() => { reject(new Error('Jev shadow timeout')); controller.abort(); }, 5_000);
+      }),
+    ]);
+    const jevYes = response.answers.irreversible?.noul;
+    if (typeof jevYes !== 'number' || !Number.isFinite(jevYes)) { emit('failed', { reason: 'no-answer' }); return; }
+    const threshold = typeof config.threshold === 'number' && config.threshold > 0 && config.threshold < 1 ? config.threshold : 0.7;
+    const allowlistApprove = verdict.wouldApprove === true;
+    const irreversible = jevYes >= threshold;
+    const judged = {
+      requestKind: verdict.requestKind, decidingToken: (request as { decidingToken?: string }).decidingToken, evidenceWhy: verdict.evidenceWhy,
+      allowlistApprove, jevYes, irreversible, agree: allowlistApprove === !irreversible, threshold,
+      confidence: response.answers.irreversible?.confidence, latencyMs: now() - startedAt, model: response.model,
+    };
+    emit('judged', judged);
+    // 핵심 지표: 허용목록이 막았는데 되돌릴 수 있는 명령(오탐 차단) · 반대로 통과시켰는데 되돌릴 수 없는 명령(경고).
+    if (!allowlistApprove && !irreversible) emit('safe-but-blocked', judged);
+    if (allowlistApprove && irreversible) emit('warn-disagree', judged, 'warn');
+    if (response.usage) {
+      try {
+        const usage = { inputTokens: response.usage.input_tokens, outputTokens: response.usage.output_tokens };
+        if (deps.logUsage) deps.logUsage(response.model, usage);
+        else {
+          const { logAgentTurnUsage } = await import('../llm.js');
+          logAgentTurnUsage(response.model, usage, { providerName: 'typesafe', site: 'jev-boundary-shadow', role: 'classify' });
+        }
+      } catch { /* usage observation must not affect the boundary */ }
+    }
+  } catch (error) {
+    emit('failed', { reason: error instanceof Error && error.message === 'Jev shadow timeout' ? 'timeout' : 'request-failed' });
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}