# 문제 해결

> preflight BLOCKED, Orca CLI 미등록, misplacement, duplicate master, Unavailable worktree, model probe undecidable, redaction cannot decide를 증상별로 다룹니다.

- 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/getting-started.md`
- `local-mogui-ade-orchestrator:docs/public/orca-concepts.md`
- `local-mogui-ade-orchestrator:docs/public/master-lifecycle.md`
- `local-mogui-ade-orchestrator:docs/public/defense-inventory.md`
- `local-master-ops:docs/runbooks/orca-wait.md`
- `local-master-ops:docs/runbooks/error-and-logging.md`
- `local-master-ops:docs/blame/BLAME-2026-08-04-succession-misseat.md`

---

---
title: "문제 해결"
description: "preflight BLOCKED, Orca CLI 미등록, misplacement, duplicate master, Unavailable worktree, model probe undecidable, redaction cannot decide를 증상별로 다룹니다."
---

`scripts/onboarding-preflight.sh`, `scripts/master-succeed`, `scripts/model-identity-probe`, `scripts/model-drift-audit`, `scripts/redaction-scan.sh`는 성공 여부를 추론하지 않고 측정값과 exit code로 분리한다. 문제 해결의 기본 순서는 증상 문자열을 먼저 확인하고, 해당 스크립트가 요구하는 입력을 다시 측정한 뒤, 실패가 배치·모델·redaction 범위 중 어느 계층에서 난 것인지 좁히는 것이다.

## 빠른 판별표

| 증상 | 먼저 볼 신호 | 정상 해석 | 다음 조치 |
| --- | --- | --- | --- |
| `Preflight summary` 아래 `BLOCKED` | `FAIL` 행과 essential block | 필수 체크가 만족되지 않음 | 각 `FAIL`을 고치고 preflight 재실행 |
| Orca CLI 미등록 | `orca is not available`, `orca status --json failed` | 앱은 있어도 shell command가 없음 | Orca 설정에서 CLI shell command 활성화 |
| misplacement | master가 제품 repo worktree 아래에 보임 | multi-repo master seat가 아님 | 새 founding 금지, selector와 seat 재측정 |
| duplicate master | 같은 workspace에 master 세션 2개 | 런타임 사고 | `check-duplicates` 결과를 기준으로 정리 |
| `Unavailable worktree` | folder workspace master | 보통 정상 | `worktreeId`가 `folder:<uuid>`인지 확인 |
| model probe undecidable | probe/audit exit `2` | 검증 불가 또는 drift 계열 | 통과로 읽지 말고 transcript 설정 또는 succession 검토 |
| redaction cannot decide | redaction exit `2` | scan 범위가 확정되지 않음 | `gitleaks`, org rules, allowlist, usage를 고침 |

<Warning>
exit `2`는 “깨끗함”이 아니다. 이 런타임에서 `2`는 주로 `cannot decide`, `undecidable`, usage/runtime error를 뜻한다.
</Warning>

## preflight가 `BLOCKED`로 끝남

`BLOCKED`는 `scripts/onboarding-preflight.sh`가 하나 이상의 required check를 `FAIL`로 판정했다는 뜻이다. WARN만 있으면 exit 1로 막지 않지만, essential component는 요약에서 다시 출력된다.

```bash
ORCA_AGENT_CLI="<master-agent-cli>" bash scripts/onboarding-preflight.sh
```

확인 순서:

<Steps>
<Step title="FAIL 행을 그대로 읽기">
`PASS`, `WARN`, `FAIL`, `WAIVED`가 라벨별로 출력된다. `BLOCKED`가 있으면 `FAIL` 라벨이 원인이다.
</Step>
<Step title="필수 도구를 고치기">
`orca`, `orchestration`, `skills`, `agent-cli`, `worker-runtime`, `bd`, `python3`, `git`, `gh`, `redaction-extra` 같은 라벨은 later spawn과 dispatch의 실제 전제다.
</Step>
<Step title="waiver를 명시적으로만 사용하기">
`PREFLIGHT_WAIVE=<label>`은 해당 check를 `WAIVED`로 낮춘다. 이 값은 결핍을 해결하지 않고, 받아들인 동작을 출력에 남긴다.
</Step>
</Steps>

```bash
PREFLIGHT_WAIVE=ctx ORCA_AGENT_CLI=claude bash scripts/onboarding-preflight.sh
```

`orchestration` 실패는 단순 reachability 문제가 아닐 수 있다. `legacy_read_only`, `run_required`, `run:null` 계열 메시지가 나오면 `orca orchestration run-create`로 현재 terminal에 non-legacy Run을 다시 묶고 preflight를 재실행한다.

## Orca CLI가 등록되지 않음

preflight의 Orca 해석 순서는 `ORCA_CLI_COMMAND`, `ORCA_DEV_REPO_ROOT`, 기본 `orca`다. 지원 basename은 `orca`, `orca-dev`, `orca-ide`다.

```bash
command -v orca
orca status --json
```

실패 메시지가 `follow-up: enable Settings > Orca CLI > Shell command`를 가리키면 Orca 앱의 CLI launcher가 shell에 노출되지 않은 상태다. 앱을 열고 **Settings → Orca CLI → Shell command**를 켠 뒤 다시 측정한다.

macOS에서 설치 자체가 없으면 preflight는 Homebrew cask 경로를 안내한다.

```bash
brew install --cask stablyai/orca/orca
```

Linux와 Windows는 공식 다운로드 경로를 사용한다. 설치 후에도 성공 기준은 동일하다: `command -v orca`와 `orca status --json`의 `ok:true`.

## misplacement: master가 잘못된 자리에 앉음

multi-repository workspace에서 master seat는 workspace root의 folder workspace다. 제품 저장소나 ops 저장소의 repository worktree에 앉은 master는 cwd가 맞아 보여도 misplacement다.

정상 selector 형태:

```text
id:folder:<uuid>
```

repository worktree selector는 worker seat에 사용한다.

```text
id:<repoId>::<path>
```

피해야 할 패턴:

| 입력 | 문제 |
| --- | --- |
| `path:/abs/dir` | Orca가 내부 id로 resolve해도 spawn placement 비교에서 mismatch가 날 수 있음 |
| bare `folder:<uuid>` | 일부 subcommand에서는 통과하고 일부 list 계열에서는 거부되는 비대칭이 있음 |
| ops repo worktree fallback | workspace master가 owner sidebar와 lineage seat 밖으로 이동함 |

승계나 founding spawn 직후에는 생존만 보지 말고 placement evidence를 본다.

```bash
orca terminal list --worktree "id:folder:<uuid>" --json
scripts/master-succeed spawn \
  --workspace-selector "id:folder:<uuid>" \
  --expected-placement "id:folder:<uuid>" \
  --kickoff-text "Founding master boot" \
  --root . \
  --model "<configured-model>" \
  --title "Founding master boot" \
  --json
