OMX - State Lifecycle

시리즈: oh-my-codex 아키텍처 해부

이 시리즈는 OpenAI Codex CLI 확장 런타임인 oh-my-codex(OMX)의 내부 구조를 단계별로 해부하는 과정이다.

편	내용	핵심
0편	Overview	3-Plane 아키텍처, OMC와의 차이, 전체 흐름
1편	Codex CLI Foundation	Codex CLI 자체의 구조와 확장 포인트
2편	OMX Integration	OMX가 Codex에 어떻게 연결되나
3편	Skill System	워크플로우를 어떻게 정의하나
4편	Prompt & Agent System	에이전트는 뭐고 어떻게 선택되나
5편	MCP Servers	어떤 MCP 도구를 쓸 수 있나
6편 (본문)	State & Lifecycle	상태를 어떻게 유지하나
7편	Team Orchestration	Team 모드는 어떻게 동작하나
8편	Native & Spark	Rust 네이티브 도구는 뭔가

---

• State & Lifecycle은 OMX의 모드 상태 관리, 세션 생명주기, 계획 게이트 전략
• .omx/ 디렉토리에 모드 상태·세션 메타·계획 산출물·로그를 영속화하며, PID 기반 stale 감지와 atomic write로 데이터 무결성을 보장하는 상태 인프라
• 5편의 MCP 서버가 “어떻게 읽고 쓰는지” 를 다뤘다면, 이 파트는 “언제, 무엇을, 어떤 규칙으로” 상태를 관리하는지를 다루는 구조

해당 개념이 필요한 이유

• 5편에서 MCP 서버로 상태를 읽고 쓸 수 있게 되었음
• 하지만 “언제 상태를 기록하고, 모드 전환은 어떻게 되며, 세션 간 정보를 어떻게 보존하는지” 가 빠져 있음
• 이 파트는 모드 상태 머신, 배타적/합성 규칙, Ralph planning gate, 세션 관리를 다루어 그 간극을 메움

AS-IS (OMC — Hook 기반 종료 차단)

sequenceDiagram
    autonumber
    participant CC as Claude Code
    participant SH as persistent-mode.mjs (Stop Hook)
    participant ST as .omc/state/

    CC->>CC: 작업 완료 시도
    CC->>SH: Stop Hook 이벤트 발생
    SH->>ST: 활성 모드 확인
    alt 활성 모드 존재
        SH-->>CC: 종료 차단 (stdout JSON 주입)
        Note over CC: Hook이 결정론적으로 종료를 차단
    else 활성 모드 없음
        SH-->>CC: 종료 허용
    end

TO-BE (OMX — AGENTS.md Continuation 지침)

sequenceDiagram
    autonumber
    participant CX as Codex CLI (LLM)
    participant AM as AGENTS.md
    participant ST as .omx/state/

    CX->>CX: 작업 완료 시도
    CX->>AM: Continuation 지침 확인
    Note over AM: "no pending work, features working,<br/>tests passing, zero known errors,<br/>verification evidence collected. If not, continue."
    CX->>ST: state_read(mode) — 활성 모드 확인
    alt 미완료 작업 존재
        CX->>CX: LLM이 자발적으로 작업 계속
        Note over CX: 확률론적 — LLM 판단에 의존
    else 완료 조건 충족
        CX->>ST: state_write(active: false, completed_at: ...)
    end

핵심 차이: OMC는 Stop Hook으로 결정론적으로 종료를 차단하지만, OMX는 AGENTS.md Continuation 지침으로 LLM이 자발적으로 계속할지 판단한다. 전 계층이 확률론적인 OMX 아키텍처의 일관된 설계다.

.omx/ 디렉토리 구조

