axmap-cli 1.5.0 → 1.6.0

package/src/managed-session.mts

@@ -0,0 +1,198 @@
+/** Explicitly launched persistent CLI sessions. No transcript scraping, global
+ * hook edits, per-message process spawning, or inference while the queue is idle. */
+import fs from 'node:fs'
+import path from 'node:path'
+import net from 'node:net'
+import { spawn } from 'node:child_process'
+import { randomUUID, randomBytes, timingSafeEqual } from 'node:crypto'
+import { bridgeHome, repoKey, writeJSON } from './bridge.mjs'
+import { normalizeUsage, usageDelta } from './session-usage.mjs'
+import { errorMessage } from './session-types.mjs'
+import type { ChildProcessWithoutNullStreams } from 'node:child_process'
+import type { Provider, SessionRecord, RequestState, LocalMessage, JobRecord } from './session-types.mjs'
+
+interface ManagedSessionOptions {
+  provider: Provider; executable?: string; prefix?: string[]; args?: string[] | null; model?: string; role?: string
+  cwd?: string; maxTokens?: number; timeoutMs?: number; onEvent?: (event: Record<string, unknown>) => void
+}
+interface ProviderMessage {
+  id?: string | number; method?: string; event?: string; conversation_id?: string
+  error?: { message: string }; result?: unknown
+  params?: {
+    threadId?: string; tokenUsage?: { total: unknown }; item?: { type: string; text?: string }
+    turn?: { id: string; status: string; error?: { message: string } }
+    [key: string]: unknown
+  }
+}
+interface AgyResult { conversation_id: string; status: string; response?: unknown; error?: string; usage?: unknown }
+
+const pipeFor = (id: string) => process.platform === 'win32' ? `\\\\.\\pipe\\axmap-${id}` : path.join(bridgeHome(), `${id}.sock`)
+const uuid = (value: string | undefined) => /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value || '')
+
+export async function startManagedSession({ provider, executable = provider, prefix = [], args = null, model, role = '',
+  cwd = process.cwd(), maxTokens = 100000, timeoutMs = 120000, onEvent = () => {} }: ManagedSessionOptions) {
+  if (!['codex', 'agy'].includes(provider)) throw new Error('지원하는 세션은 codex 또는 agy입니다.')
+  if (!Number.isSafeInteger(maxTokens) || maxTokens < 1 || !Number.isSafeInteger(timeoutMs) || timeoutMs < 1) throw new Error('양의 토큰/시간 한도가 필요합니다.')
+  if (typeof role !== 'string' || role.length > 1000) throw new Error('역할은 1000자 이하여야 합니다.')
+  const id = randomUUID(), token = randomBytes(32).toString('hex')
+  const sessionPath = path.join(bridgeHome(), 'sessions', `${id}.json`)
+  const s: SessionRecord = { id, token, provider, transport: 'stdio', role, model: model || null,
+    workspaces: [path.resolve(cwd)], repos: [repoKey(cwd)], state: 'starting', fullyIdle: false,
+    registeredAt: new Date().toISOString(), usage: null, usageKnown: true, maxTokens }
+  const jobs = new Map<string, JobRecord>()
+  const calls = new Map<string | number, { resolve: (result: unknown) => void; reject: (reason: Error) => void; timer: NodeJS.Timeout }>()
+  let child: ChildProcessWithoutNullStreams | undefined, sequence = 0, pending: JobRecord | null = null, closed = false, buffer = '', stderr = '', turnTimer: NodeJS.Timeout | undefined
+  const save = () => { s.registeredAt = new Date().toISOString(); writeJSON(sessionPath, s) }
+  const emit = (event: Record<string, unknown>) => onEvent({ session: id, ...event })
+  const write = (message: unknown) => {
+    if (closed || !child?.stdin.writable) throw new Error('세션 입력 연결이 종료됐습니다.')
+    child.stdin.write(JSON.stringify(message) + '\n')
+  }
+  const rpc = <T = unknown,>(method: string, params: unknown): Promise<T> => new Promise((resolve, reject) => {
+    const callId = ++sequence
+    const timer = setTimeout(() => { calls.delete(callId); reject(new Error(`${method}: 응답 시간 초과`)) }, 15000)
+    calls.set(callId, { resolve: value => resolve(value as T), reject, timer })
+    try { write({ id: callId, method, params }) } catch (e) { clearTimeout(timer); calls.delete(callId); reject(e) }
+  })
+  const finish = (state: RequestState, result?: unknown, error?: string, rawUsage?: unknown) => {
+    if (!pending) return
+    clearTimeout(turnTimer)
+    const usage = normalizeUsage(provider, rawUsage)
+    Object.assign(pending, { state, result, error, usage: pending.baselineKnown ? usageDelta(usage, pending.baseline) : null,
+      completedAt: new Date().toISOString(), conversationId: s.conversationId })
+    delete pending.baseline
+    delete pending.baselineKnown
+    if (usage) s.usage = usage
+    s.usageKnown = usage !== null
+    emit({ event: 'result', request: { ...pending } })
+    pending = null; s.state = 'idle'; s.fullyIdle = true; delete s.pendingApproval; save()
+  }
+  const shutdown = (reason: string) => {
+    if (closed) return
+    finish('unknown', undefined, reason)
+    closed = true; clearTimeout(turnTimer)
+    for (const c of calls.values()) { clearTimeout(c.timer); c.reject(new Error(reason)) }
+    calls.clear()
+    s.state = 'closed'; s.fullyIdle = false; save()
+    child?.stdin.destroy(); child?.kill(); server.close()
+  }
+  const handle = (message: LocalMessage) => {
+    const offered = Buffer.from(typeof message.token === 'string' ? message.token : '')
+    const expected = Buffer.from(token)
+    if (offered.length !== expected.length || !timingSafeEqual(offered, expected)) throw new Error('로컬 세션 인증 실패')
+    if (message.action === 'status') return { id, state: s.state, usage: s.usage, pendingApproval: s.pendingApproval }
+    if (message.action === 'result') {
+      const result = jobs.get(message.id)
+      if (!result) throw new Error('이 세션에 해당 요청이 없습니다.')
+      const { baseline, baselineKnown, ...publicResult } = result
+      return publicResult
+    }
+    if (message.action === 'answer') {
+      const approval = s.pendingApproval
+      if (!approval || String(approval.id) !== String(message.id)) throw new Error('현재 대기 중인 승인 요청이 아닙니다.')
+      if (!['accept', 'decline', 'cancel'].includes(message.decision)) throw new Error('이번 실행의 accept, decline 또는 cancel만 지원합니다.')
+      write({ id: approval.id, result: { decision: message.decision } })
+      delete s.pendingApproval; s.state = 'running'; save(); return { answered: true }
+    }
+    if (message.action !== 'submit') throw new Error('지원하지 않는 로컬 세션 요청입니다.')
+    if (closed || s.state !== 'idle' || pending) throw new Error('세션이 대기 중이 아닙니다. 요청을 전달하지 않았습니다.')
+    if (!s.usageKnown) throw new Error('직전 요청의 사용량을 확인하지 못했습니다. 새 연결에서 예산을 확인하세요.')
+    if (s.usage && s.usage.totalTokens >= maxTokens) throw new Error('세션 토큰 한도에 도달했습니다.')
+    const request = message.request
+    if (!uuid(request?.id) || request.to !== id || typeof request.prompt !== 'string' || !request.prompt.trim() || Buffer.byteLength(request.prompt) > 32768) throw new Error('요청 형식이 올바르지 않습니다.')
+    pending = { id: request.id, to: id, state: 'submitted', baseline: s.usage, baselineKnown: s.usageKnown, result: '' }
+    jobs.set(request.id, pending); s.state = 'running'; s.fullyIdle = false; save()
+    const prompt = `[axMap request ${request.id}]\n요청자: ${request.from || 'axmap'}\n${role ? `역할: ${role}\n` : ''}${request.prompt}`
+    turnTimer = setTimeout(() => shutdown('실행 시간 한도 초과. 완료 여부가 불명확하므로 자동 재시도하지 않습니다.'), timeoutMs)
+    if (provider === 'agy') write({ event: 'user', message: { content: prompt } })
+    else rpc<{ turn: { id: string } }>('turn/start', { threadId: s.conversationId, input: [{ type: 'text', text: prompt }], effort: 'low' })
+      .then(r => { if (pending?.id === request.id) pending.turnId = r.turn.id })
+      .catch(e => shutdown(e.message))
+    return { accepted: true, session: id }
+  }
+  const server = net.createServer(socket => {
+    socket.setEncoding('utf8')
+    let input = '', handled = false
+    socket.setTimeout(15000, () => socket.destroy()); socket.on('error', () => {})
+    socket.on('data', chunk => {
+      if (handled) return
+      input += chunk
+      if (Buffer.byteLength(input) > 65536) return socket.destroy()
+      const end = input.indexOf('\n'); if (end < 0) return
+      handled = true
+      try { socket.end(JSON.stringify({ result: handle(JSON.parse(input.slice(0, end))) }) + '\n') }
+      catch (e) { socket.end(JSON.stringify({ error: errorMessage(e) }) + '\n') }
+    })
+  })
+  fs.mkdirSync(bridgeHome(), { recursive: true, mode: 0o700 })
+  await new Promise<void>((resolve, reject) => { server.once('error', reject); server.listen(pipeFor(id), resolve) })
+  if (process.platform !== 'win32') fs.chmodSync(pipeFor(id), 0o600)
+  save()
+  const cliArgs = args || (provider === 'codex' ? ['app-server', '--stdio']
+    : ['--input-format', 'stream-json', '--output-format', 'stream-json', '--disable-slash-commands', '--effort', 'low', ...(model ? ['--model', model] : [])])
+  child = spawn(executable, [...prefix, ...cliArgs], { cwd, windowsHide: true, stdio: ['pipe', 'pipe', 'pipe'],
+    env: { ...process.env, AXMAP_AGENT: `${provider}-${id.slice(0, 8)}`, AXMAP_SESSION: id } })
+  child.stdin.on('error', e => shutdown(e.message))
+  const exited = new Promise<{ code: number | null; signal?: NodeJS.Signals | null; error?: string }>(resolve => {
+    child.once('error', e => { shutdown(e.message); resolve({ code: 1, error: e.message }) })
+    child.once('exit', (code, signal) => { shutdown(`CLI가 종료됐습니다 (${code ?? signal}). ${stderr.slice(-1000)}`); resolve({ code, signal }) })
+  })
+  child.stderr.on('data', chunk => { stderr = (stderr + chunk.toString('utf8')).slice(-8192) })
+  child.stdout.setEncoding('utf8')
+  child.stdout.on('data', chunk => {
+    buffer += chunk
+    if (Buffer.byteLength(buffer) > 4 * 1024 * 1024) return shutdown('CLI 응답 크기 제한 초과')
+    while (buffer.includes('\n') && !closed) {
+      const end = buffer.indexOf('\n'), line = buffer.slice(0, end); buffer = buffer.slice(end + 1)
+      if (!line.trim()) continue
+      try {
+        const m = JSON.parse(line) as ProviderMessage
+        if (provider === 'agy') {
+          if (m.event === 'init') { s.conversationId = m.conversation_id; s.state = 'idle'; s.fullyIdle = true; save(); emit({ event: 'ready', conversationId: s.conversationId }) }
+          if (m.event === 'result' && pending) {
+            const r = m.result as AgyResult
+            if (r.conversation_id !== s.conversationId) throw new Error('agy 대화 ID가 바뀌었습니다.')
+            finish(r.status === 'SUCCESS' ? 'completed' : 'failed', r.response, r.error, r.usage)
+          }
+          continue
+        }
+        if (m.id !== undefined && !m.method) {
+          const call = calls.get(m.id)
+          if (call) { clearTimeout(call.timer); calls.delete(m.id); m.error ? call.reject(new Error(m.error.message)) : call.resolve(m.result) }
+          continue
+        }
+        if (m.id !== undefined && m.method) {
+          if (['item/commandExecution/requestApproval', 'item/fileChange/requestApproval'].includes(m.method)) {
+            s.pendingApproval = { id: m.id, method: m.method, ...m.params }; s.state = 'awaiting_user'; save()
+            emit({ event: 'awaiting_user', request: s.pendingApproval })
+          } else { write({ id: m.id, error: { code: -32601, message: '이 연결에서 지원하지 않는 사용자 입력입니다. 대화형 CLI에서 처리하세요.' } }) }
+          continue
+        }
+        if (m.params?.threadId !== s.conversationId) continue
+        if (m.method === 'thread/tokenUsage/updated' && pending) pending.rawUsage = m.params?.tokenUsage?.total
+        if (m.method === 'item/completed' && pending && m.params?.item?.type === 'agentMessage') pending.result = m.params.item.text
+        if (m.method === 'turn/completed' && pending) {
+          const r = m.params?.turn
+          if (!r) throw new Error('Codex 실행 결과가 없습니다.')
+          if (pending.turnId && pending.turnId !== r.id) throw new Error('Codex 실행 ID가 다릅니다.')
+          finish(r.status === 'completed' ? 'completed' : 'failed', pending.result, r.error?.message, pending.rawUsage)
+        }
+      } catch (e) { shutdown(`CLI 프로토콜 오류: ${errorMessage(e)}`) }
+    }
+  })
+  try {
+    if (provider === 'codex') {
+      await rpc('initialize', { clientInfo: { name: 'axmap', version: '1' } })
+      write({ method: 'initialized' })
+      const r = await rpc<{ thread: { id: string }; model?: string }>('thread/start', { cwd: path.resolve(cwd), ...(model ? { model } : {}),
+        sandbox: 'read-only', approvalPolicy: 'on-request' })
+      s.conversationId = r.thread.id; s.model = r.model || model || null; s.state = 'idle'; s.fullyIdle = true; save()
+      emit({ event: 'ready', conversationId: s.conversationId })
+    } else {
+      const deadline = Date.now() + 30000
+      while (s.state === 'starting' && !closed && Date.now() < deadline) await new Promise(r => setTimeout(r, 25))
+      if (s.state !== 'idle') throw new Error(`agy 시작 실패: ${stderr.slice(-1000) || s.state}`)
+    }
+  } catch (e) { shutdown(errorMessage(e)); throw e }
+  return { id, pid: child.pid, conversationId: s.conversationId, exited, close: () => shutdown('사용자가 관리형 연결을 종료했습니다.') }
+}

