# 런타임 유닛

> U1–U12 책임 경계, L0/L1 컨텍스트, 부분 구현 유닛, bootstrap·dispatch·succession·lineage 모듈 대응표.

- Repository: local/mogui-ADE-orchestrator

- Human docs: https://grok-wiki.com/public/docs/local-mogui-ade-orchestrator-97afe791d5ac
- Complete Markdown: https://grok-wiki.com/public/docs/local-mogui-ade-orchestrator-97afe791d5ac/llms-full.txt

## Source Files

- `docs/public/concepts.md`
- `src/master_runtime/core/bootstrap.py`
- `src/master_runtime/core/bootstrap_live.py`
- `src/master_runtime/core/context/resolver.py`
- `src/master_runtime/core/work_ledger.py`
- `src/master_runtime/core/approval/gates.py`
- `src/master_runtime/core/adapter/doctor.py`

---

---
title: "런타임 유닛"
description: "U1–U12 책임 경계, L0/L1 컨텍스트, 부분 구현 유닛, bootstrap·dispatch·succession·lineage 모듈 대응표."
---

마스터 런타임은 단일 프로세스가 아니라 **U1–U12 책임 단위**로 나뉜다. 유닛 번호는 설계 어휘이고, 실제 구현은 `src/master_runtime/core/` 모듈과 `scripts/` 엔트리포인트에 붙는다. 유닛이 있다고 해서 전부 모듈이 완성된 것은 아니며, U4는 설계만, U5·U7·U11은 부분 구현이다.

## 유닛 개요

| Unit | 이름 | 책임 | 모듈 / 스크립트 | 상태 |
| --- | --- | --- | --- | --- |
| U1 | Bootstrap | 안전 기동에 필요한 최소 L0/L1 로드 | `bootstrap.py`, `bootstrap_live.py` → `scripts/master-bootstrap`, `scripts/master-bootstrap-live` | 구현 |
| U2 | Context Resolver | 경로가 workspace / repo / worktree / folder 중 어디에 속하는지 판정 | `context/` (`resolver.py`, `descriptor.py`, `manifest.py`) | 구현 |
| U3 | Workspace Runtime | 트랙·교차 저장소 상태·장기 실행 기록 | `work_ledger.py` (`JsonlWorkLedger`, `WorkspaceRuntime`) | 구현 |
| U4 | Repository Runtime Loader | 대상 저장소에 필요한 harness만 로드 | 없음 | 설계 전용 |
| U5 | Worker Scheduler | 리스 발급, 격리 선택, dispatch, 예산, reap | 부분: `dispatch_gate.py`, `worker_reap.py` → `scripts/dispatch-gate`, `scripts/worker-reap` | 부분 |
| U6 | Approval Manager | 액션 위험 분류와 승인 상태 바인딩 | `approval/` (`gates.py`, `registry.py`) | 구현 |
| U7 | Role Runtime | 활성 역할 1개, role lock, 전이 상태 | 부분: `RoleState` 파싱은 `bootstrap.py`; lock 자체는 정책 | 부분 |
| U8 | Recovery Manager | reattach / 1회 resume / 상태 재구성 (읽기 전용) | `recovery.py` → `scripts/master-recover` | 구현 |
| U9 | Succession Manager | freeze, thin handoff, successor 검증, predecessor retire | `succession.py` → `scripts/master-succeed` | 구현 |
| U10 | Lineage Recorder | succession 품질 메타데이터 append-only 기록 (부트 소스 아님) | `lineage.py` | 구현 |
| U11 | Observability | 프로브·알림·컨텍스트 품질·모델 신원·acceptance 증거 | 부분: `digest_loop.py`, `watchdog.py`, `acceptance/`, 모델 프로브 스크립트 | 부분 |
| U12 | Adapter Layer | 제품별 CLI·포맷을 공통 계약 뒤로 격리 | `adapter/` → `scripts/adapter` | 구현 (launch 래핑 제거 후 doctor 중심) |

유닛 번호는 책임 자리표이다. “U5가 있다”는 말은 리스 발급·격리·launch·예산·reap이 전부 한 모듈에 있다는 뜻이 아니다.

## L0 / L1 컨텍스트

### 정의

| 계층 | 내용 | 대표 소스 |
| --- | --- | --- |
| **L0** | 안정 운영 프레임: charter, 역할 규칙, 상시 조정 규칙 | charter 파일 (`scripts/master-bootstrap --charter`) |
| **L1** | 활성 작업 컨텍스트: 트랙, handoff, digest 관측, 최근 운영 증거 | handoff, work ledger, live bootstrap 블록, `scripts/l1-digest` |

