axmap-cli 1.3.2 → 1.4.0

package/CLAUDE.md

@@ -1,21 +1,27 @@
 # axMap 작업 규칙
 
-axMap은 여러 AI 에이전트의 작업 경로를 선점하고 충돌을 예방하는 CLI 도구다. 현재 개발 범위는 CLI와 MCP를 통한 협업 기능이다. 코드 분석·지도·코퍼스 기준 도구로의 확장은 보류한다. 범위 결정은 `docs/DECISIONS.md`의 D21을 따른다. 산문은 `axMap`, 식별자와 명령은 `axmap`, npm 패키지는 `axmap-cli`를 쓴다.
+axMap은 여러 AI 에이전트의 작업 경로를 선점하고 충돌을 예방하는 CLI·MCP 협업 도구다.
+쪽지와 로컬 세션 연결도 이 범위에 포함한다. 현재 제품 결정은 `docs/DECISIONS.md`를 따른다.
+산문은 `axMap`, 식별자와 명령은 `axmap`, npm 패키지는 `axmap-cli`를 쓴다.
 
-개발 기준은 `main`이다. 이 저장소의 소스 확인에는 `node bin/axmap.mjs`를 사용한다. PATH의 `axmap`은 npm 설치본일 수 있다.
+개발 기준은 `main`이다. 소스 확인에는 `node bin/axmap.mjs`를 사용한다.
+PATH의 `axmap`은 npm 설치본일 수 있다.
 
 ## 작업 절차
 
-1. `docs/DECISIONS.md`, `docs/THREADS.md`, `docs/SPEC.md`, `docs/INVARIANTS.md`에서 관련 결정과 규격을 읽는다.
-2. 세션마다 고유한 `AXMAP_AGENT`와 `AXMAP_SESSION`을 정한다. 변경 전에 `node bin/axmap.mjs claim <경로> --task <작업> --intent "목적"`으로 선점한다.
-3. 선점이 겹치면 다른 영역으로 옮긴다. 필요한 경로만 잡고, 끝나면 `node bin/axmap.mjs release`로 반납한다.
+1. `docs/DECISIONS.md`, `docs/THREADS.md`, `docs/SPEC.md`, `docs/INVARIANTS.md`에서 관련 내용을 읽는다.
+2. 세션마다 고유한 `AXMAP_AGENT`와 `AXMAP_SESSION`을 정하고, 변경 전에 필요한 경로를 선점한다.
+3. 선점이 겹치면 다른 영역으로 옮긴다. 작업이 끝나면 같은 신원으로 반납한다.
 4. 선점 없는 커밋을 만들거나 `git commit --no-verify`로 훅을 우회하지 않는다. push 대상 원격과 브랜치를 확인한다.
 
 ## 구현 기준
 
-루트 CLI는 Node 20+와 git만으로 동작한다. 새 의존성은 추가 전에 사용자와 논의한다. 데스크톱 셸의 기존 의존성은 `desktop/package.json`을 따른다.
+Node 20+와 Git을 사용한다. 터미널 연결 의존성은 npm 설치에 포함하며 별도 컴파일러 설치를 요구하지 않는다.
+새 의존성은 추가 전에 사용자와 논의한다. 이번 터미널 의존성 추가는 사용자가 승인했다.
 
-없는 데이터와 읽지 못한 데이터를 구별한다. 판정을 못 하면 통과시키지 않는다. 주석에는 구현 이유를 쓰고, 수치에는 측정 조건과 근거를 붙인다. 테스트 개수나 미측정 성능을 문서에 쓰지 않는다.
+없는 데이터와 읽지 못한 데이터를 구별한다. 판정을 못 하면 통과시키지 않는다.
+주석에는 구현 이유를 쓰고, 수치에는 측정 조건과 근거를 붙인다. 테스트 개수나 미측정 성능을 문서에 쓰지 않는다.
+가짜 provider의 테스트 결과를 실제 AI CLI 연결 성공으로 소개하지 않는다.
 
 ## 검증
 
@@ -24,7 +30,7 @@ npm test
 npm run demo
 npm run demo:compare
 npm run demo:chaos
