axmap-cli 0.0.1 → 0.2.0

package/.claude/commands/ax.md

@@ -1,13 +1,29 @@
 ---
-description: axMap — 지금 누가 어디를 잡고 있는지 보고, 내가 건드릴 곳이 비었는지 확인한다
+description: axMap — 지금 누가 어디를 잡고 있는지 본다. 경로를 주면 겹치는지도 확인한다
 ---
 
-`ax_status` 를 불러 지금 장부에 무엇이 들어 있는지 보여줘.
+인자: $ARGUMENTS (경로들. 비워도 된다)
 
-그 다음 이번 대화에서 내가 건드릴 것으로 보이는 경로에 대해 `ax_check` 를 불러
-겹치는 것이 있는지 확인하고, 결과를 한 문단으로 정리해줘.
+## 할 일
 
-겹치는 것이 있으면 **재시도하지 말고** 비어 있는 다른 영역을 제안해.
-같은 요청은 몇 번을 보내도 같은 답이 온다.
+1. `ax_status` 를 부른다. 장부에 무엇이 들어 있는지 그대로 보여준다.
+2. **인자로 경로를 받았을 때만** 그 경로들로 `ax_check` 를 부른다.
+3. 결과를 짧게 정리한다. 겹치면 **재시도하지 말고** 누가 왜 잡고 있는지와 함께
+   비어 있는 다른 곳을 제안한다. 같은 요청은 몇 번을 보내도 같은 답이 온다.
 
-$ARGUMENTS
+## 🔴 저장소를 뒤지지 않는다
+
+**인자가 없으면 `ax_status` 만 부르고 끝낸다.** 무엇을 건드릴지 추측하지 않는다.
+
+예전에는 이 명령이 *"이번 대화에서 건드릴 것으로 보이는 경로를 확인해라"* 라고
+시켰다. 그러면 에이전트는 추측하려고 저장소를 뒤진다 — 파일 목록, git 상태,
+문서 몇 개. **한 줄 확인하자고 대화 하나치 컨텍스트를 쓴다.** 그리고 그렇게
+추측한 경로는 대체로 틀린다. 정작 건드릴 파일은 일을 시작해 봐야 정해지기 때문이다.
+
+잡을 곳이 정해졌을 때 부르는 것이 맞다:
+
+```
+/ax frontend/src/pages/Trip.tsx
+```
+
+정해지지 않았으면 장부만 보면 된다. 그게 이 명령의 기본값이다.

package/CLAUDE.md

@@ -79,6 +79,28 @@ axmap claim <경로...> --task <작업ID> --intent "<한 줄 설명>"
 > 훅이 당신을 **다른 사람으로 보고 커밋을 막는다.** 커밋할 때도 같은 값을 준다:
 > `AXMAP_AGENT=<내-이름> git commit`
 
+> 🔴 **"세션마다 고유하게" 는 말이 아니라 검사다 (2026-08-28).**
+>
+> 같은 PC 에서 AI 도구 세션 두 개가 같은 저장소를 만졌다. 둘 다 이름을 안 주어
+> `git config user.name` 으로 떨어졌고, 장부에서 **한 사람**이 되었다.
+> 뒤에 온 claim 이 그냥 통과했고 — 레코드는 이름당 파일 하나다 — 앞 세션의
+> 작업·의도가 덮여 `status` 에 1건만 남았다. 두 세션이 같은 파일을 동시에 밀었다.
+>
+> 이제 claim 레코드에 **세션 id** 가 함께 적힌다(`--session` · `AXMAP_SESSION` ·
+> `CLAUDE_CODE_SESSION_ID` 순). 같은 이름인데 세션이 다르면 `claim` 과 `release` 를
+> **거부한다**(종료 코드 2). 레코드는 손대지 않으므로 앞 세션의 것이 사라지지 않는다.
+> 양쪽 중 하나라도 세션을 모르면 막지 않고 **알리기만 한다** — 모르는 것과 다른 것은
+> 다르고, 모른다고 막으면 세션 개념이 없는 셸에서 아무것도 못 하게 된다.
+>
+> 제대로 된 해법은 여전히 위 한 줄이다. **세션마다 `AXMAP_AGENT` 를 다르게 준다.**
+> 그래야 장부에서 둘로 갈라지고 겹침 검사가 실제로 돈다. `--takeover` 는 "저 세션이
+> 확실히 나 자신" 일 때만 쓰는 문이고, 붙여도 잡혀 있던 경로는 안 없어진다.
+
+> 🔴 **링크된 worktree**(`git worktree add` 로 옆에 펼친 폴더)**에서도 그대로 돈다.**
+> 장부는 메인 체크아웃에 **하나뿐**이고 링크된 worktree 는 그것을 본다
+> (`git rev-parse --git-common-dir` 로 찾는다). 그 안에 `.axmap/ledger` 를 또 만들지
+> 않는다 — 같은 저장소에 장부가 둘이면 락이 아니다.
+
 **어떤 파일이든 수정하기 전에 claim 이 먼저다.** 읽기만 할 때는 필요 없다.
 
 작업 범위가 확실치 않으면 **넓게 잡지 말고 좁게 시작해서 추가로 claim** 한다.
