# Orca 객체 모델

> Project, workspace, worktree, terminal, Run, selector 형식, folder workspace의 정상 라벨과 misplacement 실패 조건을 설명합니다.

- 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/orca-concepts.md`
- `local-mogui-ade-orchestrator:docs/public/getting-started.md`
- `local-mogui-ade-orchestrator:src/master_runtime/core/succession.py`
- `local-mogui-ade-orchestrator:tests/test_succession.py`
- `local-master-ops:docs/runbooks/succession-boot-card.md`

---

---
title: "Orca 객체 모델"
description: "Project, workspace, worktree, terminal, Run, selector 형식, folder workspace의 정상 라벨과 misplacement 실패 조건을 설명합니다."
---

Orca 런타임은 master와 worker를 모두 Orca terminal에 앉히며, `worktreeId`, `worktreePath`, terminal handle, orchestration Run을 서로 다른 식별자로 취급한다. multi-repository workspace에서 master의 정상 좌석은 workspace root의 folder workspace이고, worker의 정상 좌석은 작업 대상 repository worktree이다.

## 객체 경계

| 객체 | 의미 | 정상 소유자 | 주요 식별자 |
| --- | --- | --- | --- |
| Project | Orca에 등록된 폴더 단위 | Orca sidebar | 등록된 folder 또는 repository |
| Workspace | terminal이 생성되는 좌석 | Project | repository worktree 또는 folder workspace |
| Worktree | Git checkout이 있는 repository workspace | worker | `repoId::path`, `id:<repoId>::<path>` |
| Folder workspace | Git checkout이 없는 folder project 좌석 | master | `folder:<uuid>`, 권장 기록형은 `id:folder:<uuid>` |
| Terminal | Orca가 관리하는 live session | master 또는 worker | `handle`, `ptyId`, `sessionId` |
| Run | terminal에 묶인 durable orchestration context | coordinator | task, dispatch, mailbox 상태 |

<Note>
folder workspace는 Git checkout이 아니다. 따라서 `worktreePath`가 빈 문자열이어도 정상이며, placement 판단은 `worktreeId`로 한다.
</Note>

## master와 worker 좌석

multi-repository workspace에서 master는 repository 하나의 worktree 안에 있으면 안 된다. master는 여러 repository를 조정하므로 workspace root의 folder workspace에 앉아야 한다. 단일 repository workspace에서는 그 repository의 primary worktree가 workspace-level seat가 될 수 있다.

worker는 반대다. Git 작업을 해야 하는 worker는 대상 repository의 독립 worktree에서 시작해야 한다. folder workspace에 worker를 만들면 첫 명령이 checkout으로 이동하지 않는 한 `git` 작업이 실패하거나 잘못된 위치에서 실행된다.

```text
workspace root/
  product-a/        <- worker worktree 대상 repository
  product-b/        <- worker worktree 대상 repository
  master-ops/       <- 운영 기록과 runbook
  [folder workspace] <- master seat