`bootstrap()`은 L0(charter)을 예산 안에서 먼저 채우고, 남은 예산으로 L1(handoff)을 붙인다. 기본 예산은 `DEFAULT_BUDGET_CHARS = 24_000`이다. 초과 시 마커:

- L0: `[TRUNCATED:BOOTSTRAP_BUDGET_EXCEEDED]` → warning `BUDGET_TRUNCATED:L0`
- L1: `[TRUNCATED:L1_BUDGET_EXCEEDED]` → warning `BUDGET_TRUNCATED:L1`

### Role State (L0 경계에 걸친 상속 상태)

handoff에 `## Role State` 블록이 있으면 파싱한다. 필수 필드:

| 필드 | 의미 |
| --- | --- |
| `Current Role` | `VALID_ROLES` 집합 안 값만 허용 |
| `Role Lock` | `ENABLED` / `DISABLED` |
| `Frozen` | 동결된 역할/작업 설명 |
| `Unlock` | 잠금 해제 조건 |

허용 역할: `Architecture`, `Research`, `Reference Implementation`, `Feature Implementation`, `Release / Operations`, `Incident Response`, `Maintenance`.

### Live bootstrap (`bootstrap_live.py`)

세션 시작용 동적 블록(~1KB 목표, `SELF_BLOCK_CAP = 1_000`). 메모리 본문을 재발행하지 않고 `bd prime --memories-only`를 L0/L1/untagged로 **감사**만 한다.

고정 섹션 순서:

```text
[MASTER-BOOTSTRAP v1]
## Role State
## Active tracks
## Charter
[BD-PRIME-AUDIT] ...
[DUAL-INSTANCE] ...
## Alerts  (있을 때만)
```

내부 예외는 전부 잡아 `[BOOTSTRAP-FALLBACK] <reason>` 한 줄로 낮춘다. boot가 죽지 않는 것이 계약이다.

### L1 관측 루프

`scripts/l1-digest tick --config ...`는 설정된 repo·ledger tail·job log·process 패턴을 읽고 digest를 쓴다. 작업 실행과 acceptance는 digest 밖에 있다.

## 모듈 대응표 (bootstrap · dispatch · succession · lineage)

### Bootstrap (U1 + Role 파싱)

| 표면 | 역할 |
| --- | --- |
| `bootstrap.py` | charter + handoff → budgeted L0/L1, Role State, dual-instance 경고 |
| `bootstrap_live.py` | SessionStart 블록: Role State, tracks, memory audit, dual-instance |
| `scripts/master-bootstrap` | CLI; `--charter`, `--handoff`, `--budget`, `--session-id`, `--strict-lease`, `--json` |
| `scripts/master-bootstrap-live` | CLI; `--handoff-dir`, `--role-state-file`, `--budget`, `--charter-pointer` |

`strict_lease=True`이고 dual-instance 경고가 있으면 `BootstrapError`로 실패한다.

### Dispatch / Worker path (U5 부분 + U11 watchdog)

```text
check -> (host dispatch) -> register -> independent verification -> acceptance
```

| 표면 | 역할 |
| --- | --- |
| `dispatch_gate.py` | 계약 가독성, 문자 예산, tier fan-out, reason code, JSONL ledger, ticket TTL |
| `scripts/dispatch-gate check` | allow/deny 기록 |
| `scripts/dispatch-gate register` | probe exit 0 + job id 출현 후에만 등록 |
| `scripts/dispatch-gate watch` | stall 검사 (`watchdog.check_stall`) |
| `scripts/dispatch-gate report` | ledger 집계 |
| `worker_reap.py` / `scripts/worker-reap` | settled dispatch 터미널 close, worktree 정리, reap ledger |
| `work_ledger.ReapObservability` | unreaped settled lease 탐지 |

**의도적 공백:** typed adapter launch 경로는 제거되었다. 워커 시작은 호스트(Orca 터미널)가 한다. 게이트는 그 단계를 **괄호로 감싸** 기록·검증한다. isolation 선택·전체 lease 발급기는 이 저장소에 없다.

리스 수명 (운영 runbook):

```text
issued → running → submitted → accepted → reaped
```

`scripts/worker-reap`는 settled(`COMPLETED`/`ACCEPTED`/`FAILED`/`ABANDONED`)가 아니면 exit 3으로 거절한다. 잘못된 reap은 비용이 크고, 건너뛴 reap은 싸다.

### Succession (U9) + Recovery (U8)

| 표면 | 역할 |
| --- | --- |
| `succession.py` | trigger 분류, handoff 작성, successor 검증, duplicate 탐지, retire, spawn placement 검증 |
| `scripts/master-succeed` | `detect`, `handoff`, `verify-successor`, `check-duplicates`, `retire`, `spawn` |
| `recovery.py` | Recovery Flow 0–6 **읽기 전용** (파일/프로세스 변경 없음) |
| `scripts/master-recover` | recovery 리포트 CLI |

