axmap-cli 0.0.1

package/app/lib/session.mjs

@@ -0,0 +1,389 @@
+/**
+ * 대화 세션 — 겉은 채팅, 속은 CLI 프로세스.
+ *
+ * 🔴 세션을 **화면이 아니라 여기(서버)가** 들고 있다.
+ *
+ * 요구는 하나였다: "앱이 느려져도 터미널에서의 작업은 정상이었으면 좋겠다."
+ * 그러려면 진행 중인 작업이 렌더러와 **아무 관계가 없어야** 한다.
+ * 그래서 이렇게 갈랐다.
+ *
+ *   프로세스를 띄우고 출력을 모으는 일   서버 (이 파일)
+ *   모인 것을 말풍선으로 그리는 일       화면
+ *
+ * 창을 닫아도, 그래프가 버벅여도, 렌더러가 죽어도 자식 프로세스는 계속 돈다.
+ * 화면은 나중에 붙어서 `?since=` 로 밀린 것을 받아 가면 된다.
+ *
+ * 🔴 그리고 **감추는 것은 터미널이지 결과가 아니다.**
+ *
+ * 사용자에게 "지금 CLI 를 쓰고 있다" 는 사실은 숨겨도 되지만, AI 가 어떤 파일을
+ * 고쳤는지는 숨기면 안 된다. 그것을 숨기는 순간 이 제품이 없애려던 공포
+ * (D1 의 F2 — "AI 가 뭘 망가뜨렸는지 모른다")를 이 제품이 직접 만들어내는 셈이 된다.
+ * 그래서 `touched` 를 따로 모아 화면이 반드시 띄우게 한다.
+ *
+ * 🔴 그리고 **세션마다 다른 사람이어야 한다.**
+ *
+ * 이 앱의 목적이 "여러 AI CLI 세션을 동시에 굴리는 것" 인데, 오랫동안 `spawn` 에
+ * `env` 옵션이 없어서 자식이 서버의 환경을 통째로 물려받았다. 그러면 세션이
+ * 몇 개든 전부 같은 `AXMAP_AGENT` 이고, `checkOverlap` 은 자기 claim 을 겹침으로
+ * 보지 않으므로 **서로를 하나도 못 막는다.** 이름을 정하는 규칙과 그 근거는
+ * `app/lib/slots.mjs` 머리말에 있다.
+ */
+
+import { randomUUID } from 'node:crypto'
+import { spawn } from 'node:child_process'
+import { agentById, argvFor, pickId, resolveBin } from './agentcli.mjs'
+import * as slots from './slots.mjs'
+
+/**
+ * 한 세션이 들고 있을 최대 메시지 수.
+ * 넘으면 오래된 것부터 버리되 **버렸다고 말한다** — 조용히 사라지면
+ * 사용자는 대화가 원래 그랬던 줄 안다.
+ */
+const MAX_MESSAGES = 2000
+
+/** 파일을 실제로 바꾸는 도구들. 이 이름이 보이면 `touched` 에 올린다. */
+const EDITORS = new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit', 'apply_patch', 'edit_file'])
+
+/**
+ * 대화가 아닌 이벤트들. 화면은 접어 두지만 기록은 남긴다.
+ * 실측에서 나온 것부터 넣었다 — 모르는 것은 여기 넣지 말고 `raw` 로 흘려보낸다.
+ */
+const NOT_CONVERSATION = new Set([
+  'system', 'rate_limit_event', 'stream_event', 'control_response', 'control_request',
+])
+
+const sessions = new Map()
+
+// ── 만들기 · 조회 ───────────────────────────────────────────────────────────
+
+export function create({ agent = 'claude', cwd = process.cwd(), title = '' } = {}) {
+  const spec = agentById(agent)
+  if (!spec) throw new Error(`모르는 에이전트: ${agent}`)
+  if (!resolveBin(spec.bin)) throw new Error(`${spec.name} 이(가) 이 PC 에 없습니다`)
+
+  const id = randomUUID()
+  /**
+   * 🔴 이름을 못 정하면 세션을 만들지 않는다.
+   *
+   * 이름 없이 띄우면 자식이 서버의 `AXMAP_AGENT` 를 그대로 물려받아 세션들이
+   * 다시 한 사람이 된다 — 이 파일 머리말의 그 버그다. 못 막는 것보다 못 띄우는
+   * 것이 낫다(fail-closed). 이유는 메시지에 그대로 실어 보낸다.
+   */
+  let seat
+  try {
+    seat = slots.acquire(cwd, { sessionId: id })
+  } catch (e) {
+    throw new Error(`세션 이름을 정하지 못해 시작하지 않았습니다: ${e.message}`)
+  }
+
+  const s = {
+    id,
+    agent,
+    agentName: spec.name,
+    /** 이 세션이 장부에서 누구인가. 자식에게 `AXMAP_AGENT` 로 넘어간다 */
+    axmapAgent: seat.agent,
+    slot: seat.slot,
+    cwd,
+    title: title || '새 대화',
+    /** CLI 쪽 대화 id. 이게 있어야 다음 턴이 앞 대화에 이어붙는다. */
+    cid: null,
+    state: 'idle',
+    error: null,
+    seq: 0,
+    messages: [],
+    /** path -> {tool, n} — AI 가 건드린 파일. 반드시 화면에 보인다 */
+    touched: new Map(),
+    dropped: 0,
+    startedAt: Date.now(),
+    proc: null,
+  }
+  sessions.set(s.id, s)
+  return view(s)
+}
+
+/**
+ * 자식에게 줄 환경.
+ *
+ * 🔴 `env` 를 주지 않으면 자식은 서버의 환경을 **통째로** 물려받는다. 그래서
+ * 여기가 이 파일에서 가장 중요한 세 줄이다 — 이 한 줄이 빠져 있는 동안 앱에서
+ * 띄운 세션은 몇 개든 장부에서 한 사람이었다.
+ *
+ * `process.env` 를 먼저 펼치는 이유: CLI 는 PATH·HOME·자격증명 경로·프록시
+ * 설정을 전부 환경에서 읽는다. 필요한 것만 골라 넘기면 어느 CLI 가 무엇을 읽는지
+ * 우리가 다 아는 척하는 것이고, 빠뜨리면 "왜 로그인이 안 되지" 로 돌아온다.
+ */
+export function childEnv(s, base = process.env) {
+  return { ...base, AXMAP_AGENT: s.axmapAgent }
+}
+
+export const get = (id) => sessions.get(id) ?? null
+
+/** 목록. 사이드바가 이걸 그린다 — 이 목록이 곧 "지금 살아 있는 터미널들" 이다. */
+export function list() {
+  return [...sessions.values()]
+    .sort((a, b) => b.startedAt - a.startedAt)
+    .map((s) => ({
+      id: s.id,
+      title: s.title,
+      agent: s.agent,
+      agentName: s.agentName,
+      // 사이드바가 "이 대화는 장부에서 누구인가" 를 그릴 수 있어야 한다.
+      // 이름을 사람이 읽는 것이 이 제품의 목적이라 UUID 대신 슬롯 번호를 쓴다.
+      axmapAgent: s.axmapAgent,
+      cwd: s.cwd,
+      state: s.state,
+      messages: s.messages.length,
+      touched: s.touched.size,
+      startedAt: s.startedAt,
+    }))
+}
+
+/** 화면에 주는 모양. `since` 뒤의 메시지만 준다 — 매번 전부 보내면 앱이 느려진다. */
+export function view(s, since = -1) {
+  return {
+    id: s.id,
+    title: s.title,
+    agent: s.agent,
+    agentName: s.agentName,
+    axmapAgent: s.axmapAgent,
+    cwd: s.cwd,
+    state: s.state,
+    error: s.error,
+    seq: s.seq,
+    dropped: s.dropped,
+    messages: s.messages.filter((m) => m.seq > since),
+    touched: [...s.touched.entries()].map(([file, v]) => ({ file, ...v })),
+  }
+}
+
+export function remove(id) {
+  const s = sessions.get(id)
+  if (!s) return false
+  stop(id)
+  sessions.delete(id)
+  // 슬롯을 즉시 돌려준다. 안 돌려주면 다음 세션이 `s3`, `s4` 로 번호만 커지고,
+  // 그러면 앱을 껐다 켤 때 이름이 달라져 두고 간 claim 을 반납할 수 없다.
+  releaseSeat(s)
+  return true
+}
+
+/** 슬롯 반납은 실패해도 세션 정리를 막지 않는다 — 죽은 pid 는 다음 acquire 가 걷어낸다. */
+function releaseSeat(s) {
+  try { slots.release(s.cwd, s.slot) } catch { /* 편의 기록이다. 여기서 죽을 이유가 없다 */ }
+}
+
+/** 진행 중인 턴을 끊는다. 세션 자체는 남는다 — 이어서 다시 물을 수 있다. */
+export function stop(id) {
+  const s = sessions.get(id)
+  if (!s?.proc) return false
+  try { s.proc.kill() } catch { /* 이미 죽었으면 그만 */ }
+  s.proc = null
+  s.state = 'idle'
+  push(s, { role: 'note', text: '중단했습니다.' })
+  return true
+}
+
+// ── 메시지 ──────────────────────────────────────────────────────────────────
+
+function push(s, m) {
+  s.messages.push({ seq: ++s.seq, at: Date.now(), ...m })
+  if (s.messages.length > MAX_MESSAGES) {
+    const cut = s.messages.length - MAX_MESSAGES
+    s.messages.splice(0, cut)
+    s.dropped += cut
+  }
+}
+
+// ── 한 턴 보내기 ────────────────────────────────────────────────────────────
+
+/**
+ * 프롬프트 하나를 보내고, 응답을 말풍선으로 쌓는다.
+ *
+ * 🔴 프롬프트를 **stdin 으로** 준다. 인자로 넘기면 따옴표·개행·백틱이 셸이나
+ * 인자 파서에 먹혀 **조용히 잘린다.** 사용자가 쓴 말이 반쯤 사라진 채 AI 에게
+ * 가는 것이라 최악의 실패다. stdin 은 그런 해석을 아예 안 거친다.
+ *
+ * 반환은 즉시 한다. 기다리지 않는다 — 화면이 뒤에서 `?since=` 로 받아 간다.
+ */
+export function send(id, prompt) {
+  const s = sessions.get(id)
+  if (!s) throw new Error('없는 세션입니다')
+  if (s.state === 'running') throw new Error('아직 앞의 답을 기다리는 중입니다')
+
+  const spec = agentById(s.agent)
+  const bin = resolveBin(spec.bin)
+  if (!bin) throw new Error(`${spec.name} 이(가) 이 PC 에 없습니다`)
+
+  push(s, { role: 'user', text: prompt })
+  if (s.title === '새 대화') s.title = prompt.slice(0, 40).replace(/\s+/g, ' ').trim()
+
+  // 이 CLI 가 세션 id 를 받는 쪽이면 우리가 만들어 박는다 (agentcli.mjs 참고).
+  const newId = spec.takesId ? randomUUID() : null
+  const argv = argvFor(spec, { cid: s.cid, newId })
+
+  s.state = 'running'
+  s.error = null
+
+  const proc = spawn(bin, argv, {
+    cwd: s.cwd,
+    windowsHide: true,
+    stdio: ['pipe', 'pipe', 'pipe'],
+    // 🔴 이 줄이 없으면 세션이 몇 개든 전부 같은 사람이 된다. childEnv 머리말 참고.
+    env: childEnv(s),
+  })
+  s.proc = proc
+  if (spec.takesId && !s.cid) s.cid = newId
+
+  let out = ''
+  let err = ''
+
+  proc.stdout.setEncoding('utf8')
+  proc.stdout.on('data', (chunk) => {
+    out += chunk
+    // JSONL 이다. 마지막 조각은 아직 안 끝났을 수 있으니 남겨 둔다.
+    const lines = out.split('\n')
+    out = lines.pop() ?? ''
+    for (const line of lines) if (line.trim()) feed(s, line.trim())
+  })
+
+  proc.stderr.setEncoding('utf8')
+  proc.stderr.on('data', (chunk) => { err += chunk })
+
+  proc.on('error', (e) => {
+    s.state = 'error'
+    s.error = e.message
+    s.proc = null
+    push(s, { role: 'error', text: `실행하지 못했습니다: ${e.message}` })
+  })
+
+  proc.on('close', (code) => {
+    if (out.trim()) feed(s, out.trim())
+    s.proc = null
+    if (code === 0) {
+      s.state = 'idle'
+      return
+    }
+    s.state = 'error'
+    /**
+     * 🔴 여기가 로그인 안 된 경우가 튀어나오는 자리다.
+     * 터미널을 감춰 놨으므로 그냥 두면 사용자에게는 **아무 일도 안 일어난 것**으로
+     * 보인다. stderr 를 그대로 올려서 최소한 무엇 때문인지는 보이게 한다.
+     */
+    s.error = err.trim() || `종료 코드 ${code}`
+    push(s, { role: 'error', text: s.error })
+  })
+
+  try {
+    proc.stdin.end(prompt, 'utf8')
+  } catch (e) {
+    s.state = 'error'
+    push(s, { role: 'error', text: `프롬프트를 넘기지 못했습니다: ${e.message}` })
+  }
+
+  return view(s, s.seq - 1)
+}
+
+// ── stream-json 읽기 ────────────────────────────────────────────────────────
+
+/**
+ * CLI 가 흘려주는 JSONL 한 줄을 말풍선으로 바꾼다.
+ *
+ * 🔴 못 읽은 줄을 **버리지 않는다.** 버리면 화면은 조용히 불완전한 대화를
+ * 보여주고 사용자는 그게 전부인 줄 안다. 모양이 낯설면 낯선 채로 올린다.
+ * (`애매하면 거부한다` 와 같은 이유 — CLAUDE.md)
+ */
+function feed(s, line) {
+  let ev
+  try { ev = JSON.parse(line) } catch {
+    push(s, { role: 'raw', text: line })
+    return
+  }
+
+  const cid = pickId(ev)
+  if (cid) s.cid = cid
+
+  /**
+   * 계측·제어 이벤트는 대화가 아니다.
+   *
+   * 🔴 그래도 **버리지는 않는다.** `meta` 로 올려서 화면이 접어 두게 한다.
+   * 실측에서 `rate_limit_event` 와 MCP 경고가 말풍선 사이에 그대로 끼어들었다 —
+   * 사용자에게는 AI 가 헛소리를 한 것처럼 보인다. 그렇다고 조용히 지우면
+   * 사용량 한도에 걸려 멈춘 것인지 알 방법이 없어진다. 접어 두는 것이 답이다.
+   */
+  if (NOT_CONVERSATION.has(ev.type)) { push(s, { role: 'meta', text: line }); return }
+
+  const content = ev.message?.content ?? ev.content
+  if (Array.isArray(content)) {
+    for (const b of content) block(s, b)
+    return
+  }
+
+  if (ev.type === 'result') {
+    // 최종 답. 앞서 assistant 블록으로 이미 올라온 것과 같은 내용이면 중복이므로 건너뛴다.
+    const last = s.messages[s.messages.length - 1]
+    const text = typeof ev.result === 'string' ? ev.result : null
+    if (text && last?.role === 'assistant' && last.text.trim() === text.trim()) return
+    if (text) push(s, { role: 'assistant', text })
+    if (ev.is_error) push(s, { role: 'error', text: '에이전트가 오류로 끝났습니다.' })
+    return
+  }
+
+  if (typeof ev.text === 'string') { push(s, { role: 'assistant', text: ev.text }); return }
+
+  push(s, { role: 'raw', text: line })
+}
+
+function block(s, b) {
+  if (!b || typeof b !== 'object') return
+
+  if (b.type === 'text' && b.text) { push(s, { role: 'assistant', text: b.text }); return }
+
+  if (b.type === 'tool_use') {
+    const file = b.input?.file_path ?? b.input?.path ?? null
+    const edits = EDITORS.has(b.name)
+
+    if (edits && file) {
+      const prev = s.touched.get(file)
+      s.touched.set(file, { tool: b.name, n: (prev?.n ?? 0) + 1 })
+    }
+
+    push(s, {
+      role: 'tool',
+      tool: b.name,
+      file,
+      /** 파일을 실제로 바꾼 도구인가. 화면이 이걸로 강조 여부를 정한다 */
+      edits,
+      text: summarize(b),
+    })
+    return
+  }
+
+  // tool_result 는 대개 길고 사람이 읽을 것이 아니다. 오류일 때만 올린다.
+  if (b.type === 'tool_result' && b.is_error) {
+    push(s, { role: 'error', text: String(b.content ?? '도구가 실패했습니다').slice(0, 500) })
+  }
+}
+
+/** 도구 한 번을 한 줄로. 사람이 읽을 수 있는 만큼만. */
+function summarize(b) {
+  const i = b.input ?? {}
+  if (i.file_path || i.path) return String(i.file_path ?? i.path)
+  if (i.command) return String(i.command).slice(0, 200)
+  if (i.pattern) return String(i.pattern).slice(0, 200)
+  if (i.query) return String(i.query).slice(0, 200)
+  if (i.prompt) return String(i.prompt).slice(0, 200)
+  return ''
+}
+
+/** 서버가 내려갈 때 자식들을 남기지 않는다. */
+export function shutdown() {
+  for (const s of sessions.values()) {
+    try { s.proc?.kill() } catch { /* 그만 */ }
+    /**
+     * 슬롯도 함께 비운다. 여기서 못 비워도(강제 종료·정전) 다음 실행이 죽은
+     * pid 를 보고 회수하므로 영구히 새지는 않는다 — 그것이 pid 를 적어둔 이유다.
+     * 그래도 정상 종료에서는 비워둔다. 그래야 다음에 켰을 때 s1 부터 다시 준다.
+     */
+    releaseSeat(s)
+  }
+}