package/src/monitor-cli.mjs

@@ -0,0 +1,87 @@
+// Generated from src/monitor-cli.mts. Edit the .mts source and run npm run build.
+import path from 'node:path';
+import { createMonitor, renderMonitor } from './monitor.mjs';
+import { errorMessage } from './session-types.mjs';
+export async function runMonitor(args) {
+    if (args.includes('--help') || args.includes('-h')) {
+        console.log('axmap monitor [--cwd <repo>] [--interval 1000] [--once | --json] [--no-color]\n세션·요청 파이프라인·자동 대화·선점·최근 이벤트를 실시간으로 표시합니다.\nTTY에서는 계속 갱신하며, 파이프/리디렉션에서는 한 번만 출력합니다. q / Esc / Ctrl+C 종료.');
+        return;
+    }
+    const allowed = new Set(['--cwd', '--interval', '--once', '--json', '--no-color']);
+    for (let i = 0; i < args.length; i++) {
+        if (!allowed.has(args[i]))
+            throw new Error(`알 수 없는 옵션: ${args[i]}`);
+        if (args[i] === '--cwd' || args[i] === '--interval') {
+            if (!args[i + 1] || args[i + 1].startsWith('--'))
+                throw new Error(`${args[i]} 값이 필요합니다.`);
+            i++;
+        }
+    }
+    const option = (name) => { const index = args.indexOf(name); return index < 0 ? undefined : args[index + 1]; };
+    const interval = Number(option('--interval') || 1000);
+    if (!Number.isInteger(interval) || interval < 250 || interval > 60000)
+        throw new Error('interval은 250~60000ms 정수여야 합니다.');
+    const collect = createMonitor(path.resolve(option('--cwd') || process.cwd()));
+    const live = !!process.stdout.isTTY && !!process.stdin.isTTY && process.env.TERM !== 'dumb' && !args.includes('--once') && !args.includes('--json');
+    const color = !!process.stdout.isTTY && !args.includes('--no-color') && process.env.NO_COLOR === undefined && process.env.TERM !== 'dumb';
+    if (!live) {
+        const snapshot = await collect();
+        console.log(args.includes('--json') ? JSON.stringify(snapshot, null, 2) : renderMonitor(snapshot, { columns: process.stdout.columns || 100, rows: process.stdout.rows || 40, color }));
+        return;
+    }
+    let stopped = false, frame = 0, timer, animation;
+    let latest = null;
+    const wasRaw = !!process.stdin.isRaw;
+    await new Promise(resolve => {
+        const restore = () => {
+            if (stopped)
+                return;
+            stopped = true;
+            clearTimeout(timer);
+            clearInterval(animation);
+            process.stdin.off('data', input);
+            process.off('SIGINT', restore);
+            process.off('SIGTERM', restore);
+            process.off('exit', restore);
+            process.stdin.setRawMode(wasRaw);
+            process.stdin.pause();
+            process.stdout.write('\x1b[0m\x1b[?25h\x1b[?1049l');
+            resolve();
+        };
+        const input = (text) => { if (text === '\x1b' || text.includes('\x03') || /^[qQ]+$/.test(text))
+            restore(); };
+        const draw = () => {
+            if (stopped || !latest)
+                return;
+            const view = renderMonitor(latest, { columns: process.stdout.columns || 100, rows: Math.max(1, (process.stdout.rows || 36) - 1), color, frame: frame++ });
+            process.stdout.write('\x1b[H' + view.replaceAll('\n', '\x1b[K\r\n') + '\x1b[K\x1b[J');
+        };
+        const update = async () => {
+            try {
+                const snapshot = await collect();
+                if (stopped)
+                    return;
+                latest = snapshot;
+                draw();
+            }
+            catch (e) {
+                restore();
+                console.error(`axMap monitor: ${errorMessage(e)}`);
+                process.exitCode = 1;
+                return;
+            }
+            if (!stopped)
+                timer = setTimeout(update, interval);
+        };
+        process.stdout.write('\x1b[?1049h\x1b[?25l\x1b[2J\x1b[H');
+        process.stdin.setEncoding('utf8');
+        process.stdin.setRawMode(true);
+        process.stdin.resume();
+        process.stdin.on('data', input);
+        process.once('SIGINT', restore);
+        process.once('SIGTERM', restore);
+        process.once('exit', restore);
+        animation = setInterval(draw, 180);
+        void update();
+    });
+}