```

`SPAWN_PLACEMENT_MISMATCH` 또는 exit `26`은 fail-closed다. 새 terminal을 계속 진행하지 말고 selector, expected placement, workspace root 등록 상태를 다시 확인한다.

## duplicate master

duplicate master는 reverify 대신 founding을 다시 돌리거나, succession/resume 뒤 이전 master가 살아 있을 때 생긴다. 기존 ops repository와 lineage가 있으면 Founding으로 다시 들어가지 않는다.

```bash
scripts/master-succeed check-duplicates \
  --session-marker "<workspace-master-marker>" \
  --self-handle "<current-terminal-handle>" \
  --json
```

결과가 비어 있지 않으면 soft warning이 아니라 finding이다. 현재 master를 기준으로 predecessor 또는 revived session을 분류하고, retirement 절차는 pane close만으로 끝내지 않는다. 완전 종료는 process, host pane, tty의 소멸을 각각 측정해야 한다.

<Warning>
duplicate가 의심될 때 새 master를 하나 더 만들지 않는다. 먼저 live terminal 목록, lineage session id, role-state를 대조한다.
</Warning>

## `Unavailable worktree`

folder workspace에 앉은 master는 Git worktree가 아니므로 Orca UI나 session history에서 `Unavailable worktree`처럼 보일 수 있다. 이 자체는 crash가 아니다.

정상 확인 기준은 path가 아니라 `worktreeId`다.

```bash
orca terminal list --json
```

folder workspace master의 전형적 신호:

```json
{
  "worktreeId": "folder:<uuid>",
  "worktreePath": ""
}
```

multi-repo workspace에서 이 상태는 master seat와 맞다. 반대로 master가 특정 제품 repository의 worktree 아래에 보이면 `Unavailable worktree`가 없더라도 misplacement일 수 있다.

## model probe undecidable

`model-identity-probe`는 최근 assistant turn의 model field를 본다. `--transcript`가 없으면 `MOGUI_TRANSCRIPT_GLOB` 또는 `config/instance-runtime.json`의 `transcript_globs.<runtime>`로 newest match를 찾는다.

```bash
scripts/model-identity-probe \
  --transcript ./sessions/example.jsonl \
  --expect "<expected-model>"
