triflux 10.50.2 → 10.52.0

package/CLAUDE.md

@@ -1,20 +1,25 @@
-# triflux — Claude Code 운영 가이드
+# triflux Claude Code 운영 가이드
 
 <core-systems>
-## 핵심 스킬 시스템 (항상 인지)
+## 스킬 시스템
 
 이 프로젝트는 3개의 스킬 시스템을 동시에 사용한다. 어떤 작업이든 해당 시스템의 스킬이 있는지 먼저 확인한다.
 
 | 시스템 | 접두사 | 용도 | 스킬 수 |
 |--------|--------|------|---------|
-| **triflux** | `/tfx-*` | CLI 라우팅·다중 모델 조정·스웜·원격 실행 | ~40개 |
+| **triflux** | `/tfx-*` | CLI 라우팅·다중 모델 조정·원격 실행 | 10개 |
 | **gstack** | `/` (접두사 없음) | QA·출시·조사·설계·검토·점검 지점 | ~35개 |
 | **omc** | `/oh-my-claudecode:*` | autopilot·ralph·team·execute·ultragoal | ~37개 |
 
-스킬을 모르면 자연어 라우팅(`.claude/rules/tfx-routing.md`)으로 자동 매핑된다.
-세션 종료 전 메모리 파일이 3개+ 변경됐으면 `/memory-hygiene` 제안을 검토한다.
+필요한 스킬은 이름으로 호출한다.
 </core-systems>
 
+<code-principles>
+## 코드 작성 원칙
+
+코드는 간결하게 쓰고 의미 있는 이름을 쓴다. 주석은 이유만 짧게 한국어로 쓴다. 테스트는 회귀를 막는 핵심 경로만 최소한으로 둔다. 제거 여부는 해당 파일을 끝까지 직접 읽고 판단한다.
+</code-principles>
+
 <psmux-wt>
 ## psmux/WT 규칙 (Windows 한정)
 
@@ -28,7 +33,7 @@ macOS/Linux는 플랫폼 보호기가 아무 작업도 하지 않게 처리하
 
 위 `<psmux-wt>` 룰셋은 Windows 전용이다. macOS/Linux 환경에서 triflux가 터미널/세션을 다루는 방식.
 
-### terminal-opener.mjs 3단계 대체 경로(`hub/team/terminal-opener.mjs` 의 `openCommand`)
+### 터미널 실행 경로
 
 `openCommand()` 가 순차 평가하는 분기:
 
@@ -37,9 +42,9 @@ macOS/Linux는 플랫폼 보호기가 아무 작업도 하지 않게 처리하
 | 1 | `platform === "win32"` | `wt-manager.createTab` | `hub/team/wt-manager.mjs` |
 | 2 | `isTmuxLikeMux(mux)` (`detectMultiplexer()` → `getMultiplexerType()`/`hasMultiplexer()`/`hasTmux()`) | `tmux new-window -n <title> <command>` | 셸 직접 호출 |
 | 3 | `platform === "darwin"` (대체 경로) | `open -a Terminal` | macOS `open` 명령 |
-| — | Linux(멀티플렉서 없음) | 미지원(`false` 반환) | — |
+| 없음 | Linux(멀티플렉서 없음) | 미지원(`false` 반환) | 없음 |
 
-### 별도 mac 매니저 불필요
+### 터미널 관리 방식
 
 | 후보 | 필요성 | 이유 |
 |------|--------|------|
@@ -47,21 +52,19 @@ macOS/Linux는 플랫폼 보호기가 아무 작업도 하지 않게 처리하
 | tmux 관리자 | **불필요** | `terminal-opener.mjs`가 `tmux new-window`로 직접 호출한다. |
 | psmux 관리자 | **이미 있음** | `hub/team/psmux.mjs`가 Windows에서는 psmux, macOS/Linux에서는 tmux를 사용한다. |
 
-참고 사례: OMC(`oh-my-claudecode`)도 운영체제별 관리자를 만들지 않고 Tmux 관리자·워크트리 관리자·Claude 실행기 세 구성 요소로 정리한다. 이 저장소 결정의 외부 근거가 아니라 비교 참고로만 본다.
-
-### 플랫폼 보호기 위치(참고)
+### 플랫폼 보호기
 
-| 파일 | 줄 | 보호기 |
+| 파일 | 함수 | 보호기 |
 |------|------|-------|
-| `hub/team/wt-manager.mjs` | 199 | `if (platform() !== "win32") return createNonWindowsStubManager();` |
-| `hub/team/headless.mjs` | 1725-1726 | `if (process.platform !== "win32") return false;` + `WT_SESSION` 체크 |
-| `tfx-route.sh` | 86, 1662, 1681 | `case "$(uname -s)"` 분기 |
+| `hub/team/wt-manager.mjs` | `createWtManager` | `if (platform() !== "win32") return createNonWindowsStubManager();` |
+| `hub/team/headless.mjs` | `autoAttachTerminal` | `if (process.platform !== "win32") return false;` + `WT_SESSION` 체크 |
+| `scripts/tfx-route.sh` | `resolve_machine_profile_path`, `heartbeat_monitor` | `case "$(uname -s)"` 분기 |
 
-mac에서 위 코드가 호출돼도 일찍 반환하므로 실행되지 않는 코드가 동작하지 않는다. **실행되지 않는 문서만 주입되는 것이 남은 불일치다.**
+Windows 전용 경로는 플랫폼과 `WT_SESSION` 조건을 확인한다.
 
-### macOS 알림(참고)
+### macOS 알림
 
-`hub/team/notify.mjs:221~234`가 `osascript`로 macOS 기본 알림을 보낸다. 별도 의존성은 없다.
+`hub/team/notify.mjs`의 `sendToast`가 `osascript`로 macOS 기본 알림을 보낸다. 별도 의존성은 없다.
 </macos-terminal>
 
 <codex-config>