```

## selector 형식

좌석은 terminal handle이 아니라 selector로 기록한다. handle은 live app runtime 안의 terminal 주소이고, 재시작이나 close 이후 durable seat identity가 아니다.

| selector | 용도 | 운영 판단 |
| --- | --- | --- |
| `id:<repoId>::<path>` | repository worktree | repository worker 좌석에 사용 |
| `id:folder:<uuid>` | folder workspace | master seat의 권장 durable 형식 |
| `folder:<uuid>` | folder workspace | `terminal create`에서는 동작할 수 있으나 `terminal list --worktree`와 비대칭이 있어 기록형으로 쓰지 않는다 |
| `path:/abs/dir` | filesystem path selector | Orca가 resolve할 수 있어도 placement 비교에서 mismatch를 만들 수 있으므로 master seat 기록에 쓰지 않는다 |

<Warning>
`orca terminal create --worktree`에 selector를 생략하면 현재 shell cwd에서 Orca가 좌석을 추론할 수 있다. 이 경로는 misplacement 원인이므로 founding, succession, reverify에서는 durable selector를 명시한다.
</Warning>

## 정상 라벨

folder workspace master에는 UI나 CLI에서 Git worktree가 없다는 신호가 나타난다. 이 신호는 장애가 아니다.

| 표시 | 의미 | 조치 |
| --- | --- | --- |
| `Unavailable worktree` | session이 Git worktree가 아닌 folder workspace에 있음 | master가 folder workspace에 있으면 정상 |
| 빈 `worktreePath` | folder workspace에는 checkout path가 없음 | `worktreeId`가 `folder:<uuid>`인지 확인 |
| workspace root에서 `not a valid worktree folder` 계열 메시지 | workspace root가 plain folder임 | submodule parent나 Git repository로 바꾸지 않는다 |

## misplacement 실패 조건

misplacement는 terminal 생성이 실패한 상태만 뜻하지 않는다. terminal이 살아 있고 cwd, hook, session artifact가 모두 그럴듯해도 좌석이 틀리면 실패다.

다음 조건이면 master placement 실패로 본다.

| 조건 | 실패 이유 |
| --- | --- |
| multi-repo workspace의 master가 product repository worktree 아래에 표시됨 | master가 worker용 좌석에 앉아 workspace 전체를 대표하지 못함 |
| `worktreePath`만 보고 folder workspace를 실패로 판단함 | folder workspace의 정상 shape를 Git worktree 기준으로 오판함 |
| `path:` selector로 green 상태를 만든 뒤 durable selector로 기록함 | request 자체가 의도한 seat인지 검증하지 않음 |
| temporary seat-check terminal이 남아 있는데 founding spawn을 진행함 | master seat가 비어 있지 않아 duplicate master 위험이 있음 |
| Reverify에서 master 부재를 보고 Founding을 다시 실행함 | 기존 workspace에는 recovery 또는 succession 경로를 써야 함 |

## 검증 명령

좌석 검증은 Orca의 terminal metadata에서 시작한다.

```console
$ orca terminal show --terminal <terminal-handle> --json
```

folder workspace의 기대 shape:

```json
{
  "worktreeId": "folder:<uuid>",
  "worktreePath": "",
  "handle": "<terminal-handle>",
  "connected": true
}
```

durable selector가 여전히 host에서 해석되는지 확인한다.

```console
$ orca terminal list --worktree id:folder:<uuid> --json
```

founding spawn 전에는 이 목록이 비어 있어야 한다. reverify에서는 같은 selector에 live master terminal이 정확히 하나 있어야 한다.

## succession과 Run

succession은 기존 master가 새 terminal을 만들고, 새 terminal이 같은 workspace-level seat에 있는지 확인한 뒤 role state와 lineage를 이어받는 절차다. spawn 검증은 다음 값을 분리해서 본다.

| 값 | 역할 |
| --- | --- |
| `requested_worktree` | spawn 요청에 사용한 selector |
| `worktreeId` | Orca create/list 응답의 실제 seat |
| `expected_placement` | ops 기록이 기대하는 durable seat |
| `handle` | 새 terminal을 조작하기 위한 live 주소 |
| Run | task, dispatch, completion mailbox를 보존하는 orchestration context |

검증 결과는 `MATCH` 또는 `MATCH_REISSUED`만 성공으로 취급한다. `MATCH_REISSUED`는 create 응답의 handle이 stale일 때, 같은 selector 안의 새 live terminal을 title과 연결 상태로 재확인해 채택한 경우다. selector mismatch, expected placement mismatch, stale handle ambiguity는 fail-closed다.

## workspace descriptor

workspace inventory는 instance-owned `config/workspace-descriptor.json`에 둔다. template은 example만 제공하고, 실제 파일은 설치 환경의 absolute `workspace_root`와 repository 목록을 담을 수 있으므로 커밋 대상이 아니다.

핵심 필드:

| 필드 | 값 |
| --- | --- |
| `workspace_root_is_plain_folder` | 항상 `true` |
| `workspace_root` | owner가 확인한 absolute workspace root |
| `master_seat` | `id:folder:<uuid>` 또는 단일 repository 예외의 primary seat |
| `repositories[].path` | workspace-root-relative path |
| `repositories[].role` | `product` 또는 `ops` |
| `repositories[].prohibited` | 예: `direct-main-commit`, `force-push` |

<Info>
이 모델은 특정 agent CLI나 model provider에 종속되지 않는다. Orca의 project, workspace, terminal, Run 식별자를 기준으로 좌석과 dispatch를 검증하고, agent CLI는 terminal 안에서 실행되는 runtime으로 취급한다.
</Info>

## Related pages

<CardGroup>
  <Card title="워크스페이스와 제품 저장소 관계" href="/workspace-product-relationship">
    workspace root, ops repository, product repository의 경계를 구분한다.
  </Card>
  <Card title="워크스페이스 Founding" href="/found-workspace">
    folder workspace seat 측정과 founding spawn 절차를 실행 순서로 확인한다.
  </Card>
  <Card title="마스터 승계" href="/run-succession">
    successor spawn, placement 검증, predecessor retirement 흐름을 다룬다.
  </Card>
  <Card title="문제 해결" href="/troubleshooting">
    misplacement, duplicate master, Unavailable worktree 증상을 진단한다.
  </Card>
</CardGroup>