-npm run smoke
 ```
 
-프로토콜 변경은 회귀 테스트와 경합 데모로 검증하고, 화면 변경은 브라우저 스모크를 돌린다. 데스크톱 변경은 설치된 Electron으로 `npm run desktop:smoke`를 추가한다. 성공 여부는 종료 코드로 판단한다. 필요한 실행 환경이 없으면 검증 제한을 보고한다.
+프로토콜 변경은 회귀 테스트와 경합 데모로 검증한다. 설치 변경은 격리된 사용자 환경에서 검사한다.
+성공 여부는 종료 코드로 판단한다. 필요한 실행 환경이 없으면 검증 제한을 보고한다.

package/README.ko.md

@@ -1,130 +1,134 @@
 # axMap
 
-[![English](https://raw.githubusercontent.com/rl2aderjoon/axmap/main/docs/assets/readme-en.svg)](https://github.com/rl2aderjoon/axmap/blob/main/README.md) [![한국어](https://raw.githubusercontent.com/rl2aderjoon/axmap/main/docs/assets/readme-ko.svg)](https://github.com/rl2aderjoon/axmap/blob/main/README.ko.md)
+**한 저장소에서 일하는 여러 AI가 서로의 작업을 덮어쓰지 않도록.**
 
-**여러 AI 에이전트가 같은 git 저장소에서 작업할 때, 수정할 경로를 먼저 선점해 충돌을 예방하는 CLI 도구.**
+axMap은 수정할 파일과 폴더를 미리 선점하고, 겹치는 작업을 알려주는 협업 CLI입니다.
+Codex·Antigravity·Claude Code에서는 MCP로 선점과 반납, 상태 확인, 쪽지 기능을 사용할 수 있습니다.
 
-누가 어디를 고치는지 장부에 기록하고, 겹치는 경로의 선점을 거부한다.
-커밋 훅으로 선점 범위를 확인하고, 작업이 끝나면 반납한다.
-AI 도구에서는 MCP로 같은 기능을 사용할 수 있다.
-
-Node 20+와 git이 필요하다. CLI의 런타임 의존성은 없다.
-npm 패키지 이름은 `axmap-cli`, 실행 명령은 `axmap`이다.
+[English](README.md) · **한국어**   /   Node.js 20+ · Git · MIT
 
 ## 설치
 
-Git 저장소 밖을 포함해 어느 폴더에서든 실행한다.
-
 ```bash
 npm install -g axmap-cli@latest
 axmap setup
 ```
 
-`setup`은 이 PC에 axMap을 설치하고 AI 도구의 사용자 설정에 MCP를 등록한다. 실행한 폴더에 타겟을 고정하거나 repo를 초기화하지 않는다.
-MCP를 사용하려면 설정 후 AI 도구를 다시 시작한다.
-함께 작업하는 사람과 에이전트는 같은 원격 장부를 사용해야 서로의 선점을 볼 수 있다.
+어느 폴더에서든 한 번 설정한 뒤 AI 도구를 다시 시작하세요.
+새 Git 저장소의 장부는 첫 사용 때 자동으로 준비합니다. 함께 일하는 사람은 같은 원격 장부를 사용합니다.
 
-## 1.3.2: 쪽지 표시 이름과 사용자 자동 공유
+[사용법](docs/INSTALL.md) · [MCP 연결](mcp/README.md) · [개발 가이드](docs/ONBOARD-TEAM.md)
 
-대화형 `setup`에서 `장효준`, `John Smith`처럼 쪽지에 표시할 이름을 입력한다. 입력 없이 설정하거나 오타를 고치려면 `axmap setup --name "장효준"`을 실행한다. 재설치할 때는 저장된 이름을 유지하며 Git 이름·이메일 설정은 바꾸지 않는다.
+---
 
-각 repo에서 axMap을 처음 사용하면 해당 repo의 Git 이메일을 읽고 기존 `axmap/users` 고아 브랜치에 표시 이름을 자동 공유한다. 코드 커밋이나 repo별 수동 등록은 필요 없다. 다른 팀원은 사용자 정보 동기화 후 수신자로 발견한다. 원격 push 권한이 필요하며, 공유 실패는 경고하고 다음 사용 때 재시도한다. `setup`만 실행하고 사용한 적 없는 repo에는 등록하지 않는다.
+## 변경 기록
 
-`axmap bus contacts`로 수신자 이름·이메일을 확인한다. 아는 이름으로 보낸 쪽지는 이메일 주소로 저장하므로 이름을 고쳐도 수신·읽음 기록이 이어진다. 동명이인은 이메일로 지정한다. 쪽지 자동 등록은 투표권이나 MR 승인 권한을 부여하지 않는다.
+최신 변경부터 정리합니다.
 
-자세한 설치·설정은 [docs/INSTALL.md](https://github.com/rl2aderjoon/axmap/blob/main/docs/INSTALL.md)를 참고한다.
+### 1.4.0
 
-## 1.3.1: 어느 폴더에서든 setup 한 번, 이후 repo 자동 연결
+<sub>2026.10.20</sub>
 
-axMap을 한 번 설정하면 다른 Git 저장소에서도 Codex 등 AI CLI를 열어 바로 사용할 수 있다. 세션의 작업 repo를 자동으로 선택하고, 첫 조회·선점 때 장부를 준비하므로 매번 `axmap init`을 실행하지 않아도 된다.
+**Codex와 Antigravity가 제한된 자동 대화를 주고받으며 토큰 사용량을 추적합니다.**
 
-기존 원격 장부가 있으면 이어 쓰고, 같은 repo의 worktree는 장부 하나를 공유한다. 서로 다른 repo의 동시 세션은 독립적으로 동작한다. 원격 접근 실패를 장부 없음으로 판단해 별도 장부를 만들지 않는다.
+**추가**
 
-MCP는 클라이언트가 알려주는 작업 폴더(roots)를 따라간다. 미지원 클라이언트는 시작 폴더를 사용하며, 도중에 폴더를 바꾸면 도구의 `cwd`에 작업 폴더 절대 경로를 전달한다. 커밋 훅을 적용할 새 repo에서는 `axmap hook install`을 실행한다.
+- `axmap bridge serve codex|agy`로 관리형 CLI를 한 번 시작하고, `bridge chat`으로 완료 또는 한도까지 짧은 메시지를 자동 중계합니다.
+- MCP `ax_chat`, `ax_dialogue`, `ax_chat_stop`으로 중계 시작·조회·중단을 제공합니다. 요청별·누적 토큰과 캐시 사용량을 기록하며 대기 중에는 모델을 호출하지 않습니다.
+- 별도 `axmap run`은 사용자가 직접 여는 대화형 터미널을 연결하는 프로토타입입니다.
+- 터미널 연결 의존성을 npm 설치에 포함하고, setup의 실행 사본에도 함께 준비합니다.
 
-기존 설치를 업그레이드할 때도 어느 폴더에서든 아래 명령을 한 번 실행하고 AI CLI를 다시 시작한다.
+**정리**
 
-```bash
-npm install -g axmap-cli@latest
-axmap setup
-```
+- 코드 시각화 화면, Electron 앱, 코드 분석·코퍼스 도구와 관련 테스트·연구 문서를 제거했습니다.
+- 설치와 MCP에서 쓰는 CLI 탐지 코드를 공용 모듈로 분리했습니다.
 
-`setup`은 MCP와 공유 훅 실행 사본 및 등록을 갱신한다. 이후 repo를 옮길 때는 setup이나 init을 반복하지 않는다. 특정 repo의 장부와 커밋 훅까지 미리 준비하려면 `axmap setup --repo <경로>`를 명시한다.
+**검증 상태**
 
-## 작업 흐름
+Windows에서 실제 Codex 0.163.0·agy 1.4.2의 문맥을 유지한 4회 자동 중계와 MCP를 통한 2회 백그라운드 중계를 확인했습니다.
+검증 합계는 처리 102590토큰(캐시 입력 54400, 출력 393 포함)입니다. 짧은 메시지도 CLI의 기본 문맥 비용이 크며, 예산은 다음 실행 전에 검사하므로 실행 중 엄격한 토큰 상한은 아닙니다.
+별도 대화형 PTY 경로는 가짜 프로그램 회귀 검증 단계입니다.
+[개발 상태 보기 →](docs/SESSION-BRIDGE.md)
 
-```bash
-# 지금 누가 무엇을 잡고 있는지 확인
-axmap status
+---
 