.omx/
├── state/                          # 모드·세션 상태
│   ├── {mode}-state.json           # 모드별 상태 (autopilot, ralph, team 등)
│   ├── session.json                # 현재 세션 메타데이터
│   ├── hud-state.json              # HUD 메트릭 (세션 시작 시 리셋)
│   ├── skill-active-state.json     # 현재 활성 스킬 추적
│   ├── ralph-progress.json         # Ralph 실행 레저
│   └── sessions/
│       └── {sessionId}/            # 세션 스코프 상태
│           └── {mode}-state.json
├── plans/                          # 계획 산출물 (Ralph planning gate)
│   ├── prd-*.md                    # PRD 문서
│   └── test-spec-*.md              # 테스트 스펙
├── specs/                          # 스펙 파일
│   └── deep-interview-*.md         # Deep interview 산출물
├── logs/                           # 세션 히스토리·일일 로그
│   ├── session-history.jsonl       # 종료된 세션 아카이브
│   ├── omx-YYYY-MM-DD.jsonl        # 일일 이벤트 로그
│   └── turns-*.jsonl               # 턴 로그 (trace 서버용)
├── metrics.json                    # 세션 메트릭 (토큰, 턴 수)
├── project-memory.json             # 프로젝트 메모리 (크로스 세션)
├── notepad.md                      # 노트패드
├── setup-scope.json                # 설치 scope 기록 (user/project)
└── .gitignore                      # .omx/ 전체를 gitignore 처리

omx setup 시 state/, plans/, logs/ 디렉토리가 생성되고, .gitignore에 .omx/ 엔트리가 추가된다.

모드 상태 머신 — 배타적 vs 합성

7개 모드 정의 (소스: src/modes/base.ts)

export type ModeName =
  'autopilot' | 'autoresearch' | 'ralph' | 'ultrawork' |
  'team' | 'ultraqa' | 'ralplan';

배타적(Exclusive) 모드 — 동시 실행 불가

const EXCLUSIVE_MODES: ModeName[] = ['autopilot', 'autoresearch', 'ralph', 'ultrawork'];

배타적 모드 시작 시 assertModeStartAllowed()가 다른 배타적 모드의 활성 상태를 확인한다. 충돌 시 "Cannot start {mode}: {other} is already active. Run cancel first." 에러를 던진다.

모드	배타/합성	비고
autopilot	배타적	전체 자동화 파이프라인
ralph	배타적	검증 루프 (내부적으로 ultrawork 위임 가능)
ultrawork	배타적	병렬 실행
autoresearch	배타적	자동 리서치
team	합성	N worker 병렬 조율
ultraqa	합성	QA 사이클
ralplan	합성	합의 기반 계획 (planning gate)

3편 Skill Composition과의 관계: ralph가 ultrawork를 “감싸는” 3계층 합성은 모드 수준의 동시 활성이 아니다. Ralph 모드가 활성일 때 내부적으로 ultrawork의 병렬 위임을 사용하는 것이지, 두 모드가 독립적으로 동시에 active 상태가 되는 것이 아니다.

상태 전이 다이어그램

stateDiagram-v2
    [*] --> inactive

    inactive --> active: state_write(active: true)

    state active {
        [*] --> starting
        starting --> executing: phase 변경
        executing --> verifying: 작업 완료, 검증 시작
        verifying --> fixing: 검증 실패
        fixing --> executing: 수정 후 재실행
        verifying --> complete: 검증 통과
        executing --> failed: 에러 발생
        fixing --> failed: 에러 발생
    }

    active --> completed: state_write(active: false, completed_at: ...)
    active --> cancelled: cancel 스킬 실행

    completed --> [*]
    cancelled --> [*]

모드 라이프사이클 규칙

AGENTS.md <state_management> 섹션에 명시된 4단계 필수 규칙:

단계	동작	예시
1. 시작	state_write — 모드 상태 기록	state_write({mode: "ralph", active: true, started_at: ...})
2. 변경	페이즈/이터레이션 변경 시 업데이트	state_write({current_phase: "verifying", iteration: 2})
3. 완료	completed_at 마킹, active: false	state_write({active: false, completed_at: "2026-..."})
4. 취소	정리 후 상태 클리어	state_clear({mode: "ralph"})

