axmap-cli 1.7.0 → 1.8.0

package/.claude/commands/axmap-view.md

@@ -0,0 +1,9 @@
+---
+description: axMap 세션·선점·받은 편지함을 터미널 카드로 보여 줍니다
+---
+
+현재 Git 저장소를 대상으로 별도의 대화형 터미널에서 `axmap view --cwd <현재 저장소 절대경로>`를 실행하도록 안내한다. 이 명령은 터미널에서 직접 갱신되며 `q`로 닫는다. 도구가 대화형 터미널을 제공하지 않는다면 `axmap view --cwd <현재 저장소 절대경로> --once`의 결과를 스냅샷으로 보여 주고 실시간 화면이라고 주장하지 않는다. 저장소가 모호하면 다른 저장소를 임의로 선택하지 않는다.
+
+관측은 작업을 새로 시작하거나 메시지를 회수·전송하지 않는다. 실제 등록·관측된 상태만 보여 주며 미확인 값을 추정하지 않는다.
+
+개발 중인 axMap 소스 체크아웃에서는 설치본이 구버전일 수 있다. `axmap view --help`를 확인하고 해당 명령이 없으면 소스 체크아웃의 `node bin/axmap.mjs view --cwd <현재 저장소 절대경로>`를 사용한다.

package/README.ko.md

@@ -23,6 +23,8 @@ axmap setup
 
 지원되는 MCP Apps 호스트에서는 대화 안에서 파이프라인을 확인하고, Claude Code·agy에서는 기존 상태줄에 진행을 추가할 수 있습니다. 호스트별 지원이 다르며 ChatGPT·Claude 앱의 실제 임베디드 화면은 아직 검증하지 않았습니다. [클라이언트 설정과 제한](docs/PIPELINE-CLIENTS.md). 선택적으로 별도 터미널의 `axmap monitor`도 제공합니다([사용법](docs/MONITOR.md)).
 
+터미널에서 `axmap view --cwd <저장소>`를 실행하면 관측된 로컬 세션·선점·대기 메시지·최근 이벤트를 카드로 볼 수 있습니다. 화면은 자동 갱신되며 `q` 또는 Esc로 닫습니다. `--once`는 한 번만 출력하고 `--json`은 구조화된 결과를 제공합니다. 등록되지 않은 모든 에이전트나 GitLab 활동까지 표시하는 것은 아닙니다. [화면 사용법](docs/VIEW.md).
+
 ---
 
 ## 변경 기록

package/README.md

@@ -1,5 +1,7 @@
 # axMap
 
+Run `axmap view --cwd <repository>` to see observed local sessions, claims, pending mailbox messages and recent events in a terminal dashboard. The view refreshes interactively; press `q` or Esc to exit. Use `--once` for a snapshot or `--json` for structured output. See [the view guide](docs/VIEW.md). The display reflects available observations, not a complete view of every agent or GitLab activity.
+
 **Several AI agents. One repository. Clear ownership before every edit.**
 
 axMap is a collaboration CLI that claims files and folders before work begins and rejects overlapping claims.

package/bin/axmap.mjs

