axmap-cli 1.8.0 → 1.10.0

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/bridge.mjs

@@ -34,12 +34,14 @@ try {
     case 'connect':
     case 'serve': {
       const provider = args[1]
-      if (!['codex', 'agy'].includes(provider)) throw new Error('axmap bridge serve codex|agy를 사용하세요.')
+      if (!['codex', 'agy', 'claude'].includes(provider)) throw new Error('axmap bridge serve codex|agy|claude를 사용하세요.')
       const binary = resolveBin(provider)
       if (!binary) throw new Error(`${provider} 실행 파일을 찾지 못했습니다.`)
       const [executable, ...prefix] = provider === 'codex' ? codexInvocation(binary) : [binary]
       if (command === 'connect' && (!option('thread') || !option('socket'))) throw new Error('bridge connect codex --thread <기존 UUID> --socket <로컬 경로>가 필요합니다.')
       const session = await startManagedSession({ provider, executable, prefix, model: option('model'), role: option('role'),
+        ...(provider === 'claude' && option('permission-mode') ? { permissionMode: option('permission-mode') } : {}),
+        ...(option('timeout-ms') ? { timeoutMs: Number(option('timeout-ms')) } : {}),
         ...(command === 'connect' ? { existingThreadId: option('thread'), socketPath: option('socket'), observeActive: args.includes('--observe') } : {}),
         maxTokens: Number(option('max-tokens') || 100000), onEvent: output })
       output({ event: 'connected', ...session, exited: undefined, close: undefined })
@@ -52,6 +54,8 @@ try {
       const options = { ...(option('id') ? { id: option('id') } : {}), left: option('left'), right: option('right'), prompt: fs.readFileSync(0, 'utf8'),
         maxTurns: Number(option('max-turns') || 4), maxTokens: Number(option('max-tokens') || 50000),
         maxMessageChars: Number(option('max-message-chars') || 2000),
+        ...(option('timeout-ms') ? { timeoutMs: Number(option('timeout-ms')) } : {}),
+        ...(option('done-by') ? { doneBy: option('done-by') } : {}),
         onEvent: event => console.error(JSON.stringify(event)) }
       const r = args.includes('--background') ? await startBackgroundDialogue(options) : await runDialogue(options)
       output(r); if (r.state !== 'completed') process.exitCode = 2
@@ -85,8 +89,8 @@ try {
     case 'send': {
       const waitMs = Number(option('wait-ms') || 0)
       if (!Number.isInteger(waitMs) || waitMs < 0 || waitMs > 30000) throw new Error('wait-ms는 0~30000 정수여야 합니다.')
-      const r = dispatchRequest({ to: option('to'), prompt: fs.readFileSync(0, 'utf8'), cwd: process.cwd(), from: process.env.AXMAP_AGENT || 'axmap' })
-      const result = waitMs && r.state === 'submitted' ? await waitForRequest(r.id, process.cwd(), waitMs) : r
+      const r = dispatchRequest({ to: option('to'), prompt: fs.readFileSync(0, 'utf8'), cwd: process.cwd(), from: process.env.AXMAP_AGENT || 'axmap', queueIfBusy: !args.includes('--no-queue') })
+      const result = waitMs && ['queued', 'submitted'].includes(r.state) ? await waitForRequest(r.id, process.cwd(), waitMs) : r
       output(result)
       if (result.state === 'unknown') process.exitCode = 2
       break
@@ -95,12 +99,15 @@ try {
     case undefined:
     case '--help':
       console.log(`axMap 로컬 세션 연결 — 관리형 Codex/agy와 제한된 자동 대화
-axmap bridge serve codex|agy [--model 이름] [--role 역할] [--max-tokens 100000]
+axmap bridge serve codex|agy|claude [--model 이름] [--role 역할] [--max-tokens 100000]
+    claude 는 --permission-mode default|plan|acceptEdits (기본 default: 읽기만, 고치기는 거절)
+    --timeout-ms 한 실행의 시간 한도(기본 120000). 넘기면 결과가 불명확하므로 세션을 닫고 재시도하지 않습니다.
     명시적으로 새 관리형 CLI를 시작합니다. 기존 창에 임의로 붙지 않습니다.
 axmap bridge connect codex --thread <기존 UUID> --socket <로컬 socket> [--role 역할] [--observe]
     실행 중인 공식 Codex daemon의 기존 idle 대화에 연결합니다. 새 모델/대화를 만들지 않습니다.
     --observe는 active 대화에도 관측만 연결하며 idle 전환 전에는 새 요청을 거절합니다.
-axmap bridge chat --left <UUID> --right <UUID> [--max-turns 4] [--max-tokens 50000]
+axmap bridge chat --left <UUID> --right <UUID> [--max-turns 4] [--max-tokens 50000] [--done-by <UUID>] [--timeout-ms 120000]
+    --done-by 를 주면 그 세션의 done:true 만 대화를 끝냅니다(다른 쪽 done 은 기록만).
     stdin 작업을 자동 중계합니다. 기본 메시지 한도 2000자, 대기 중 모델 호출 없음.
 axmap bridge answer --to <UUID> --request <ID> --decision accept|decline|cancel
     Codex가 요청한 이번 실행의 승인을 사용자가 결정합니다.
@@ -111,9 +118,10 @@ axmap bridge install --experimental --executable <agy 절대 경로>   연결
 axmap bridge uninstall                             추가한 연결 훅 해제
 axmap bridge sessions                              이 repo에 연결된 세션
 axmap bridge notice --to <UUID>                    stdin 안내를 기존 Codex 문맥에 기록 (모델 호출 없음)
-axmap bridge attach --pid <PID>                    이미 실행한 Windows agy 콘솔을 현재 repo에 연결
+axmap bridge attach --pid <PID>                    이미 실행한 Windows agy·Claude 콘솔을 현재 repo에 연결
 axmap bridge status [--json]                        로컬 연결·작업·승인 대기·종료 상태 조회 (모델 호출 없음)
 axmap bridge send --to <세션 UUID> [--wait-ms 30000] 본문은 stdin. 전달 후 지정 시간까지 로컬에서 회신 대기
+    관리형 stdio와 Windows 일반 Claude 콘솔은 작업 중 FIFO 접수 후 실행합니다. --no-queue로 거절 모드.
     send는 실행용 저수준 명령입니다. 일반 협업 알림에는 message를 사용하세요.
 axmap bridge message --to <UUID> [--topic <갱신 주제>] [--key <중복 방지 키>] [--ttl-seconds 3600]
     stdin 일반 메시지를 큐에 저장합니다. 모델 호출·새 턴 없음. 같은 발신자의 대기 중 topic만 최신으로 합칩니다.

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)

package/tools/console-queue.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { runConsoleQueue } from '../src/bridge.mjs'
+try { runConsoleQueue(process.argv[2], process.argv[3]) } catch (e) { console.error(e.message); process.exitCode = 1 }

package/tools/run.mjs

@@ -4,21 +4,28 @@ import path from 'node:path'
 import { spawnSync } from 'node:child_process'
 import { startTerminal, sendTerminal, installTerminalHooks, installTerminalRuntime } from '../src/terminal-bridge.mjs'
 import { registerExternalHook } from '../src/external-console.mjs'
+import { RPC_NOT_DELIVERED_EXIT } from '../src/session-types.mjs'
 
 const [command, ...args] = process.argv.slice(2)
 try {
   if (command === 'install-runtime') {
     console.log(JSON.stringify(installTerminalRuntime(args[0])))
   } else if (command === 'install-hooks') {
-    console.log(JSON.stringify({ hooks: [installTerminalHooks(), installTerminalHooks(undefined, 'codex')] }))
+    console.log(JSON.stringify({ hooks: (args[0] ? [args[0]] : ['agy', 'codex', 'claude']).map(provider => installTerminalHooks(undefined, provider)) }))
   } else if (command === 'rpc') {
-    console.log(JSON.stringify(await sendTerminal(args[0], JSON.parse(fs.readFileSync(0, 'utf8')))))
+    try { console.log(JSON.stringify(await sendTerminal(args[0], JSON.parse(fs.readFileSync(0, 'utf8'))))) }
+    catch (e) {
+      if (e?.notDelivered !== true) throw e
+      // 연결 전에 실패해 아무것도 보내지 않았다. 호출한 쪽(bridge.terminalRPC)이
+      // 문구가 아니라 종료 코드로 "확실히 미전달"을 알아보게 한다.
+      console.error(e.message); process.exitCode = RPC_NOT_DELIVERED_EXIT
+    }
   } else if (command === 'hook') {
     const input = JSON.parse(fs.readFileSync(0, 'utf8'))
     if (process.env.AXMAP_TERMINAL_SESSION && process.env.AXMAP_TERMINAL_TOKEN) {
       await sendTerminal(process.env.AXMAP_TERMINAL_SESSION, { action: 'hook', event: args[0], input }, process.env.AXMAP_TERMINAL_TOKEN)
-    } else if (process.platform === 'win32' && input.conversationId) {
-      try { registerExternalHook(input, args[0]) }
+    } else if (process.platform === 'win32' && (input.conversationId || input.session_id)) {
+      try { registerExternalHook(input, args[0], args.includes('--provider') ? args[args.indexOf('--provider') + 1] : undefined) }
       catch (e) { console.error(`axMap 독립 콘솔: ${e.message}`) }
     }
     console.log('{}')

package/tools/setup.mjs

@@ -257,7 +257,7 @@ if (!has('--no-register')) {
   else {
     const hookRunner = path.join(DEST, 'tools', 'run.mjs')
     const r = spawnSync(process.execPath, [hookRunner, 'install-hooks'], { encoding: 'utf8', windowsHide: true })
-    if (r.status === 0) ok('세션 연결', 'Windows에서 직접 여는 agy와 axmap run CLI가 자동 연결됩니다')
+    if (r.status === 0) ok('세션 연결', 'Windows에서 직접 여는 Claude Code·agy와 axmap run CLI가 자동 연결됩니다')
     else no('세션 연결', r.stderr?.trim() || '연결 훅 등록 실패')
   }
 }