@@ -88,7 +110,7 @@ axmap claim <경로...> --task <작업ID> --intent "<한 줄 설명>"
 
 | 종료 코드 | 의미 | 할 일 |
 |---|---|---|
-| 2 | 경로가 겹침 | **다른 작업으로 전환.** 재시도해도 결과는 같다 |
+| 2 | 경로가 겹침 **또는 같은 이름·다른 세션** | **다른 작업으로 전환.** 재시도해도 결과는 같다 |
 | 3 | claim 없이 커밋 시도 | 해당 경로를 claim 하거나 스테이징에서 뺀다 |
 | 1 | 환경 오류 / 경합 과다 | 메시지를 읽고 고친다 |
 | 5 | `release` 가 **아무것도 반납 못 함** | 잡을 때와 이름이 다르다. `AXMAP_AGENT` 를 확인한다 |

package/README.md

@@ -81,6 +81,14 @@ node bin/axmap.mjs status      # 누가 무엇을
 node bin/axmap.mjs release     # 끝나면 즉시
 ```
 
+이름은 **세션마다 다르게** 준다. 같은 PC 에서 AI 도구 세션을 둘 띄우고 둘 다
+이름을 안 주면 `git config user.name` 으로 떨어져 장부에서 한 사람이 된다.
+그러면 서로를 하나도 못 막는다. 이름이 같은데 세션이 다르면 `claim`·`release` 는
+거부되고(종료 코드 2) 앞 세션의 레코드는 그대로 남는다 — 자세한 것은 [docs/SPEC.md](docs/SPEC.md) 3절.
+
+`git worktree add` 로 만든 폴더 안에서도 그대로 쓴다. 장부는 메인 체크아웃에
+하나뿐이고, 링크된 worktree 는 그것을 본다. 거기에 장부를 또 만들지 않는다.
+
 git 은 **같은 줄**을 고쳐야 충돌을 안다. 그런데 더 위험한 것은
 같은 기능을 앞에서부터·뒤에서부터 만드는 두 사람이다 — 경로가 안 겹쳐도 어긋난다.
 장부는 그것을 코드를 쓰기 **전에** 터뜨린다.

package/bin/axmap.mjs

@@ -20,6 +20,8 @@ import {
   applyRenew,
   coversPath,
   formatBlocks,
+  formatSessionConflict,
+  shortSession,
   humanDuration,
   normalizePath,
   activeClaims,
@@ -321,6 +323,26 @@ function parseArgs(argv) {
   return { positional, flags }
 }
 
+/**
+ * 값을 받지 않는 깃발을 안전하게 읽는다.
+ *
+ * 🔴 `parseArgs` 는 `--x 뒤낱말` 을 값으로 삼킨다. 그래서
+ *    `axmap claim --takeover src/foo` 는 `takeover='src/foo'` 가 되고
+ *    **경로 하나가 positional 에서 통째로 사라진다.** 잡은 줄 알았는데 안 잡힌
+ *    상태로 커밋하러 가는 것이라, 조용히 참으로 읽지 않고 거부한다.
+ */
+function boolFlag(v, name) {
+  if (v === undefined) return false
+  if (v === true) return true
+  const s = String(v).toLowerCase()
+  if (s === 'true' || s === '1' || s === 'yes') return true
+  die(
+    `--${name} 는 값을 받지 않는데 뒤에 온 "${v}" 를 값으로 삼켰습니다.\n` +
+      `  그대로 두면 "${v}" 가 인자 목록에서 사라집니다.\n` +
+      `  --${name} 를 맨 뒤에 두거나 --${name}=true 로 쓰세요.`,
+  )
+}
+
 // ---------------------------------------------------------------------------
 // 레포 / 장부 위치
 // ---------------------------------------------------------------------------
@@ -472,14 +494,93 @@ function repoRoot() {
   return r.out
 }
 
+/**
+ * `.axmap/` 가 실제로 있는 곳 — **메인 체크아웃**.
+ *
+ * 🔴 링크된 worktree 에서 커밋이 통째로 막히던 자리다 (2026-08-28 실측).
+ *
+ *    `git worktree add` 로 만든 worktree(= 같은 저장소의 다른 브랜치를 옆 폴더로
+ *    펼쳐 둔 것)에서 `git commit` 을 하면 `pre-commit` 훅이 돈다. 훅 디렉터리는
+ *    저장소에 하나뿐이라(공통 디렉터리 아래) worktree 마다 따로 설치할 것도 없이
+ *    그대로 실행된다. 그런데 `repoRoot()` 는 **그 worktree** 를 가리키고
+ *    `.axmap/ledger` 는 **메인 체크아웃에만** 있으므로 `requireLedger` 가
+ *    "장부가 없습니다" 로 종료 코드 1 을 냈다 — 선점과 아무 상관 없는 커밋까지.
+ *
+ *    사람이 쓴 우회는 그 worktree 안에 장부 worktree 를 하나 더 만드는 것이었다.
+ *    돌아가긴 하지만 장부 worktree 가 worktree 수만큼 늘고, 그중 하나가 뒤처지면
+ *    **같은 저장소에 장부가 여럿**이 된다. 락 시스템에서 진실이 둘이면 락이 아니다.
+ *
+ * ── 왜 `--git-common-dir` 인가 ────────────────────────────────────────────
+ *
+ * git 은 worktree 마다 다른 것(HEAD·인덱스·FETCH_HEAD)과 저장소에 하나뿐인 것
+ * (오브젝트·refs·훅)을 나눠 둔다. 후자가 있는 곳이 **공통 디렉터리**다.
+ *
+ *   메인 체크아웃에서   git rev-parse --git-common-dir  →  .git         (상대)
+ *   링크된 worktree 에서 git rev-parse --git-common-dir  →  <메인>/.git  (절대)
+ *
+ * 그 부모가 메인 체크아웃이다. 이 파일은 이미 훅 설치(`cmdHookInstall`)에서
+ * 같은 명령을 쓰고 있었다 — 훅은 공통이라는 사실을 알면서 장부는 몰랐던 것이다.
+ *
+ * 🔴 **"못 찾음" 과 "없음" 을 뭉개지 않는다.** 여기서 하는 일은 *어디를 볼지*를
+ *    바로잡는 것뿐이다. 바로잡은 자리에 장부가 없으면 `requireLedger` 는 지금처럼
+ *    거부한다. 뭉개면 `init` 을 안 돌린 저장소에서 장부 없이 커밋이 통과한다.
+ *
+ * 판정이 안 서면 `root` 를 그대로 돌려준다(= 지금까지의 동작). 공통 디렉터리가
+ * `.git` 이라는 이름이 아닌 배치 — bare 저장소의 worktree 나 `--git-dir` 을 손으로
+ * 준 경우 — 에서 부모를 짚으면 저장소 **바깥**을 가리키게 되기 때문이다.
+ */
+const axmapHomeCache = new Map()
+
+function axmapHome(root) {
+  if (axmapHomeCache.has(root)) return axmapHomeCache.get(root)
+  const home = computeAxmapHome(root)
+  axmapHomeCache.set(root, home)
+  return home
+}
+
+function computeAxmapHome(root) {
+  /**
+   * 🔴 빠른 길이 있어야 한다. 이 함수는 거의 모든 명령이 부르는데, git 을 한 번 더
+   *    띄우는 것은 윈도우에서 수십 ms 다. `test/ledgerlock.test.mjs` 처럼 400ms
+   *    창 안에서 재시도가 도는지를 보는 검사가 있어, 여기서 늘린 시간이 그대로
+   *    **엉뚱한 곳의 실패**로 나타난다.
+   *
+   *    판별은 파일 하나로 끝난다. 메인 체크아웃의 `.git` 은 **디렉터리**이고
+   *    링크된 worktree 의 `.git` 은 `gitdir: …` 한 줄이 든 **파일**이다.
+   *    디렉터리면 여기가 곧 메인 체크아웃이므로 git 에게 물을 것이 없다 —
+   *    지금까지의 동작과 한 글자도 다르지 않다.
+   */
+  try {
+    if (fs.statSync(path.join(root, '.git')).isDirectory()) return root
+  } catch {
+    /* .git 이 없거나 못 읽으면 아래에서 git 에게 물어본다 */
+  }
+  const r = git(['rev-parse', '--git-common-dir'], { cwd: root })
+  if (r.code !== 0 || !r.out) return root
+  const common = path.resolve(root, r.out)
+  const parent = path.dirname(common)
+  if (path.basename(common) !== '.git' || !fs.existsSync(parent)) return root
+  return parent
+}
+
 function ledgerDir(root) {
-  return path.join(root, LEDGER_REL)
+  return path.join(axmapHome(root), LEDGER_REL)
 }
 
 function claimsDir(root) {
   return path.join(ledgerDir(root), 'claims')
 }
 
+/**
+ * 쪽지함은 **일부러 `root` 그대로 둔다.**
+ *
+ * 장부와 같은 `.axmap/` 아래라 같은 문제가 있지만(링크된 worktree 에는 없다),
+ * 고치려면 `tools/bus.mjs` 의 `SEEN_FILE`·쪽지함 경로까지 같이 옮겨야 한다.
+ * 한쪽만 옮기면 **읽는 곳과 쓰는 곳이 갈려** 읽음 표시가 어긋난다 —
+ * 쪽지가 안 보이는 것보다 나쁘다. 장부와 달리 여기서는 못 찾아도 죽지 않고
+ * "새 쪽지 없음" 으로 조용히 지나가므로, 링크된 worktree 에서 쪽지가 안 보이는
+ * 것은 남는 구멍으로 적어 둔다.
+ */
 function busDir(root) {
   return path.join(root, BUS_REL)
 }
@@ -662,6 +763,62 @@ function agentName(flags) {
   return r.name
 }
 
+/**
+ * 세션 id 가 **어디서 왔는지**. 이름의 `agentFrom` 과 같은 이유로 남긴다 —
+ * 막혔을 때 "왜 남이라고 하는가" 의 답이 대부분 여기 있다.
+ */
+let sessionFrom = null
+
+/**
+ * 이 실행은 **어느 세션의 것인가**. 이름과 달리 **없어도 죽지 않는다.**
+ *
+ * 🔴 이름은 없으면 die 인데 세션은 왜 아닌가.
+ *
+ *    이름이 없으면 장부에 아무것도 못 적는다 — 레코드의 키가 이름이다.
+ *    세션은 키가 아니라 **키 안의 구별**이다. 없으면 지금까지처럼 돌고,
+ *    다만 같은 이름의 두 주체를 구별하지 못할 뿐이다. 없다고 멈춰 세우면
+ *    세션 개념이 없던 모든 셸에서 axMap 이 통째로 안 돈다.
+ *
+ * 순서. 이름(`resolveAgentName`)과 같은 모양으로 맞춘다 — 모양이 다르면
+ * 한쪽만 기억하게 되고, 그때부터 둘 중 하나는 반드시 틀린다.
+ *
+ *   1. `--session <값>`          그 명령에서만
+ *   2. `AXMAP_SESSION`           도구가 심어준다 (MCP 서버가 여기에 적는다)
+ *   3. `CLAUDE_CODE_SESSION_ID`  Claude Code 가 세션마다 다르게 준다
+ *   4. 없으면 null → "확인할 수 없음". 막지 않되 조용히 넘어가지도 않는다
+ *
+ * 🔴 **없다고 프로세스마다 다른 값을 지어내지 않는다.** pid 나 난수를 채우면
+ *    `axmap` 을 부를 때마다 다른 세션이 되고, 자기가 잡은 것을 자기가 못 늘리고
+ *    못 반납한다. 모를 때는 모른다고 말하는 것이 유일하게 안전한 값이다.
+ */
+function resolveSessionId(flags) {
+  const pick = (v, src) => {
+    sessionFrom = src
+    return String(v)
+  }
+  if (typeof flags?.session === 'string' && flags.session) return pick(flags.session, '--session')
+  if (process.env.AXMAP_SESSION) return pick(process.env.AXMAP_SESSION, 'AXMAP_SESSION')
+  if (process.env.CLAUDE_CODE_SESSION_ID) return pick(process.env.CLAUDE_CODE_SESSION_ID, 'CLAUDE_CODE_SESSION_ID')
+  sessionFrom = null
+  return null
+}
+
+/**
+ * 세션을 확인할 수 없을 때 한 번만 알린다.
+ *
+ * 🔴 **조용히 넘어가지 않는다.** 이 결함의 피해는 "덮어썼다" 가 아니라
+ *    "덮어썼는데 아무도 몰랐다" 였다. 막을 근거가 없을 때 할 수 있는 최소한은
+ *    무엇이 일어나는지를 말하는 것이다.
+ */
+function warnUnverifiableSession(me, prevPaths) {
+  console.error(
+    `알림: "${me}" 의 유효한 claim 이 이미 있습니다 (경로 ${prevPaths}개). 덮지 않고 여기에 더합니다.\n` +
+      '      이 실행이 그 claim 을 만든 세션과 같은 세션인지는 확인하지 못했습니다\n' +
+      `      (${sessionFrom ? `내 세션은 ${sessionFrom} 에서 왔지만 레코드에 세션 표식이 없습니다` : 'AXMAP_SESSION 도 CLAUDE_CODE_SESSION_ID 도 없습니다'}).\n` +
+      '      한 PC 에서 세션을 여럿 굴린다면 세션마다 AXMAP_SESSION 을 다르게 주세요.',
+  )
+}
+
 /**
  * 장부 worktree 의 존재만 확인한다.
  *
@@ -670,9 +827,17 @@ function agentName(flags) {
  * 그러면 "정상적으로 다 반납한 상태"가 "장부가 없음"으로 오진된다.
  */
 function requireLedger(root) {
-  if (!fs.existsSync(path.join(ledgerDir(root), '.git'))) {
-    die(`장부가 없습니다. 먼저 실행하세요:\n  axmap init`)
+  if (fs.existsSync(path.join(ledgerDir(root), '.git'))) return
+  const home = axmapHome(root)
+  let msg = `장부가 없습니다. 먼저 실행하세요:\n  axmap init`
+  // 링크된 worktree 에서 실행 중이면 어디를 보고 없다고 하는지 밝힌다.
+  // 안 밝히면 "여기 .axmap 이 없는데?" 로 읽혀 장부를 또 만들게 된다 (그러면 진실이 둘이다).
+  if (path.resolve(home) !== path.resolve(root)) {
+    msg += `\n\n찾아본 곳: ${path.join(home, LEDGER_REL)}`
+    msg += `\n(여기는 링크된 worktree 라 장부는 메인 체크아웃에 하나만 둡니다.`
+    msg += `\n 이 폴더 안에 장부를 또 만들지 마세요 — 같은 저장소에 장부가 둘이 되면 락이 아닙니다.)`
   }
+  die(msg)
 }
 
 /** 지금 실행 위치가 장부 worktree 자신인가. */
@@ -1108,6 +1273,8 @@ function cmdClaim(positional, flags) {
   const root = repoRoot()
   requireLedger(root)
   const me = agentName(flags)
+  const session = resolveSessionId(flags)
+  const takeover = boolFlag(flags.takeover, 'takeover')
   if (!positional.length) die('claim 할 경로를 하나 이상 지정하세요.\n  axmap claim src/auth --task task-12')
   for (const p of positional) {
     const err = claimPathError(p)
@@ -1144,14 +1311,33 @@ function cmdClaim(positional, flags) {
       // 치환은 서로 다른 두 입력을 같은 것으로 만든다 — 여기서는 색깔만
       // 정하는 필드라 피해가 작지만, 원칙에 예외를 두면 그 예외가 기준이 된다.
       actor: resolveActor(flags.actor),
+      session,
+      takeover,
     })
     if (!res.ok) {
-      console.error(formatBlocks(res.blocks, t))
+      /**
+       * 두 가지 거부가 있고 **둘 다 종료 코드 2** 다 (SPEC 8절).
+       * 부르는 쪽이 해야 할 일이 같기 때문이다 — 재시도하지 말고 방향을 바꾼다.
+       */
+      if (res.sessionConflict) {
+        console.error(formatSessionConflict(res.sessionConflict, t, 'claim'))
+        console.error(`\n  (이 세션의 id 는 ${sessionFrom ?? '어디에서도 오지 않았습니다'})`)
+      } else {
+        console.error(formatBlocks(res.blocks, t))
+      }
       process.exit(2)
     }
     if (res.hadExpired) {
       console.error(`알림: ${me} 의 이전 claim 이 만료되어 새 claim 으로 시작합니다.`)
     }
+    if (res.tookOver) {
+      console.error(
+        `알림: --takeover — "${me}" 의 레코드를 다른 세션에게서 이 세션이 넘겨받습니다.\n` +
+          '      저 세션이 잡고 있던 경로는 하나도 빠지지 않고 그대로 합쳐집니다.',
+      )
+    } else if (res.session === 'unverifiable') {
+      warnUnverifiableSession(me, res.record.paths.length)
+    }
     // push 실패 시 되돌아갈 지점. 커밋을 만들기 **전에** 잡아둔다.
     const before = ledgerHead(root)
     // 커밋 전에 실패할 수도 있다. 그때는 HEAD 가 아니라 이 파일을 되돌려야 한다.
@@ -1211,11 +1397,24 @@ function cmdRelease(positional, flags) {
   const root = repoRoot()
   requireLedger(root)
   const me = agentName(flags)
+  const session = resolveSessionId(flags)
+  const takeover = boolFlag(flags.takeover, 'takeover')
   const drop = positional.map(normalizePath)
 
   for (let attempt = 1; attempt <= MAX_CAS_RETRIES; attempt++) {
     syncLedger(root)
-    const res = applyRelease({ claims: readClaims(root), me, drop })
+    const t = now()
+    const res = applyRelease({ claims: readClaims(root), me, drop, session, takeover, now: t })
+    /**
+     * 🔴 `hadNothing` 보다 **먼저** 본다. 여기서 막힌 것은 "반납할 게 없다"가
+     *    아니라 "반납하면 남의 세션 기록이 사라진다" 이고, 둘을 같은 코드로 내면
+     *    부르는 쪽이 이름을 고치는 엉뚱한 처방으로 간다.
+     */
+    if (res.sessionConflict) {
+      console.error(formatSessionConflict(res.sessionConflict, t, 'release'))
+      console.error(`\n  (이 세션의 id 는 ${sessionFrom ?? '어디에서도 오지 않았습니다'})`)
+      process.exit(2)
+    }
     if (res.hadNothing) {
       /**
        * 🔴 반납을 시켰는데 아무것도 반납 안 된 것은 **성공이 아니다.**
@@ -1264,12 +1463,24 @@ function cmdRenew(flags) {
   const root = repoRoot()
   requireLedger(root)
   const me = agentName(flags)
+  const session = resolveSessionId(flags)
   const ttlMs = parseTtl(flags.ttl)
 
   for (let attempt = 1; attempt <= MAX_CAS_RETRIES; attempt++) {
     syncLedger(root)
     const t = now()
-    const res = applyRenew({ claims: readClaims(root), me, now: t, ttlMs })
+    const res = applyRenew({ claims: readClaims(root), me, now: t, ttlMs, session })
+    /**
+     * renew 는 **막지 않는다** (applyRenew 의 주석 참고). 다만 남의 세션 락의
+     * 수명을 늘리고 있다는 사실은 말한다 — 모르고 늘리면 그 경로는 아무도
+     * 안 쓰는데 계속 막혀 있게 된다.
+     */
+    if (res.ok && res.session === 'different') {
+      console.error(
+        `경고: "${me}" 의 이 claim 은 다른 세션(${shortSession(res.record.session)})이 만든 것입니다.\n` +
+          '      TTL 만 늘리고 소유자는 그대로 둡니다. 저 세션이 끝난 것이면 늘리지 마세요.',
+      )
+    }
     if (!res.ok) {
       die(
         `${me} 의 유효한 claim 이 없습니다.\n` +
@@ -1332,8 +1543,15 @@ function cmdStatus(flags) {
   }
 
   console.log(`장부 상태 (${new Date(t).toISOString()})\n`)
+  // 이름이 같은 줄이 여럿일 수는 없다(레코드는 이름당 하나). 그래서 세션은
+  // 여기서 줄을 나누는 것이 아니라, **내 것이 아닌데 내 이름인** 줄을 알아보게 한다.
+  const mySession = resolveSessionId(flags)
   for (const c of live) {
     console.log(`  ${c.agent}${c.task ? `  [${c.task}]` : ''}  - ${humanDuration(claimExpiresAt(c) - t)} 남음`)
+    if (c.session) {
+      const same = mySession && c.session === mySession
+      console.log(`    세션 ${shortSession(c.session)}${same ? ' (이 세션)' : mySession ? ' (이 세션이 아님)' : ''}`)
+    }
     if (c.intent) console.log(`    "${c.intent}"`)
     for (const p of c.paths) console.log(`      ${p}`)
     console.log('')
@@ -1531,10 +1749,24 @@ function cmdDoctor(flags) {
   if (me) ok('내 이름', `${me}  (${agentFrom})`)
   else no('내 이름', 'AXMAP_AGENT 도 git config user.name 도 없습니다')
 
+  // 3-b. 세션 — 이름이 같은 두 주체를 가르는 것. 없으면 못 가른다(= 예전 사고 그대로)
+  const sid = resolveSessionId(flags)
+  if (sid) ok('내 세션', `${shortSession(sid)}  (${sessionFrom})`)
+  else {
+    hm(
+      '내 세션',
+      '알 수 없습니다 — 같은 이름의 다른 세션을 구별하지 못합니다\n' +
+        '         세션마다 AXMAP_SESSION 을 다르게 주세요 (Claude Code 는 자동입니다)',
+    )
+  }
+
   // 4. 장부
+  const home = axmapHome(root)
   const hasLedger = fs.existsSync(path.join(ledgerDir(root), '.git'))
-  if (hasLedger) ok('장부', LEDGER_REL)
-  else no('장부', `없습니다 — 'axmap init' 또는 setup 스크립트를 실행하세요`)
+  // 링크된 worktree 면 장부가 어디 있는지 그대로 보여준다. 같은 저장소에 장부는 하나다.
+  const where = path.resolve(home) === path.resolve(root) ? LEDGER_REL : path.join(home, LEDGER_REL)
+  if (hasLedger) ok('장부', where)
+  else no('장부', `없습니다 (${where}) — 'axmap init' 또는 setup 스크립트를 실행하세요`)
 
   // 5. 원격 — 없어도 돌지만, 그때 claim 은 "겹치지 않는다" 가 아니라 "남을 못 본다" 다
   const r = resolveRemote(root, flags)
@@ -1750,21 +1982,49 @@ exec node "$AX" verify
  * 무엇을 대신 하면 되는지를 말한다 — 이 저장소가 `tools/bus.mjs` 로 한 번 겪은
  * 실패다(사본에 빠져 있는데 오류만 났다).
  */
-function cmdSetup(rest, flags) {
-  const script = path.join(SELF_ROOT, 'tools', 'setup.mjs')
+/**
+ * 딸린 프로그램들. **이름을 경로로 바꿔 주는 것이 전부다.**
+ *
+ * 🔴 원래는 파일 경로로 불렀다 — `node axmap/governance/gate.mjs`. 저장소 안에
+ *    사본을 두고 쓸 때는 그게 됐다. 사본의 자리를 팀이 알고 있었기 때문이다.
+ *    **npm 으로 설치하면 그 경로가 기계마다 다르다.** 그래서 팀의 CI 설정과
+ *    슬래시 명령이 경로를 박아 둘 수밖에 없었고, 경로가 박혀 있는 한 사본을
+ *    지울 수 없었다. 여기 이름이 하나 생길 때마다 박힌 경로가 하나 사라진다.
+ *
+ * 값은 [파일, 한 줄 설명] 이다. 설명은 HELP 와 오류 메시지가 같이 쓴다 —
+ * 두 군데 적으면 한 쪽만 고쳐지는 날이 온다.
+ */
+const RUNNERS = {
+  gate: ['governance/gate.mjs', '이 MR 이 정족수를 채웠는가'],
+  vote: ['governance/vote.mjs', '표를 던진다'],
+  bus: ['tools/bus.mjs', '에이전트 사이 쪽지함'],
+  'mr-target': ['tools/mr-target.mjs', '이 브랜치가 저 브랜치로 갈 수 있는가'],
+  version: ['tools/version.mjs', '브랜치 단계로 다음 버전을 정한다'],
+  promote: ['tools/promote.mjs', '한 단계 위로 올리는 MR 을 만든다'],
+  mcp: ['mcp/server.mjs', 'AI 도구가 붙는 서버를 띄운다'],
+  setup: ['tools/setup.mjs', '이 PC 와 이 저장소에 axMap 을 붙인다'],
+}
+
+function cmdRun(name) {
+  const [rel, what] = RUNNERS[name]
+  const script = path.join(SELF_ROOT, ...rel.split('/'))
   if (!fs.existsSync(script)) {
     die(
-      `이 axMap 에는 setup 이 들어 있지 않습니다: ${script}\n\n` +
+      `이 axMap 에는 ${name}(${what})이 들어 있지 않습니다: ${script}\n\n` +
         (isVendored(SELF_ROOT)
           ? `  여기는 팀 저장소 안의 **벤더링된 사본**입니다(옆에 SOURCE.json 이 있습니다).\n` +
-            `  사본에는 CI 가 판정에 쓰는 파일만 들어 있고 설치기는 빠져 있습니다.\n\n` +
-            `  설치는 배포판으로 하세요:\n` +
-            `    npx -y ${PACKAGE_NAME}@latest setup`
-          : `  꾸러미가 온전하지 않습니다. 다시 받으세요:\n    npx -y ${PACKAGE_NAME}@latest setup`),
+            `  사본에는 CI 가 판정에 쓰는 파일만 들어 있습니다.\n\n` +
+            `  배포판으로 부르세요:\n    npx -y ${PACKAGE_NAME}@latest ${name}`
+          : `  꾸러미가 온전하지 않습니다. 다시 받으세요:\n    npx -y ${PACKAGE_NAME}@latest ${name}`),
     )
   }
-  // 인자를 그대로 넘긴다. 여기서 다시 해석하면 두 곳의 플래그 목록이 어긋난다.
-  const argv = process.argv.slice(2).filter((a) => a !== 'setup')
+  // 인자는 그대로 넘긴다. 여기서 다시 해석하면 두 곳의 플래그 목록이 어긋난다.
+  //
+  // 🔴 명령 이름은 **처음 나온 것 하나만** 뗀다. 전부 지우면 같은 낱말이 값으로
+  //    올 때 그 값까지 사라진다 — `axmap bus post --subject vote` 의 "vote".
+  const argv = process.argv.slice(2)
+  const at = argv.indexOf(name)
+  if (at >= 0) argv.splice(at, 1)
   const r = spawnSync(process.execPath, [script, ...argv], { stdio: 'inherit', windowsHide: true })
   process.exit(r.status ?? 1)
 }
@@ -1859,6 +2119,7 @@ const HELP = `axmap - AI 에이전트 작업 선점 프로토콜
   axmap claim <경로...>              경로를 선점한다  [--task --intent --ttl 30m]
   axmap release [경로...]            반납한다 (경로 생략 시 전부)
   axmap renew                        TTL 을 연장한다  [--ttl 30m]
