axmap-cli 1.7.0 → 1.9.0

package/src/monitor-cli.mts

@@ -3,13 +3,14 @@ import { createMonitor, renderMonitor } from './monitor.mjs'
 import type { MonitorSnapshot } from './monitor.mjs'
 import { errorMessage } from './session-types.mjs'
 import { renderPipelineGraph } from './pipeline-graph.mjs'
+import { createView, renderView } from './view.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', '--graph'])
+  const allowed = new Set(['--cwd', '--interval', '--once', '--json', '--no-color', '--graph', '--view'])
   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') {
@@ -20,8 +21,9 @@ export async function runMonitor(args: string[]): Promise<void> {
   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 render = args.includes('--graph') ? renderPipelineGraph : renderMonitor
+  const cwd = path.resolve(option('--cwd') || process.cwd())
+  const collect = args.includes('--view') ? createView(cwd) : createMonitor(cwd)
+  const render = args.includes('--view') ? renderView : args.includes('--graph') ? renderPipelineGraph : renderMonitor
   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) {

package/src/session-mailbox.mjs

@@ -4,7 +4,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
-import { bridgeHome, repoKey, sessions, readJSON, writeJSON, dispatchRequest } from './bridge.mjs';
+import { bridgeHome, repoKey, sessions, readJSON, writeJSON, dispatchRequest, notDelivered } from './bridge.mjs';
 import { withRepoLock } from './repolock.mjs';
 import { errorMessage } from './session-types.mjs';
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
@@ -31,7 +31,7 @@ function load(target) {
         !['boundary', 'immediate'].includes(m.priority) || !states.includes(m.state) ||
         !Number.isFinite(Date.parse(m.createdAt)) || !Number.isFinite(Date.parse(m.expiresAt))) ||
         b.batches.some(x => !x || !UUID.test(x.id || '') || typeof x.repo !== 'string' || !Array.isArray(x.ids) ||
-            !['sending', 'submitted', 'unknown'].includes(x.state)))
+            !['sending', 'submitted', 'unknown', 'failed'].includes(x.state)))
         throw new Error('받은 편지함 기록이 손상됐습니다. 빈 큐로 바꾸지 않습니다.');
     return b;
 }
@@ -169,22 +169,32 @@ export function flushMail({ to, cwd, at, immediateId }) {
         writeJSON(target, b);
         try {
             const r = dispatchRequest({ to, cwd, from: 'axmap-agent-mailbox', prompt });
-            batch.state = r.state === 'submitted' ? 'submitted' : 'unknown';
+            batch.state = r.state === 'submitted' ? 'submitted' : r.state === 'failed' ? 'failed' : 'unknown';
             batch.requestId = r.id;
             batch.error = r.error;
         }
         catch (e) {
             // A storage error can happen after the provider accepted a request. Even
-            // thrown errors must not put this batch back into an executable queue.
-            batch.state = 'unknown';
+            // thrown errors must not put this batch back into an executable queue —
+            // unless the error came before anything was sent.
+            batch.state = notDelivered(e) ? 'failed' : 'unknown';
             batch.error = errorMessage(e);
         }
-        for (const m of selected) {
-            m.state = batch.state;
-            m.requestId = batch.requestId;
-            m.error = batch.error;
-        }
+        // 확실히 전달되지 않은 묶음의 쪽지는 대기열로 돌려 다음 경계에서 다시 보낼 수 있게 한다.
+        // 자동으로 다시 보내지는 않는다. 묶음 기록은 이력으로 남는다.
+        if (batch.state === 'failed')
+            for (const m of selected) {
+                m.state = 'queued';
+                m.error = batch.error;
+            }
+        else
+            for (const m of selected) {
+                m.state = batch.state;
+                m.requestId = batch.requestId;
+                m.error = batch.error;
+            }
         writeJSON(target, b);
-        return { ...batch, modelInvocationRequested: batch.state === 'submitted', modelInvoked: null };
+        return { ...batch, modelInvocationRequested: batch.state === 'submitted', modelInvoked: null,
+            ...(batch.state === 'failed' ? { requeued: selected.length } : {}) };
     });
 }

package/src/session-mailbox.mts

@@ -3,7 +3,7 @@
 import fs from 'node:fs'
 import path from 'node:path'
 import { randomUUID } from 'node:crypto'
-import { bridgeHome, repoKey, sessions, readJSON, writeJSON, dispatchRequest } from './bridge.mjs'
+import { bridgeHome, repoKey, sessions, readJSON, writeJSON, dispatchRequest, notDelivered } from './bridge.mjs'
 import { withRepoLock } from './repolock.mjs'
 import { errorMessage } from './session-types.mjs'
 
@@ -15,7 +15,7 @@ export interface Mail {
   createdAt: string; expiresAt: string; state: State
   supersededBy?: string; batchId?: string; requestId?: string; error?: string
 }
