elanous 0.2.7 → 0.2.8

package/src/cli/skills-cli.ts

@@ -0,0 +1,173 @@
+// SK2 — `elanous skills repair`: 색인이 못 읽은 스킬을 보여 주고, 확인([y/N])한 것만 그 자리에서 고친다.
+import type { Command } from 'commander';
+import { createInterface } from 'node:readline/promises';
+import { getSkillIndex, resetSkillIndex, skillIndexProblems } from '../skills/index.js';
+import { applySkillRepair, planSkillRepair, skillRepairNotice } from '../skills/repair.js';
+import { CONNECT_AGENTS, connectPrompt, connectSkillRoot, planConnect, withConnectedSource, withoutSources, type ConnectAgent } from '../skills/connect.js';
+import { debug } from '../debug/log.js';
+import { resolve } from 'node:path';
+import { claudePluginPrompt, isClaudePluginDir, mcpEnableHint, planClaudePlugin, readClaudePlugin } from '../skills/connect-claude-plugin.js';
+
+async function ask(question: string, defaultYes = false): Promise<boolean> {
+  if (!process.stdin.isTTY) return false;
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const answer = (await rl.question(question)).trim();
+    return answer === '' ? defaultYes : /^(y|yes|예|네)$/i.test(answer);
+  }
+  finally { rl.close(); }
+}
+
+/** EN9 — `elanous connect <claude|codex>`: find the skills that agent already uses and register their folder (no copy). */
+export function registerConnectCommand(program: Command): void {
+  program.command('connect <agent>')
+    .description(`Use the skills you already have in another agent (${CONNECT_AGENTS.join(' | ')}) or a Claude Code plugin folder — registers in place, never copies; plugin MCP servers are added switched off`)
+    .option('--yes', 'Register without asking')
+    .option('--json', 'Print the plan as JSON and change nothing')
+    .option('--undo', 'Stop using that folder (the files stay where they are)')
+    .action(async (agentArg: string, opts: { yes?: boolean; json?: boolean; undo?: boolean }) => {
+      const agent = agentArg.toLowerCase() as ConnectAgent;
+      if (!CONNECT_AGENTS.includes(agent) && isClaudePluginDir(resolve(agentArg))) {
+        await connectClaudePlugin(resolve(agentArg), opts);
+        return;
+      }
+      if (!CONNECT_AGENTS.includes(agent)) {
+        console.error(`지원하는 에이전트: ${CONNECT_AGENTS.join(', ')} · 또는 Claude 플러그인 폴더(.claude-plugin/plugin.json) (받은 값: ${agentArg})`);
+        process.exitCode = 2;
+        return;
+      }
+      const { defaultSkillDirs, getUserConfig, saveUserConfig } = await import('../user-config.js');
+      const cfg = getUserConfig();
+      if (opts.undo) {
+        const root = connectSkillRoot(agent);
+        const sources = withoutSources(cfg.skills.sources, [root]);
+        if (sources.length === (cfg.skills.sources ?? []).length) { console.log(`연결된 적이 없습니다(${root}).`); return; }
+        saveUserConfig({ ...cfg, skills: { ...cfg.skills, sources } });
+        resetSkillIndex();
+        debug.log('skills.connect', 'undone', { agent });
+        console.log(`연결을 끊었습니다. 파일은 그대로 있습니다(${root}).`);
+        return;
+      }
+      const plan = planConnect(agent, defaultSkillDirs(cfg));
+      debug.log('skills.connect', 'plan', { agent, state: plan.state, count: 'skills' in plan ? plan.skills.length : 0 });
+      if (opts.json) { console.log(JSON.stringify(plan, null, 2)); return; }
+      const prompt = connectPrompt(plan);
+      if (plan.state !== 'new') { console.log(prompt); return; }
+      if (!opts.yes) {
+        if (!process.stdin.isTTY) { console.log(`${prompt.split('\n')[0]}\n가져오려면: elanous connect ${agent} --yes`); return; }
+        if (!(await ask(prompt, true))) { console.log('가져오지 않았습니다. 나중에: elanous connect ' + agent); return; }
+      } else {
+        console.log(prompt.split('\n')[0]);
+      }
+      const next = { ...cfg, skills: { ...cfg.skills, sources: withConnectedSource(cfg.skills.sources, plan.root, agent) } };
+      saveUserConfig(next);
+      resetSkillIndex();
+      const index = getSkillIndex(defaultSkillDirs(next));
+      const problems = skillIndexProblems().filter((p) => p.dir === plan.root);
+      const usable = plan.skills.length - problems.length;
+      debug.log('skills.connect', 'registered', { agent, found: plan.skills.length, problems: problems.length, indexed: index.length });
+      console.log(`연결했습니다 — ${usable}개를 바로 쓸 수 있습니다. 끊으려면: elanous connect ${agent} --undo`);
+      const notice = skillRepairNotice(problems);
+      if (notice) console.log(notice);
+    });
+}
+
+export function registerSkillsCommands(program: Command): void {
+  const skills = program.command('skills').description('Check and repair installed skills');
+  skills.command('sources')
+    .description('List every skill folder elanous reads, in order (preset · shared · connected · package)')
+    .option('--json', 'JSON output')
+    .action(async (opts: { json?: boolean }) => {
+      const { resolveSkillSources } = await import('../user-config.js');
+      const { existsSync } = await import('node:fs');
+      const sources = resolveSkillSources().map((source) => ({ ...source, exists: existsSync(source.path) }));
+      debug.log('skills.sources', 'listed', { count: sources.length, kinds: sources.map((source) => source.kind) });
+      if (opts.json) { console.log(JSON.stringify(sources, null, 2)); return; }
+      const width = Math.max(10, ...sources.map((source) => source.id.length));
+      for (const source of sources) {
+        console.log(`${source.enabled ? '●' : '○'} ${source.id.padEnd(width)}  ${source.kind.padEnd(9)} ${source.path}${source.exists ? '' : '  (없음)'}`);
+      }
+      console.log('묶음 스킬(패키지 skills/)은 늘 마지막에 읽습니다. 다른 에이전트 스킬 더하기: elanous connect claude|codex|<플러그인 폴더>');
+    });
+  skills.command('repair')
+    .description('List skills that could not be read and repair the ones that can be fixed (asks first)')
+    .option('--yes', 'Repair every fixable skill without asking')
+    .action(async (opts: { yes?: boolean }) => {
+      getSkillIndex();
+      const problems = skillIndexProblems();
+      if (!problems.length) { console.log('모든 스킬을 읽었습니다. 고칠 것이 없습니다.'); return; }
+      console.log(`스킬 ${problems.length}개를 읽지 못했습니다.`);
+      // ER1 — operations hears about it too (consented · scrubbed).
+      try {
+        const { reportError } = await import('../error-report/report.js');
+        for (const p of problems.slice(0, 3)) await reportError({ code: 'skill-index', message: `${p.name}: ${p.code ?? ''} ${p.error}`.trim(), surface: 'cli' });
+      } catch { /* reporting is advisory */ }
+      let fixed = 0;
+      for (const problem of problems) {
+        const plan = planSkillRepair(problem);
+        console.log(`\n· ${problem.name} — ${problem.error.split('\n')[0]}`);
+        if (plan.kind === 'permission' || plan.kind === 'manual') { console.log(`  ${plan.hint}`); continue; }
+        const what = plan.kind === 'fixable-permission' ? '읽기 권한을 켭니다' : `${plan.keys.join(', ')} 를 한 줄로 고칩니다(원본은 .bak 으로 남김)`;
+        if (!opts.yes && !(await ask(`  ${what}. 고칠까요? [y/N] `))) { console.log('  건너뜀'); continue; }
+        const result = applySkillRepair(plan);
+        if (result.ok) { fixed += 1; console.log(`  고쳤습니다 — ${result.path}`); }
+        else console.log(`  고치지 못했습니다(${result.reason}) — 원래대로 되돌렸습니다.`);
+      }
+      console.log(`\n${fixed}개를 고쳤습니다.`);
+      if (fixed < problems.length) process.exitCode = 1;
+    });
+}
+
+/** EN8 — a Claude Code plugin folder: skills join `skills.sources[]` (kind connected) in place, `.mcp.json` servers join `mcp.servers[]` switched off. */
+async function connectClaudePlugin(dir: string, opts: { yes?: boolean; json?: boolean; undo?: boolean }): Promise<void> {
+  const { defaultSkillDirs, getUserConfig, saveUserConfig } = await import('../user-config.js');
+  const cfg = getUserConfig();
+  let plugin;
+  try { plugin = readClaudePlugin(dir); }
+  catch (error) {
+    console.error(`플러그인 정보를 읽지 못했습니다(.claude-plugin/plugin.json): ${error instanceof Error ? error.message : String(error)}`);
+    process.exitCode = 1;
+    return;
+  }
+  const rawMcp = (cfg.raw.mcp && typeof cfg.raw.mcp === 'object' && !Array.isArray(cfg.raw.mcp) ? cfg.raw.mcp : {}) as Record<string, unknown>;
+  const rawServers = (Array.isArray(rawMcp.servers) ? rawMcp.servers : []) as Array<Record<string, unknown>>;
+  const writeServers = (servers: Array<Record<string, unknown>>) => ({ ...cfg.raw, mcp: { ...rawMcp, servers } });
+  if (opts.undo) {
+    const ids = new Set(plugin.mcp.map((server) => server.id));
+    const sources = withoutSources(cfg.skills.sources, plugin.skillRoots);
+    const servers = rawServers.filter((row) => !ids.has(row.id as string));
+    if (sources.length === (cfg.skills.sources ?? []).length && servers.length === rawServers.length) { console.log(`연결된 적이 없습니다(${plugin.name}).`); return; }
+    saveUserConfig({ ...cfg, raw: writeServers(servers), skills: { ...cfg.skills, sources } });
+    resetSkillIndex();
+    debug.log('skills.connect', 'undone', { plugin: plugin.name });
+    console.log(`«${plugin.name}» 연결을 끊었습니다. 파일은 그대로 있습니다(${plugin.root}).`);
+    return;
+  }
+  const plan = planClaudePlugin(plugin, defaultSkillDirs(cfg), rawServers.map((row) => row.id as string));
+  debug.log('skills.connect', 'plan', { plugin: plugin.name, state: plan.state, skills: plugin.skills.length, mcp: plugin.mcp.length, skipped: plugin.skipped.length });
+  if (opts.json) { console.log(JSON.stringify(plan, null, 2)); return; }
+  const prompt = claudePluginPrompt(plan);
+  if (plan.state !== 'new') { console.log(prompt); return; }
+  const firstLines = prompt.slice(0, prompt.lastIndexOf('\n'));
+  if (!opts.yes) {
+    if (!process.stdin.isTTY) { console.log(`${firstLines}\n가져오려면: elanous connect ${plugin.root} --yes`); return; }
+    if (!(await ask(prompt, true))) { console.log(`가져오지 않았습니다. 나중에: elanous connect ${plugin.root}`); return; }
+  } else {
+    console.log(firstLines);
+  }
+  const sources = plan.newSkillRoots.reduce((list, root, i) => withConnectedSource(list, root, `plugin:${plugin.name}${i ? `:${i + 1}` : ''}`), cfg.skills.sources ?? []);
+  const servers = [...rawServers, ...plan.newMcp];
+  saveUserConfig({ ...cfg, raw: writeServers(servers), skills: { ...cfg.skills, sources } });
+  resetSkillIndex();
+  const next = { ...cfg, skills: { ...cfg.skills, sources } };
+  getSkillIndex(defaultSkillDirs(next));
+  const problems = skillIndexProblems().filter((p) => plugin.skillRoots.includes(p.dir));
+  debug.log('skills.connect', 'registered', { plugin: plugin.name, skills: plugin.skills.length, problems: problems.length, mcp: plan.newMcp.length });
+  console.log(`연결했습니다 — 스킬 ${plugin.skills.length - problems.length}개를 바로 쓸 수 있습니다. 끊으려면: elanous connect ${plugin.root} --undo`);
+  const notice = skillRepairNotice(problems);
+  if (notice) console.log(notice);
+  if (plan.newMcp.length) {
+    console.log(`MCP 서버 ${plan.newMcp.length}개를 꺼진 채로 등록했습니다. 믿을 수 있는 것만 켜 주세요(켠 뒤 데몬 재시작):`);
+    for (const line of mcpEnableHint(plan.newMcp, servers)) console.log(line);
+  }
+}

