axmap-cli 1.0.0 → 1.0.3

package/bin/axmap.mjs

@@ -108,6 +108,24 @@ const LEDGER_REL = path.join('.axmap', 'ledger')
  */
 const BUS_BRANCH = 'axmap/bus'
 const BUS_REL = path.join('.axmap', 'bus')
+
+/**
+ * 사람별 상태가 사는 곳 — 어디까지 읽었는지, 이 사람이 쓰는 이름이 무엇무엇인지.
+ *
+ * 🔴 왜 쪽지함과 다른 브랜치인가. 쪽지 **본문**은 모두가 공유하는 한 벌이고,
+ *    **어디까지 읽었는지**는 사람마다 다르다. 한 브랜치에 섞으면 쪽지를 읽기만
+ *    해도 공유 브랜치에 커밋이 쌓인다 — 읽는 행위가 남에게 보이는 흔적을 남기는
+ *    것은 쪽지함이 할 일이 아니다.
+ *
+ * 🔴 그리고 왜 각자 PC 의 파일이 아닌가. 지금까지 읽음 표시는 작업 폴더 안의
+ *    파일 하나였다. 그래서 **PC 를 바꾸면 전부 다시 안 읽음**이 됐다. 쪽지는
+ *    공유되는데 읽었다는 사실만 그 PC 에 갇혀 있었다.
+ *
+ * 파일은 사람마다 하나(`users/<이메일>.json`)다. 서로 다른 파일이라 여럿이
+ * 동시에 써도 부딪히지 않는다 — 쪽지가 파일 하나씩인 것과 같은 이유다.
+ */
+const USERS_BRANCH = 'axmap/users'
+const USERS_REL = path.join('.axmap', 'users')
 /**
  * `release` 가 아무것도 반납하지 못했을 때. SPEC 8절.
  * 0 이 아니어야 하는 이유는 그 주변 주석에 적혀 있다.
@@ -591,6 +609,15 @@ function busMessagesDir(root) {
   return path.join(busDir(root), 'messages')
 }
 
+function usersDir(root) {
+  return path.join(root, USERS_REL)
+}
+
+/** 사람마다의 파일이 쌓이는 곳. `.gitattributes` 와 섞이지 않게 한 폴더 아래 모은다. */
+function usersFilesDir(root) {
+  return path.join(usersDir(root), 'users')
+}
+
 /**
  * 옛 쪽지함. **읽기만 한다.**
  *
@@ -1108,11 +1135,25 @@ function restoreClaimFile(file, prev) {
  *
  * @returns {'ready'|'created'|'failed'}
  */