-# 수정 전에 경로와 목적을 선언
-axmap claim src/auth --agent my-agent --session my-session --task T-12 --intent "토큰 만료 처리"
+### 1.3.3
 
-# 파일을 수정한 뒤 커밋할 변경을 준비하고 선점 범위를 확인
-git add src/auth
-axmap verify --agent my-agent --session my-session
+<sub>2026.10.16</sub>
 
-# 작업이 끝나면 반납
-axmap release --agent my-agent --session my-session
-```
+**Windows에서 npm으로 설치한 Codex도 정상 연결됩니다.**
 
-에이전트 이름과 세션은 각 작업 세션마다 고유하게 정하고, 선점부터 반납까지 같은 값을 쓴다.
-커밋 훅에서도 같은 식별자를 사용하도록 `AXMAP_AGENT`와 `AXMAP_SESSION` 환경변수를 설정한다.
-선점이 거절되면 메시지의 점유자·작업·남은 시간을 확인하고 겹치지 않는 영역을 선택한다.
-필요한 경로만 잡고, 작업이 길어지면 `axmap renew`에 같은 agent와 session을 지정해 갱신한다.
+**수정**
 
-`git worktree`로 나눈 작업 폴더도 같은 장부를 사용한다.
-`release`는 현재 세션이 잡은 경로를 반납한다.
+- `axmap setup`이 Codex 패키지의 Node 진입점을 직접 실행합니다.
+- 설치 경로에 공백이 있거나 인수에 따옴표가 있어도 셸 해석으로 값이 바뀌지 않도록 했습니다.
 
-## 동작 방식
+[릴리스 소스 →](https://github.com/rl2aderjoon/axmap/tree/v1.3.3)
 
-git은 변경을 합칠 때 텍스트 충돌을 발견한다.
-axMap은 수정 전에 경로를 선점해, 여러 에이전트가 같은 영역을 동시에 고치는 상황을 먼저 막는다.
+---
 
-선점 장부는 전용 git 브랜치에 저장한다. 원격의 최신 장부를 확인하고,
-git ref의 원자적 갱신과 경로 겹침 판정으로 선점한다.
-커밋 훅은 실제 수정 경로와 선점 범위를 대조한다.
-`axmap audit`은 장부 이력을 재생해 규칙 위반을 검사한다.
+### 1.3.2
 
-상태를 읽지 못하면 그 이유를 알리고, 판정할 수 없는 상태를 성공으로 처리하지 않는다.
-프로토콜은 [docs/SPEC.md](https://github.com/rl2aderjoon/axmap/blob/main/docs/SPEC.md), 지켜야 할 성질은 [docs/INVARIANTS.md](https://github.com/rl2aderjoon/axmap/blob/main/docs/INVARIANTS.md)에 있다.
+<sub>2026.10.16</sub>
 
-## AI 도구에서 사용
+**쪽지에 표시할 이름을 정하고, 동료를 자동으로 찾습니다.**
 
-MCP를 연결하면 `ax_claim`, `ax_status`, `ax_release` 등의 도구를 AI가 호출할 수 있다.
-에이전트에게 다음 작업 규칙을 전달한다.
+**추가**
 
-```text
-파일을 수정하기 전에 ax_claim으로 경로와 목적을 선언한다.
-선점이 거절되면 점유자를 확인하고 겹치지 않는 다른 작업을 선택한다.
-작업이 끝나면 ax_release로 반납한다.
-```
+- 대화형 setup에서 표시 이름을 입력합니다. `axmap setup --name "이름"`으로 바꿀 수도 있습니다.
+- 저장소를 처음 사용할 때 Git 이메일과 표시 이름을 팀의 사용자 장부에 공유합니다.
+- `axmap bus contacts`로 쪽지를 받을 사람을 확인합니다.
 
-연결 방법과 도구 목록은 [mcp/README.md](https://github.com/rl2aderjoon/axmap/blob/main/mcp/README.md)를 참고한다.
+**개선**
 
-## 개발과 검증
+- 이름으로 보낸 쪽지는 확인된 이메일로 저장해, 이름을 바꿔도 수신·읽음 기록이 이어집니다.
+- 동명이인은 이메일로 구분하며, 공유 실패는 경고하고 다음 사용 때 재시도합니다.
+- Git 이름·이메일 설정과 투표 권한은 변경하지 않습니다.
 
-```bash
-git clone https://github.com/rl2aderjoon/axmap.git
-cd axmap
-node bin/axmap.mjs --version
-npm test
-npm run demo
-npm run demo:compare
-npm run demo:chaos
-```
+[릴리스 소스 →](https://github.com/rl2aderjoon/axmap/tree/v1.3.2)
+
+---
+
+### 1.3.1
+
+<sub>2026.10.15</sub>
+
+**setup은 어느 폴더에서든 한 번이면 됩니다.**
+
+**개선**
+
+- Git 저장소 밖에서도 설치와 MCP 등록을 할 수 있습니다.
+- setup을 실행한 폴더에 이후 작업 대상을 고정하지 않습니다.
+- 기존 MCP 등록의 서버 경로와 환경을 갱신하면서 개인 설정과 다른 서버는 보존합니다.
+
+특정 저장소의 장부와 커밋 훅까지 준비하려면 `axmap setup --repo <경로>`를 사용합니다.
+
+[릴리스 소스 →](https://github.com/rl2aderjoon/axmap/tree/v1.3.1)
+
+---
+
+### 1.3.0
+
+<sub>2026.10.15</sub>
+
+**저장소를 옮겨도, 세션의 작업 위치를 따라갑니다.**
+
+**추가**
+
+- 첫 상태 조회·선점 때 장부를 자동으로 준비해 저장소마다 `init`을 반복하지 않아도 됩니다.
+- MCP가 클라이언트의 작업 폴더(roots)와 변경 알림을 지원합니다.
+
+**개선**
+
+- 기존 원격 장부를 이어 쓰고, 같은 저장소의 worktree는 장부 하나를 공유합니다.
+- 서로 다른 저장소에서 실행한 세션은 독립적으로 동작합니다.
+- 원격 접근 실패를 빈 장부로 취급하지 않습니다.
 
-루트 CLI를 실행하기 위한 `npm install`은 필요 없다. 데모는 bash 환경에서 실행한다.
-소스 확인에는 `node bin/axmap.mjs`를 사용한다.
+roots 미지원 도구나 작업 대상이 모호한 경우에는 MCP 인수 `cwd`로 작업 폴더를 지정합니다.
+커밋 검증이 필요한 저장소에는 `axmap hook install`을 실행합니다.
 
-| 문서 | 내용 |
-|---|---|
-| [CLAUDE.md](https://github.com/rl2aderjoon/axmap/blob/main/CLAUDE.md) | 소스 작업 규칙 |
-| [docs/INSTALL.md](https://github.com/rl2aderjoon/axmap/blob/main/docs/INSTALL.md) | 설치와 사용 |
-| [docs/SPEC.md](https://github.com/rl2aderjoon/axmap/blob/main/docs/SPEC.md) | 명령과 선점 프로토콜 |
-| [docs/INVARIANTS.md](https://github.com/rl2aderjoon/axmap/blob/main/docs/INVARIANTS.md) | 불변식과 검증 기준 |
-| [docs/DECISIONS.md](https://github.com/rl2aderjoon/axmap/blob/main/docs/DECISIONS.md) | 제품 범위와 설계 결정 |
+[릴리스 소스 →](https://github.com/rl2aderjoon/axmap/tree/v1.3.0)
 
-## 라이선스
+---
 
-[MIT](https://github.com/rl2aderjoon/axmap/blob/main/LICENSE)
+[설치·업그레이드](docs/INSTALL.md) · [프로토콜](docs/SPEC.md) · [문제 제보](https://github.com/rl2aderjoon/axmap/issues) · [MIT 라이선스](LICENSE)

package/README.md

@@ -1,130 +1,134 @@
 # axMap
 
-[![English](https://raw.githubusercontent.com/rl2aderjoon/axmap/main/docs/assets/readme-en.svg)](https://github.com/rl2aderjoon/axmap/blob/main/README.md) [![한국어](https://raw.githubusercontent.com/rl2aderjoon/axmap/main/docs/assets/readme-ko.svg)](https://github.com/rl2aderjoon/axmap/blob/main/README.ko.md)
+**Several AI agents. One repository. Clear ownership before every edit.**
 
-**A CLI tool that helps AI agents avoid conflicting edits by claiming paths before working in the same Git repository.**
+axMap is a collaboration CLI that claims files and folders before work begins and rejects overlapping claims.
+Codex, Antigravity and Claude Code can use claims, releases, status and messaging through MCP.
 
-axMap records who is editing which paths and rejects overlapping claims.
-Commit hooks check changes against claimed paths, and agents release their claims when work is done.
-AI tools can use the same workflow through MCP.
+**English** · [한국어](README.ko.md)   /   Node.js 20+ · Git · MIT
 
-Requires Node.js 20+ and Git. The CLI has no npm runtime dependencies.
-The npm package is `axmap-cli`; the command is `axmap`.
-
-## Installation
-
-Run these commands from any folder, including outside a Git repository.
+## Install
 
 ```bash
 npm install -g axmap-cli@latest
 axmap setup
 ```
 
-`setup` installs axMap and registers MCP in your AI tool's user settings. It does not bind the installation to the current folder or initialize a repository.
-Restart your AI tool after setup to use MCP.
-People and agents working together must share the same remote ledger to see each other's claims.
+Run setup once from any folder, then restart your AI tool.
+Each Git repository's ledger is prepared on first use. Collaborators must share the same remote ledger.
 
-During interactive setup, enter the name people should use for messages, such as `John Smith` or `장효준`. To set or correct it without a prompt, run `axmap setup --name "John Smith"`. Reinstallation keeps the saved name. Git's name and email settings are unchanged.
+[Usage](docs/INSTALL.md) · [MCP setup](mcp/README.md) · [Development](docs/ONBOARD-TEAM.md)
 
-On first use in a repository, axMap reads that repository's Git email and shares your display name through the existing `axmap/users` branch. No code commit or per-repository manual registration is needed. Teammates discover it when their user information synchronizes. This requires push access; an offline or rejected update is reported and retried. Setup alone does not announce you to repositories you have never used.
+---
 
-Use `axmap bus contacts` to list known names and email addresses. Messages sent to a known name are addressed to its email, so correcting the name preserves delivery and read history. If multiple people use the same name, specify the recipient's email. Messaging registration does not grant voting or MR approval rights.
+## Changelog
 
-See [docs/INSTALL.md](https://github.com/rl2aderjoon/axmap/blob/main/docs/INSTALL.md) for installation and configuration details (Korean).
+Newest changes first.
 
-## Global setup and automatic repositories in 1.3.1
+### 1.4.0
 
-Set up axMap once, then open Codex or another AI CLI in any Git repository. axMap selects that session's repository and prepares its ledger on the first status or claim request. There is no per-repository `axmap init` step.
+<sub>October 20, 2026</sub>
 
-Existing remote ledgers are reused. Linked worktrees share one ledger, and simultaneous sessions in different repositories keep independent targets. Remote access failures stop the request instead of creating a separate ledger.
+**Codex and Antigravity can exchange tasks automatically, with measured token usage and bounded conversations.**
 
-MCP follows workspace roots supplied by the client. When roots are unsupported, it uses the launch directory; pass the absolute working directory through the tool's `cwd` argument for later directory changes. Run `axmap hook install` in each repository where you want commit enforcement.
+**Added**
 
-To upgrade an existing installation, run this once from any folder, then restart your AI CLI:
+- `axmap bridge serve codex|agy` explicitly starts persistent managed CLI sessions. `bridge chat` relays short messages until completion or a configured limit.
+- MCP `ax_chat`, `ax_dialogue`, and `ax_chat_stop` start, inspect, and stop automatic relay. Per-request and cumulative token counts include cache details; idle waiting makes no model calls.
+- The separate prototype `axmap run` command connects a user-launched interactive terminal.
+- The terminal dependency ships with npm installation and is copied into setup's installed runtime.
 
-```bash
-npm install -g axmap-cli@latest
-axmap setup
-```
+**Removed**
 
-`setup` refreshes the installed MCP and shared hook runner as well as its registration. Subsequent repository changes do not require another setup or init. To explicitly prepare one repository and its commit hook during setup, use `axmap setup --repo <path>`.
+- Code visualization screens, the Electron app, analysis and corpus tools, and their tests and research documents.
+- Setup and MCP now share CLI discovery from a dedicated source module.
 
-## Workflow
+**Validation**
 
-```bash
-# Check who has claimed which paths
-axmap status
+On Windows, actual Codex 0.163.0 and agy 1.4.2 completed a four-turn automatic exchange with retained context, followed by a two-turn MCP background exchange.
+These six model turns processed 102,590 tokens, including 54,400 cached input tokens and 393 output tokens. CLI context dominates short-message costs; budgets are checked before the next turn, not enforced as a hard limit within an active turn.
+The separate interactive PTY prototype remains validated with simulated programs only.
+[Read the development status →](docs/SESSION-BRIDGE.md)
 