package/src/monitor-cli.mts

@@ -0,0 +1,64 @@
+import path from 'node:path'
+import { createMonitor, renderMonitor } from './monitor.mjs'
+import type { MonitorSnapshot } from './monitor.mjs'
+import { errorMessage } from './session-types.mjs'
+
+export async function runMonitor(args: string[]): Promise<void> {
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log('axmap monitor [--cwd <repo>] [--interval 1000] [--once | --json] [--no-color]\n세션·요청 파이프라인·자동 대화·선점·최근 이벤트를 실시간으로 표시합니다.\nTTY에서는 계속 갱신하며, 파이프/리디렉션에서는 한 번만 출력합니다. q / Esc / Ctrl+C 종료.')
+    return
+  }
+  const allowed = new Set(['--cwd', '--interval', '--once', '--json', '--no-color'])
+  for (let i = 0; i < args.length; i++) {
+    if (!allowed.has(args[i]!)) throw new Error(`알 수 없는 옵션: ${args[i]}`)
+    if (args[i] === '--cwd' || args[i] === '--interval') {
+      if (!args[i + 1] || args[i + 1]!.startsWith('--')) throw new Error(`${args[i]} 값이 필요합니다.`)
+      i++
+    }
+  }
+  const option = (name: string) => { const index = args.indexOf(name); return index < 0 ? undefined : args[index + 1] }
+  const interval = Number(option('--interval') || 1000)
+  if (!Number.isInteger(interval) || interval < 250 || interval > 60000) throw new Error('interval은 250~60000ms 정수여야 합니다.')
+  const collect = createMonitor(path.resolve(option('--cwd') || process.cwd()))
+  const live = !!process.stdout.isTTY && !!process.stdin.isTTY && process.env.TERM !== 'dumb' && !args.includes('--once') && !args.includes('--json')
+  const color = !!process.stdout.isTTY && !args.includes('--no-color') && process.env.NO_COLOR === undefined && process.env.TERM !== 'dumb'
+  if (!live) {
+    const snapshot = await collect()
+    console.log(args.includes('--json') ? JSON.stringify(snapshot, null, 2) : renderMonitor(snapshot, { columns: process.stdout.columns || 100, rows: process.stdout.rows || 40, color }))
+    return
+  }
+  let stopped = false, frame = 0, timer: NodeJS.Timeout | undefined, animation: NodeJS.Timeout | undefined
+  let latest: MonitorSnapshot | null = null
+  const wasRaw = !!process.stdin.isRaw
+  await new Promise<void>(resolve => {
+    const restore = () => {
+      if (stopped) return
+      stopped = true; clearTimeout(timer); clearInterval(animation)
+      process.stdin.off('data', input); process.off('SIGINT', restore); process.off('SIGTERM', restore); process.off('exit', restore)
+      process.stdin.setRawMode(wasRaw); process.stdin.pause()
+      process.stdout.write('\x1b[0m\x1b[?25h\x1b[?1049l')
+      resolve()
+    }
+    const input = (text: string) => { if (text === '\x1b' || text.includes('\x03') || /^[qQ]+$/.test(text)) restore() }
+    const draw = () => {
+      if (stopped || !latest) return
+      const view = renderMonitor(latest, { columns: process.stdout.columns || 100, rows: Math.max(1, (process.stdout.rows || 36) - 1), color, frame: frame++ })
+      process.stdout.write('\x1b[H' + view.replaceAll('\n', '\x1b[K\r\n') + '\x1b[K\x1b[J')
+    }
+    const update = async () => {
+      try {
+        const snapshot = await collect()
+        if (stopped) return
+        latest = snapshot; draw()
+      } catch (e) {
+        restore(); console.error(`axMap monitor: ${errorMessage(e)}`); process.exitCode = 1; return
+      }
+      if (!stopped) timer = setTimeout(update, interval)
+    }
+    process.stdout.write('\x1b[?1049h\x1b[?25l\x1b[2J\x1b[H')
+    process.stdin.setEncoding('utf8'); process.stdin.setRawMode(true); process.stdin.resume(); process.stdin.on('data', input)
+    process.once('SIGINT', restore); process.once('SIGTERM', restore); process.once('exit', restore)
+    animation = setInterval(draw, 180)
+    void update()
+  })
+}