-function ensureBus(root) {
-  const dir = busDir(root)
+/**
+ * 고아 브랜치(**코드 이력과 아무 조상도 공유하지 않는 별도 계보**) 하나를 만들고
+ * 그것을 옆 폴더에 펼친다. 쪽지함과 사람별 상태가 **같은 코드**로 만들어진다.
+ *
+ * 🔴 이 함수가 있는 이유는 사본을 안 만들기 위해서다. 쪽지함 것을 복사해서
+ *    사람 것을 만들면 두 벌이 되고, 두 벌은 반드시 어긋난다 — 이 저장소가 팀
+ *    사본을 걷어낸 것과 같은 이유이고, 실제로 그 어긋남으로 쪽지가 묻혔다.
+ *
+ * @param what  실패 메시지에 쓸 사람 말 ("쪽지함" · "사람별 상태")
+ * @param seed  worktree 를 만든 직후 그 안을 채우는 함수. 브랜치마다 다른 유일한 곳
+ */
+function ensureOrphan(root, { branch, rel, dir, what, seed }) {
+  const fail = (r) => {
+    console.error(`경고: ${what}을(를) 준비하지 못했습니다 - ${(r.err || r.out || '').split('\n')[0]}`)
+    return 'failed'
+  }
   if (fs.existsSync(path.join(dir, '.git'))) return 'ready'
   if (fs.existsSync(dir) && fs.readdirSync(dir).length) {
-    console.error(`경고: ${BUS_REL} 가 있지만 쪽지함 worktree 가 아닙니다.\n  지운 뒤 다시 실행하세요:  rm -rf ${BUS_REL}`)
+    console.error(`경고: ${rel} 가 있지만 ${what} worktree 가 아닙니다.\n  지운 뒤 다시 실행하세요:  rm -rf ${rel}`)
     return 'failed'
   }
 
@@ -1122,54 +1163,107 @@ function ensureBus(root) {
   const remote = r.source === 'ambiguous' ? null : r.name
 
   let base = null
-  if (remote && git(['fetch', '--quiet', remote, BUS_BRANCH], { cwd: root }).code === 0) {
+  if (remote && git(['fetch', '--quiet', remote, branch], { cwd: root }).code === 0) {
     base = git(['rev-parse', 'FETCH_HEAD'], { cwd: root }).out
   } else {
     // 빈 트리 -> 부모 없는 커밋 -> 브랜치. 작업 트리를 건드리지 않는 고아 브랜치.
     const tree = git(['mktree'], { cwd: root, input: '' })
-    if (tree.code !== 0) return busSetupFailed(tree)
-    const c = git(['commit-tree', tree.out, '-m', 'axmap: bus init'], { cwd: root })
-    if (c.code !== 0) return busSetupFailed(c)
+    if (tree.code !== 0) return fail(tree)
+    const c = git(['commit-tree', tree.out, '-m', `axmap: ${branch} init`], { cwd: root })
+    if (c.code !== 0) return fail(c)
     base = c.out
   }
 
-  if (git(['rev-parse', '--verify', '--quiet', BUS_BRANCH], { cwd: root }).code !== 0) {
-    const b = git(['branch', BUS_BRANCH, base], { cwd: root })
-    if (b.code !== 0) return busSetupFailed(b)
+  if (git(['rev-parse', '--verify', '--quiet', branch], { cwd: root }).code !== 0) {
+    const b = git(['branch', branch, base], { cwd: root })
+    if (b.code !== 0) return fail(b)
   }
-  const w = git(['worktree', 'add', '--quiet', dir, BUS_BRANCH], { cwd: root })
-  if (w.code !== 0) return busSetupFailed(w)
+  const w = git(['worktree', 'add', '--quiet', dir, branch], { cwd: root })
+  if (w.code !== 0) return fail(w)
 
-  // git 은 빈 디렉터리를 추적하지 않는다. 쪽지가 0개인 동안에도 폴더가 살아 있게 한다.
-  fs.mkdirSync(busMessagesDir(root), { recursive: true })
-  fs.writeFileSync(path.join(busMessagesDir(root), '.gitkeep'), '')
+  seed(dir)
 
   // 🔴 고아 브랜치는 **자기 트리의 `.gitattributes` 만** 본다. 저장소 루트에
   //    있는 것은 여기 안 닿으므로, 심어 두지 않으면 Windows(`core.autocrlf=true`)
-  //    에서 쪽지가 CRLF 로 체크아웃된다. 2026-08-26 에 실제로 그랬고, 머리말
+  //    에서 파일이 CRLF 로 체크아웃된다. 2026-08-26 에 실제로 그랬고, 머리말
   //    파서가 `\r` 에 걸려 **쪽지가 목록에서 조용히 사라졌다.**
   //    파서도 함께 고쳤지만(`tools/bus.mjs`) 바이트가 플랫폼마다 달라지는 것
   //    자체를 막는 편이 낫다 — 해시도, diff 도, 파서도 전부 같은 것을 본다.
   fs.writeFileSync(
     path.join(dir, '.gitattributes'),
-    '# 쪽지는 어느 OS 에서 만들어도 같은 바이트여야 한다.\n' +
+    '# 이 브랜치의 파일은 어느 OS 에서 만들어도 같은 바이트여야 한다.\n' +
       '# 저장소 루트의 .gitattributes 는 고아 브랜치에 닿지 않으므로 여기 따로 둔다.\n' +
       '* text=auto eol=lf\n',
   )
 
   if (remote) {
     git(['add', '-A'], { cwd: dir })
-    // --no-verify: 연결된 worktree 는 훅을 공유한다. 쪽지함은 사용자 코드가 아니다.
-    git(['commit', '--quiet', '--no-verify', '-m', 'axmap: bus init'], { cwd: dir })
-    const p = git(['push', '--quiet', remote, `HEAD:${BUS_BRANCH}`], { cwd: dir })
-    if (p.code !== 0) console.error(`경고: 쪽지함 push 실패 - ${(p.err ?? '').split('\n')[0]}`)
+    // --no-verify: 연결된 worktree 는 훅을 공유한다. 이 브랜치는 사용자 코드가 아니다.
+    git(['commit', '--quiet', '--no-verify', '-m', `axmap: ${branch} init`], { cwd: dir })
+    const p = git(['push', '--quiet', remote, `HEAD:${branch}`], { cwd: dir })
+    if (p.code !== 0) console.error(`경고: ${what} push 실패 - ${(p.err ?? '').split('\n')[0]}`)
   }
   return 'created'
 }
 
-function busSetupFailed(r) {
-  console.error(`경고: 쪽지함을 준비하지 못했습니다 - ${(r.err || r.out || '').split('\n')[0]}`)
-  return 'failed'
+function ensureBus(root) {
+  return ensureOrphan(root, {
+    branch: BUS_BRANCH, rel: BUS_REL, dir: busDir(root), what: '쪽지함',
+    seed: () => {
+      // git 은 빈 디렉터리를 추적하지 않는다. 쪽지가 0개인 동안에도 폴더가 살아 있게 한다.
+      fs.mkdirSync(busMessagesDir(root), { recursive: true })
+      fs.writeFileSync(path.join(busMessagesDir(root), '.gitkeep'), '')
+    },
+  })
+}
+
+function ensureUsers(root) {
+  return ensureOrphan(root, {
+    branch: USERS_BRANCH, rel: USERS_REL, dir: usersDir(root), what: '사람별 상태',
+    seed: () => {
+      fs.mkdirSync(usersFilesDir(root), { recursive: true })
+      fs.writeFileSync(path.join(usersFilesDir(root), '.gitkeep'), '')
+    },
+  })
+}
+
+/**
+ * 쪽지함만 준비한다. **장부는 건드리지 않는다.**
+ *
+ * 🔴 왜 `init` 을 부르지 않고 이 명령이 따로 있는가. 쪽지를 **읽는** 길에서
+ *    부를 자리가 필요해서다. `init` 은 장부(`axmap/claims`)까지 만들고 그것을
+ *    원격에 push 한다 — "내 쪽지 좀 보자" 가 남의 저장소에 **선점 장부**를
+ *    만드는 일이 되면 안 된다. 쪽지 브랜치는 쪽지함이 원래 사는 곳이므로
+ *    거기까지는 간다. 선을 긋는 자리는 "읽으려는 그것" 과 "그 밖의 것" 사이다.
+ *
+ *    그래서 `tools/bus.mjs` 는 쪽지함이 없을 때 이 명령을 부른다. 만드는 코드를
+ *    저쪽에 복사하지 않는 이유는 사본이 곧 두 벌이고, 두 벌은 반드시 어긋나기
+ *    때문이다 — 이 저장소가 팀 사본을 걷어낸 것과 같은 이유다.
+ */
+function cmdBusRepair() {
+  const root = repoRoot()
+  // .axmap 을 손으로 지웠어도 git 쪽에 worktree 등록이 남아 add 가 실패한다.
+  git(['worktree', 'prune'], { cwd: root })
+  const r = ensureBus(root)
+  if (r === 'failed') process.exit(1)
+  console.log(
+    r === 'ready'
+      ? `쪽지함이 이미 있습니다: ${BUS_REL}`
+      : `쪽지함을 만들었습니다: ${BUS_REL}  (${BUS_BRANCH})`,
+  )
+}
+
+/** 사람별 상태만 준비한다. `bus-repair` 와 같은 이유로 따로 있다. */
+function cmdUsersRepair() {
+  const root = repoRoot()
+  git(['worktree', 'prune'], { cwd: root })
+  const r = ensureUsers(root)
+  if (r === 'failed') process.exit(1)
+  console.log(
+    r === 'ready'
+      ? `사람별 상태가 이미 있습니다: ${USERS_REL}`
+      : `사람별 상태를 만들었습니다: ${USERS_REL}  (${USERS_BRANCH})`,
+  )
 }
 
 function cmdInit(flags = {}) {
@@ -1186,6 +1280,7 @@ function cmdInit(flags = {}) {
     //    돌린 사람은 장부만 있고 쪽지함이 없다. 그 사람들이 다시 init 을 불렀을 때
     //    받아 가는 자리가 여기다.
     if (ensureBus(root) === 'created') console.log(`쪽지함을 만들었습니다: ${BUS_REL}  (${BUS_BRANCH})`)
+    if (ensureUsers(root) === 'created') console.log(`사람별 상태를 만들었습니다: ${USERS_REL}  (${USERS_BRANCH})`)
     return
   }
   if (fs.existsSync(dir) && fs.readdirSync(dir).length) {
@@ -1262,8 +1357,9 @@ function cmdInit(flags = {}) {
   }
 
   ensureBus(root)
+  ensureUsers(root)
 
-  console.log(`준비 완료. 장부 ${LEDGER_BRANCH} · 쪽지함 ${BUS_BRANCH}`)
+  console.log(`준비 완료. 장부 ${LEDGER_BRANCH} · 쪽지함 ${BUS_BRANCH} · 사람별 상태 ${USERS_BRANCH}`)
 }
 
 // ---------------------------------------------------------------------------
@@ -1664,7 +1760,16 @@ function collectCodeCommits(root, range) {
   for (const line of log.out ? log.out.split(NL) : []) {
     if (!line) continue
     const [sha, author, ct, subject] = line.split(NUL)
-    const files = git(['show', '--no-renames', '--name-only', '--format=', sha], { cwd: root }).out
+    // 🔴 `-c core.quotepath=false` 가 없으면 **한글 경로가 claim 과 안 맞는다.**
+    //    git 은 기본으로 ASCII 밖 글자를 역슬래시 + 8진수 세 자리로 감싸 내보낸다.
+    //    그 문자열은 장부에 적힌 경로와 절대 같아질 수 없고, 검사는 "안 겹친다" 로
+    //    **조용히 통과**한다 - 락에서 최악인 fail-open 이다.
+    //    팀 CI 가 잡 안에서 `git config core.quotepath false` 로 막고 있었다.
+    //    우회는 그 잡에만 걸린다. 부르는 자리에서 못을 박는다 (verify 와 같은 방식).
+    const files = git(
+      ['-c', 'core.quotepath=false', 'show', '--no-renames', '--name-only', '--format=', sha],
+      { cwd: root },
+    ).out
     out.push({
       sha,
       author,
@@ -2186,6 +2291,9 @@ const HELP = `axmap - AI 에이전트 작업 선점 프로토콜
   axmap setup                        이 PC 와 이 저장소에 axMap 을 붙인다 (첫 한 번)
                                         [--remote <이름|git 주소>] [--name] [--dry-run]
   axmap init                         장부(고아 브랜치 + worktree)를 준비한다
+  axmap bus-repair                   쪽지함만 준비한다 (장부는 안 건드린다)
+                                     쪽지를 읽다가 "쪽지함을 못 열었습니다" 를 봤을 때
+  axmap users-repair                 사람별 상태(어디까지 읽었나)만 준비한다
   axmap claim <경로...>              경로를 선점한다  [--task --intent --ttl 30m]
   axmap release [경로...]            반납한다 (경로 생략 시 전부)
   axmap renew                        TTL 을 연장한다  [--ttl 30m]
@@ -2197,6 +2305,7 @@ const HELP = `axmap - AI 에이전트 작업 선점 프로토콜
   axmap doctor                       이 PC 에서 선점이 실제로 도는지 점검  [--json]
   axmap hook install                 verify 를 pre-commit 훅으로 설치
   axmap update                       새 버전이 있는지 묻는다 (바꾸지는 않는다)
+  axmap --version                    지금 도는 판 번호를 찍는다 (아래 version 명령과 다르다)
 
 딸린 프로그램 — 예전에는 파일 경로로 불렀다. 이제 이름으로 부른다.
 인자는 그대로 전달되고, 각각의 사용법은 그 프로그램이 답한다.
@@ -2219,6 +2328,27 @@ const HELP = `axmap - AI 에이전트 작업 선점 프로토콜
 const { positional, flags } = parseArgs(process.argv.slice(2))
 const [cmd, ...rest] = positional
 
+/**
+ * 🔴 `--version` 은 명령이 아니라 **깃발**이라 아래 switch 에 안 걸린다.
+ *    그대로 default 로 떨어져 **도움말을 찍고 종료 코드 0** 을 냈다. 팀 CI 가
+ *    "어느 판이 돌았는지" 를 남기려고 넣은 줄이 조용히 쓸모없어졌고, 0 이라
+ *    아무도 못 알아챘다 (실측 2026-09-01, 팀 저장소 .gitlab-ci.yml eb3b56d).
+ *
+ * 🔴 `version` **명령과는 다른 것을 답한다.** 저쪽(tools/version.mjs)은
+ *    `process.cwd()` 의 git 태그를 읽는 도구라, 남의 저장소에서 부르면 그
+ *    저장소의 버전이 나온다. 여기가 답해야 하는 것은 "지금 도는 axMap 이 몇
+ *    판인가" 이고, 그 답은 설치본 자기 package.json 에만 있다.
+ *
+ *    못 읽으면 죽는다. 모르는 것을 빈 줄로 내면 CI 로그에는 "판을 확인했다" 는
+ *    흔적만 남고 실제로는 아무것도 확인되지 않는다.
+ */
+if (boolFlag(flags.version, 'version') && !cmd) {
+  const v = selfVersion()
+  if (!v) die('버전을 알 수 없습니다 - package.json 이 없는 사본입니다.')
+  console.log(v)
+  process.exit(0)
+}
+
 switch (cmd) {
   // 이름을 경로로 바꿔 주는 것들 (RUNNERS). 인자는 손대지 않고 그대로 간다.
   case 'setup':
@@ -2238,6 +2368,12 @@ switch (cmd) {
   case 'init':
     cmdInit(flags)
     break
+  case 'bus-repair':
+    cmdBusRepair()
+    break
+  case 'users-repair':
+    cmdUsersRepair()
+    break
   case 'claim':
     cmdClaim(rest, flags)
     break

package/mcp/server.mjs

@@ -460,7 +460,7 @@ const TOOLS = [
     inputSchema: {
       type: 'object',
       properties: {
-        to: { type: 'string', description: '받는 에이전트 이름. 생략하면 모두에게.' },
+        to: { type: 'string', description: '받는 사람. 이름도 이메일도 됩니다. 여럿이면 쉼표로 (예: "bob,carol"). 생략하면 모두에게.' },
         subject: { type: 'string', description: '한 줄 제목' },
         body: { type: 'string', description: '본문 (마크다운)' },
       },
@@ -878,7 +878,11 @@ function dispatch(name, args = {}) {
     case 'ax_send': {
       if (!args.subject || !args.body) return { ok: false, text: 'subject 와 body 가 필요합니다.' }
       const a = ['post', '--subject', String(args.subject)]
-      if (args.to) a.push('--to', String(args.to))
+      // 여럿에게 한 통을 보낼 수 있다. 문자열로 `"a,b"` 를 줘도, 배열로 줘도 같다 —
+      // 같은 내용을 두 번 보내면 답장이 두 갈래로 갈려 대화가 쪼개진다.
+      for (const t of (Array.isArray(args.to) ? args.to : (args.to ? [args.to] : []))) {
+        if (String(t).trim()) a.push('--to', String(t).trim())
+      }
       const r = bus(a, String(args.body))
       return {
         ok: r.code === 0,

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.0.0",
+  "version": "1.0.3",
   "//private": "🔴 여기 있던 \"private\": true 를 2026-08-28 에 지웠다. 그 줄이 있는 동안 npm publish 는 거부됐다. 되돌리려면 다시 넣으면 되지만, 이미 올라간 버전은 그래도 안 사라진다 — npm 은 같은 번호를 덮어쓰지 못하고 삭제도 72시간 안에만 된다. 즉 이 줄을 되살리는 것은 '앞으로 안 올린다' 는 뜻이지 '올린 것을 없앤다' 는 뜻이 아니다.",
   "//publishConfig": "axmap-cli 는 스코프가 없어서 기본이 이미 공개다. 즉 지금은 없어도 된다. 그래도 남겨 두는 이유: 나중에 @조직/axmap 처럼 스코프를 붙이는 날 이 줄이 없으면 publish 가 '유료 플랜이 필요하다'는 엉뚱한 말로 실패한다.",
   "publishConfig": {

package/tools/bus.mjs

@@ -30,7 +30,7 @@
  *    에 한 줄로 적는 편이 빠르다 — 그건 `axmap status` 로 바로 보인다.
  */
 
-import { execFileSync } from 'node:child_process'
+import { execFileSync, spawnSync } from 'node:child_process'
 import fs from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
@@ -114,6 +114,79 @@ function gitBus(argv, opts = {}) {
 
 const busReady = () => BUS_WT !== null && fs.existsSync(path.join(BUS_WT, '.git'))
 
+/**
+ * 쪽지함을 못 연 이유. `null` 이면 정상이다.
+ *
+ * 🔴 이 변수가 있는 이유는 하나다 — **"쪽지 없음" 과 "못 읽었음" 을 다른 문장으로
+ *    내기 위해서다.**
+ *
+ *    2026-09-03 실측: 원격 `axmap/bus` 에 쪽지 129건이 있고 그중 오늘 온 것이
+ *    있는데, 이 체크아웃에 worktree 가 없어서 `pull()` 이 **fetch 를 한 번도 안
+ *    하고 조용히 반환**했다. 읽는 자리는 옛 함(`docs/bus`)으로 떨어졌고 거기 있던
+ *    8월 것은 이미 읽음이라 화면에 나온 답은 `쪽지 없음.` 이었다. 경고도 없었다.
+ *
+ *    **보내기는 같은 상황에서 제대로 거부했다** (아래 `post`). 쓰기는 막고 읽기만
+ *    통과시킨 것이다. 락 시스템에서 최악의 실패는 거부해야 할 것을 조용히
+ *    통과시키는 것이고(CLAUDE.md 「애매하면 거부한다」), 쪽지함에서는 **못 읽은
+ *    것을 "없다" 고 답하는 것**이 바로 그 자리다. 잘못 막으면 사람이 메시지를
+ *    읽고 고치면 되지만, 조용히 없다고 하면 아무도 잘못됐다는 것을 모른다.
+ */
+let busProblem = null
+
+/** 옛 함(`docs/bus`)에서만 읽었는가. 새 함을 못 연 채로 성공한 것처럼 보이지 않게 한다. */
+let readFromLegacyOnly = false
+
+/**
+ * 쪽지함을 연다. **없으면 만든다. 만들었으면 만들었다고 말한다.**
+ *
+ * 🔴 만드는 코드를 여기에 복사하지 않는다. `bin/axmap.mjs` 의 `ensureBus` 하나뿐이고
+ *    이 함수는 그것을 `bus-repair` 로 부른다. 사본을 두면 두 벌이 되고, 두 벌은
+ *    반드시 어긋난다 — 이 저장소가 팀 사본을 걷어낸 것과 같은 이유다.
+ *
+ * 🔴 만들고 나서 **조용히 넘어가지 않는다.** 이 버그의 본질이 "말없이 넘어간 것"
+ *    이라, 자동으로 만들어 놓고 또 말없이 넘어가면 증상만 다른 같은 병이 된다.
+ *    stdout 이 아니라 stderr 로 낸다 — 목록을 파이프로 넘겨도 사람 눈에는 남는다.
+ */
+function openBus() {
+  if (process.env.AXMAP_BUS_DIR) return true // 대상이 명시됐으면 물을 것이 없다
+  if (busReady()) return true
+  if (BUS_WT === null) {
+    busProblem = '이 저장소를 찾지 못했습니다.'
+    return false
+  }
+
+  const r = spawnSync(process.execPath, [path.join(ROOT, 'bin', 'axmap.mjs'), 'bus-repair'], {
+    cwd: REPO, encoding: 'utf8', windowsHide: true,
+  })
+  if (busReady()) {
+    console.error(`쪽지함이 없어서 만들었습니다: ${path.join('.axmap', 'bus')}  (${BUS_BRANCH})`)
+    return true
+  }
+  busProblem = (r.stderr ?? '').trim() || (r.stdout ?? '').trim() || '알 수 없는 이유로 실패했습니다.'
+  return false
+}
+
+/**
+ * 쪽지함을 못 열었다는 것을 사람이 볼 수 있게 낸다.
+ *
+ * 🔴 **"없음" 이라고 말하지 않는다.** 받은 쪽지가 없는 것이 아니라 확인을 못 한
+ *    것이고, 둘은 사람이 해야 할 일이 정반대다.
+ */
+function reportBusProblem() {
+  // 🔴 순서가 뜻이다. **무슨 일인지 먼저, 이유는 그다음.** 이유부터 내면 그것이
+  //    여러 줄일 때 안내가 아래로 밀려서, 급한 사람이 첫 줄만 보고 넘어간다.
+  const why = busProblem
+    .replace(/^경고: /, '')
+    .split('\n')
+    .map((s, i) => (i === 0 ? s : `        ${s.trim()}`))
+    .join('\n')
+  console.error(
+    '쪽지함을 못 열었습니다 — 받은 쪽지가 없는 것이 아니라 확인을 못 한 것입니다.\n' +
+      `\n  이유: ${why}\n` +
+      '\n  고치기:  axmap bus-repair      (MCP 에서는 ax_init)',
+  )
+}
+
 /**
  * 원격의 쪽지를 받아온다. **실패해도 죽지 않는다** — 못 받은 것은 위험이 아니라
  * 지연이다. 장부(`syncLedger`)가 같은 자리에서 죽는 것과 정반대이고, 그 차이의
@@ -129,7 +202,10 @@ const busReady = () => BUS_WT !== null && fs.existsSync(path.join(BUS_WT, '.git'
  *    쪽지 worktree(`.axmap/bus`) **바깥**이라 고아 브랜치에 섞이지 않는다.
  */
 function pull() {
-  if (!busReady()) return
+  // 🔴 예전에는 여기가 `if (!busReady()) return` 이었다. 쪽지함이 없으면 **fetch 를
+  //    한 번도 안 하고 조용히 반환**했고, 그것이 "쪽지 없음" 으로 보였다.
+  //    이제는 열어 보고, 못 열면 그 사실을 `busProblem` 에 남긴다.
+  if (!openBus()) return
   // 🔴 주기는 **설정에서 온다.** `--throttle` 이 1순위(부르는 쪽이 그 자리에서
   //    정한다), 없으면 `AXMAP_BUS_POLL`(초), 그것도 없으면 0 = 매번 받아온다.
   //
@@ -159,6 +235,30 @@ const cmd = args[0]
 const flag = (n, d = null) => { const i = args.indexOf(n); return i < 0 ? d : args[i + 1] }
 const has = (n) => args.includes(n)
 
+/**
+ * 같은 이름의 옵션이 여러 번 와도 전부 모은다. `flag` 는 첫 번째만 낸다.
+ *
+ * 🔴 쪽지 216통을 세어 보니 **같은 제목이 초 단위로 두 번씩 나간 것**이 여러
+ *    건이었다. 같은 내용을 두 사람에게 보내려면 두 번 보내는 수밖에 없어서다.
+ *    그러면 답장이 두 갈래로 갈려 대화가 쪼개지고, 나중에 읽는 사람은 어느
+ *    쪽이 이어진 이야기인지 모른다. 그래서 사람들이 관계없는 사람까지 읽는
+ *    전체공지로 도망쳤다 — 48통이 그렇게 나갔다.
+ */
+const flagAll = (n) => {
+  const out = []
+  for (let i = 0; i < args.length; i++) if (args[i] === n && args[i + 1] != null) out.push(args[i + 1])
+  return out
+}
+
+/** 받는 사람 목록. `--to a --to b` 도, `--to "a,b"` 도 같은 것으로 본다. */
+const recipientArgs = () => flagAll('--to')
+  .flatMap((s) => String(s).split(','))
+  .map((s) => s.trim())
+  .filter(Boolean)
+
+/** 쪽지 하나의 받는 사람들. 예전 쪽지는 값이 하나라 그대로 한 개짜리 목록이 된다. */
+const recipientsOf = (m) => String(m.to ?? 'all').split(',').map(norm).filter(Boolean)
+
 /**
  * 나는 누구인가. 선점 프로토콜과 **같은 값**을 쓴다 — 두 이름을 두면 갈린다.
  *
@@ -191,6 +291,186 @@ function me() {
   process.exit(1)
 }
 
+/**
+ * 사람의 주소는 **이메일**이다. 이름은 그 사람을 부르는 여러 별칭 중 하나일 뿐이다.
+ *
+ * 🔴 왜 이름이 아니라 이메일인가. 실측(2026-09-05, 팀 저장소 최근 300커밋):
+ *
+ *      사람 6명  →  git 이름 11개  →  git 이메일 6개
+ *
+ *    한 사람이 `yeaseung lee` · `yeaseung-lee` · `이예승` 셋으로 커밋한다.
+ *    **이름은 갈리는데 이메일은 안 갈린다** — 표기는 바꿔도 이메일은 안 바꾼다.
+ *
+ *    그래서 이름을 주소로 쓰면, 보낸 쪽은 "보냈습니다" 를 보고 받는 쪽은
+ *    "쪽지 없음" 을 본다. **양쪽 다 오류가 없어서 아무도 실패를 못 본다.**
+ *    실제로 216통 중 존재하지 않는 이름으로 간 것이 1통 있었고, 보낸 사람이
+ *    13분 뒤에 눈치채고 다시 보냈다.
+ *
+ *    그리고 이 저장소는 **이미 한쪽에서 옳게 하고 있었다** — 투표권자 명단
+ *    (`governance/policy.json`)은 처음부터 이메일로 사람을 가른다. 쪽지함과
+ *    선점만 이름을 썼다. 한 저장소가 두 개의 주소 체계를 갖고 있던 것이다.
+ */
+const norm = (s) => String(s ?? '').trim().toLowerCase()
+
+/** 이 저장소를 쓰는 사람들. `{ email, names:Set }` 의 목록. 한 프로세스에서 한 번만 센다. */
+let rosterCache = null
+
+function roster() {
+  if (rosterCache) return rosterCache
+  const byEmail = new Map()
+
+  /**
+   * 🔴 **이름 하나는 사람 하나에게만 붙는다. 먼저 붙은 쪽이 이긴다.**
+   *
+   *    이 줄이 없으면 어긋난 쪽지 한 통이 두 사람을 영구히 합친다. 실제로 그랬다 —
+   *    도구 이름은 `alice` 인데 git 이메일이 `bob@x.com` 인 쪽지가 하나 있었고,
+   *    그 뒤로 `alice` 가 bob 의 이름이 됐다. 그러면 bob 은 alice 가 보낸 쪽지를
+   *    **자기가 보낸 것으로 보고 안 읽음에서 지운다.**
+   *
+   *    이름이 어긋나 쪽지가 묻히는 것이 이 판에서 고치려던 바로 그 증상인데,
+   *    신원을 합치는 방식으로 고치면 **자리만 바꿔서 되살아난다.**
+   *
+   *    순서가 곧 우선순위다: git 이력(1) → 쪽지 머리말(2) → 적어 둔 별칭(3).
+   *    git 이력이 가장 믿을 만하다 — 사람이 자기 PC 에 직접 설정한 값이다.
+   */
+  const nameOwner = new Map()
+  const add = (email, name) => {
+    const e = norm(email)
+    if (!e || !e.includes('@')) return
+    if (!byEmail.has(e)) byEmail.set(e, { email: e, names: new Set() })
+    const n = norm(name)
+    if (!n) return
+    const owner = nameOwner.get(n)
+    if (owner && owner !== e) return          // 이미 남의 이름이다. 합치지 않는다
+    nameOwner.set(n, e)
+    byEmail.get(e).names.add(n)
+  }
+
+  // 1) git 이력 — 이 저장소에서 실제로 일한 사람이 곧 명단이다. 별도 파일도,
+  //    별도 브랜치도 필요 없다. **아무 저장소에서나 성립한다**는 것이 중요하다.
+  try {
+    const out = execFileSync('git', ['log', '--all', '--format=%ae\t%an', '-n', '5000'], {
+      cwd: REPO ?? process.cwd(), encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+    })
+    for (const line of out.split('\n')) {
+      const [e, n] = line.split('\t')
+      add(e, n)
+    }
+  } catch { /* 저장소가 아니거나 이력이 없다. 아래 2)로 채운다 */ }
+
+  // 2) 쪽지를 보낸 적이 있는 사람. 커밋은 없지만 쪽지는 쓴 사람이 실제로 있다
+  //    (기획·디자인). 여기서 안 주우면 그 사람에게는 답장을 못 보낸다.
+  try {
+    for (const m of readAll()) if (m.fromEmail) add(m.fromEmail, m.from)
+  } catch { /* 쪽지함을 못 열었을 뿐이다. 1)만으로도 명단은 선다 */ }
+
+  // 3) 적혀 있는 별칭. **git 이 모르는 이름이 여기 들어온다.**
+  //
+  //    🔴 여기서 받아오는 것이 중요하다. 예전에는 안 읽음 표시를 볼 때만 받아왔고,
+  //       명단은 그 자리를 안 거쳤다. 그래서 **별칭 앞으로 온 쪽지가 그 사람에게
+  //       안 갔다** — 보낸 쪽 PC 에는 별칭이 있고 받는 쪽 PC 에는 없었기 때문이다.
+  //       이름이 어긋나서 쪽지가 묻히는 것, 정확히 고치려던 그 증상이 자리만
+  //       바꿔서 되살아난 것이었다.
+  pullUsers()
+  //
+  //    🔴 실측에서 커밋 로그에 없는 이름이 넷 있었다 — codex-jinmiri · jaehyeon-2 ·
+  //       codex · rleaderjoon-desktop. 사람이 아니라 그 사람이 띄운 AI 도구이거나
+  //       다른 PC 다. git 은 이것을 알 방법이 없으므로 적어 두는 자리가 필요하다.
+  try {
+    const dir = USERS_WT ? path.join(USERS_WT, 'users') : null
+    for (const f of (dir ? fs.readdirSync(dir) : [])) {
+      if (!f.endsWith('.json')) continue
+      const st = JSON.parse(fs.readFileSync(path.join(dir, f), 'utf8'))
+      const email = f.replace(/\.json$/, '')
+      add(email, st.name)
+      for (const a of (st.aliases ?? [])) add(email, a)
+    }
+  } catch { /* 사람별 상태가 아직 없다. 1)·2)만으로도 명단은 선다 */ }
+
+  rosterCache = [...byEmail.values()]
+  return rosterCache
+}
+
+/**
+ * 이 사람을 가리키는 **모든 주소**. 이름으로 물어도 이메일로 물어도 같은 답이 온다.
+ *
+ * 명단에 없으면 물어본 것 그대로 한 개짜리 집합을 낸다 — 모르는 사람을 아는 척
+ * 하지 않는다. 그 판단은 부르는 쪽(`post`)이 한다.
+ */
+function addressesOf(who) {
+  const w = norm(who)
+  const p = roster().find((x) => x.email === w || x.names.has(w))
+  return p ? new Set([p.email, ...p.names]) : new Set([w])
+}
+
+/**
+ * 아는 주소 중 이것과 **거의 같은 것**들. 오타를 잡기 위한 것이지 검색이 아니다.
+ *
+ * 두 가지만 본다.
+ *   1. 한쪽이 다른 쪽의 앞부분이다  — `ahwlstjd` / `ahwlstjd57` (실제로 난 오타)
+ *   2. 글자 **하나** 차이다          — 손가락이 미끄러진 것
+ *
+ * 🔴 넓히지 않는다. 넓히면 남남인 이름끼리 "혹시 이것입니까" 가 뜨고, 그러면
+ *    사람은 그 물음을 안 읽게 된다. 안 읽히는 확인은 없는 확인이다.
+ *
+ *    두 글자까지 봤다가 `reader` 와 `sender` 가 걸렸다 — 여섯 글자에서 두 글자면
+ *    3분의 1이 다른 것이고, 그건 오타가 아니라 다른 낱말이다. 실제로 났던 오타는
+ *    거리가 아니라 **앞부분 일치**로 잡히므로 좁혀도 잃는 것이 없다.
+ */
+function nearMatches(who) {
+  const w = norm(who)
+  const all = roster().flatMap((p) => [p.email, ...p.names])
+  return all.filter((a) => {
+    if (a === w) return false
+    const [s, l] = a.length < w.length ? [a, w] : [w, a]
+    if (l.startsWith(s) && l.length - s.length <= 4) return true
+    return distance(w, a) <= 1
+  }).slice(0, 5)
+}
+
+/** 두 글자열을 같게 만드는 데 필요한 최소 편집 횟수 (Levenshtein). */
+function distance(a, b) {
+  const prev = Array.from({ length: b.length + 1 }, (_, i) => i)
+  for (let i = 1; i <= a.length; i++) {
+    let diag = prev[0]
+    prev[0] = i
+    for (let j = 1; j <= b.length; j++) {
+      const t = prev[j]
+      prev[j] = Math.min(prev[j] + 1, prev[j - 1] + 1, diag + (a[i - 1] === b[j - 1] ? 0 : 1))
+      diag = t
+    }
+  }
+  return prev[b.length]
+}
+
+/** 내 이메일. 없으면 null — 없다고 죽지는 않는다. 이름만으로도 지금까지처럼 돈다. */
+function myEmail() {
+  const v = process.env.AXMAP_AGENT_EMAIL
+  if (v && v.includes('@')) return norm(v)
+  try {
+    const e = execFileSync('git', ['config', 'user.email'], {
+      cwd: REPO ?? process.cwd(), encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim()
+    return e.includes('@') ? norm(e) : null
+  } catch { return null }
+}
+
+/**
+ * 나에게 온 쪽지인지 판정할 때 쓰는 내 주소 전부.
+ *
+ * 🔴 `AXMAP_AGENT` 로 붙인 이름도 넣는다. 실측에서 `codex-jinmiri`·`jaehyeon-2`
+ *    처럼 **커밋 로그에 없는 이름**이 넷 있었다. 사람이 아니라 그 사람이 띄운
+ *    AI 도구라 git 이 모른다. 그것도 나다.
+ */
+function myAddresses() {
+  const s = new Set()
+  const e = myEmail()
+  if (e) for (const a of addressesOf(e)) s.add(a)
+  s.add(norm(me()))
+  if (process.env.AXMAP_AGENT) s.add(norm(process.env.AXMAP_AGENT))
+  return s
+}
+
 /**
  * 읽음 표시 — 규격은 `docs/SPEC.md` §2「읽음 표시」다. 여기와 `bin/axmap.mjs`
  * 의 `unreadNotes` 가 **같은 파일을 같은 규칙으로** 본다. 규칙이 한 줄이라
@@ -199,11 +479,94 @@ function me() {
  * 🔴 장부에 넣지 않는다. 읽었는지는 나만의 상태라 남과 합의할 필요가 없고,
  *    장부에 쓰면 쪽지를 볼 때마다 push 경합이 생긴다.
  */
+/**
+ * 옛 자리 — **이 PC 안의 파일 하나.** 읽기만 한다. 새 자리로 옮기는 재료다.
+ *
+ * 🔴 여기 있었기 때문에 **PC 를 바꾸면 전부 다시 안 읽음**이 됐다. 쪽지 본문은
+ *    고아 브랜치로 모두가 공유하는데, 읽었다는 사실만 그 PC 에 갇혀 있었다.
+ *    다시 clone 하면 사라지고, 같은 사람이 도구를 둘 띄우면 각자 다른 상태를 봤다.
+ */
 const SEEN_FILE = REPO ? path.join(REPO, '.axmap-bus-seen.json') : null
 
+/** 새 자리 — 고아 브랜치 `axmap/users` 의 worktree. 사람마다 파일 하나. */
+const USERS_WT = REPO ? path.join(REPO, '.axmap', 'users') : null
+const USERS_BRANCH = 'axmap/users'
+const usersReady = () => USERS_WT !== null && fs.existsSync(path.join(USERS_WT, '.git'))
+
+function gitUsers(argv, opts = {}) {
+  try {
+    return {
+      code: 0,
+      out: execFileSync('git', argv, {
+        cwd: USERS_WT, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'], ...opts,
+      }).trim(),
+    }
+  } catch (e) { return { code: e.status ?? 1, out: '', err: String(e.stderr ?? e.message) } }
+}
+
+/**
+ * 사람별 상태를 연다. **못 열어도 죽지 않고, 말하지도 않는다.**
+ *
+ * 🔴 실패 방침이 쪽지함과 **정반대**다. 쪽지함은 못 읽으면 큰 소리로 말해야 한다 —
+ *    거기서 조용하면 **온 쪽지를 없다고 답하게** 되기 때문이다. 여기서 조용하면
+ *    **이미 읽은 쪽지가 한 번 더 뜰** 뿐이다.
+ *
+ *    즉 두 실패의 방향이 다르다. 하나는 **덜 보여주는 쪽**으로 틀리고 하나는
+ *    **더 보여주는 쪽**으로 틀린다. 더 보여주는 실패는 사람이 알아서 넘긴다.
+ *    그래서 여기에 경고를 달면 쓸모없는 줄이 매번 뜨고, 그러면 진짜 경고까지
+ *    같이 안 읽히게 된다.
+ */
+function openUsers() {
+  if (usersReady()) return true
+  if (USERS_WT === null || process.env.AXMAP_BUS_DIR) return false
+  spawnSync(process.execPath, [path.join(ROOT, 'bin', 'axmap.mjs'), 'users-repair'], {
+    cwd: REPO, encoding: 'utf8', windowsHide: true,
+  })
+  return usersReady()
+}
+
+/** 이 사람의 파일 자리. **이메일이 정본**이고, 없는 사람만 이름으로 떨어진다. */
+function userKey(who) {
+  const w = norm(who)
+  const p = roster().find((x) => x.email === w || x.names.has(w))
+  return p ? p.email : w
+}
+
+const userFile = (who) => path.join(USERS_WT, 'users', `${userKey(who)}.json`)
+
+function readUserState(who) {
+  try { return JSON.parse(fs.readFileSync(userFile(who), 'utf8')) } catch { return {} }
+}
+
+/** 원격의 사람별 상태를 받아온다. 자주 물을 이유가 없어 느슨하게 맞춘다. */
+function pullUsers() {
+  if (!openUsers()) return
+  const stampFile = path.join(REPO, '.axmap', '.users-lastfetch')
+  // 🔴 60초. 쪽지함(기본 0초)보다 훨씬 느슨한 것은 **늦어도 손해가 없기 때문**이다.
+  //    늦으면 다른 PC 에서 읽은 것이 여기서 한 번 더 뜬다. 그뿐이다.
+  //    반대로 매번 물으면 도구 호출마다 통신이 한 번씩 더 붙는다 (실측 0.8초).
+  try {
+    if (Date.now() - fs.statSync(stampFile).mtimeMs < 60_000) return
+  } catch { /* 처음이다. 받아온다 */ }
+  const remote = gitUsers(['config', '--get', 'axmap.remote'], { cwd: REPO }).out || 'origin'
+  if (gitUsers(['fetch', '--quiet', remote, USERS_BRANCH]).code !== 0) return
+  gitUsers(['reset', '--hard', '--quiet', 'FETCH_HEAD'])
+  try { fs.writeFileSync(stampFile, '') } catch { /* 스탬프 실패는 치명적이지 않다 */ }
+}
+
 function readSeen(who) {
-  if (!SEEN_FILE) return ''
-  try { return JSON.parse(fs.readFileSync(SEEN_FILE, 'utf8'))[who] ?? '' } catch { return '' }
+  pullUsers()
+  const fromBranch = usersReady() ? (readUserState(who).seen ?? '') : ''
+  // 🔴 옛 자리도 함께 본다. **둘 중 더 나아간 쪽**을 쓴다.
+  //
+  //    안 그러면 이 판으로 올린 날 모두의 쪽지가 전부 "안 읽음" 으로 되살아난다.
+  //    수십 건이 한꺼번에 뜨면 사람은 그것을 배경으로 여기고 안 읽게 되는데,
+  //    그건 이 도구가 고치려던 바로 그 상태다.
+  let legacy = ''
+  if (SEEN_FILE) {
+    try { legacy = JSON.parse(fs.readFileSync(SEEN_FILE, 'utf8'))[who] ?? '' } catch { /* 없다 */ }
+  }
+  return fromBranch > legacy ? fromBranch : legacy
 }
 
 /**
@@ -215,14 +578,56 @@ function readSeen(who) {
  *    한쪽이 질 수 있는데, 지는 쪽의 손해는 "한 번 더 뜬다" 뿐이라 잠그지 않는다.
  */
 function markSeen(who, id) {
-  if (!SEEN_FILE || !who || !id) return
+  if (!who || !id) return
+  // 옛 자리에도 계속 쓴다. 아직 옛 판을 쓰는 PC 가 같은 저장소에 있을 수 있고,
+  // 그쪽에서는 이 자리만 읽는다. 새 판이 다 퍼지면 이 줄은 지운다.
+  if (SEEN_FILE) {
+    try {
+      let all = {}
+      try { all = JSON.parse(fs.readFileSync(SEEN_FILE, 'utf8')) } catch { /* 처음이다 */ }
+      if ((all[who] ?? '') < id) {
+        all[who] = id
+        fs.writeFileSync(SEEN_FILE, JSON.stringify(all, null, 2) + '\n')
+      }
+    } catch { /* 조용히 */ }
+  }
+
+  if (!openUsers()) return
   try {
-    let all = {}
-    try { all = JSON.parse(fs.readFileSync(SEEN_FILE, 'utf8')) } catch { /* 처음이다 */ }
-    if ((all[who] ?? '') >= id) return           // 뒤로 가지 않는다
-    all[who] = id
-    fs.writeFileSync(SEEN_FILE, JSON.stringify(all, null, 2) + '\n')
-  } catch { /* 조용히 */ }
+    const f = userFile(who)
+    const cur = readUserState(who)
+    if ((cur.seen ?? '') >= id) return          // 뒤로 가지 않는다
+    fs.mkdirSync(path.dirname(f), { recursive: true })
+
+    // 🔴 **별칭은 저절로 적힌다.** 손으로 관리하게 하면 아무도 안 한다.
+    //
+    //    지금 쓰고 있는 이름이 이메일도 아니고 git 이 아는 이름도 아니면, 그것은
+    //    이 사람이 띄운 도구의 이름이다 (codex-jinmiri · jaehyeon-2 처럼). 적어
+    //    두면 다음부터 그 이름으로 온 쪽지도 이 사람 것이 된다.
+    const known = addressesOf(who)
+    const now = norm(me())
+    const aliases = [...new Set([...(cur.aliases ?? []), ...(known.has(now) ? [] : [now])])]
+
+    // 이름도 같이 남긴다 — 파일 이름이 이메일이라 사람이 열었을 때 누구인지 보이게.
+    fs.writeFileSync(f, JSON.stringify({ ...cur, name: me(), aliases, seen: id }, null, 2) + '\n')
+
+    gitUsers(['add', '--', path.relative(USERS_WT, f).replace(/\\/g, '/')])
+    // --no-verify: 연결된 worktree 는 훅을 공유한다. 이 브랜치는 사용자 코드가 아니다.
+    gitUsers(['commit', '--quiet', '--no-verify', '-m', `seen: ${userKey(who)}`])
+
+    // 🔴 push 는 **60초에 한 번**만 시도한다. 커밋은 이 PC 안이라 싸지만 push 는
+    //    통신이고, 쪽지를 볼 때마다 붙으면 모든 도구 호출이 그만큼 느려진다.
+    //    늦게 가도 손해가 없다 — 다른 PC 에서 그 쪽지가 한 번 더 뜰 뿐이다.
+    const stamp = path.join(REPO, '.axmap', '.users-lastpush')
+    let due = true
+    try { due = Date.now() - fs.statSync(stamp).mtimeMs >= 60_000 } catch { /* 처음이다 */ }
+    if (due) {
+      const remote = gitUsers(['config', '--get', 'axmap.remote'], { cwd: REPO }).out || 'origin'
+      if (gitUsers(['push', '--quiet', remote, `HEAD:${USERS_BRANCH}`]).code === 0) {
+        try { fs.writeFileSync(stamp, '') } catch { /* 스탬프 실패는 치명적이지 않다 */ }
+      }
+    }
+  } catch { /* 조용히 — 못 찍으면 다음에 한 번 더 뜰 뿐이다 */ }
 }
 
 const stamp = (d) => d.toISOString().replace(/[-:]/g, '').replace(/\.\d+Z$/, 'Z')
@@ -230,11 +635,17 @@ const slug = (s) => s.toLowerCase().replace(/[^\w가-힣]+/g, '-').replace(/^-|-
 
 function readAll() {
   const found = []
+  let newBoxOpened = false
   for (const box of READ_BOXES) {
     let ns = []
     try { ns = fs.readdirSync(box).filter((f) => f.endsWith('.md')) } catch { continue }
+    if (box === BOX) newBoxOpened = true
     for (const f of ns) found.push({ box, f })
   }
+  // 🔴 옛 함(`docs/bus`)은 **읽기 전용 유산**이다. 새 함을 못 열었는데 옛 함이
+  //    읽히면 지금까지는 그것이 **성공한 것처럼** 보였다 — 8월 20일자 8건이
+  //    나오고 오늘 온 쪽지는 없는 것이 된다. 어느 함에서 읽었는지를 남긴다.
+  readFromLegacyOnly = !newBoxOpened && found.length > 0
   return found.map(({ box, f }) => {
     const text = fs.readFileSync(path.join(box, f), 'utf8')
     const head = {}
@@ -269,6 +680,24 @@ function stdin() {
 
 function post({ to, subject, body, replyTo = null }) {
   const from = me()
+  // 부르는 쪽이 하나를 주든 여럿을 주든 여기서는 목록 하나로 본다.
+  let tos = (Array.isArray(to) ? to : (to == null ? [] : [to])).map((s) => String(s).trim()).filter(Boolean)
+
+  // 🔴 대상을 안 주면 지금까지처럼 전체에게 간다. **바꾸지 않는다** — 바꾸면
+  //    어제 되던 것이 오늘 안 되는 변경이고, 그건 맨 앞자리 번호를 올리고 먼저
+  //    알린 뒤에 할 일이다 (MCP 의 ax_send 도 `to` 를 선택으로 두고 있다).
+  //
+  //    대신 **조용히 넘어가지는 않는다.** 옵션 하나를 빠뜨린 것과 전체에게
+  //    보내려는 것은 명령줄에서 생김새가 똑같다. 실제로 216통 중 48통이
+  //    전체공지였는데, 그중 몇이 의도한 것이었는지는 아무도 모른다.
+  if (!tos.length) {
+    console.error('※ 받는 사람을 주지 않았습니다 — 전체(all)에게 보냅니다.  한 사람에게 보내려면 --to <상대>')
+    tos = ['all']
+  }
+  if (tos.length > 1 && tos.some((t) => norm(t) === 'all')) {
+    console.error('※ all 이 섞여 있어 전체에게 보냅니다. 나머지 이름은 뜻이 없습니다.')
+    tos = ['all']
+  }
   if (!subject) { console.error('--subject 가 필요합니다.'); process.exit(1) }
   if (!body.trim()) { console.error('본문이 비었습니다 (stdin 으로 주세요).'); process.exit(1) }
   // 🔴 쪽지함이 없으면 **쓰지 않고 거부한다.**
@@ -286,12 +715,55 @@ function post({ to, subject, body, replyTo = null }) {
     )
     process.exit(1)
   }
+  // 🔴 **모르는 주소로는 안 보낸다.**
+  //
+  //    지금까지는 받는 사람 이름을 아무도 검사하지 않았다. 오타 하나면 그 쪽지는
+  //    아무에게도 안 가는데 보낸 쪽은 성공을 본다 — 실측에서 실제로 1통이
+  //    `ahwlstjd` (뒤의 `57` 이 빠진 이름)로 갔고 13분 뒤에야 발견됐다.
+  //
+  //    거부하는 쪽을 고른 이유는 이 저장소가 정한 것 그대로다 — 잘못 막으면
+  //    사람이 메시지를 읽고 고치면 되지만, 조용히 보내면 아무도 모른다.
+  //    다만 **처음 오는 사람**(커밋도 쪽지도 아직 없는 사람)은 오타와 생김새가
+  //    같으므로 빠져나갈 문을 둔다 — `--force`. 문이 없으면 사람은 시스템 밖으로
+  //    나가고, 그때는 흔적도 안 남는다.
+  for (const one of (has('--force') ? [] : tos)) {
+    if (norm(one) === 'all') continue
+    const known = roster().some((p) => p.email === norm(one) || p.names.has(norm(one)))
+    if (!known) {
+      const near = nearMatches(one)
+      if (near.length) {
+        // 🔴 **거부하는 것은 오타뿐이다.** 아는 이름과 한 글자 차이거나 그 이름의
+        //    앞부분이면 새 사람이 아니라 손이 미끄러진 것이다. 실측에서 실제로
+        //    `ahwlstjd` 로 갔다 — 뒤의 `57` 이 빠졌고, 13분 뒤에야 발견됐다.
+        console.error(
+          `받는 사람을 찾지 못했습니다: ${one}\n` +
+            `  혹시 이것입니까?  ${near.join('  ·  ')}\n\n` +
+            '  이 이름 그대로 보내려면:  --force',
+        )
+        process.exit(1)
+      }
+      // 🔴 **모르는 사람이라고 막지는 않는다.** 아직 커밋이 없는 사람이 실제로
+      //    있다 — 팀에 새로 온 사람에게 보내는 첫 쪽지가 정확히 그 모양이다.
+      //    여기서 막으면 정상적인 첫 연락마다 `--force` 를 치게 되고, 그러면
+      //    사람은 그것을 반사적으로 붙이게 되어 **오타 검사가 아무것도 못 잡는다.**
+      //    대신 보내는 순간 눈에 띄게 말한다 — 조용히 보내는 것과는 다르다.
+      console.error(`※ 이 저장소에서 처음 보는 이름입니다: ${one}  (그래도 보냅니다)`)
+    }
+  }
+
   fs.mkdirSync(BOX, { recursive: true })
   const now = new Date()
   const id = `${stamp(now)}-${from}-${slug(subject)}`
+  // 🔴 `from` 은 **이름 그대로** 둔다. 파일 이름에 들어가는 값이라 바꾸면 예전
+  //    쪽지와 형식이 갈린다. 대신 이메일을 한 줄 더 적는다 — 이름이 나중에
+  //    바뀌어도 **누구였는지는 남는다.** 이것이 명단을 세우는 재료가 된다.
+  const fromEmail = myEmail()
   const head = [
     `from: ${from}`,
-    `to: ${to ?? 'all'}`,
+    fromEmail ? `fromEmail: ${fromEmail}` : null,
+    // 여럿이면 쉼표로 잇는다. 하나면 예전 쪽지와 글자 그대로 같은 모양이 된다 —
+    // 형식을 새로 만들지 않으므로 옛 쪽지도 새 코드가 그대로 읽는다.
+    `to: ${tos.join(', ')}`,
     `at: ${now.toISOString()}`,
     `subject: ${subject}`,
     replyTo ? `replyTo: ${replyTo}` : null,
@@ -393,8 +865,18 @@ function list() {
   const all = readAll()
   const to = has('--mine') ? me() : flag('--to')
   const from = flag('--from')
-  let rows = all.filter((m) => (has('--all') || !to || m.to === to || m.to === 'all')
-    && (!from || m.from === from))
+
+  // 🔴 **한 사람에게는 주소가 여럿이다.** `--to yeaseung-lee` 로 물어도
+  //    `이예승` 앞으로 온 쪽지가 나와야 한다 — 같은 사람이기 때문이다.
+  //    이름 하나로만 맞춰 보던 것이 쪽지를 묻은 원인이었다.
+  //
+  //    `--mine` 일 때는 내 이메일·git 이름·AXMAP_AGENT 를 전부 나로 친다.
+  const toSet = to ? (has('--mine') ? myAddresses() : addressesOf(to)) : null
+  const fromSet = from ? addressesOf(from) : null
+
+  let rows = all.filter((m) => (has('--all') || !toSet
+      || recipientsOf(m).some((r) => r === 'all' || toSet.has(r)))
+    && (!fromSet || fromSet.has(norm(m.from)) || (m.fromEmail && fromSet.has(norm(m.fromEmail)))))
 
   // 🔴 `--unread` 는 자기 앞으로 온 것을 가릴 때만 뜻이 있다. 받는 사람이
   //    정해지지 않았는데 "안 읽음" 을 말하면 누구의 읽음인지가 없다.
@@ -416,10 +898,33 @@ function list() {
     //
     //    숫자가 둘이면 사람은 어느 쪽도 안 믿는다. 그 순간 알림은 배경이 되고,
     //    배경이 된 알림은 진짜 쪽지가 왔을 때도 안 읽힌다.
-    rows = rows.filter((m) => m.id > seen && m.from !== who)
+    // 🔴 `m.from !== who` 였다. 이름이 하나일 때만 맞는 비교다 — 내가 `이예승`
+    //    으로 커밋하고 `yeaseung-lee` 로 쪽지를 보냈으면, 내가 보낸 전체공지가
+    //    **내 안 읽은 쪽지로 다시 잡힌다.** 주소 전부와 견준다.
+    const mine = has('--mine') ? myAddresses() : addressesOf(who)
+    rows = rows.filter((m) => m.id > seen
+      && !mine.has(norm(m.from)) && !(m.fromEmail && mine.has(norm(m.fromEmail))))
   }
 
-  if (!rows.length) return has('--quiet-if-empty') ? undefined : console.log('쪽지 없음.')
+  // 🔴 **못 읽었으면 "없음" 이라고 답하지 않는다.** 이 세 줄이 이 파일에서 제일
+  //    중요하다. 나머지는 편의고 이것만이 사고를 막는다.
+  //
+  //    종료 코드를 0 이 아닌 것으로 낸다 — MCP 서버(`mcp/server.mjs`)는 이미
+  //    `ok: r.code === 0` 으로 갈라 "쪽지함을 읽지 못했습니다" 를 따로 내도록
+  //    되어 있었다. 읽기가 그 신호를 **한 번도 낸 적이 없었을** 뿐이다.
+  //
+  //    `--quiet-if-empty`(훅·배너)일 때만 0 으로 끝낸다. 훅에서 0 이 아니면
+  //    커밋이 막히는데, 쪽지를 못 읽은 것으로 커밋을 막는 것은 과하다.
+  //    **다만 말은 한다** — stderr 는 그 경우에도 그대로 나간다.
+  if (busProblem) {
+    reportBusProblem()
+    if (!has('--quiet-if-empty')) process.exit(1)
+    return
+  }
+  if (!rows.length) {
+    if (readFromLegacyOnly) console.error('※ 옛 쪽지함(docs/bus)만 읽었습니다 — 새 쪽지함은 비어 있습니다.')
+    return has('--quiet-if-empty') ? undefined : console.log('쪽지 없음.')
+  }
   for (const m of rows) {
     console.log(`${m.at?.slice(0, 16).replace('T', ' ')}  ${(m.from ?? '?').padEnd(18)} → ${(m.to ?? 'all').padEnd(18)} ${m.subject ?? ''}`)
     console.log(`    ${m.id}`)
@@ -444,6 +949,9 @@ function list() {
 function read(id) {
   pull()
   const m = readAll().find((x) => x.id === id || x.id.includes(id))
+  // 🔴 못 열었으면 "없는 쪽지" 라고 말하지 않는다. 목록과 같은 이유다 — 사람은
+  //    아이디를 잘못 적었다고 믿고 다시 치게 되는데, 몇 번을 쳐도 같은 답이 온다.
+  if (!m && busProblem) { reportBusProblem(); process.exit(1) }
   if (!m) { console.error(`없는 쪽지: ${id}`); process.exit(1) }
   console.log(`── ${m.subject}\n   ${m.from} → ${m.to}   ${m.at}\n`)
   console.log(m.body)
@@ -488,10 +996,14 @@ function seen() {
 }
 
 switch (cmd) {
-  case 'post': post({ to: flag('--to'), subject: flag('--subject'), body: stdin() }); break
+  case 'post': post({ to: recipientArgs(), subject: flag('--subject'), body: stdin() }); break
   case 'reply': {
     const target = args[1]
+    // 🔴 답장도 먼저 받아온다. 예전에는 받아오지 않고 찾아서, 원격에만 있는 쪽지에
+    //    답장하면 **"없는 쪽지"** 가 나왔다. 아이디를 잘못 적은 것과 구별이 안 된다.
+    pull()
     const src = readAll().find((x) => x.id === target || x.id.includes(target))
+    if (!src && busProblem) { reportBusProblem(); process.exit(1) }
     if (!src) { console.error(`없는 쪽지: ${target}`); process.exit(1) }
     post({ to: src.from, subject: flag('--subject') ?? `Re: ${src.subject}`, body: stdin(), replyTo: src.id })
     break
@@ -504,6 +1016,8 @@ switch (cmd) {
     console.log(`에이전트 쪽지함
 
   ${selfCmd()} post --to <상대> --subject "<제목>" < 본문.md
+                   --to 를 여러 번 주거나 "a,b" 로 여럿에게 한 통을 보냅니다
+                   --to 를 아예 안 주면 전체(all)에게 갑니다
   ${selfCmd()} list [--to <나>|--mine] [--from <상대>] [--all]
                    [--unread] [--no-mark] [--throttle <초>] [--quiet-if-empty]
   ${selfCmd()} read <아이디>

package/.claude/settings.local.json

@@ -1,32 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(sed -i 's|/\\\\*\\\\* 궤도 모드에서 허용하는 yaw 한계 \\(약 35°\\). cos 이 0.82 아래로 내려가지 않는다. \\\\*/\\\\nconst YAW_LIMIT = 0.62|X|' app/web/graph.js)",
-      "Bash(sed -i 's|const YAW_LIMIT = 0.62|const TILT_LIMIT = 0.62|; s|허용하는 yaw 한계|허용하는 기울기 한계 \\(yaw · pitch 공통\\)|' app/web/graph.js)",
-      "Bash(sed -i 's|인코딩은 인코딩이 아니다. cos\\(TILT_LIMIT\\)=0.82 이면 고리의 화면 반지름이\\\\n   \\\\* \\\\[0.82R, R\\\\] 안에 머물러 이웃 단계와 절대 겹치지 않는다.|X|' app/web/graph.js)",
-      "Bash(sed -n '/인코딩은 인코딩이 아니다/,+2p' app/web/graph.js)",
-      "Bash(sed -i 's|import { applyEdits, draft, editRecord } from|import { applyEdits, draft } from|' app/server.mjs)",
-      "Bash(sed -i 's|\"test\": \"node --test test/protocol.test.mjs test/model.test.mjs test/analyze.test.mjs\"|\"test\": \"node --test test/protocol.test.mjs test/model.test.mjs test/analyze.test.mjs test/features.test.mjs\"|' package.json)",
-      "Bash(npm test *)",
-      "Bash(sed -i 's|        .filter\\(\\(\\\\[t\\\\]\\) => t !== name \\\\&\\\\& !taken.has\\(t\\)\\)|        .filter\\(\\([t]\\) => t !== name \\\\&\\\\& !taken.has\\(t\\) \\\\&\\\\& !tooCommon\\(t\\)\\)|' app/lib/features.mjs)",
-      "Bash(node -e ' *)",
-      "Bash(npm run *)",
-      "Bash(export AXMAP_AGENT=claude-fix GIT_AUTHOR_NAME=claude-fix GIT_AUTHOR_EMAIL=claude-fix@local GIT_COMMITTER_NAME=claude-fix GIT_COMMITTER_EMAIL=claude-fix@local)",
-      "Bash(node bin/axmap.mjs claim app/web/app.js app/web/graph.js app/web/style.css --task fix-click-color --intent \"이름 클릭=강조/더블클릭=이름변경, 단계 없을 때 색 회귀 수정\" --actor agent)",
-      "Bash(sed 's/\\\\$$//')",
-      "Bash(python -)",
-      "Bash(sed -n '/import 를 뽑을 수 있는 언어 이름/,/^\\\\]\\)/p' app/lib/analyze.mjs)",
-      "Bash(export AXMAP_AGENT=janghyojoon)",
-      "Bash(node bin/axmap.mjs release)",
-      "Bash(echo \"// 테스트\")",
-      "Bash(git add *)",
-      "Bash(git commit *)",
-      "Bash(git reset *)",
-      "Bash(git checkout *)"
-    ]
-  },
-  "enabledMcpjsonServers": [
-    "axmap"
-  ],
-  "enableAllProjectMcpServers": true
-}