tfx-remote

name	tfx-remote
description	원격 관련 표면을 setup/spawn 계열 하나로 통합한 엔트리포인트. setup, spawn, list, attach, send, resume, kill, probe 하위 명령을 기준으로 기존 tfx-remote-setup/tfx-remote-spawn 흐름을 축소 통합한다.
argument-hint	[setup|spawn|list|attach|send|resume|kill|probe] ...

tfx-remote — remote consolidated entrypoint

tfx-remote는 신규 원격 엔진이 아니라 기존 tfx-remote-setup + tfx-remote-spawn 표면을 한 명령군으로 축소한 통합 진입점이다.

Public subcommands

Subcommand	역할	legacy 매핑
setup	hosts 등록/편집/진단/probe-all	tfx-remote-setup
spawn <host> [prompt]	원격/로컬 세션 생성	tfx-remote-spawn
list	활성 세션 목록	tfx-remote-spawn --list
attach <session>	세션 재부착	tfx-remote-spawn --attach
send <session> "<msg>"	세션에 후속 프롬프트 전송	tfx-remote-spawn --send
`resume <session	host	recent>`
kill <session>	세션 종료	legacy kill 동작 공식 승격
probe <host>	SSH/Tailscale/Claude 연결 체크	tfx-remote-setup / tfx-remote-spawn --probe

capture / wait는 Phase 4b public consolidation 대상이 아니다. 필요하면 legacy passthrough로만 유지한다.

Dispatch contract

tfx-remote setup

기존 tfx-remote-setup 플로우를 그대로 사용한다.

• setup
• setup --add
• setup --edit
• setup --probe-all
• setup --diagnose

hosts.json 은 user-state 경로 한 곳만 읽고 쓴다.

• macOS/Linux: ~/.config/triflux/hosts.json
• Windows: %APPDATA%\triflux\hosts.json

기존 references/hosts.json 및 source/packages/global 3곳 fan-out 단계는 더 이상 사용하지 않는다. 첫 실행 시 legacy references/hosts.json 이 발견되면 lazy auto-migration으로 user-state 경로에 자동 이동된다.

tfx-remote spawn

기존 tfx-remote-spawn 플로우를 사용하되 아래 preflight를 먼저 수행한다.

1. user-state hosts.json 존재 확인
2. 호스트명/alias 해석
3. probe TTL 확인
4. SSH 실패 시 setup diagnose 또는 setup edit 복귀 경로 제시

preflight 실패 시 중단만 하지 말고 아래 중 하나로 복귀시킨다.

• tfx-remote setup --add
• tfx-remote setup --edit
• tfx-remote setup --diagnose
• tfx-remote probe <host>

tfx-remote resume

우선순위는 아래와 같다.

1. 세션명이 주어지면 해당 세션 attach/복구
2. 호스트명이 주어지면 해당 호스트의 최근 세션 탐색
3. recent 또는 생략이면 최근 세션 우선, 없으면 default_host 기준 새 spawn

tfx-remote kill

공식 public subcommand다. 세션 종료 전에 psmux/WT 정리 규칙은 .claude/rules/tfx-psmux.md와 AGENTS.md의 detach-first 정책을 따른다.

hosts.json contract

신규 코드는 가능하면 hub/lib/hosts-compat.mjs를 기준으로 해석한다. 저장 위치는 macOS/Linux ~/.config/triflux/hosts.json, Windows %APPDATA%\triflux\hosts.json 이다.

• v1 legacy 필드 유지: os, ssh_user, tailscale.ip, tailscale.dns, capabilities
• v2 additive 필드 허용: ssh.user, capabilities_v2, last_probe

resolveHost(nameOrAlias) 기준으로 alias, tailscale DNS/IP, ssh_user@host를 canonical host로 정규화한다.

Verification

허용 범위 안에서 Phase 4b가 완료되었는지 확인할 때 최소 검증은 아래와 같다.

• node hub/lib/hosts-compat.mjs --self-test
• Get-FileHash .claude/rules/tfx-psmux.md, AGENTS.md
• legacy alias 문서가 모두 tfx-remote 또는 rule 문서로 위임되는지 확인