5.6 KB · updated 2026-07-31 · md

v0.28.4.ko.md

docs/i18n/release-notes/v0.28.4.ko.md

Tesserae v0.28.4 — 나머지 계정은 한 번도 쓰이지 않고 있었다

<!-- translations:start -->

English · 中文 · 日本語 · Русский · Español · Français · Deutsch

<!-- translations:end -->

Released 2026-07-31 · PyPI · GitHub release · pip install --upgrade tesserae==0.28.4

Tesserae는 로그인된 CLI 계정들을 순회한다. 사용량 한도에 걸린 계정이 있으면 다음 계정으로 넘어가, 남은 작업 전체가 결정론적 추출로 떨어지지 않게 하기 위해서다. 그런데 그 순회가 꺼져 있었다 — 그것도 Tesserae가 가장 흔하게 실행되는 방식에서.

환경변수 하나가 메커니즘 전체를 무력화했다

CLAUDE_CONFIG_DIR 또는 CODEX_HOME을 설정하면 탐색된 계정 목록이 그 디렉터리 하나로 대체됐다. Claude Code 세션이 띄우는 모든 프로세스는 CLAUDE_CONFIG_DIR을 상속하므로, 컴파일은 자신을 시작한 세션의 계정만 쓸 수 있었고 그 계정이 마르면 순회는 갈 곳이 없었다.

이 프로젝트 자체 그래프에서 하루 만에 측정된 결과:

  • 어떤 컴파일은 한 계정의 5시간 한도를 소진하며 1,531개 문서를 결정론적 추출로 떨궜다. 그동안 로그인된 다른 두 계정은 할당량을 가득 채운 채 놀고 있었다.
  • 이후 실행은 한 계정의 만료된 OAuth 때문에 1,590개를 더 잃었다. 바로 옆에 멀쩡한 계정이 있었는데도.

그래프는 약 13,000노드에서 5,155노드로 조용히 줄어든 뒤에야 발견됐다.

이제 환경변수는 가장 먼저 시도할 계정을 지정할 뿐, 유일하게 시도 가능한 계정을 뜻하지 않는다.

어떤 계정을 쓸지는 사용자가 정한다

llm_claude_config_dirs와 새로 추가된 llm_codex_homes(순회 순서를 가진 리스트)를 설정하면 그 목록이 최종 권위를 가진다. 목록 밖은 시도되지 않으며, 선택된 것이 아니라 상속된 값인 주변 환경변수보다 우선한다.

{
  "llm_codex_homes": ["/Users/you/.codex-work", "/Users/you/.codex-personal"]
}

프로바이더마다 키가 다른 이유는 Claude CLI 설정 디렉터리와 Codex 홈이 디스크상 서로 다른 것이기 때문이다. Codex 탐색은 이제 auth.json을 요구한다. 실제 어느 머신에서는 이 조건이 떠돌던 ~/.codex-*.log 파일 24개를 걸러냈는데, 그것들은 문서마다 실패가 예정된 codex exec를 한 번씩 낭비시키고 있었다.

소진된 계정 때문에 문서마다 프로세스를 띄우지 않는다

할당량은 계정의 사실이지 문서의 사실이 아니다. 설정된 모든 계정이 한도를 보고한 뒤에도, 실행은 남은 문서마다 계정마다 CLI 자식 프로세스를 띄워 같은 말을 다시 들었다. 이제 그 판정은 남은 실행 동안 기억된다.

오작동은 일부러 어렵게 만들었다. 시도된 모든 계정이 확인된 막다른 길이어야 하고, 그중 최소 하나는 "you've hit your … limit"라고 명시해야 한다. 그중 하나라도 타임아웃이면 실행은 계속 시도한다 — 일시적 장애는 소진이 아니다. 판정은 클라이언트 단위라, 오래 사는 데몬이 한도 초기화 이후에도 멈춰 있지 않는다.

개념 계층을 잃은 컴파일은 이제 그렇다고 말한다

Compiled project wiki: processed=2492 skipped=0 fallbacks=1531 nodes=… edges=…
WARNING: 1531 of 2492 document(s) (61.4%) fell back to deterministic extraction —
their concept layer is missing from this graph.

fallbacks=N은 기계가 읽는 요약 줄에 실려 CI가 이를 기준으로 게이트할 수 있고, 사람이 읽는 줄은 50%를 넘으면 note:에서 경고로 올라간다. 둘 다 복구 방법을 알려주며, 그 복구에는 전체 재컴파일이 필요 없다:

tesserae compile --changed-only --retry-fallbacks

#92 이야기다. 위의 모든 버그를 하루 동안 보이지 않게 만든 것이 바로 이 침묵이었다. 종료 코드는 그대로 뒀다 — compile을 스크립트로 감싼 모든 것에 대한 계약 변경이며, 별도 결정이 필요하다.

그 밖에

Claude 추출기는 더 이상 --max-turns 1을 넘기지 않는다. 이 플래그는 응답이 아니라 도구 호출을 세므로, MCP 서버가 설정된 머신에서는 모델의 첫 도구 호출이 유일한 턴을 소진했고 CLI는 JSON을 내보내기 전에 종료했다. 원샷 의도가 실제로 요구하는 것은 --strict-mcp-config다.

@jokerized/tesserae는 이제 npm OIDC 신뢰 게시(trusted publishing)를 통해 GitHub Actions에서 배포된다. 릴리스에 프로버넌스 증명이 붙고, 오래 사는 npm 토큰은 더 이상 존재하지 않는다.

v0.28.3에서 업그레이드

그대로 교체하면 된다. API·스키마 변경 없음. llm_codex_homes는 추가된 키이며 기존의 단수형 llm_codex_home도 계속 동작한다.

여러 계정을 쓴다면 다시 컴파일하라. 이전 버전에서 품질이 떨어진 문서를 새 실행이 복구할 수 있고, 캐시 덕분에 영향받은 파일만 비용이 든다:

tesserae compile --changed-only --retry-fallbacks