다른 장치의 워커

한 장치의 코디네이터가 같은 계정의 다른 장치에 워커를 띄우거나, 그 장치에서 이미 실행 중이던 에이전트를 워커로 데려옵니다. 시뮬레이터처럼 그 장치가 있어야 하는 일에 씁니다.

워커는 같은 계정의 다른 장치(예: CI용으로 둔 Mac)에서도 실행할 수 있습니다. 그 장치에 새로 띄워도 되고, 그 장치에서 이미 실행 중이던 에이전트를 데려와도 됩니다. 그 장치의 시뮬레이터, GPU, 저장소처럼 그 장치가 있어야 하는 일에 씁니다. 워커는 그 장치에서 보통의 워커로 실행되고, 창, 대화, 질문, 알림도 그 장치에 따로 있습니다. 코디네이터 쪽 st는 그 장치에 있는 워커에게 일을 주고, 기다리고, 결과를 읽어 옵니다.

필요한 것

• 두 장치 모두 st 0.3.85 이상이어야 합니다.
• 두 장치가 같은 계정으로 로그인되어 있어야 합니다.
• 코디네이터 쪽 장치는 st login으로 로그인되어 있어야 합니다.
• 일을 받는 장치에서 st orch accept-remote on으로 허용해야 합니다. 켜기 전까지는 꺼져 있습니다.
• 일을 받는 장치에서 st가 실행 중이어야 하고, 그 장치에도 훅(st hooks install)이 설치되어 있어야 합니다.
• Windows 장치(psmux 3.4.0, st 0.3.97 이상)는 데려오기로만 워커를 받습니다. 그 장치로 보내는 st worker start --machine은 거절됩니다. st는 시작할 때 psmux를 시험해 보고, psmux가 st에 필요한 것을 유지하지 못하면(예를 들어 옛 psmux) 그 장치의 워커를 끄며, st orch accept-remote on과 --machine이 그 이유를 알려 줍니다.

순서

1. 일을 받는 장치에서 허용합니다. 다른 장치가 이 장치에서 에이전트를 띄우고 입력까지 하는 기능이므로 직접 켜기 전까지는 꺼져 있습니다. 켜더라도 같은 계정의 장치만 받습니다.

st orch accept-remote on        # 같은 계정의 다른 장치에서 워커를 받습니다
st orch accept-remote status    # 지금 받는지
st orch accept-remote off       # 그만 받기

2. 코디네이터에서 일을 넘깁니다. 장치는 이름, 호스트 이름, slug 가운데 무엇으로 불러도 되고 대소문자는 가리지 않습니다. 장치 목록은 st machines로 봅니다. 지금 이 장치를 가리키면 거절됩니다. 그때는 --machine을 빼면 됩니다.

st worker start --machine ci-mac --agent claude --task sim.md
st worker wait ci-mac/%7
st worker read ci-mac/%7

평소처럼 코디네이터에게 "iOS 테스트는 ci-mac에서 실행해 줘"라고 부탁하면 코디네이터가 이 명령을 실행합니다.

그 장치의 워커

• 워커는 그 장치의 st-remote 세션에 새 창으로 뜨고(세션이 없으면 만듭니다), 그 장치의 홈 폴더나 --cwd로 준 폴더에서 일합니다.
• --owns와 --worktree는 한 장치에서 쓸 때와 똑같이 동작하고, worktree는 그 장치의 저장소에 만들어집니다.
• st worker start는 그 장치에서 워커가 턴을 시작한 것을 확인한 뒤에 돌아옵니다. 확인은 최대 150초까지 합니다. 신뢰 화면과 훅 확인은 한 장치에서와 같은 방식으로 그 장치에서 합니다.
• id는 ci-mac/%7처럼 장치와 pane으로 이루어집니다. st는 장치 자리에 slug를 쓰지만, 이름이나 호스트 이름을 써도 됩니다. pane 자리에 워커 이름을 써서 ci-mac/<이름>으로 불러도 됩니다(st 0.3.90 이상).
• wait, read, send, stop, list, adopt, rename, release가 이 id를 받습니다. id 없이 st worker wait를 실행하면 이 pane이 다른 장치에 둔 워커도 기다리고, st worker list는 그런 워커를 장치 이름과 함께 보여 줍니다. st worker list --all은 이 장치의 모든 실행이 다른 장치에 둔 워커를 보여 줍니다(st 0.3.88 이상).
• 깊이 한도는 장치를 넘어서도 이어서 셉니다. 한 실행 안에서 두 단계, 맨 위 코디네이터부터 전체 사슬 네 단계입니다(두 장치 모두 st 0.3.88 이상).
• 워커는 평소처럼 자기 장치에서 st worker done으로 보고하고, 코디네이터 쪽 st가 그 장치에서 보고를 읽어 옵니다.
• 그 장치에 연결되지 않는 동안 wait는 그 워커를 아직 일하는 중으로 보고, list는 unreachable로 표시합니다.