@@ -2625,6 +2625,7 @@ const RUNNERS = {
   run: ['tools/run.mjs', '사용자가 여는 AI CLI를 연결한다'],
   bridge: ['tools/bridge.mjs', '열린 로컬 AI 세션에 작업을 전달한다'],
   monitor: ['tools/monitor.mjs', '세션과 요청 파이프라인을 실시간으로 표시한다'],
+  view: ['tools/view.mjs', '세션·선점·받은 편지함을 터미널 카드로 표시한다'],
   pipeline: ['tools/pipeline.mjs', '대화 안 파이프라인 표시와 CLI 상태줄을 연결한다'],
   gate: ['governance/gate.mjs', '이 MR 이 정족수를 채웠는가'],
   vote: ['governance/vote.mjs', '표를 던진다'],
@@ -2837,6 +2838,7 @@ const HELP = `axmap - AI 에이전트 작업 선점 프로토콜
   axmap bus                          에이전트 사이 쪽지함 (post · list · read · reply)
   axmap bridge                       로컬 세션·자동 대화 (serve · sessions · send · chat · dialogue)
   axmap monitor                      에이전트·요청 파이프라인·최근 이벤트 실시간 화면
+  axmap view                         세션·선점·받은 편지함을 카드로 실시간 표시
   axmap pipeline                     대화 안 표시·Claude/agy 상태줄 연결 (--help)
   axmap run agy [인수...]             연결된 Antigravity CLI를 직접 연다
   axmap mr-target                    이 브랜치가 저 브랜치로 갈 수 있는가
@@ -2881,6 +2883,7 @@ switch (cmd) {
   case 'setup':
   case 'bridge':
   case 'monitor':
+  case 'view':
   case 'pipeline':
   case 'run':
   case 'gate':

package/docs/VIEW.md

@@ -0,0 +1,19 @@
+# 터미널에서 axMap 보기
+
+설치한 패키지에서 다음 명령으로 실행한다.
+
+```powershell
+axmap view --cwd C:\work\my-repo
+```
+
+소스 체크아웃에서 확인할 때는 `node bin/axmap.mjs view --cwd <repo>`를 사용한다.
+
+연결된 세션을 우선해 카드로 보여 주고 현재 선점, 등록된 세션의 대기 중인 로컬 편지와 최근 관측 이벤트를 표시한다. 실시간 갱신 중 `q`, Esc 또는 Ctrl+C로 화면을 닫는다. 진행 중인 작업은 계속된다. 창 크기에 따라 카드가 한 줄 또는 여러 줄로 배치된다.
+
+`--once`는 한 번만 출력하며, `--json`은 같은 관측 자료를 JSON으로 출력한다. `--interval 1000`은 수집 간격이고 `--no-color` 또는 `NO_COLOR`는 색을 끈다. 파이프나 리디렉션에서는 스냅샷만 출력한다. 터미널 글꼴은 사용자의 터미널 설정을 따른다.
+
+수신자별 편지함을 읽기만 한다. 읽음 처리, 만료 상태 저장, 메시지 전송, 모델 요청 및 승인 조작은 하지 않는다. 만료 시각이 지난 대기 메시지는 화면 집계에서 제외하고 파일은 수정하지 않는다. 편지함을 읽을 수 없으면 빈 편지함으로 단정하지 않고 오류를 보여 준다. 기존 모니터와 마찬가지로 요청의 관측 결과 확인 과정은 기존 요청 기록을 갱신할 수 있다. 출력에 메시지 주제 또는 내용이 포함될 수 있으니 공유할 때 범위를 확인한다.
+
+포트폴리오 그림은 설명용 애니메이션이며 이 명령은 실제 관측값을 보여 준다. 확인하지 못한 작업률·토큰·연결 상태를 임의로 만들지 않는다. 등록하지 않은 AI 대화는 표시되지 않는다.
+
+Claude Code에서 프로젝트 명령을 설치한 환경은 `/axmap-view`로 안내를 부를 수 있다. Codex 등 다른 호스트는 `skills/axmap-view/SKILL.md`를 해당 호스트의 방법으로 설치해야 하며, 모든 터미널에서 `/axmap-view` 자체가 실행되는 것은 아니다. 확실한 실행 방법은 `axmap view`다.

package/package.json

@@ -1,7 +1,7 @@
 {
   "//name": "🔴 npm 의 'axmap' 은 2022년부터 남이 쓰고 있는 다른 꾸러미다(leozin_ 의 Map 라이브러리, 1.1.2). 그래서 `npx axmap` 은 우리 것이 아니고, 누구에게도 그렇게 안내하면 안 된다. 2026-08-28 에 axmap-cli 로 정했다 — 스코프(@사용자/이름)를 쓰지 않는 이유는 스코프가 npm 계정 이름에 묶여서 나중에 팀이나 조직으로 옮길 때 이름이 통째로 바뀌기 때문이다. 사람이 치는 **명령** 이름은 그대로 axmap 이다 (아래 bin) — 꾸러미 이름과 명령 이름은 달라도 된다.",
   "name": "axmap-cli",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "//private": "🔴 여기 있던 \"private\": true 를 2026-08-28 에 지웠다. 그 줄이 있는 동안 npm publish 는 거부됐다. 되돌리려면 다시 넣으면 되지만, 이미 올라간 버전은 그래도 안 사라진다 — npm 은 같은 번호를 덮어쓰지 못하고 삭제도 72시간 안에만 된다. 즉 이 줄을 되살리는 것은 '앞으로 안 올린다' 는 뜻이지 '올린 것을 없앤다' 는 뜻이 아니다.",
   "//publishConfig": "axmap-cli 는 스코프가 없어서 기본이 이미 공개다. 즉 지금은 없어도 된다. 그래도 남겨 두는 이유: 나중에 @조직/axmap 처럼 스코프를 붙이는 날 이 줄이 없으면 publish 가 '유료 플랜이 필요하다'는 엉뚱한 말로 실패한다.",
   "publishConfig": {
@@ -34,6 +34,7 @@
     "tools/",
     "skills/",
     "governance/",
+    "docs/VIEW.md",
     ".claude/",
     "CLAUDE.md"
   ],

package/skills/axmap-view/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: axmap-view
+description: Show the current Git repository's axMap sessions, active claims, pending mailbox and recent events in a terminal view.
+---
+
+Use the current Git repository or the user's explicitly designated repository. Run `axmap view --cwd <absolute-repository>` in an interactive terminal; `q`, Esc or Ctrl+C closes the view. If the host cannot provide an interactive terminal, run `axmap view --cwd <absolute-repository> --once` and identify it as a snapshot. Slash-menu availability depends on the host and installed skill; do not imply that a bare slash command works in every terminal.
+
+The display reads local evidence only. It does not start an AI session, submit work, send or collect mail, or imply that an unobserved session is idle. Never invent progress percentages or token counts.

package/src/monitor-cli.mjs

@@ -3,12 +3,13 @@ import path from 'node:path';
 import { createMonitor, renderMonitor } 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) {
     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]}`);
