triflux 10.57.0 → 10.57.2

package/.claude/rules/tfx-routing.md

@@ -0,0 +1,178 @@
+# 자연어 → 스킬 라우팅
+
+사용자가 스킬명을 모르더라도 자연어로 요청하면 아래 규칙에 따라 적절한 스킬을 호출한다.
+
+이 문서는 **무엇을 어떤 순서로 밟는가**(워크플로 단계 + 자연어 트리거)를 정한다.
+**어느 시스템이 그 기능을 소유하는가**(gstack / superpowers / triflux)는
+`tfx-stack-coexistence.md` 의 책임 매트릭스가 SSOT다. 두 문서가 어긋나 보이면 층위를
+먼저 구분한다. 실행 계획은 superpowers `writing-plans`, TFX 다중모델 계획·실행은
+`tfx-auto --mode deep`이 맡는다. 같은 층위에서 실제로 갈릴 때만 coexistence를 따른다.
+
+## 기본 워크플로우 ladder
+
+넓은 운영 순서와 스택 간 책임 경계는 이 파일에 둔다. 개별 `SKILL.md`
+description에는 해당 스킬을 고르는 데 필요한 좁은 activation phrase만 넣는다.
+
+| 상황 | 기본 순서 | 비고 |
+|------|-----------|------|
+| 메타 라우팅/스킬 선택 | `/tfx-harness` | 어떤 스킬/순서가 맞는지 먼저 판정해야 할 때 쓰는 단일 진입점. |
+| 신규 제품/아이디어 | `/gstack-office-hours` → `/gstack-autoplan` → `/superpowers:writing-plans` → `/tfx-auto` | 먼저 문제/범위를 잡고, 리뷰된 계획을 실행으로 넘긴다. |
+| 기존 작업 계속 | `/gstack-context-restore` → `/tfx-auto` | 저장된 맥락을 복원한 뒤 실행한다. |
+| 직접 구현/수정 | `/tfx-auto` (Codex 우선) | "이거 고쳐줘", "구현해줘". 기존 작업 연장이면 `/gstack-context-restore` 먼저. |
+| 디버그 | Claude 기본 Explore 에이전트 → `/superpowers:systematic-debugging` → `/tfx-auto` | 코드 위치/사용처 확인과 원인 분석을 분리한다. |
+| 리서치 | `/tfx-research` 또는 `/multilingual-parallel-research` | 외부/최신/도구 가능 여부 의문문은 `/tfx-research`; 언어권 병렬 조사는 multilingual 경로. |
+| 검증 | `/superpowers:requesting-code-review` + `/gstack-qa` + `/superpowers:verification-before-completion` | 코드 판정은 review, 브라우저/워크플로우 게이트는 qa, 완료 주장 전 evidence 수집은 verification. |
+| 디자인 검토 | `/gstack-design-review` | 시각/UX 판정. 코드 판정과 분리. |
+| TDD 시작 | `/superpowers:test-driven-development` | 테스트부터 짜는 흐름. 구현 전에 invoke. |
+| 코드 변경 병렬 실행 | 작업별 worktree와 세션을 분리하고 각 세션에서 `/tfx-auto` 실행 | Claude Agent는 `isolation: worktree` 사용 가능. |
+| 병렬 작업 (read-only) | `/tfx-auto --parallel N --mode deep` 또는 `/superpowers:dispatching-parallel-agents` | cwd 공유가 가능한 read-only 병렬. 코드 변경은 작업별 worktree를 분리. |
+| plan 실행 (체크포인트 별도) | `/superpowers:executing-plans` | 다른 세션에서 plan 을 단계별 실행. |
+| 머지 직전 정리 | `/superpowers:finishing-a-development-branch` → `/tfx-ship` 또는 `/gstack-ship` | merge/PR/cleanup 결정 후 ship. |
+| 리뷰 응답 | `/superpowers:receiving-code-review` | 검토 의견에 기술적 rigor 로 응답. blind apply 금지. |
+| triflux 릴리즈 | `/tfx-ship` | triflux 본체는 AI trailer 금지 정책이 있는 전용 ship 경로를 쓴다. |
+| 일반 PR/배포 | `/gstack-ship` | 로컬 `/gstack-ship`도 AI attribution footer/trailer 없이 실행되어야 한다. |
+| 저장/복원 | `/gstack-context-save` / `/gstack-context-restore` | 진행 상태는 gstack checkpoint 계열이 소유한다. |
+| 회고/슬롭 정리 | `/gstack-retro` 또는 명시 `tfx-auto --mode consensus` | 세션 회고는 gstack, 무수식 AI slop/deslop은 host ai-slop-cleaner, TFX 3자 cleanup만 `tfx-auto --mode consensus`. |
+
+## 스킬 선택 결정트리 (SSOT)
+
+우선순위는 **명시 스킬/플래그 > D0-D11 결정트리 > 위 quick reference > 개별 description**이다. 위 표는 파생 참조이며 충돌하면 이 결정트리가 이긴다.
+
+- D0: 명시 `/skill`, `$skill`, `tfx-*`, `--mode/--cli`는 안전 위반이 없으면 유지한다.
+- D1: “어떤 스킬/경로?”만 묻는 요청은 `tfx-harness`가 recommendation-only로 owner 하나를 반환한다.
+- D2: 목표·non-goal·acceptance criteria가 불명확하면 host `deep-interview`; 자연어 목표의 `/goal` 변환은 Claude Code 기본 `/goal`을 쓴다.
+- D3: 제품 수요·wedge 단계는 `office-hours`; D4 해법/UX 발산은 `brainstorming`.
+- D5: 승인된 spec의 실행 계획은 superpowers `writing-plans`; 명시 TFX 다중모델 계획·실행은 `tfx-auto --mode deep`.
+- D6: 실패/버그/test failure는 `systematic-debugging` 후 `tfx-auto`; 정상 구조 설명은 `tfx-auto --mode consensus --shape panel`.
+- D7: 로컬 파일·심볼은 Claude 기본 Explore 에이전트(스킬 없음); 외부·최신·공식 문서는 `tfx-research`.
+- D8: 무수식 AI slop/deslop/refactor는 host `ai-slop-cleaner`; 명시 TFX 3자 cleanup만 `tfx-auto --mode consensus`; 회고는 `retro`. “정리” 한 단어로 cleanup을 강제하지 않는다.
+- D9: web/app flow는 `qa`; code verdict는 review backend; 완료 주장은 `verification-before-completion`이 필수다.
+- D10: 명확한 직접 구현은 TDD 필요 여부 뒤 `tfx-auto`; 2+ code-changing lane은 worktree와 세션을 각각 분리.
+- D11: fresh verification 없이 ship 금지. triflux release는 `tfx-ship`, 일반 release는 `ship`, 중단/재개는 context save/restore.
+
+owner availability를 실제로 검출한 경우에만 `owner unavailable → tfx-X fallback`을 명시해 fallback할 수 있다. availability가 unknown이면 추측 fallback하지 않는다.
+
+## 행동 유형 → 스킬 매핑
+
+| 의도 | 자연어 신호 | 스킬 |
+|------|-----------|------|
+| 리드 운영 | 리드 맡아, 세션들 지휘, 워커 띄워서 조율, 승계·머지·릴리스 조율 | tfx-lead |
+| 구현/수정 | 만들어, 고쳐, 구현해, 짜줘, 수정해, 바꿔 | tfx-auto |
+| 리뷰 | 봐줘, 리뷰해, 검토해, 괜찮아? | `superpowers:requesting-code-review` (owner). 교차모델 판정이 필요할 때만 tfx-review |
+| 분석 | 분석해, 어떻게 돌아가?, 구조가 뭐야 | tfx-auto (`--mode consensus --shape panel`) |
+| 계획 | 계획, 어떻게 하지, 설계해 | superpowers `writing-plans`; TFX 다중모델 계획·실행은 `tfx-auto --mode deep` |
+| 요구사항 명확화 | 요구사항, 인터뷰, 목표 구체화 | host `deep-interview`; 목표 변환은 Claude Code 기본 `/goal` |
+| Codex 프로필 관리 | 프로필, 모델, effort 변경 | `~/.codex/<프로필>.config.toml` 직접 관리 |
+| 검색 | 찾아, 어디있어, 파일 찾아 | Claude 기본 Explore 에이전트 |
+| 리서치 (빠른) | 검색해줘, 찾아봐, 공식문서, 이거 뭐야 | tfx-research |
+| 리서치 (자율) | 자율 리서치, 검색하고 정리해, research and plan | tfx-research (Auto 모드) |
+| 테스트 | 테스트, 검증, 돌려봐, QA | 코드 판정은 tfx-review, 테스트→수정 반복은 tfx-auto, 브라우저 흐름은 gstack `/gstack-qa` |
+| 정리 | 대상 domain을 먼저 판정; 무수식 AI slop/deslop은 host ai-slop-cleaner | D8 참조 (명시 TFX 3자 cleanup만 `tfx-auto --mode consensus`) |
+| 토론/비교 | 뭐가 나을까, 비교해, A vs B | tfx-auto (`--mode consensus --shape debate`) |
+| 합의 | 합의로 분석해, 3자 합의, consensus | tfx-auto (`--mode consensus`) |
+| 패널 | panel, 패널, 전문가 의견, expert panel | tfx-auto (`--mode consensus --shape panel`) |
+
+위 표는 Claude가 요청을 읽고 스킬을 고를 때 쓰는 지도다. 자동 키워드 주입은 [ADR-0023](../../docs/adr/0023-remove-command-hooks-hub-and-adopt-mods.md)에 따라 제거한다. 명시적 스킬 호출은 해당 스킬의 설치 여부와 호출 문법을 확인한다.
+
+## 깊이 수정자
+
+| 수정자 | 신호 | 효과 |
+|--------|------|------|
+| 기본 | (없음), 빠르게, 간단히 | Light 스킬 |
+| 깊이 | 제대로, 꼼꼼히, 철저히 | `tfx-auto --mode deep` |
+| 합의 | 3자, 교차, 다각도 | `tfx-auto --mode consensus` |
+| 반복 | 끝까지, 멈추지마, ralph | `--retry ralph` (Phase 3 true state machine, `.claude/rules/tfx-escalation-chain.md` 참조) |
+| 승격 | 알아서 승격, 안 되면 더 강한 모델 | `--retry auto-escalate` (Phase 3 CLI 체인 승격) |
+| 자율 | 알아서, 자동으로, autopilot | autopilot 모드 |
+| 최대 effort | ultracode, 울트라코드 | Claude Code `--effort ultracode`(v2.1.203+). 멀티에이전트 Workflow 오케스트레이션, 토큰 비용 무관 철저성 우선. tfx CLI 플래그는 아니다 |
+
+## CLI 우선순위 정책: default = Codex
+
+> 근거(why): [ADR-0004: 기본 구현 CLI = Codex](../../docs/adr/0004-codex-as-default-cli.md). 이 절이 SSOT(어떻게), ADR은 결정 이력(왜).
+
+triflux 본체 개발의 실측 운영 패턴 (v10.18.0 ~ v10.20.2, 2주, 25+ PR) 이 거의 전부 Codex 단독 또는 Codex worker spawn 으로 진행되었다. 이 운영 fact 를 default policy 로 명시한다.
+
+| 우선순위 | CLI / 모델 | default 적용 lane |
+|---------|-----------|-------------------|
+| 1차 (default) | **Codex** (프로필 설정 기준) | 구현, 수정, 디버그, 리뷰, 분석, 테스트 작성, 회귀 가드, 릴리즈 prepare |
+| 2차 | **Antigravity** | Codex quota exhaust, 가독성 cross-check, 별도 시각 검토 |
+| 한정 (Claude 만) | **Claude** (`opus` 최신 tier 별칭) | 메타 라우팅 (`/tfx-harness`), planning gate (`/gstack-office-hours`, `/gstack-autoplan`), gstack-specific surface (`/gstack-context-*`, `/gstack-qa`), 또는 Codex/Antigravity 미가용 |
+
+`tfx-auto`, `tfx-review`, `tfx-research` 등 multi-CLI wrapper 는 이 정책을 따른다. 명시 플래그 (`--cli claude`, `--cli codex`) 가 있으면 override. `--mode consensus` (3-CLI 합의) 도 default head 는 Codex.
+
+`--retry auto-escalate` 체인 (`.claude/rules/tfx-escalation-chain.md`) 의 1단계가 Codex 인 것도 이 정책과 정합한다 (2단계 Claude `fable` 최신 tier 별칭은 최종 수단).
+
+### 모델 배치
+
+> 근거(why): [ADR-0016](../../docs/adr/0016-codex-astra-top-tier-and-fable-escalation.md), [ADR-0017](../../docs/adr/0017-gpt6-sol-luna-lanes.md), [ADR-0019](../../docs/adr/0019-gpt61-sol-and-sonnet-55.md). 기준 문서는 OpenAI Codex 모델 페이지와 Anthropic 모델 개요(2026-09-30 확인)다.
+
+Codex 역할별 프로필의 SSOT는 `scripts/lib/agent-route-policy.mjs`이고, 모델 ID는 `~/.codex/<프로필>.config.toml`이 정한다. `designer`, `writer` 항목은 직접 Codex를 지정한 경우에만 적용하며 일반 실행의 provider는 `hub/team/agent-map.json`이 정한다.
+
+| 프로필 | triflux lane |
+|---------|--------------|
+| `gpt6_astra_xhigh` | architect, planner, critic, analyst, debugger, deep-executor, security-reviewer, scientist-deep, designer(직접 지정) |
+| `gpt6_astra_max` / `gpt6_astra_ultra` | `TFX_CODEX_PROFILE=max/ultra`, 재시도 1단계 |
+| `gpt61_sol_high` | executor, codex, code-reviewer, quality-reviewer, verifier, test-engineer, qa-tester, scientist, document-specialist |
+| `gpt61_sol_med` | cleanup, deslop |
+| `gpt6_luna_high` | build-fixer, writer(직접 지정) |
+| `gpt6_luna_low` | spark, explore 재매핑, ChatGPT tier 폴백 |
+| `fable` | `--retry auto-escalate` 최종 단계 |
+| `opus` | 메타 라우팅, planning gate, 스킬의 `model="opus"` lane |
+| `sonnet` | Claude native test-engineer, qa-tester, verifier |
+| `haiku` | Claude native explore, claude |
+
+## CLI 라우팅
+
+`codex exec` / `agy -y -p` 직접 호출은 금지한다. tfx 스킬 경유 필수. 자동 차단 훅(headless-guard)은 제거되었으므로 호출자가 지킨다.
+
+**Layer 1: Light** (tfx-route.sh → 단일 CLI)
+
+| 경로 | CLI | 용도 |
+|------|-----|------|
+| `tfx-auto` | 자동 | 통합 진입점 |
+| `tfx-auto --cli codex` | Codex | Codex 전용 lane |
+| `tfx-auto --cli antigravity` | Antigravity | Antigravity 전용 lane |
+| `tfx-auto --mode quick` | Codex→검증 | 단일 파일, 5분 이내 |
+| `tfx-auto --retry auto-escalate` | 자동 승격 | 실패→더 강한 모델 |
+
+**Layer 2: Deep** (headless 3-CLI 합의)
+
+`tfx-auto --mode deep`, `tfx-auto --mode consensus --shape consensus|debate|panel`,
+`tfx-auto --retry ralph`
+
+**Layer 3: Remote/병렬**
+
+| 스킬 | 용도 |
+|------|------|
+| `tfx multi` CLI | 2+개 태스크 headless 병렬 |
+| tfx-remote | Claude Code 원격 세션 (SSH, user-state hosts.json setup 필수) |
+
+**Claude 네이티브** (CLI 불필요): tfx-setup, tfx-doctor
+
+**Headless UI default** : `tfx-auto`, `tfx multi`의 headless 워커는 default 로 `claude agents` 패널에 노출 (`--native-bridge-ui agents`). opt-out: `--no-native-bridge-ui`. interactive (tmux/wt) 경로는 default-off. 행에서 Enter 를 누르면 워커가 도는 tmux pane 이 열린다. 상세 행동표는 `CLAUDE.md` 의 `<native-bridge>` 섹션. 근거(why): [ADR-0008 : headless 워커 native-bridge 기본 노출](../../docs/adr/0008-native-bridge-ui-default-on.md), [ADR-0026 : agents 행을 워커 tmux 방의 attach client 로](../../docs/adr/0026-agents-row-tmux-attach.md).
+
+자원 우선순위: remote-spawn > multi > Light > 로컬 단독
+
+**원격 오프로드 기본 정책** : 로컬 기기의 램이 빠듯해지면 무거운 작업을 `hosts.json` 에 등록한 원격 호스트로 넘긴다. 판단 시점은 병렬 dispatch 직전이다.
+
+- 판정 명령: `sysctl -n kern.memorystatus_vm_pressure_level` (1=normal, 2=warn, 4=critical; Stats 앱·활성 상태 보기의 메모리 색과 같은 커널 신호, 노랑=2 빨강=4)
+- 4(critical): 무조건 오프로드
+- 2(warn): 무거운 shard(빌드·전체 테스트 스위트·대규모 리팩터)를 띄우거나 워커 3+개를 새로 만들 때만 오프로드
+- 1(normal): 로컬 유지
+- sysctl 실패 시 대체 신호: `vm_stat` 5초 간격 2회 측정에서 swapouts 증가
+- 원격으로 넘기기 전에 `node scripts/remote-spawn.mjs --probe <host>`로 호스트 상태를 먼저 확인한다.
+- 행동: 원격 코드 변경은 별도 worktree와 세션에서 실행한다. 탐색·대화형은 tfx-remote로 원격 세션을 띄운다
+- 로컬 여유가 충분하면 로컬 유지. 사용자가 로컬/원격을 명시하면 그에 따른다
+- 원격 호스트 부재 시(ssh 불응) 조용히 로컬로 강등하지 말고 한 줄 알린 뒤 로컬 진행
+
+원격 hosts 설정은 user-state 경로만 참조한다: macOS/Linux `~/.config/triflux/hosts.json`, Windows `%APPDATA%\triflux\hosts.json`. 기존 source-tree `references/hosts.json` 은 라우팅 입력으로 사용하지 않으며 첫 실행 lazy auto-migration 대상이다.
+
+## 충돌 해소
+
+- ralph = persist alias
+- "auto" 단독 → tfx-auto. "알아서 해" → autopilot 모드 (위 깊이 수정자)
+- "코드에서 찾아" → Claude 기본 Explore 에이전트. "알아봐" → tfx-research
+- 복합 의도: "구현하고 리뷰까지" → tfx-auto 실행 후 리뷰 결과 확인
+- "합의해서 비교해" 류 요청은 기본적으로 `tfx-auto --mode consensus --shape debate` 로 fold 한다
+- `ralph` 표기는 항상 `--retry ralph` mode 를 지칭. persist 스킬도 동일 의미. `--retry auto-escalate` 와 동시 사용 불가 (escalation-chain.md 규약).
+- 코드 변경 병렬 작업은 작업별 worktree와 세션을 분리하고 각 세션에서 `tfx-auto`로 실행한다.

