moai session 세션 레지스트리
moai session 은 .moai/state/active-sessions.json 의 다중 세션 조율 레지스트리를 관리합니다. 여러 Claude Code 세션이 같은 프로젝트를 동시에 건드릴 때 생기는 경쟁(race)을 줄이는 도구입니다.
SPEC 단위로 작업하는 관리자 에이전트가 동시에 같은 파일을 고치면 서로의 변경을 덮어쓰는 치명적인 경합이 생길 수 있기 때문에, 이 레지스트리는 활성 세션의 존재를 알리는 단일 조율 지점을 제공합니다. 따라서 하네스(harness) 의 pre-spawn 검사가 이 데이터를 읽어 다음 에이전트를 spawn 해도 안전한지를 판정합니다.
| 명령어 | 설명 |
|---|---|
moai session register <session_id> <spec_id> <phase> | 새 활성 세션 등록 |
moai session heartbeat <session_id> | 기존 세션의 last_heartbeat 갱신 (idempotent) |
moai session deregister <session_id> | 세션 제거 (idempotent) |
moai session list | 활성 세션 나열 (--filter-spec 필터 가능) |
moai session purge | stale 항목 제거 (기본: 마지막 heartbeat 후 30분 초과) |
moai session current | 이 오케스트레이터의 세션 UUID 출력 |
moai session doctor | 레지스트리가 비어 있는 원인 진단 |
대부분의 하위 명령어는 --json 플래그로 기계 판독 출력을 지원합니다.
bash
moai session list
moai session list --filter-spec SPEC-AUTH-001| 플래그 | 설명 |
|---|---|
--json | 기계 판독 JSON 출력 (오케스트레이터 pre-spawn 검사 형식) |
--filter-spec <id> | 해당 spec_id와 일치하는 항목만 반환 |
bash
moai session purge| 플래그 | 설명 |
|---|---|
--json | JSON 출력 |
--threshold-minutes <n> | stale heartbeat 컷오프 (분, 기본 30) |
bash
moai session current오케스트레이터 자신의 세션 UUID를 출력합니다. 런타임이 세션 ID를 노출하지 않으면 canonical fallback 문자열을 반환합니다.
| 플래그 | 설명 |
|---|---|
--json | JSON 출력 |
--show-fallback | canonical fallback 문자열만 출력 (paste-ready resume 생성용) |
bash
moai session doctor다중 세션 조율 레지스트리가 비어 있는 이유를 진단합니다 (write-path 진단).
| 플래그 | 설명 |
|---|---|
--json | JSON 출력 |
오케스트레이터는 구현 에이전트를 spawn 하기 전에 이 레지스트리로 동시 세션 경쟁을 잡아냅니다. moai session list --json --filter-spec <SPEC-ID> 가 다른 세션 항목을 돌려주면, 오케스트레이터는 진행을 멈추고 사용자에게 확인을 받습니다.
- moai inventory — 세션·워크트리·하네스 통합 조회
- CLI 개요