+                                     claim·release 는 [--session <id>] [--takeover]
   axmap status                       누가 무엇을 잡고 있는지  [--json]
   axmap verify                       staged 파일이 내 claim 안에 있는지 검사
   axmap audit                        장부 이력 전체를 재생해 상호배제 위반을 사후 증명
@@ -1867,7 +2128,21 @@ const HELP = `axmap - AI 에이전트 작업 선점 프로토콜
   axmap hook install                 verify 를 pre-commit 훅으로 설치
   axmap update                       새 버전이 있는지 묻는다 (바꾸지는 않는다)
 
+딸린 프로그램 — 예전에는 파일 경로로 불렀다. 이제 이름으로 부른다.
+인자는 그대로 전달되고, 각각의 사용법은 그 프로그램이 답한다.
+
+  axmap gate                         이 MR 이 정족수를 채웠는가 (CI 가 부른다)
+  axmap vote                         표를 던진다
+  axmap bus                          에이전트 사이 쪽지함 (post · list · read · reply)
+  axmap mr-target                    이 브랜치가 저 브랜치로 갈 수 있는가
+  axmap version                      브랜치 단계로 다음 버전을 정한다
+  axmap promote                      한 단계 위로 올리는 MR 을 만든다
+  axmap mcp                          AI 도구가 붙는 서버를 띄운다 (직접 부를 일은 없다)
+
 에이전트 이름: --agent 또는 AXMAP_AGENT, 없으면 git config user.name
+세션 id     : --session 또는 AXMAP_SESSION, 없으면 CLAUDE_CODE_SESSION_ID
+              같은 이름이라도 세션이 다르면 남의 claim 을 덮지 않고 거부한다(종료 코드 2).
+              정말 같은 세션이라면 --takeover 로 넘겨받는다 — 경로는 안 없어진다.
 장부 원격:     --remote 또는 AXMAP_REMOTE, 없으면 git config axmap.remote
 `
 
@@ -1875,8 +2150,16 @@ const { positional, flags } = parseArgs(process.argv.slice(2))
 const [cmd, ...rest] = positional
 
 switch (cmd) {
+  // 이름을 경로로 바꿔 주는 것들 (RUNNERS). 인자는 손대지 않고 그대로 간다.
   case 'setup':
-    cmdSetup(rest, flags)
+  case 'gate':
+  case 'vote':
+  case 'bus':
+  case 'mr-target':
+  case 'version':
+  case 'promote':
+  case 'mcp':
+    cmdRun(cmd)
     break
   case 'update':
     // 이 파일은 ESM 이라 최상위 await 이 된다. update 만 비동기다 (레지스트리에 묻는다).