package/adapters/codex/skills/tfx-harness/SKILL.md

@@ -15,24 +15,26 @@ tree, keyword rules, or owner matrix into this file.
 ## Locate the routing SSOT
 
 This skill is installed globally but the SSOT belongs to the Triflux project.
-Try these locations in order and return blocked only when all three fail:
+Try these locations in order and return blocked only when all four fail:
 
 1. `$TFX_ROUTING_SSOT`, when set.
 2. `.claude/rules/tfx-routing.md` below the main Git worktree, derived from
    the parent of `git rev-parse --git-common-dir`.
 3. Walk upward from the current working directory looking for
    `.claude/rules/tfx-routing.md`.
+4. `references/tfx-routing.md` inside this skill directory, copied from the
+   package by `tfx setup`. It serves machines without a clone and may lag the
+   clone, so it comes last.
 
 Do not use `git rev-parse --show-toplevel` for step 2. In a linked worktree it
 returns that worktree root, whose SSOT may be a stale branch snapshot.
 `--git-common-dir` still points to the main repository's `.git` directory.
 
-When blocked, include this one-line remedy:
-
-`export TFX_ROUTING_SSOT=<triflux clone>/.claude/rules/tfx-routing.md`
-
-Prefer `~/.zshenv` for this variable because hooks and headless workers may not
-load interactive `~/.zshrc`. Do not create a global copy or symlink under
+When blocked, include this one-line remedy: rerun `tfx setup` to install the
+step 4 copy. To follow a clone's latest policy instead, set
+`export TFX_ROUTING_SSOT=<triflux clone>/.claude/rules/tfx-routing.md` in
+`~/.zshenv`, because hooks and headless workers may not load interactive
+`~/.zshrc`. Do not create a global copy or symlink under
 `~/.claude/rules/`; Claude auto-loads that directory into unrelated sessions.
 
 ## Return contract