라이프사이클:

```text
founding spawn → boot measurement → steady state → clean succession → lineage record
```

Successor 검증 상태: `PASS` | `PARTIAL` | `FAILED`.  
Predecessor retire: process/pane/tty 측정; 부분 소멸은 `CLOSED_PARTIAL`로 기록해 full close와 혼동하지 않는다.

### Lineage (U10)

`lineage.append_entry`는 마크다운 원장에 **append-only**로 한 generation을 붙인다. lineage는 런타임 결정을 먹이지 않는다 (부트 소스 금지).

필수 필드:

| 필드 | 제약 |
| --- | --- |
| `generation` | 정수; 이미 있으면 `LineageValidationError` |
| `parent_session`, `successor_session` | 텍스트 |
| `timestamp` | 텍스트 |
| `inherited_role` | 텍스트 |
| `succession_reason` | 텍스트 |
| `recovery_sources` | 텍스트 |
| `inherited_open_tracks` | 텍스트 |
| `verification` | `PASS` \| `PARTIAL` \| `FAILED` |
| `repeated_question_count`, `reopened_decision_count` | 카운트 |
| `context_loss_summary` | 텍스트 |
| `predecessor_retirement_verified` | 텍스트 |
| `notes` | 선택 |

### Context / Workspace (U2 · U3)

| 표면 | 역할 |
| --- | --- |
| `context/resolver.resolve` | manifest 선언 + 파일시스템 관찰 → `ContextDescriptor` |
| `ContextKind` | `folder`, `git-repo`, `git-worktree`, `multi-repo-workspace`, `nested-repo` |
| `JsonlWorkLedger` | track `register` / `update` / `close` JSONL 이벤트 |
| `WorkspaceRuntime` | ledger 위 세션 L1 캐시 |

경로 재귀 스캔은 non-goal이다. 관찰 범위: 선언된 repo, workspace root 직계 자식, 질의 경로의 조상.

### Approval (U6)

`classify(ActionSpec)` → `GateClass`:

| Class | 조건 |
| --- | --- |
| `G0_READ_ONLY` | 읽기 전용 |
| `G1_REVERSIBLE_LOCAL` | 로컬 가역 쓰기 |
| `G2_SHARED_STATE` | 공유 상태 쓰기 (또는 비-read_only 기본) |
| `G3_IRREVERSIBLE` | 비가역 |

`approval/registry.py`는 proposal lifecycle `PENDING → APPROVED|REJECTED → CONSUMED`를 강제한다. 승인 없는 gated 실행은 `ApprovalRequired`.

### Adapter (U12)

| 표면 | 역할 |
| --- | --- |
| `adapter/doctor.py` | git / node / orca / bd 존재 프로브 (`orca status --json` — `--version` 아님) |
| `adapter/profile.py` | sync CLI argv 프로파일 (Claude / Codex / Cursor) |
| `scripts/adapter doctor` | JSON 리포트 |

워커 launch 래핑은 공개 표면에 없다. pretrust 보조: `scripts/codex-worker-pretrust`, `scripts/cursor-worker-pretrust`.

## 부분 구현 유닛 — 정직한 경계

### U4 Repository Runtime Loader

모듈 없음. 저장소별 harness lazy-load는 설계 어휘로만 남아 있다. 현재는 U2 descriptor와 호스트 worktree가 그 자리를 대체한다.

### U5 Worker Scheduler

| 있음 | 없음 / 호스트 |
| --- | --- |
| 계약 check/register, 예산·tier 캡, ledger | 워커 프로세스 launch (Orca) |
| settled reap + unreaped 탐지 | 전체 lease 발급기·격리 정책 엔진 |
| stall watch | “모든 생성 경로가 게이트를 통과한다”는 workspace wiring 증명 |

공개 문서의 “no lease or reap module” 표현은 이후 `worker_reap` 추가로 완화되었다. 그래도 U5 전체 스펙(리스 발급·격리 선택·launch 래핑)은 미완성이다.

### U7 Role Runtime

`RoleState` 파싱·유효 역할 검증·live 블록 주입은 코드에 있다. role lock 강제, 역할 전이 상태 머신, “한 활성 역할” 런타임 락은 **운영 정책**(Role State 파일 + 마스터 규약)이다.

### U11 Observability

| 구현 조각 | 스크립트 |
| --- | --- |
| L1 digest | `scripts/l1-digest` |
| stall watchdog | `dispatch-gate watch` |
| acceptance loop | `scripts/acceptance-loop` |
| model identity / drift | `scripts/model-identity-probe`, `scripts/model-drift-audit` |

