파일 tail과 세션 로케이터의 크로스 플랫폼 호환성 가이드.

경로 정규화

locator.py의 _norm() 함수가 핵심:

def _norm(p: str) -> str:
    s = p.replace("\\", "/").rstrip("/")
    if len(s) >= 2 and s[1] == ":":  # Windows drive letter
        s = s.lower()
    return s

백슬래시 → 슬래시 변환
trailing separator 제거
드라이브 레터 있으면 소문자화 (Windows case-insensitive FS)

세션 탐색 우선순위

SessionLocator.find_active() 폴백 체인:

slug 디렉토리: ~/.claude/projects/{slug-of-cwd}/ 하위 최신 JSONL
cwd 필드 매칭: slug 미스 시, 전체 JSONL의 cwd 필드를 읽어 현재 작업 디렉토리와 비교
전역 최신: 위 모두 실패 시, ~/.claude/projects/*/ 하위 가장 최신 JSONL

cwd 필드 폴백을 제거하면 Windows/git-bash에서 세션을 찾지 못한다. 이 경로는 보존해야 한다.

ChosenReason 타입

파일 tail과 세션 로케이터의 크로스 플랫폼 호환성 가이드.

경로 정규화

locator.py의 _norm() 함수가 핵심:

def _norm(p: str) -> str:
    s = p.replace("\\", "/").rstrip("/")
    if len(s) >= 2 and s[1] == ":":  # Windows drive letter
        s = s.lower()
    return s

백슬래시 → 슬래시 변환
trailing separator 제거
드라이브 레터 있으면 소문자화 (Windows case-insensitive FS)

세션 탐색 우선순위

SessionLocator.find_active() 폴백 체인:

slug 디렉토리: ~/.claude/projects/{slug-of-cwd}/ 하위 최신 JSONL
cwd 필드 매칭: slug 미스 시, 전체 JSONL의 cwd 필드를 읽어 현재 작업 디렉토리와 비교
전역 최신: 위 모두 실패 시, ~/.claude/projects/*/ 하위 가장 최신 JSONL

cwd 필드 폴백을 제거하면 Windows/git-bash에서 세션을 찾지 못한다. 이 경로는 보존해야 한다.

플랫폼	핵심 검증 항목
macOS/Linux	slug 디렉토리 매칭
Windows	드라이브 레터 정규화, 백슬래시 변환
git-bash	cwd 필드 폴백 (slug 패턴 불일치)
CI (no watchfiles)	PollingTailer 폴백

Watcher Portability

경로 정규화

세션 탐색 우선순위

ChosenReason 타입

Watcher Portability

경로 정규화

세션 탐색 우선순위

ChosenReason 타입

와처 아키텍처

WatchfilesTailer (기본)

PollingTailer (폴백)

공통 방어

서브에이전트 와처

Shift+S 경로 입력

테스트 대상

Coding Agent (bash-first)

Fix

Commit

Init

Github Copilot Upgrader

Rebuilding Flutter Tool