-# Declare your paths and purpose before editing
-axmap claim src/auth --agent my-agent --session my-session --task T-12 --intent "Handle token expiration"
+---
 
-# After editing, stage your changes and check their claimed scope
-git add src/auth
-axmap verify --agent my-agent --session my-session
+### 1.3.3
 
-# Release your claims when work is done
-axmap release --agent my-agent --session my-session
-```
+<sub>October 16, 2026</sub>
 
-Use a unique agent name and session for each work session, and keep them consistent from claim to release.
-Set the `AXMAP_AGENT` and `AXMAP_SESSION` environment variables so commit hooks use the same identity.
-If a claim is rejected, check its owner, purpose, and remaining time, then choose a different area.
-Claim only the paths you need. For longer tasks, run `axmap renew` with the same agent and session.
+**Windows setup connects npm-installed Codex correctly.**
 
-Work folders created with `git worktree` share the same ledger.
-`release` releases paths claimed by the current session.
+**Fixed**
 
-## How it works
+- `axmap setup` launches the Codex package's Node entry directly.
+- Paths containing spaces and quoted arguments reach Codex without shell reinterpretation.
 
-Git detects text conflicts when changes are merged.
-axMap claims paths before edits to prevent agents from working on the same area at the same time.
+[Release source →](https://github.com/rl2aderjoon/axmap/tree/v1.3.3)
 
-The claim ledger lives on a dedicated Git branch. axMap checks the latest remote ledger,
-then uses atomic Git ref updates and path overlap checks to acquire claims.
-Commit hooks compare staged changes with claimed paths.
-`axmap audit` replays the ledger history to check for rule violations.
+---
 
-axMap reports unreadable state and refuses operations it cannot safely evaluate.
-The protocol is documented in [docs/SPEC.md](https://github.com/rl2aderjoon/axmap/blob/main/docs/SPEC.md), and its invariants in [docs/INVARIANTS.md](https://github.com/rl2aderjoon/axmap/blob/main/docs/INVARIANTS.md) (Korean).
+### 1.3.2
 
-## Using AI tools
+<sub>October 16, 2026</sub>
 
-With MCP connected, AI agents can call tools such as `ax_claim`, `ax_status`, and `ax_release`.
-Give your agents these working rules.
+**Choose your messaging name. Discover teammates automatically.**
 
-```text
-Before editing files, declare the paths and purpose with ax_claim.
-If a claim is rejected, check its owner and choose another task with no overlapping paths.
-Release your claims with ax_release when work is done.
-```
+**Added**
 
-See [mcp/README.md](https://github.com/rl2aderjoon/axmap/blob/main/mcp/README.md) for connection instructions and the tool list (Korean).
+- Interactive setup asks for a display name. Change it with `axmap setup --name "Your name"`.
+- First use in a repository shares its Git email and your display name through the team's user ledger.
+- `axmap bus contacts` lists known recipients.
 
-## Development and verification
+**Updated**
 
-```bash
-git clone https://github.com/rl2aderjoon/axmap.git
-cd axmap
-node bin/axmap.mjs --version
-npm test
-npm run demo
-npm run demo:compare
-npm run demo:chaos
-```
+- Messages sent to a known name are addressed by email, preserving delivery and read history after name changes.
+- Duplicate names require an email address. Failed profile updates are reported and retried on later use.
+- Git identity settings and voting permissions remain unchanged.
+
+[Release source →](https://github.com/rl2aderjoon/axmap/tree/v1.3.2)
+
+---
+
+### 1.3.1
+
+<sub>October 15, 2026</sub>
+
+**One setup, from any folder.**
+
+**Updated**
+
+- Installation and MCP registration work outside Git repositories.
+- Running setup in a folder does not pin future work to that repository.
+- Registration refreshes server paths and environment settings while preserving personal settings and other servers.
+
+Use `axmap setup --repo <path>` to prepare a specific repository's ledger and commit hook.
+
+[Release source →](https://github.com/rl2aderjoon/axmap/tree/v1.3.1)
+
+---
+
+### 1.3.0
+
+<sub>October 15, 2026</sub>
+
+**Your session follows its working repository.**
+
+**Added**
+
+- Status and claim commands prepare missing ledgers automatically, removing the repeated `init` step.
+- MCP follows client workspace roots and their change notifications.
+
+**Updated**
 
-The root CLI runs without `npm install`. The demos require Bash.
-Use `node bin/axmap.mjs` to run the source version.
+- Existing remote ledgers are reused, and linked worktrees share one ledger.
+- Sessions in separate repositories keep independent targets.
+- A remote access failure is never treated as an empty ledger.
 
-The following supporting documents are currently in Korean.
+Use the MCP tool's `cwd` argument when roots are unavailable or the target is ambiguous.
+Run `axmap hook install` in repositories that need commit enforcement.
 
-| Document | Contents |
-|---|---|
-| [CLAUDE.md](https://github.com/rl2aderjoon/axmap/blob/main/CLAUDE.md) | Rules for working on the source |
-| [docs/INSTALL.md](https://github.com/rl2aderjoon/axmap/blob/main/docs/INSTALL.md) | Installation and usage |
-| [docs/SPEC.md](https://github.com/rl2aderjoon/axmap/blob/main/docs/SPEC.md) | Commands and the claim protocol |
-| [docs/INVARIANTS.md](https://github.com/rl2aderjoon/axmap/blob/main/docs/INVARIANTS.md) | Invariants and verification criteria |
-| [docs/DECISIONS.md](https://github.com/rl2aderjoon/axmap/blob/main/docs/DECISIONS.md) | Product scope and design decisions |
+[Release source →](https://github.com/rl2aderjoon/axmap/tree/v1.3.0)
 
-## License
+---
 
-[MIT](https://github.com/rl2aderjoon/axmap/blob/main/LICENSE)
+[Installation & upgrades](docs/INSTALL.md) · [Protocol](docs/SPEC.md) · [Report an issue](https://github.com/rl2aderjoon/axmap/issues) · [MIT license](LICENSE)

package/bin/axmap.mjs

@@ -43,7 +43,7 @@ import {
   noticeLine,
   registryUrl,
 } from '../src/update.mjs'
-import { stateDir } from '../src/repotarget.mjs'
+import { stateDir } from '../src/state.mjs'
 import { homeRegistrations } from '../src/mcpstate.mjs'
 import { compareBranchFor, formatOverlap } from '../src/overlap.mjs'
 import { withRepoLock } from '../src/repolock.mjs'
@@ -2599,7 +2599,7 @@ exec node "$AX" verify
  *
  * 🔴 **import 하지 않고 spawn 한다.** 이유가 둘이다.
  *
- *   1. `tools/setup.mjs` 는 설치기를 부르느라 `app/lib/agentcli.mjs` 계열까지
+ *   1. `tools/setup.mjs` 는 설치기를 부르느라 `src/agentcli.mjs` 계열까지
  *      끌고 온다. 여기서 static import 를 걸면 그 전부가 `src/closure.mjs` 의
  *      import 그래프에 잡혀 **팀 저장소의 `ci/axmap/` 사본이 통째로 불어난다.**
  *      사본은 CI 가 판정에 쓰는 파일만 담기로 한 자리다.
@@ -2622,6 +2622,8 @@ exec node "$AX" verify
  * 두 군데 적으면 한 쪽만 고쳐지는 날이 온다.
  */
 const RUNNERS = {
+  run: ['tools/run.mjs', '사용자가 여는 AI CLI를 연결한다'],
+  bridge: ['tools/bridge.mjs', '열린 로컬 AI 세션에 작업을 전달한다'],
   gate: ['governance/gate.mjs', '이 MR 이 정족수를 채웠는가'],
   vote: ['governance/vote.mjs', '표를 던진다'],
   bus: ['tools/bus.mjs', '에이전트 사이 쪽지함'],
@@ -2764,7 +2766,7 @@ async function cmdUpdate(flags) {
  *
  * 🔴 자리를 여기서 새로 정하지 않는다 — `stateDir()` 을 쓴다. 그래야
  *    `AXMAP_STATE_DIR` 이 여기에도 걸린다. 그 환경변수가 있는 이유가
- *    `src/repotarget.mjs` 에 적혀 있다 — *"테스트가 사람의 작업 환경을 고치는
+ *    `src/state.mjs` 에 적혀 있다 — *"테스트가 사람의 작업 환경을 고치는
  *    것은 어떤 이유로도 정당하지 않다."* `os.homedir()` 를 직접 부르면 이 명령의
  *    출력이 **돌리는 사람의 PC 상태에 따라 달라지고**, 그러면 시험이 사람마다
  *    다른 답을 낸다 (실제로 그렇게 깨졌다).
@@ -2831,6 +2833,8 @@ const HELP = `axmap - AI 에이전트 작업 선점 프로토콜
   axmap gate                         이 MR 이 정족수를 채웠는가 (CI 가 부른다)
   axmap vote                         표를 던진다
   axmap bus                          에이전트 사이 쪽지함 (post · list · read · reply)