통합 observability bus나 중앙 알림 서비스는 없다. 각 프로브가 독립 exit 코드 계약을 가진다 (스크립트마다 0/1/2 의미가 다름).

## 능력 영역 ↔ 유닛

| 능력 영역 | 주 유닛 | 메커니즘 |
| --- | --- | --- |
| Execution environment | 호스트 + 스크립트 | Orca 터미널, worktree, `scripts/*` |
| Context management | U1, U2, U3, U11(부분) | bootstrap L0/L1, resolver, ledger, digest |
| Delegation | U5(부분), U12, U11 acceptance | dispatch-gate, host launch, acceptance-loop |
| Steering | U6, U7(부분) | approval registry, Role State 정책 |
| Filesystem model | U2 | real git paths; sensitive-lane 차단은 워크스페이스 호스트 훅 |

## 라이프사이클에서 유닛이 붙는 지점

```mermaid
flowchart LR
  A[U1 Bootstrap] --> B[Steady state]
  B --> C[U5 Dispatch gate]
  C --> D[Host worker]
  D --> E[U5 Register / Reap]
  E --> F[U11 Acceptance]
  B --> G[U8 Recovery read-only]
  B --> H[U9 Succession]
  H --> I[U10 Lineage append]
  I --> A
```

1. **Boot:** U1 (+ U7 Role State 파싱), 선택적 model probe (U11).  
2. **Operate:** U2 경로 판정, U3 트랙, U5 check/register/reap, U6 승인, U11 digest/probe.  
3. **Recover:** U8 Flow 0–6 읽기 전용 리포트.  
4. **Succeed:** U9 handoff → spawn → verify → retire → U10 lineage. 다음 세대는 다시 U1.

## 검증 신호

| 신호 | 의미 |
| --- | --- |
| `scripts/master-bootstrap --json` | L0/L1 길이, role_state, warnings |
| `scripts/master-bootstrap-live` 출력에 `[MASTER-BOOTSTRAP v1]` | live 블록 조립 성공 |
| `[BOOTSTRAP-FALLBACK]` | live 경로 내부 실패, boot은 계속 |
| `dispatch-gate check` ledger 행 | allow/deny + reason code |
| `dispatch-gate register` 실패 `UNVERIFIED_JOB` | probe가 job id를 증명하지 못함 |
| `worker-reap` exit 3 | dispatch not settled |
| `master-succeed spawn` placement mismatch | successor 좌석이 요청 selector와 불일치 |
| lineage generation 중복 예외 | 같은 generation 재기록 시도 |

단위 테스트 통과는 해당 유닛의 **로컬 실행 증거**일 뿐, 운영 workspace가 모든 경로를 그 유닛으로 강제한다는 증명은 아니다.

## 구현 상태 라벨 (문서 어휘)

| 라벨 | 의미 |
| --- | --- |
| Configured | 파일·스크립트·훅·정적 계약이 repo에 존재 |
| Intended | 설계 계약은 문서화, 라이브 런타임 증거 주장 안 함 |
| Observed | git/로컬 실행/로그/ledger/프로브로 self-report와 독립 관측 |
| Unknown | 현재 증거로 증명 불가, 또는 공개 표면 밖 |

Configured ≠ operating. 훅 파일이나 유닛 번호만으로 “동작 중”이라 쓰지 않는다.

## Related pages

<CardGroup cols={2}>
  <Card title="Overview" href="/overview">
    공개 표면, Orca 전제, 마스터/워커 역할
  </Card>
  <Card title="Master lifecycle" href="/master-lifecycle">
    founding spawn → boot → steady → succession → lineage
  </Card>
  <Card title="Orca object model" href="/orca-object-model">
    project·workspace·worktree·terminal·Run 좌석 규칙
  </Card>
  <Card title="Supervised dispatch" href="/supervised-dispatch">
    check → dispatch → register, ledger, model probe
  </Card>
  <Card title="Clean succession" href="/succession">
    handoff, placement spawn, retire, lineage 필드
  </Card>
  <Card title="Evidence and acceptance" href="/evidence-and-acceptance">
    self-report vs 독립 검증, acceptance 판정
  </Card>
  <Card title="Worker reap" href="/worker-reap">
    issued→reaped, settled 검증, dry-run·ledger
  </Card>
  <Card title="Defense inventory" href="/defense-inventory">
    디스패치·placement·redaction·revival 가드 표
  </Card>
  <Card title="CLI reference" href="/cli-reference">
    scripts/ 공개 명령 표
  </Card>
</CardGroup>