연결

• 따로 포트를 열거나 SSH를 쓸 필요가 없습니다. 코디네이터 쪽 st가 계정을 거쳐 그 장치에 닿습니다.
• 통신은 https로만 합니다.
• 장치 접근 권한은 11시간 동안 ~/.sophonz/remote/<slug>.json에 보관하므로 명령마다 장치를 다시 열지 않습니다. 장치 주소가 바뀌면 다시 엽니다.

다른 장치의 에이전트 데려오기

다른 장치에서 이미 실행 중이던 에이전트도 대화를 그대로 유지한 채 코디네이터의 워커로 데려올 수 있습니다.

st worker adopt ci-mac/%7
st worker send ci-mac/%7 "iPhone 16 시뮬레이터에서 UI 테스트를 실행해 줘."

• 이 경우에도 그 장치가 워커를 받도록(st orch accept-remote on) 켜 두어야 합니다.
• --owns는 이 장치의 워커에만 쓸 수 있습니다. 다른 장치의 id와 함께 주면 거절됩니다.
• 이미 다른 에이전트의 워커인 에이전트는 놓아 주기 전까지 데려올 수 없습니다.
• 자기 워커를 거느린 에이전트는 팀으로 들어옵니다. 팀장은 자기 장치에서 자기 실행을 유지하고 팀도 그 장치에 그대로 남으며, 이쪽에서는 st worker list에 (team N)이 붙은 워커 하나로 보입니다. 두 장치 모두 st 0.3.88 이상이어야 합니다. 그 장치의 st가 그보다 오래되면 팀장이 이쪽 코디네이터의 실행으로 옮겨 옵니다. 팀을 워커로 데려오기를 보세요.

다른 장치의 워커 이름 바꾸기

st worker rename ci-mac/%7 ios-ci는 그 장치에서 워커의 이름을 바꾸고, 이 장치의 실행 기록도 함께 고칩니다. 두 장치 모두 st 0.3.96 이상이어야 합니다.

• 그 장치는 워커가 일해 주는 장치에서 온 요청만 받습니다. 다른 장치에서 바꾸려 하면 거절합니다.
• 그 장치의 st가 오래되었으면 "st upgrade there"라며 거절합니다. 그 장치에서 st upgrade를 실행하세요.
• 이름은 장치가 아니라 라벨입니다. 워커의 이름을 보세요.

앱에서 보이는 것

다른 장치의 워커는 코디네이터 창 카드 안에 장치 아이콘과 이름이 붙은 채 나옵니다. 데스크탑 앱 0.1.33부터는 일을 맡긴 에이전트 아래에 놓이고, 그 에이전트 자신이 워커여도 마찬가지입니다. 워커가 있는 장치에서는 워커 창이 제자리에 있고 "home-macbook의 coordinator 워커"처럼 표시됩니다.

• 데스크탑 앱. 사이드바에서 다른 장치의 창 행을 끌어 놓아 데려옵니다(데스크탑 앱 0.1.31 이상). 화면에 어떻게 보이는지와 아직 안 되는 것은 데스크탑 앱 가이드의 다른 장치의 워커에 있습니다.
• 폰. 에이전트 차트는 다른 장치의 워커와 코디네이터도 같은 트리에 이어 그립니다. 폰에서 데려올 때 워커를 받지 않는 장치는 흐리게 나오고 "CI Mac은 다른 기기의 워커를 받지 않습니다. 그 기기에서 st orch accept-remote on을 실행하세요."라고 알려 줍니다. 장치의 st와 에이전트 훅 시트에는 다른 기기의 워커 받기: 켜짐(또는 꺼짐)이 나옵니다.
• 웹 터미널. Agents 카드와 에이전트 그래프가 계정의 다른 장치에 있는 에이전트도 보여 줍니다. 하나를 누르면 그 장치에서 그 창을 엽니다. 오프라인인 장치는 흐리게 나옵니다(st 0.3.92 이상).