```

출력 해석:

| 출력 | exit | 의미 |
| --- | --- | --- |
| `MODEL-PROBE OK ...` | `0` | 최근 sample이 기대 model과 일치 |
| `MODEL-PROBE INFO ... nothing asserted` | `0` | 기대값이 없어 측정만 했고 검증 주장은 없음 |
| `MODEL-PROBE DRIFT: ...` | `2` | mismatch, unreadable, unconfigured, invalid limit 등으로 통과 판정 불가 |

중간 drift는 최근 sample만으로 놓칠 수 있다. succession audit이나 session close에서는 전체 transcript를 걷는 audit을 사용한다.

```bash
scripts/model-drift-audit \
  --transcript ./sessions/example.jsonl \
  --expect "<expected-model>"
```

`model-drift-audit`의 exit code는 `0` no transition, `1` transition 또는 expectation mismatch, `2` undecidable이다. `2`는 transcript 없음, unreadable, assistant turn 없음, real model 미관측 같은 상태다.

## redaction cannot decide

`scripts/redaction-scan.sh`는 gitleaks를 engine으로 사용하고, repository content와 선택된 commit message 범위를 스캔한다. exit code는 `0` clean, `1` findings, `2` cannot decide다.

```bash
scripts/redaction-scan.sh
scripts/redaction-scan.sh --staged
scripts/redaction-scan.sh --range "$remote_sha..$local_sha"
scripts/redaction-scan.sh --commit-messages "$remote_sha..$local_sha"
```

`cannot decide`의 대표 원인:

| 원인 | 신호 | 조치 |
| --- | --- | --- |
| `gitleaks` 없음 | `gitleaks is not on PATH` | `gitleaks` 설치 후 재실행 |
| base config 없음 | `missing config/gitleaks.toml` | checkout과 repo root 확인 |
| organization rules 없음 | `required organization rules were not loaded` | `REDACTION_EXTRA_PATTERNS` 파일 지정 |
| retired allowlist 존재 | `redaction-allowlist.txt has entries in the retired format` | `.gitleaksignore` fingerprint 또는 `config/gitleaks.toml` allowlist로 이전 |
| range 오류 | `--range requires A..B`, `range does not resolve` | push range 또는 commit range 수정 |
| RE2 미지원 regex | `merged config crashes the engine` | 해당 rule id의 regex를 RE2 호환으로 수정 |

organization-specific rule 파일 형식:

```text
id|description|regex
```

public release나 push 전에는 generic-only green을 허용하지 않도록 강제한다.

```bash
REDACTION_REQUIRE_EXTRA=1 \
REDACTION_EXTRA_PATTERNS=~/.config/redaction-extra.txt \
scripts/redaction-scan.sh --range "$remote_sha..$local_sha"
```

정상 green은 scope를 포함한다.

```text
redaction-scan: OK — 0 findings (mode=tracked, files=144, commit-messages=not-scanned, org-rules=10)
```

`org-rules=0`인 green은 organization identifier까지 검증했다는 뜻이 아니다.

## 관련 페이지

<CardGroup>
<Card title="설치" href="/installation">
preflight가 측정하는 도구, redaction rules, Orca CLI 등록 전제.
</Card>
<Card title="Orca 객체 모델" href="/orca-object-model">
Project, folder workspace, worktree, terminal, selector 형식과 misplacement 조건.
</Card>
<Card title="방어 인벤토리" href="/defense-inventory">
placement, duplicate master, model verification, redaction gate의 fail-closed 표면.
</Card>
<Card title="모델 식별과 drift 감사" href="/model-identity">
model probe, drift audit, undecidable 상태, transcript glob 설정.
</Card>
<Card title="Redaction 게이트" href="/redaction-gates">
repository scan, organization rules, commit message scan, exit code 기준.
</Card>
</CardGroup>