@@ -74,25 +77,24 @@ mac에서 위 코드가 호출돼도 일찍 반환하므로 실행되지 않는
 | `approval_policy` (`on-request` / `never` / granular) | `--dangerously-bypass-approvals-and-sandbox` |
 | `sandbox_mode` (`read-only` / `workspace-write` / `danger-full-access`) | `-s`, `--sandbox` |
 
-`--full-auto` 는 Codex 0.147 에서 제거됐다. 안전한 방식: `config.toml`에 기본값을 두고 CLI에서는 `--profile`만 선택한다.
+`--full-auto` 는 Codex 0.147 에서 제거되었다. 안전한 방식: `config.toml`에 기본값을 두고 CLI에서는 `--profile`만 선택한다.
 프로필은 `$CODEX_HOME/<이름>.config.toml` 파일이다(인라인 `[profiles.*]` 아님).
 </codex-config>
 
 <account-broker>
 ## AccountBroker (계정 브로커)
 
-conductor·headless·swarm-hypervisor가 하나의 AccountBroker 단일 인스턴스를 공유한다.
+headless 워커는 AccountBroker를 사용한다.
 
 | 항목 | 설명 |
 |------|------|
-| 계정별 회로 차단기 | 장애 격리 — 한 계정 오류가 다른 계정에 전파되지 않음 |
+| 계정별 회로 차단기 | 장애 격리: 한 계정 오류가 다른 계정에 전파되지 않음 |
 | 사용 중 플래그 | 동일 계정 이중 임대 방지 |
-| `/broker/reload` | 장시간 세션 중 accounts.json을 다시 불러온다. 활성 임대 소유권은 다시 불러온 뒤에도 보존한다. |
+| `reloadBroker()` | accounts.json을 다시 불러온다. 활성 임대 소유권은 다시 불러온 뒤에도 보존한다. 허브가 없어 HTTP 엔드포인트는 없고 모듈 함수로만 부를 수 있다. |
 | 어댑터의 임대 없음 정책 | headless 어댑터는 브로커가 비활성·비어 있음이면 기본 CLI 인증 경로로 실행하고, 브로커가 활성인데 임대가 없으면 `circuit_open`으로 실패한다. |
-| Conductor의 임대 없음 정책 | 로컬 Conductor 세션은 `broker_no_lease`를 이벤트 로그에 남기고 생성을 계속한다. accountId가 없으므로 해제는 호출하지 않는다. |
-| 공개 스냅숏 정책 | `/broker/snapshot`과 대시보드는 `publicSnapshot()`만 사용한다. `env`, `authFile`, `profile`, `host`, 파일 경로, 가공하지 않은 실패 시각은 공개하지 않는다. |
-| 진단 이벤트 | `securityViolation`, `authSyncError`는 허브가 가린 경고 로그(`broker.security_violation`, `broker.auth_sync_error`)로 처리한다. |
-| EventEmitter 이벤트 | `lease`, `release`, `cooldown`, `tierFallback`, `circuitOpen`, `circuitClose`, `noAvailableAccounts` — HUD 연동용 |
+| 공개 스냅숏 정책 | 밖에 보여 줄 때는 `publicSnapshot()`만 쓴다. `env`, `authFile`, `profile`, `host`, 파일 경로, 가공하지 않은 실패 시각은 공개하지 않는다. |
+| 진단 이벤트 | `securityViolation`, `authSyncError`는 이벤트로만 내보낸다. 구독하는 쪽이 없으면 기록되지 않는다. |
+| EventEmitter 이벤트 | `lease`, `release`, `cooldown`, `tierFallback`, `circuitOpen`, `circuitClose`, `noAvailableAccounts`: HUD 연동용 |
 </account-broker>
 
 <remote>
@@ -102,7 +104,6 @@ conductor·headless·swarm-hypervisor가 하나의 AccountBroker 단일 인스
 
 | 스킬 | 대상 | 방식 |
 |------|------|------|
-| tfx-swarm | 로컬 worktree + shard `host:` 원격 분배 | PRD별 worktree, 다중 모델·기기 |
 | tfx-remote | Claude Code 원격 | SSH → Claude Code 세션 → 내부 tfx 라우팅 |
 
 Codex를 SSH 너머로 직접 실행하지 않는다. `config.toml` 충돌과 TTY 문제가 있다.
@@ -137,18 +138,30 @@ Codex를 SSH 너머로 직접 실행하지 않는다. `config.toml` 충돌과 TT
 </headless-retrieval>
 
 <native-bridge>
+## 팀 실행 모드
+
+`tfx multi`는 tmux/psmux와 headless를 지원한다. in-process와 WT 팀 모드는 지원하지 않는다.
+headless 워커도 tmux/psmux 방에서 돈다. 멀티플렉서가 없으면 모드와 관계없이 설치 안내 오류로 끝난다.
+Windows Terminal의 독립 탭 열기는 유지한다.
+
 ## 기본 연결 UI(`claude agents` 노출)
 
-비대화식 워커는 기본적으로 `claude agents` 패널에 행으로 나타난다. 제외하려면 `--no-native-bridge-ui`를 쓴다.
+워커는 tmux 방에서 돌고, `claude agents` 행은 그 방에 붙는 attach client다. 행에서 Enter를 누르면
+워커가 도는 tmux pane이 열린다. 행은 공식 `claude --bg --exec`로 만든다(macOS/Linux).
+
+| 대상 | 기본값 | 행에서 할 수 있는 것 |
+|------|--------|----------------------|
+| `tfx-auto` / `tfx multi` headless 워커 | 켬, `--no-native-bridge-ui`로 끔 | 읽기 전용 관찰 |
+| `tfx-live start` 로 띄운 Claude 외 세션 | 켬 | 입력 가능. python3가 없으면 읽기 전용이고 행 이름에 `[read-only]`가 붙음 |
+| 대화형 `tfx multi`(tmux/psmux) | 끔 | 해당 없음 |
 
