# 런타임 유닛
> Bootstrap, Context Resolver, Workspace Runtime, Worker Scheduler, Approval Manager, Recovery, Succession, Lineage, Adapter Layer의 구현 상태와 경계를 정리합니다.
- Repository: local/master-ops-with-local-mogui-ADE-orchestrator
- Human docs: https://grok-wiki.com/public/docs/local-master-ops-with-local-mogui-ade-orches-0ac7093355f3
- Complete Markdown: https://grok-wiki.com/public/docs/local-master-ops-with-local-mogui-ade-orches-0ac7093355f3/llms-full.txt
## Source Files
- `local-mogui-ade-orchestrator:docs/public/concepts.md`
- `local-mogui-ade-orchestrator:src/master_runtime/core/bootstrap.py`
- `local-mogui-ade-orchestrator:src/master_runtime/core/context/resolver.py`
- `local-mogui-ade-orchestrator:src/master_runtime/core/work_ledger.py`
- `local-mogui-ade-orchestrator:src/master_runtime/core/recovery.py`
- `local-mogui-ade-orchestrator:src/master_runtime/core/adapter/doctor.py`
---
---
title: "런타임 유닛"
description: "Bootstrap, Context Resolver, Workspace Runtime, Worker Scheduler, Approval Manager, Recovery, Succession, Lineage, Adapter Layer의 구현 상태와 경계를 정리합니다."
---
`local-mogui-ade-orchestrator`의 런타임은 `src/master_runtime/core/` 아래 Python 모듈과 `scripts/` CLI 래퍼로 구현된다. 설치 후 운영 규칙과 역할 상태는 `local-master-ops`의 문서 템플릿에 남고, 실제 판단은 bootstrap, resolver, ledger, dispatch gate, approval registry, recovery, succession, lineage, adapter 모듈이 각자 맡은 범위에서 수행한다.
## 구현 상태 표
| 유닛 | 현재 표면 | 상태 | 경계 |
| --- | --- | --- | --- |
| Bootstrap | `local-mogui-ade-orchestrator:src/master_runtime/core/bootstrap.py`, `scripts/master-bootstrap` | `Observed` | charter와 선택 handoff를 읽고 L0/L1 예산, Role State, 중복 세션 경고를 산출한다. |
| Context Resolver | `context/resolver.py`, `context/manifest.py`, `context/descriptor.py` | `Observed` | manifest 선언, workspace 직계 하위 디렉터리, 요청 path 조상만 관찰한다. 임의 하위 트리 재귀 탐색은 비목표다. |
| Workspace Runtime | `work_ledger.py` | `Observed` | JSONL work ledger를 replay해 active track 캐시를 만든다. 트랙 상태 저장소이지 worker 실행기가 아니다. |
| Repository Runtime Loader | 공개 모듈 없음 | `Intended` | 개념상 저장소별 harness 로딩 자리만 있다. 현재 구현 claims로 문서화하지 않는다. |
| Worker Scheduler | `dispatch_gate.py`, `scripts/dispatch-gate`, `worker_reap.py` | `Partial` | gate는 dispatch 전후를 bracket하고 ledger/ticket을 남긴다. 실제 worker launch와 Orca pane 생성은 host/runtime 쪽 경계다. |
| Approval Manager | `approval/gates.py`, `approval/registry.py` | `Observed` | action risk를 gate class로 분류하고 승인된 proposal과 정확히 일치하는 실행만 통과시킨다. registry는 in-memory다. |
| Recovery | `recovery.py`, `scripts/master-recover` | `Observed` | charter, handoff, ledger, git 상태, monitor process를 read-only로 점검하고 successor checklist를 만든다. |
| Succession | `succession.py`, `scripts/master-succeed` | `Observed` | trigger 감지, thin handoff 생성, successor 검증, duplicate 감지, predecessor retire/spawn을 Orca terminal 표면으로 수행한다. |
| Lineage | `lineage.py` | `Observed` | append-only Markdown ledger를 검증해 추가한다. 런타임 의사결정 입력으로 쓰지 않는다. |
| Adapter Layer | `adapter/doctor.py`, `scripts/adapter doctor` | `Observed` | `git`, `node`, `orca status --json`, `bd --version` 같은 설치 표면을 측정한다. 제품별 adapter 실행 추상화는 현재 doctor 중심이다. |
상태 라벨은 구현 claim의 강도를 나타낸다. `Configured`는 파일이나 설정이 있다는 뜻이고, `Observed`는 코드 또는 테스트 가능한 실행 표면이 있다는 뜻이다. `Partial`과 `Intended`는 구현과 운영 규칙을 분리해서 읽어야 한다.
## Bootstrap
Bootstrap은 master session이 시작될 때 durable context를 작은 결과 객체로 줄인다.
```bash
local-mogui-ade-orchestrator/scripts/master-bootstrap \
--charter local-master-ops/docs/MASTER-OPERATIONS.md \
--handoff ./handoffs/latest.md \
--budget 24000 \
--session-id \
--json
```
입력은 `BootstrapConfig`다.
필수 charter 파일이다. 없으면 `BootstrapError`가 발생한다.
존재하면 L1 입력으로 읽고 `Role State` block을 파싱한다. 없으면 `HANDOFF_MISSING` warning만 남긴다.
기본값은 `24000`이다. L0부터 채우고 남은 예산에 L1을 넣는다.
주어지면 process list에서 같은 session id를 가진 다른 `claude` process를 찾아 `DUAL_INSTANCE:` warning을 낸다.
중복 instance warning이 있으면 warning 대신 `BootstrapError`로 실패한다.
출력은 `BootstrapResult`이며 `role_state`, `l0_text`, `l1_text`, `budget_used`, `warnings`를 포함한다. Role State는 `Current Role`, `Role Lock`, `Frozen`, `Unlock` 필드를 요구하고, role 값은 runtime의 허용 role 집합에 있어야 한다.
`local-master-ops:docs/runbooks/role-state.md`는 설치 후 운영 저장소의 role-state SSOT다. bootstrap은 이 문서를 직접 강제하는 정책 엔진이 아니라 handoff나 지정 파일에서 role-state 형식을 회수하는 로더다.
## Context Resolver
Context Resolver는 workspace manifest와 실제 filesystem marker를 결합해 `ContextDescriptor`를 반환한다.
```python
resolve(path, workspace_manifest) -> ContextDescriptor
```
반환 가능한 `kind`는 다음 값이다.
| `ContextKind` | 의미 |
| --- | --- |
| `folder` | Git marker가 없는 일반 폴더 |
| `git-repo` | `.git` 디렉터리가 있는 repository |
| `git-worktree` | `gitdir:` marker 파일을 가진 worktree |
| `multi-repo-workspace` | 요청 path가 workspace root이고 repository marker가 없는 multi-repo workspace |
| `nested-repo` | 관찰된 repository가 다른 repository 안에 들어간 상태 |
Resolver는 세 종류의 repository entry를 구분한다.
| `RepoStatus` | 조건 |
| --- | --- |
| `declared+observed` | manifest 선언 path가 disk에서 Git repository 또는 worktree로 확인됨 |
| `declared-missing` | manifest에는 있으나 disk marker가 없음 |
| `observed-undeclared` | workspace 직계 child 또는 요청 path 조상에서 관찰됐지만 manifest에는 없음 |
충돌 규칙은 fail-closed에 가깝다. 서로 다른 identity가 같은 정규화 path로 선언되면 `ManifestError`가 발생한다. 반대로 누락 repository와 undeclared repository는 exception이 아니라 descriptor warning으로 유지된다.
## Workspace Runtime과 ledger
Workspace Runtime은 long-lived process state를 직접 저장하지 않는다. `JsonlWorkLedger`가 append-only JSONL event를 읽고 replay한 상태를 `WorkspaceRuntime`이 session L1 cache로 보관한다.
| Event | 필수 필드 | 효과 |
| --- | --- | --- |
| `register` | `ts`, `track_id`, `title`, `refs` | 새 `TrackState` 생성 |
| `update` | `ts`, `track_id`, `status`, `note` | active track 상태와 note 갱신 |
| `close` | `ts`, `track_id`, `resolution` | status를 `CLOSED`로 바꾸고 active set에서 제외 |
잘못된 JSONL line, unknown event, unknown track update/close는 replay warning으로 남기고 건너뛴다. `WorkspaceRuntime.refresh()`는 ledger를 다시 읽어 active cache를 맞춘다.
## Worker Scheduler 경계
Worker Scheduler의 구현 표면은 dispatch 자체가 아니라 dispatch gate다. `DispatchGate.check()`는 계약 파일, runtime 이름, model, estimated chars, agent 수, completion channel, tier policy를 평가하고 JSONL ledger와 dispatch ticket을 남긴다.
```bash
local-mogui-ade-orchestrator/scripts/dispatch-gate check \
--runtime codex \
--model gpt-5.6-sol \
--contract ./contracts/example.md \
--agents 1 \
--completion-channel orchestration
```
주요 deny reason은 `CONTRACT_UNREADABLE`, `INVALID_REQUEST`, `TIER_POLICY_UNAVAILABLE`, `TIER_FANOUT_CAP`, `BUDGET_EXCEEDED`, `ROUTING_VIOLATION`, `NO_COMPLETION_CHANNEL`, `NO_MODEL`이다. 허용된 dispatch는 contract SHA 기반 ticket을 발행하고, register 단계는 job id가 독립 probe 결과에 실제로 포함될 때만 통과한다.
```bash
local-mogui-ade-orchestrator/scripts/dispatch-gate register \
--job-id \
--probe-cmd "cat ./worker-result.json" \
--contract-sha \
--runtime codex \
--orchestration-task
```
현재 gate는 worker 실행 전후의 검문과 기록을 담당한다. Orca terminal 생성, CLI agent 실행, worktree 배치 자체를 모두 이 모듈이 소유한다고 해석하면 안 된다.
## Approval Manager
Approval Manager는 두 층이다.
| 층 | 구현 | 동작 |
| --- | --- | --- |
| 분류 | `classify(ActionSpec)` | `read_only`, `writes_local`, `writes_shared`, `irreversible` 조합을 `G0`부터 `G3`까지 분류 |
| 집행 | `ProposalRegistry.guard()` | `G0_READ_ONLY` 외 action은 approved proposal이 필요하고, proposal의 action spec이 실행 action과 정확히 같아야 함 |
`G2_SHARED_STATE`와 `G3_IRREVERSIBLE`의 승인 authority는 `HUMAN`이어야 한다. 승인된 proposal은 guard 통과 후 `CONSUMED`가 되어 재사용되지 않는다. registry는 durable store가 아니라 deterministic in-memory registry이므로, 운영 감사 기록은 별도 ledger나 문서 표면에 남겨야 한다.
## Recovery
Recovery는 read-only Flow 0-6 executor다.
```bash
local-mogui-ade-orchestrator/scripts/master-recover \
--charter local-master-ops/docs/MASTER-OPERATIONS.md \
--handoff ./handoffs/latest.md \
--ledger ./.work-ledger.jsonl \
--repo ./local-mogui-ade-orchestrator \
--monitor-pattern l1-digest \
--session-id \
--json
```
| Step | 검사 |
| --- | --- |
| `0` | charter 존재, bootstrap 가능 여부, Role State 회수, duplicate instance warning |
| `1` | handoff 존재, Role State block/body 존재 |
| `1-ledger` | ledger path가 있으면 active tracks replay |
| `2-3` | 지정 repository의 `git rev-parse`, branch, dirty 상태 |
| `4` | 누락 정보 요약과 Trace Archive 수동 검색 action |
| `5` | monitor process pattern 관찰과 takeover 후 re-arm action |
| `6` | successor가 active tracks를 recite하고 predecessor PID command line을 비교하라는 checklist |
Step 0이 `MISS`면 이후 repo/monitor 검사는 skip되고 fail-closed recovery report가 생성된다. Recovery는 파일을 수정하거나 process를 종료하지 않는다.
## Succession
Succession은 자동 교체가 아니라 명시적 전환 절차다. `detect_trigger()`는 explicit instruction만 `IMMEDIATE`로 분류하고, context ratio나 milestone은 `ADVISORY`로만 반환한다.
```bash
local-mogui-ade-orchestrator/scripts/master-succeed detect \
"succession now" \
--context-ratio 0.65 \
--json
```
주요 subcommand는 다음과 같다.
| Command | 역할 |
| --- | --- |
| `detect` | trigger text와 context pressure 분류 |
| `handoff` | JSON spec에서 Role State, objective, active tracks, accepted artifacts를 포함한 thin handoff 생성 |
| `verify-successor` | recovery report의 `MISS`, step `6`, step `2-3`, step `5`를 보고 `PASS`, `PARTIAL`, `FAILED` 산출 |
| `check-duplicates` | Orca terminal list에서 같은 marker를 가진 master session 탐지 |
| `spawn` | Orca terminal을 만들고 반환 handle/worktree 배치를 검증 |
| `retire` | predecessor 후보를 정확히 하나로 좁히고, `--execute`가 있을 때만 close 후 disappearance를 재측정 |
`spawn`은 agent별 기본 model을 일부만 가진다. unknown agent에 `--model`이 없으면 실패한다. 이는 provider-neutral 경계다. runtime은 특정 모델 공급자를 가정하지 않고, CLI 이름과 측정된 model id를 입력값으로 취급한다.
## Lineage
Lineage는 succession 결과의 append-only 관측 기록이다. `append_entry(path, entry)`는 required field, integer count, text field, verification value를 검증하고 Markdown section을 파일 끝에만 추가한다. 같은 generation이 이미 있으면 거부하고, append 검증 실패나 validation 실패 시 기존 bytes를 복원한다.
필수 필드는 `generation`, `parent_session`, `successor_session`, `timestamp`, `inherited_role`, `succession_reason`, `recovery_sources`, `inherited_open_tracks`, `verification`, `repeated_question_count`, `reopened_decision_count`, `context_loss_summary`, `predecessor_retirement_verified`이다. `verification` 값은 `PASS`, `PARTIAL`, `FAILED` 중 하나다.
Lineage는 bootstrap source가 아니며 runtime decision에도 쓰이지 않는다. 다음 generation의 실제 상태는 bootstrap, recovery, ledger, host 관찰 결과로 다시 확인한다.
## Adapter Layer
현재 Adapter Layer의 공개 CLI는 `adapter doctor`다.
```bash
local-mogui-ade-orchestrator/scripts/adapter doctor
```
기본 check는 `git --version`, `node --version`, `orca status --json`, `bd --version`이다. `orca --version`을 쓰지 않는 이유는 host별로 usage banner나 GUI launch처럼 측정 의미가 다른 결과가 나올 수 있기 때문이다. doctor 결과는 `present`, `missing`, 개별 `detail`을 JSON으로 출력한다.
이 계층은 BYOC/BYOK 친화적으로 유지된다. 특정 hosted connector나 모델 공급자에 runtime을 묶지 않고, 설치된 로컬 CLI, 파일, repository 설정, catalog/skill source를 측정 가능한 입력으로 취급한다.
## 운영 저장소와 제품 저장소 경계
`local-master-ops`는 설치 후 생성되는 operations repository template이다. `docs/MASTER-OPERATIONS.md`는 charter section map과 change rule을 보관하고, `docs/runbooks/role-state.md`는 role lock과 allowed roles를 보관한다. 반면 runtime code와 CLI 구현은 `local-mogui-ade-orchestrator`에 있다.
```text
local-master-ops
docs/MASTER-OPERATIONS.md 운영 SSOT와 charter map
docs/runbooks/role-state.md role-state 운영 파일
local-mogui-ade-orchestrator
src/master_runtime/core/ 런타임 모듈
scripts/ 공개 CLI entrypoint
config/*.example.json 설치 instance 설정 예시
tests/ 구현 경계 회귀 테스트
```
## 설정 표면
| 파일 | 런타임에서 쓰는 의미 |
| --- | --- |
| `config/instance-runtime.example.json` | master host runtime, transcript glob, optional product repo 예시 |
| `config/workspace-descriptor.example.json` | workspace root, master seat, repository inventory, repository별 prohibited action 예시 |
| `config/model-tier-policy.example.json` | dispatch gate가 소비하는 instance-owned tier policy 예시 |
`dispatch_gate.py`의 tier policy resolution은 환경 변수 `DISPATCH_TIER_POLICY`를 먼저 보고, 그다음 `config/model-tier-policy.json`, 마지막으로 `master-ops/model-tier-policy.json` fallback을 본다. 예시 파일은 template이며, 채워진 instance policy를 commit하는 규칙은 별도 운영 정책의 영역이다.
## Related pages
ops 저장소, 제품 저장소, sibling checkout 모델의 경계를 확인합니다.
dispatch gate, contract, register probe, acceptance 전 재검증 흐름을 확인합니다.
trigger, handoff, successor verify, predecessor retirement, lineage append 순서를 확인합니다.
instance runtime, workspace descriptor, model tier policy의 필드와 fail-closed 동작을 확인합니다.