axmap-cli 1.0.3 → 1.1.1

package/bin/axmap.mjs

@@ -11,6 +11,7 @@
  */
 
 import { spawnSync } from 'node:child_process'
+import crypto from 'node:crypto'
 import fs from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
@@ -20,17 +21,18 @@ import {
   applyRenew,
   coversPath,
   formatBlocks,
-  formatSessionConflict,
+  formatOtherSessions,
   shortSession,
   humanDuration,
   normalizePath,
   activeClaims,
   claimExpiresAt,
-  myActiveClaim,
+  isSameSubject,
+  myActivePaths,
   agentNameError,
   claimPathError,
 } from '../src/protocol.mjs'
-import { auditLedger, formatAudit } from '../src/invariants.mjs'
+import { auditLedger, formatAudit, planAudit, snapshotTime } from '../src/invariants.mjs'
 import {
   PACKAGE_NAME,
   fetchLatest,
@@ -126,6 +128,27 @@ const BUS_REL = path.join('.axmap', 'bus')
  */
 const USERS_BRANCH = 'axmap/users'
 const USERS_REL = path.join('.axmap', 'users')
+
+/**
+ * 감사 체크포인트가 사는 곳 — *"장부를 뿌리부터 여기까지 재생했고 깨끗했다"* 는 기록.
+ *
+ * 🔴 **장부 브랜치에 넣지 않는다.** 장부(`axmap/claims`)는 선점의 진실이고,
+ *    거기에 감사 결과가 섞이면 claim 한 번에 커밋이 둘 생기거나(경합이 두 배)
+ *    감사가 자기가 검사하는 이력을 자기가 늘리게 된다. 검사 대상과 검사 결과는
+ *    같은 자리에 두지 않는다.
+ *
+ * 🔴 **worktree 를 만들지 않는다.** 쪽지함·사람별 상태와 다른 점이다.
+ *    이것을 쓰는 자리는 팀 CI 의 감사 잡이고, CI 는 신선한 clone 이라 `.axmap/`
+ *    아래에 아무것도 없다. 읽는 것도 쓰는 것도 git 배관(hash-object · mktree ·
+ *    commit-tree)으로 하면 폴더가 필요 없고, 그러면 **각자 PC 와 CI 가 같은
+ *    한 길**을 쓴다. 길이 둘이면 반드시 한쪽만 고쳐진다.
+ *
+ * 파일은 하나(`checkpoints.json`)다. 쪽지처럼 사람마다 갈릴 것이 없고, 쓰는 일이
+ * 드물어(감사가 통과할 때만) 경합이 거의 없다 — 부딪히면 다시 받아서 얹는다.
+ */
+const CHECKPOINT_BRANCH = 'axmap/checkpoints'
+const CHECKPOINT_FILE = 'checkpoints.json'
+
 /**
  * `release` 가 아무것도 반납하지 못했을 때. SPEC 8절.
  * 0 이 아니어야 하는 이유는 그 주변 주석에 적혀 있다.
@@ -153,6 +176,14 @@ const GIT_ENV_KEYS = [
   'GIT_PREFIX',
 ]
 
+/**
+ * 눈에 안 보이는 두 글자와 탭. git 의 `%x00` 구분자와 줄바꿈을 소스에 그대로
+ * 적지 않는 이유는 편집기·패치마다 사라지거나 바뀌기 때문이다.
+ */
+const NUL = String.fromCharCode(0)
+const NL = String.fromCharCode(10)
+const TAB = String.fromCharCode(9)
+
 function cleanEnv(keep = []) {
   const e = { ...process.env }
   for (const k of GIT_ENV_KEYS) if (!keep.includes(k)) delete e[k]
@@ -832,19 +863,29 @@ function resolveSessionId(flags) {
 }
 
 /**
- * 세션을 확인할 수 없을 때 한 번만 알린다.
+ * 물러난 깃발 `--takeover` 를 만났을 때.
+ *
+ * 🔴 **그냥 무시하면 안 된다.** `parseArgs` 는 모르는 깃발을 조용히 흘려보내는데,
+ *    `--takeover ci` 처럼 쓰면 뒤 낱말을 값으로 삼켜 **경로 하나가 통째로 사라진다.**
+ *    그래서 여기서 `boolFlag` 로 한 번 걸러 그 사고부터 막는다.
+ *
+ * 이 깃발은 "같은 이름의 다른 세션에게서 레코드를 넘겨받는다" 는 뜻이었다.
+ * 이제 세션마다 레코드가 따로라 넘겨받을 것이 없다. release 에서만 뜻이 남아
+ * `--all-sessions` 로 이름이 바뀌었다.
  *
- * 🔴 **조용히 넘어가지 않는다.** 이 결함의 피해는 "덮어썼다" 가 아니라
- *    "덮어썼는데 아무도 몰랐다" 였다. 막을 근거가 없을 때 할 수 있는 최소한은
- *    무엇이 일어나는지를 말하는 것이다.
+ * @returns {boolean} release 에서 `--all-sessions` 로 이어줄지
  */
-function warnUnverifiableSession(me, prevPaths) {
+function warnRetiredTakeover(flags, command) {
+  if (!boolFlag(flags.takeover, 'takeover')) return false
+  if (command === 'release') {
+    console.error('알림: --takeover 는 --all-sessions 로 이름이 바뀌었습니다. 이번에는 그것으로 처리합니다.')
+    return true
+  }
   console.error(
-    `알림: "${me}" 의 유효한 claim 이 이미 있습니다 (경로 ${prevPaths}개). 덮지 않고 여기에 더합니다.\n` +
-      '      이 실행이 그 claim 을 만든 세션과 같은 세션인지는 확인하지 못했습니다\n' +
-      `      (${sessionFrom ? `내 세션은 ${sessionFrom} 에서 왔지만 레코드에 세션 표식이 없습니다` : 'AXMAP_SESSION 도 CLAUDE_CODE_SESSION_ID 도 없습니다'}).\n` +
-      '      한 PC 에서 세션을 여럿 굴린다면 세션마다 AXMAP_SESSION 을 다르게 주세요.',
+    '알림: --takeover 는 이제 필요 없습니다 — 세션마다 레코드가 따로 적히므로 넘겨받을 것이 없습니다.\n' +
+      '      claim 은 그대로 진행합니다.',
   )
+  return false
 }
 
 /**
@@ -1039,10 +1080,49 @@ function readClaims(root) {
     })
 }
 
-// 에이전트 이름은 agentNameError() 로 이미 검증되었으므로 그대로 파일명이 된다.
-// 여기서 문자를 치환하면 서로 다른 이름이 같은 파일을 가리킬 수 있다.
-function claimPath(root, agent) {
-  return path.join(claimsDir(root), `${agent}.json`)
+/**
+ * 레코드 하나가 앉을 파일.
+ *
+ * 에이전트 이름은 agentNameError() 로 이미 검증되었으므로 그대로 파일명이 된다.
+ * 여기서 문자를 치환하면 서로 다른 이름이 같은 파일을 가리킬 수 있다.
+ *
+ * 🔴 **세션마다 다른 파일이다.** 한 파일에 이름 하나면 두 번째 창이 적는 순간
+ *    첫 창의 줄이 사라진다 — 그것이 이 판의 결함이었다 (protocol.mjs `isSameSubject`).
+ *
+ * 세션 id 는 **그대로 파일명에 못 쓴다.** 값이 환경변수에서 오므로 슬래시든
+ * 무엇이든 들어올 수 있고, 이름 검증을 거치지 않는다. 그래서 짧게 해싱한다 —
+ * 파일명은 자리를 가르기만 하면 되고, 진짜 값은 파일 **안**에 그대로 들어 있다.
+ * 세션을 모르는 레코드는 예전과 같은 `<이름>.json` 이라 옛 장부와 그대로 맞물린다.
+ */
+function claimPath(root, agent, session = null) {
+  if (!session) return path.join(claimsDir(root), `${agent}.json`)
+  const h = crypto.createHash('sha256').update(String(session)).digest('hex').slice(0, 8)
+  return path.join(claimsDir(root), `${agent}@${h}.json`)
+}
+
+/**
+ * 같은 (이름, 세션) 짝의 레코드 파일을 **전부** 지운다. `keep` 만 남긴다.
+ *
+ * 🔴 파일명을 계산해서 지우는 것만으로는 부족하다. 세션 표식이 있는 레코드가
+ *    옛 이름(`<이름>.json`)에 들어 있는 장부가 이미 돌아다니기 때문이다.
+ *    그것을 안 지우면 같은 임자의 줄이 둘로 보이고, 지운 줄 알았던 것이 남는다.
+ *    그래서 **파일 안을 열어보고** 임자가 같으면 지운다.
+ */
+function removeClaimFiles(root, agent, session, keep = null) {
+  const dir = claimsDir(root)
+  if (!fs.existsSync(dir)) return
+  for (const f of fs.readdirSync(dir)) {
+    if (!f.endsWith('.json')) continue
+    const full = path.join(dir, f)
+    if (keep && path.resolve(full) === path.resolve(keep)) continue
+    let rec
+    try {
+      rec = JSON.parse(fs.readFileSync(full, 'utf8'))
+    } catch {
+      continue // 깨진 파일은 readClaims 가 fail-closed 로 잡는다. 여기서 지우면 증거가 사라진다.
+    }
+    if (isSameSubject(rec, agent, session ?? null)) fs.rmSync(full, { force: true })
+  }
 }
 
 /**
@@ -1097,11 +1177,10 @@ function ensureLedgerIgnore(root) {
 function writeClaim(root, claim) {
   fs.mkdirSync(claimsDir(root), { recursive: true })
   ensureLedgerIgnore(root)
-  writeFileAtomic(claimPath(root, claim.agent), JSON.stringify(claim, null, 2) + '\n')
-}
-
-function myClaim(root, agent) {
-  return readClaims(root).find((c) => c.agent === agent) ?? null
+  const target = claimPath(root, claim.agent, claim.session)
+  // 같은 임자의 줄이 옛 이름으로 남아 있으면 지운다. 안 그러면 장부에 같은 줄이 둘이다.
+  removeClaimFiles(root, claim.agent, claim.session ?? null, target)
+  writeFileAtomic(target, JSON.stringify(claim, null, 2) + '\n')
 }
 
 /**
@@ -1371,7 +1450,7 @@ function cmdClaim(positional, flags) {
   requireLedger(root)
   const me = agentName(flags)
   const session = resolveSessionId(flags)
-  const takeover = boolFlag(flags.takeover, 'takeover')
+  warnRetiredTakeover(flags, 'claim')
   if (!positional.length) die('claim 할 경로를 하나 이상 지정하세요.\n  axmap claim src/auth --task task-12')
   for (const p of positional) {
     const err = claimPathError(p)
@@ -1409,36 +1488,23 @@ function cmdClaim(positional, flags) {
       // 정하는 필드라 피해가 작지만, 원칙에 예외를 두면 그 예외가 기준이 된다.
       actor: resolveActor(flags.actor),
       session,
-      takeover,
     })
     if (!res.ok) {
-      /**
-       * 두 가지 거부가 있고 **둘 다 종료 코드 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))
-      }
+      // 거부는 종료 코드 2 다 (SPEC 8절). 재시도하지 말고 방향을 바꾸라는 뜻이다.
+      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)
+    if (res.otherSessions.length) {
+      console.error(formatOtherSessions(res.otherSessions, want, t))
+      console.error(`      (이 세션의 id 는 ${sessionFrom ?? '어디에서도 오지 않았습니다'})`)
     }
     // push 실패 시 되돌아갈 지점. 커밋을 만들기 **전에** 잡아둔다.
     const before = ledgerHead(root)
     // 커밋 전에 실패할 수도 있다. 그때는 HEAD 가 아니라 이 파일을 되돌려야 한다.
-    const myFile = claimPath(root, me)
+    const myFile = claimPath(root, me, session)
     const myFileBefore = fs.existsSync(myFile) ? fs.readFileSync(myFile) : null
     writeClaim(root, res.record)
 
@@ -1495,23 +1561,17 @@ function cmdRelease(positional, flags) {
   requireLedger(root)
   const me = agentName(flags)
   const session = resolveSessionId(flags)
-  const takeover = boolFlag(flags.takeover, 'takeover')
+  // 다른 세션이 잡은 것까지 함께 푸는 문. 기본은 **이 세션이 잡은 것만**이다.
+  // 둘을 각각 먼저 읽는다. `||` 로 이으면 앞이 참일 때 뒤가 안 불리고,
+  // 그러면 `--takeover` 가 뒤 낱말을 삼키는 것을 못 잡는다 (warnRetiredTakeover 참고).
+  const retired = warnRetiredTakeover(flags, 'release')
+  const allSessions = boolFlag(flags['all-sessions'], 'all-sessions') || retired
   const drop = positional.map(normalizePath)
 
   for (let attempt = 1; attempt <= MAX_CAS_RETRIES; attempt++) {
     syncLedger(root)
-    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)
-    }
+    // 🔴 release 는 시계를 안 본다. 만료된 껍데기도 반납 대상이다 — 지우는 것이 곧 정리다.
+    const res = applyRelease({ claims: readClaims(root), me, drop, session, allSessions })
     if (res.hadNothing) {
       /**
        * 🔴 반납을 시켰는데 아무것도 반납 안 된 것은 **성공이 아니다.**
@@ -1525,8 +1585,24 @@ function cmdRelease(positional, flags) {
        * 조용히 통과시키는 것이 가장 나쁜 실패다.
        */
       const others = readClaims(root).filter((c) => c.agent !== me)
-      console.error(`반납할 것이 없습니다 — "${me}" 이(가) 잡고 있는 경로가 하나도 없습니다.`)
+      console.error(`반납할 것이 없습니다 — "${me}" 이(가) 이 세션에서 잡고 있는 경로가 하나도 없습니다.`)
       console.error(`  이 이름은 ${agentFrom} 에서 왔습니다.`)
+      /**
+       * 🔴 **이름은 맞는데 세션이 달라서 못 찾은 경우를 따로 말한다.**
+       *    둘을 같은 말로 내면 이름을 고치는 엉뚱한 처방으로 간다. 여기서는
+       *    이름이 아니라 **어느 창이 잡았는가**가 원인이다.
+       */
+      if (res.otherSessions.length) {
+        console.error('')
+        console.error(`  같은 이름 "${me}" 을(를) 잡고 있는 것은 있습니다 — 다른 세션이 적은 줄입니다:`)
+        for (const c of res.otherSessions) {
+          console.error(`    세션 ${shortSession(c.session)}${c.task ? ` [${c.task}]` : ''}  경로 ${c.paths.length}개`)
+        }
+        console.error(`  (이 세션의 id 는 ${sessionFrom ?? '어디에서도 오지 않았습니다'})`)
+        console.error('')
+        console.error('  그것까지 풀려면 --all-sessions 를 붙이세요.')
+        console.error('  저 창이 아직 살아 있다면 풀지 마세요 — 저쪽은 자기가 쥐고 있다고 믿습니다.')
+      }
       if (others.length) {
         console.error('')
         console.error('  장부에는 다른 이름으로 잡힌 것이 있습니다:')
@@ -1540,12 +1616,13 @@ function cmdRelease(positional, flags) {
     if (res.unheld.length) {
       console.error(`알림: 잡고 있지 않은 경로는 무시합니다: ${res.unheld.join(', ')}`)
     }
-    if (res.record) writeClaim(root, res.record)
-    else fs.rmSync(claimPath(root, me), { force: true })
+    for (const r of res.records) writeClaim(root, r)
+    // 지우는 것도 파일명 계산이 아니라 **내용으로** 찾아 지운다 (removeClaimFiles 참고).
+    for (const r of res.removed) removeClaimFiles(root, r.agent, r.session ?? null)
 
     const pushed = commitAndPush(root, `release(${me}): ${drop.length ? drop.join(' ') : 'all'}`)
     if (pushed === 'ok' || pushed === 'nothing') {
-      const left = res.record?.paths.length ?? 0
+      const left = res.records.reduce((n, r) => n + r.paths.length, 0)
       console.log(`release 완료 - ${me}${left ? ` (남은 ${left}개)` : ' (전부 반납)'}`)
       return
     }
@@ -1567,23 +1644,22 @@ function cmdRenew(flags) {
     syncLedger(root)
     const t = now()
     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` +
-          'TTL 이 이미 만료되었다면 그 사이 다른 에이전트가 가져갔을 수 있습니다.\n' +
-          'axmap claim 으로 다시 선점하세요 (겹침 검사를 다시 거칩니다).',
-      )
+      let msg =
+        `${me} 의 유효한 claim 이 이 세션에는 없습니다.\n` +
+        'TTL 이 이미 만료되었다면 그 사이 다른 에이전트가 가져갔을 수 있습니다.\n' +
+        'axmap claim 으로 다시 선점하세요 (겹침 검사를 다시 거칩니다).'
+      // 같은 이름의 다른 창이 잡고 있는 것이라면 처방이 다르다 — 다시 잡는 게 아니라
+      // 그 세션이라고 말하고 늘리는 것이다. 안 알려주면 두 번 잡게 된다.
+      if (res.otherSessions.length) {
+        msg += '\n\n같은 이름의 다른 세션이 잡고 있는 것은 있습니다:'
+        for (const c of res.otherSessions) {
+          msg += `\n  세션 ${shortSession(c.session)}${c.task ? ` [${c.task}]` : ''}  경로 ${c.paths.length}개`
+        }
+        msg += '\n그 세션의 것을 늘리려면 --session <그 세션 id> 로 그 세션이라고 말하세요.'
+        msg += '\n저 창이 이미 끝난 것이면 늘리지 마세요 — 늘린 만큼 아무도 안 쓰는 경로가 막힙니다.'
+      }
+      die(msg)
     }
     writeClaim(root, res.record)
     const pushed = commitAndPush(root, `renew(${me})`)
@@ -1640,8 +1716,9 @@ 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)} 남음`)
@@ -1709,8 +1786,13 @@ function cmdVerify(flags) {
 
   if (!staged.length) return
 
-  const mine = myActiveClaim(readClaims(root), me, now())
-  const paths = mine?.paths ?? []
+  /**
+   * 🔴 여기만 **사람 단위**로 본다 (세션이 아니라 이름 전체).
+   *
+   * 커밋하는 것은 세션이 아니라 사람이다. A 창에서 잡고 B 창에서 커밋하는 것은
+   * 원래 되던 일이고, 여기까지 세션으로 좁히면 고치려던 것보다 큰 고장이 된다.
+   */
+  const paths = myActivePaths(readClaims(root), me, now())
   const uncovered = staged.filter((f) => !coversPath(paths, f))
 
   if (uncovered.length) {
@@ -1746,8 +1828,6 @@ function collectCodeCommits(root, range) {
     console.log(`구간에 빈 sha 가 있습니다 (${range}) - 첫 push 로 보고 코드 대조를 건너뜁니다.`)
     return null
   }
-  const NUL = String.fromCharCode(0)
-  const NL = String.fromCharCode(10)
   const log = git(['log', '--no-merges', '--format=%H%x00%an%x00%ct%x00%s', range], { cwd: root })
   if (log.code !== 0) {
     // 🔴 못 읽은 것을 통과로 내지 않는다. 조용히 빈 배열을 주면 "위반 0" 이 된다.
@@ -1782,10 +1862,152 @@ function collectCodeCommits(root, range) {
 }
 
 
+// ---------------------------------------------------------------------------
+// 감사 체크포인트 — "여기까지는 이미 재생해서 깨끗함을 봤다"
+//
+// 왜 필요한지와 왜 이력을 버리지 않는지는 src/invariants.mjs 의 planAudit 위에 있다.
+// 여기 있는 것은 그 기록을 git 에 넣고 빼는 배관뿐이다.
+// ---------------------------------------------------------------------------
+
+/**
+ * 체크포인트 브랜치의 끝을 **sha 로 굳혀서** 돌려준다. 없으면 null.
+ *
+ * FETCH_HEAD 는 worktree 마다 따로 보관되고 다음 fetch 가 덮어쓴다. 그래서 받자마자
+ * sha 로 바꾼다 — 이 값은 그 뒤 어느 폴더에서 써도 같다 (한 저장소의 worktree 들은
+ * 객체 저장소를 공유한다).
+ */
+function checkpointTip(root, { fetch }) {
+  if (fetch) {
+    const r = resolveRemote(root)
+    const remote = r.source === 'ambiguous' ? null : r.name
+    if (remote && git(['fetch', '--quiet', remote, CHECKPOINT_BRANCH], { cwd: root }).code === 0) {
+      const h = git(['rev-parse', 'FETCH_HEAD'], { cwd: root })
+      if (h.code === 0 && h.out) return h.out
+    }
+    /**
+     * 못 받았으면 **아직 아무도 체크포인트를 안 남겼다**로 읽는다.
+     * 원격이 죽은 경우는 장부를 받는 자리에서 이미 멈춰 있고(거기가 fail-closed),
+     * 여기서 잘못 판단해도 대가는 "처음부터 다 재생한다" 뿐이다 — 느려질 뿐
+     * 통과가 헐거워지지 않는다.
+     */
+  }
+  const local = git(['rev-parse', '--verify', '--quiet', CHECKPOINT_BRANCH], { cwd: root })
+  return local.code === 0 && local.out ? local.out : null
+}
+
+/**
+ * 체크포인트 목록을 읽는다. **깨져 있으면 멈춘다** (fail-closed).
+ *
+ * 조용히 빈 목록으로 넘기면 그냥 느려질 뿐이라 무해해 보이지만 아니다 —
+ * 이 목록이 **면제(amnesty) 경계**를 정한다. 없는 것으로 만들면 봐주는 범위가
+ * 통째로 달라진다. 판정 범위를 정하는 입력은 못 읽었을 때 추측하지 않는다.
+ */
+function readCheckpoints(cwd, tipSha) {
+  if (!tipSha) return []
+  const r = git(['show', `${tipSha}:${CHECKPOINT_FILE}`], { cwd })
+  if (r.code !== 0) return [] // 브랜치는 있는데 파일이 없다 = 아직 하나도 안 적혔다
+  let doc
+  try {
+    doc = JSON.parse(r.out)
+  } catch (e) {
+    die(
+      `체크포인트를 읽을 수 없습니다 (${CHECKPOINT_BRANCH}:${CHECKPOINT_FILE})` +
+        NL + e.message + NL + NL +
+        '어디서부터 재생할지 정할 수 없으므로 중단합니다 — 검사하지 못한 것을 통과로 내지 않습니다.',
+    )
+  }
+  const list = Array.isArray(doc?.checkpoints) ? doc.checkpoints : null
+  if (!list) {
+    die(`체크포인트 파일에 checkpoints 배열이 없습니다 (${CHECKPOINT_BRANCH}:${CHECKPOINT_FILE}).`)
+  }
+  for (const c of list) {
+    if (!/^[0-9a-f]{40}$/.test(c?.ledger ?? '') || !Number.isFinite(c?.time)) {
+      die(
+        `체크포인트 항목이 망가졌습니다: ${JSON.stringify(c)}` + NL +
+          '필요: ledger(장부 커밋 sha 40자) · time(그 스냅샷의 논리 시각, ms)',
+      )
+    }
+  }
+  return list
+}
+
+function warnCheckpoint(r) {
+  console.error(`경고: 체크포인트를 남기지 못했습니다 — ${(r.err || r.out || '').split(NL)[0]}`)
+  console.error('  판정은 그대로입니다. 다음 감사가 그만큼 더 오래 걸립니다.')
+}
+
+/**
+ * 이번에 재생해서 깨끗했던 끝점을 체크포인트로 남긴다.
+ *
+ * 🔴 **감사가 통과했을 때만 부른다.** 체크포인트의 뜻이 "여기까지 봤고 깨끗했다"
+ *    이므로, 위반이 있는데 적으면 그 위반이 영원히 검사 밖으로 나간다.
+ *
+ * 🔴 적는 것은 장부 상태의 **사본이 아니라 커밋 sha 하나**다. 사본을 두면 장부와
+ *    두 벌이 되고, 두 벌은 반드시 어긋난다. 주소는 어긋날 수가 없다.
+ *
+ * 실패해도 **죽지 않는다.** 못 적은 체크포인트의 대가는 다음 감사가 느린 것이지
+ * 판정이 헐거워지는 것이 아니다 — 장부 push 실패와 정반대다.
+ */
+function saveCheckpoint(root, cwd, ledgerTip, time, snapshotCount, agent) {
+  const r0 = resolveRemote(root)
+  const remote = r0.source === 'ambiguous' ? null : r0.name
+  const entry = {
+    ledger: ledgerTip,
+    time,
+    at: new Date(time).toISOString(),
+    snapshots: snapshotCount,
+    by: agent,
+  }
+  // CI 컨테이너에는 git 신원이 없을 수 있다. commit-tree 는 그것 없이는 못 만든다.
+  const ident = git(['config', 'user.email'], { cwd: root }).out
+  const idArgs = ident ? [] : ['-c', 'user.name=axmap', '-c', 'user.email=axmap@invalid']
+
+  // 회차는 1부터 센다 — casBackoff 가 그 관례로 대기 시간을 고른다.
+  for (let attempt = 1; attempt <= MAX_CAS_RETRIES; attempt++) {
+    const parent = checkpointTip(root, { fetch: !!remote })
+    const list = readCheckpoints(cwd, parent)
+    if (list.some((c) => c.ledger === ledgerTip)) {
+      console.log(`체크포인트가 이미 있습니다: ${ledgerTip.slice(0, 7)}`)
+      return
+    }
+    const next = [...list, entry].sort((a, b) => a.time - b.time)
+    const body = JSON.stringify({ version: 1, checkpoints: next }, null, 2) + NL
+    const blob = git(['hash-object', '-w', '--stdin'], { cwd: root, input: body })
+    if (blob.code !== 0) return warnCheckpoint(blob)
+    const tree = git(['mktree'], { cwd: root, input: `100644 blob ${blob.out}${TAB}${CHECKPOINT_FILE}${NL}` })
+    if (tree.code !== 0) return warnCheckpoint(tree)
+    const msg = `axmap: checkpoint ${ledgerTip.slice(0, 7)} (스냅샷 ${snapshotCount}개까지 재생 확인)`
+    const commit = git(
+      [...idArgs, 'commit-tree', tree.out, ...(parent ? ['-p', parent] : []), '-m', msg],
+      { cwd: root },
+    )
+    if (commit.code !== 0) return warnCheckpoint(commit)
+
+    if (!remote) {
+      git(['branch', '-f', CHECKPOINT_BRANCH, commit.out], { cwd: root })
+      warnSolo(r0)
+      console.log(`체크포인트를 로컬에만 남겼습니다: ${ledgerTip.slice(0, 7)}`)
+      return
+    }
+    // push 를 먼저 하고 성공했을 때만 로컬 브랜치를 옮긴다. 순서를 뒤집으면
+    // 원격에 없는 체크포인트를 로컬이 진짜로 믿게 된다.
+    const p = git(['push', '--quiet', remote, `${commit.out}:refs/heads/${CHECKPOINT_BRANCH}`], { cwd: root })
+    if (p.code === 0) {
+      git(['branch', '-f', CHECKPOINT_BRANCH, commit.out], { cwd: root })
+      console.log(`체크포인트를 남겼습니다: ${ledgerTip.slice(0, 7)}  (${CHECKPOINT_BRANCH})`)
+      return
+    }
+    // 거부 = 남이 먼저 올렸다. 다시 받아서 그 위에 얹는다 (장부의 CAS 와 같은 모양).
+    if (attempt === MAX_CAS_RETRIES) return warnCheckpoint(p)
+    casBackoff(attempt)   // 이 함수가 직접 잔다
+  }
+}
+
 function cmdAudit(flags) {
   const root = repoRoot()
   const dir = ledgerDir(root)
   const hasWorktree = fs.existsSync(path.join(dir, '.git'))
+  const wantCheckpoint = boolFlag(flags.checkpoint, 'checkpoint')
 
   /**
    * 🔴 **`--fetch` 는 장부 worktree 를 요구하지 않는다.**
@@ -1803,9 +2025,10 @@ function cmdAudit(flags) {
    * (`log` · `ls-tree` · `show`). 쓰지 않으므로 worktree 가 필요 없고 ref 하나면 된다.
    */
   let cwd = dir
-  let tip = 'HEAD'
+  let tip = null
   if (hasWorktree) {
     if (flags.fetch) syncLedger(root)
+    tip = gitOrDie(['rev-parse', 'HEAD'], { cwd: dir }).out
   } else if (flags.fetch) {
     const r = resolveRemote(root)
     const remote = r.source === 'ambiguous' ? null : r.name
@@ -1827,21 +2050,60 @@ function cmdAudit(flags) {
       )
     }
     cwd = root
-    tip = 'FETCH_HEAD'
+    // 🔴 FETCH_HEAD 를 그대로 들고 다니지 않는다. 바로 뒤에서 체크포인트를 또
+    //    받으면 덮어쓴다. 받은 자리에서 sha 로 굳힌다.
+    tip = gitOrDie(['rev-parse', 'FETCH_HEAD'], { cwd: root }).out
   } else {
     requireLedger(root)
+    tip = gitOrDie(['rev-parse', 'HEAD'], { cwd: dir }).out
   }
 
-  // 오래된 것부터 재생한다.
-  const log = gitOrDie(['log', '--reverse', '--format=%H%x00%ct%x00%s', tip], { cwd }).out
-  const commits = log ? log.split('\n').map((l) => l.split('\0')) : []
+  const codeCommits = typeof flags.code === 'string' && flags.code
+    ? collectCodeCommits(root, flags.code)
+    : null
+
+  // 어디서부터 재생할지는 **이번 코드 구간에서 가장 오래된 커밋**이 정한다.
+  // 왜 "가장 최근 체크포인트" 가 아닌지는 planAudit 위에 적혀 있다.
+  const checkpoints = readCheckpoints(cwd, checkpointTip(root, { fetch: !!flags.fetch }))
+  const plan = planAudit({ checkpoints, codeCommits })
+
+  let replay = null
+  let lines = []
+  const FMT = '%H%x00%ct%x00%s'
+  if (plan.from) {
+    /**
+     * 🔴 체크포인트가 가리키는 커밋이 지금 장부의 조상이 아니면 **판정 불가**다.
+     *    이력이 다시 쓰였다는 뜻이고, 그러면 "여기까지 봤다" 는 문장이 가리키는
+     *    이력이 더 이상 없다. 성능을 위해 보장을 무르게 만들지 않는다.
+     */
+    if (git(['merge-base', '--is-ancestor', plan.from.ledger, tip], { cwd }).code !== 0) {
+      die(
+        `판정 불가 — 체크포인트 ${plan.from.ledger.slice(0, 7)} 가 지금 장부(${tip.slice(0, 7)})의 조상이 아닙니다.` + NL +
+          '  장부 이력이 다시 쓰였을 때만 이렇게 됩니다. 그 체크포인트가 보증하던 구간이 사라졌으므로' + NL +
+          '  이어서 재생할 수 없습니다. 체크포인트 브랜치를 지우고 (' + CHECKPOINT_BRANCH + ')' + NL +
+          '  `axmap audit --checkpoint` 로 처음부터 다시 세우세요.',
+      )
+    }
+    const before = Number(gitOrDie(['rev-list', '--count', plan.from.ledger], { cwd }).out)
+    replay = { from: plan.from.ledger, at: plan.from.at ?? new Date(plan.from.time).toISOString(), covered: before - 1 }
+    // 체크포인트 자신도 재생 목록에 넣는다. I5 가 그 시점의 장부 상태를 밑바탕으로 쓴다.
+    const head = gitOrDie(['log', '-1', `--format=${FMT}`, plan.from.ledger], { cwd }).out
+    const rest = gitOrDie(['log', '--reverse', `--format=${FMT}`, `${plan.from.ledger}..${tip}`], { cwd }).out
+    lines = [head, ...(rest ? rest.split(NL) : [])]
+  } else {
+    // 체크포인트가 하나도 없다. 예전과 똑같이 뿌리부터 전부 재생한다.
+    const log = gitOrDie(['log', '--reverse', `--format=${FMT}`, tip], { cwd }).out
+    lines = log ? log.split(NL) : []
+  }
 
   const snapshots = []
-  for (const [sha, ct, subject] of commits) {
+  for (const line of lines) {
+    if (!line) continue
+    const [sha, ct, subject] = line.split(NUL)
     const files = git(['ls-tree', '-r', '--name-only', sha, 'claims/'], { cwd }).out
     const claims = []
     // readClaims 와 같은 규칙으로 .json 만 본다. claims/ 에는 .gitkeep 도 있다.
-    for (const f of (files ? files.split('\n') : []).filter((f) => f.endsWith('.json'))) {
+    for (const f of (files ? files.split(NL) : []).filter((f) => f.endsWith('.json'))) {
       const blob = git(['show', `${sha}:${f}`], { cwd })
       if (blob.code !== 0) continue
       try {
@@ -1853,17 +2115,57 @@ function cmdAudit(flags) {
     snapshots.push({ commit: sha, time: Number(ct) * 1000, subject, claims })
   }
 
-  const codeCommits = typeof flags.code === 'string' && flags.code
-    ? collectCodeCommits(root, flags.code)
-    : null
+  /**
+   * 🔴 체크포인트에 적힌 시각과 그 커밋을 실제로 펼친 시각이 다르면 **판정 불가**다.
+   *    시작 지점을 고르는 계산이 전부 그 시각 위에 서 있으므로, 어긋난 채로 가면
+   *    "가장 오래된 코드 커밋보다 앞선다" 는 판단 자체가 거짓이 된다.
+   */
+  if (plan.from && snapshots.length) {
+    const actual = snapshotTime(snapshots[0])
+    if (actual !== plan.from.time) {
+      die(
+        `판정 불가 — 체크포인트 ${plan.from.ledger.slice(0, 7)} 에 적힌 시각과 실제 장부 스냅샷의 시각이 다릅니다.` + NL +
+          `  적힌 것: ${new Date(plan.from.time).toISOString()}` + NL +
+          `  실제:    ${new Date(actual).toISOString()}`,
+      )
+    }
+  }
+
+  const amnesty = plan.amnestied.map((c) => ({
+    sha: c.sha,
+    subject: c.subject,
+    at: new Date(c.time).toISOString(),
+  }))
+  const report = auditLedger(snapshots, plan.judged, { replay, amnesty })
+
+  /**
+   * 🔴 그물. 판정하기로 한 커밋이 재생 구간보다 앞서 있으면 enforcementViolations
+   *    가 그것을 "장부보다 앞선 커밋" 으로 조용히 건너뛴다 — 거부해야 할 것을
+   *    통과시키는 쪽의 실패다. 시작 지점 고르기가 어긋났을 때만 생기는 일이라
+   *    평소에는 절대 안 걸리지만, 걸리면 통과가 아니라 중단이어야 한다.
+   */
+  if (plan.from && report.codeSkipped?.length) {
+    die(
+      `판정 불가 — 재생 구간(체크포인트 ${plan.from.ledger.slice(0, 7)} 이후)보다 앞선 코드 커밋 ${report.codeSkipped.length}개가 남았습니다.` + NL +
+        report.codeSkipped.map((s) => `  - ${String(s.commit).slice(0, 7)}  ${s.subject}`).join(NL),
+    )
+  }
 
-  const report = auditLedger(snapshots, codeCommits)
   if (flags.json) {
     console.log(JSON.stringify(report, null, 2))
   } else {
     console.log(formatAudit(report))
   }
   if (!report.ok) process.exit(4)
+
+  if (wantCheckpoint) {
+    if (!snapshots.length) {
+      console.log('장부에 스냅샷이 없어 체크포인트를 남기지 않았습니다.')
+      return
+    }
+    const total = Number(gitOrDie(['rev-list', '--count', tip], { cwd }).out)
+    saveCheckpoint(root, cwd, tip, snapshotTime(snapshots[snapshots.length - 1]), total, resolveAgentName(flags).name)
+  }
 }
 
 /**
@@ -2295,13 +2597,15 @@ const HELP = `axmap - AI 에이전트 작업 선점 프로토콜
                                      쪽지를 읽다가 "쪽지함을 못 열었습니다" 를 봤을 때
   axmap users-repair                 사람별 상태(어디까지 읽었나)만 준비한다
   axmap claim <경로...>              경로를 선점한다  [--task --intent --ttl 30m]
-  axmap release [경로...]            반납한다 (경로 생략 시 전부)
+  axmap release [경로...]            반납한다 (경로 생략 시 이 세션이 잡은 것 전부)
+                                        [--all-sessions  같은 이름의 다른 창이 잡은 것까지]
   axmap renew                        TTL 을 연장한다  [--ttl 30m]
-                                     claim·release 는 [--session <id>] [--takeover]
+                                     claim·release·renew 는 [--session <id>]
   axmap status                       누가 무엇을 잡고 있는지  [--json]
   axmap verify                       staged 파일이 내 claim 안에 있는지 검사
   axmap audit                        장부 이력 전체를 재생해 상호배제 위반을 사후 증명
-                                        [--json] [--fetch]
+                                        [--json] [--fetch] [--code <구간>]
+                                        [--checkpoint  통과하면 "여기까지 봤다" 를 남긴다]
   axmap doctor                       이 PC 에서 선점이 실제로 도는지 점검  [--json]
   axmap hook install                 verify 를 pre-commit 훅으로 설치
   axmap update                       새 버전이 있는지 묻는다 (바꾸지는 않는다)
@@ -2320,8 +2624,9 @@ const HELP = `axmap - AI 에이전트 작업 선점 프로토콜
 
 에이전트 이름: --agent 또는 AXMAP_AGENT, 없으면 git config user.name
 세션 id     : --session 또는 AXMAP_SESSION, 없으면 CLAUDE_CODE_SESSION_ID
-              같은 이름이라도 세션이 다르면 남의 claim 을 덮지 않고 거부한다(종료 코드 2).
-              정말 같은 세션이라면 --takeover 로 넘겨받는다 — 경로는 안 없어진다.
+              레코드는 이름당 하나가 아니라 (이름, 세션) 짝마다 하나다. 그래서
+              한 PC 의 창 둘이 서로를 덮지 않고, release 도 이 세션이 잡은 것만 푼다.
+              다른 창이 두고 간 것까지 풀려면 release --all-sessions.
 장부 원격:     --remote 또는 AXMAP_REMOTE, 없으면 git config axmap.remote
 `