-| 모드 | 기본값 | 행이 보이는 위치 |
-|------|---------|--------------------|
-| `tfx-auto` / `tfx multi`(비대화식) | 켬 | 로컬 `claude agents` |
-| `tfx swarm` 로컬 조각 | 켬 | 로컬 `claude agents`(`Triflux swarm <shard-name>`) |
-| `tfx swarm` 원격 조각 | **건너뛰고 경고** | 해당 없음 — `registerSwarmShard()`가 host!=local일 때 `{ ok: true, skipped: true }`를 반환하고 `"remote launcher must register on that host"`만 경고한다. 원격 데몬 실제 등록은 후속 PRD다. |
-| 대화식(tmux/wt) | 끔 | 해당 없음 |
+- 행을 닫거나 Ctrl+Z로 목록에 돌아가도 워커는 계속 돈다.
+- headless 워커 여럿이 한 방을 나눠 쓰면 행마다 방 전체가 보이고, 활성 pane은 행끼리 공유한다.
+- 방이 사라지면 행이 스스로 지워진다. headless 실행은 끝날 때 자기가 연 행을 직접 지운다.
+- 바깥 터미널의 질의 응답이 방 입력으로 새지 않게, 읽기 전용 attach 또는 `hub/team/agents-row-attach.py` 중계를 쓴다.
+- 행 생성에는 cwd가 Claude에서 trust 된 워크스페이스여야 한다. 실패하면 워커는 그대로 돌고 경고만 남는다.
 