-interface Batch { id: string; repo: string; ids: string[]; state: 'sending' | 'submitted' | 'unknown'; requestId?: string; error?: string }
+interface Batch { id: string; repo: string; ids: string[]; state: 'sending' | 'submitted' | 'unknown' | 'failed'; requestId?: string; error?: string }
 interface Box { version: 1; messages: Mail[]; batches: Batch[] }
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
 const reasons = ['stop', 'data-loss', 'work-invalidated']
@@ -38,7 +38,7 @@ function load(target: string): Box {
     !['boundary', 'immediate'].includes(m.priority) || !states.includes(m.state) ||
     !Number.isFinite(Date.parse(m.createdAt)) || !Number.isFinite(Date.parse(m.expiresAt))) ||
     b.batches.some(x => !x || !UUID.test(x.id || '') || typeof x.repo !== 'string' || !Array.isArray(x.ids) ||
-      !['sending', 'submitted', 'unknown'].includes(x.state))) throw new Error('받은 편지함 기록이 손상됐습니다. 빈 큐로 바꾸지 않습니다.')
+      !['sending', 'submitted', 'unknown', 'failed'].includes(x.state))) throw new Error('받은 편지함 기록이 손상됐습니다. 빈 큐로 바꾸지 않습니다.')
   return b
 }
 function expire(b: Box) {
@@ -144,14 +144,19 @@ export function flushMail({ to, cwd, at, immediateId }:
     writeJSON(target, b)
     try {
       const r = dispatchRequest({ to, cwd, from: 'axmap-agent-mailbox', prompt })
-      batch.state = r.state === 'submitted' ? 'submitted' : 'unknown'; batch.requestId = r.id; batch.error = r.error
+      batch.state = r.state === 'submitted' ? 'submitted' : r.state === 'failed' ? 'failed' : 'unknown'; batch.requestId = r.id; batch.error = r.error
     } catch (e) {
       // A storage error can happen after the provider accepted a request. Even
-      // thrown errors must not put this batch back into an executable queue.
-      batch.state = 'unknown'; batch.error = errorMessage(e)
+      // thrown errors must not put this batch back into an executable queue —
+      // unless the error came before anything was sent.
+      batch.state = notDelivered(e) ? 'failed' : 'unknown'; batch.error = errorMessage(e)
     }
-    for (const m of selected) { m.state = batch.state; m.requestId = batch.requestId; m.error = batch.error }
+    // 확실히 전달되지 않은 묶음의 쪽지는 대기열로 돌려 다음 경계에서 다시 보낼 수 있게 한다.
+    // 자동으로 다시 보내지는 않는다. 묶음 기록은 이력으로 남는다.
+    if (batch.state === 'failed') for (const m of selected) { m.state = 'queued'; m.error = batch.error }
+    else for (const m of selected) { m.state = batch.state as State; m.requestId = batch.requestId; m.error = batch.error }
     writeJSON(target, b)
-    return { ...batch, modelInvocationRequested: batch.state === 'submitted', modelInvoked: null }
+    return { ...batch, modelInvocationRequested: batch.state === 'submitted', modelInvoked: null,
+      ...(batch.state === 'failed' ? { requeued: selected.length } : {}) }
   })
 }

package/src/session-types.mjs

@@ -1,4 +1,7 @@
 // Generated from src/session-types.mts. Edit the .mts source and run npm run build.
+/** `run.mjs rpc` 가 로컬 파이프에 연결조차 못 했을 때(ENOENT·ECONNREFUSED)의 종료 코드.
+ * 이 경우에만 요청이 확실히 전달되지 않았다고 판단한다. */
+export const RPC_NOT_DELIVERED_EXIT = 3;
 export function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }

package/src/session-types.mts

@@ -4,6 +4,11 @@ export type Transport = 'console' | 'stdio' | 'pty' | 'agentapi'
 export type SessionState = 'starting' | 'running' | 'idle' | 'awaiting_user' | 'settling' | 'closed' | 'unknown'
 export type RequestState = 'sending' | 'submitted' | 'unknown' | 'completed' | 'failed' | 'superseded'
 export type ConnectionState = 'connected' | 'closed' | 'unreachable' | 'unverified'
