# relay-baton v0.3.0 릴리즈 노트

날짜: 2026-05-28

## 요약

v0.3.0은 v0.2의 project layer 위에 안정성/안전성 패치를 얹은 버전이다. 코드 리뷰에서 발견한 4가지 이슈를 고치고, registry를 비파괴적으로 다루기 위한 기반을 추가했다.

핵심:

- `ProjectResolver.resolve()`가 더 이상 registry에 side effect를 일으키지 않는다.
- 손상된 `projects.json`에서 crash 대신 recovery 한다.
- `RELAY_BATON_PROJECTS_FILE` env로 registry 경로를 override 할 수 있다.
- `run`이 fallback 감지 후 stale `lastError`를 남기지 않는다.

## 패치

### Resolver의 side effect 제거

v0.2에서는 `--project`나 active project로 해석할 때마다 `updateLastUsedAt`이 호출되어 `projects.json`이 매번 다시 써졌다. `status`, `budget`, `doctor` 같은 read-only 명령에서도 disk write가 발생한다는 뜻이다.

v0.3:

- `ProjectResolver.resolve()`는 순수 함수처럼 repo root만 계산한다.
- 새 `ProjectResolver.touch(result)`가 `lastUsedAt`을 명시적으로 갱신한다.
- CLI의 `resolveProjectContext(opts, touch = true)`는 agent를 실제로 실행하는 명령(`run`, `handoff`)에서만 `touch()`를 호출한다.
- `status`, `budget`, `doctor`, `init`, `compact`, `squeeze`, `tui`는 resolve 과정에서 더 이상 registry에 쓰지 않는다.

### Registry recovery

`projects.json`이 손상되었을 때 v0.2는 `ProjectRegistryError`를 던지고 CLI가 종료됐다.

v0.3:

- 손상된 파일을 `<file>.corrupt-<timestamp>.bak`로 백업한다.
- 비어 있는 새 registry를 쓴다.
- `[relay-baton]` 경고를 stderr에 찍는다.
- 명령은 그대로 진행한다.

JSON parse 실패와 shape 불일치 모두에 적용된다.

### `RELAY_BATON_PROJECTS_FILE` env override

`ProjectRegistry.defaultPath()`가 환경변수 `RELAY_BATON_PROJECTS_FILE`을 우선 사용한다. 용도:

- smoke test를 사용자 registry와 격리해서 실행
- CI 환경에서 `relay-baton` sandboxing
- `~/.relay-baton` 대신 다른 위치의 registry 사용

빈 값은 무시되고, 설정 안 했을 때는 v0.2와 동일하게 `~/.relay-baton/projects.json`을 사용한다.

### `run`의 `lastError` 초기화

v0.2에서는 Codex가 fallback 패턴을 출력했지만 non-zero로 종료한 경우, `meta.lastError`에 `codex exited with <n>`이 남았다. 이후 agent 실행이 stale 에러를 그대로 물려받았다.

v0.3에서는 fallback이 감지되면 exitCode와 무관하게 `lastError`를 `null`로 비운다. `status: "fallback_detected"`의 의미와 일치시킨 동작이다.

## 호환성

- CLI 인터페이스 변경 없음. v0.2 명령어와 옵션 그대로 동작.
- `ProjectResolver.resolve()`의 side effect가 사라졌다. `lastUsedAt`을 갱신해야 하는 곳은 `touch()`를 명시적으로 호출해야 한다 (이미 `run`/`handoff` 갱신됨).
- `ProjectRegistry.read()`는 손상된 파일에서 더 이상 throw하지 않는다. `ProjectRegistryError`를 catch하던 코드는 빈 registry를 받고 stderr 경고를 보게 된다.
- `RELAY_BATON_PROJECTS_FILE`이 있으면 그 경로를 쓰고, 없으면 v0.2와 동일.

## 다음 개선 추천

- 빌드된 binary를 `RELAY_BATON_PROJECTS_FILE` 기준으로 실행하는 CLI smoke test.
- TUI fuzzy project switcher.
- project별 session list와 recent handoff history.
- TUI command palette.
- 추가 agent adapter scaffold (`opencode`, `gemini`, `aider`).