axmap-cli 1.8.0 → 1.9.0

package/src/session-types.mts

@@ -4,6 +4,11 @@ export type Transport = 'console' | 'stdio' | 'pty' | 'agentapi'
 export type SessionState = 'starting' | 'running' | 'idle' | 'awaiting_user' | 'settling' | 'closed' | 'unknown'
 export type RequestState = 'sending' | 'submitted' | 'unknown' | 'completed' | 'failed' | 'superseded'
 export type ConnectionState = 'connected' | 'closed' | 'unreachable' | 'unverified'
+/** 관리형 세션 호스트의 생존. unverified 는 "확인하지 못함"이며 살아 있음도 죽음도 아니다. */
+export type HostLiveness = 'alive' | 'dead' | 'unverified'
+/** `run.mjs rpc` 가 로컬 파이프에 연결조차 못 했을 때(ENOENT·ECONNREFUSED)의 종료 코드.
+ * 이 경우에만 요청이 확실히 전달되지 않았다고 판단한다. */
+export const RPC_NOT_DELIVERED_EXIT = 3
 export type HookEvent = 'SessionStart' | 'PreInvocation' | 'Stop'
 
 export interface Usage {
@@ -38,9 +43,12 @@ export interface SessionRecord {
   executable?: string
   address?: string
   token?: string
+  /** 로컬 파이프를 연 `bridge serve`·`run` 프로세스. 비 Windows 생존 확인에 쓴다. */
+  hostPid?: number
+  closedReason?: string
 }
 export type PublicSession = Pick<SessionRecord, 'id' | 'provider' | 'workspaces' | 'model' | 'transport' |
-  'state' | 'pid' | 'registeredAt' | 'event' | 'fullyIdle' | 'role' | 'usage' | 'usageKnown' | 'maxTokens' | 'pendingApproval' | 'conversationId'>
+  'state' | 'pid' | 'registeredAt' | 'event' | 'fullyIdle' | 'role' | 'usage' | 'usageKnown' | 'maxTokens' | 'pendingApproval' | 'conversationId'> & { liveness?: HostLiveness }
 export interface SessionSnapshot extends PublicSession {
   lastKnownState: SessionState | null
   state: SessionState

package/src/terminal-bridge.mjs

@@ -8,7 +8,7 @@ import net from 'node:net';
 import { randomUUID, randomBytes, timingSafeEqual } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 import { createRequire } from 'node:module';
-import { bridgeHome, repoKey, readJSON, writeJSON } from './bridge.mjs';
+import { bridgeHome, hostPipe, repoKey, readJSON, writeJSON } from './bridge.mjs';
 import { errorCode, errorMessage } from './session-types.mjs';
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const validID = (id) => /^[0-9a-f-]{36}$/i.test(id || '');
@@ -17,8 +17,8 @@ const sessionFile = (id) => {
         throw new Error('잘못된 터미널 세션 ID입니다.');
     return path.join(bridgeHome(), 'sessions', `${id}.json`);
 };
-const pipeFor = (id) => process.platform === 'win32'
-    ? `\\\\.\\pipe\\axmap-${id}` : path.join(bridgeHome(), `${id}.sock`);
+// 생존 확인(bridge.sessions)이 같은 이름을 보도록 한 곳에서 만든다.
+const pipeFor = hostPipe;
 export function sendTerminal(id, message, token = null, { timeoutMs = 10000 } = {}) {
     if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1)
         throw new Error('양의 응답 시간 한도가 필요합니다.');
@@ -28,11 +28,17 @@ export function sendTerminal(id, message, token = null, { timeoutMs = 10000 } =
     return new Promise((resolve, reject) => {
         const socket = net.createConnection(pipeFor(id));
         socket.setEncoding('utf8');
-        let buffer = '';
+        let buffer = '', connected = false;
         const fail = (e) => { socket.destroy(); reject(e); };
         socket.setTimeout(timeoutMs, () => fail(new Error('로컬 세션 응답 시간 초과. 자동 재전송하지 마세요.')));
-        socket.on('error', fail);
-        socket.on('connect', () => socket.write(JSON.stringify({ ...message, token: token || s.token }) + '\n'));
+        socket.on('error', e => {
+            // 연결 전의 ENOENT(파이프·소켓 없음)·ECONNREFUSED(듣는 쪽 없음)는 아무것도 쓰지
+            // 않았다는 증거다. 연결 뒤의 오류는 요청이 이미 건너갔을 수 있어 구별해 둔다.
+            if (!connected && ['ENOENT', 'ECONNREFUSED'].includes(errorCode(e) || ''))
+                Object.assign(e, { notDelivered: true });
+            fail(e);
+        });
+        socket.on('connect', () => { connected = true; socket.write(JSON.stringify({ ...message, token: token || s.token }) + '\n'); });
         socket.on('data', chunk => {
             buffer += chunk;
             if (Buffer.byteLength(buffer) > 1024 * 1024)
@@ -60,7 +66,7 @@ export async function startTerminal({ executable, args = [], provider, cwd = pro
     const { spawn } = await import('node-pty');
     const id = randomUUID(), token = randomBytes(32).toString('hex');
     const s = { id, provider, transport: 'pty', token, workspaces: [cwd], repos: [repoKey(cwd)],
-        state: 'starting', fullyIdle: false, registeredAt: new Date().toISOString(), event: 'launch' };
+        state: 'starting', fullyIdle: false, registeredAt: new Date().toISOString(), event: 'launch', hostPid: process.pid };
     const jobs = new Map();
     let pending = null, draft = false, term, closed = false, stopTimer;
     const save = () => { s.registeredAt = new Date().toISOString(); writeJSON(sessionFile(id), s); };

package/src/terminal-bridge.mts

@@ -7,7 +7,7 @@ import net from 'node:net'
 import { randomUUID, randomBytes, timingSafeEqual } from 'node:crypto'
 import { fileURLToPath } from 'node:url'
 import { createRequire } from 'node:module'
-import { bridgeHome, repoKey, readJSON, writeJSON } from './bridge.mjs'
+import { bridgeHome, hostPipe, repoKey, readJSON, writeJSON } from './bridge.mjs'
 import { errorCode, errorMessage } from './session-types.mjs'
 import type { IPty } from 'node-pty'
 import type { Provider, SessionRecord, LocalMessage, JobRecord, RequestState, TranscriptEntry } from './session-types.mjs'
@@ -25,8 +25,8 @@ const sessionFile = (id: string) => {
   if (!validID(id)) throw new Error('잘못된 터미널 세션 ID입니다.')
   return path.join(bridgeHome(), 'sessions', `${id}.json`)
 }
-const pipeFor = (id: string) => process.platform === 'win32'
-  ? `\\\\.\\pipe\\axmap-${id}` : path.join(bridgeHome(), `${id}.sock`)
+// 생존 확인(bridge.sessions)이 같은 이름을 보도록 한 곳에서 만든다.
+const pipeFor = hostPipe
 
 export function sendTerminal(id: string, message: LocalMessage, token: string | null = null, { timeoutMs = 10000 } = {}): Promise<unknown> {
   if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1) throw new Error('양의 응답 시간 한도가 필요합니다.')
@@ -35,11 +35,16 @@ export function sendTerminal(id: string, message: LocalMessage, token: string |
   return new Promise((resolve, reject) => {
     const socket = net.createConnection(pipeFor(id))
     socket.setEncoding('utf8')
-    let buffer = ''
+    let buffer = '', connected = false
     const fail = (e: Error) => { socket.destroy(); reject(e) }
     socket.setTimeout(timeoutMs, () => fail(new Error('로컬 세션 응답 시간 초과. 자동 재전송하지 마세요.')))
-    socket.on('error', fail)
-    socket.on('connect', () => socket.write(JSON.stringify({ ...message, token: token || s.token }) + '\n'))
+    socket.on('error', e => {
+      // 연결 전의 ENOENT(파이프·소켓 없음)·ECONNREFUSED(듣는 쪽 없음)는 아무것도 쓰지
+      // 않았다는 증거다. 연결 뒤의 오류는 요청이 이미 건너갔을 수 있어 구별해 둔다.
+      if (!connected && ['ENOENT', 'ECONNREFUSED'].includes(errorCode(e) || '')) Object.assign(e, { notDelivered: true })
+      fail(e)
+    })
+    socket.on('connect', () => { connected = true; socket.write(JSON.stringify({ ...message, token: token || s.token }) + '\n') })
     socket.on('data', chunk => {
       buffer += chunk
       if (Buffer.byteLength(buffer) > 1024 * 1024) return fail(new Error('로컬 응답 크기 제한 초과'))
@@ -59,7 +64,7 @@ export async function startTerminal({ executable, args = [], provider, cwd = pro
   const { spawn } = await import('node-pty')
   const id = randomUUID(), token = randomBytes(32).toString('hex')
   const s: SessionRecord = { id, provider, transport: 'pty', token, workspaces: [cwd], repos: [repoKey(cwd)],
-    state: 'starting', fullyIdle: false, registeredAt: new Date().toISOString(), event: 'launch' }
+    state: 'starting', fullyIdle: false, registeredAt: new Date().toISOString(), event: 'launch', hostPid: process.pid }
   const jobs = new Map<string, JobRecord>()
   let pending: JobRecord | null = null, draft = false, term: IPty, closed = false, stopTimer: NodeJS.Timeout | undefined
   const save = () => { s.registeredAt = new Date().toISOString(); writeJSON(sessionFile(id), s) }

package/src/update.mjs

@@ -11,19 +11,9 @@
  *    코드가 아니기 때문이다. 적용은 사람이 `axmap update` 를 읽고 한 줄을
  *    직접 실행하는 것으로만 일어난다.
  *
- * ── 🔴 벤더링된 사본에서는 아무것도 하지 않는다 ─────────────────────────────
- *
- * 팀 저장소의 `ci/axmap/` 은 이 코드의 **사본**이고(팀 CLAUDE.md 0.3),
- * 그 사본이 최신인지는 npm 이 아니라 `tools/vendor.mjs` 가 정한다. 사본이
- * 레지스트리를 쳐다보면 두 가지가 한꺼번에 나빠진다.
- *
- *   1. 팀 CI 가 매 파이프라인마다 바깥 네트워크에 의존하게 된다 — 벤더링이
- *      끊으려고 했던 바로 그 연결이다
- *   2. "새 버전이 있다" 는 안내가 팀원에게 뜨는데, 그 팀원이 할 수 있는 일은
- *      없다. 사본은 axMap 저장소에서 `vendor.mjs` 를 다시 돌려야만 바뀐다
- *
- * 사본인지 아닌지는 **옆에 `SOURCE.json` 이 있는가**로 가른다. 그 파일은
- * `tools/vendor.mjs` 가 사본에만 써 넣는다(원본 저장소 루트에는 없다).
+ * 팀 저장소 안에 이 코드의 사본(`ci/axmap/`)을 두던 시절에는 사본이면 확인을
+ * 건너뛰는 갈래가 여기 있었다. 2026-10-29 에 사본을 걷어냈으므로(DECISIONS D31)
+ * 그 갈래도 없다 — 이 코드가 도는 자리는 npm 설치본과 axMap 저장소뿐이다.
  */
 
 import fs from 'node:fs'
@@ -79,13 +69,6 @@ export function compareVersions(a, b) {
   return x.pre > y.pre ? 1 : -1
 }
 
-/**
- * 이 axMap 이 **벤더링된 사본**인가. 사본이면 갱신 확인을 통째로 건너뛴다.
- *
- * @param {string} axmapRoot  `bin/` · `src/` 를 담고 있는 폴더
- */
-export const isVendored = (axmapRoot) => fs.existsSync(path.join(axmapRoot, 'SOURCE.json'))
-
 /**
  * 확인을 하지 말아야 하는 자리인가.
  *

package/src/workspace.mjs

@@ -0,0 +1,247 @@
+// Generated from src/workspace.mts. Edit the .mts source and run npm run build.
+/** 작업 폴더 → 대상 Git 저장소. MCP 서버·로컬 세션 연결·CLI가 이 한 곳에서 정한다.
+ *
+ * 사람이 AI 도구를 여는 폴더가 Git 저장소가 아닐 수 있다. 예: 한 저장소의 worktree
+ * 여러 개를 나란히 담아 둔 `robotable_hj_workspace`. 위로만 찾으면 이 폴더는
+ * "Git 저장소 아님"이 되어 연결이 끊긴다. 그래서 위로 찾기에 실패한 폴더에 한해
+ * 아래 순서로 정한다 (D30).
+ *
+ *   0. 수동 설정 — 그 폴더나 조상에 있는 `.axmap.json` 의 `{ "repo": "<경로>" }`
+ *   1. 자동 탐색 — 바로 아래 자식 폴더(깊이 1)의 Git 저장소를 공통 디렉터리로 묶어
+ *                  묶음이 정확히 하나면 그 저장소
+ *   2. 모호함   — 묶음이 둘 이상이면 고르지 않고 후보를 적은 오류를 낸다
+ *
+ * 매번 디스크와 git 에게 다시 묻는다. 캐시하면 사람이 설정 파일을 쓰거나 폴더를
+ * 추가한 뒤에도 서버를 다시 켜기 전까지 옛 판단이 남는다.
+ *
+ * 읽지 못한 것과 없는 것을 구별한다. `.git` 이 있는데 git 이 읽지 못한 자식 폴더를
+ * "저장소 없음"으로 세면, 실제로는 두 저장소인데 하나로 보고 엉뚱한 장부를 잡는다.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+// bin/axmap.mjs·mcp/server.mjs 가 CLI 를 띄울 때마다 import 하므로 Node 내장만 쓴다.
+// 그래서 session-types 의 작은 도우미도 가져오지 않는다.
+const errorMessage = (e) => e instanceof Error ? e.message : String(e);
+const errorCode = (e) => e instanceof Error && 'code' in e && typeof e.code === 'string' ? e.code : undefined;
+export const WORKSPACE_CONFIG = '.axmap.json';
+/** 오류 문구만으로 종류를 가르지 않도록 사유를 붙인다. */
+export class WorkspaceError extends Error {
+    reason;
+    constructor(message, reason) {
+        super(message);
+        this.reason = reason;
+    }
+}
+// 커밋 훅 안에서는 GIT_DIR 등이 설정돼 있다. 그대로 두면 자식 폴더마다 같은 저장소로
+// 답해서 서로 다른 저장소가 하나로 묶인다. bin/axmap.mjs 의 GIT_ENV_KEYS 와 같은 목록이다.
+const GIT_ENV_KEYS = ['GIT_DIR', 'GIT_WORK_TREE', 'GIT_COMMON_DIR', 'GIT_INDEX_FILE',
+    'GIT_OBJECT_DIRECTORY', 'GIT_ALTERNATE_OBJECT_DIRECTORIES', 'GIT_PREFIX'];
+function gitEnv() {
+    // "not a git repository" 문구로 판정하므로 번역된 메시지가 나오지 않게 고정한다.
+    const env = { ...process.env, LC_ALL: 'C', LANGUAGE: 'C' };
+    for (const key of GIT_ENV_KEYS)
+        delete env[key];
+    return env;
+}
+function askGit(cwd, args) {
+    const r = spawnSync('git', args, { cwd, env: gitEnv(), encoding: 'utf8', windowsHide: true });
+    if (r.error)
+        return { ok: false, notRepo: false, detail: r.error.message };
+    if (r.status === 0)
+        return { ok: true, lines: (r.stdout ?? '').split(/\r?\n/).map(s => s.trim()).filter(Boolean) };
+    const detail = (r.stderr ?? '').trim() || `git 종료 코드 ${r.status}`;
+    return { ok: false, notRepo: /not a git repository/i.test(detail), detail };
+}
+const real = (p) => fs.realpathSync(p);
+/** 공통 디렉터리 비교 키. bridge 의 repoKey 와 같은 규칙이다 (Windows 는 대소문자 무시). */
+export const commonKey = (common) => process.platform === 'win32' ? common.toLowerCase() : common;
+function statOrNull(p) {
+    try {
+        return fs.statSync(p);
+    }
+    catch (e) {
+        if (['ENOENT', 'ENOTDIR'].includes(errorCode(e) || ''))
+            return null;
+        throw e;
+    }
+}
+/** 폴더가 속한 Git 저장소의 최상위. 저장소 밖이면 null, 판정하지 못하면 예외. */
+export function gitTop(dir) {
+    const stat = statOrNull(dir);
+    if (!stat || !stat.isDirectory())
+        return null;
+    const r = askGit(dir, ['rev-parse', '--show-toplevel']);
+    if (r.ok) {
+        if (!r.lines[0])
+            throw new WorkspaceError(`Git 최상위 폴더를 읽지 못했습니다: ${dir}`, 'unreadable');
+        return real(r.lines[0]);
+    }
+    if (r.notRepo)
+        return null;
+    throw new WorkspaceError(`Git 저장소인지 확인하지 못했습니다: ${dir}\n  ${r.detail}`, 'unreadable');
+}
+/** 그 폴더나 조상에 있는 `.axmap.json`. 없으면 null. 읽지 못하면 예외. */
+export function findWorkspaceConfig(dir) {
+    for (let at = path.resolve(dir);; at = path.dirname(at)) {
+        const candidate = path.join(at, WORKSPACE_CONFIG);
+        const stat = statOrNull(candidate);
+        if (stat)
+            return candidate;
+        if (path.dirname(at) === at)
+            return null;
+    }
+}
+function manualTarget(config) {
+    let data;
+    try {
+        data = JSON.parse(fs.readFileSync(config, 'utf8'));
+    }
+    catch (e) {
+        throw new WorkspaceError(`작업 폴더 설정을 읽지 못했습니다: ${config}\n  ${errorMessage(e)}`, 'manual');
+    }
+    const repo = data?.repo;
+    if (!data || typeof data !== 'object' || Array.isArray(data) || typeof repo !== 'string' || !repo.trim()) {
+        throw new WorkspaceError(`작업 폴더 설정에 "repo" 경로가 없습니다: ${config}\n  예: { "repo": "폴더이름" }`, 'manual');
+    }
+    const wanted = path.resolve(path.dirname(config), repo);
+    // 설정이 틀렸을 때 자동 탐색으로 넘어가지 않는다. 사람이 고른 것을 몰래 바꾸면
+    // 다른 저장소의 장부에 선점이 남는다.
+    const top = gitTop(wanted);
+    if (!top)
+        throw new WorkspaceError(`작업 폴더 설정의 저장소가 Git 저장소가 아닙니다: ${wanted}\n  (설정 파일: ${config})`, 'manual');
+    return top;
+}
+function scanChildren(dir) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch (e) {
+        throw new WorkspaceError(`작업 폴더의 하위 폴더를 읽지 못했습니다: ${dir}\n  ${errorMessage(e)}`, 'unreadable');
+    }
+    const groups = new Map(), unreadable = [];
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+        if (entry.name.startsWith('.') || entry.name === 'node_modules')
+            continue;
+        const child = path.join(dir, entry.name);
+        try {
+            // worktree 폴더가 심볼릭 링크·junction 일 수 있어 링크는 따라가서 본다.
+            const isDir = entry.isDirectory() || (entry.isSymbolicLink() && !!statOrNull(child)?.isDirectory());
+            if (!isDir)
+                continue;
+            // `.git` 이 없는 폴더는 저장소의 최상위가 아니다. git 을 띄우지 않고 넘어간다.
+            if (fs.lstatSync(path.join(child, '.git'), { throwIfNoEntry: false }) === undefined)
+                continue;
+        }
+        catch (e) {
+            unreadable.push(`${entry.name} (${errorMessage(e)})`);
+            continue;
+        }
+        const r = askGit(child, ['rev-parse', '--path-format=absolute', '--show-toplevel', '--git-common-dir']);
+        if (!r.ok || r.lines.length < 2) {
+            unreadable.push(`${entry.name} (${r.ok ? 'git 응답이 비어 있음' : r.detail})`);
+            continue;
+        }
+        let top, common;
+        try {
+            top = real(r.lines[0]);
+            common = real(r.lines[1]);
+        }
+        catch (e) {
+            unreadable.push(`${entry.name} (${errorMessage(e)})`);
+            continue;
+        }
+        const key = commonKey(common);
+        const group = groups.get(key) ?? { key, common, target: '', members: [] };
+        group.members.push({ name: entry.name, top });
+        groups.set(key, group);
+    }
+    for (const group of groups.values()) {
+        // 메인 체크아웃(공통 디렉터리 `.git` 의 부모)을 겨눈다. 장부도 거기 있다.
+        // bare 저장소처럼 그 부모가 체크아웃이 아니면 첫 번째 worktree 를 쓴다.
+        const parent = path.dirname(group.common);
+        group.target = path.basename(group.common).toLowerCase() === '.git' && statOrNull(parent)?.isDirectory()
+            ? real(parent) : group.members[0].top;
+    }
+    return { groups: [...groups.values()], unreadable };
+}
+/** 무엇을 왜 고르는지까지 돌려준다. 모호함은 예외가 아니라 결과다 (`workspace show` 용). */
+export function inspectTarget(dir) {
+    const from = path.resolve(dir);
+    const top = gitTop(from);
+    if (top)
+        return { kind: 'git', from, repo: top };
+    if (!statOrNull(from)?.isDirectory())
+        return { kind: 'none', from };
+    const config = findWorkspaceConfig(from);
+    if (config)
+        return { kind: 'manual', from, repo: manualTarget(config), config };
+    const { groups, unreadable } = scanChildren(from);
+    if (unreadable.length) {
+        throw new WorkspaceError([
+            `작업 폴더 ${from} 아래에서 확인하지 못한 Git 폴더가 있어 대상 저장소를 정하지 않았습니다.`,
+            ...unreadable.map(s => `  - ${s}`),
+            `저장소를 직접 고르려면 이 폴더에서 \`axmap workspace use <폴더>\` 를 실행하세요.`,
+        ].join('\n'), 'unreadable');
+    }
+    if (groups.length === 1)
+        return { kind: 'auto', from, repo: groups[0].target, group: groups[0] };
+    if (groups.length > 1)
+        return { kind: 'ambiguous', from, groups };
+    return { kind: 'none', from };
+}
+export function ambiguityMessage(r) {
+    return [
+        `작업 폴더 ${r.from} 아래에 서로 다른 Git 저장소가 ${r.groups.length}개 있어 하나로 정하지 않았습니다.`,
+        ...r.groups.map(g => `  - ${g.target}  (폴더: ${g.members.map(m => m.name).join(', ')})`),
+        '고르는 방법 (둘 중 하나):',
+        '  1. 도구를 부를 때 cwd 에 작업할 저장소 폴더의 절대 경로를 넘긴다.',
+        `  2. 이 폴더에 ${WORKSPACE_CONFIG} 을 둔다: { "repo": "${r.groups[0].members[0].name}" }`,
+        `     터미널에서는: axmap workspace use ${r.groups[0].members[0].name}`,
+    ].join('\n');
+}
+/** 대상 저장소 경로. 저장소가 없으면 null, 모호하거나 판정하지 못하면 예외. */
+export function resolveTarget(dir) {
+    const r = inspectTarget(dir);
+    if (r.kind === 'ambiguous')
+        throw new WorkspaceError(ambiguityMessage(r), 'ambiguous');
+    return r.kind === 'none' ? null : r.repo;
+}
+export function describeTarget(r) {
+    switch (r.kind) {
+        case 'git': return `대상 저장소: ${r.repo}\n이유: 작업 폴더가 Git 저장소 안에 있습니다.`;
+        case 'manual': return `대상 저장소: ${r.repo}\n이유: 수동 설정 ${r.config}`;
+        case 'auto': return `대상 저장소: ${r.repo}\n이유: 자동 탐색 — 하위 폴더가 모두 같은 저장소입니다 (${r.group.members.map(m => m.name).join(', ')}).`;
+        case 'ambiguous': return ambiguityMessage(r);
+        case 'none': return `대상 저장소 없음: ${r.from}\n이유: 이 폴더와 바로 아래 폴더에서 Git 저장소를 찾지 못했습니다.`;
+    }
+}
+/** `axmap workspace use` — 사람이 고른 저장소를 작업 폴더의 `.axmap.json` 에 적는다. */
+export function writeWorkspaceChoice(dir, choice) {
+    const from = path.resolve(dir);
+    if (gitTop(from))
+        throw new WorkspaceError(`이 폴더는 이미 Git 저장소 안이라 ${WORKSPACE_CONFIG} 를 쓰지 않습니다: ${from}`, 'manual');
+    const wanted = path.resolve(from, choice);
+    const repo = gitTop(wanted);
+    if (!repo)
+        throw new WorkspaceError(`Git 저장소가 아닙니다: ${wanted}`, 'manual');
+    const config = path.join(from, WORKSPACE_CONFIG);
+    let data = {};
+    if (statOrNull(config)) {
+        // 읽지 못한 설정은 덮어쓰지 않는다 (D23 과 같은 원칙).
+        try {
+            data = JSON.parse(fs.readFileSync(config, 'utf8'));
+        }
+        catch (e) {
+            throw new WorkspaceError(`기존 ${config} 를 읽지 못해 바꾸지 않았습니다: ${errorMessage(e)}`, 'manual');
+        }
+        if (!data || typeof data !== 'object' || Array.isArray(data))
+            throw new WorkspaceError(`기존 ${config} 가 객체가 아니라 바꾸지 않았습니다.`, 'manual');
+    }
+    // 폴더 안의 저장소는 상대 경로로 적어 작업 폴더를 통째로 옮겨도 맞게 한다.
+    const relative = path.relative(from, wanted);
+    const value = !relative || relative.startsWith('..') || path.isAbsolute(relative) ? wanted : relative.replaceAll(path.sep, '/');
+    fs.writeFileSync(config, JSON.stringify({ ...data, repo: value }, null, 2) + '\n');
+    return { config, repo, value };
+}

package/src/workspace.mts

@@ -0,0 +1,220 @@
+/** 작업 폴더 → 대상 Git 저장소. MCP 서버·로컬 세션 연결·CLI가 이 한 곳에서 정한다.
+ *
+ * 사람이 AI 도구를 여는 폴더가 Git 저장소가 아닐 수 있다. 예: 한 저장소의 worktree
+ * 여러 개를 나란히 담아 둔 `robotable_hj_workspace`. 위로만 찾으면 이 폴더는
+ * "Git 저장소 아님"이 되어 연결이 끊긴다. 그래서 위로 찾기에 실패한 폴더에 한해
+ * 아래 순서로 정한다 (D30).
+ *
+ *   0. 수동 설정 — 그 폴더나 조상에 있는 `.axmap.json` 의 `{ "repo": "<경로>" }`
+ *   1. 자동 탐색 — 바로 아래 자식 폴더(깊이 1)의 Git 저장소를 공통 디렉터리로 묶어
+ *                  묶음이 정확히 하나면 그 저장소
+ *   2. 모호함   — 묶음이 둘 이상이면 고르지 않고 후보를 적은 오류를 낸다
+ *
+ * 매번 디스크와 git 에게 다시 묻는다. 캐시하면 사람이 설정 파일을 쓰거나 폴더를
+ * 추가한 뒤에도 서버를 다시 켜기 전까지 옛 판단이 남는다.
+ *
+ * 읽지 못한 것과 없는 것을 구별한다. `.git` 이 있는데 git 이 읽지 못한 자식 폴더를
+ * "저장소 없음"으로 세면, 실제로는 두 저장소인데 하나로 보고 엉뚱한 장부를 잡는다.
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+
+// bin/axmap.mjs·mcp/server.mjs 가 CLI 를 띄울 때마다 import 하므로 Node 내장만 쓴다.
+// 그래서 session-types 의 작은 도우미도 가져오지 않는다.
+const errorMessage = (e: unknown) => e instanceof Error ? e.message : String(e)
+const errorCode = (e: unknown) => e instanceof Error && 'code' in e && typeof e.code === 'string' ? e.code : undefined
+
+export const WORKSPACE_CONFIG = '.axmap.json'
+
+export interface WorkspaceMember { name: string; top: string }
+export interface RepoGroup { key: string; common: string; target: string; members: WorkspaceMember[] }
+export type TargetResolution =
+  | { kind: 'git'; from: string; repo: string }
+  | { kind: 'manual'; from: string; repo: string; config: string }
+  | { kind: 'auto'; from: string; repo: string; group: RepoGroup }
+  | { kind: 'ambiguous'; from: string; groups: RepoGroup[] }
+  | { kind: 'none'; from: string }
+
+/** 오류 문구만으로 종류를 가르지 않도록 사유를 붙인다. */
+export class WorkspaceError extends Error {
+  constructor(message: string, readonly reason: 'ambiguous' | 'manual' | 'unreadable') { super(message) }
+}
+
+// 커밋 훅 안에서는 GIT_DIR 등이 설정돼 있다. 그대로 두면 자식 폴더마다 같은 저장소로
+// 답해서 서로 다른 저장소가 하나로 묶인다. bin/axmap.mjs 의 GIT_ENV_KEYS 와 같은 목록이다.
+const GIT_ENV_KEYS = ['GIT_DIR', 'GIT_WORK_TREE', 'GIT_COMMON_DIR', 'GIT_INDEX_FILE',
+  'GIT_OBJECT_DIRECTORY', 'GIT_ALTERNATE_OBJECT_DIRECTORIES', 'GIT_PREFIX']
+function gitEnv(): NodeJS.ProcessEnv {
+  // "not a git repository" 문구로 판정하므로 번역된 메시지가 나오지 않게 고정한다.
+  const env: NodeJS.ProcessEnv = { ...process.env, LC_ALL: 'C', LANGUAGE: 'C' }
+  for (const key of GIT_ENV_KEYS) delete env[key]
+  return env
+}
+
+type GitAnswer = { ok: true; lines: string[] } | { ok: false; notRepo: boolean; detail: string }
+function askGit(cwd: string, args: string[]): GitAnswer {
+  const r = spawnSync('git', args, { cwd, env: gitEnv(), encoding: 'utf8', windowsHide: true })
+  if (r.error) return { ok: false, notRepo: false, detail: r.error.message }
+  if (r.status === 0) return { ok: true, lines: (r.stdout ?? '').split(/\r?\n/).map(s => s.trim()).filter(Boolean) }
+  const detail = (r.stderr ?? '').trim() || `git 종료 코드 ${r.status}`
+  return { ok: false, notRepo: /not a git repository/i.test(detail), detail }
+}
+
+const real = (p: string) => fs.realpathSync(p)
+/** 공통 디렉터리 비교 키. bridge 의 repoKey 와 같은 규칙이다 (Windows 는 대소문자 무시). */
+export const commonKey = (common: string) => process.platform === 'win32' ? common.toLowerCase() : common
+
+function statOrNull(p: string): fs.Stats | null {
+  try { return fs.statSync(p) } catch (e) {
+    if (['ENOENT', 'ENOTDIR'].includes(errorCode(e) || '')) return null
+    throw e
+  }
+}
+
+/** 폴더가 속한 Git 저장소의 최상위. 저장소 밖이면 null, 판정하지 못하면 예외. */
+export function gitTop(dir: string): string | null {
+  const stat = statOrNull(dir)
+  if (!stat || !stat.isDirectory()) return null
+  const r = askGit(dir, ['rev-parse', '--show-toplevel'])
+  if (r.ok) {
+    if (!r.lines[0]) throw new WorkspaceError(`Git 최상위 폴더를 읽지 못했습니다: ${dir}`, 'unreadable')
+    return real(r.lines[0])
+  }
+  if (r.notRepo) return null
+  throw new WorkspaceError(`Git 저장소인지 확인하지 못했습니다: ${dir}\n  ${r.detail}`, 'unreadable')
+}
+
+/** 그 폴더나 조상에 있는 `.axmap.json`. 없으면 null. 읽지 못하면 예외. */
+export function findWorkspaceConfig(dir: string): string | null {
+  for (let at = path.resolve(dir); ; at = path.dirname(at)) {
+    const candidate = path.join(at, WORKSPACE_CONFIG)
+    const stat = statOrNull(candidate)
+    if (stat) return candidate
+    if (path.dirname(at) === at) return null
+  }
+}
+
+function manualTarget(config: string): string {
+  let data: unknown
+  try { data = JSON.parse(fs.readFileSync(config, 'utf8')) } catch (e) {
+    throw new WorkspaceError(`작업 폴더 설정을 읽지 못했습니다: ${config}\n  ${errorMessage(e)}`, 'manual')
+  }
+  const repo = (data as { repo?: unknown } | null)?.repo
+  if (!data || typeof data !== 'object' || Array.isArray(data) || typeof repo !== 'string' || !repo.trim()) {
+    throw new WorkspaceError(`작업 폴더 설정에 "repo" 경로가 없습니다: ${config}\n  예: { "repo": "폴더이름" }`, 'manual')
+  }
+  const wanted = path.resolve(path.dirname(config), repo)
+  // 설정이 틀렸을 때 자동 탐색으로 넘어가지 않는다. 사람이 고른 것을 몰래 바꾸면
+  // 다른 저장소의 장부에 선점이 남는다.
+  const top = gitTop(wanted)
+  if (!top) throw new WorkspaceError(`작업 폴더 설정의 저장소가 Git 저장소가 아닙니다: ${wanted}\n  (설정 파일: ${config})`, 'manual')
+  return top
+}
+
+function scanChildren(dir: string): { groups: RepoGroup[]; unreadable: string[] } {
+  let entries: fs.Dirent[]
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }) } catch (e) {
+    throw new WorkspaceError(`작업 폴더의 하위 폴더를 읽지 못했습니다: ${dir}\n  ${errorMessage(e)}`, 'unreadable')
+  }
+  const groups = new Map<string, RepoGroup>(), unreadable: string[] = []
+  for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+    if (entry.name.startsWith('.') || entry.name === 'node_modules') continue
+    const child = path.join(dir, entry.name)
+    try {
+      // worktree 폴더가 심볼릭 링크·junction 일 수 있어 링크는 따라가서 본다.
+      const isDir = entry.isDirectory() || (entry.isSymbolicLink() && !!statOrNull(child)?.isDirectory())
+      if (!isDir) continue
+      // `.git` 이 없는 폴더는 저장소의 최상위가 아니다. git 을 띄우지 않고 넘어간다.
+      if (fs.lstatSync(path.join(child, '.git'), { throwIfNoEntry: false }) === undefined) continue
+    } catch (e) { unreadable.push(`${entry.name} (${errorMessage(e)})`); continue }
+    const r = askGit(child, ['rev-parse', '--path-format=absolute', '--show-toplevel', '--git-common-dir'])
+    if (!r.ok || r.lines.length < 2) { unreadable.push(`${entry.name} (${r.ok ? 'git 응답이 비어 있음' : r.detail})`); continue }
+    let top: string, common: string
+    try { top = real(r.lines[0]); common = real(r.lines[1]) } catch (e) { unreadable.push(`${entry.name} (${errorMessage(e)})`); continue }
+    const key = commonKey(common)
+    const group = groups.get(key) ?? { key, common, target: '', members: [] }
+    group.members.push({ name: entry.name, top })
+    groups.set(key, group)
+  }
+  for (const group of groups.values()) {
+    // 메인 체크아웃(공통 디렉터리 `.git` 의 부모)을 겨눈다. 장부도 거기 있다.
+    // bare 저장소처럼 그 부모가 체크아웃이 아니면 첫 번째 worktree 를 쓴다.
+    const parent = path.dirname(group.common)
+    group.target = path.basename(group.common).toLowerCase() === '.git' && statOrNull(parent)?.isDirectory()
+      ? real(parent) : group.members[0].top
+  }
+  return { groups: [...groups.values()], unreadable }
+}
+
+/** 무엇을 왜 고르는지까지 돌려준다. 모호함은 예외가 아니라 결과다 (`workspace show` 용). */
+export function inspectTarget(dir: string): TargetResolution {
+  const from = path.resolve(dir)
+  const top = gitTop(from)
+  if (top) return { kind: 'git', from, repo: top }
+  if (!statOrNull(from)?.isDirectory()) return { kind: 'none', from }
+  const config = findWorkspaceConfig(from)
+  if (config) return { kind: 'manual', from, repo: manualTarget(config), config }
+  const { groups, unreadable } = scanChildren(from)
+  if (unreadable.length) {
+    throw new WorkspaceError([
+      `작업 폴더 ${from} 아래에서 확인하지 못한 Git 폴더가 있어 대상 저장소를 정하지 않았습니다.`,
+      ...unreadable.map(s => `  - ${s}`),
+      `저장소를 직접 고르려면 이 폴더에서 \`axmap workspace use <폴더>\` 를 실행하세요.`,
+    ].join('\n'), 'unreadable')
+  }
+  if (groups.length === 1) return { kind: 'auto', from, repo: groups[0].target, group: groups[0] }
+  if (groups.length > 1) return { kind: 'ambiguous', from, groups }
+  return { kind: 'none', from }
+}
+
+export function ambiguityMessage(r: Extract<TargetResolution, { kind: 'ambiguous' }>): string {
+  return [
+    `작업 폴더 ${r.from} 아래에 서로 다른 Git 저장소가 ${r.groups.length}개 있어 하나로 정하지 않았습니다.`,
+    ...r.groups.map(g => `  - ${g.target}  (폴더: ${g.members.map(m => m.name).join(', ')})`),
+    '고르는 방법 (둘 중 하나):',
+    '  1. 도구를 부를 때 cwd 에 작업할 저장소 폴더의 절대 경로를 넘긴다.',
+    `  2. 이 폴더에 ${WORKSPACE_CONFIG} 을 둔다: { "repo": "${r.groups[0].members[0].name}" }`,
+    `     터미널에서는: axmap workspace use ${r.groups[0].members[0].name}`,
+  ].join('\n')
+}
+
+/** 대상 저장소 경로. 저장소가 없으면 null, 모호하거나 판정하지 못하면 예외. */
+export function resolveTarget(dir: string): string | null {
+  const r = inspectTarget(dir)
+  if (r.kind === 'ambiguous') throw new WorkspaceError(ambiguityMessage(r), 'ambiguous')
+  return r.kind === 'none' ? null : r.repo
+}
+
+export function describeTarget(r: TargetResolution): string {
+  switch (r.kind) {
+    case 'git': return `대상 저장소: ${r.repo}\n이유: 작업 폴더가 Git 저장소 안에 있습니다.`
+    case 'manual': return `대상 저장소: ${r.repo}\n이유: 수동 설정 ${r.config}`
+    case 'auto': return `대상 저장소: ${r.repo}\n이유: 자동 탐색 — 하위 폴더가 모두 같은 저장소입니다 (${r.group.members.map(m => m.name).join(', ')}).`
+    case 'ambiguous': return ambiguityMessage(r)
+    case 'none': return `대상 저장소 없음: ${r.from}\n이유: 이 폴더와 바로 아래 폴더에서 Git 저장소를 찾지 못했습니다.`
+  }
+}
+
+/** `axmap workspace use` — 사람이 고른 저장소를 작업 폴더의 `.axmap.json` 에 적는다. */
+export function writeWorkspaceChoice(dir: string, choice: string): { config: string; repo: string; value: string } {
+  const from = path.resolve(dir)
+  if (gitTop(from)) throw new WorkspaceError(`이 폴더는 이미 Git 저장소 안이라 ${WORKSPACE_CONFIG} 를 쓰지 않습니다: ${from}`, 'manual')
+  const wanted = path.resolve(from, choice)
+  const repo = gitTop(wanted)
+  if (!repo) throw new WorkspaceError(`Git 저장소가 아닙니다: ${wanted}`, 'manual')
+  const config = path.join(from, WORKSPACE_CONFIG)
+  let data: Record<string, unknown> = {}
+  if (statOrNull(config)) {
+    // 읽지 못한 설정은 덮어쓰지 않는다 (D23 과 같은 원칙).
+    try { data = JSON.parse(fs.readFileSync(config, 'utf8')) } catch (e) {
+      throw new WorkspaceError(`기존 ${config} 를 읽지 못해 바꾸지 않았습니다: ${errorMessage(e)}`, 'manual')
+    }
+    if (!data || typeof data !== 'object' || Array.isArray(data)) throw new WorkspaceError(`기존 ${config} 가 객체가 아니라 바꾸지 않았습니다.`, 'manual')
+  }
+  // 폴더 안의 저장소는 상대 경로로 적어 작업 폴더를 통째로 옮겨도 맞게 한다.
+  const relative = path.relative(from, wanted)
+  const value = !relative || relative.startsWith('..') || path.isAbsolute(relative) ? wanted : relative.replaceAll(path.sep, '/')
+  fs.writeFileSync(config, JSON.stringify({ ...data, repo: value }, null, 2) + '\n')
+  return { config, repo, value }
+}

package/tools/build.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-/** TS owns migrated modules; checked-in JS keeps Node 20 and vendored installs usable. */
+/** TS owns migrated modules; checked-in JS keeps Node 20 source checkouts and npm installs usable without a build step. */
 import fs from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'

package/tools/bus.mjs

@@ -1002,7 +1002,7 @@ function publish(id) {
 
 /**
  * 이 파일을 지금 폴더에서 부르는 명령. **문자열로 적지 않고 계산한다.**
- * 벤더링된 사본에서는 `tools/bus.mjs` 가 아니라 `ci/axmap/tools/bus.mjs` 다.
+ * 이 파일은 도구가 설치된 자리(npm 설치본·axMap 저장소)에 있고, 그 자리는 기계마다 다르다.
  */
 function selfCmd() {
   const self = fileURLToPath(import.meta.url)