# 마스터 승계
> trigger 감지, role freeze, thin handoff, successor verify, predecessor retirement, lineage append, revival check의 실행 순서를 설명합니다.
- 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/master-lifecycle.md`
- `local-mogui-ade-orchestrator:src/master_runtime/core/succession.py`
- `local-mogui-ade-orchestrator:src/master_runtime/core/lineage.py`
- `local-mogui-ade-orchestrator:scripts/master-succeed`
- `local-master-ops:docs/runbooks/succession-boot-card.md`
- `local-master-ops:docs/lineage/MASTER-LINEAGE.md`
- `local-mogui-ade-orchestrator:tests/test_succession_scenario.py`
---
---
title: "마스터 승계"
description: "trigger 감지, role freeze, thin handoff, successor verify, predecessor retirement, lineage append, revival check의 실행 순서를 설명합니다."
---
`scripts/master-succeed`가 마스터 승계의 실행 표면이다. 승계는 자동 교체가 아니라 명시적 지시 또는 측정된 advisory 신호를 분류한 뒤, 현재 마스터가 얇은 handoff를 만들고, successor가 recovery를 검증하고, predecessor를 측정 기반으로 retirement 처리한 뒤 lineage에 관측값을 append하는 절차다.
## 실행 순서
`master-succeed detect`는 텍스트와 선택적 `--context-ratio`를 받아 `IMMEDIATE`, `ADVISORY`, `NONE` 중 하나를 반환한다. `succession now`, `handoff to successor`, `승계해줘`, `다음 마스터로 넘기자`, `승계 진행해`는 즉시 승계 지시로 분류된다.
```bash
scripts/master-succeed detect \
"승계 진행해" \
--context-ratio 0.65 \
--json
```
`context_ratio >= 0.60`은 `ADVISORY`다. advisory는 승계 제안 신호일 뿐 successor를 자동 spawn하지 않는다.
승계 handoff는 `Role State`를 먼저 고정한다. `freeze_roles`는 현재 role만 유지하고 `lock_enabled=true`, `frozen=all other roles`, `unlock=explicit user instruction only` 형태로 잠근다. 현재 role이 없으면 승계 오류로 중단된다.
현재 마스터는 구조화된 JSON spec으로 handoff를 생성한다. handoff는 장문 회고가 아니라 successor가 복구해야 할 최소 운영 상태다.
```bash
scripts/master-succeed handoff \
--spec ./ops/handoff-spec.json \
--json
```
Spec에는 다음 항목을 넣는다.
| 항목 | 의미 |
| --- | --- |
| `current_role` 또는 `role_state` | 승계 후 유지할 현재 role |
| `current_objective` | 현재 목표 |
| `active_tracks`, `open_tracks` | 이어받을 작업 트랙 |
| `accepted_artifacts` | 이미 승인된 산출물 |
| `deferred_work` | 미룬 작업 |
| `open_questions` | 미해결 질문 |
| `recommended_next_role` | successor가 시작할 role |
| `observed_baseline` | handoff 시점의 관측 기준선 |
Successor spawn은 workspace selector, kickoff, root, model, title을 명시한다. 먼저 dry-run으로 실제 host command를 확인할 수 있다.
```bash
scripts/master-succeed spawn \
--workspace-selector "id:folder:" \
--kickoff-file ./ops/successor-kickoff.md \
--root . \
--model "" \
--agent codex \
--title "Gen N successor" \
--expected-placement "id:folder:" \
--json
```
Spawn은 생성 전 terminal 목록을 snapshot하고, 생성 후 반환된 `worktreeId`가 요청 selector와 일치하는지 확인한다. `--expected-placement`가 있으면 독립 기대 placement와도 다시 비교한다. 불일치하면 fail-closed로 terminal close를 시도하고 `SPAWN_PLACEMENT_MISMATCH` 계열 오류로 중단한다.
Successor는 recovery report를 만들고 `verify-successor`로 검증한다.
```bash
scripts/master-succeed verify-successor \
--report ./ops/recovery-report.json \
--json
```
검증 규칙은 단순하다. recovery step에 `MISS`가 있으면 `FAILED`다. step `6`이 `OK`이면 open tracks recited, step `2-3`이 `OK` 또는 없음이면 baseline matched, step `5`가 `OK`이면 monitors rearmed로 계산한다. 세 체크가 모두 있으면 `PASS`, 일부만 있으면 `PARTIAL`, 없으면 `FAILED`다.
Freezing은 retirement가 아니다. Predecessor 종료는 successor가 successor 자신과 predecessor를 구분한 뒤 실행한다. 기본은 dry-run이며, 실제 close에는 `--execute`가 필요하다.
```bash
scripts/master-succeed retire \
--self-handle \
--target-handle \
--target-pid \
--target-tty \
--json \
--execute
```
`retire`는 정확히 하나의 predecessor candidate만 허용한다. self handle 매치, candidate 없음, ambiguous candidate는 모두 `REFUSED`다. `--target-handle`, `--target-pty-id`, `--target-session-id`는 해당 필드에 exact match로 적용되고, selector 기반 fallback은 handle, pty, session id, worktree id, path, branch, title에 substring match를 수행한다.
Successor verification과 predecessor retirement 측정 후 `docs/lineage/MASTER-LINEAGE.md`에 concise entry를 append한다. Lineage는 append-only observability metadata이며 bootstrap source, priority source, model-evaluation source가 아니다.
Runtime의 `append_entry` 스키마는 `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`만 허용한다.
Retired 또는 frozen session은 다른 terminal, remote machine, mobile resume 경로에서 되살아날 수 있다. Boot 시점과 stray session 보고 시점에는 lineage에 기록된 session id를 running agent process argv에서 찾는다. Hit가 있으면 revived session 기록에서 freeze 이후 활동과 unanswered owner instruction을 확인하고, 해당 process와 tty chain을 같은 retirement 기준으로 제거한다.
## 상태와 판정값
| 단계 | 주요 상태 | 의미 |
| --- | --- | --- |
| Trigger | `IMMEDIATE` | 명시적 승계 지시 |
| Trigger | `ADVISORY` | context pressure 또는 milestone 신호. 자동 승계 금지 |
| Trigger | `NONE` | 승계 신호 없음 |
| Successor verify | `PASS` | open tracks, baseline, monitors 체크가 모두 충족됨 |
| Successor verify | `PARTIAL` | 일부 recovery evidence만 충족됨 |
| Successor verify | `FAILED` | `MISS`가 있거나 검증 체크가 없음 |
| Retirement | `DRY_RUN` | candidate만 확인하고 close하지 않음 |
| Retirement | `CLOSED` | pane, process, tty 세 소멸이 모두 측정됨 |
| Retirement | `CLOSED_PARTIAL` | pane은 사라졌지만 pid 또는 tty 측정이 skip됨 |
| Retirement | `REFUSED` | candidate, self-match, survivor, close 실패 등으로 종료 불가 |
`CLOSED_PARTIAL`은 성공적인 전체 retirement가 아니다. pid 또는 tty를 측정하지 못한 상태에서 pane만 사라진 경우이며, lineage에는 partial measurement로 기록해야 한다.
## Retirement handshake
`master-succeed retire --execute`는 predecessor pane을 닫는 host-level close다. 그 자체는 agent 내부에 flush를 요청하지 않는다. 운영 절차에서는 close 전에 predecessor에게 새 dispatch 중단, 미커밋 상태 flush, live worker와 unfinished track 보고, 최종 FIN line 출력을 요구한다.
| 단계 | Actor | 요구 사항 |
| --- | --- | --- |
| Freeze notice | Successor | predecessor에게 새 작업 수락 중단과 flush를 지시 |
| ACK | Predecessor | 중단 상태를 확인하고 남은 송신만 유지 |
| Flush | Predecessor | 커밋 가능한 상태를 저장하거나 저장 실패 경로를 보고 |
| FIN | Predecessor | 합의한 final line을 출력하고 이후 발화 중단 |
| TIME_WAIT | Successor | pane read와 host last-output 기준으로 quiet window 측정 |
| Close | Successor | `retire --execute` 후 pane/process/tty 소멸 측정 |
## Placement와 duplicate 방어
Successor spawn은 selector와 실제 `worktreeId`를 비교한다. Folder workspace selector는 `id:folder:` 형태가 정상이며, bare `folder:`는 terminal list 호출에서 `id:`가 붙어 처리된다. `path:` selector는 repository worktree path 비교에만 사용된다.
```bash
scripts/master-succeed check-duplicates \
--self-handle \
--marker \
--json
```
Duplicate check는 현재 handle을 제외하고 marker와 일치하는 Orca terminal session을 찾는다. 결과가 비어 있지 않으면 같은 lineage 또는 workspace를 잡은 다른 master가 있다는 신호다.
## Lineage 작성 기준
Lineage entry는 successor가 boot comparison을 끝낸 뒤 append한다. 기록에는 최소한 generation, parent/successor reference, inherited role, open tracks, verification result, measured comparison values, context-loss 또는 repeated-question metric을 포함한다. 측정하지 못한 값은 narrative로 채우지 않고 `미확인` 또는 tool이 실제 반환한 `unconfigured`로 남긴다.
Lineage는 관측 로그다. Handoff와 fresh measurement가 충돌하면 handoff를 덮어쓰지 말고, 충돌 사실과 fresh measurement의 범위를 함께 기록한다.
## 실패 처리
| 증상 | 처리 |
| --- | --- |
| `detect`가 `ADVISORY`를 반환 | 승계를 제안할 수 있지만 자동 spawn하지 않는다 |
| successor spawn placement mismatch | 생성된 terminal close를 시도하고 fail-closed로 중단 |
| 반환 handle이 stale 또는 재발급됨 | 새 terminal 목록에서 같은 workspace와 title의 유일한 candidate만 adopt한다 |
| predecessor candidate가 0개 또는 여러 개 | `REFUSED`; title drift와 match attempts를 확인한다 |
| close 후 pane이 남아 있음 | `REFUSED`; close 반환값보다 측정 결과가 우선한다 |
| pid 또는 tty 미제공 | `CLOSED_PARTIAL`; full close로 기록하지 않는다 |
| process death, host restart, stale UI handle | succession이 아니라 accident recovery로 다루고 같은 session resume 가능성을 먼저 확인한다 |
## Related pages
Succession이 bootstrap, recovery, lineage, adapter layer와 어떻게 분리되는지 확인합니다.
Workspace selector, folder workspace, worktree placement 판정 기준을 확인합니다.
Duplicate master, placement mismatch, revival check가 어떤 실패를 막는지 표로 확인합니다.
`scripts/master-succeed` 하위 명령과 option surface를 빠르게 확인합니다.