Ralph Phase Contract (소스: src/ralph/contract.ts)

Ralph 모드는 7개 정규 phase를 가지며, 레거시 별칭이 자동 정규화된다.

export const RALPH_PHASES = [
  'starting', 'executing', 'verifying', 'fixing',
  'complete', 'failed', 'cancelled'
] as const;

레거시 별칭	정규화 대상
start, started	starting
execution, execute	executing
verify, verification	verifying
fix	fixing
completed	complete
fail, error	failed
cancel	cancelled

터미널 phase: complete, failed, cancelled — 이 상태에 도달하면 모드가 비활성화된다.

Mode Runtime Context (소스: src/state/mode-state-context.ts)

모드가 활성화될 때 TMUX pane ID를 자동 캡처하여 상태에 저장한다.

export function withModeRuntimeContext<T>(existing, next, options?) {
  // active 전환 시 환경변수에서 TMUX_PANE 캡처
  // 최초 1회만 저장 (이후 덮어쓰지 않음)
  // tmux_pane_id, tmux_pane_set_at 기록
}

이 정보는 team 모드에서 어떤 pane이 어떤 모드를 실행 중인지 추적하는 데 사용된다.

Session 관리 (소스: src/hooks/session.ts)

세션 생명주기

sequenceDiagram
    autonumber
    participant H as 사람
    participant CLI as omx launch
    participant SS as session.ts
    participant SF as .omx/state/session.json
    participant LG as .omx/logs/

    H->>CLI: omx launch
    CLI->>SS: writeSessionStart(cwd, sessionId)
    SS->>SF: session.json 생성 (pid, started_at, cwd)
    SS->>LG: omx-YYYY-MM-DD.jsonl에 session_start 기록
    SS->>SS: resetSessionMetrics() — metrics.json 초기화

    Note over CLI: 세션 진행 중...

    CLI->>SS: writeSessionEnd(cwd, sessionId)
    SS->>LG: session-history.jsonl에 아카이브 (started_at, ended_at)
    SS->>SF: session.json 삭제
    SS->>LG: omx-YYYY-MM-DD.jsonl에 session_end 기록

SessionState 인터페이스

export interface SessionState {
  session_id: string;
  started_at: string;
  cwd: string;
  pid: number;
  platform?: NodeJS.Platform;
  pid_start_ticks?: number;    // Linux: /proc/PID/stat 필드 20
  pid_cmdline?: string;        // Linux: /proc/PID/cmdline
}

Stale 세션 감지 — PID 기반 (시간 제한 없음)

export function isSessionStale(state: SessionState): boolean {
  // 1. PID liveness: process.kill(pid, 0)
  // 2. Linux 전용: /proc/PID/stat의 start ticks 비교
  //    → PID가 재사용되었는지 확인 (같은 번호, 다른 프로세스)
  // 3. macOS/Windows: PID liveness만 확인
}

OMC와의 차이: OMC는 2시간 타임아웃으로 stale을 판단했지만, OMX는 PID 생존 여부만 확인한다. 소스 주석: “No age-based threshold: staleness is determined by PID liveness/identity. Long-running sessions (>2h) are legitimate and should not be reaped.”

세션 메트릭 초기화 (resetSessionMetrics)

세션 시작 시 .omx/metrics.json을 리셋한다:

{
  "total_turns": 0,
  "session_turns": 0,
  "last_activity": "2026-03-19T...",
  "session_input_tokens": 0,
  "session_output_tokens": 0,
  "session_total_tokens": 0
}

Ralph Planning Gate (소스: src/planning/artifacts.ts)

게이트 조건

const PRD_PATTERN = /^prd-.*\.md$/i;
const TEST_SPEC_PATTERN = /^test-?spec-.*\.md$/i;
 
export function isPlanningComplete(artifacts: PlanningArtifacts): boolean {
  return artifacts.prdPaths.length > 0 && artifacts.testSpecPaths.length > 0;
}