@@ -22,8 +23,9 @@ export async function runMonitor(args) {
     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/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/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')
+}

package/tools/run-tests.mjs

@@ -40,7 +40,9 @@ if (files.length === 0) {
 // Windows ConPTY owns native console workers. Exercise it after other test
 // processes have exited so temporary console teardown cannot race the suite's
 // many concurrent subprocess fixtures. Both batches remain mandatory.
-const nativeNames = new Set(['terminal-bridge.test.mjs', 'monitor-cli.test.mjs'])
+// The lock test also asserts an elapsed-time ceiling, so concurrent fixtures
+// can make it fail even when the lock retry path was never entered.
+const nativeNames = new Set(['terminal-bridge.test.mjs', 'monitor-cli.test.mjs', 'view.test.mjs', 'ledgerlock.test.mjs'])
 const native = process.platform === 'win32' ? files.filter(f => nativeNames.has(path.basename(f))) : []
 const ordinary = files.filter(f => !native.includes(f))
 for (const batch of [ordinary, ...native.map(f => [f])].filter(batch => batch.length)) {

package/tools/view.mjs

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { runMonitor } from '../src/monitor-cli.mjs'
+import { errorMessage } from '../src/session-types.mjs'
+
+if (process.argv.includes('--help') || process.argv.includes('-h')) {
+  console.log('axmap view [--cwd <repo>] [--interval 1000] [--once | --json] [--no-color]\n실제 세션·선점·대기 메시지·최근 이벤트를 터미널에서 표시합니다. q / Esc / Ctrl+C 종료.')
+} else {
+  try { await runMonitor(['--view', ...process.argv.slice(2)]) }
+  catch (e) { console.error(`axMap view: ${errorMessage(e)}`); process.exitCode = 1 }
+}