elanous 0.2.7 → 0.2.9

package/src/self-dev/orchestrate.ts

@@ -987,6 +987,23 @@ async function deleteLabelledJobs(runId: string, selectedTargets: readonly { con
   return counts.reduce((sum, count) => sum + count, 0);
 }
 
+/** `self-dev-runs/<runId>/pid.json` — what `harness stop <runId>` reads (start time guards PID reuse).
+ *  HS1: written as soon as the run ID exists, not only when the jobs start — pod planning and image sync can
+ *  take minutes before that, and a stop in that window found «no process» (10-01 · three runs). */
+export function writeRunPidRecord(runId: string, runsDir: string = selfDevRunsDir()): string {
+  const pidPath = join(runsDir, runId, 'pid.json');
+  mkdirSync(join(runsDir, runId), { recursive: true });
+  const temporary = `${pidPath}.${process.pid}.${randomUUID()}.tmp`;
+  const fd = openSync(temporary, 'wx', 0o600);
+  try {
+    try {
+      writeFileSync(fd, JSON.stringify({ pid: process.pid, startedAt: Date.now() - Math.floor(process.uptime() * 1000), argv0: process.argv0 }));
+    } finally { closeSync(fd); }
+    renameSync(temporary, pidPath);
+  } catch (error) { unlinkSync(temporary); throw error; }
+  return pidPath;
+}
+
 /**
  * Run N self-dev jobs in parallel under the TOX dispatcher and resolve
  * once every job reaches a terminal status.
@@ -1419,17 +1436,7 @@ export function orchestrateSelfDev(opts: OrchestrateSelfDevOptions): Promise<Sel
     signals.on('SIGTERM', onTerm);
     signals.on('SIGINT', onInt);
     try {
-      if (pidPath) {
-        mkdirSync(join(opts.runsDir ?? selfDevRunsDir(), runId!), { recursive: true });
-        const temporary = `${pidPath}.${process.pid}.${randomUUID()}.tmp`;
-        const fd = openSync(temporary, 'wx', 0o600);
-        try {
-          try {
-            writeFileSync(fd, JSON.stringify({ pid: process.pid, startedAt: Date.now() - Math.floor(process.uptime() * 1000), argv0: process.argv0 }));
-          } finally { closeSync(fd); }
-          renameSync(temporary, pidPath);
-        } catch (error) { unlinkSync(temporary); throw error; }
-      }
+      if (pidPath) writeRunPidRecord(runId!, opts.runsDir ?? selfDevRunsDir());
     } catch (error) { cleanup(); reject(error); return; }
 
     // Current full result set: resumed-done goals + each running task's

package/src/shell-env-bootstrap.ts

@@ -88,7 +88,7 @@ export function parsePrintenv(raw: string): Record<string, string> {
  *    - HOME, USER, LOGNAME, SHELL, TERM
  *    - LANG / LC_* — locale matters for some prompts (starship, powerlevel)
  *  Everything else is left for the login shell itself to define. */
-export function runPrintenvCapture(): Record<string, string> | null {
+function captureSeed(): { shell: string; seedEnv: NodeJS.ProcessEnv } | null {
   const shell = process.env.SHELL;
   if (!shell) return null;
   const base = basename(shell);
@@ -103,6 +103,22 @@ export function runPrintenvCapture(): Record<string, string> | null {
   for (const [k, v] of Object.entries(process.env)) {
     if (k.startsWith('LC_') && typeof v === 'string') seedEnv[k] = v;
   }
+  return { shell, seedEnv };
+}
+
+/** printenv output → env, or null when it does not look like a real login env. */
+function acceptCapture(stdout: string): Record<string, string> | null {
+  if (!stdout) return null;
+  const parsed = parsePrintenv(stdout);
+  // Sanity: require PATH and at least 5 keys, else something is off.
+  if (!parsed.PATH || Object.keys(parsed).length < 5) return null;
+  return parsed;
+}
+
+export function runPrintenvCapture(): Record<string, string> | null {
+  const seed = captureSeed();
+  if (!seed) return null;
+  const { shell, seedEnv } = seed;
 
   let res: ReturnType<typeof spawnSync>;
   try {
@@ -119,12 +135,33 @@ export function runPrintenvCapture(): Record<string, string> | null {
   }
   if (res.status !== 0 && res.status !== null) return null;
   if (res.signal) return null;
-  const stdout = typeof res.stdout === 'string' ? res.stdout : '';
-  if (!stdout) return null;
-  const parsed = parsePrintenv(stdout);
-  // Sanity: require PATH and at least 5 keys, else something is off.
-  if (!parsed.PATH || Object.keys(parsed).length < 5) return null;
-  return parsed;
+  return acceptCapture(typeof res.stdout === 'string' ? res.stdout : '');
+}
+
+/** Fill the login-env cache off the event loop (daemon boot). The first web-terminal spawn otherwise ran the
+ *  `-l -i` printenv with spawnSync and froze the whole daemon for ~3 s (10-02 TERM1). A no-op once captured;
+ *  a failed warm leaves the cache empty so `getCapturedEnv()` still tries (and falls back) as before. */
+export async function warmCapturedEnv(spawn: typeof Bun.spawn = Bun.spawn): Promise<boolean> {
+  if (captured) return cached !== null;
+  if (process.env.ELANOUS_SKIP_LOGIN_ENV === '1' || process.env.TERM_PROGRAM === 'monad-agent-nested') return false;
+  const seed = captureSeed();
+  if (!seed) return false;
+  const start = Date.now();
+  try {
+    const proc = spawn([seed.shell, '-l', '-i', '-c', 'printenv'], { env: seed.seedEnv as Record<string, string>, stdin: 'ignore', stdout: 'pipe', stderr: 'ignore' });
+    const timer = setTimeout(() => proc.kill(), TIMEOUT_MS);
+    const [out, code] = await Promise.all([new Response(proc.stdout as ReadableStream).text(), proc.exited]);
+    clearTimeout(timer);
+    const parsed = code === 0 ? acceptCapture(out) : null;
+    if (captured) return cached !== null; // a synchronous capture won the race
+    if (!parsed) return false;
+    cached = parsed;
+    captured = true;
+    debug.log('shell.envbootstrap.capture', 'warmed', { ok: true, ms: Date.now() - start, keyCount: Object.keys(parsed).length });
+    return true;
+  } catch {
+    return false;
+  }
 }
 
 /** Return the captured login env, running the capture on first call.

package/src/skills/connect-claude-plugin.ts

@@ -0,0 +1,142 @@
+// EN8 — `elanous connect <플러그인 폴더>`: Claude Code 플러그인(`.claude-plugin/plugin.json`)을 «그대로» 쓴다.
+// 스킬 폴더는 EN9 와 같은 칸(`skills.sources[]` · kind connected · id `plugin:<이름>`)에 등록하고(복사 없음), `.mcp.json` 의 서버는 «꺼진 채»(`enabled:false`)
+// `mcp.servers[]` 에 넣는다 — 켜기는 사람이 확인한 뒤에 한다. 환경변수가 필요한 서버는 등록하지 않고 이유를 말한다.
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { findSkillFolders } from './connect.js';
+
+export const CLAUDE_PLUGIN_MANIFEST = join('.claude-plugin', 'plugin.json');
+
+export function isClaudePluginDir(dir: string): boolean {
+  return existsSync(join(dir, CLAUDE_PLUGIN_MANIFEST));
+}
+
+/** What we write into `mcp.servers[]` (raw config shape — parsed by parseMcpServerSpec). */
+export type PluginMcpServer =
+  | { id: string; command: string[]; enabled: false }
+  | { id: string; transport: 'http'; url: string; enabled: false };
+
+export interface ClaudePlugin {
+  root: string;
+  name: string;
+  version: string;
+  /** Skill folders that hold at least one SKILL.md folder. */
+  skillRoots: string[];
+  skills: string[];
+  mcp: PluginMcpServer[];
+  skipped: { name: string; reason: string }[];
+}
+
+function readJson(path: string): unknown {
+  return JSON.parse(readFileSync(path, 'utf8'));
+}
+
+function asObject(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : null;
+}
+
+function serverId(plugin: string, name: string): string {
+  return `${plugin}-${name}`.toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '');
+}
+
+function expandRoot(value: string, root: string): string {
+  return value.split('${CLAUDE_PLUGIN_ROOT}').join(root);
+}
+
+/** One `.mcp.json` entry → a server spec, or the reason it is not registered. */
+export function convertMcpEntry(plugin: string, name: string, raw: unknown, root: string): PluginMcpServer | { skipped: string } {
+  const entry = asObject(raw);
+  if (!entry) return { skipped: '형식을 읽지 못했습니다' };
+  const env = asObject(entry.env);
+  if (env && Object.keys(env).length) return { skipped: `환경변수가 필요합니다(${Object.keys(env).join(', ')}) — 직접 등록해 주세요` };
+  const id = serverId(plugin, name);
+  const type = typeof entry.type === 'string' ? entry.type : undefined;
+  if (typeof entry.url === 'string' && entry.url) {
+    if (type && type !== 'http') return { skipped: `${type} 방식은 아직 지원하지 않습니다` };
+    if (entry.headers && Object.keys(asObject(entry.headers) ?? {}).length) return { skipped: '헤더(인증)가 필요합니다 — 직접 등록해 주세요' };
+    return { id, transport: 'http', url: entry.url, enabled: false };
+  }
+  if (typeof entry.command === 'string' && entry.command) {
+    const args = Array.isArray(entry.args) ? entry.args.filter((a): a is string => typeof a === 'string') : [];
+    return { id, command: [expandRoot(entry.command, root), ...args.map((a) => expandRoot(a, root))], enabled: false };
+  }
+  return { skipped: '실행 명령이나 주소가 없습니다' };
+}
+
+function mcpSource(root: string, manifest: Record<string, unknown>): Record<string, unknown> | null {
+  const declared = manifest.mcpServers;
+  let raw: unknown = null;
+  if (typeof declared === 'string') {
+    const path = resolve(root, declared);
+    if (path.startsWith(`${root}/`) && existsSync(path)) raw = readJson(path);
+  } else if (asObject(declared)) {
+    raw = declared;
+  } else if (existsSync(join(root, '.mcp.json'))) {
+    raw = readJson(join(root, '.mcp.json'));
+  }
+  const object = asObject(raw);
+  if (!object) return null;
+  return asObject(object.mcpServers) ?? object;
+}
+
+function skillRootsOf(root: string, manifest: Record<string, unknown>): string[] {
+  const declared = typeof manifest.skills === 'string' ? [manifest.skills]
+    : Array.isArray(manifest.skills) ? manifest.skills.filter((s): s is string => typeof s === 'string') : [];
+  const candidates = [join(root, 'skills'), ...declared.map((rel) => resolve(root, rel))]
+    .filter((path) => path === root || path.startsWith(`${root}/`));
+  return [...new Set(candidates)].filter((path) => findSkillFolders(path).length > 0);
+}
+
+/** Read a Claude Code plugin folder. Throws only when the manifest is not JSON. */
+export function readClaudePlugin(dir: string): ClaudePlugin {
+  const root = resolve(dir);
+  const manifest = asObject(readJson(join(root, CLAUDE_PLUGIN_MANIFEST))) ?? {};
+  const name = typeof manifest.name === 'string' && manifest.name.trim() ? manifest.name.trim() : root.split('/').pop() ?? 'plugin';
+  const version = typeof manifest.version === 'string' ? manifest.version : '0.0.0';
+  const skillRoots = skillRootsOf(root, manifest);
+  const skills = skillRoots.flatMap(findSkillFolders).sort();
+  const mcp: PluginMcpServer[] = [];
+  const skipped: ClaudePlugin['skipped'] = [];
+  for (const [server, raw] of Object.entries(mcpSource(root, manifest) ?? {})) {
+    const converted = convertMcpEntry(name, server, raw, root);
+    if ('skipped' in converted) skipped.push({ name: server, reason: converted.skipped });
+    else mcp.push(converted);
+  }
+  return { root, name, version, skillRoots, skills, mcp, skipped };
+}
+
+export interface ClaudePluginPlan {
+  plugin: ClaudePlugin;
+  newSkillRoots: string[];
+  newMcp: PluginMcpServer[];
+  state: 'new' | 'already' | 'empty';
+}
+
+export function planClaudePlugin(plugin: ClaudePlugin, activeDirs: readonly string[], mcpIds: readonly string[]): ClaudePluginPlan {
+  const newSkillRoots = plugin.skillRoots.filter((dir) => !activeDirs.includes(dir));
+  const newMcp = plugin.mcp.filter((server) => !mcpIds.includes(server.id));
+  const state = !plugin.skills.length && !plugin.mcp.length ? 'empty' : newSkillRoots.length || newMcp.length ? 'new' : 'already';
+  return { plugin, newSkillRoots, newMcp, state };
+}
+
+export function claudePluginPrompt(plan: ClaudePluginPlan): string {
+  const { plugin } = plan;
+  const head = `Claude 플러그인 «${plugin.name}» ${plugin.version}`;
+  const skipped = plugin.skipped.map((s) => `\n  · MCP ${s.name}: ${s.reason}`).join('');
+  if (plan.state === 'empty') return `${head}에서 쓸 스킬이나 MCP 서버를 찾지 못했습니다.${skipped}`;
+  if (plan.state === 'already') return `${head}은 이미 연결돼 있습니다 — 스킬 ${plugin.skills.length}개 · MCP ${plugin.mcp.length}개.${skipped}`;
+  const parts = [
+    plugin.skills.length ? `스킬 ${plugin.skills.length}개(그 자리를 그대로 씁니다)` : '',
+    plan.newMcp.length ? `MCP 서버 ${plan.newMcp.length}개(꺼진 채로 등록 — 켜기는 따로 확인합니다)` : '',
+  ].filter(Boolean).join(' · ');
+  return `${head}: ${parts}${skipped}\n가져올까요? [Y/n] `;
+}
+
+/** How to turn one registered server on — shown after connecting, never done for the person. */
+export function mcpEnableHint(servers: readonly PluginMcpServer[], all: readonly { id?: unknown }[]): string[] {
+  return servers.map((server) => {
+    const index = all.findIndex((row) => row.id === server.id);
+    const what = 'url' in server ? server.url : server.command.join(' ');
+    return `  · ${server.id} — ${what}\n    켜려면: elanous config set mcp.servers.${index}.enabled true`;
+  });
+}

package/src/skills/connect.ts

@@ -0,0 +1,70 @@
+// EN9 — `elanous connect <claude|codex>`: 쓰던 에이전트의 스킬을 찾아 «복사가 아니라 등록»한다(대표 «기존 플러그인을 그대로 쓸 수 있다»).
+// 등록 = `skills.sources[]`(EN5 한 모델)에 kind `connected` 로 원본 경로를 더한다 · 원본은 읽기만 하고 고치지 않는다 · 읽지 못한 스킬은 SK2(`skills repair`)로 안내한다.
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { skillSourceId, type SkillSource } from '../user-config.js';
+
+export type ConnectAgent = 'claude' | 'codex';
+export const CONNECT_AGENTS: readonly ConnectAgent[] = ['claude', 'codex'];
+
+const AGENT_LABEL: Record<ConnectAgent, string> = { claude: 'Claude Code', codex: 'Codex' };
+
+export function connectSkillRoot(agent: ConnectAgent, home = homedir()): string {
+  return agent === 'claude' ? join(home, '.claude', 'skills') : join(home, '.codex', 'skills');
+}
+
+/** Folders that hold a SKILL.md (one level, like the skill index). Hidden folders such as `.system` are skipped. */
+export function findSkillFolders(root: string): string[] {
+  try {
+    return readdirSync(root)
+      .filter((name) => !name.startsWith('.'))
+      .filter((name) => {
+        try { return statSync(join(root, name)).isDirectory() && existsSync(join(root, name, 'SKILL.md')); }
+        catch { return false; }
+      })
+      .sort();
+  } catch { return []; }
+}
+
+export type ConnectPlan =
+  | { agent: ConnectAgent; root: string; state: 'missing' }
+  | { agent: ConnectAgent; root: string; state: 'empty' }
+  | { agent: ConnectAgent; root: string; state: 'already'; skills: string[] }
+  | { agent: ConnectAgent; root: string; state: 'new'; skills: string[] };
+
+/** `activeDirs` = the skill directories elanous reads today (defaultSkillDirs). */
+export function planConnect(agent: ConnectAgent, activeDirs: readonly string[], home = homedir()): ConnectPlan {
+  const root = connectSkillRoot(agent, home);
+  if (!existsSync(root)) return { agent, root, state: 'missing' };
+  const skills = findSkillFolders(root);
+  if (!skills.length) return { agent, root, state: 'empty' };
+  return activeDirs.includes(root) ? { agent, root, state: 'already', skills } : { agent, root, state: 'new', skills };
+}
+
+function sample(skills: readonly string[]): string {
+  const head = skills.slice(0, 5).join(', ');
+  return skills.length > 5 ? `${head} 외 ${skills.length - 5}개` : head;
+}
+
+/** The first screen — one question, or one line saying why there is nothing to ask. */
+export function connectPrompt(plan: ConnectPlan): string {
+  const who = AGENT_LABEL[plan.agent];
+  switch (plan.state) {
+    case 'missing': return `${who} 스킬 폴더가 없습니다(${plan.root}). 가져올 것이 없습니다.`;
+    case 'empty': return `${who} 스킬 폴더에 스킬이 없습니다(${plan.root}).`;
+    case 'already': return `${who}에서 쓰던 스킬 ${plan.skills.length}개는 이미 연결돼 있습니다 — ${sample(plan.skills)}`;
+    case 'new': return `${who}에서 쓰던 스킬 ${plan.skills.length}개를 찾았습니다 — ${sample(plan.skills)}\n복사하지 않고 그 자리(${plan.root})를 그대로 씁니다. 가져올까요? [Y/n] `;
+  }
+}
+
+/** Returns the new connected-source list (unchanged when the path is already there). */
+export function withConnectedSource(sources: readonly SkillSource[] | undefined, path: string, id = skillSourceId(path)): SkillSource[] {
+  const list = [...(sources ?? [])];
+  if (!list.some((source) => source.path === path)) list.push({ id, path, kind: 'connected', enabled: true });
+  return list;
+}
+
+export function withoutSources(sources: readonly SkillSource[] | undefined, paths: readonly string[]): SkillSource[] {
+  return (sources ?? []).filter((source) => !paths.includes(source.path));
+}

package/src/skills/index.ts

@@ -93,6 +93,17 @@ export function nameTriggers(name: string): string[] {
   return out;
 }
 
+/** A skill the index could not read — surfaced to the person (startup notice · repair offer), never swallowed. */
+export interface SkillIndexProblem { name: string; dir: string; code: string | null; error: string }
+const skillProblems = new Map<string, SkillIndexProblem>();
+function recordSkillIndexProblem(problem: SkillIndexProblem): void {
+  skillProblems.set(`${problem.dir}\u0000${problem.name}`, problem);
+}
+/** Skills skipped by the most recent index builds (deduped by dir + name). */
+export function skillIndexProblems(): SkillIndexProblem[] {
+  return [...skillProblems.values()];
+}
+
 function makeEntry(name: string, rootDir: string): SkillIndexEntry | null {
   let m: ReturnType<typeof parseSkillMd>;
   try {
@@ -458,9 +469,26 @@ export function buildSkillIndex(
   const out: SkillIndexEntry[] = [];
   const seenNames = new Set<string>();
   for (const dir of dirs) {
+    // Problems reflect the latest build of each dir — a repaired skill must drop off the list (SK2).
+    for (const key of [...skillProblems.keys()]) if (key.startsWith(`${dir}\u0000`)) skillProblems.delete(key);
     const names = listSkillNames(dir);
     for (const name of names) {
-      const entry = makeEntry(name, dir);
+      // One malformed third-party skill must not take down the index (and with it the first screen).
+      let entry: SkillIndexEntry | null;
+      try {
+        entry = makeEntry(name, dir);
+      } catch (err) {
+        // 대표 10-01: a broken skill must never crash the product — and must never vanish silently either (G9 P5a).
+        // It is skipped, recorded in skillIndexProblems() (a startup notice offers to repair it), and logged.
+        const problem: SkillIndexProblem = {
+          name, dir,
+          code: (err as NodeJS.ErrnoException)?.code ?? null,
+          error: err instanceof Error ? err.message.slice(0, 200) : String(err).slice(0, 200),
+        };
+        recordSkillIndexProblem(problem);
+        debug.log('skills.index', 'skill-skipped', { ...problem }, { level: 'warn' });
+        continue;
+      }
       if (!entry) continue;
       if (seenNames.has(entry.name)) continue; // first-wins dedup
       seenNames.add(entry.name);

package/src/skills/repair.ts

@@ -0,0 +1,124 @@
+// SK2 — 남의 SKILL.md 를 색인이 못 읽으면(skillIndexProblems) 시스템 에러 대신 «안내 ⊕ 확인 뒤 수리».
+// 대표 10-01: «시스템 에러가 아니라 별도 시스템 메시지를 받고 스킬을 수리» · «PR 이 아니라 접근한 서피스에서 간단히».
+// 고칠 수 있는 것만 고친다: 한 줄이어야 하는 프론트매터 값이 YAML 목록·인라인 배열이면 한 줄로 편다.
+// 권한 오류는 원인·명령만 안내한다. 고치기 전 원본은 옆에 `.bak` 으로 남기고, 다시 읽어 안 풀리면 되돌린다.
+import { chmodSync, copyFileSync, existsSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { debug } from '../debug/log.js';
+import { buildSkillIndex, skillIndexProblems, type SkillIndexProblem } from './index.js';
+
+/** Frontmatter keys the index reads as one-line text. */
+const SCALAR_KEYS = ['name', 'description', 'version', 'when_to_use', 'when-to-use', 'argument-hint', 'model', 'category'];
+
+export type SkillRepairPlan =
+  | { kind: 'fixable'; problem: SkillIndexProblem; path: string; keys: string[] }
+  | { kind: 'fixable-permission'; problem: SkillIndexProblem; path: string }
+  | { kind: 'permission'; problem: SkillIndexProblem; path: string; hint: string }
+  | { kind: 'manual'; problem: SkillIndexProblem; path: string; hint: string };
+
+export function skillFilePath(problem: SkillIndexProblem): string {
+  return join(problem.dir, problem.name, 'SKILL.md');
+}
+
+function quote(value: string): string {
+  return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+
+function stripQuotes(value: string): string {
+  const v = value.trim();
+  return (v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'")) ? v.slice(1, -1) : v;
+}
+
+/** Rewrite list-valued scalar keys as one quoted line; returns null when nothing needs changing. */
+export function flattenScalarLists(markdown: string): { text: string; keys: string[] } | null {
+  const fm = /^---\r?\n([\s\S]*?)\r?\n---/.exec(markdown);
+  if (!fm) return null;
+  const lines = fm[1]!.split(/\r?\n/);
+  const out: string[] = [];
+  const keys: string[] = [];
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]!;
+    const m = /^([A-Za-z][A-Za-z0-9_-]*)\s*:\s*(.*)$/.exec(line);
+    if (!m || !SCALAR_KEYS.includes(m[1]!)) { out.push(line); continue; }
+    const key = m[1]!;
+    const value = m[2]!.trim();
+    if (/^\[.*\]$/.test(value)) {
+      const items = value.slice(1, -1).split(',').map(stripQuotes).filter(Boolean);
+      out.push(`${key}: ${quote(items.join(' · '))}`); keys.push(key);
+      continue;
+    }
+    if (value === '') {
+      const items: string[] = [];
+      let j = i + 1;
+      while (j < lines.length && /^\s+-\s+/.test(lines[j]!)) { items.push(stripQuotes(lines[j]!.replace(/^\s+-\s+/, ''))); j++; }
+      if (items.length) { out.push(`${key}: ${quote(items.join(' · '))}`); keys.push(key); i = j - 1; continue; }
+    }
+    out.push(line);
+  }
+  if (!keys.length) return null;
+  const text = markdown.slice(0, fm.index) + `---\n${out.join('\n')}\n---` + markdown.slice(fm.index + fm[0].length);
+  return { text, keys };
+}
+
+export function planSkillRepair(problem: SkillIndexProblem, read: (path: string) => string = (p) => readFileSync(p, 'utf8')): SkillRepairPlan {
+  const path = skillFilePath(problem);
+  if (problem.code === 'EACCES' || problem.code === 'EPERM') {
+    // Our own file: we may add the read bit after the person says yes. Someone else's: name the command only.
+    try {
+      if (typeof process.getuid === 'function' && statSync(path).uid === process.getuid()) return { kind: 'fixable-permission', problem, path };
+    } catch { /* fall through to the hint */ }
+    return { kind: 'permission', problem, path, hint: `읽기 권한이 없습니다 — 터미널에서: sudo chmod a+r "${path}"` };
+  }
+  try {
+    const fixed = flattenScalarLists(read(path));
+    if (fixed) return { kind: 'fixable', problem, path, keys: fixed.keys };
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code === 'EACCES' || code === 'EPERM') return { kind: 'permission', problem, path, hint: `읽기 권한이 없습니다 — 터미널에서: chmod u+r "${path}"` };
+  }
+  return { kind: 'manual', problem, path, hint: `자동으로 고칠 수 없는 형식입니다 — 파일 맨 위 «---» 사이를 확인해 주세요: ${path}` };
+}
+
+export type SkillRepairResult = { ok: true; path: string; keys: string[]; backup: string } | { ok: false; path: string; reason: string };
+
+function stillUnreadable(problem: SkillIndexProblem): boolean {
+  buildSkillIndex([problem.dir]);
+  return skillIndexProblems().some((p) => p.dir === problem.dir && p.name === problem.name);
+}
+
+/** Apply a fixable plan (after the person said yes): read bit, or back up → rewrite → re-index → restore on failure. */
+export function applySkillRepair(plan: Extract<SkillRepairPlan, { kind: 'fixable' | 'fixable-permission' }>): SkillRepairResult {
+  const { path, problem } = plan;
+  if (plan.kind === 'fixable-permission') {
+    const before = statSync(path).mode & 0o777;
+    chmodSync(path, before | 0o400);
+    if (stillUnreadable(problem)) {
+      chmodSync(path, before);
+      debug.log('skills.repair', 'reverted', { name: problem.name, kind: 'permission' });
+      return { ok: false, path, reason: 'still-unreadable' };
+    }
+    debug.log('skills.repair', 'repaired', { name: problem.name, kind: 'permission' });
+    return { ok: true, path, keys: ['permission'], backup: '' };
+  }
+  const original = readFileSync(path, 'utf8');
+  const fixed = flattenScalarLists(original);
+  if (!fixed) return { ok: false, path, reason: 'nothing-to-fix' };
+  const backup = `${path}.bak`;
+  copyFileSync(path, existsSync(backup) ? `${path}.${Date.now()}.bak` : backup);
+  const temp = `${path}.tmp-${process.pid}`;
+  writeFileSync(temp, fixed.text);
+  renameSync(temp, path);
+  if (stillUnreadable(problem)) {
+    writeFileSync(path, original);
+    debug.log('skills.repair', 'reverted', { name: problem.name, keys: fixed.keys });
+    return { ok: false, path, reason: 'still-unreadable' };
+  }
+  debug.log('skills.repair', 'repaired', { name: problem.name, keys: fixed.keys });
+  return { ok: true, path, keys: fixed.keys, backup };
+}
+
+/** One line for a surface (TUI · REPL · PWA) — null when every skill was read. */
+export function skillRepairNotice(problems: readonly SkillIndexProblem[]): string | null {
+  if (!problems.length) return null;
+  return `스킬 ${problems.length}개를 읽지 못했습니다 — 고치려면: elanous skills repair (확인한 뒤에만 고칩니다)`;
+}

package/src/skills/runner.ts

@@ -330,6 +330,15 @@ function parseTier(raw: unknown): SkillTier | undefined {
 
 const FRONTMATTER_RE = /^---\s*\n([\s\S]*?)\n---\s*\n?/;
 
+/** A frontmatter value as one line of text. Third-party SKILL.md files (~/.codex/skills, ~/.claude/skills …)
+ *  sometimes write `description:` as a YAML list; the parser then returns an array, and a 0.2.6 beta tester's
+ *  first screen crashed on `description.trim is not a function`. Lists are joined; anything else non-string is dropped. */
+export function frontmatterText(value: unknown): string {
+  if (typeof value === 'string') return value;
+  if (Array.isArray(value)) return value.filter((x): x is string => typeof x === 'string').join(' ').trim();
+  return '';
+}
+
 function parseFrontmatter(md: string): { fm: Record<string, any>; body: string } {
   const match = md.match(FRONTMATTER_RE);
   if (!match) return { fm: {}, body: md };
@@ -544,8 +553,8 @@ export function parseSkillMd(skillName: string, baseDir: string = LOCAL_SKILLS_D
   const cost = rawCost === 'light' || rawCost === 'heavy' ? rawCost : undefined;
 
   return {
-    name: fm['name'] || skillName,
-    description: fm['description'] || '',
+    name: frontmatterText(fm['name']) || skillName,
+    description: frontmatterText(fm['description']),
     model: fm['model'] || undefined,
     allowedTools,
     deniedTools,

package/src/skills/tools/usage-slash.ts

@@ -1,9 +1,7 @@
-// Slash command: /usage
-//
-// Screen does not compute. It prints the same structured report the
-// `elanous usage` command produces.
+// Slash commands: /usage and /remaining — compact TUI view of the unified report.
 
-import { collectUnifiedUsage, formatUnifiedUsage, type UnifiedUsageDeps } from '../../budget/unified-usage.js';
+import { collectUnifiedUsage, formatUsageCompact, type UnifiedUsageDeps } from '../../budget/unified-usage.js';
+import { visibleWidth } from '../../tui.js';
 import type { SlashExecuteRequest, SlashExecuteResult } from './dashboard-slash.js';
 
 export interface UsageSlashResult extends SlashExecuteResult {
@@ -12,15 +10,18 @@ export interface UsageSlashResult extends SlashExecuteResult {
 }
 
 export async function executeUsageSlash(
-  req: SlashExecuteRequest,
+  req: SlashExecuteRequest & { width?: number },
   deps: UnifiedUsageDeps = {},
 ): Promise<UsageSlashResult | null> {
   if (req.name !== 'usage' && req.name !== 'remaining') return null;
   const report = await collectUnifiedUsage(deps);
+  const width = req.width ?? 120;
+  const hint = ['자세히: elanous usage', 'elanous usage', 'elanous…', '…']
+    .find((text) => visibleWidth(text) <= width) ?? '';
   return {
     ok: true,
     name: req.name,
     args: req.args,
-    logLines: formatUnifiedUsage(report).split('\n').filter((line) => line.length > 0),
+    logLines: [...formatUsageCompact(report, { width, nowMs: Date.now() }), hint],
   };
 }

package/src/skills/trigger-extract.ts

@@ -56,7 +56,7 @@ const BACKWARD_MARKER = /(?:등(?:의)?\s*)?(?:언급\s*)?시\s*(?:이?\s*스킬
  *  keywords. Empty array is a perfectly normal result (description
  *  without any recognized marker). */
 export function extractTriggers(description: string): string[] {
-  if (!description || !description.trim()) return [];
+  if (typeof description !== 'string' || !description.trim()) return [];
 
   const segments = extractTriggerSegments(description);
   const items: string[] = [];