package/bin/triflux.mjs

@@ -74,6 +74,7 @@ import {
   listInlineProfileNames,
   MODS_UPDATE_COMMAND,
   persistSettings,
+  planStatusLine,
   REQUIRED_CODEX_PROFILES,
   retireOldInstallFiles,
   runConsentSteps,
@@ -1139,11 +1140,11 @@ function previewStatusLineAction() {
   return {
     type: "statusLine",
     path: settingsPath,
-    change: currentCmd.includes("hud-qos-status.mjs")
-      ? "noop"
-      : currentCmd
-        ? "skip"
-        : "create",
+    // setup 은 statusLine 을 다루기 전에 HUD 파일(래퍼 포함)을 먼저 복사한다.
+    change: planStatusLine(settings, {
+      hudPath,
+      willSyncWrapper: existsSync(join(PKG_ROOT, "hud", "hud-statusline.sh")),
+    }),
     current: currentCmd || null,
     target: hudPath,
   };

package/hud/constants.mjs

@@ -17,6 +17,8 @@ export const CLAUDE_BAND_MARKER_DIR = join(
 export const BAND_FLAG = "--band";
 export const BAND_HEADER = "tfx-band 1";
 export const BAND_ALL_TTL_MS = 3 * 60 * 1000;
+// 양옆 여백 4칸과 첫 행 오른쪽 알림 자리 30칸.
+export const STATUSLINE_RESERVE_COLS = 34;
 export const CLAUDE_BAND_MARKER_TTL_MS = 12 * 60 * 60 * 1000;
 
 export const CONTEXT_MONITOR_CACHE_PATH = join(

package/hud/hud-qos-status.mjs

@@ -24,6 +24,7 @@ import {
   CODEX_REFRESH_FLAG,
   getCodexAuthPath,
   getCodexHome,
+  STATUSLINE_RESERVE_COLS,
 } from "./constants.mjs";
 import { buildContextUsageView } from "./context-monitor.mjs";
 import {
@@ -69,11 +70,15 @@ async function main() {
 
   // --band: triflux mods 가 입력창 위에 그릴 줄을 만든다. statusLine 은 band 가 다 그리는 세션에서 비운다.
   const bandMode = process.argv.includes(BAND_FLAG);
+  // statusLine 은 엔진이 양옆에 2칸씩 여백을 두고, 첫 행 오른쪽에 알림을 띄운다(공식 문서). 그만큼 좁게 그린다.
+  // 알림 자리를 빼고 40칸이 안 남는 좁은 화면은 그대로 두어 원래 축소 단계를 따른다.
+  const reserved = Number(process.env.COLUMNS) - STATUSLINE_RESERVE_COLS;
+  if (!bandMode && reserved >= 40) process.env.COLUMNS = String(reserved);
   const stdin = await readStdinJson();
   const bandState = bandMode ? "none" : readBandState(stdin?.session_id);
   if (bandState === "all") return;
-  // mods 가 넘긴 세션 사용량이 있으면 Claude API 를 따로 조회하지 않는다.
-  const bandClaudeUsage = claudeUsageFromRateLimits(stdin?.claude_rate_limits);
+  // Claude Code 가 넘긴 세션 사용량이 있으면 Claude API 를 따로 조회하지 않는다.
+  const stdinClaudeUsage = claudeUsageFromStdin(stdin);
 
   const { showCodex, antigravityAllowed } = resolveHudCliVisibility();
   const claudeUsageSnapshot = readClaudeUsageSnapshot();
@@ -84,7 +89,7 @@ async function main() {
   if (antigravitySnapshot?.shouldRefresh) scheduleAntigravityQuotaRefresh();
   // 설정이 없는 홈에서는 갱신 프로세스를 시작하지 않는다.
   if (
-    !bandClaudeUsage &&
+    !stdinClaudeUsage &&
     claudeUsageSnapshot.shouldRefresh &&
     existsSync(join(homedir(), ".claude"))
   ) {
@@ -96,7 +101,7 @@ async function main() {
 
   const contextView = buildContextUsageView(stdin);
   const claudeUsage =
-    bandClaudeUsage ??
+    stdinClaudeUsage ??
     (claudeUsageSnapshot.data
       ? { ...claudeUsageSnapshot.data, stale: claudeUsageSnapshot.isStale }
       : null);
@@ -123,7 +128,12 @@ async function main() {
   const rows =
     bandState === "claude"
       ? []
-      : getClaudeRows(currentTier, contextView, claudeUsage);
+      : getClaudeRows(
+          currentTier,
+          contextView,
+          claudeUsage,
+          Number(stdin?.cost?.total_cost_usd ?? Number.NaN),
+        );
   let codexRowIndex = -1;
   if (showCodex) {
     codexRowIndex = rows.length;
@@ -191,16 +201,30 @@ function readBandState(sessionId) {
   }
 }
 
-// mods 의 $.session.usage() rateLimits 를 HUD 의 Claude 사용량 형식으로 바꾼다.
-function claudeUsageFromRateLimits(rateLimits) {
-  if (!Array.isArray(rateLimits)) return null;
-  const find = (kind) => rateLimits.find((w) => w?.kind === kind);
-  const fiveHour = find("five_hour");
-  const weekly = find("seven_day");
-  const spendLimit = find("spend_limit");
+// statusLine 입력의 rate_limits(Claude Code 2.1.251+, Pro/Max 와 gateway)를 HUD 의 Claude 사용량 형식으로 바꾼다.
+// 10.57.0 mods 가 넘기던 claude_rate_limits 배열도 받는다.
+function claudeUsageFromStdin(stdin) {
+  const windows = {};
+  const limits = stdin?.rate_limits;
+  if (limits && typeof limits === "object" && !Array.isArray(limits)) {
+    for (const kind of ["five_hour", "seven_day", "spend_limit"]) {
+      const w = limits[kind];
+      if (w)
+        windows[kind] = { percent: w.used_percentage, resetsAt: w.resets_at };
+    }
+  } else if (Array.isArray(stdin?.claude_rate_limits)) {
+    for (const w of stdin.claude_rate_limits)
+      if (w?.kind)
+        windows[w.kind] = { percent: w.percentUsed, resetsAt: w.resetsAt };
+  }
+  const {
+    five_hour: fiveHour,
+    seven_day: weekly,
+    spend_limit: spendLimit,
+  } = windows;
   if (!fiveHour && !weekly && !spendLimit) return null;
   const percent = (w) =>
-    Number.isFinite(w?.percentUsed) ? Math.round(w.percentUsed) : null;
+    Number.isFinite(w?.percent) ? Math.round(w.percent) : null;
   return {
     fiveHourPercent: percent(fiveHour),
     weeklyPercent: percent(weekly),

package/hud/hud-statusline.sh

@@ -0,0 +1,15 @@
+#!/bin/sh
+# statusLine 진입점. triflux mods band 가 HUD 를 입력창 위에 그리는 세션이면 node 를 띄우지 않고 끝낸다.
+# band 는 1분마다 표식에 "all:<시각>" 을 다시 쓰므로, 3분 넘게 멈췄거나 표식이 없으면 HUD 를 그대로 돌린다.
+# 인자 1: node 실행 파일(없으면 PATH 의 node).
+# Claude Code 는 입력을 닫아 주지만, 닫히지 않아도 1초 뒤에는 읽기를 끝낸다.
+# 백그라운드 명령은 stdin 이 /dev/null 로 바뀌므로 fd 3 으로 넘긴다.
+exec 3<&0
+input=$({ cat <&3 & cat_pid=$!; (sleep 1; kill "$cat_pid" 2>/dev/null) >/dev/null 2>&1 & wait "$cat_pid"; })
+exec 3<&-
+sid=$(printf '%s' "$input" | sed -n 's/.*"session_id"[[:space:]]*:[[:space:]]*"\([A-Za-z0-9_-]*\)".*/\1/p' | head -n 1)
+marker="$HOME/.claude/cache/triflux/claude-band/$sid"
+if [ -n "$sid" ] && [ -f "$marker" ] && [ -n "$(find "$marker" -mmin -3 2>/dev/null)" ]; then
+  case "$(head -c 4 "$marker")" in all:) exit 0 ;; esac
+fi
+printf '%s' "$input" | "${1:-node}" "$(dirname "$0")/hud-qos-status.mjs"

package/hud/providers/claude.mjs

@@ -26,8 +26,10 @@ import {
   SPAWN_LOCK_TTL_MS,
 } from "../constants.mjs";
 import {
+  acquireSpawnLock,
   advanceToNextCycle,
   clampPercent,
+  parseRetryAfterMs,
   readJson,
   writeJsonSafe,
 } from "../utils.mjs";
@@ -77,10 +79,27 @@ export function computeClaudeUsagePollState({
   };
 }
 
+// 서버가 Retry-After 로 더 기다리라고 하면 따르되, 잘못된 큰 값에 오래 묶이지 않게 1시간에서 자른다.
+const MAX_RETRY_AFTER_MS = 60 * 60 * 1000;
+function withRetryAfter(pollState, retryAfterMs) {
+  if (!retryAfterMs) return pollState;
+  return {
+    ...pollState,
+    delayMs: Math.max(
+      pollState.delayMs,
+      Math.min(retryAfterMs, MAX_RETRY_AFTER_MS),
+    ),
+  };
+}
+
 function getSnapshotSchedule(cache) {
   const timestamp = Number(cache?.timestamp);
   const nextRefreshAt = Number(cache?.nextRefreshAt);
-  if (Number.isFinite(nextRefreshAt)) {
+  // 다음 갱신이 상한보다 멀면 시계가 뒤로 간 것이다. 그대로 두면 갱신이 오래 멈춘다.
+  if (
+    Number.isFinite(nextRefreshAt) &&
+    nextRefreshAt - Date.now() <= MAX_RETRY_AFTER_MS
+  ) {
     return {
       nextRefreshAt,
       shouldRefresh: Date.now() >= nextRefreshAt,
@@ -448,7 +467,11 @@ export function fetchClaudeUsageFromApi(accessToken) {
               resolve({ ok: false, status: 0 });
             }
           } else {
-            resolve({ ok: false, status: res.statusCode });
+            resolve({
+              ok: false,
+              status: res.statusCode,
+              retryAfterMs: parseRetryAfterMs(res.headers?.["retry-after"]),
+            });
           }
         });
       },
@@ -674,10 +697,13 @@ export async function fetchClaudeUsage(forceRefresh = false) {
             : "unknown";
     const pollState =
       errorType === "rate_limit"
-        ? computeClaudeUsagePollState({
-            consecutive429s,
-            outcome: "rate_limit",
-          })
+        ? withRetryAfter(
+            computeClaudeUsagePollState({
+              consecutive429s,
+              outcome: "rate_limit",
+            }),
+            result.retryAfterMs,
+          )
         : null;
     writeClaudeUsageCache(
       existingSnapshot.data,
@@ -720,11 +746,7 @@ export function scheduleClaudeUsageRefresh() {
 
   // 스폰 락: 30초 내 이미 스폰했으면 중복 방지 (첫 설치 시 429 방지)
   try {
-    if (existsSync(CLAUDE_REFRESH_LOCK_PATH)) {
-      const lockAge = Date.now() - readJson(CLAUDE_REFRESH_LOCK_PATH, {}).t;
-      if (lockAge < SPAWN_LOCK_TTL_MS) return;
-    }
-    writeJsonSafe(CLAUDE_REFRESH_LOCK_PATH, { t: Date.now() });
+    if (!acquireSpawnLock(CLAUDE_REFRESH_LOCK_PATH, SPAWN_LOCK_TTL_MS)) return;
   } catch {
     /* 락 실패 무시 — 스폰 진행 */
   }

package/hud/providers/codex.mjs

@@ -26,7 +26,12 @@ import {
   getCodexHome,
   SPAWN_LOCK_TTL_MS,
 } from "../constants.mjs";
-import { decodeJwtEmail, readJson, writeJsonSafe } from "../utils.mjs";
+import {
+  acquireSpawnLock,
+  decodeJwtEmail,
+  readJson,
+  writeJsonSafe,
+} from "../utils.mjs";
 import {
   listProbeTargets,
   probeRateLimitsViaAppServer,
@@ -552,11 +557,7 @@ export function scheduleCodexRateLimitRefresh() {
 
   // 스폰 락: 30초 내 이미 스폰했으면 중복 방지
   try {
-    if (existsSync(CODEX_REFRESH_LOCK_PATH)) {
-      const lockAge = Date.now() - readJson(CODEX_REFRESH_LOCK_PATH, {}).t;
-      if (lockAge < SPAWN_LOCK_TTL_MS) return;
-    }
-    writeJsonSafe(CODEX_REFRESH_LOCK_PATH, { t: Date.now() });
+    if (!acquireSpawnLock(CODEX_REFRESH_LOCK_PATH, SPAWN_LOCK_TTL_MS)) return;
   } catch {
     /* 락 실패 무시 — 스폰 진행 */
   }

package/hud/providers/gemini.mjs

@@ -10,7 +10,12 @@ import {
   ANTIGRAVITY_SIGNED_IN_GRACE_MS,
   SPAWN_LOCK_TTL_MS,
 } from "../constants.mjs";
-import { decodeJwtEmail, readJson, writeJsonSafe } from "../utils.mjs";
+import {
+  acquireSpawnLock,
+  decodeJwtEmail,
+  readJson,
+  writeJsonSafe,
+} from "../utils.mjs";
 
 function getCredentialEmail(credential) {
   return (
@@ -140,9 +145,8 @@ export function scheduleAntigravityQuotaRefresh() {
     isGcpProjectAuth()
   )
     return;
-  const lock = readJson(ANTIGRAVITY_REFRESH_LOCK_PATH, null);
-  if (Date.now() - Number(lock?.t || 0) < SPAWN_LOCK_TTL_MS) return;
-  writeJsonSafe(ANTIGRAVITY_REFRESH_LOCK_PATH, { t: Date.now() });
+  if (!acquireSpawnLock(ANTIGRAVITY_REFRESH_LOCK_PATH, SPAWN_LOCK_TTL_MS))
+    return;
   try {
     const child = spawn(
       process.execPath,

package/hud/renderers.mjs

@@ -177,9 +177,20 @@ function spendOnlyPercent(claudeUsage) {
 // ============================================================================
 // Claude 행 렌더러
 // ============================================================================
-export function getClaudeRows(currentTier, contextView, claudeUsage) {
+export function getClaudeRows(
+  currentTier,
+  contextView,
+  claudeUsage,
+  costUsd = null,
+) {
   const ctxView = contextView || buildContextUsageView({});
   const prefix = `${bold(claudeOrange("c"))}:`;
+  // 이번 세션 비용. 폭이 넉넉한 full, compact 에서만 CTX 뒤에 붙인다.
+  const costText =
+    Number.isFinite(costUsd) &&
+    (currentTier === "full" || currentTier === "compact")
+      ? ` ${dim(`$${costUsd.toFixed(2)}`)}`
+      : "";
   const spend = spendOnlyPercent(claudeUsage);
   if (spend != null) {
     if (currentTier === "nano" || currentTier === "micro") {
@@ -188,7 +199,7 @@ export function getClaudeRows(currentTier, contextView, claudeUsage) {
     }
     const pct = colorByProvider(spend, formatPercentCell(spend), claudeOrange);
     const left = `${dim("$:")}${tierBar(currentTier, spend, CLAUDE_ORANGE)}${pct}`;
-    const right = `${dim("CTX:")}${contextPercentText(ctxView)}`;
+    const right = `${dim("CTX:")}${contextPercentText(ctxView)}${costText}`;
     return [{ prefix, left, right }];
   }
   // API 실측 데이터
@@ -256,7 +267,7 @@ export function getClaudeRows(currentTier, contextView, claudeUsage) {
     const warning = ctxView.warningTag
       ? ` ${dim("|")} ${yellow(ctxView.warningTag)}`
       : "";
-    const contextSection = `${dim("CTX:")}${contextPercentText(ctxView)}${warning}`;
+    const contextSection = `${dim("CTX:")}${contextPercentText(ctxView)}${costText}${warning}`;
     return [{ prefix, left: quotaSection, right: contextSection }];
   }
 
@@ -266,7 +277,7 @@ export function getClaudeRows(currentTier, contextView, claudeUsage) {
   const warning = ctxView.warningTag
     ? ` ${dim("|")} ${yellow(ctxView.warningTag)}`
     : "";
-  const contextSection = `${dim("CTX:")}${contextPercentText(ctxView)}${warning}`;
+  const contextSection = `${dim("CTX:")}${contextPercentText(ctxView)}${costText}${warning}`;
   return [{ prefix, left: quotaSection, right: contextSection }];
 }
 

package/hud/utils.mjs

@@ -7,32 +7,40 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
 import { PERCENT_CELL_WIDTH, TIME_CELL_INNER_WIDTH } from "./constants.mjs";
 
+const STDIN_MAX_BYTES = 1024 * 1024;
+
+// 입력이 JSON 으로 읽히는 순간 끝낸다. Claude Code 가 stdin 을 늦게 닫아도 기다리지 않는다.
 export async function readStdinJson() {
   if (process.stdin.isTTY) return {};
   return new Promise((resolve) => {
-    const timeout = setTimeout(() => {
-      process.stdin.destroy();
-      resolve({});
-    }, 200);
-    const chunks = [];
-    process.stdin.on("data", (chunk) => chunks.push(chunk));
-    process.stdin.on("end", () => {
+    let raw = "";
+    let done = false;
+    const finish = (value) => {
+      if (done) return;
+      done = true;
       clearTimeout(timeout);
-      const raw = chunks.join("").trim();
-      if (!raw) {
-        resolve({});
-        return;
-      }
+      process.stdin.removeAllListeners("data");
+      process.stdin.destroy();
+      resolve(value);
+    };
+    const tryParse = () => {
       try {
-        resolve(JSON.parse(raw));
+        return JSON.parse(raw);
       } catch {
-        resolve({});
+        return null;
       }
+    };
+    // 200ms 안에 다 못 받으면 받은 만큼으로 판정한다.
+    const timeout = setTimeout(() => finish(tryParse() ?? {}), 200);
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk) => {
+      raw += chunk;
+      if (raw.length > STDIN_MAX_BYTES) return finish({});
+      const parsed = tryParse();
+      if (parsed) finish(parsed);
     });
-    process.stdin.on("error", () => {
-      clearTimeout(timeout);
-      resolve({});
-    });
+    process.stdin.on("end", () => finish(tryParse() ?? {}));
+    process.stdin.on("error", () => finish({}));
     process.stdin.resume();
   });
 }
@@ -56,6 +64,28 @@ export function writeJsonSafe(filePath, data) {
 }
 
 // .omc/ → .claude/cache/ 마이그레이션: 새 경로 우선, 없으면 레거시 읽고 복사
+// 갱신 프로세스를 겹쳐 띄우지 않는 락. 만료 시각을 적고, 남은 시간이 ttl 보다 길면(시계가 뒤로 감) 깨진 락으로 본다.
+// 예전 { t } 락도 읽는다.
+export function acquireSpawnLock(lockPath, ttlMs, now = Date.now()) {
+  const lock = readJson(lockPath, null);
+  const until = Number(lock?.until ?? Number(lock?.t) + ttlMs);
+  const remaining = until - now;
+  if (Number.isFinite(remaining) && remaining > 0 && remaining <= ttlMs)
+    return false;
+  writeJsonSafe(lockPath, { until: now + ttlMs });
+  return true;
+}
+
+// Retry-After 헤더(초 또는 HTTP 날짜)를 ms 로 바꾼다. 없거나 지난 값이면 null.
+export function parseRetryAfterMs(value, now = Date.now()) {
+  if (value == null || value === "") return null;
+  const seconds = Number(value);
+  const ms = Number.isFinite(seconds)
+    ? seconds * 1000
+    : Date.parse(value) - now;
+  return Number.isFinite(ms) && ms > 0 ? ms : null;
+}
+
 export function readJsonMigrate(newPath, legacyPath, fallback) {
   const data = readJson(newPath, null);
   if (data != null) return data;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "triflux",
-  "version": "10.57.0",
+  "version": "10.57.2",
   "description": "CLI-first multi-model orchestrator for Claude Code — route tasks to Codex, Antigravity, and Claude",
   "type": "module",
   "bin": {
@@ -23,6 +23,7 @@
     "adapters",
     "bin",
     "config",
+    ".claude/rules/tfx-routing.md",
     "skills",
     "!skills/tfx-workspace",
     "hooks",

package/scripts/release/check-packages-mirror.mjs

@@ -33,6 +33,8 @@ const MIRROR_TOPS = [
   "scripts",
   "skills",
 ];
+// 디렉터리 전체가 아니라 한 파일만 게시하는 경로. tfx-harness 가 clone 없는 기기에서 읽는다.
+const MIRROR_FILES = [".claude/rules/tfx-routing.md"];
 // core 미러 대상은 pack.mjs 의 CORE_ENTRIES 하나로 정한다. 검사기가 따로 손 목록을 두면
 // 하위 디렉터리나 새 파일이 빠져도 OK 가 나왔다(#674).
 const CORE_NON_MIRROR = new Set([
@@ -189,48 +191,55 @@ function compareMirror({
   const issues = [];
   const fixed = [];
 
+  const pairs = [];
   for (const top of MIRROR_TOPS) {
-    const srcDir = join(repoRoot, top);
-    const dstDir = join(mirrorRoot, top);
     const skipRels = SKIP_RELS.get(top) ?? new Set();
-    const srcFiles = new Set(walkRelFiles(srcDir, skipRels));
-    const dstFiles = new Set(walkRelFiles(dstDir, skipRels));
-    const allFiles = new Set([...srcFiles, ...dstFiles]);
+    const srcFiles = new Set(walkRelFiles(join(repoRoot, top), skipRels));
+    const dstFiles = new Set(walkRelFiles(join(mirrorRoot, top), skipRels));
+    for (const rel of new Set([...srcFiles, ...dstFiles]))
+      pairs.push({
+        rel: `${top}/${rel}`,
+        inSrc: srcFiles.has(rel),
+        inDst: dstFiles.has(rel),
+      });
+  }
+  for (const rel of MIRROR_FILES) {
+    const inSrc = existsSync(join(repoRoot, rel));
+    const inDst = existsSync(join(mirrorRoot, rel));
+    if (inSrc || inDst) pairs.push({ rel, inSrc, inDst });
+  }
 
-    for (const rel of allFiles) {
-      const srcPath = join(srcDir, rel);
-      const dstPath = join(dstDir, rel);
-      const inSrc = srcFiles.has(rel);
-      const inDst = dstFiles.has(rel);
-      const displayPath = `packages/triflux/${top}/${rel}`;
+  for (const { rel, inSrc, inDst } of pairs) {
+    const srcPath = join(repoRoot, rel);
+    const dstPath = join(mirrorRoot, rel);
+    const displayPath = `packages/triflux/${rel}`;
 
-      if (inSrc && !inDst) {
-        if (fix) {
-          mkdirSync(dirname(dstPath), { recursive: true });
-          copyFileSync(srcPath, dstPath);
-          fixed.push({ path: displayPath, kind: "added" });
-        } else {
-          issues.push({ path: displayPath, kind: "missing-in-mirror" });
-        }
-        continue;
+    if (inSrc && !inDst) {
+      if (fix) {
+        mkdirSync(dirname(dstPath), { recursive: true });
+        copyFileSync(srcPath, dstPath);
+        fixed.push({ path: displayPath, kind: "added" });
+      } else {
+        issues.push({ path: displayPath, kind: "missing-in-mirror" });
       }
+      continue;
+    }
 
-      if (!inSrc && inDst) {
-        // Orphan in mirror — source of truth is root, mirror must not have
-        // extra files. Do not auto-delete; require manual decision.
-        issues.push({ path: displayPath, kind: "orphan-in-mirror" });
-        continue;
-      }
+    if (!inSrc && inDst) {
+      // Orphan in mirror — source of truth is root, mirror must not have
+      // extra files. Do not auto-delete; require manual decision.
+      issues.push({ path: displayPath, kind: "orphan-in-mirror" });
+      continue;
+    }
 
-      const a = readFileSync(srcPath);
-      const b = readFileSync(dstPath);
-      if (!a.equals(b)) {
-        if (fix) {
-          copyFileSync(srcPath, dstPath);
-          fixed.push({ path: displayPath, kind: "updated" });
-        } else {
-          issues.push({ path: displayPath, kind: "content-diff" });
-        }
+    const a = readFileSync(srcPath);
+    const b = readFileSync(dstPath);
+    if (!a.equals(b)) {
+      if (fix) {
+        copyFileSync(srcPath, dstPath);
+        fixed.push({ path: displayPath, kind: "updated" });
+      } else {
+        issues.push({ path: displayPath, kind: "content-diff" });
       }
     }
   }

package/scripts/setup.mjs

@@ -676,7 +676,7 @@ function installEntries(pluginRoot) {
     "scripts/codex-profile-sanitize.mjs",
     // tfx-route.sh 가 $sd/lib 에서 찾는다.
     ...listFiles(pluginRoot, "scripts/lib", [".mjs", ".sh"]),
-    ...listFiles(pluginRoot, "hud", [".mjs"]),
+    ...listFiles(pluginRoot, "hud", [".mjs", ".sh"]),
   ];
 }
 
@@ -1241,6 +1241,19 @@ function syncCodexManagedSkills({
   }));
 }
 
+// tfx-harness 는 triflux clone 밖에서도 호출된다. clone 이 없는 기기에서도 라우팅 문서를
+// 읽도록 패키지에 든 사본을 설치된 스킬 옆에 둔다. ~/.claude/rules 는 모든 세션이 자동
+// 로드하므로 쓰지 않는다.
+function installRoutingSsot(pluginRoot, skillDir) {
+  const src = join(pluginRoot, ".claude", "rules", "tfx-routing.md");
+  const dst = join(skillDir, "references", "tfx-routing.md");
+  if (!existsSync(src) || !existsSync(join(skillDir, "SKILL.md"))) return false;
+  if (!shouldSyncTextFile(src, dst)) return false;
+  mkdirSync(dirname(dst), { recursive: true });
+  copyFileSync(src, dst);
+  return true;
+}
+
 export function syncSkills({
   pluginRoot = PLUGIN_ROOT,
   claudeDir = CLAUDE_DIR,
@@ -1293,6 +1306,12 @@ export function syncSkills({
     } else if (skill.action === "skipped")
       result.warnings.push(`Codex ${skill.name}: 사용자 스킬 보존`);
   }
+  const harnessDirs = [join(destination, "tfx-harness")];
+  const codexHarness = join(codexDir, "skills", "tfx-harness");
+  if (existsSync(join(codexHarness, MANAGED_CODEX_SKILL_MARKER)))
+    harnessDirs.push(codexHarness);
+  for (const dir of harnessDirs)
+    if (installRoutingSsot(pluginRoot, dir)) result.changed++;
   return result;
 }
 
@@ -1689,35 +1708,71 @@ export function persistSettings(settings, settingsPath = SETTINGS_PATH) {
   }
 }
 
+const HUD_STATUSLINE_SCRIPT = "hud-statusline.sh";
+
+function commandTokens(command) {
+  return [
+    ...String(command || "").matchAll(/"([^"\n]+)"|'([^'\n]+)'|(\S+)/gu),
+  ].map((m) => m[1] ?? m[2] ?? m[3]);
+}
+
+// macOS/Linux 는 sh 래퍼로 돌려 mods band 가 그리는 세션에서 node 를 띄우지 않는다(hud/hud-statusline.sh).
+// willSyncWrapper: 미리보기처럼 래퍼를 아직 복사하기 전이지만 setup 이 곧 복사할 때.
+function buildStatusLineCommand(hudPath, { willSyncWrapper = false } = {}) {
+  const wrapper = join(dirname(hudPath), HUD_STATUSLINE_SCRIPT);
+  if (process.platform === "win32" || !(willSyncWrapper || existsSync(wrapper)))
+    return buildNodeScriptCommand(hudPath);
+  const node = resolveStableNodeBin(process.execPath, { fallback: "node" });
+  return `sh ${quoteShellCommandArg(wrapper)} ${quoteShellCommandArg(node)}`;
+}
+
+// triflux 가 등록한 statusLine 인지: node <hud> 또는 sh <래퍼> <node>.
+function isTrifluxStatusLine(command, hudPath) {
+  const isNode = (bin) => /(?:^|[/\\])node(?:\.exe)?$/u.test(bin ?? "");
+  const tokens = commandTokens(command);
+  const hud = hudPath.replace(/\\/g, "/");
+  const wrapper = join(dirname(hudPath), HUD_STATUSLINE_SCRIPT).replace(
+    /\\/g,
+    "/",
+  );
+  if (tokens.length === 2) return isNode(tokens[0]) && tokens[1] === hud;
+  if (tokens.length === 3)
+    return tokens[0] === "sh" && tokens[1] === wrapper && isNode(tokens[2]);
+  return false;
+}
+
+// 미리보기와 실제 적용이 같은 판정을 쓴다. 사용자가 직접 넣은 statusLine 은 skip 이다.
+export function planStatusLine(
+  settings,
+  { hudPath = HUD_PATH, willSyncWrapper = false } = {},
+) {
+  const current = settings.statusLine;
+  if (current == null) return "create";
+  if (current.command === buildStatusLineCommand(hudPath, { willSyncWrapper }))
+    return "noop";
+  return current.type === "command" &&
+    isTrifluxStatusLine(current.command, hudPath)
+    ? "update"
+    : "skip";
+}
+
 export function applyStatusLine(
   settings,
   { hudPath = HUD_PATH, warn = console.warn } = {},
 ) {
   if (!existsSync(hudPath)) return false;
-  const current = settings.statusLine;
-  const desiredCommand = buildNodeScriptCommand(hudPath);
-  if (current?.command === desiredCommand) return false;
-  if (current != null) {
-    const tokens = String(current.command || "").match(
-      /^(?:"([^"\n]+)"|'([^'\n]+)'|(\S+))\s+(?:"([^"\n]+)"|'([^'\n]+)'|(\S+))$/u,
+  const change = planStatusLine(settings, { hudPath });
+  if (change === "noop") return false;
+  if (change === "skip") {
+    warn(
+      "기존 statusLine 유지: Triflux HUD를 쓰려면 settings.json에서 직접 선택하세요.",
     );
-    const node = tokens?.[1] ?? tokens?.[2] ?? tokens?.[3] ?? "";
-    const script = tokens?.[4] ?? tokens?.[5] ?? tokens?.[6];
-    if (
-      current.type !== "command" ||
-      !/(?:^|[/\\])node(?:\.exe)?$/u.test(node) ||
-      script !== hudPath.replace(/\\/g, "/")
-    ) {
-      warn(
-        "기존 statusLine 유지: Triflux HUD를 쓰려면 settings.json에서 직접 선택하세요.",
-      );
-      return false;
-    }
+    return false;
   }
   settings.statusLine = {
-    ...current,
+    ...settings.statusLine,
     type: "command",
-    command: desiredCommand,
+    command: buildStatusLineCommand(hudPath),
   };
   return true;
 }

package/skills/tfx-harness/SKILL.md

@@ -21,19 +21,22 @@ host capability evidence를 판정한다. 정책 표, keyword 표, owner 매트
 2. git 메인 워크트리 — `$(git rev-parse --git-common-dir)`의 부모 아래
    `.claude/rules/tfx-routing.md`
 3. cwd에서 위로 올라가며 `.claude/rules/tfx-routing.md`
+4. 이 스킬 디렉터리의 `references/tfx-routing.md` (`tfx setup`이 패키지에서 복사한 사본)
+
+4순위는 clone이 없는 기기를 위한 것이다. 설치한 버전의 정책이라 clone보다 늦을 수 있으므로
+1~3순위 뒤에 둔다.
 
 2순위에 `--show-toplevel`을 쓰지 않는다. linked worktree 안에서는 worktree 루트를
 반환하는데 그곳의 SSOT는 브랜치 분기 시점 사본이라, blocked 없이 stale 정책으로
 조용히 오판정한다. `--git-common-dir`은 worktree 안에서도 메인 repo의 `.git`을 가리킨다.
 
-blocked를 반환할 때는 해소 방법을 한 줄 덧붙인다:
-`export TFX_ROUTING_SSOT=<triflux clone>/.claude/rules/tfx-routing.md`
-(`~/.zshrc`가 아니라 `~/.zshenv`에 둔다. zshrc는 interactive 전용이라 훅·headless
-워커·툴 셸에서는 1순위가 통째로 죽는다.)
+blocked를 반환할 때는 해소 방법을 한 줄 덧붙인다: `tfx setup`을 다시 실행해 4순위 사본을 설치한다.
+clone의 최신 정책을 쓰려면 `export TFX_ROUTING_SSOT=<triflux clone>/.claude/rules/tfx-routing.md`
+를 `~/.zshenv`에 둔다. `~/.zshrc`는 interactive 전용이라 훅·headless 워커·툴 셸에서는 읽히지 않는다.
 
 `~/.claude/rules/`에 사본이나 symlink를 두지 않는다. 그 디렉터리는 Claude가 모든 세션에
 자동 로드하므로 tfx와 무관한 세션까지 SSOT 전문을 매번 컨텍스트에 싣게 된다.
-npm 패키지에도 `.claude/`는 없다(`tfx-mirror-policy.md` mirror 제외 대상).
+npm 패키지에는 `.claude/` 중 `rules/tfx-routing.md` 한 파일만 들어 있다.
 
 반환 형식: