axmap-cli 0.0.1 → 0.3.0

package/src/protocol.mjs

@@ -58,6 +58,57 @@ export function myActiveClaim(claims, me, now) {
   return activeClaims(claims, now).find((c) => c.agent === me) ?? null
 }
 
+/**
+ * 이 레코드를 만든 **세션**과 지금 실행하는 세션이 같은가.
+ *
+ * 🔴 왜 이름만으로는 부족한가 — 2026-08-28 에 두 번 재현된 사고.
+ *
+ *    한 PC 에서 Claude Code 세션 두 개가 같은 저장소를 만졌다. 둘 다
+ *    `git config user.name` 이 `janghyojoon` 이라 장부에서 **한 사람**이었다.
+ *    `checkOverlap` 은 자기 claim 을 겹침으로 보지 않으므로 세션 B 의 claim 이
+ *    그냥 통과했고, 레코드는 이름 하나에 파일 하나라 A 의 것이 B 의 것으로
+ *    덮였다. 두 세션이 같은 파일을 동시에 밀었고 장부는 아무 말도 안 했다.
+ *
+ *    이름은 **누구인가**이고 세션은 **어느 작업 주체인가**다. 한 사람이 동시에
+ *    두 주체일 수 있다. 그 둘을 같은 것으로 두면 락이 조용히 두 번 발급된다.
+ *
+ * ── 왜 "모르면 막는다" 가 아닌가 ──────────────────────────────────────────
+ *
+ * 세션 id 는 환경이 알려줄 때만 있다. 없을 때 막아버리면 세션 개념이 없던
+ * 시절에 잡아둔 레코드와 셸에서 쓰는 사람이 **자기 claim 을 못 늘리고 못 반납**
+ * 한다 — 고치려던 것보다 큰 고장이다. 그래서 셋으로 나눈다:
+ *
+ *   same         양쪽 다 알고 같다   → 지금까지와 똑같이 돈다
+ *   different    양쪽 다 알고 다르다 → **거부한다.** 이것이 위 사고다
+ *   unverifiable 한쪽이라도 모른다   → 막지 않되 **조용히 넘어가지 않는다**
+ *
+ * 이 판정은 인증이 아니다. 환경변수를 지우면 `unverifiable` 로 내려온다.
+ * 막으려는 것은 악의가 아니라 **아무도 눈치 못 챈 사고**다.
+ *
+ * @returns {'none'|'same'|'different'|'unverifiable'}
+ */
+export function sessionVerdict(prev, session) {
+  if (!prev) return 'none'
+  const held = prev.session ?? null
+  const mine = session ?? null
+  if (!held || !mine) return 'unverifiable'
+  return held === mine ? 'same' : 'different'
+}
+
+/** 거부 메시지에 실을 만큼만 담은 충돌 정보. 레코드 원본을 그대로 흘리지 않는다. */
+function sessionConflictOf(prev, me, session) {
+  return {
+    agent: me,
+    heldSession: prev.session ?? null,
+    mySession: session ?? null,
+    task: prev.task ?? null,
+    intent: prev.intent ?? null,
+    paths: [...(prev.paths ?? [])],
+    since: prev.since,
+    expiresAt: claimExpiresAt(prev),
+  }
+}
+
 /**
  * 이 프로토콜의 심장.
  *
@@ -108,9 +159,31 @@ function upsert(claims, record) {
 
 /**
  * claim 취득. 관문 2 의 판정이 여기서 일어난다.
- * @returns {{ok:true, record, claims, hadExpired}|{ok:false, blocks}}
+ *
+ * 관문 2 는 이제 질문이 둘이다.
+ *   2-a 남이 잡은 경로와 겹치는가            → checkOverlap
+ *   2-b 같은 이름인데 **다른 세션**이 잡았는가 → sessionVerdict
+ *
+ * 🔴 어느 쪽으로 막든 **아무것도 쓰지 않고 돌아간다.** 이 결함의 핵심 피해가
+ *    "A 의 레코드가 사라졌다" 였으므로, 판정이 끝나기 전에는 레코드를 만들지 않는다.
+ *    `--takeover` 로 넘겨받을 때조차 `paths` 는 합집합이라 경로는 하나도 안 없어진다.
+ *
+ * @returns {{ok:true, record, claims, hadExpired, session, tookOver}
+ *          |{ok:false, blocks}
+ *          |{ok:false, blocks:[], sessionConflict}}
  */
-export function applyClaim({ claims, me, requested, now, ttlMs, task = null, intent = null, actor = null }) {
+export function applyClaim({
+  claims,
+  me,
+  requested,
+  now,
+  ttlMs,
+  task = null,
+  intent = null,
+  actor = null,
+  session = null,
+  takeover = false,
+}) {
   const want = [...new Set(requested.map(normalizePath))]
 
   const verdict = checkOverlap({ requested: want, claims, me, now })
@@ -121,6 +194,18 @@ export function applyClaim({ claims, me, requested, now, ttlMs, task = null, int
   const prev = myActiveClaim(claims, me, now)
   const hadExpired = !prev && claims.some((c) => c.agent === me)
 
+  /**
+   * 경로가 안 겹쳐도 막는다.
+   *
+   * 겹칠 때만 막으면 안 되는 이유: 이름당 레코드는 하나뿐이라 경로가 안 겹쳐도
+   * 저쪽의 `task`·`intent`·`since`·TTL 이 이쪽 값으로 덮인다. 장부를 읽는 사람은
+   * 저 세션이 무엇을 왜 하고 있었는지를 잃는다 — 그게 "기록이 사라졌다" 의 실체다.
+   */
+  const sv = sessionVerdict(prev, session)
+  if (sv === 'different' && !takeover) {
+    return { ok: false, blocks: [], sessionConflict: sessionConflictOf(prev, me, session) }
+  }
+
   const record = {
     agent: me,
     task: task ?? prev?.task ?? null,
@@ -128,21 +213,42 @@ export function applyClaim({ claims, me, requested, now, ttlMs, task = null, int
     // 누가 잡았는지의 '종류'. 화면에서 사람·AI·백그라운드 에이전트를 색으로 나눈다.
     // 프로토콜 판정에는 쓰이지 않는다 — 표시용 정보다.
     actor: actor ?? prev?.actor ?? null,
+    /**
+     * 이 레코드를 만든 세션. **판정에 쓰인다** (actor 와 다른 점이다).
+     *
+     * 내가 세션을 모르면 앞 레코드의 값을 그대로 둔다. 모른다고 지워버리면
+     * 세션 없는 셸에서 한 번 부르는 것만으로 표식이 날아가고, 그다음부터
+     * 다른 세션이 아무 말 없이 덮을 수 있게 된다 — 막으려던 그 자리로 돌아간다.
+     */
+    session: session ?? prev?.session ?? null,
     since: new Date(now).toISOString(),
     ttlMs,
     paths: [...new Set([...(prev?.paths ?? []).map(normalizePath), ...want])].sort(),
   }
-  return { ok: true, record, claims: upsert(claims, record), hadExpired }
+  return { ok: true, record, claims: upsert(claims, record), hadExpired, session: sv, tookOver: sv === 'different' }
 }
 
 /**
  * 반납. drop 이 비어 있으면 전부 반납한다.
  * 만료된 레코드도 반납할 수 있다 (단순 정리이므로 관문 2 가 필요 없다).
+ *
+ * 🔴 **세션 검사가 claim 뿐 아니라 여기에도 있어야 한다.**
+ *    `release` 는 경로를 다 빼면 레코드 파일을 지운다. 같은 이름의 다른 세션이
+ *    이것을 부르면 claim 을 덮는 것보다 더 확실하게 기록이 사라진다.
+ *
+ *    다만 **만료된 레코드는 막지 않는다.** 만료된 것은 아무도 못 막는 껍데기라
+ *    지우는 것이 곧 정리다. 여기서까지 막으면 죽은 세션이 두고 간 레코드를
+ *    아무도 못 치운다. (`now` 를 안 주면 만료 여부를 모르므로 막는 쪽으로 둔다.)
  */
-export function applyRelease({ claims, me, drop }) {
+export function applyRelease({ claims, me, drop, session = null, takeover = false, now = null }) {
   const mine = claims.find((c) => c.agent === me)
   if (!mine) return { claims, record: null, unheld: [], hadNothing: true }
 
+  const stillActive = now === null || !isExpired(mine, now)
+  if (stillActive && !takeover && sessionVerdict(mine, session) === 'different') {
+    return { claims, record: null, unheld: [], hadNothing: false, sessionConflict: sessionConflictOf(mine, me, session) }
+  }
+
   const held = mine.paths.map(normalizePath)
   const want = [...new Set(drop.map(normalizePath))]
   const unheld = want.filter((p) => !held.includes(p))
@@ -159,12 +265,21 @@ export function applyRelease({ claims, me, drop }) {
  * TTL 연장.
  * 만료된 claim 은 연장할 수 없다. renew 는 관문 2 를 거치지 않으므로,
  * 만료 이후를 허용하면 그 사이 남이 가져간 경로를 검사 없이 되찾게 된다.
+ *
+ * 🔴 **세션이 달라도 막지 않는다.** renew 는 아무것도 지우지 않고 아무것도 덮지
+ *    않는다 — 시간만 늘린다. 여기서 막으면 "한 사람이 자기 claim 을 갱신한다" 는
+ *    정상 흐름이 세션 표식 하나 때문에 끊긴다. 대신 어느 세션의 것을 늘리고
+ *    있는지는 `session` 으로 돌려주고, 부르는 쪽이 그것을 말한다.
+ *
+ *    세션 표식이 없던 레코드에는 이번 세션 값을 **채워 넣는다**(이관이 아니라
+ *    이주다). 이미 표식이 있으면 건드리지 않는다 — 바꾸면 그것이 곧 조용한 이관이다.
  */
-export function applyRenew({ claims, me, now, ttlMs }) {
+export function applyRenew({ claims, me, now, ttlMs, session = null }) {
   const mine = myActiveClaim(claims, me, now)
   if (!mine) return { ok: false, reason: 'expired-or-missing' }
-  const record = { ...mine, since: new Date(now).toISOString(), ttlMs }
-  return { ok: true, record, claims: upsert(claims, record) }
+  const sv = sessionVerdict(mine, session)
+  const record = { ...mine, session: mine.session ?? session ?? null, since: new Date(now).toISOString(), ttlMs }
+  return { ok: true, record, claims: upsert(claims, record), session: sv }
 }
 
 // ---------------------------------------------------------------------------
@@ -257,6 +372,47 @@ export function formatBlocks(blocks, now) {
   return lines.join('\n')
 }
 
+/** 세션 id 는 길다. 사람이 두 개를 눈으로 구분할 만큼만 보여준다. */
+export function shortSession(id) {
+  const s = String(id ?? '')
+  if (!s) return '(모름)'
+  return s.length <= 12 ? s : `${s.slice(0, 8)}…${s.slice(-4)}`
+}
+
+/**
+ * "같은 이름, 다른 세션" 을 사람과 AI 가 함께 읽는 형태로.
+ *
+ * `formatBlocks` 와 같은 원칙이다 — 막혔다는 말만 하면 에이전트가 다음 행동을
+ * 고를 수 없다. 여기서 특히 중요한 것은 **왜 이름이 같은데 남이라고 하는지**를
+ * 설명하는 것이다. 설명이 없으면 에이전트는 이것을 버그로 보고 우회를 찾는다.
+ */
+export function formatSessionConflict(c, now, command = 'claim') {
+  const lines = [
+    `${command} 거부 - 이름은 "${c.agent}" 로 같지만 그 claim 을 만든 세션이 다릅니다.`,
+    '',
+    `  잡고 있는 세션 : ${shortSession(c.heldSession)}`,
+    `  지금 이 세션   : ${shortSession(c.mySession)}`,
+  ]
+  if (c.task) lines.push(`  작업           : ${c.task}`)
+  if (c.intent) lines.push(`  의도           : ${c.intent}`)
+  lines.push(`  시작           : ${c.since}`)
+  lines.push(`  TTL            : ${humanDuration(c.expiresAt - now)} 남음`)
+  lines.push('  잡힌 경로      :')
+  for (const p of c.paths) lines.push(`      ${p}`)
+  lines.push('')
+  lines.push('같은 사람이라도 세션이 다르면 서로 다른 작업 주체입니다. 이름당 레코드는')
+  lines.push('하나뿐이라, 그대로 진행하면 저 세션의 작업·의도·시작 시각이 이 세션의')
+  lines.push('것으로 덮여 장부에서 사라집니다. 그래서 아무것도 쓰지 않고 멈췄습니다.')
+  lines.push('')
+  lines.push('다음 중 하나를 하세요:')
+  lines.push('  - 이 세션에 다른 이름을 준다 (권장)')
+  lines.push(`      AXMAP_AGENT=${c.agent}-2  — 장부에서 둘로 갈라지고 겹침 검사가 실제로 돕니다`)
+  lines.push('  - 저 세션이 끝난 것이 확실하면 TTL 만료를 기다린다')
+  lines.push(`  - 저 세션이 확실히 나 자신이면 --takeover 를 붙인다`)
+  lines.push('      레코드를 이 세션으로 넘겨받습니다. 잡혀 있던 경로는 하나도 안 없어집니다.')
+  return lines.join('\n')
+}
+
 // ---------------------------------------------------------------------------
 // 병합 합의 — 게이트는 거부권, 표는 판단 (SPEC 7-3)
 //

package/tools/mcp-register.mjs

@@ -74,12 +74,102 @@ const same = (a, b) => JSON.stringify(a) === JSON.stringify(b)
 
 // ── Claude Code ────────────────────────────────────────────────────────────
 //
-// 할 일이 없다. 저장소의 `.mcp.json` 을 스스로 발견하고 승인만 묻는다.
-// 그래도 한 줄 찍는다 — "내 CLI 는 왜 아무 말이 없지" 를 없애기 위해서다.
-function doClaude(repo) {
+// 🔴 **2026-08-31 — 여기서 전역 등록을 하도록 바꿨다.** 그전에는 저장소의
+//    `.mcp.json` 이 있는지 확인만 하고 아무것도 하지 않았다.
+//
+//    그래서 Claude 만 **저장소에 파일을 커밋해야** 붙는 유일한 CLI 였다. npm 으로
+//    설치해 남의 저장소에서 쓰는 사람은 그 파일을 넣을 권한이 없을 수도 있고,
+//    넣더라도 "도구는 나가고 데이터만 남는다" 는 이 저장소의 방침에 어긋난다.
+//    `mcp/install.ps1` 은 이미 전역 등록을 하고 있었다 — 설치 경로 둘이 서로 다르게
+//    굴어서, 둘 다 돌린 PC 에는 **범위가 충돌하는 항목**이 남았다(claude mcp list 가
+//    "Conflicting scopes" 로 알려 준다). 두 경로를 같은 동작으로 맞춘다.
+//
+// 설정: `~/.claude.json` 의 최상위 `mcpServers` (user 범위)
+// 형식: `claude mcp add <이름> -s user [-e K=V] -- <명령> <인수...>`
+//
+// 🔴 `~/.claude.json` 을 **우리가 쓰지 않는다.** 그 파일에는 Claude Code 의 세션
+//    상태까지 들어 있어 읽고 다시 쓰는 순간 남의 것을 깨뜨릴 위험이 생긴다.
+//    있는지 **읽는 것만** 우리가 하고, 쓰는 일은 claude 자신에게 맡긴다 —
+//    doCodex 와 같은 태도다.
+
+/** `~/.claude.json` 의 user 범위 axmap 항목. 없으면 null, **못 읽으면 undefined**. */
+function claudeUserEntry() {
+  try {
+    const cfg = JSON.parse(fs.readFileSync(path.join(os.homedir(), '.claude.json'), 'utf8'))
+    return (cfg && cfg.mcpServers && cfg.mcpServers.axmap) || null
+  } catch (e) {
+    // 파일이 아예 없는 것은 "등록 안 됨"(null)이고, 있는데 못 읽는 것은 사고(undefined)다.
+    return e && e.code === 'ENOENT' ? null : undefined
+  }
+}
+
+/**
+ * 이미 쓸 만한 항목인가.
+ *
+ * env 는 **우리가 넣는 키만** 본다. 남이 `AXMAP_AGENT` 를 손으로 넣어 뒀을 수 있고,
+ * 그건 그 사람의 이름이라 지우면 안 된다 (install.ps1 이 실제로 넣는다).
+ */
+const sameEntry = (cur, want) =>
+  !!cur && cur.command === want.command &&
+  JSON.stringify(cur.args || []) === JSON.stringify(want.args) &&
+  Object.entries(want.env).every(([k, v]) => ((cur.env || {})[k] === v))
+
+function doClaude(bin, repo) {
+  const run = (args) => spawnSync(bin, args, { encoding: 'utf8', windowsHide: true })
+  const want = entry()
+
+  const cur = claudeUserEntry()
+  if (cur === undefined) {
+    no('claude', '~/.claude.json 을 읽지 못했습니다 — 건드리지 않았습니다')
+    snippetClaude()
+    return
+  }
+  if (sameEntry(cur, want)) { ok('claude', '이미 등록돼 있습니다 (user 범위)'); return }
+
+  // 문서에 있다고 믿고 부르지 않는다 — 먼저 물어본다. doCodex 와 같다.
+  const help = run(['mcp', 'add', '--help'])
+  if (help.status !== 0 || !/--scope/.test(`${help.stdout}${help.stderr}`)) {
+    hm('claude', "'claude mcp add -s user' 를 확인하지 못했습니다 — 손으로 넣으세요")
+    snippetClaude()
+    return
+  }
+
+  const add = ['mcp', 'add', 'axmap', '-s', 'user',
+    ...Object.entries(want.env).flatMap(([k, v]) => ['-e', `${k}=${v}`]),
+    '--', want.command, ...want.args]
+
+  if (DRY) {
+    hm('claude', `(dry-run) ${cur ? 'claude mcp remove axmap -s user 뒤 ' : ''}claude ${add.join(' ')}`)
+    return
+  }
+
+  // 자리를 비워야 add 가 덮어쓴다. 지우는 것은 **우리 이름(`axmap`)의 항목뿐**이다.
+  if (cur) run(['mcp', 'remove', 'axmap', '-s', 'user'])
+
+  const r = run(add)
+  if (r.status === 0 && sameEntry(claudeUserEntry(), want)) {
+    ok('claude', 'user 범위에 등록했습니다 — 어느 폴더에서 열어도 붙습니다')
+  } else {
+    no('claude', `claude mcp add 가 실패했습니다 (${(r.stderr || r.stdout || '').trim().split('\n')[0] || `exit ${r.status}`})`)
+    snippetClaude()
+  }
+
+  // 저장소에 `.mcp.json` 이 남아 있으면 **그쪽이 이긴다.** 조용히 두면 방금 등록한
+  // 것이 왜 안 쓰이는지 아무도 못 찾는다.
   const f = path.join(repo, '.mcp.json')
-  if (fs.existsSync(f)) ok('claude', '.mcp.json — 이 폴더를 열면 스스로 발견합니다 (승인만 누르면 됩니다)')
-  else no('claude', `.mcp.json 이 없습니다: ${f}`)
+  if (fs.existsSync(f)) hm('claude', `저장소의 .mcp.json 이 먼저 쓰입니다 (같은 서버라면 문제 없습니다): ${f}`)
+}
+
+/** 손으로 넣을 한 줄. 경로에 공백이 있을 수 있어 겹따옴표로 감싼다. */
+function snippetClaude() {
+  console.log('')
+  console.log('      아래 한 줄을 치세요:')
+  console.log('')
+  console.log(`        claude mcp add axmap -s user -e AXMAP_ACTOR=agent -e AXMAP_TTL=45m -- node "${SERVER}"`)
+  console.log('')
+  console.log('      AXMAP_AGENT 는 적지 마세요 — 여러 사람이 같은 이름이 되면')
+  console.log('      서로의 선점을 겹침으로 보지 못합니다.')
+  console.log('')
 }
 
 // ── Antigravity CLI (agy) ──────────────────────────────────────────────────
@@ -234,7 +324,7 @@ function snippetToml() {
 // ── 본체 ───────────────────────────────────────────────────────────────────
 
 function main() {
-  const repo = spawnSync('git', ['rev-parse', '--show-toplevel'], { cwd: AXMAP_DIR, encoding: 'utf8', windowsHide: true })
+  const repo = spawnSync('git', ['rev-parse', '--show-toplevel'], { cwd: process.cwd(), encoding: 'utf8', windowsHide: true })
   const root = repo.status === 0 ? path.resolve(repo.stdout.trim()) : path.resolve(AXMAP_DIR, '..')
 
   console.log('')
@@ -253,7 +343,7 @@ function main() {
     const bin = resolveBin(a.bin)
     if (!bin) continue
     any = true
-    if (a.id === 'claude') doClaude(root)
+    if (a.id === 'claude') doClaude(bin, root)
     else if (a.id === 'agy') doAgy()
     else if (a.id === 'codex') doCodex(bin)
   }

package/tools/promote.mjs

@@ -46,7 +46,7 @@
 import { spawnSync } from 'node:child_process'
 import path from 'node:path'
 import { fileURLToPath, pathToFileURL } from 'node:url'
-import { planPromotions, formatPlan, describeStep, STEPS } from '../src/promote.mjs'
+import { planPromotions, formatPlan, describeStep, mergeCommitMessage, STEPS } from '../src/promote.mjs'
 
 /** 이 도구의 종료 코드. */
 export const EXIT = { OK: 0, ERROR: 1, POLICY_BROKEN: 4 }
@@ -54,9 +54,16 @@ export const EXIT = { OK: 0, ERROR: 1, POLICY_BROKEN: 4 }
 /** 게이트의 종료 코드. `src/governance.mjs` 의 EXIT 과 같은 값이다. */
 const GATE = { OK: 0, UNDECIDABLE: 1, SHORT: 2, POLICY_BROKEN: 4 }
 
-/** `axmap/` 폴더. 호출 위치에 기대지 않는다 (tools/version.mjs 와 같은 방식). */
+/** `axmap/` 폴더. **프로그램**을 찾을 때만 쓴다 (옆에 있는 gate.mjs 같은 것). */
 const AXMAP = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
 
+/**
+ * 🔴 git 은 **서 있는 저장소**에서 부른다. 프로그램이 있는 폴더가 아니다.
+ *    npm 으로 설치하면 그 폴더는 `node_modules/axmap-cli/` 이고 저장소가 아니다.
+ *    근거는 tools/version.mjs 의 같은 자리 주석.
+ */
+const REPO = process.cwd()
+
 // ---------------------------------------------------------------------------
 // 인자 — `--k v` · `--k=v` · `--k`(=true). gate.mjs 의 parseArgs 와 같은 규칙.
 // ---------------------------------------------------------------------------
@@ -123,7 +130,7 @@ function defaultGit(args) {
   const env = { ...process.env }
   for (const k of ['GIT_DIR', 'GIT_WORK_TREE', 'GIT_COMMON_DIR', 'GIT_INDEX_FILE',
     'GIT_OBJECT_DIRECTORY', 'GIT_ALTERNATE_OBJECT_DIRECTORIES', 'GIT_PREFIX']) delete env[k]
-  const r = spawnSync('git', args, { cwd: AXMAP, env, encoding: 'utf8', windowsHide: true })
+  const r = spawnSync('git', args, { cwd: REPO, env, encoding: 'utf8', windowsHide: true })
   return { code: r.status ?? 1, out: (r.stdout ?? '').trim(), err: (r.stderr ?? '').trim() }
 }
 
@@ -142,7 +149,7 @@ function defaultGate({ source, target }) {
   const r = spawnSync(
     process.execPath,
     [path.join(AXMAP, 'governance', 'gate.mjs'), '--source', source, '--target', target, '--json'],
-    { cwd: AXMAP, encoding: 'utf8', windowsHide: true },
+    { cwd: REPO, encoding: 'utf8', windowsHide: true },
   )
   let verdict = null
   try { verdict = JSON.parse(r.stdout ?? '') } catch { verdict = null }
@@ -469,10 +476,18 @@ export async function run(argv, io = {}) {
       }
 
       // 4. 머지. 🔴 sha 를 반드시 싣는다 (CAS).
+      //
+      // 🔴 표의 이유를 **머지 커밋 본문**에 싣는다 (src/promote.mjs 의 근거 참고).
+      //    MR 댓글에 두면 clone 에 안 따라오고 GitLab 을 떠나면 사라진다. 트레일러로
+      //    적으면 `git log --grep` 과 `git interpret-trailers --parse` 가 읽는다.
+      //    표가 하나도 없으면 null 이고, 그때는 필드를 아예 안 보내 GitLab 기본
+      //    메시지를 그대로 쓴다 — 빈 문자열을 보내면 기본 메시지를 덮어쓴다.
+      const message = mergeCommitMessage({ source, target, verdict })
       const merged = await gl('PUT', `/merge_requests/${mr.iid}/merge`, {
         body: {
           // 판정할 때 본 그 커밋. 지금 MR 헤드가 다르면 GitLab 이 409 로 거부한다.
           sha: verdict.sha,
+          ...(message ? { merge_commit_message: message } : {}),
           // 🔴 판정 시점과 머지 시점을 벌리지 않는다. 벌어진 사이에 들어온 커밋이
           //    옛 표로 머지되는 것이 이 파일이 막으려는 사고 전부다.
           merge_when_pipeline_succeeds: false,

package/tools/version.mjs

@@ -29,8 +29,22 @@ import { planBump, latestVersion, formatVersion } from '../src/version.mjs'
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
 
+/**
+ * 🔴 git 은 **서 있는 저장소**에서 부른다. 프로그램이 있는 폴더가 아니다.
+ *
+ *    예전에는 `cwd: ROOT` 였다. 저장소 안에 사본을 두고 쓸 때는 그게 맞았다 —
+ *    사본이 곧 저장소 안이었기 때문이다. **npm 으로 설치하면 틀린다.**
+ *    `node_modules/axmap-cli/` 에서 git 을 부르게 되고, 거기는 저장소가 아니라서
+ *    "not a git repository" 로 죽는다. 실측: 설치본으로 `version next` → 종료 코드 1.
+ *
+ *    쪽지함이 이미 같은 실수를 했다 — 프로그램 위치로 데이터를 찾다가 "쪽지가
+ *    있어도 없다" 고 답했다 (tools/bus.mjs 의 주석). 같은 답을 쓴다: 위치를
+ *    묻지 말고 **서 있는 곳**에게 묻는다.
+ */
+const REPO = process.cwd()
+
 function git(args) {
-  const r = spawnSync('git', args, { cwd: ROOT, encoding: 'utf8', windowsHide: true })
+  const r = spawnSync('git', args, { cwd: REPO, encoding: 'utf8', windowsHide: true })
   return { code: r.status ?? 1, out: (r.stdout ?? '').trim(), err: (r.stderr ?? '').trim() }
 }