놓아 주기

• 코디네이터 쪽에서(st worker release ci-mac/%7) 놓아 주면, 워커에게는 이제 누구의 워커도 아니라고 알리고, 코디네이터에게는 더 이상 일을 보내지 말라고 알리고, 실행(run)에서도 뺍니다.
• 워커의 장치에서(그 장치 그래프의 Release) 놓아 주면 워커에게만 알립니다. 코디네이터의 실행 목록에는 그대로 남습니다.

새 pane으로 옮긴 코디네이터

다른 장치의 워커는 코디네이터를 main-pc/%0처럼 이 장치의 pane id로 압니다. 이 장치의 tmux 서버가 내려갔다가 st가 세션을 되살리면 코디네이터는 %8 같은 다른 pane으로 돌아옵니다. st 0.3.88부터는 이렇게 됩니다.

• 코디네이터 쪽 st가 10초쯤 안에 옮겨 간 것을 알아채고, 다른 장치의 워커마다 코디네이터의 새 pane을 알립니다. 워커의 에이전트에게는 아무 말도 하지 않습니다. 그 장치에 닿지 않으면 1분마다 다시 시도합니다.
• 그 장치의 st가 오래되었으면 코디네이터 쪽 st가 워커를 놓아 줬다가 다시 데려옵니다.
• 알림을 받기 전까지 그 워커의 장치에서 st worker list를 보면 (parent gone; its coordinator is main-pc/%8 now)처럼 나옵니다. 코디네이터 쪽 장치의 st가 오래되었으면 아무것도 나오지 않습니다.
• 코디네이터 쪽의 st worker list --all은 이 장치의 모든 실행이 다른 장치에 둔 워커를 보여 주고, 코디네이터가 사라진 워커에 표시를 붙입니다.
• 사이드바에서는 코디네이터가 사라진 워커에 ⚠와 Release가 나옵니다(데스크탑 앱 0.1.33 이상, 웹 터미널은 st 0.3.88 이상).

한 장치 안에서 일어나는 같은 일은 tmux 재시작 뒤를 보세요.

거절 메시지

st가 이유와 할 일을 알려 줍니다.

보안

• 같은 계정의 장치만, 그리고 받는 장치가 accept-remote를 켰을 때만 됩니다.
• 그 장치의 에이전트는 권한 모드를 포함해 그 장치의 설정대로 실행됩니다. 코디네이터가 이를 정하지 않습니다.
• 컨트롤 플레인은 연결을 열어 주기만 합니다. 과제와 답은 두 장치의 st 사이에서 오갑니다.

아직 되지 않는 것

• 장치 사이에서 코드를 옮기지 못합니다. st worker diff, merge, pick은 이 장치의 워커에만 씁니다.
• 다른 장치에서는 순서가 있는 작업(st task --machine)을 쓸 수 없습니다.
• 워커가 그 장치에 남긴 결과물(스크린샷, 로그)로 가는 링크가 없습니다.
• 계정의 모든 장치를 그래프 하나로 볼 수 없습니다.

그때까지는 워커가 공유 git 원격 저장소에서 코드를 받고 올리게 하고, 과제에도 그렇게 적어 둡니다.

그 밖의 제약은 이렇습니다.

• 릴레이로만 연결되는 장치가 워커를 받을 수 있는지는 아직 확인되지 않았습니다.
• --split은 이 장치의 워커에만 씁니다. --fan에 --machine을 함께 주면 워커가 모두 그 장치에서 뜹니다.
• 다른 장치에서 데려온 팀장은 자기 위의 사슬을 코디네이터 쪽 장치까지만 압니다. 그래서 팀장이 그 장치에서 띄우는 워커는 그보다 위의 단계까지 따져 보지 않습니다.