axmap-cli 1.2.4 → 1.3.0

package/mcp/server.mjs

@@ -46,8 +46,6 @@ import path from 'node:path'
 import readline from 'node:readline'
 import { fileURLToPath } from 'node:url'
 
-import { readTarget } from '../src/repotarget.mjs'
-
 const HERE = path.dirname(fileURLToPath(import.meta.url))
 
 /**
@@ -59,6 +57,10 @@ const HERE = path.dirname(fileURLToPath(import.meta.url))
  */
 const SELF = path.resolve(HERE, '..')
 const CLI = path.join(SELF, 'bin', 'axmap.mjs')
+// Vendored copies may omit package.json; the protocol handshake must still work.
+const VERSION = (() => {
+  try { return JSON.parse(fs.readFileSync(path.join(SELF, 'package.json'), 'utf8')).version } catch { return 'unknown' }
+})()
 
 /**
  * 대상 저장소 — **지금 이 서버가 겨누고 있는 폴더.**
@@ -67,32 +69,52 @@ const CLI = path.join(SELF, 'bin', 'axmap.mjs')
  * 끝이어서, 사람이 앱에서 다른 저장소를 열어도 MCP 는 처음 폴더를 계속 붙잡고 있었다.
  * 지금은 **도구를 부를 때마다** `syncRepo()` 가 다시 정한다.
  */
+let clientRoots = null
+let rootsError = null
+let rootsSupported = false
+let rootsTask = null
+let rootsGeneration = 0
+let rootRequestId = 0
+const pendingRoots = new Map()
 let REPO = resolveRepo()
 