+/** 관리형 세션 호스트의 생존. unverified 는 "확인하지 못함"이며 살아 있음도 죽음도 아니다. */
+export type HostLiveness = 'alive' | 'dead' | 'unverified'
+/** `run.mjs rpc` 가 로컬 파이프에 연결조차 못 했을 때(ENOENT·ECONNREFUSED)의 종료 코드.
+ * 이 경우에만 요청이 확실히 전달되지 않았다고 판단한다. */
+export const RPC_NOT_DELIVERED_EXIT = 3
 export type HookEvent = 'SessionStart' | 'PreInvocation' | 'Stop'
 
 export interface Usage {
@@ -38,9 +43,12 @@ export interface SessionRecord {
   executable?: string
   address?: string
   token?: string
+  /** 로컬 파이프를 연 `bridge serve`·`run` 프로세스. 비 Windows 생존 확인에 쓴다. */
+  hostPid?: number
+  closedReason?: string
 }
 export type PublicSession = Pick<SessionRecord, 'id' | 'provider' | 'workspaces' | 'model' | 'transport' |
-  'state' | 'pid' | 'registeredAt' | 'event' | 'fullyIdle' | 'role' | 'usage' | 'usageKnown' | 'maxTokens' | 'pendingApproval' | 'conversationId'>
+  'state' | 'pid' | 'registeredAt' | 'event' | 'fullyIdle' | 'role' | 'usage' | 'usageKnown' | 'maxTokens' | 'pendingApproval' | 'conversationId'> & { liveness?: HostLiveness }
 export interface SessionSnapshot extends PublicSession {
   lastKnownState: SessionState | null
   state: SessionState

package/src/terminal-bridge.mjs

@@ -8,7 +8,7 @@ import net from 'node:net';
 import { randomUUID, randomBytes, timingSafeEqual } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 import { createRequire } from 'node:module';
-import { bridgeHome, repoKey, readJSON, writeJSON } from './bridge.mjs';
+import { bridgeHome, hostPipe, repoKey, readJSON, writeJSON } from './bridge.mjs';
 import { errorCode, errorMessage } from './session-types.mjs';
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const validID = (id) => /^[0-9a-f-]{36}$/i.test(id || '');
@@ -17,8 +17,8 @@ const sessionFile = (id) => {
         throw new Error('잘못된 터미널 세션 ID입니다.');
     return path.join(bridgeHome(), 'sessions', `${id}.json`);
 };
-const pipeFor = (id) => process.platform === 'win32'
-    ? `\\\\.\\pipe\\axmap-${id}` : path.join(bridgeHome(), `${id}.sock`);
+// 생존 확인(bridge.sessions)이 같은 이름을 보도록 한 곳에서 만든다.
+const pipeFor = hostPipe;
 export function sendTerminal(id, message, token = null, { timeoutMs = 10000 } = {}) {
     if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1)
         throw new Error('양의 응답 시간 한도가 필요합니다.');
@@ -28,11 +28,17 @@ export function sendTerminal(id, message, token = null, { timeoutMs = 10000 } =
     return new Promise((resolve, reject) => {
         const socket = net.createConnection(pipeFor(id));
         socket.setEncoding('utf8');
-        let buffer = '';
+        let buffer = '', connected = false;
         const fail = (e) => { socket.destroy(); reject(e); };
         socket.setTimeout(timeoutMs, () => fail(new Error('로컬 세션 응답 시간 초과. 자동 재전송하지 마세요.')));
-        socket.on('error', fail);
-        socket.on('connect', () => socket.write(JSON.stringify({ ...message, token: token || s.token }) + '\n'));
+        socket.on('error', e => {
+            // 연결 전의 ENOENT(파이프·소켓 없음)·ECONNREFUSED(듣는 쪽 없음)는 아무것도 쓰지
+            // 않았다는 증거다. 연결 뒤의 오류는 요청이 이미 건너갔을 수 있어 구별해 둔다.
+            if (!connected && ['ENOENT', 'ECONNREFUSED'].includes(errorCode(e) || ''))
+                Object.assign(e, { notDelivered: true });
+            fail(e);
+        });
+        socket.on('connect', () => { connected = true; socket.write(JSON.stringify({ ...message, token: token || s.token }) + '\n'); });
         socket.on('data', chunk => {
             buffer += chunk;
             if (Buffer.byteLength(buffer) > 1024 * 1024)
@@ -60,7 +66,7 @@ export async function startTerminal({ executable, args = [], provider, cwd = pro
     const { spawn } = await import('node-pty');
     const id = randomUUID(), token = randomBytes(32).toString('hex');
     const s = { id, provider, transport: 'pty', token, workspaces: [cwd], repos: [repoKey(cwd)],
-        state: 'starting', fullyIdle: false, registeredAt: new Date().toISOString(), event: 'launch' };
+        state: 'starting', fullyIdle: false, registeredAt: new Date().toISOString(), event: 'launch', hostPid: process.pid };
     const jobs = new Map();
     let pending = null, draft = false, term, closed = false, stopTimer;
     const save = () => { s.registeredAt = new Date().toISOString(); writeJSON(sessionFile(id), s); };

package/src/terminal-bridge.mts

@@ -7,7 +7,7 @@ import net from 'node:net'
 import { randomUUID, randomBytes, timingSafeEqual } from 'node:crypto'
 import { fileURLToPath } from 'node:url'
 import { createRequire } from 'node:module'
-import { bridgeHome, repoKey, readJSON, writeJSON } from './bridge.mjs'
+import { bridgeHome, hostPipe, repoKey, readJSON, writeJSON } from './bridge.mjs'
 import { errorCode, errorMessage } from './session-types.mjs'
 import type { IPty } from 'node-pty'
 import type { Provider, SessionRecord, LocalMessage, JobRecord, RequestState, TranscriptEntry } from './session-types.mjs'
@@ -25,8 +25,8 @@ const sessionFile = (id: string) => {
   if (!validID(id)) throw new Error('잘못된 터미널 세션 ID입니다.')
   return path.join(bridgeHome(), 'sessions', `${id}.json`)
 }
-const pipeFor = (id: string) => process.platform === 'win32'
-  ? `\\\\.\\pipe\\axmap-${id}` : path.join(bridgeHome(), `${id}.sock`)
+// 생존 확인(bridge.sessions)이 같은 이름을 보도록 한 곳에서 만든다.
+const pipeFor = hostPipe
 
 export function sendTerminal(id: string, message: LocalMessage, token: string | null = null, { timeoutMs = 10000 } = {}): Promise<unknown> {
   if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1) throw new Error('양의 응답 시간 한도가 필요합니다.')
@@ -35,11 +35,16 @@ export function sendTerminal(id: string, message: LocalMessage, token: string |
   return new Promise((resolve, reject) => {
     const socket = net.createConnection(pipeFor(id))
     socket.setEncoding('utf8')
-    let buffer = ''
+    let buffer = '', connected = false
     const fail = (e: Error) => { socket.destroy(); reject(e) }
     socket.setTimeout(timeoutMs, () => fail(new Error('로컬 세션 응답 시간 초과. 자동 재전송하지 마세요.')))
-    socket.on('error', fail)
-    socket.on('connect', () => socket.write(JSON.stringify({ ...message, token: token || s.token }) + '\n'))
+    socket.on('error', e => {
+      // 연결 전의 ENOENT(파이프·소켓 없음)·ECONNREFUSED(듣는 쪽 없음)는 아무것도 쓰지
+      // 않았다는 증거다. 연결 뒤의 오류는 요청이 이미 건너갔을 수 있어 구별해 둔다.
+      if (!connected && ['ENOENT', 'ECONNREFUSED'].includes(errorCode(e) || '')) Object.assign(e, { notDelivered: true })
+      fail(e)
+    })
+    socket.on('connect', () => { connected = true; socket.write(JSON.stringify({ ...message, token: token || s.token }) + '\n') })
     socket.on('data', chunk => {
       buffer += chunk
       if (Buffer.byteLength(buffer) > 1024 * 1024) return fail(new Error('로컬 응답 크기 제한 초과'))
@@ -59,7 +64,7 @@ export async function startTerminal({ executable, args = [], provider, cwd = pro
   const { spawn } = await import('node-pty')
   const id = randomUUID(), token = randomBytes(32).toString('hex')
   const s: SessionRecord = { id, provider, transport: 'pty', token, workspaces: [cwd], repos: [repoKey(cwd)],
-    state: 'starting', fullyIdle: false, registeredAt: new Date().toISOString(), event: 'launch' }
+    state: 'starting', fullyIdle: false, registeredAt: new Date().toISOString(), event: 'launch', hostPid: process.pid }
   const jobs = new Map<string, JobRecord>()
   let pending: JobRecord | null = null, draft = false, term: IPty, closed = false, stopTimer: NodeJS.Timeout | undefined
   const save = () => { s.registeredAt = new Date().toISOString(); writeJSON(sessionFile(id), s) }

package/src/update.mjs

@@ -11,19 +11,9 @@
  *    코드가 아니기 때문이다. 적용은 사람이 `axmap update` 를 읽고 한 줄을
  *    직접 실행하는 것으로만 일어난다.
  *
- * ── 🔴 벤더링된 사본에서는 아무것도 하지 않는다 ─────────────────────────────
- *
- * 팀 저장소의 `ci/axmap/` 은 이 코드의 **사본**이고(팀 CLAUDE.md 0.3),
- * 그 사본이 최신인지는 npm 이 아니라 `tools/vendor.mjs` 가 정한다. 사본이
- * 레지스트리를 쳐다보면 두 가지가 한꺼번에 나빠진다.
- *
- *   1. 팀 CI 가 매 파이프라인마다 바깥 네트워크에 의존하게 된다 — 벤더링이
- *      끊으려고 했던 바로 그 연결이다
- *   2. "새 버전이 있다" 는 안내가 팀원에게 뜨는데, 그 팀원이 할 수 있는 일은
- *      없다. 사본은 axMap 저장소에서 `vendor.mjs` 를 다시 돌려야만 바뀐다
- *
- * 사본인지 아닌지는 **옆에 `SOURCE.json` 이 있는가**로 가른다. 그 파일은
- * `tools/vendor.mjs` 가 사본에만 써 넣는다(원본 저장소 루트에는 없다).
+ * 팀 저장소 안에 이 코드의 사본(`ci/axmap/`)을 두던 시절에는 사본이면 확인을
+ * 건너뛰는 갈래가 여기 있었다. 2026-10-29 에 사본을 걷어냈으므로(DECISIONS D31)
+ * 그 갈래도 없다 — 이 코드가 도는 자리는 npm 설치본과 axMap 저장소뿐이다.
  */
 
 import fs from 'node:fs'
@@ -79,13 +69,6 @@ export function compareVersions(a, b) {
   return x.pre > y.pre ? 1 : -1
 }
 
-/**
- * 이 axMap 이 **벤더링된 사본**인가. 사본이면 갱신 확인을 통째로 건너뛴다.
- *
- * @param {string} axmapRoot  `bin/` · `src/` 를 담고 있는 폴더
- */
-export const isVendored = (axmapRoot) => fs.existsSync(path.join(axmapRoot, 'SOURCE.json'))
-
 /**
  * 확인을 하지 말아야 하는 자리인가.
  *

package/src/view.mjs

@@ -0,0 +1,129 @@
+// Generated from src/view.mts. Edit the .mts source and run npm run build.
+/** Read-only terminal view of observed sessions, claims, mail and events. */
+import fs from 'node:fs';
+import path from 'node:path';
+import { bridgeHome } from './bridge.mjs';
+import { createMonitor, fitTerminal, terminalText } from './monitor.mjs';
+const uuid = /^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/i;
+export function createView(cwd, options = {}) {
+    const collect = createMonitor(cwd, options);
+    return async () => {
+        const snapshot = await collect(), mail = [], mailIssues = [];
+        if (snapshot.issues.some(issue => issue.startsWith('세션 확인:')))
+            mailIssues.push('받은 편지함: 세션 목록을 확인하지 못함');
+        // Reading does not create mailboxes, expire records, collect messages or wake a model.
+        for (const session of snapshot.sessions.slice(0, 100)) {
+            if (!uuid.test(session.id)) {
+                mailIssues.push('받은 편지함: 세션 ID 확인 필요');
+                continue;
+            }
+            const file = path.join(bridgeHome(), 'mailboxes', `${session.id}.json`);
+            try {
+                if (fs.statSync(file).size > 1024 * 1024)
+                    throw new Error('파일 크기 초과');
+                const box = JSON.parse(fs.readFileSync(file, 'utf8'));
+                if (!box || typeof box !== 'object' || box.version !== 1 || !Array.isArray(box.messages))
+                    throw new Error('형식 오류');
+                for (const m of box.messages) {
+                    if (!m || typeof m !== 'object')
+                        throw new Error('메시지 형식 오류');
+                    const entry = m;
+                    if (entry.repo !== snapshot.repo || entry.state !== 'queued')
+                        continue;
+                    if (entry.to !== session.id || typeof entry.from !== 'string' || typeof entry.text !== 'string' || typeof entry.expiresAt !== 'string' || !Number.isFinite(Date.parse(entry.expiresAt)))
+                        throw new Error('메시지 형식 오류');
+                    if (Date.parse(entry.expiresAt) <= Date.now())
+                        continue;
+                    mail.push({ to: session.id, from: entry.from, topic: typeof entry.topic === 'string' ? entry.topic : '', text: entry.text });
+                }
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    mailIssues.push(`받은 편지함 ${session.id.slice(0, 8)}: 읽기 실패`);
+            }
+        }
+        if (snapshot.sessions.length > 100)
+            mailIssues.push('받은 편지함: 앞의 세션 100개만 확인');
+        return { ...snapshot, mail, mailIssues };
+    };
+}
+const labels = { idle: '대기', running: '작업 중', closed: '종료', awaiting_user: '승인 대기', unknown: '상태 미확인', starting: '시작 중', settling: '대기 전환 중' };
+const segmenter = new Intl.Segmenter(undefined, { granularity: 'grapheme' });
+function cells(value) {
+    return [...segmenter.segment(value)].reduce((n, { segment }) => {
+        const cp = segment.codePointAt(0) || 0;
+        return n + (/\p{Extended_Pictographic}/u.test(segment) || cp >= 0x1100 && (cp <= 0x115f || cp >= 0x2e80 && cp <= 0xa4cf || cp >= 0xac00 && cp <= 0xd7a3 || cp >= 0xf900 && cp <= 0xfaff || cp >= 0xfe10 && cp <= 0xfe6f || cp >= 0xff01 && cp <= 0xff60 || cp >= 0x20000) ? 2 : /^\p{Mark}+$/u.test(segment) ? 0 : 1);
+    }, 0);
+}
+function pad(value, width) {
+    const text = fitTerminal(value, Math.max(0, width));
+    return text + ' '.repeat(Math.max(0, width - cells(text)));
+}
+export function renderView(snapshot, { columns = 100, rows = 36, color = false, frame = 0 } = {}) {
+    const width = Math.max(1, Math.floor(columns)), height = Math.max(1, Math.floor(rows)), lines = [];
+    if (width < 20)
+        return [fitTerminal('axMap · 화면이 좁습니다', width), fitTerminal('q 종료', width)].slice(0, height).join('\n');
+    const view = snapshot;
+    const palette = {
+        text: '194;197;205', muted: '137;140;150', border: '78;82;94', accent: '172;158;199',
+        claude: '207;157;134', codex: '143;174;214', agy: '139;187;165', warning: '212;171;125',
+    };
+    const paint = (text, tone) => color ? `\x1b[38;2;${palette[tone]}m${text}\x1b[0m` : text;
+    const line = (text, tone = 'text') => lines.push(paint(fitTerminal(text, width), tone));
+    const paintBoxLine = (text, index, last, tone, colorStatus = false) => {
+        if (index === 0 || index === last)
+            return paint(text, 'border');
+        return paint(text.slice(0, 1), 'border') + paint(text.slice(1, -1), index === 1 || colorStatus && index === 3 ? tone : 'text') + paint(text.slice(-1), 'border');
+    };
+    const box = (title, content, w) => {
+        const n = Math.max(1, w - 2);
+        return [`┌${'─'.repeat(n)}┐`, ...[title, ...content].map(s => `│${pad(' ' + terminalText(s), n)}│`), `└${'─'.repeat(n)}┘`];
+    };
+    line('axMap VIEW · 실제 로컬 관측', 'accent');
+    line(`${snapshot.cwd} · ${snapshot.checkedAt}`, 'muted');
+    const sessions = [...snapshot.sessions].sort((a, b) => Number(b.connection === 'connected') - Number(a.connection === 'connected')).slice(0, 3);
+    const cols = width >= 90 ? 3 : width >= 58 ? 2 : 1;
+    const cardWidth = Math.max(3, Math.floor((width - (cols - 1) * 2) / cols));
+    const cards = sessions.map(s => {
+        const active = snapshot.requests.some(r => r.to === s.id && ['sending', 'submitted'].includes(r.state));
+        const connection = { closed: '연결 종료', unreachable: '연결 불가', unverified: '연결 미확인' };
+        const state = s.connection === 'connected' ? labels[s.state] || '상태 미확인' : connection[s.connection] || '연결 미확인';
+        return box(`${s.provider.toUpperCase()} · ${s.id.slice(0, 8)}`, [s.role || '역할 미확인', `${active ? ['◐', '◓', '◑', '◒'][frame % 4] : '○'} ${state}`, s.model || '모델 미확인'], cardWidth);
+    });
+    for (let start = 0; start < cards.length; start += cols) {
+        const group = cards.slice(start, start + cols);
+        for (let i = 0; i < group[0].length; i++)
+            lines.push(group.map((card, k) => {
+                const provider = sessions[start + k].provider.toLowerCase();
+                const tone = provider === 'codex' ? 'codex' : provider === 'agy' ? 'agy' : provider === 'claude' ? 'claude' : 'accent';
+                return paintBoxLine(card[i], i, card.length - 1, tone, true);
+            }).join('  '));
+    }
+    if (!sessions.length)
+        line('등록된 세션 없음 · bridge 연결 후 표시', 'muted');
+    const claims = snapshot.claims.flatMap(c => c.paths.map(p => `${terminalText(c.agent)} · ${terminalText(p)}`));
+    const mails = view.mail?.map(m => `${terminalText(m.from)} → ${m.to.slice(0, 8)} · ${terminalText(m.topic || m.text)}`) || [];
+    const left = [`LEDGER · 현재 선점 ${snapshot.claims.length}건`, ...(claims.slice(0, 4).length ? claims.slice(0, 4) : ['현재 선점 없음'])];
+    const right = [`MAILBOX · ${view.mailIssues?.length ? '일부 확인 실패' : `대기 ${view.mail?.length ?? 0}건`}`, ...(mails.slice(0, 4).length ? mails.slice(0, 4) : [view.mailIssues?.length ? '대기 건수 미확인' : '대기 메시지 없음'])];
+    if (width >= 58) {
+        const lw = Math.floor((width - 2) / 2), rw = width - lw - 2, count = Math.max(left.length, right.length);
+        const a = box(left[0], Array.from({ length: count - 1 }, (_, i) => left[i + 1] || ''), lw);
+        const b = box(right[0], Array.from({ length: count - 1 }, (_, i) => right[i + 1] || ''), rw);
+        a.forEach((v, i) => lines.push(paintBoxLine(v, i, a.length - 1, 'accent') + '  ' + paintBoxLine(b[i], i, b.length - 1, 'accent')));
+    }
+    else {
+        const a = box(left[0], left.slice(1), Math.max(3, width));
+        const b = box(right[0], right.slice(1), Math.max(3, width));
+        lines.push(...a.map((x, i) => paintBoxLine(x, i, a.length - 1, 'accent')));
+        lines.push(...b.map((x, i) => paintBoxLine(x, i, b.length - 1, 'accent')));
+    }
+    line('── 최근 관측 이벤트 ──', 'muted');
+    for (const e of snapshot.events.slice(0, 4))
+        line(`${terminalText(e.at.slice(11, 19))}  ${terminalText(e.label)}`);
+    if (!snapshot.events.length)
+        line('기록된 이벤트 없음', 'muted');
+    for (const issue of [...snapshot.issues, ...(view.mailIssues || [])].slice(0, 2))
+        line(`확인 필요: ${issue}`, 'warning');
+    const footer = paint(fitTerminal('q / Esc 종료 · 작업은 계속됨 · 모델 호출 없음', width), 'muted');
+    return [...lines.slice(0, Math.max(0, height - 1)), footer].join('\n');
+}

package/src/view.mts

@@ -0,0 +1,115 @@
+/** Read-only terminal view of observed sessions, claims, mail and events. */
+import fs from 'node:fs'
+import path from 'node:path'
+import { bridgeHome } from './bridge.mjs'
+import { createMonitor, fitTerminal, terminalText } from './monitor.mjs'
+import type { MonitorSnapshot } from './monitor.mjs'
+
+interface ViewMail { to: string; from: string; topic: string; text: string }
+export interface ViewSnapshot extends MonitorSnapshot { mail: ViewMail[]; mailIssues: string[] }
+const uuid = /^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/i
+
+export function createView(cwd: string, options: Parameters<typeof createMonitor>[1] = {}): () => Promise<ViewSnapshot> {
+  const collect = createMonitor(cwd, options)
+  return async () => {
+    const snapshot = await collect(), mail: ViewMail[] = [], mailIssues: string[] = []
+    if (snapshot.issues.some(issue => issue.startsWith('세션 확인:'))) mailIssues.push('받은 편지함: 세션 목록을 확인하지 못함')
+    // Reading does not create mailboxes, expire records, collect messages or wake a model.
+    for (const session of snapshot.sessions.slice(0, 100)) {
+      if (!uuid.test(session.id)) { mailIssues.push('받은 편지함: 세션 ID 확인 필요'); continue }
+      const file = path.join(bridgeHome(), 'mailboxes', `${session.id}.json`)
+      try {
+        if (fs.statSync(file).size > 1024 * 1024) throw new Error('파일 크기 초과')
+        const box: unknown = JSON.parse(fs.readFileSync(file, 'utf8'))
+        if (!box || typeof box !== 'object' || (box as { version?: unknown }).version !== 1 || !Array.isArray((box as { messages?: unknown }).messages)) throw new Error('형식 오류')
+        for (const m of (box as { messages: unknown[] }).messages) {
+          if (!m || typeof m !== 'object') throw new Error('메시지 형식 오류')
+          const entry = m as Record<string, unknown>
+          if (entry.repo !== snapshot.repo || entry.state !== 'queued') continue
+          if (entry.to !== session.id || typeof entry.from !== 'string' || typeof entry.text !== 'string' || typeof entry.expiresAt !== 'string' || !Number.isFinite(Date.parse(entry.expiresAt))) throw new Error('메시지 형식 오류')
+          if (Date.parse(entry.expiresAt) <= Date.now()) continue
+          mail.push({ to: session.id, from: entry.from, topic: typeof entry.topic === 'string' ? entry.topic : '', text: entry.text })
+        }
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== 'ENOENT') mailIssues.push(`받은 편지함 ${session.id.slice(0, 8)}: 읽기 실패`)
+      }
+    }
+    if (snapshot.sessions.length > 100) mailIssues.push('받은 편지함: 앞의 세션 100개만 확인')
+    return { ...snapshot, mail, mailIssues }
+  }
+}
+
+const labels: Record<string, string> = { idle: '대기', running: '작업 중', closed: '종료', awaiting_user: '승인 대기', unknown: '상태 미확인', starting: '시작 중', settling: '대기 전환 중' }
+const segmenter = new Intl.Segmenter(undefined, { granularity: 'grapheme' })
+function cells(value: string): number {
+  return [...segmenter.segment(value)].reduce((n, { segment }) => {
+    const cp = segment.codePointAt(0) || 0
+    return n + (/\p{Extended_Pictographic}/u.test(segment) || cp >= 0x1100 && (cp <= 0x115f || cp >= 0x2e80 && cp <= 0xa4cf || cp >= 0xac00 && cp <= 0xd7a3 || cp >= 0xf900 && cp <= 0xfaff || cp >= 0xfe10 && cp <= 0xfe6f || cp >= 0xff01 && cp <= 0xff60 || cp >= 0x20000) ? 2 : /^\p{Mark}+$/u.test(segment) ? 0 : 1)
+  }, 0)
+}
+function pad(value: unknown, width: number): string {
+  const text = fitTerminal(value, Math.max(0, width))
+  return text + ' '.repeat(Math.max(0, width - cells(text)))
+}
+
+export function renderView(snapshot: MonitorSnapshot, { columns = 100, rows = 36, color = false, frame = 0 } = {}): string {
+  const width = Math.max(1, Math.floor(columns)), height = Math.max(1, Math.floor(rows)), lines: string[] = []
+  if (width < 20) return [fitTerminal('axMap · 화면이 좁습니다', width), fitTerminal('q 종료', width)].slice(0, height).join('\n')
+  const view = snapshot as Partial<ViewSnapshot>
+  const palette = {
+    text: '194;197;205', muted: '137;140;150', border: '78;82;94', accent: '172;158;199',
+    claude: '207;157;134', codex: '143;174;214', agy: '139;187;165', warning: '212;171;125',
+  }
+  type Tone = keyof typeof palette
+  const paint = (text: string, tone: Tone) => color ? `\x1b[38;2;${palette[tone]}m${text}\x1b[0m` : text
+  const line = (text: string, tone: Tone = 'text') => lines.push(paint(fitTerminal(text, width), tone))
+  const paintBoxLine = (text: string, index: number, last: number, tone: Tone, colorStatus = false) => {
+    if (index === 0 || index === last) return paint(text, 'border')
+    return paint(text.slice(0, 1), 'border') + paint(text.slice(1, -1), index === 1 || colorStatus && index === 3 ? tone : 'text') + paint(text.slice(-1), 'border')
+  }
+  const box = (title: string, content: string[], w: number): string[] => {
+    const n = Math.max(1, w - 2)
+    return [`┌${'─'.repeat(n)}┐`, ...[title, ...content].map(s => `│${pad(' ' + terminalText(s), n)}│`), `└${'─'.repeat(n)}┘`]
+  }
+  line('axMap VIEW · 실제 로컬 관측', 'accent')
+  line(`${snapshot.cwd} · ${snapshot.checkedAt}`, 'muted')
+  const sessions = [...snapshot.sessions].sort((a, b) => Number(b.connection === 'connected') - Number(a.connection === 'connected')).slice(0, 3)
+  const cols = width >= 90 ? 3 : width >= 58 ? 2 : 1
+  const cardWidth = Math.max(3, Math.floor((width - (cols - 1) * 2) / cols))
+  const cards = sessions.map(s => {
+    const active = snapshot.requests.some(r => r.to === s.id && ['sending', 'submitted'].includes(r.state))
+    const connection: Record<string, string> = { closed: '연결 종료', unreachable: '연결 불가', unverified: '연결 미확인' }
+    const state = s.connection === 'connected' ? labels[s.state] || '상태 미확인' : connection[s.connection] || '연결 미확인'
+    return box(`${s.provider.toUpperCase()} · ${s.id.slice(0, 8)}`, [s.role || '역할 미확인', `${active ? ['◐', '◓', '◑', '◒'][frame % 4] : '○'} ${state}`, s.model || '모델 미확인'], cardWidth)
+  })
+  for (let start = 0; start < cards.length; start += cols) {
+    const group = cards.slice(start, start + cols)
+    for (let i = 0; i < group[0]!.length; i++) lines.push(group.map((card, k) => {
+      const provider = sessions[start + k]!.provider.toLowerCase()
+      const tone: Tone = provider === 'codex' ? 'codex' : provider === 'agy' ? 'agy' : provider === 'claude' ? 'claude' : 'accent'
+      return paintBoxLine(card[i]!, i, card.length - 1, tone, true)
+    }).join('  '))
+  }
+  if (!sessions.length) line('등록된 세션 없음 · bridge 연결 후 표시', 'muted')
+  const claims = snapshot.claims.flatMap(c => c.paths.map(p => `${terminalText(c.agent)} · ${terminalText(p)}`))
+  const mails = view.mail?.map(m => `${terminalText(m.from)} → ${m.to.slice(0, 8)} · ${terminalText(m.topic || m.text)}`) || []
+  const left = [`LEDGER · 현재 선점 ${snapshot.claims.length}건`, ...(claims.slice(0, 4).length ? claims.slice(0, 4) : ['현재 선점 없음'])]
+  const right = [`MAILBOX · ${view.mailIssues?.length ? '일부 확인 실패' : `대기 ${view.mail?.length ?? 0}건`}`, ...(mails.slice(0, 4).length ? mails.slice(0, 4) : [view.mailIssues?.length ? '대기 건수 미확인' : '대기 메시지 없음'])]
+  if (width >= 58) {
+    const lw = Math.floor((width - 2) / 2), rw = width - lw - 2, count = Math.max(left.length, right.length)
+    const a = box(left[0]!, Array.from({ length: count - 1 }, (_, i) => left[i + 1] || ''), lw)
+    const b = box(right[0]!, Array.from({ length: count - 1 }, (_, i) => right[i + 1] || ''), rw)
+    a.forEach((v, i) => lines.push(paintBoxLine(v, i, a.length - 1, 'accent') + '  ' + paintBoxLine(b[i]!, i, b.length - 1, 'accent')))
+  } else {
+    const a = box(left[0]!, left.slice(1), Math.max(3, width))
+    const b = box(right[0]!, right.slice(1), Math.max(3, width))
+    lines.push(...a.map((x, i) => paintBoxLine(x, i, a.length - 1, 'accent')))
+    lines.push(...b.map((x, i) => paintBoxLine(x, i, b.length - 1, 'accent')))
+  }
+  line('── 최근 관측 이벤트 ──', 'muted')
+  for (const e of snapshot.events.slice(0, 4)) line(`${terminalText(e.at.slice(11, 19))}  ${terminalText(e.label)}`)
+  if (!snapshot.events.length) line('기록된 이벤트 없음', 'muted')
+  for (const issue of [...snapshot.issues, ...(view.mailIssues || [])].slice(0, 2)) line(`확인 필요: ${issue}`, 'warning')
+  const footer = paint(fitTerminal('q / Esc 종료 · 작업은 계속됨 · 모델 호출 없음', width), 'muted')
+  return [...lines.slice(0, Math.max(0, height - 1)), footer].join('\n')
+}