package/src/cli/start-cli.ts

@@ -5,6 +5,8 @@ import type { DetectedProvider } from '../llm/provider-detect.js';
 import { resolveUsableLlm, type UsableLlm } from '../llm/usable-llm.js';
 import { resolveDaemonEndpoint, type DaemonEndpoint, type ResolveDaemonEndpointOpts } from '../nexus/daemon-endpoint.js';
 import { runBgLaunch } from './bg-launch.js';
+import { browserUnavailableReason } from '../oauth/browser-availability.js';
+import { debug } from '../debug/log.js';
 
 export interface StartOptions {
   gui?: boolean;
@@ -63,6 +65,8 @@ export interface StartDeps {
   openTui?: (json: boolean) => Promise<number>;
   sleep?: (ms: number) => Promise<void>;
   output?: (line: string) => void;
+  browserEnv?: NodeJS.ProcessEnv;
+  browserPlatform?: NodeJS.Platform;
   /** Test seam — daemon address. `null` means this universe has no daemon (do not guess a port).
    *  Called again after a launch so the opened address is the daemon that was just started. */
   resolveEndpoint?: (opts?: ResolveDaemonEndpointOpts) => DaemonEndpoint | null;
@@ -193,10 +197,15 @@ export async function runStart(options: StartOptions = {}, deps: StartDeps = {})
       if (!openUrl) {
         record('open-gui', 'failed', 'Daemon address unknown');
       } else {
-        try {
-          if (await (deps.openGui ?? defaultOpenGui)(openUrl)) surface = 'gui';
-        } catch { /* A browser is optional; retain the URL for manual opening. */ }
-        record('open-gui', surface === 'gui' ? 'done' : 'failed', surface === 'gui' ? `Opened ${openUrl}` : `Open manually: ${openUrl}`);
+        const why = browserUnavailableReason(deps.browserEnv ?? process.env, deps.browserPlatform ?? process.platform);
+        if (why) {
+          debug.log('browser.open', 'skipped', { reason: why.includes('ssh') ? 'ssh' : 'no-display' });
+        } else {
+          try {
+            if (await (deps.openGui ?? defaultOpenGui)(openUrl)) surface = 'gui';
+          } catch { /* A browser is optional; retain the URL for manual opening. */ }
+        }
+        record('open-gui', surface === 'gui' ? 'done' : why ? 'skipped' : 'failed', surface === 'gui' ? `Opened ${openUrl}` : `Open manually: ${openUrl}${why ? ` — ${why}` : ''}`);
       }
       record('open-tui', 'skipped', 'GUI selected');
     } else {

package/src/codex/setup.ts

@@ -82,12 +82,14 @@ export async function pickCodexAuthMode(io: WizardIO, deps: CodexAuthModeDeps =
   if (existing || codexCli) {
     if (existing) {
       const exp = existing.tokens.expiresAt;
-      const when = exp != null
-        ? (Date.now() > exp ? 'EXPIRED' : `${Math.round((exp - Date.now()) / 60000)}min left`)
-        : 'no expiry tracked';
-      io.print(`  OAuth tokens already on file (${when}).`);
+      const left = exp != null ? exp - Date.now() : null;
+      const when = left == null ? '만료 시각 모름'
+        : left <= 0 ? '만료됨'
+          : left >= 86_400_000 ? `약 ${Math.round(left / 86_400_000)}일 남음`
+            : left >= 3_600_000 ? `약 ${Math.round(left / 3_600_000)}시간 남음` : `약 ${Math.max(1, Math.round(left / 60_000))}분 남음`;
+      io.print(`  이미 로그인돼 있습니다(${when}).`);
     } else {
-      io.print('  Found your ChatGPT/Codex login from the codex CLI (~/.codex/auth.json).');
+      io.print('  Codex CLI 에 있는 ChatGPT/Codex 로그인을 찾았습니다(~/.codex/auth.json).');
     }
     // Sprint 11 — chooseFrom Yes/No so fullScreenIO renders the arrow
     // picker (with 'y'/'n' + 한글 자모 quick-pick from PR #986 + #988)
@@ -96,10 +98,10 @@ export async function pickCodexAuthMode(io: WizardIO, deps: CodexAuthModeDeps =
     // rotation on an unnecessary refresh).
     const keep = await chooseFrom<boolean>(
       io,
-      'Keep using existing OAuth tokens?',
+      '지금 로그인을 그대로 쓸까요?',
       [
-        { key: 'y', label: 'Yes — keep them', value: true },
-        { key: 'n', label: 'No — re-run device-code flow', value: false },
+        { key: 'y', label: '예 — 그대로 씁니다', value: true },
+        { key: 'n', label: '아니오 — 다시 로그인합니다', value: false },
       ],
       { defaultIndex: 0 },
       undefined,
@@ -265,18 +267,18 @@ async function runCodexSetupImpl(
   let apiKey: string | undefined = initial.llm.apiKey;
 
   if (authMode === 'oauth') {
-    io.print('  Launching device-code flow…');
+    io.print('  코드로 로그인합니다…');
     try {
       await loginWithCodex({
         onProgress: (p) => {
           if (p.type === 'user_code') {
             io.print('');
-            io.print(`    1) Open in any browser: ${p.loginUrl}`);
-            io.print(`    2) Enter code:          ${p.userCode}`);
+            io.print(`    1) 아무 브라우저에서 열기: ${p.loginUrl}`);
+            io.print(`    2) 코드 입력:             ${p.userCode}`);
             io.print('');
-            io.print('  Waiting for sign-in…');
+            io.print('  로그인을 기다리는 중…');
           }
-          if (p.type === 'saved') io.print('  Signed in. Tokens saved.');
+          if (p.type === 'saved') io.print('  로그인했습니다. 저장했습니다.');
         },
         fetchImpl: opts.fetchImpl,
         sleepImpl: opts.sleepImpl,

package/src/dashboard/index.ts

@@ -725,7 +725,8 @@ import { SELF_IMPLEMENT_TOOL_NAMES } from '../boot/daemon-tools/self-implement-n
 import { FOLD_LIMITS, type FoldMode } from '../log-entry.js';
 import { renderToolCallEvent, renderToolResultVariants } from '../chat/tool-render/index.js';
 import { FoldStack } from '../fold-stack.js';
-import { getSkillIndex, reloadSkillIndex, applySkillFilter } from '../skills/index.js';
+import { getSkillIndex, reloadSkillIndex, applySkillFilter, skillIndexProblems } from '../skills/index.js';
+import { skillRepairNotice } from '../skills/repair.js';
 import type { DetectResult } from '../skills/router.js';
 import { detectUrlRoute } from '../skills/url-router.js';
 import {
@@ -7190,6 +7191,21 @@ Mode- and sync-specific instructions are injected per-turn when relevant — do
   // and after each user-initiated skill cursor change.
   const skillView: SkillViewState = createSkillViewState(LOCAL_SKILLS_DIR);
   try { refreshSkills(skillView); refreshSkillFiles(skillView); } catch { /* missing root fine */ }
+  // SK2 — a skill the index could not read is a one-line notice with the repair command, never a crash.
+  try {
+    getSkillIndex();
+    const problems = skillIndexProblems();
+    const notice = skillRepairNotice(problems);
+    if (notice) chatLines.push(C.info(notice));
+    // ER1 — tell operations too (consented · scrubbed · async); a kept unsent report is retried once a day.
+    void import('../error-report/report.js').then(async ({ reportError, retryPendingErrorReport }) => {
+      await retryPendingErrorReport();
+      for (const p of problems.slice(0, 3)) {
+        const outcome = await reportError({ code: 'skill-index', message: `${p.name}: ${p.code ?? ''} ${p.error}`.trim(), surface: 'tui' });
+        if (outcome.sent && outcome.reportId) { chatLines.push(C.muted(`  운영팀에 알렸습니다 (보고 번호 ${outcome.reportId})`)); }
+      }
+    }).catch(() => { /* reporting never breaks the dashboard */ });
+  } catch { /* the notice is advisory */ }
 
   // Scratch visibility (Phase S5). When closed, the workingDir
   // layouts drop the scratch cell so the remaining panes expand

package/src/dashboard/slash-runtime/dashboard-handlers.ts

@@ -1370,8 +1370,8 @@ export function buildDashboardSlashRegistry(): SlashCommandRegistry<DashboardSla
     ctx.attachmentRowMap.clear();
     ctx.clearLogSearch();
     ctx.clearLogFilter();
-    ctx.pushDebugLine(ctx.muted('Status cleared'));
-    ctx.chatLines.push(ctx.muted('Status cleared'));
+    ctx.pushDebugLine(ctx.muted('Chat log cleared'));
+    ctx.chatLines.push(ctx.muted('Chat log cleared'));
     ctx.setChatScrollOffset(-1);
   });
 

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

@@ -3,7 +3,9 @@ import { visibleWidth } from '../../tui.js';
 
 const ESSENTIAL_KEYS = [
   ['Enter', 'Send message'],
-  ['Esc', 'Clear input / close help modal'],
+  // U1 · 2026-10-02 — stopping and queueing while an answer streams were missing from help (same line count:
+  // the modal has a row budget and falls back to the chat log when it is exceeded).
+  ['Esc', 'Stop the answer (Esc again = rewind) · clear input / close help'],
   ['Ctrl+U', 'Clear text before cursor'],
   ['Ctrl+W', 'Delete previous word'],
   ['Ctrl+← / →', 'Move by word'],
@@ -11,7 +13,7 @@ const ESSENTIAL_KEYS = [
   ['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'],
+  ['Ctrl+↑', 'Recall a queued line (Enter while answering queues it)'],
 ] as const;
 
 function fitLine(text: string, width: number): string {

package/src/decisions/decision-cards.ts

@@ -0,0 +1,291 @@
+// DEC-TG(대표 10-02 07:1x) — «밖에 있어도 주요 결정을 텔레그램·디스코드로 다 끝낸다».
+// `elanous decisions raise` 로 올라온 결정 → 대표 DM 카드(SCQA 요약 ⊕ 선택지 버튼 ⊕ 메모 달기) → 누르면 CLI `decide` 와 같은
+// 원장 메서드로 기록 → 올린 자리에 회신 → 카드는 «결정됨: A · 시각»으로 바뀐다.
+// ⛔ 보안: 버튼은 대표 id 만 받는다(그 밖은 무시 ⊕ 관측). 되돌릴 수 없는 범주(결제·외부 게시·보안·비가역)는 «되돌릴 수 없음» ⊕ 두 번 확인.
+// 플랫폼(텔레그램·디스코드)은 `CardTransport` 하나만 구현한다 — 판단은 전부 여기 있다.
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { debug } from '../debug/log.js';
+import { DecisionLedger, type DecisionEntry } from './decision-ledger.js';
+
+export type CardPlatform = 'telegram' | 'discord';
+export interface CardButton { label: string; data: string }
+export interface CardView { text: string; buttons: CardButton[][] }
+export interface CardRef { chat: string; message: string }
+
+/** What a platform must provide. Every method is best-effort; failures are observed, never thrown to the poller. */
+export interface CardTransport {
+  platform: CardPlatform;
+  /** Owner DM destinations (Telegram chat id = user id for a DM; Discord DM channel id). */
+  ownerChats(): Promise<string[]>;
+  send(chat: string, view: CardView): Promise<CardRef | null>;
+  edit(ref: CardRef, view: CardView): Promise<void>;
+  /** Plain text (reminders, list replies). */
+  notify(chat: string, text: string): Promise<void>;
+}
+
+const IRREVERSIBLE = new Set(['money', 'publish', 'security', 'irreversible', 'secret']);
+export const DECISION_DATA_PREFIX = 'dec:';
+const REMIND_BEFORE_MS = 2 * 3600_000;
+
+export function isIrreversible(entry: Pick<DecisionEntry, 'category'>): boolean {
+  return IRREVERSIBLE.has(entry.category);
+}
+
+const kst = (at: string) => new Intl.DateTimeFormat('ko-KR', { timeZone: 'Asia/Seoul', month: 'numeric', day: 'numeric', hour: '2-digit', minute: '2-digit', hour12: false }).format(new Date(at));
+
+/** The card body: title, SCQA in four short lines, options with consequences, recommendation, deadline. */
+export function renderCardText(e: DecisionEntry, extra: { note?: string; confirm?: string } = {}): string {
+  const lines = [
+    `🗳 결정 요청 ${e.id}${isIrreversible(e) ? ' · ⚠️ 되돌릴 수 없음' : ''}`,
+    `«${e.title}» · 올린 자리: ${e.raisedBy.agent}${e.raisedBy.track ? `(${e.raisedBy.track})` : ''}`,
+    '',
+    `상황: ${e.scqa.s}`,
+    `문제: ${e.scqa.c}`,
+    ...(e.scqa.q ? [`질문: ${e.scqa.q}`] : []),
+    ...(e.scqa.a ? [`제안: ${e.scqa.a}`] : []),
+    '',
+    ...e.options.map((o) => `${o.key.toUpperCase()}) ${o.label} — ${o.consequence}`),
+    'skipped' in e.recommendation ? `권고 없음: ${e.recommendation.reason}` : `권고: ${e.recommendation.option.toUpperCase()} — ${e.recommendation.why}`,
+    ...(e.dueAt ? [`기한: ${kst(e.dueAt)}`] : []),
+    ...(extra.note ? ['', `📝 메모: ${extra.note}`] : []),
+  ];
+  if (extra.confirm) {
+    const option = e.options.find((o) => o.key === extra.confirm);
+    lines.push('', `⚠️ ${extra.confirm.toUpperCase()}) ${option?.label ?? ''} — 되돌릴 수 없습니다. 정말 이것으로 정할까요?`);
+  }
+  return lines.join('\n');
+}
+
+export function renderCard(e: DecisionEntry, extra: { note?: string; confirm?: string } = {}): CardView {
+  const text = renderCardText(e, extra);
+  if (e.status === 'decided') {
+    const option = e.options.find((o) => o.key === e.choice);
+    return { text: `${text}\n\n✅ 결정됨: ${e.choice?.toUpperCase() ?? '?'}) ${option?.label ?? ''} · ${e.decidedAt ? kst(e.decidedAt) : ''}${e.note ? `\n📝 ${e.note}` : ''}`, buttons: [] };
+  }
+  if (e.status === 'withdrawn') return { text: `${text}\n\n↩️ 철회됨${e.withdrawReason ? `: ${e.withdrawReason}` : ''}`, buttons: [] };
+  if (extra.confirm) {
+    return { text, buttons: [[
+      { label: `✅ 예, ${extra.confirm.toUpperCase()} 로 정한다`, data: `${DECISION_DATA_PREFIX}${e.id}:${extra.confirm}:ok` },
+      { label: '취소', data: `${DECISION_DATA_PREFIX}${e.id}:-` },
+    ]] };
+  }
+  const choices = e.options.map((o) => ({ label: Array.from(`${o.key.toUpperCase()}) ${o.label}`).slice(0, 60).join(''), data: `${DECISION_DATA_PREFIX}${e.id}:${o.key}` }));
+  const rows: CardButton[][] = [];
+  for (let i = 0; i < choices.length; i += 2) rows.push(choices.slice(i, i + 2));
+  rows.push([{ label: '📝 메모 달기', data: `${DECISION_DATA_PREFIX}${e.id}:memo` }]);
+  return { text, buttons: rows };
+}
+
+export type ParsedTap = { id: string; action: 'choose'; key: string; confirmed: boolean } | { id: string; action: 'memo' } | { id: string; action: 'cancel' };
+
+export function parseTap(data: string): ParsedTap | null {
+  const m = /^dec:(D-\d{8}-\d+):([a-z]|memo|-)(:ok)?$/.exec(data);
+  if (!m) return null;
+  if (m[2] === 'memo') return { id: m[1]!, action: 'memo' };
+  if (m[2] === '-') return { id: m[1]!, action: 'cancel' };
+  return { id: m[1]!, action: 'choose', key: m[2]!, confirmed: Boolean(m[3]) };
+}
+
+interface CardState {
+  /** First start of this platform's service — decisions raised before it are not pushed (no burst of old items at
+   *  deploy); they stay reachable through `/decisions`. */
+  since?: string;
+  cards: Record<string, { refs: CardRef[]; closed?: boolean; remindedAt?: string; note?: string }>;
+}
+
+export interface DecisionCardServiceOptions {
+  transport: CardTransport;
+  /** Owner user ids for this platform — taps from anyone else are refused and observed. */
+  ownerIds: readonly string[];
+  ledger?: DecisionLedger;
+  /** Where this platform keeps which card it sent (one file per platform — the two bots may run in different processes). */
+  statePath?: string;
+  now?: () => Date;
+  /** Tell the seat that raised it. Default: none (observed only). */
+  replyToRaiser?: (entry: DecisionEntry, via: CardPlatform) => Promise<void>;
+}
+
+export type TapOutcome =
+  | { kind: 'refused' } | { kind: 'ignored' } | { kind: 'unknown' }
+  | { kind: 'confirm'; view: CardView; toast: string }
+  | { kind: 'decided'; view: CardView; toast: string }
+  | { kind: 'cancelled'; view: CardView; toast: string }
+  | { kind: 'memo-requested'; toast: string }
+  | { kind: 'closed'; view: CardView; toast: string };
+
+/** One per platform bot. `tick()` sends new cards, closes decided ones, sends reminders; `tap()` handles a button. */
+export class DecisionCardService {
+  private readonly ledger: DecisionLedger;
+  private readonly statePath: string;
+  private readonly now: () => Date;
+  constructor(private readonly opts: DecisionCardServiceOptions) {
+    this.ledger = opts.ledger ?? new DecisionLedger();
+    this.statePath = opts.statePath ?? join(this.ledger.path, '..', `cards-${opts.transport.platform}.json`);
+    this.now = opts.now ?? (() => new Date());
+  }
+
+  private load(): CardState {
+    try { return JSON.parse(readFileSync(this.statePath, 'utf8')) as CardState; } catch { return { cards: {} }; }
+  }
+  private save(state: CardState): void {
+    mkdirSync(join(this.statePath, '..'), { recursive: true });
+    const tmp = `${this.statePath}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(state, null, 2), { mode: 0o600 });
+    renameSync(tmp, this.statePath);
+  }
+
+  isOwner(userId: string): boolean { return this.opts.ownerIds.includes(userId); }
+
+  /** Send cards for new open decisions · close cards decided elsewhere · remind two hours before a deadline. */
+  async tick(): Promise<{ sent: number; closed: number; reminded: number }> {
+    const platform = this.opts.transport.platform;
+    const state = this.load();
+    let sent = 0; let closed = 0; let reminded = 0;
+    let all: DecisionEntry[];
+    try { all = this.ledger.list({ status: 'all' }); } catch (error) {
+      debug.log('decisions.telegram', 'ledger-unreadable', { platform, reason: error instanceof Error ? error.message.slice(0, 80) : 'unknown' }, { level: 'warn' });
+      return { sent, closed, reminded };
+    }
+    let dirty = false;
+    if (!state.since) { state.since = this.now().toISOString(); dirty = true; debug.log('decisions.telegram', 'baseline', { platform, since: state.since }); }
+    const chats = await this.opts.transport.ownerChats().catch(() => [] as string[]);
+    for (const e of all) {
+      const card = state.cards[e.id];
+      if (e.status === 'open' && !card && e.options.length >= 2 && e.raisedAt !== undefined && e.raisedAt >= state.since) {
+        const refs: CardRef[] = [];
+        for (const chat of chats) {
+          const ref = await this.opts.transport.send(chat, renderCard(e)).catch(() => null);
+          if (ref) refs.push(ref);
+        }
+        if (refs.length) { state.cards[e.id] = { refs }; sent++; }
+        debug.log('decisions.telegram', 'card-sent', { platform, id: e.id, category: e.category, chats: chats.length, delivered: refs.length });
+        continue;
+      }
+      if (card && !card.closed && e.status !== 'open') {
+        for (const ref of card.refs) await this.opts.transport.edit(ref, renderCard(e)).catch(() => undefined);
+        card.closed = true; closed++;
+        debug.log('decisions.telegram', 'card-closed', { platform, id: e.id, status: e.status });
+        continue;
+      }
+      if (e.status === 'open' && card && e.dueAt && !card.remindedAt && this.now().getTime() >= Date.parse(e.dueAt) - REMIND_BEFORE_MS) {
+        for (const chat of chats) await this.opts.transport.notify(chat, `⏰ 기한 2시간 전 — ${e.id} «${e.title}» (기한 ${kst(e.dueAt)}) · 카드에서 정하거나 /decisions`).catch(() => undefined);
+        card.remindedAt = this.now().toISOString(); reminded++;
+        debug.log('decisions.telegram', 'reminded', { platform, id: e.id });
+      }
+    }
+    if (dirty || sent || closed || reminded) this.save(state);
+    return { sent, closed, reminded };
+  }
+
+  /** A button tap. Never throws. */
+  async tap(userId: string, data: string): Promise<TapOutcome> {
+    const platform = this.opts.transport.platform;
+    const parsed = parseTap(data);
+    if (!parsed) return { kind: 'ignored' };
+    if (!this.isOwner(userId)) {
+      debug.log('decisions.telegram', 'tap-refused', { platform, id: parsed.id }, { level: 'warn' });
+      return { kind: 'refused' };
+    }
+    let entry: DecisionEntry;
+    try { entry = this.ledger.show(parsed.id); } catch { return { kind: 'unknown' }; }
+    const state = this.load();
+    const card = state.cards[entry.id];
+    if (entry.status !== 'open') return { kind: 'closed', view: renderCard(entry), toast: '이미 정해진 결정입니다' };
+    if (parsed.action === 'memo') {
+      debug.log('decisions.telegram', 'memo-requested', { platform, id: entry.id });
+      return { kind: 'memo-requested', toast: '메모를 보내 주세요 — 다음 메시지가 메모가 됩니다' };
+    }
+    if (parsed.action === 'cancel') return { kind: 'cancelled', view: renderCard(entry, card?.note ? { note: card.note } : {}), toast: '취소했습니다' };
+    if (!entry.options.some((o) => o.key === parsed.key)) return { kind: 'unknown' };
+    if (isIrreversible(entry) && !parsed.confirmed) {
+      debug.log('decisions.telegram', 'confirm-asked', { platform, id: entry.id, key: parsed.key });
+      return { kind: 'confirm', view: renderCard(entry, { confirm: parsed.key, ...(card?.note ? { note: card.note } : {}) }), toast: '되돌릴 수 없는 결정 — 한 번 더 확인해 주세요' };
+    }
+    let decided: DecisionEntry;
+    try {
+      // Same ledger method the CLI `decide` uses — one record path.
+      decided = this.ledger.decide(entry.id, parsed.key, { kind: 'human' }, card?.note);
+    } catch (error) {
+      debug.log('decisions.telegram', 'decide-failed', { platform, id: entry.id, reason: error instanceof Error ? error.message.slice(0, 80) : 'unknown' }, { level: 'warn' });
+      try { const now = this.ledger.show(entry.id); if (now.status !== 'open') return { kind: 'closed', view: renderCard(now), toast: '이미 정해진 결정입니다' }; } catch { /* fall through */ }
+      return { kind: 'unknown' };
+    }
+    const view = renderCard(decided);
+    if (card) {
+      for (const ref of card.refs) await this.opts.transport.edit(ref, view).catch(() => undefined);
+      card.closed = true;
+      this.save(state);
+    }
+    debug.log('decisions.telegram', 'decided', { platform, id: decided.id, choice: decided.choice, category: decided.category, noted: Boolean(decided.note) });
+    await this.opts.replyToRaiser?.(decided, platform).catch((error: unknown) => {
+      debug.log('decisions.telegram', 'reply-failed', { platform, id: decided.id, reason: error instanceof Error ? error.message.slice(0, 80) : 'unknown' }, { level: 'warn' });
+    });
+    return { kind: 'decided', view, toast: `결정했습니다: ${decided.choice?.toUpperCase()}` };
+  }
+
+  /** Store a memo typed after «메모 달기»; the card shows it and the eventual decision carries it. */
+  async setNote(userId: string, id: string, note: string): Promise<CardView | null> {
+    if (!this.isOwner(userId)) return null;
+    let entry: DecisionEntry;
+    try { entry = this.ledger.show(id); } catch { return null; }
+    const clean = note.replace(/\s+/g, ' ').trim().slice(0, 300);
+    if (!clean || entry.status !== 'open') return null;
+    const state = this.load();
+    const card = state.cards[id] ?? { refs: [] };
+    card.note = clean;
+    state.cards[id] = card;
+    this.save(state);
+    const view = renderCard(entry, { note: clean });
+    for (const ref of card.refs) await this.opts.transport.edit(ref, view).catch(() => undefined);
+    debug.log('decisions.telegram', 'memo-set', { platform: this.opts.transport.platform, id, chars: clean.length });
+    return view;
+  }
+
+  /** `/decisions` — open decisions as one list; each card is sent again so the buttons are at hand. */
+  async listOpen(chat: string): Promise<string> {
+    let open: DecisionEntry[];
+    try { open = this.ledger.list({ status: 'open' }).filter((e) => e.options.length >= 2); } catch { return '결정 원장을 읽지 못했습니다.'; }
+    if (!open.length) return '열린 결정이 없습니다.';
+    const state = this.load();
+    for (const e of open) {
+      const ref = await this.opts.transport.send(chat, renderCard(e, state.cards[e.id]?.note ? { note: state.cards[e.id]!.note } : {})).catch(() => null);
+      if (ref) { const card = state.cards[e.id] ?? { refs: [] }; card.refs.push(ref); state.cards[e.id] = card; }
+    }
+    this.save(state);
+    debug.log('decisions.telegram', 'listed', { platform: this.opts.transport.platform, open: open.length });
+    return `열린 결정 ${open.length}건 — ${open.map((e) => `${e.id}${e.dueAt ? `(기한 ${kst(e.dueAt)})` : ''}`).join(' · ')}`;
+  }
+}
+
+/** Reply line for the seat that raised it. Posted to the coordination PR when `decisions.replyGhPr` = "owner/repo#N". */
+export function raiserReplyText(e: DecisionEntry, via: CardPlatform): string {
+  const option = e.options.find((o) => o.key === e.choice);
+  const at = e.decidedAt ? new Intl.DateTimeFormat('sv-SE', { timeZone: 'Asia/Seoul', dateStyle: 'short', timeStyle: 'short' }).format(new Date(e.decidedAt)) : '';
+  return `**[대표]** ${at} KST → ${e.raisedBy.agent} · 결정 ${e.id} «${e.title}» = ${e.choice?.toUpperCase()}) ${option?.label ?? ''}${e.note ? ` · 메모: ${e.note}` : ''} (${via === 'telegram' ? '텔레그램' : '디스코드'})`;
+}
+
+export function ghPrReplier(target: string, run: (args: string[], stdin: string) => Promise<number> = runGh): (e: DecisionEntry, via: CardPlatform) => Promise<void> {
+  const m = /^([\w.-]+\/[\w.-]+)#(\d+)$/.exec(target.trim());
+  return async (e, via) => {
+    if (!m) throw new Error('decisions.replyGhPr must be owner/repo#N');
+    const code = await run(['pr', 'comment', m[2]!, '--repo', m[1]!, '--body-file', '-'], raiserReplyText(e, via));
+    debug.log('decisions.telegram', 'replied', { id: e.id, via, target: 'gh-pr', ok: code === 0 });
+    if (code !== 0) throw new Error(`gh exit ${code}`);
+  };
+}
+
+/** Post as the automation App (not the machine's personal gh login — that would make 대표 a participant and mail them),
+ *  with proxy variables removed (they break gh on the ops host). TC review #22660. */
+async function runGh(args: string[], stdin: string): Promise<number> {
+  const env: Record<string, string> = {};
+  for (const [k, v] of Object.entries(process.env)) if (v !== undefined && !/^(https?|all|no)_proxy$/i.test(k)) env[k] = v;
+  try {
+    const { githubAutomationToken } = await import('../auth/github-app-token.js');
+    const token = githubAutomationToken();
+    if (token) env.GH_TOKEN = token;
+    debug.log('decisions.telegram', 'reply-identity', { app: Boolean(token) });
+  } catch { /* falls back to the machine login */ }
+  const proc = Bun.spawn(['gh', ...args], { stdin: new Blob([stdin]), stdout: 'ignore', stderr: 'ignore', env });
+  return proc.exited;
+}