package/src/monitor.mjs

@@ -0,0 +1,240 @@
+// Generated from src/monitor.mts. Edit the .mts source and run npm run build.
+/** Local observation only: no model submission, Git fetch, ledger bootstrap or approval. */
+import fs from 'node:fs';
+import path from 'node:path';
+import { bridgeHome, repoKey, requestResult } from './bridge.mjs';
+import { sessionStatus } from './session-status.mjs';
+import { errorCode, errorMessage } from './session-types.mjs';
+const uuidFile = /^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}\.json$/i;
+const pending = new Set(['sending', 'submitted', 'unknown']);
+const requestLabels = { sending: '전달 중', submitted: '응답 대기', completed: '완료', failed: '실패', unknown: '전송 확인 필요', superseded: '다른 입력으로 대체됨' };
+const sessionLabels = { starting: '시작 중', running: '작업 중', idle: '대기', awaiting_user: '사용자 승인 필요', settling: '대기 전환 중', closed: '종료', unknown: '상태 미확인' };
+const dialogueLabels = { queued: '접수', running: '중계 중', stopping: '중단 대기', completed: '완료', failed: '실패', cancelled: '중단', token_limit: '토큰 한도', unknown: '확인 필요', usage_unavailable: '사용량 미확인', message_limit: '메시지 한도', invalid_response: '응답 형식 확인 필요', turn_limit: '횟수 한도' };
+function records(directory, issues, label, uuidOnly = true) {
+    try {
+        const files = fs.readdirSync(directory).filter(name => uuidOnly ? uuidFile.test(name) : name.endsWith('.json'))
+            .map(name => ({ name, stat: fs.statSync(path.join(directory, name)) }))
+            .sort((a, b) => b.stat.mtimeMs - a.stat.mtimeMs);
+        if (files.length > 500)
+            issues.push(`${label}: 최근 500개 기록만 표시합니다.`);
+        const result = [];
+        for (const { name, stat } of files.slice(0, 500)) {
+            if (stat.size > 1024 * 1024) {
+                issues.push(`${label}: 큰 기록을 건너뛰었습니다 (${name}).`);
+                continue;
+            }
+            try {
+                result.push(JSON.parse(fs.readFileSync(path.join(directory, name), 'utf8')));
+            }
+            catch {
+                issues.push(`${label}: 읽을 수 없는 기록 (${name}).`);
+            }
+        }
+        return result;
+    }
+    catch (e) {
+        if (errorCode(e) !== 'ENOENT')
+            issues.push(`${label}: ${errorMessage(e)}`);
+        return [];
+    }
+}
+const object = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+const time = (v) => typeof v === 'string' ? Date.parse(v) || 0 : 0;
+export function createMonitor(cwd, options = {}) {
+    const workspace = path.resolve(cwd), repo = repoKey(workspace);
+    const probe = options.probe || sessionStatus, resolve = options.resolve || requestResult, now = options.now || Date.now;
+    const observed = new Map(), events = new Map();
+    const event = (id, at, label, tone = 'info') => events.set(id, { id, at, label, tone });
+    return async () => {
+        const checkedAt = new Date(now()).toISOString(), issues = [];
+        let sessions = [];
+        try {
+            sessions = await probe(workspace);
+        }
+        catch (e) {
+            issues.push(`세션 확인: ${errorMessage(e)}`);
+        }
+        const requests = [];
+        for (const raw of records(path.join(bridgeHome(), 'requests'), issues, '요청')) {
+            if (!object(raw) || raw.repo !== repo)
+                continue;
+            if (typeof raw.id !== 'string' || typeof raw.to !== 'string' || typeof raw.prompt !== 'string' || typeof raw.from !== 'string' || typeof raw.createdAt !== 'string' || !Number.isFinite(Date.parse(raw.createdAt)) || typeof raw.state !== 'string' || !requestLabels[raw.state]) {
+                issues.push('형식이 올바르지 않은 요청 기록이 있습니다.');
+                continue;
+            }
+            requests.push(raw);
+        }
+        requests.sort((a, b) => time(b.createdAt) - time(a.createdAt));
+        // Refresh at most one pending request per session, never submit or retry it.
+        const refreshed = new Set();
+        for (let index = 0; index < requests.length && refreshed.size < 4; index++) {
+            const request = requests[index];
+            if (!['submitted', 'unknown'].includes(request.state) || refreshed.has(request.to))
+                continue;
+            refreshed.add(request.to);
+            try {
+                requests[index] = resolve(request.id, workspace);
+            }
+            catch (e) {
+                issues.push(`요청 ${request.id.slice(0, 8)}: ${errorMessage(e)}`);
+            }
+        }
+        for (const request of requests) {
+            const key = `request:${request.id}`, previous = observed.get(key);
+            event(`${key}:created`, request.createdAt, `요청 접수 · ${request.from} → ${request.to.slice(0, 8)}`);
+            if (request.completedAt)
+                event(`${key}:completed`, request.completedAt, `완료 확인 · ${request.to.slice(0, 8)}`, 'success');
+            if (previous !== undefined && previous !== request.state && !(request.state === 'completed' && request.completedAt))
+                event(`${key}:${request.state}`, checkedAt, `${requestLabels[request.state]} · ${request.to.slice(0, 8)}`, request.state === 'completed' ? 'success' : request.state === 'submitted' ? 'info' : 'warning');
+            observed.set(key, request.state);
+        }
+        for (const session of sessions) {
+            const key = `session:${session.id}`, value = `${session.connection}:${session.state}`, previous = observed.get(key);
+            if (previous !== undefined && previous !== value)
+                event(`${key}:${value}`, checkedAt, `${session.provider} ${session.id.slice(0, 8)} · ${sessionLabels[session.state]}`, session.state === 'awaiting_user' || session.connection === 'unreachable' ? 'warning' : 'info');
+            observed.set(key, value);
+        }
+        const dialogues = [];
+        for (const raw of records(path.join(bridgeHome(), 'dialogues'), issues, '대화')) {
+            if (!object(raw) || raw.repo !== repo)
+                continue;
+            if (typeof raw.id !== 'string' || typeof raw.state !== 'string' || !dialogueLabels[raw.state] || !Array.isArray(raw.turns)) {
+                issues.push('형식이 올바르지 않은 대화 기록이 있습니다.');
+                continue;
+            }
+            dialogues.push(raw);
+        }
+        dialogues.sort((a, b) => time(b.createdAt) - time(a.createdAt));
+        const claims = [];
+        const ledger = path.join(path.dirname(repo), '.axmap', 'ledger', 'claims');
+        for (const raw of records(ledger, issues, '선점', false)) {
+            if (!object(raw) || typeof raw.agent !== 'string' || !Array.isArray(raw.paths) || !raw.paths.every(p => typeof p === 'string') || typeof raw.since !== 'string' || typeof raw.ttlMs !== 'number') {
+                issues.push('형식이 올바르지 않은 선점 기록이 있습니다.');
+                continue;
+            }
+            const expiresAt = time(raw.since) + raw.ttlMs;
+            if (!Number.isFinite(expiresAt) || expiresAt <= now())
+                continue;
+            claims.push({ agent: raw.agent, paths: raw.paths, expiresAt,
+                session: typeof raw.session === 'string' ? raw.session : null, task: typeof raw.task === 'string' ? raw.task : null, intent: typeof raw.intent === 'string' ? raw.intent : null });
+        }
+        const recent = [...events.values()].sort((a, b) => time(b.at) - time(a.at)).slice(0, 40);
+        events.clear();
+        for (const entry of recent)
+            events.set(entry.id, entry);
+        return { cwd: workspace, repo, checkedAt, sessions, requests: requests.slice(0, 50), dialogues: dialogues.slice(0, 20), claims, events: recent, issues };
+    };
+}
+/** Strip untrusted terminal controls, including OSC, CSI and bidi overrides. */
+export function terminalText(value) {
+    return String(value ?? '').replace(/\x1b\][^\x07]*(?:\x07|\x1b\\)/g, '')
+        .replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, '').replace(/[\x00-\x1f\x7f-\x9f\u202a-\u202e\u2066-\u2069]/g, ' ').replace(/\s+/g, ' ').trim();
+}
+const segmenter = new Intl.Segmenter(undefined, { granularity: 'grapheme' });
+function cellWidth(text) {
+    if (/\p{Extended_Pictographic}/u.test(text))
+        return 2;
+    const cp = text.codePointAt(0) || 0;
+    if (/^\p{Mark}+$/u.test(text))
+        return 0;
+    return cp >= 0x1100 && (cp <= 0x115f || cp === 0x2329 || cp === 0x232a ||
+        cp >= 0x2e80 && cp <= 0xa4cf || cp >= 0xac00 && cp <= 0xd7a3 || cp >= 0xf900 && cp <= 0xfaff ||
+        cp >= 0xfe10 && cp <= 0xfe6f || cp >= 0xff01 && cp <= 0xff60 || cp >= 0xffe0 && cp <= 0xffe6 || cp >= 0x20000) ? 2 : 1;
+}
+export function fitTerminal(value, width) {
+    const text = terminalText(value), parts = [...segmenter.segment(text)].map(s => s.segment);
+    if (parts.reduce((n, c) => n + cellWidth(c), 0) <= width)
+        return text;
+    let out = '', used = 0;
+    for (const part of parts) {
+        const next = cellWidth(part);
+        if (used + next > width - 1)
+            break;
+        out += part;
+        used += next;
+    }
+    return width > 0 ? out + '…' : '';
+}
+const elapsed = (start, end) => {
+    const seconds = Math.max(0, Math.floor((end - time(start)) / 1000));
+    return seconds < 60 ? `${seconds}초` : `${Math.floor(seconds / 60)}분 ${seconds % 60}초`;
+};
+const clock = (value) => new Date(value).toLocaleTimeString('en-GB', { hour: '2-digit', minute: '2-digit', second: '2-digit', hour12: false });
+export function renderMonitor(snapshot, { columns = 100, rows = 36, color = false, now = Date.now(), frame = 0 } = {}) {
+    const width = Math.max(1, Math.floor(columns)), height = Math.max(1, Math.floor(rows)), lines = [];
+    const paint = (text, tone = 'info') => color ? `\x1b[${{ info: 36, success: 32, warning: 33, muted: 90 }[tone]}m${text}\x1b[0m` : text;
+    const add = (text, tone) => {
+        const indent = Math.min(text.length - text.trimStart().length, 4, width);
+        lines.push(paint(' '.repeat(indent) + fitTerminal(text, width - indent), tone));
+    };
+    const heading = (text) => add(`── ${text} ${'─'.repeat(Math.max(0, width - 4 - [...text].reduce((n, c) => n + cellWidth(c), 0)))}`, 'muted');
+    const active = snapshot.requests.filter(r => pending.has(r.state)), attention = snapshot.sessions.filter(s => s.state === 'awaiting_user').length;
+    add(`axMap  LIVE  · 진행 확인 ${active.length}개${attention ? `  · 승인 대기 ${attention}` : ''}`, attention ? 'warning' : 'info');
+    add(snapshot.cwd, 'muted');
+    add(`관측 ${clock(snapshot.checkedAt)} · 확인된 정보만 표시 · 모델 호출 없음`, 'muted');
+    if (width < 56 || height < 16) {
+        add('터미널을 넓히면 파이프라인과 최근 이벤트가 표시됩니다.', 'muted');
+        for (const s of snapshot.sessions.slice(0, Math.max(0, height - 7)))
+            add(`${s.provider} ${s.id.slice(0, 8)} · ${sessionLabels[s.state]}`);
+        for (const r of active.slice(0, 2))
+            add(`${r.id.slice(0, 8)} · ${requestLabels[r.state]}`, 'warning');
+    }
+    else {
+        heading('에이전트');
+        if (!snapshot.sessions.length)
+            add('연결된 세션 기록이 없습니다. axmap bridge attach / serve로 연결하세요.', 'muted');
+        for (const session of snapshot.sessions.slice(0, Math.min(5, Math.max(1, Math.floor((height - 14) / 5))))) {
+            const state = sessionLabels[session.state], connection = { connected: '연결됨', closed: '종료됨', unreachable: '연결 확인 불가', unverified: '확인 미지원' }[session.connection];
+            const usage = session.usage?.totalTokens == null ? '토큰 미측정' : `처리 ${session.usage.totalTokens.toLocaleString()} 토큰`;
+            add(`${session.state === 'idle' ? '○' : session.state === 'running' ? '●' : '◇'} ${session.provider.toUpperCase()}  ${session.id.slice(0, 8)}  ${state} · ${connection} · ${usage}`, session.state === 'awaiting_user' || session.connection === 'unreachable' ? 'warning' : 'info');
+            if (session.role)
+                add(`  역할  ${session.role}`, 'muted');
+            if (session.pendingApproval) {
+                const detail = session.pendingApproval.command || session.pendingApproval.commandLine || session.pendingApproval.reason;
+                if (typeof detail === 'string')
+                    add(`  승인 요청  ${detail}`, 'warning');
+            }
+        }
+        heading('요청 파이프라인');
+        const selected = [...active, ...snapshot.requests.filter(r => !pending.has(r.state))].slice(0, height >= 32 ? 3 : 1);
+        if (!selected.length) {
+            add('새 요청을 기다리는 중', 'muted');
+            add('별도 터미널이나 AI에서 요청을 보내면 여기에 흐름이 나타납니다.', 'muted');
+        }
+        for (const request of selected) {
+            const session = snapshot.sessions.find(s => s.id === request.to);
+            const target = `${session?.provider || '세션'} ${request.to.slice(0, 8)}`;
+            const tone = request.state === 'completed' ? 'success' : ['unknown', 'failed', 'superseded'].includes(request.state) ? 'warning' : 'info';
+            add(`${request.from}  →  ${target}  · ${requestLabels[request.state]} · ${elapsed(request.createdAt, request.completedAt ? time(request.completedAt) : now)}`, tone);
+            const spin = ['◐', '◓', '◑', '◒'][frame % 4];
+            const stages = request.state === 'completed' ? '● 접수 ── ● 전달 ── ● 응답 ── ● 완료 확인' :
+                request.state === 'submitted' ? `● 접수 ── ● 전달 ── ${spin} 응답 대기 ── ○ 완료 확인` :
+                    request.state === 'sending' ? `● 접수 ── ${spin} 전달 중 ── ○ 응답 ── ○ 완료 확인` :
+                        request.state === 'unknown' ? '● 접수 ── ? 전달 확인 필요 ── ○ 완료 미확정' : '● 접수 ── ! 진행 중단 ── ○ 완료 미확정';
+            add(`  ${stages}`, tone);
+            add(`  작업  ${request.prompt}`, 'muted');
+            if (request.error)
+                add(`  사유  ${request.error}`, 'warning');
+        }
+        const dialogue = snapshot.dialogues.find(d => ['queued', 'running', 'stopping'].includes(d.state));
+        if (dialogue) {
+            const used = dialogue.usage?.totalTokens ?? dialogue.knownUsage?.totalTokens;
+            add(`자동 대화  ${dialogueLabels[dialogue.state]} · ${dialogue.turns.length}/${dialogue.limits?.maxTurns ?? '?'}회 · 처리 ${used == null ? '미확인' : used.toLocaleString()} 토큰${dialogue.usagePending ? ' (측정 대기 포함)' : ''}`);
+        }
+        if (snapshot.claims.length && lines.length < height - 6) {
+            heading('작업 선점');
+            for (const claim of snapshot.claims.slice(0, 2))
+                add(`${claim.agent} · ${claim.intent || claim.task || '작업 중'} · ${claim.paths.slice(0, 2).join(', ')}${claim.paths.length > 2 ? ` 외 ${claim.paths.length - 2}개` : ''}`, 'muted');
+        }
+        if (lines.length < height - 4) {
+            heading('최근 이벤트');
+            if (!snapshot.events.length)
+                add('관측된 이벤트가 없습니다.', 'muted');
+            for (const event of snapshot.events.slice(0, Math.min(5, height - lines.length - 3)))
+                add(`${clock(event.at)}  ${event.label}`, event.tone);
+        }
+    }
+    const warnings = snapshot.issues.slice(0, Math.min(2, height - 1)).map(issue => paint(fitTerminal(`! ${issue}`, width), 'warning'));
+    const footer = paint(fitTerminal('q / Esc 종료 · 모니터를 닫아도 진행 중인 작업은 계속됩니다.', width), 'muted');
+    return [...lines.slice(0, height - 1 - warnings.length), ...warnings, footer].join('\n');
+}