package/app/lib/slots.mjs

@@ -0,0 +1,233 @@
+/**
+ * 세션마다 안정적인 고유 이름 — `<base>-s<N>`.
+ *
+ * 🔴 이 파일이 없던 동안 **앱에서 띄운 세션은 몇 개든 전부 같은 사람이었다.**
+ *
+ * `app/lib/session.mjs` 의 `spawn` 에 `env` 옵션이 없어서 자식이 `app/server.mjs`
+ * 의 환경을 그대로 물려받았다. 그러면 세 세션이 전부 같은 `AXMAP_AGENT` 로
+ * claim 하고, `checkOverlap` 은 **자기 claim 을 겹침으로 보지 않으므로**
+ * 서로를 하나도 못 막는다. 이 저장소가 `.mcp.json` 에서 뿌리뽑은 바로 그 실패가
+ * (SPEC §3 "에이전트 이름을 정하는 순서") 앱 안에서 되살아나 있었다.
+ * "혼자서 에이전트 여러 개" 가 실제로 일어나는 곳이 여기다.
+ *
+ * ── 이름을 왜 이렇게 짓는가 ────────────────────────────────────────────────
+ *
+ * `base` 는 `live.mjs` 의 `whoAmI()` 가 정한다. **여기서 다시 구현하지 않는다.**
+ * 두 곳이 갈리면 CLI 는 `A` 로 claim 했는데 화면이 그것을 남의 것으로 칠한다.
+ *
+ * 랜덤 UUID 를 쓰지 않는다. 이 제품의 목적이 "누가 무엇을 잡았는지 **사람이 보는
+ * 것**" 이므로 화면에 `f47ac10b-…-s?` 가 뜨면 목적에 정면으로 반한다.
+ * `janghyojoon-s2` 는 읽는 순간 누구인지 안다.
+ *
+ * ── 슬롯 레지스트리(`<repo>/.axmap/sessions.json`)가 왜 필요한가 ───────────
+ *
+ * 세션 id(UUID)를 이름으로 쓰면 앱을 껐다 켤 때마다 이름이 바뀐다. 그러면
+ * **앱이 죽으며 두고 간 claim 을 아무도 반납할 수 없다** — `release` 는 이름이
+ * 다르므로 종료 코드 5 를 내고, 그동안 TTL 이 다 갈 때까지 남의 영역이 막힌다.
+ *
+ * 슬롯 번호는 pid 로 회수되므로 앱을 껐다 켜면 옛 pid 가 죽어 슬롯이 전부 비고
+ * 첫 세션이 다시 `s1` 을 받는다. **이름이 재시작을 넘어 안정적**이라는 뜻이고,
+ * 그래서 다시 켠 세션이 자기가 두고 간 claim 을 그대로 반납할 수 있다.
+ *
+ * pid 를 기록하는 이유는 **앱을 두 개 띄웠을 때**다. 그때 둘 다 `s1` 을 잡으면
+ * 이름 충돌이 그대로 돌아온다. 살아있는 pid 의 슬롯은 절대 뺏지 않는다.
+ *
+ * ── 이 파일은 fail-closed 의 예외다 ────────────────────────────────────────
+ *
+ * 레지스트리가 없거나 깨져 있으면 **빈 것으로 시작한다.** 장부 레코드였다면
+ * 전체를 중단해야 하지만(SPEC §6) 이것은 락이 아니라 **편의 기록**이다.
+ * 여기서 중단하면 얻는 것 없이 앱이 세션을 하나도 못 띄운다. 반대로 빈 것으로
+ * 시작해서 생기는 최악은 "살아있는 앱의 슬롯을 잊고 같은 번호를 준다" 인데,
+ * 그것은 아래 `alive()` 가 죽은 pid 만 버리는 것과 acquire 직후의 I7 검사가 막는다.
+ * 판정을 바꾸지 않는 기록에까지 fail-closed 를 적용하면 원칙이 아니라 미신이 된다.
+ *
+ * 다만 **이름을 정하지 못하는 것은 다르다.** 이름 없이 세션을 띄우면 그 순간
+ * 위의 버그가 그대로 돌아오므로, `acquire` 가 실패하면 세션을 만들지 않는다.
+ */
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { whoAmI } from './live.mjs'
+import { sessionIdentityViolations } from '../../src/invariants.mjs'
+
+/** `.axmap/` 는 이미 gitignore 다. 새 항목을 만들지 않는다. */
+const REGISTRY_REL = path.join('.axmap', 'sessions.json')
+
+/**
+ * `whoAmI()` 가 아무것도 못 찾았을 때의 이름.
+ *
+ * CLI 는 이름을 모르면 die 하지만(치환이 곧 소유권 충돌이므로) 여기서는 다르다.
+ * 슬롯 번호가 붙어 **세션끼리는 어차피 서로 다른 이름**이 되므로, 같은 이름이
+ * 되어 서로를 못 막는 그 실패는 일어나지 않는다. 사람 이름을 못 찾은 것은
+ * 화면에서 `agent-s1` 로 보이는 불편이지 상호배제의 구멍이 아니다.
+ */
+const FALLBACK_BASE = 'agent'
+
+export function registryPath(repoRoot) {
+  return path.join(repoRoot, REGISTRY_REL)
+}
+
+/** 이 저장소에서 '나'. 순서는 CLI·MCP·화면과 같아야 하므로 live.mjs 것을 그대로 쓴다. */
+export function baseName(repoRoot) {
+  return whoAmI(repoRoot) || FALLBACK_BASE
+}
+
+export function sessionAgentName(base, slot) {
+  return `${base}-s${slot}`
+}
+
+/**
+ * 이 pid 가 아직 살아 있는가. `process.kill(pid, 0)` 은 신호를 보내지 않고
+ * 존재만 확인하며, 윈도우에서도 동작한다.
+ *
+ * 🔴 `EPERM` 은 **살아 있는 것**이다. 다른 사용자의 프로세스라 신호를 못 보낼
+ * 뿐 존재는 한다. 여기서 죽었다고 보면 남이 쓰는 슬롯을 뺏어 같은 이름이 둘
+ * 생긴다 — 애매하면 뺏지 않는 쪽이 맞다.
+ */
+export function alive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (e) {
+    return e?.code === 'EPERM'
+  }
+}
+
+/** 레지스트리를 읽는다. 없거나 깨졌으면 빈 것 (머리말의 "fail-closed 의 예외"). */
+export function readRegistry(repoRoot) {
+  let raw
+  try {
+    raw = fs.readFileSync(registryPath(repoRoot), 'utf8')
+  } catch {
+    return {}
+  }
+  try {
+    const j = JSON.parse(raw)
+    const slots = j?.slots
+    return slots && typeof slots === 'object' && !Array.isArray(slots) ? slots : {}
+  } catch {
+    return {}
+  }
+}
+
+/**
+ * 파일 하나를 원자적으로 쓴다 — 임시 파일에 다 쓴 뒤 같은 디렉터리에서 rename.
+ *
+ * 방식과 이유는 `bin/axmap.mjs` 의 `writeFileAtomic` 머리말에 적혀 있다. 요약하면
+ * `writeFileSync` 는 호출 하나로 보여도 커널이 여러 번에 나눠 쓸 수 있고, 그 사이에
+ * 다른 앱 인스턴스가 이 파일을 읽으면 **반쯤 쓰인 JSON** 을 본다. 그러면 위 규칙에
+ * 따라 빈 것으로 시작하고, 살아있는 슬롯을 잊어 같은 번호를 두 번 준다.
+ * 같은 디렉터리 안의 rename 은 같은 파일시스템이라 원자적이다.
+ */
+function writeFileAtomic(target, data) {
+  const tmp = `${target}.tmp-${process.pid}`
+  try {
+    fs.writeFileSync(tmp, data)
+    fs.renameSync(tmp, target)
+  } catch (e) {
+    try { fs.rmSync(tmp, { force: true }) } catch { /* 원래 원인을 가리지 않는다 */ }
+    throw e
+  }
+}
+
+function writeRegistry(repoRoot, slots) {
+  const file = registryPath(repoRoot)
+  fs.mkdirSync(path.dirname(file), { recursive: true })
+  writeFileAtomic(file, JSON.stringify({ slots }, null, 2) + '\n')
+}
+
+/**
+ * 죽은 항목을 버리고 **가장 작은 빈 번호**를 준다. 순수 함수다 —
+ * `isAlive` 를 인자로 받으므로 진짜 프로세스 없이도 회수 규칙을 검증할 수 있다.
+ * (시각도 인자로 받는다. CLAUDE.md "시각은 항상 인자로 받는다")
+ *
+ * 가장 작은 빈 번호인 이유: 앱을 껐다 켜면 슬롯이 전부 비므로 첫 세션이 다시
+ * `s1` 을 받는다. 번호를 계속 키우면 재시작마다 이름이 달라져 두고 간 claim 을
+ * 반납할 수 없게 되고, 그것이 이 레지스트리를 만든 이유 자체를 무너뜨린다.
+ */
+export function allocate(slots, { sessionId, agentFor, pid, now, isAlive = alive }) {
+  const live = {}
+  for (const [k, v] of Object.entries(slots ?? {})) {
+    const n = Number(k)
+    // 번호가 아닌 키는 이 파일을 손으로 고친 흔적이다. 편의 기록이므로 버린다.
+    if (!Number.isInteger(n) || n < 1) continue
+    if (!v || typeof v !== 'object') continue
+    if (!isAlive(v.pid)) continue
+    live[String(n)] = v
+  }
+  let slot = 1
+  while (live[String(slot)]) slot++
+  live[String(slot)] = {
+    pid,
+    sessionId,
+    since: new Date(now).toISOString(),
+    /**
+     * 확정된 이름을 함께 적는다. 번호만 적으면 이름을 읽는 쪽이 `base` 를 다시
+     * 계산해야 하는데, 그 `base` 는 **그 프로세스의 환경**에서 나온다 —
+     * 앱을 두 개 띄우면 두 인스턴스가 같은 슬롯에 대해 서로 다른 이름을 말하게
+     * 되고, 그러면 I7 을 검사할 방법 자체가 없어진다.
+     */
+    agent: agentFor(slot),
+  }
+  return { slot, slots: live }
+}
+
+/** 레지스트리 한 장을 I7 검사기가 읽을 모양으로. */
+function sessionsOf(slots) {
+  return Object.entries(slots).map(([n, v]) => ({
+    id: v?.sessionId ?? `slot-${n}`,
+    agent: v?.agent ?? null,
+    pid: v?.pid ?? null,
+  }))
+}
+
+/**
+ * 슬롯 하나를 잡고 이 세션의 `AXMAP_AGENT` 를 확정한다.
+ *
+ * 실패하면 던진다. 이름 없이 세션을 띄우면 자식이 서버의 이름을 그대로 물려받아
+ * 세션들이 다시 한 사람이 되므로, **이름을 못 정하는 것은 세션을 못 만드는 것**이다.
+ */
+export function acquire(repoRoot, { sessionId, pid = process.pid, now = Date.now(), isAlive = alive } = {}) {
+  const base = baseName(repoRoot)
+  const { slot, slots } = allocate(readRegistry(repoRoot), {
+    sessionId,
+    agentFor: (n) => sessionAgentName(base, n),
+    pid,
+    now,
+    isAlive,
+  })
+
+  /**
+   * I7 을 잡은 자리에서 바로 확인한다 (docs/INVARIANTS.md).
+   * 검사기는 모델 검증기·감사와 같은 `src/invariants.mjs` 를 쓴다 — 도구마다
+   * 판정이 다르면 무엇이 맞는지 알 수 없게 된다.
+   */
+  const bad = sessionIdentityViolations(sessionsOf(slots))
+  if (bad.length) {
+    throw new Error(
+      '세션 이름이 겹쳤습니다 (I7 위반). 이 상태로 띄우면 두 세션이 서로를 막지 못합니다.\n' +
+        bad.map((v) => `  ${v.message}`).join('\n'),
+    )
+  }
+
+  writeRegistry(repoRoot, slots)
+  return { slot, agent: sessionAgentName(base, slot), base }
+}
+
+/**
+ * 슬롯을 반납한다.
+ *
+ * 🔴 **내 pid 의 것만 지운다.** 앱이 두 개일 때, 내가 들고 있다고 믿는 번호를
+ * 그 사이 다른 인스턴스가 (내 pid 가 죽은 줄 알고) 가져갔을 수 있다. 그것을
+ * 지우면 살아있는 남의 슬롯을 비우는 것이고, 다음 세션이 같은 이름을 받는다.
+ */
+export function release(repoRoot, slot, { pid = process.pid } = {}) {
+  const slots = readRegistry(repoRoot)
+  const key = String(slot)
+  const cur = slots[key]
+  if (!cur || cur.pid !== pid) return false
+  delete slots[key]
+  writeRegistry(repoRoot, slots)
+  return true
+}