+  axmap bridge                       로컬 세션·자동 대화 (serve · sessions · send · chat · dialogue)
+  axmap run agy [인수...]             연결된 Antigravity CLI를 직접 연다
   axmap mr-target                    이 브랜치가 저 브랜치로 갈 수 있는가
   axmap version                      브랜치 단계로 다음 버전을 정한다
   axmap promote                      한 단계 위로 올리는 MR 을 만든다
@@ -2871,6 +2875,8 @@ if (boolFlag(flags.version, 'version') && !cmd) {
 switch (cmd) {
   // 이름을 경로로 바꿔 주는 것들 (RUNNERS). 인자는 손대지 않고 그대로 간다.
   case 'setup':
+  case 'bridge':
+  case 'run':
   case 'gate':
   case 'vote':
   case 'bus':

package/mcp/README.md

@@ -4,7 +4,7 @@
 있게 하는 규격**)로 axMap 을 AI CLI 에 붙인다.
 
 - 붙이면 AI 도구가 **"나는 이 파일들을 건드리겠다"를 선언**하게 된다. 겹치면 그 자리에서 거부당한다
-- 코드 충돌이 나기 전에 **의도 충돌**을 먼저 터뜨리는 것이고, 뷰어는 그 선언을 읽어 화면을 그린다
+- 코드 충돌이 나기 전에 **의도 충돌**을 먼저 터뜨리는 것이고, 다른 에이전트는 그 선언을 읽어 작업 범위를 조정한다
 - **한 번 설치하면 아무 저장소에서나 붙는다.** 작업할 저장소에는 파일을 하나도 남기지 않는다
 
 ---
@@ -39,6 +39,10 @@ https://github.com/rl2aderjoon/axmap/blob/main/mcp/SETUP-FOR-AI.md
 | `ax_release(paths?)` | 끝나면 즉시. 생략하면 전부 반납 |
 | `ax_renew()` | 길어지면 시간 연장 |
 | `ax_inbox(id?)` | 다른 에이전트가 나에게 보낸 쪽지를 읽는다 |
+| `ax_sessions()` | 같은 repo의 연결된 세션·역할·상태·사용량 |
+| `ax_dispatch(to, prompt)` / `ax_result(id)` | 연결된 세션에 단일 작업 전달·결과 조회 |
+| `ax_chat(left, right, prompt, maxTurns?, maxTokens?)` | 관리형 세션 두 개의 제한된 자동 대화를 백그라운드 접수 |
+| `ax_dialogue(id)` / `ax_chat_stop(id)` | 대화·토큰 조회 / 추가 중계 중단 |
 | `ax_send(to?, subject, body)` | 다른 에이전트에게 쪽지를 보낸다 |
 | `ax_init(remote?)` | 명시적 준비용. 조회·선점은 장부를 자동 준비하므로 먼저 부를 필요가 없다 |
 
@@ -133,7 +137,7 @@ CLI 를 부를 때마다 넘긴다. 앞 두 칸은 CLI 와 순서가 같아서,
 
 ### 🔴 `AXMAP_REPO` 는 비운다 — 대상은 부를 때마다 다시 정해진다
 
-서버는 도구를 부를 때마다 대상 저장소를 다시 정한다. 순서는 `AXMAP_REPO` → 도구의 절대 경로 `cwd` → 클라이언트 작업 폴더(roots) → 시작 폴더의 Git 루트다. 앱의 전역 `current.json`은 사용하지 않는다. 근거는 [DECISIONS.md의 D22](../docs/DECISIONS.md).
+서버는 도구를 부를 때마다 대상 저장소를 다시 정한다. 순서는 `AXMAP_REPO` → 도구의 절대 경로 `cwd` → 클라이언트 작업 폴더(roots) → 시작 폴더의 Git 루트다. 근거는 [DECISIONS.md의 D22](../docs/DECISIONS.md).
 
 장부가 없는 repo도 첫 조회·선점 때 자동으로 준비한다. 기존 원격 장부가 있으면 이어 사용하고, 원격 접근 실패는 빈 장부로 바꾸지 않는다. roots가 여러 repo를 가리켜 대상을 고를 수 없으면 도구의 `cwd`를 지정한다. roots 미지원 클라이언트에서 실행 중 폴더를 바꿀 때도 `cwd`를 전달한다. 서로 다른 MCP 세션의 타겟은 독립적이다.
 
@@ -193,10 +197,7 @@ clone 하면 장부에는 `claude` 라는 **한 명**만 존재하고, 겹침
 관문 1(push CAS — **"내가 읽은 뒤로 바뀐 게 없을 때만 쓴다"**. git push 가 원래
 이렇게 동작한다)과 관문 2(겹침 판정)가 CLI 와 완전히 동일하게 적용된다.
 
-전송은 stdio + 줄바꿈 구분 JSON-RPC 2.0 이다. SDK 의존성 없이 직접 구현했다 —
-폐쇄망에서 npm 설치 없이 돌아야 한다는 제약이 여기에도 적용된다.
-설치기가 `bin` `src` `mcp` `tools` `app` `package.json` `LICENSE` 만 복사하고
-`desktop/`(Electron 껍데기)을 빼는 것도 같은 이유다. 받아야 할 것이 없다.
+전송은 stdio + 줄바꿈 구분 JSON-RPC 2.0이다. MCP 서버는 SDK 없이 구현했다. 설치기는 `bin`, `src`, `mcp`, `tools`, `package.json`, `LICENSE`와 터미널 연결 의존성을 준비한다.
 
 ---
 
@@ -220,5 +221,4 @@ clone 하면 장부에는 `claude` 라는 **한 명**만 존재하고, 겹침
 
 **`doctor` 는 전역 등록을 검사하지 않는다.** 저장소의 `.mcp.json` 만 본다. 그래서
 전역으로 설치한 PC 에서 `MCP 설정` 줄이 `~~` 로 뜨는 것은 정상이다 — 무게가 전역
-등록으로 옮겨간 지금 그 줄은 거짓 보고에 가깝다. 배경은
-[docs/HANDOVER.md](../../docs/HANDOVER.md) 4.4 절과 4.5 절에 있다.
+등록으로 옮겨간 지금 그 줄은 거짓 보고에 가깝다. 설치 후에는 실제 전역 등록 경로도 함께 확인한다.