-감시자가 종료되면 즉시 데몬의 `sendKillBySessionId`를 실행해 오래된 행을 남기지 않는다. PRD: `.triflux/plans/native-bridge-ui-default-expansion.md`(PR #323으로 병합).
+근거: [ADR-0026](docs/adr/0026-agents-row-tmux-attach.md).
 </native-bridge>
 
 <cross-review>
@@ -176,19 +189,22 @@ Codex를 SSH 너머로 직접 실행하지 않는다. `config.toml` 충돌과 TT
 
 | 파일 | 내용 |
 |------|------|
-| `.claude/rules/tfx-routing.md` | 자연어 → 스킬 라우팅, CLI 라우팅 Layer 1~3, 충돌 해소 |
-| `.claude/rules/tfx-execution-skill-map.md` | tfx-auto / multi / swarm 실행 엔진 매핑, 격리 기준, 안티패턴 |
-| `.claude/rules/tfx-autoplan-principles.md` | gstack autoplan의 여섯 가지 결정 원칙·단계 우선순위·충돌 해소 규칙 추출본 |
+| `.claude/rules/tfx-execution-skill-map.md` | tfx-auto / multi 실행 경로와 코드 변경 병렬 작업의 worktree 격리 기준 |
 | `.claude/rules/tfx-update-logic.md` | triflux / OMC / gstack / Codex / Antigravity 업데이트 로직 |
 | `.claude/rules/tfx-stack-coexistence.md` | gstack / superpowers / triflux 공존 원칙, 레이어 분리, 의존 방향, 충돌 해소 |
 | `.claude/rules/tfx-mirror-policy.md` | packages/ 3계층 미러 정책(핵심 단순 복사 / 원격 가져오기 변환 / triflux 바이트 동일), 테스트 제외 규칙, 불일치 차단 |
+| `.claude/rules/tfx-cto-hub-boundary.md` | CTO lake 조회 표면과 의존 방향 |
+| `.claude/rules/tfx-doc-governance.md` | 실행 규칙, ADR, 설계, 계획 문서의 배치 |
+| `.claude/rules/tfx-escalation-chain.md` | 자동 재시도와 CLI 전환 체인 |
+| `.claude/rules/tfx-machine-profile.md` | 기기 프로필 우선순위와 실행 정책 |
+| `.claude/rules/tfx-psmux.md` | Windows psmux와 WT 실행 규칙 |
+| `.claude/rules/tfx-routing.md` | 역할별 CLI 라우팅과 직접 호출 제한 |
+| `.claude/rules/tfx-skill-authoring.md` | 스킬 frontmatter, 프로필 표기, 검증 규약 |
 
 Claude Code는 `.claude/rules/*.md`를 자동으로 불러온다. Codex CLI는 `@import`를 지원하지 않으므로 필요하면 `AGENTS.md`를 독립적으로 유지한다.
 
 ## GBrain
 
-설정 정본은 `~/Projects/CLAUDE.md` 한 곳이다. 여기 있던 사본은 `engine=pglite` /
-`2026-04-25`로 오래되어 전역·Projects 블록과 서로 모순됐다(2026-07-26 제거).
-실제 엔진은 postgres(Supabase), gbrain 0.42.51.0이다.
+설정 정본은 `~/Projects/CLAUDE.md`다.
 
 - 이 저장소 정책: 읽기·쓰기(github.com/tellang/triflux)

package/README.ko.md

@@ -24,15 +24,28 @@
 
 triflux는 코딩 작업을 Claude, Codex, Antigravity 사이에서 나눠 맡기는 Claude Code 플러그인이자
 npm CLI다. `/tfx-auto`에 할 일을 한 번 적으면 triflux가 CLI 레인(기본은 Codex)을 고르고, 임의
-셸 명령 대신 관리된 경로로 실행한다. 필요하면 로컬 병렬 워커, worktree로 격리한 스웜,
-Claude↔Codex 라이브 세션, 원격 호스트로 작업을 나눈다. 설치, 진단, 로컬 Hub, 팀 실행은 `tfx`
+셸 명령 대신 관리된 경로로 실행한다. 필요하면 로컬 병렬 워커, Claude↔Codex 라이브 세션, 원격 호스트로 작업을 나눈다.
+코드 변경을 병렬로 진행할 때는 작업별 worktree와 세션을 분리한다. 설치, 진단, 팀 실행은 `tfx`
 셸 CLI가 맡는다.
 
 ## 설치
 
 ```bash
 npm install -g triflux   # postinstall이 setup 스크립트를 실행한다
-tfx doctor               # CLI, tmux, Hub, MCP, 프로필, 스킬 점검
+tfx doctor               # CLI, tmux, MCP, 프로필, 스킬 점검
+```
+
+npm 12 이상은 기본적으로 설치 스크립트를 막는다. setup 스크립트를 허용해 설치한다.
+
+```bash
+npm i -g triflux --allow-scripts=triflux
+```
+
+기본 setup은 `triflux` 마켓플레이스를 등록하고 mods 설치 안내만 출력한다. 사용량 band와
+서브에이전트 effort 강제 기능은 따로 설치한다(Claude Code 2.1.287 이상).
+
+```bash
+tfx setup --mods
 ```
 
 이 저장소의 마켓플레이스에서 Claude Code 플러그인으로 설치할 수도 있다.
@@ -52,8 +65,6 @@ claude plugin install triflux@triflux
 /tfx-auto "마이그레이션 끝내고 검증까지" --mode deep --retry ralph --max-iterations 10
 ```
 
-실행하지 않고 라우팅 판정만 보려면 셸에서 `tfx auto "<작업>" --json`을 실행한다.
-
 ## 스킬
 
 직접 쓰는 스킬:
@@ -61,10 +72,10 @@ claude plugin install triflux@triflux
 | 스킬 | 용도 |
 | --- | --- |
 | `/tfx-auto` | 구현, 수정, 리뷰, 병렬 작업의 진입점. 동작은 아래 플래그로 정한다. |
-| `/tfx-live` | Claude↔Codex 라이브 세션. `start`/`ask`/`stop`, `peer` 중계, `orchestrate`, `list-sessions`. |
-| `/tfx-remote` | SSH 너머 원격 Claude Code 세션. `setup`, `spawn`, `list`, `attach`, `send`, `resume`, `probe`, `kill`. |
+| `/tfx-live` | Claude↔Codex 라이브 세션. `start`/`ask`/`wait`/`stop`, `peer` 중계, `list-sessions`. |
+| `/tfx-remote` | SSH 원격 Claude Code 세션 시작, 조회, 재부착, 메시지 전송, 준비 상태 확인, 모니터링, 종료. |
 | `/tfx-setup` | 대화형 설정. 파일 동기화, HUD, Codex 프로필, MCP, 훅 우선순위. |
-| `/tfx-doctor` | 진단과 복구. Hub 시작·중지·상태 확인도 여기서 한다. |
+| `/tfx-doctor` | 진단과 복구. |
 | `/tfx-ship` | triflux 릴리즈 절차(메인테이너용). |
 | `/tfx-wt` | Windows Terminal 탭·패인 조작. `tfx setup`은 Windows에만 설치한다. |
 
@@ -88,13 +99,10 @@ Codex 프로필은 `~/.codex/<프로필>.config.toml`에서 직접 관리한다.
 | `--shape` | `consensus`, `debate`, `panel` | `--mode consensus`의 결과 형태 |
 | `--cli` | `auto`, `codex`, `antigravity`, `claude` | CLI 레인 고정 |
 | `--cli-set` | `triad`, `no-antigravity`, `custom` | 합의 참여자 구성 |
-| `--parallel` | `1`, `N`, `swarm` | `N` = 로컬 워커(`tfx multi`), `swarm` = worktree별 PRD 샤드(`tfx swarm`) |
-| `--isolation` | `none`, `worktree` | 샤드별 worktree 격리(`swarm`이면 강제) |
-| `--remote` | `<host>` | 스웜 샤드를 `hosts.json`의 호스트로 보냄 |
+| `--parallel` | `1`, `N` | `N` = 로컬 워커(`tfx multi`) |
 | `--retry` | `0`, `1`(기본), `ralph`, `auto-escalate` | `ralph` = 막힘 감지가 있는 재시도 상태 기계, `auto-escalate` = 모델 체인을 한 단계씩 올림 |
 | `--max-iterations` | `N` | `ralph`/`auto-escalate` 상한(`0`은 무제한) |
 | `--rounds` | `N`(기본 4) | `--mode live` 왕복 횟수 |
-| `--risk-tier` | `auto`, `low`, `medium`, `high` | 변경 범위로 검증 강도를 정함. `--mode`가 있으면 무시 |
 | `--skill` | `<name>` | `skills/<name>/SKILL.md`를 Codex/Antigravity 프롬프트 앞에 붙임 |
 | `--no-native-bridge-ui` | | headless 워커를 `claude agents` 패널에 띄우지 않음 |
 
@@ -124,27 +132,22 @@ Codex는 이름 붙은 프로필로 실행한다. 모델 ID는 `~/.codex/<프로
 | 명령 | 용도 |
 | --- | --- |
 | `tfx setup` / `tfx doctor` | 파일·HUD·MCP·프로필 동기화 / 진단과 복구(`--fix`, `--json`) |
-| `tfx auto` | `tfx-auto` 라우팅 판정 미리 보기 |
-| `tfx multi` | tmux + Hub 기반 로컬 멀티 CLI 팀 |
-| `tfx swarm` | PRD 기반 worktree 격리 실행: `plan`, `preflight`, `run`, `list` |
-| `tfx synapse` | 스웜 세션 레지스트리와 lease |
-| `tfx hub` | 로컬 Hub: `start`, `stop`, `status`, `ensure` |
+| `tfx multi` | tmux 기반 로컬 멀티 CLI 팀 |
 | `tfx mcp` | 관리형 MCP 레지스트리: `list`, `sync`, `add`, `remove` |
-| `tfx handoff` | 현재 맥락을 다른 세션이나 호스트로 넘길 프롬프트로 묶음 |
 | `tfx cto` | 저장소 단위 권위 콘솔: `collect`, `status`, `hygiene`(dry-run) |
-| `tfx review` / `tfx codex-team` | Codex git diff 리뷰 / Codex 주도 팀 모드 |
-| `tfx stealth-fetch <url>` | cloakbrowser로 URL 하나를 가져옴(JSON을 stdout으로) |
-| `tfx notion-read`, `tfx why`, `tfx schema`, `tfx list`, `tfx monitor`, `tfx update`, `tfx version` | Notion → Markdown, 커밋 intent 트레일러, CLI 스키마, 설치된 스킬, TUI 모니터, 업데이트, 버전 |
+| `bash ~/.claude/scripts/tfx-route.sh code-reviewer "<지시>"` | 정책에 따라 `codex exec review`로 리뷰 전달 |
+| `tfx list`, `tfx update`, `tfx version` | 설치된 스킬, 업데이트, 버전 |
 | `tfx-live` | 라이브 세션 브리지(`/tfx-live` 스킬과 같은 명령) |
 
-정확한 인자는 `tfx <명령> --help`나 `tfx schema <명령>`으로 확인한다.
+정확한 인자는 `tfx <명령> --help`로 확인한다.
 
 ## 런타임 기능
 
 **라이브 세션.** `tfx-live`는 Claude Code와 Codex TUI 세션을 조종한다. Claude 데몬 대상
 (`--short`/`--session-id`)은 UDS를 먼저 시도하고, `--session`도 주면 실패 시 tmux로 넘어간다.
-Codex는 tmux를 쓰거나 `--transport uds --thread <id|auto>`로 UDS를 쓴다. `peer`는 두 세션 사이를
-`--rounds`만큼 중계하고, `orchestrate`는 한 작업에 Claude와 Codex를 함께 붙인다. triflux의 Codex
+Codex `ask`는 `codex queue`로 메시지를 쌓고(TUI에 `[from <보낸 세션>]` 첫 줄로 보인다) 못 쓰면 이유를
+남기고 tmux로 보낸다. `--transport uds --thread <id|auto>`로 UDS도 쓸 수 있다. `peer`는 두 세션 사이를
+`--rounds`만큼 중계한다. triflux의 Codex
 훅이 실행 중인 Codex 세션을 `~/.local/state/triflux/codex-sessions/`에 기록하므로
 `tfx-live list-sessions --cli codex|claude`로 직접 띄운 tmux 세션도 찾을 수 있다.
 
@@ -152,10 +155,8 @@ Codex는 tmux를 쓰거나 `--transport uds --thread <id|auto>`로 UDS를 쓴다
 Claude Code Bash 도구의 600초 제한에 걸리지 않는다. 이후 `--job-status`, `--job-wait`,
 `--job-result`로 확인한다.
 
-**Hub.** 팀, 원격 세션, MCP 도구, 상태 표시를 잇는 로컬 메시지 버스다. 기본으로
-`127.0.0.1:27888`에 붙고(`TFX_HUB_PORT`로 변경), `TFX_HUB_TOKEN`이 있으면 bearer 토큰을 요구한다.
-`tfx-auto`, `tfx multi`, 로컬 스웜 샤드의 headless 워커는 `claude agents` 패널에 행으로 보인다.
-끄려면 `--no-native-bridge-ui`를 준다.
+**Headless 워커.** `tfx-auto`, `tfx multi`의 headless 워커는 `claude agents` 패널에 행으로 보인다.
+행에서 Enter를 누르면 그 워커가 도는 tmux pane이 열린다. 끄려면 `--no-native-bridge-ui`를 준다.
 
 **재시도와 승격.** `--retry ralph`는 끝나거나 막힐 때(같은 실패 3회 연속)까지 반복한다.
 `--retry auto-escalate`는 Codex `gpt6_astra_max`에서 Claude `fable`로 올라간다. 체인은
@@ -169,12 +170,13 @@ Claude Code Bash 도구의 600초 제한에 걸리지 않는다. 이후 `--job-s
 
 **CTO lake.** `tfx cto collect`로 `.triflux/lake/`의 저장소 스냅샷을 갱신하고,
 `tfx cto status`로 생성 시각과 경과 시간을 확인한다. `tfx cto hygiene --dry-run`는 dry-run 결과를
-보고한다. 트레이와 쓰이지 않는 CTO 운영 명령은 제거했다
-([ADR-0024](docs/adr/0024-cto-explicit-queries-only.md)). 자동 수집은 기본으로 꺼져 있고 `TFX_CTO_AUTO_COLLECT=1` 로 켠다([ADR-0018](docs/adr/0018-cto-auto-behaviors-opt-in.md)).
+보고한다. 트레이와 쓰이지 않는 CTO 운영 명령은 제거하였다
+([ADR-0024](docs/adr/0024-cto-explicit-queries-only.md)). 자동 수집은 기본으로 꺼져 있고 `TFX_CTO_AUTO_COLLECT=1` 로 켠다([ADR-0018](docs/_archive/adr/0018-cto-auto-behaviors-opt-in.md)).
 
-**원격 호스트.** `/tfx-remote`와 `--remote <host>`는 `~/.config/triflux/hosts.json`
-(Windows는 `%APPDATA%\triflux\hosts.json`)에서 호스트를 읽는다. `/tfx-remote setup`으로 호스트를
-추가한 뒤 `/tfx-remote spawn <host> "보안 리뷰 실행"`처럼 쓴다.
+**원격 호스트.** `/tfx-remote`는 `~/.config/triflux/hosts.json`
+(Windows는 `%APPDATA%\triflux\hosts.json`)에서 호스트를 읽는다. 세션 시작은
+`remote-spawn.mjs`의 `--host <host> --prompt "<요청>"` 옵션을 사용한다.
+[실행 옵션](skills/tfx-remote/SKILL.md)을 따른다.
 
 ## 구조
 
@@ -184,18 +186,14 @@ graph TD
     User --> CLI[tfx CLI]
     Skills --> Route[tfx-route.sh]
     Skills --> Live[tfx-live]
-    CLI --> Team["tfx multi · tfx swarm"]
+    CLI --> Team["tfx multi"]
     Route --> Codex[Codex CLI]
     Route --> Agy[Antigravity agy]
     Route --> Claude[Claude Code]
     Team --> Route
-    Team --> WT[(git worktrees)]
     Live -->|UDS 또는 tmux| Sessions[Claude / Codex TUI 세션]
-    Route --> Hub["Hub 127.0.0.1:27888"]
-    Team --> Hub
-    Hub --> Store[(SQLite 또는 메모리 저장소)]
-    Hub --> MCP[MCP 도구]
-    Hub --> UI["HUD · claude agents 패널"]
+    Route --> UI["HUD · claude agents 패널"]
+    Team --> UI
     CLI --> Lake[(".triflux/lake (tfx cto)")]
 ```
 
@@ -210,8 +208,8 @@ graph TD
 | Linux | tmux | 지원. |
 | Windows | psmux + Windows Terminal | 아래 참고. |
 
-**Windows.** psmux(tmux 포크)의 기본 셸은 PowerShell이다. safety-guard가 `wt.exe`와 psmux `kill-session`
-직접 호출을 막으므로 탭과 패인은 `tfx-wt` 스킬(Windows에만 설치)과
+**Windows.** psmux(tmux 포크)의 기본 셸은 PowerShell이다. `wt.exe`와 psmux `kill-session`은 직접 호출하지
+않고, 탭과 패인은 `tfx-wt` 스킬(Windows에만 설치)과
 `hub/team/wt-manager.mjs`를 거친다. 에이전트 규칙은
 [`.claude/rules/tfx-psmux.md`](.claude/rules/tfx-psmux.md).
 
@@ -219,9 +217,7 @@ graph TD
 
 | 층 | 보호 |
 | --- | --- |
-| 관리된 경로 | Codex와 Antigravity는 `tfx-route.sh`, Hub 워커, `tfx`로만 부르고 맨 `codex exec`나 `agy`로 부르지 않는다. 호출자가 지키는 규칙이며 이를 막는 훅은 없다. |
-| safety-guard 훅 | 위험한 셸 명령(루트 `rm -rf`, main 강제 push, `git clean -fd`, SQL `DROP`), `wt.exe`·psmux 종료 직접 호출, Windows 호스트로 SSH 보내는 bash 문법을 막고 관리된 대안을 알려 준다. |
-| Hub | localhost에만 붙는다. bearer 토큰(`TFX_HUB_TOKEN`)은 선택. |
+| 관리된 경로 | Codex와 Antigravity는 `tfx-route.sh`, headless 워커, `tfx`로만 부르고 맨 `codex exec`나 `agy`로 부르지 않는다. 호출자가 지키는 규칙이며 이를 막는 훅은 없다. |
 | MCP 레지스트리 | 낡았거나 지원하지 않는 MCP 항목을 관리형 항목으로 바꾼다. |
 | 합의 결과 | deep·consensus 실행은 일부 레인이 빠졌거나 의견이 갈린 결과를 숨기지 않고 표시한다. |
 

package/README.md

@@ -25,15 +25,29 @@
 triflux is a Claude Code plugin and npm CLI that routes coding work across Claude, Codex,
 and Antigravity. You describe the task once with `/tfx-auto`; triflux picks the CLI lane
 (Codex by default), runs it through managed routes instead of ad-hoc shell commands, and
-can fan the work out to parallel workers, worktree-isolated swarms, live Claude↔Codex
-sessions, or remote hosts. The `tfx` shell CLI covers setup, diagnostics, the local Hub,
+can fan the work out to parallel workers, live Claude↔Codex sessions, or remote
+hosts. Parallel code changes use separate worktrees and one session per worktree.
+The `tfx` shell CLI covers setup, diagnostics,
 and team orchestration.
 
 ## Install
 
 ```bash
 npm install -g triflux   # postinstall runs the setup script
-tfx doctor               # check CLIs, tmux, Hub, MCP, profiles, skills
+tfx doctor               # check CLIs, tmux, MCP, profiles, skills
+```
+
+npm 12 and newer block install scripts by default. Allow the setup script:
+
+```bash
+npm i -g triflux --allow-scripts=triflux
+```
+
+Setup registers the `triflux` marketplace and prints a mods installation hint. To install
+usage bands and subagent effort enforcement (Claude Code 2.1.287 or newer):
+
+```bash
+tfx setup --mods
 ```
 
 Or install the Claude Code plugin from this repository's marketplace:
@@ -53,8 +67,6 @@ claude plugin install triflux@triflux
 /tfx-auto "finish the migration and verify it" --mode deep --retry ralph --max-iterations 10
 ```
 
-Run `tfx auto "<task>" --json` in a shell to preview the routing decision without executing it.
-
 ## Skills
 
 Skills you invoke directly:
@@ -62,10 +74,10 @@ Skills you invoke directly:
 | Skill | Use |
 | --- | --- |
 | `/tfx-auto` | Front door for implementing, fixing, reviewing, and parallel work. Behavior is set by flags (below). |
-| `/tfx-live` | Live Claude↔Codex sessions: `start`/`ask`/`stop`, `peer` relay, `orchestrate`, `list-sessions`. |
-| `/tfx-remote` | Remote Claude Code sessions over SSH: `setup`, `spawn`, `list`, `attach`, `send`, `resume`, `probe`, `kill`. |
+| `/tfx-live` | Live Claude↔Codex sessions: `start`/`ask`/`wait`/`stop`, `peer` relay, `list-sessions`. |
+| `/tfx-remote` | SSH 원격 Claude Code 세션 시작, 조회, 재부착, 메시지 전송, 준비 상태 확인, 모니터링, 종료. |
 | `/tfx-setup` | Interactive setup: file sync, HUD, Codex profiles, MCP, hook priority. |
-| `/tfx-doctor` | Diagnose and repair; also starts, stops, and checks the Hub. |
+| `/tfx-doctor` | Diagnose and repair. |
 | `/tfx-ship` | triflux release flow (maintainers). |
 | `/tfx-wt` | Windows Terminal tabs and panes. `tfx setup` installs it on Windows only. |
 
@@ -89,13 +101,10 @@ and execution. Manage Codex profiles directly in `~/.codex/<profile>.config.toml
 | `--shape` | `consensus`, `debate`, `panel` | Output shape for `--mode consensus` |
 | `--cli` | `auto`, `codex`, `antigravity`, `claude` | Force a CLI lane |
 | `--cli-set` | `triad`, `no-antigravity`, `custom` | Consensus participants |
-| `--parallel` | `1`, `N`, `swarm` | `N` = local workers (`tfx multi`); `swarm` = PRD shards in worktrees (`tfx swarm`) |
-| `--isolation` | `none`, `worktree` | Worktree isolation per shard (forced on with `swarm`) |
-| `--remote` | `<host>` | Send swarm shards to a host from `hosts.json` |
+| `--parallel` | `1`, `N` | `N` = local workers (`tfx multi`) |
 | `--retry` | `0`, `1` (default), `ralph`, `auto-escalate` | `ralph` = retry state machine with stuck detection; `auto-escalate` = move up the model chain |
 | `--max-iterations` | `N` | Cap for `ralph` / `auto-escalate` (`0` = unlimited) |
 | `--rounds` | `N` (default 4) | Round trips for `--mode live` |
-| `--risk-tier` | `auto`, `low`, `medium`, `high` | Pick verification strength from the change; ignored when `--mode` is set |
 | `--skill` | `<name>` | Prepend `skills/<name>/SKILL.md` to the Codex/Antigravity prompt |
 | `--no-native-bridge-ui` | | Hide headless workers from the `claude agents` panel |
 
@@ -125,28 +134,22 @@ escalation chain: [`.claude/rules/tfx-escalation-chain.md`](.claude/rules/tfx-es
 | Command | Use |
 | --- | --- |
 | `tfx setup` / `tfx doctor` | Sync files, HUD, MCP, profiles / diagnose and repair (`--fix`, `--json`) |
-| `tfx auto` | Preview the `tfx-auto` routing decision |
-| `tfx multi` | Local multi-CLI team in tmux + Hub |
-| `tfx swarm` | PRD-based, worktree-isolated work: `plan`, `preflight`, `run`, `list` |
-| `tfx synapse` | Swarm session registry and leases |
-| `tfx hub` | Local Hub: `start`, `stop`, `status`, `ensure` |
+| `tfx multi` | Local multi-CLI team in tmux |
 | `tfx mcp` | Managed MCP registry: `list`, `sync`, `add`, `remove` |
-| `tfx handoff` | Serialize the current context for another session or host |
 | `tfx cto` | Repo-local authority console: `collect`, `status`, `hygiene` (dry-run) |
-| `tfx review` / `tfx codex-team` | Codex git-diff review / Codex-led team mode |
-| `tfx stealth-fetch <url>` | Fetch one URL through cloakbrowser (JSON on stdout) |
-| `tfx notion-read`, `tfx why`, `tfx schema`, `tfx list`, `tfx monitor`, `tfx update`, `tfx version` | Notion → Markdown, commit intent trailers, CLI schemas, installed skills, TUI monitor, update, version |
+| `bash ~/.claude/scripts/tfx-route.sh code-reviewer "<instruction>"` | Send review to Codex (`codex exec review` via policy) |
+| `tfx list`, `tfx update`, `tfx version` | Installed skills, update, version |
 | `tfx-live` | Live session bridge (same as the `/tfx-live` skill) |
 
-`tfx <command> --help` and `tfx schema <command>` print the exact arguments.
+`tfx <command> --help` prints the exact arguments.
 
 ## Runtime features
 
 **Live sessions.** `tfx-live` drives Claude Code and Codex TUI sessions. Claude daemon targets
 (`--short`/`--session-id`) try UDS first and fall back to tmux when `--session` is also given;
-Codex uses tmux, or UDS with
-`--transport uds --thread <id|auto>`. `peer` relays between two sessions for `--rounds`, and
-`orchestrate` runs Claude + Codex on one task. triflux's Codex hook records running Codex
+Codex `ask` queues the message with `codex queue` (shown in the TUI with a
+`[from <sender>]` first line) and falls back to tmux with a reported reason; UDS stays available with
+`--transport uds --thread <id|auto>`. `peer` relays between two sessions for `--rounds`. triflux's Codex hook records running Codex
 sessions under `~/.local/state/triflux/codex-sessions/`, so `tfx-live list-sessions --cli codex|claude`
 also finds sessions you started yourself in tmux.
 
@@ -154,10 +157,9 @@ also finds sessions you started yourself in tmux.
 gets past Claude Code's 600-second Bash limit. Follow up with `--job-status`, `--job-wait`, and
 `--job-result`.
 
-**Hub.** A local message bus for teams, remote sessions, MCP tools, and status surfaces. It binds
-to `127.0.0.1:27888` by default (`TFX_HUB_PORT` overrides) and accepts a bearer token from
-`TFX_HUB_TOKEN`. Headless workers from `tfx-auto`, `tfx multi`, and local swarm shards appear in
-the `claude agents` panel unless you pass `--no-native-bridge-ui`.
+**Headless workers.** Workers from `tfx-auto` and `tfx multi` appear in
+the `claude agents` panel unless you pass `--no-native-bridge-ui`. Press Enter on a row to open the
+tmux pane the worker runs in.
 
 **Retry and escalation.** `--retry ralph` loops until done or stuck (three identical failures).
 `--retry auto-escalate` steps from Codex `gpt6_astra_max` to Claude `fable`; override the chain in
@@ -171,11 +173,11 @@ falling back. Details: [`.claude/rules/tfx-machine-profile.md`](.claude/rules/tf
 **CTO lake.** Run `tfx cto collect` to refresh the repo snapshot in `.triflux/lake/`, then
 `tfx cto status` to inspect it with its generation time and age. `tfx cto hygiene --dry-run` reports
 dry-run findings. The tray and unused CTO operating commands were removed
-([ADR-0024](docs/adr/0024-cto-explicit-queries-only.md)). Automatic collection stays off unless `TFX_CTO_AUTO_COLLECT=1` is set ([ADR-0018](docs/adr/0018-cto-auto-behaviors-opt-in.md)).
+([ADR-0024](docs/adr/0024-cto-explicit-queries-only.md)). Automatic collection stays off unless `TFX_CTO_AUTO_COLLECT=1` is set ([ADR-0018](docs/_archive/adr/0018-cto-auto-behaviors-opt-in.md)).
 
-**Remote hosts.** `/tfx-remote` and `--remote <host>` read hosts from `~/.config/triflux/hosts.json`
-(Windows: `%APPDATA%\triflux\hosts.json`). Run `/tfx-remote setup` to add one, then
-`/tfx-remote spawn <host> "run a security review"`.
+**원격 호스트.** `/tfx-remote`는 `~/.config/triflux/hosts.json`에서 호스트를 읽는다
+(Windows: `%APPDATA%\triflux\hosts.json`). 세션 시작은 `remote-spawn.mjs`의
+`--host <host> --prompt "<요청>"` 옵션을 사용한다. [실행 옵션](skills/tfx-remote/SKILL.md)을 따른다.
 
 ## Architecture
 
@@ -185,18 +187,14 @@ graph TD
     User --> CLI[tfx CLI]
     Skills --> Route[tfx-route.sh]
     Skills --> Live[tfx-live]
-    CLI --> Team["tfx multi · tfx swarm"]
+    CLI --> Team["tfx multi"]
     Route --> Codex[Codex CLI]
     Route --> Agy[Antigravity agy]
     Route --> Claude[Claude Code]
     Team --> Route
-    Team --> WT[(git worktrees)]
     Live -->|UDS or tmux| Sessions[Claude / Codex TUI sessions]
-    Route --> Hub["Hub 127.0.0.1:27888"]
-    Team --> Hub
-    Hub --> Store[(SQLite or memory store)]
-    Hub --> MCP[MCP tools]
-    Hub --> UI["HUD · claude agents panel"]
+    Route --> UI["HUD · claude agents panel"]
+    Team --> UI
     CLI --> Lake[(".triflux/lake (tfx cto)")]
 ```
 
@@ -211,8 +209,8 @@ Package layout and execution paths: [ARCHITECTURE.md](ARCHITECTURE.md). Document
 | Linux | tmux | Supported. |
 | Windows | psmux + Windows Terminal | See below. |
 
-**Windows.** psmux (a tmux fork) runs PowerShell by default. safety-guard blocks direct `wt.exe`
-and raw `psmux kill-session`, so tabs and panes go through the `tfx-wt` skill (set up only on
+**Windows.** psmux (a tmux fork) runs PowerShell by default. Callers do not run `wt.exe` or raw
+`psmux kill-session` directly; tabs and panes go through the `tfx-wt` skill (set up only on
 Windows) and `hub/team/wt-manager.mjs`. Agent rules:
 [`.claude/rules/tfx-psmux.md`](.claude/rules/tfx-psmux.md).
 
@@ -220,9 +218,7 @@ Windows) and `hub/team/wt-manager.mjs`. Agent rules:
 
 | Layer | Protection |
 | --- | --- |
-| Managed routes | Codex and Antigravity are called through `tfx-route.sh`, Hub workers, or `tfx`, never through a bare `codex exec` or `agy`. This is a rule for callers; no hook enforces it. |
-| safety-guard hook | Blocks destructive shell commands (root `rm -rf`, force push to main, `git clean -fd`, SQL `DROP`), direct `wt.exe`, raw psmux kill, and bash syntax sent over SSH to Windows hosts, and points to the managed alternative. |
-| Hub | Binds to localhost; optional bearer token (`TFX_HUB_TOKEN`). |
+| Managed routes | Codex and Antigravity are called through `tfx-route.sh`, headless workers, or `tfx`, never through a bare `codex exec` or `agy`. This is a rule for callers; no hook enforces it. |
 | MCP registry | Replaces stale or unsupported MCP entries with managed ones. |
 | Consensus | Deep and consensus runs report degraded or disputed results instead of hiding them. |