--- name: file-download description: 폰의 Code SSH 앱으로 파일 직접 전송 — 마커를 출력하면 같은 SSH 세션으로 앱이 해당 파일(APK·아카이브·문서 등 임의 파일)을 받아 다운로드 폴더에 저장 --- # 파일 다운로드 (Code SSH 자동 다운로드) 폰의 Code SSH 앱이 이 터미널을 보고 있을 때, 파일을 폰으로 직접 푸시한다. 별도 서버·업로드 없이 **이미 열려 있는 SSH 세션**으로 전송된다. APK 배포, 빌드 산출물 전달, 문서·아카이브 공유 등 모든 파일에 쓸 수 있다. ## 요구사항 - 폰에 **Code SSH 1.13.0 이상** 설치 - 앱 설정의 **파일 다운로드 섹션 → "파일 다운로드" 토글 켜짐** (기본 꺼짐 — 반드시 사용자가 켜야 함. 1.17.2까지는 토글명이 "자동 다운로드"였음) ## 절차 (순서 중요) 1. **전송할 파일의 절대경로를 확정**한다. - 빌드 배포(대표 사용례): 프로젝트의 빌드 규칙(CLAUDE.md / README / Makefile)을 먼저 확인한다. 규칙이 없는 일반 Flutter 프로젝트의 기본값: ```bash flutter build apk --release --split-per-abi ``` 실기 배포는 arm64 슬라이스(`build/app/outputs/flutter-apk/*arm64*.apk`). 프로젝트 고유의 배포 스텝(루트 복사, 구버전 정리 등)이 있으면 그대로 따른다. - 일반 파일: 이미 존재하는 파일이면 그 경로를, 생성 작업이면 먼저 완료한다. 2. **사이드카 먼저, 마커 마지막** — 발화 경로는 환경에 따라 둘 중 하나: - **폰이 Claude 세션 페인을 tmux attach로 보는 구조(에이전트 사용 시 대부분)**: 도구 출력의 echo는 Claude TUI가 접을 수 있어 마커 줄이 폰 바이트 스트림에 아예 안 실릴 수 있다(2026-10-24 실측 — 무음 2회 후 3회째 성공). **페인 tty 직접 주입**이 확실한 경로다: ```bash # 폰이 보는 페인 tty 찾기 — ::1(릴레이) sshd가 붙은 tmux attach의 세션 tmux list-panes -a -F '#{session_name} tty=#{pane_tty} cmd=#{pane_current_command}' ps ax -o pid,ppid,tty,command | grep 'tmux attach' | grep -v grep echo "$FILE_ABSOLUTE_PATH" > ~/.code-ssh-last-download printf '\nCODE_SSH_DOWNLOAD v1\n' > /dev/<페인 tty> ``` 주입하면 내 TUI가 순간 오염되지만 자가 복구된다. - **일반 터미널(수동 사용·Makefile)**: 접힘 위험이 없으니 짧은 echo 2줄로 충분하다: ```bash echo "$FILE_ABSOLUTE_PATH" > ~/.code-ssh-last-download echo "CODE_SSH_DOWNLOAD v1" ``` 3. **여러 파일은 순차 전송** — 앱의 전송 래치는 앱 전체에 1개라 마커를 연달아 여러 번 내도 한 번에 하나만 실행된다. 이전 파일의 완료를 확인하고 다음 사이드카+마커를 낸다: ```bash lsof -nP <파일> # 앱의 cat 리더 = 전송 중. 리더가 사라지면 완료 ``` 릴레이 실측 ~2-5MB/s (27MB 12초 · 68MB 33초, 2026-10-28). ## 규칙 - 마커는 정확히 `CODE_SSH_DOWNLOAD`로 시작. 긴 빌드 로그에 묻히지 않도록 **마지막에 단독 출력**으로 낸다 (접힌 도구 출력은 마지막 몇 줄만 보인다). - 파일 **절대경로는 사이드카 파일(`~/.code-ssh-last-download`) 첫 줄에만** 쓴다. 터미널에 경로를 출력해선 안 된다 — 폰 화면 폭에서 TUI가 경로를 끊어 마커와 함께 쓸 수 없어서 경로 채널을 분리한 설계다. - 앱 측 검증: 절대경로 · 200MB 이하 · **사이드카 자체 mtime 5분 이내 — 대상 파일의 mtime은 게이트에 무관하다**(`maxSidecarAgeSec`, 2026-10-28 코드 확인). **파일 종류는 무제한**(APK·zip·pdf·이미지·영상 등). 어긋나면 조용히 무시된다(오탐 방어). - **재전송 dedup**: 앱은 프로세스당 `path|size|mtime` 키로 이미 받은 파일을 건너뛴다. 같은 파일을 다시 보내려면 `touch`로 mtime을 옮긴 뒤 사이드카+마커 (재빌드 산출물은 mtime이 저절로 움직여 새 키가 된다). - 성공하면 폰에 "파일 다운로드 완료" 알림 → 탭하면 다운로드 앱. APK의 경우 다운로드 앱에서 탭해 설치 — 설치 확인 대화상자는 사용자 몫 (앱이 임의 설치 권한을 요구하지 않음). ## 문제 해결 폰이 반응하지 않을 때 확인 순서: 1. 앱 설정의 "파일 다운로드" 토글이 켜져 있는가 2. Code SSH 앱 버전이 1.13.0 이상인가 3. 사이드카의 경로가 절대경로인가 4. **마커가 실제로 폰 바이트 스트림에 나갔는가** — Claude 세션이면 TUI 접힘을 의심한다. 페인 tty 주입으로 재발화하면 확실히 나간다 5. **폰이 화면 꺼짐/백그라운드면 마커를 받아도 전송이 포그라운드 복귀 시점에 실행된다**(2026-10-20 실측). "안 온다"고 판단하기 전에 폰을 깨워 1-2분 기다려볼 것 ## 수동 사용 (에이전트 없이) ```bash echo /path/to/file.zip > ~/.code-ssh-last-download && echo "CODE_SSH_DOWNLOAD v1" ``` 프로토콜은 누가 마커를 출력하든 동작하는 앱 레벨 계약이라 Makefile 타깃· 셸 alias로도 쓸 수 있다.