-/**
- * 대상 저장소를 정하는 규칙.
- *
- * 🔴 **사람에게는 아무것도 묻지 않는다.** 파일 한 개를 읽고 git 에게 한 번 물어보는
- *    것이 전부다. 사람의 입력은 앱에서 폴더를 고르는 그 한 번뿐이다.
- *
- * 순서에 근거가 있다.
- *
- *   1. `AXMAP_REPO` — 사람이 "여기로 고정" 이라고 **명시한** 것. 명시는 항상 이긴다.
- *      뒤로 미루면 고정해 둔 사람이 "왜 안 지켜지지" 를 겪고, 그러면 설정을 못 믿는다.
- *      (`tools/mcp-register.mjs` 는 이 값을 **일부러 안 적는다** — 적어 두면 등록은
- *      전역인데 대상은 한 곳으로 굳어, 다른 저장소를 열어도 엉뚱한 장부에 쌓인다.)
- *   2. `~/.axmap/current.json` — 앱에서 [폴더 열기] 로 **고른** 것. (`src/repotarget.mjs`)
- *   3. git 루트 — CLI 를 `FE/` 같은 하위 폴더에서 켰어도 저장소 하나를 가리키게 한다.
- *      `bin/axmap.mjs` 의 `repoRoot()` 가 처음부터 이렇게 했다. 여기만 안 하고 있었다.
- *   4. cwd — git 저장소가 아닐 때의 마지막 답.
- */
-function resolveRepo() {
-  if (process.env.AXMAP_REPO) return path.resolve(process.env.AXMAP_REPO)
-  const chosen = readTarget()
-  if (chosen) return chosen
-  const r = spawnSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8', windowsHide: true })
+function gitRoot(cwd) {
+  const r = spawnSync('git', ['rev-parse', '--show-toplevel'], { cwd, encoding: 'utf8', windowsHide: true })
   const top = r.status === 0 ? (r.stdout ?? '').trim() : ''
-  return path.resolve(top || process.cwd())
+  return top ? fs.realpathSync(top) : null
+}
+
+/** Explicit pin > per-call cwd > client roots > launch cwd.
+ * A global desktop selection must never redirect another CLI session. */
+function resolveRepo(args = {}) {
+  if (process.env.AXMAP_REPO) {
+    const pinned = path.resolve(process.env.AXMAP_REPO)
+    return gitRoot(pinned) || pinned
+  }
+  if (args.cwd !== undefined) {
+    if (typeof args.cwd !== 'string' || !path.isAbsolute(args.cwd)) {
+      throw new Error('cwd 는 현재 작업 폴더의 절대 경로여야 합니다.')
+    }
+    const top = gitRoot(args.cwd)
+    if (!top) throw new Error(`작업 폴더에서 Git 저장소를 찾지 못했습니다: ${args.cwd}`)
+    return top
+  }
+  if (rootsError) throw new Error(`작업 폴더를 확인하지 못했습니다: ${rootsError}`)
+  if (clientRoots !== null) {
+    const dirs = [...new Set(clientRoots.map((root) => {
+      if (typeof root?.uri !== 'string' || !root.uri.startsWith('file:')) {
+        throw new Error('클라이언트가 유효한 file:// 작업 폴더를 보내지 않았습니다.')
+      }
+      const top = gitRoot(fileURLToPath(root.uri))
+      if (!top) throw new Error(`작업 폴더에서 Git 저장소를 찾지 못했습니다: ${root.uri}`)
+      return top
+    }))]
+    if (dirs.length === 1) return dirs[0]
+    const launched = gitRoot(process.cwd())
+    if (dirs.includes(launched)) return launched
+    throw new Error('작업 저장소를 하나로 정할 수 없습니다. 도구의 cwd 에 작업 폴더 절대 경로를 지정하세요.')
+  }
+  return gitRoot(process.cwd()) || process.cwd()
 }
 
 /** axMap 저장소 자신을 겨누고 있는가. 브리핑이 무엇을 읽을지가 여기서 갈린다. */
@@ -363,28 +385,13 @@ const TOOLS = [
     inputSchema: { type: 'object', properties: {} },
   },
 
-  /**
-   * 🔴 왜 `init` 이 MCP 도구여야 하는가.
-   *
-   * 장부 없는 저장소에서 첫 `ax_claim` 은 이렇게 떨어진다:
-   *
-   *     장부가 없습니다. 먼저 실행하세요:
-   *       axmap init
-   *
-   * 메시지는 정확한데 **그 명령을 부를 방법이 도구 목록에 없었다.** 에이전트는
-   * 지시를 읽고도 실행할 수 없고, 사람이 셸로 내려가야만 풀린다. 붙이자마자
-   * 막히는 벽이 정확히 여기였다 — 그리고 이 저장소 안에서만 테스트하면
-   * 장부가 이미 있으므로 한 번도 안 밟는다.
-   *
-   * 이 도구는 판정을 새로 하지 않는다. `bin/axmap.mjs init` 을 그대로 부른다.
-   */
   {
     name: 'ax_init',
     description:
-      '이 저장소에 장부가 없을 때 한 번 부른다. 장부 worktree(.axmap/ledger)와 브랜치(axmap/claims)를 만든다. '
+      '명시적으로 장부와 부가 저장소를 준비한다. 일반적인 선점·조회는 장부를 자동으로 준비하므로 먼저 부를 필요가 없다. '
       + '이미 있으면 아무것도 바꾸지 않으므로 여러 번 불러도 안전하다. '
-      + 'ax_claim 이 "장부가 없습니다" 로 실패하면 이것을 부른 뒤 다시 claim 하십시오.',
-    inputSchema: { type: 'object', properties: {} },
+      + '원격을 직접 고르려면 remote 에 Git 원격 이름을 지정한다.',
+    inputSchema: { type: 'object', properties: { remote: { type: 'string', description: 'Git 원격 이름' } } },
   },
   {
     name: 'ax_claim',
@@ -473,6 +480,13 @@ const TOOLS = [
 
 // ── 브리핑 ──────────────────────────────────────────────────────────────────
 
+for (const tool of TOOLS) {
+  tool.inputSchema.properties.cwd = {
+    type: 'string',
+    description: '현재 작업 폴더의 절대 경로. roots 미지원 또는 여러 repo가 열려 있을 때 지정. 생략하면 세션의 작업 repo를 사용한다.',
+  }
+}
+
 // `SELF` · `REPO` · `isForeign()` 은 파일 맨 위에 있다. 기준은 거기 적어 두었다.
 
 const readFrom = (base, rel) => {
@@ -691,14 +705,8 @@ function brief() {
     }
   }
 
-  // 🔴 막다른 길을 미리 없앤다. 장부가 없으면 claim 이 전부 실패하는데,
-  //    브리핑은 보통 claim 보다 먼저 불린다. 여기서 말해 주면 한 번에 이어진다.
-  if (!fs.existsSync(path.join(REPO, '.axmap', 'ledger', '.git'))) {
-    out.push('## 🔴 이 저장소에는 아직 장부가 없다')
-    out.push('')
-    out.push('`ax_init` 을 먼저 부른다. 그 전에는 claim 이 전부 실패한다.')
-    out.push('')
-  }
+  out.push('장부는 선점·조회 시 자동으로 준비한다. 별도 `ax_init` 호출은 필요 없다.')
+  out.push('')
 
   out.push('## 이 도구를 쓰는 순서')
   out.push('')
@@ -725,7 +733,7 @@ function brief() {
  * 지금 `REPO` 가 아니라 **떠나는 저장소**를 겨눠야 한다.
  */
 function releaseAllIn(dir) {
-  const r = spawnSync(process.execPath, [CLI, 'release'], {
+  const r = spawnSync(process.execPath, [CLI, 'release', '--if-present'], {
     cwd: dir,
     encoding: 'utf8',
     windowsHide: true,
@@ -738,7 +746,7 @@ function releaseAllIn(dir) {
 }
 
 /**
- * 사람이 앱에서 다른 저장소를 열었으면 따라간다.
+ * 이 세션의 클라이언트 작업 폴더가 바뀌면 따라간다.
  *
  * 🔴 **떠나기 전에 잡아둔 것을 전부 반납한다.**
  *
@@ -754,8 +762,8 @@ function releaseAllIn(dir) {
  * 반납 실패를 **숨기지 않는다.** 조용히 넘어가면 위의 상황이 그대로 일어나는데
  * 아무도 그것을 모른다.
  */
-function syncRepo() {
-  const next = resolveRepo()
+function syncRepo(args) {
+  const next = resolveRepo(args)
   if (next === REPO) return null
   const from = REPO
   const r = releaseAllIn(from)
@@ -785,37 +793,10 @@ ${s.out}`
  *    `ax_claim` 이 쓰는 장부가 서로 다른 저장소일 수 있다. 그러면 에이전트는
  *    자기가 본 것을 근거로 확신 있게 틀린 답을 만든다 — 사람이 못 잡는 종류다.
  */
-/**
- * 🔴 **막다른 길을 남기지 않는다 — 한 곳에서.**
- *
- * 장부가 없는 저장소에서 CLI 는 어느 명령이든 이렇게 답한다:
- *
- *     장부가 없습니다. 먼저 실행하세요:
- *       axmap init
- *
- * 메시지는 정확한데 **에이전트에게는 셸이 없다.** 부를 수 있는 이름으로 바꿔줘야
- * 한다. 예전에는 그 변환이 `ax_claim` 안에만 있었고, `ax_check` · `ax_status` ·
- * `ax_release` · `ax_renew` 는 원문을 그대로 냈다. 하필 `ax_check` 는 설명이
- * "작업 계획을 세울 때 쓴다" 라 **claim 보다 먼저 불리는 도구**다 — 처음 온
- * 사람은 고쳐둔 안내를 못 보고 원래의 막다른 길을 먼저 밟았다.
- *
- * 그래서 도구마다 복사하지 않고 **길목에서 한 번** 본다. 도구가 늘어나도
- * 새 도구가 이 안내를 빠뜨릴 수 없고, 다섯 군데가 따로 낡지도 않는다.
- * 판정하지 않고 **CLI 가 낸 말을 볼 뿐**이라는 점이 중요하다 — 도구 이름
- * 목록으로 거르면 그 목록이 코드보다 먼저 낡는다.
- */
-const INIT_HINT = '\n\n→ MCP 에서는 ax_init 을 부르십시오. 그 뒤 이 도구를 다시 시도하면 됩니다.'
-
-function withInitHint(r) {
-  if (r.ok) return r
-  const t = r.text ?? ''
-  if (!t.includes('장부가 없습니다') || t.includes('ax_init')) return r
-  return { ...r, text: t + INIT_HINT }
-}
-
 function callTool(name, args = {}) {
-  const switched = syncRepo()
-  const r = withInitHint(dispatch(name, args))
+  let switched
+  try { switched = syncRepo(args) } catch (e) { return { ok: false, text: e.message } }
+  const r = dispatch(name, args)
   return switched ? { ...r, text: `${switchNotice(switched)}
 
 ${r.text}` } : r
@@ -828,7 +809,7 @@ function dispatch(name, args = {}) {
     case 'ax_brief':
       return { ok: true, text: brief() }
     case 'ax_init': {
-      const r = cli(['init'])
+      const r = cli(['init', ...(args.remote ? ['--remote', String(args.remote)] : [])])
       return {
         ok: r.code === 0,
         text: r.code === 0
@@ -984,26 +965,57 @@ function send(msg) {
   process.stdout.write(JSON.stringify(msg) + '\n')
 }
 
-function handle(req) {
+function refreshRoots() {
+  const generation = ++rootsGeneration
+  const id = `axmap-roots-${++rootRequestId}`
+  rootsTask = new Promise((resolve) => {
+    const timer = setTimeout(() => {
+      pendingRoots.delete(id)
+      if (generation === rootsGeneration) rootsError = 'roots/list 응답 시간 초과'
+      resolve()
+    }, 5000)
+    pendingRoots.set(id, (msg) => {
+      clearTimeout(timer)
+      if (generation === rootsGeneration) {
+        const roots = msg.result?.roots
+        rootsError = msg.error?.message || (!Array.isArray(roots) ? '잘못된 roots/list 응답' : null)
+        clientRoots = Array.isArray(roots) ? roots : null
+      }
+      resolve()
+    })
+    send({ jsonrpc: '2.0', id, method: 'roots/list' })
+  })
+}
+
+async function handle(req) {
   const { id, method, params } = req
 
   if (method === 'initialize') {
+    rootsSupported = !!params?.capabilities?.roots
     return {
       protocolVersion: '2024-11-05',
       capabilities: { tools: {} },
-      serverInfo: { name: 'axmap', version: '0.1.0' },
+      serverInfo: { name: 'axmap', version: VERSION },
     }
   }
   if (method === 'tools/list') return { tools: TOOLS }
   if (method === 'tools/call') {
+    if (rootsSupported && !process.env.AXMAP_REPO) {
+      if (!rootsTask || rootsError) refreshRoots()
+      // A change notification may replace the task while the previous reply arrives.
+      let task
+      do { task = rootsTask; await task } while (task !== rootsTask)
+    }
     const r = callTool(params?.name, params?.arguments ?? {})
-    return { content: [{ type: 'text', text: r.text + unreadBanner(params?.name, r.text) }], isError: !r.ok }
+    return { content: [{ type: 'text', text: r.text + (r.ok ? unreadBanner(params?.name, r.text) : '') }], isError: !r.ok }
   }
   if (method === 'ping') return {}
   return null // 알림이거나 지원하지 않는 메서드
 }
 
 const rl = readline.createInterface({ input: process.stdin })
+// Execute tools in order, but keep reading client replies while a tool awaits roots.
+let requests = Promise.resolve()
 rl.on('line', (line) => {
   const s = line.trim()
   if (!s) return
@@ -1013,18 +1025,29 @@ rl.on('line', (line) => {
   } catch {
     return
   }
-  // 알림(id 없음)에는 답하지 않는다
-  if (req.id === undefined) return
-  try {
-    const result = handle(req)
-    if (result === null) {
-      send({ jsonrpc: '2.0', id: req.id, error: { code: -32601, message: `지원하지 않는 메서드: ${req.method}` } })
-    } else {
-      send({ jsonrpc: '2.0', id: req.id, result })
-    }
-  } catch (e) {
-    send({ jsonrpc: '2.0', id: req.id, error: { code: -32603, message: e.message } })
+  if (!req || typeof req !== 'object') return
+  if (!req.method) {
+    const done = pendingRoots.get(req.id)
+    if (done) { pendingRoots.delete(req.id); done(req) }
+    return
+  }
+  if (req.id === undefined) {
+    if (rootsSupported && !process.env.AXMAP_REPO &&
+      ['notifications/initialized', 'notifications/roots/list_changed'].includes(req.method)) refreshRoots()
+    return
   }
+  requests = requests.then(async () => {
+    try {
+      const result = await handle(req)
+      if (result === null) {
+        send({ jsonrpc: '2.0', id: req.id, error: { code: -32601, message: `지원하지 않는 메서드: ${req.method}` } })
+      } else {
+        send({ jsonrpc: '2.0', id: req.id, result })
+      }
+    } catch (e) {
+      send({ jsonrpc: '2.0', id: req.id, error: { code: -32603, message: e.message } })
+    }
+  })
 })
 
 process.stderr.write(`axMap MCP · 저장소 ${REPO} · 에이전트 ${AGENT} (${ACTOR})\n`)

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.2.4",
+  "version": "1.3.0",
   "//private": "🔴 여기 있던 \"private\": true 를 2026-08-28 에 지웠다. 그 줄이 있는 동안 npm publish 는 거부됐다. 되돌리려면 다시 넣으면 되지만, 이미 올라간 버전은 그래도 안 사라진다 — npm 은 같은 번호를 덮어쓰지 못하고 삭제도 72시간 안에만 된다. 즉 이 줄을 되살리는 것은 '앞으로 안 올린다' 는 뜻이지 '올린 것을 없앤다' 는 뜻이 아니다.",
   "//publishConfig": "axmap-cli 는 스코프가 없어서 기본이 이미 공개다. 즉 지금은 없어도 된다. 그래도 남겨 두는 이유: 나중에 @조직/axmap 처럼 스코프를 붙이는 날 이 줄이 없으면 publish 가 '유료 플랜이 필요하다'는 엉뚱한 말로 실패한다.",
   "publishConfig": {
@@ -12,7 +12,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://lab.ssafy.com/rleaderjoon/axmap.git"
+    "url": "git+https://github.com/rl2aderjoon/axmap.git"
   },
   "keywords": [
     "ai-agent",
@@ -52,5 +52,9 @@
   },
   "engines": {
     "node": ">=20"
+  },
+  "homepage": "https://github.com/rl2aderjoon/axmap#readme",
+  "bugs": {
+    "url": "https://github.com/rl2aderjoon/axmap/issues"
   }
 }

package/src/overlap.mjs

@@ -27,7 +27,7 @@
  *
  * 실측으로 확인했다. 두 검사는 **정확히 엇갈린다** —
  * 뒤처짐 검사는 20:15 건을 못 잡고, 안 합쳐진 브랜치 검사는 22:31 건을 못 잡는다.
- * 그래서 둘 다 있어야 한다. (근거: axMap `docs/26.09.11/04-무엇으로-막나.md`)
+ * 그래서 둘 다 있어야 한다. (근거: axMap `docs/26.09/26.09.11/04-무엇으로-막나.md`)
  *
  * ── 🔴 왜 숫자를 경로로 자르는가 ────────────────────────────────────────────
  *

package/src/repolock.mjs

@@ -0,0 +1,31 @@
+import fs from 'node:fs'
+import crypto from 'node:crypto'
+
+/** Serialize bootstrap across processes and linked worktrees. Never steal a lock:
+ * a slow remote must not let a second initializer change the same refs/index. */
+export function withRepoLock(file, action, timeoutMs = 30000) {
+  const owner = JSON.stringify({ pid: process.pid, token: crypto.randomUUID() })
+  const deadline = Date.now() + timeoutMs
+  for (;;) {
+    try {
+      fs.writeFileSync(file, owner, { flag: 'wx' })
+      break
+    } catch (e) {
+      if (e.code !== 'EEXIST') throw e
+      if (Date.now() >= deadline) {
+        throw new Error(`장부 준비 잠금을 기다리다 중단했습니다: ${file}\n` +
+          '다른 초기화가 끝난 뒤 다시 시도하세요. 비정상 종료로 남은 잠금은 소유 프로세스가 종료됐는지 확인한 뒤 제거하세요.')
+      }
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 50)
+    }
+  }
+  const release = () => {
+    try { if (fs.readFileSync(file, 'utf8') === owner) fs.unlinkSync(file) } catch { /* already released */ }
+  }
+  // CLI errors use process.exit; finally alone would leave a permanent lock.
+  process.once('exit', release)
+  try { return action() } finally {
+    release()
+    process.removeListener('exit', release)
+  }
+}

package/src/repotarget.mjs

@@ -1,4 +1,7 @@
 /**
+ * 1.3.0: 이 파일은 데스크톱 선택 상태다. MCP는 세션의 roots/cwd를 사용하며
+ * 전역 선택을 읽지 않는다. 아래는 데스크톱과 MCP가 공유하던 이전 설계 기록이다.
+ *
  * 지금 사람이 보고 있는 저장소가 어디인지를 **프로세스 사이에 전달하는 한 칸.**
  *
  * ── 왜 파일 한 개인가 ────────────────────────────────────────────────────────

package/src/update.mjs

@@ -131,15 +131,33 @@ export const isStale = (rec, nowMs, interval = CHECK_INTERVAL_MS) =>
   !rec || typeof rec.checkedAt !== 'number' || nowMs - rec.checkedAt >= interval
 
 /**
- * 사람에게 보여줄 한 줄. 알릴 것이 없으면 `null`.
+ * 사람에게 보여줄 안내. 알릴 것이 없으면 `null`.
  *
  * 🔴 부르는 쪽은 이것을 **stderr 로** 낸다. stdout 은 `--json` 이 쓰는 자리라,
  *    여기에 사람이 읽는 글을 섞으면 그 출력을 파싱하는 쪽이 조용히 깨진다.
+ *
+ * 🔴 **두 줄을 다 낸다 (2026-09-12).** 이 PC 에 판이 두 군데 있기 때문이다 —
+ *    `axmap` 명령(전역 설치)과 git 훅이 부르는 사본(`~/.axmap/app`). 서로 안
+ *    따라간다.
+ *
+ *    전에는 `npx … setup` 한 줄만 안내했다. 그런데 **`setup` 은 전역 설치를 전혀
+ *    건드리지 않는다** (`tools/setup.mjs` 에 `npm i` 가 0건이다 — 거기 있는
+ *    `--commands global` 의 "global" 은 슬래시 명령을 어디 둘지이지 전역 설치가
+ *    아니다). 그래서 그 안내를 그대로 따르면 **사본만 새 판이 되고 `axmap` 명령은
+ *    옛 판으로 남는다.**
+ *
+ *    그건 이 명령이 1.2.4 에서 고친 문제(사본이 낡았는데 "최신입니다" 라고 한 것)를
+ *    **안내가 스스로 만들어 내는 것**이다. 반쪽짜리 안내는 틀린 안내보다 낫지
+ *    않다 — 시킨 대로 했는데 안 고쳐지면 사람은 도구를 안 믿게 된다.
  */
 export function noticeLine(current, latest) {
   if (!current || !latest) return null
   if (compareVersions(latest, current) <= 0) return null
-  return `새 버전이 있습니다: ${current} → ${latest}\n  받으려면:  npx -y ${PACKAGE_NAME}@latest setup`
+  return `새 버전이 있습니다: ${current} → ${latest}\n`
+    + `  받으려면:  npm i -g ${PACKAGE_NAME}@latest\n`
+    + `             npx -y ${PACKAGE_NAME}@latest setup\n`
+    + '  🔴 두 줄 다 필요합니다 — 앞은 axmap 명령을, 뒤는 git 훅이 부르는 사본을\n'
+    + '     올립니다. 서로 안 따라갑니다.'
 }
 
 /**

package/tools/smoke.mjs

@@ -26,6 +26,7 @@ import { spawn, spawnSync, execFileSync } from 'node:child_process'
 import fs from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { detect } from '../app/lib/agentcli.mjs'
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
 const PORT = Number(process.env.AXMAP_SMOKE_PORT ?? 7912)
@@ -92,9 +93,16 @@ const OPENED = [
   { what: '온보딩이 닫혔다', re: /id="onboard" hidden/ },
 ]
 
+// 검사 PC의 설치된 CLI를 선택한다. 특정 팀의 Claude 설치에 의존하지 않는다.
+const agent = detect().find((a) => a.installed)
+if (!agent) {
+  console.error('온보딩 이후 화면 검증에 필요한 AI CLI가 없습니다. Claude Code, agy 또는 Codex CLI를 설치하세요.')
+  process.exit(1)
+}
+
 const PAGES = [
   { path: '/', what: '처음 오는 사람', must: FIRST },
-  { path: '/?agent=claude', what: '고르기를 끝낸 사람', must: OPENED },
+  { path: `/?agent=${encodeURIComponent(agent.id)}`, what: '고르기를 끝낸 사람', must: OPENED },
 ]
 
 async function waitUp(ms = 120_000) {