양쪽 모두 존재해야 게이트 해제:

• .omx/plans/prd-*.md — 최소 1개
• .omx/plans/test-spec-*.md (또는 testspec-*.md) — 최소 1개

게이트 동작 흐름

graph TD
    RS["Ralph 활성 상태"]
    RS --> CHECK["isPlanningComplete() 확인"]
    CHECK --> |"PRD + test-spec 모두 존재"| UNLOCK["UNLOCKED — 구현 시작 허용"]
    CHECK --> |"하나라도 없음"| BLOCK["BLOCKED — 구현 차단"]
    BLOCK --> RP["$ralplan으로 리다이렉트<br/>계획 먼저 수행"]
    RP --> |"계획 산출물 생성"| CHECK

    style UNLOCK fill:#d4edda
    style BLOCK fill:#f8d7da

승인된 실행 힌트 추출

readApprovedExecutionLaunchHint()가 최신 PRD 마크다운에서 실행 명령어를 파싱한다:

// PRD 내 패턴 매칭: "omx team 3:executor refactor API"
// → { workerCount: 3, agentRole: "executor", taskDescription: "refactor API" }

이를 통해 planning gate 통과 후 자동으로 적절한 실행 모드를 시작할 수 있다.

Skill Active State — 스킬 활성화 추적

skill-active-state.json (소스: src/hooks/keyword-detector.ts)

export interface SkillActiveState {
  version: 1;
  active: boolean;
  skill: string;           // 활성 스킬 이름
  keyword: string;         // 트리거한 키워드
  phase: SkillActivePhase; // 'planning' | 'executing' | 'reviewing' | 'completing'
  activated_at: string;
  updated_at: string;
  source: 'keyword-detector';
  session_id?: string;
  input_lock?: DeepInterviewInputLock;  // Deep Interview 전용
}

recordSkillActivation()이 사용자 입력에서 키워드를 감지할 때마다 이 파일을 업데이트한다. 같은 스킬/키워드가 이미 활성이면 activated_at을 보존하고, 새 스킬이면 새 타임스탬프를 기록한다.

Deep Interview Input Lock

3편에서 다룬 input lock의 상태 관리 측면:

export interface DeepInterviewInputLock {
  active: boolean;
  scope: 'deep-interview-auto-approval';
  acquired_at: string;
  released_at?: string;
  exit_reason?: 'success' | 'error' | 'abort' | 'handoff';
  blocked_inputs: string[];  // ['yes', 'y', 'proceed', 'continue', 'ok', ...]
  message: string;
}

• 획득: deep-interview 스킬 활성화 시 createDeepInterviewInputLock()
• 해제: cancel 키워드 감지 시 또는 인터뷰 완료 시 releaseDeepInterviewInputLock(exit_reason)
• 상태 파일: skill-active-state.json의 input_lock 필드에 영속화

OMC 상태 관리와의 비교

항목	OMC	OMX
상태 디렉토리	.omc/state/	.omx/state/
종료 차단	persistent-mode.mjs Stop Hook (결정론적)	AGENTS.md Continuation 지침 (확률론적)
Stale 감지	2시간 타임아웃	PID liveness (시간 제한 없음)
Stale 플랫폼	범용	Linux: /proc/PID/stat 프로세스 동일성 검증
Notepad	.omc/notepad.md (3섹션)	omx_memory MCP 서버의 notepad_* 도구
Project Memory	.omc/project-memory.json	omx_memory MCP 서버의 project_memory_* 도구
세션 스코핑	.omc/state/sessions/{id}/	.omx/state/sessions/{id}/ (동일 패턴)
모드 배타성	스킬 수준 관리	assertModeStartAllowed() 코드 수준 강제
상태 원자성	직접 파일 쓰기	atomic write (tmp + rename) + write-lock queue
Planning gate	없음	isPlanningComplete() — PRD + test-spec 필수

참고 문서

• OMX GitHub