shellbase 0.13.5 → 0.14.0

package/README.md

@@ -158,11 +158,28 @@ Claude Code 가 화면을 꽉 채우고 있을 때 `git status` 같은 걸 잠
 - 모나코에서 **JS/TS 타입 기반 자동완성은 빠져 있어요** (그 기능 파일 하나가 6.6MB 라 웹 스토리지 한도를
   넘습니다). 색칠·단축키·검색은 모두 정상이에요.
 
-- 512KB 까지, **글자 파일만** 열려요 (사진·실행파일 같은 이진 파일은 자동으로 걸러집니다)
+- 512KB 까지, **글자 파일만** 열려요 (사진·동영상은 아래의 보기 창으로 열립니다)
 - 저장은 같은 폴더의 임시 파일에 먼저 쓴 뒤 교체해서, 저장 도중 끊겨도 원본이 깨지지 않아요
 - 파일 내용은 터미널 화면과 똑같이 세션 키로 암호화해서 주고받아요
 - 에디터는 **파일을 처음 열 때만 따로 내려받아요** — 터미널만 쓰면 그만큼 안 받습니다
 
+### 사진·동영상 보기 (0.14.0+)
+
+폴더 찾기에서 **사진(🖼)·동영상(🎬)·소리(🎵)·PDF(📕)** 를 탭하면 편집기 대신 **보기 창**이 열려서
+폰에서 그대로 보입니다. 동영상은 재생·되감기까지 돼요.
+
+- 열리는 형식: `png jpg gif webp avif bmp heic tif` · `mp4 mov m4v webm mkv avi` ·
+  `mp3 m4a aac wav ogg opus flac` · `pdf`
+- **64MB 까지**, 그리고 **3MB 가 넘으면 "받을까요?" 를 한 번 물어봐요** — 파일이 터미널 화면과
+  **같은 통로**로 오기 때문에, 큰 동영상을 잘못 누르면 그동안 터미널이 굼떠집니다
+- 받는 동안 진행 막대가 보이고 **그만두기**를 누르면 곧바로 멈춰요 (컴퓨터 쪽도 바로 손을 뗍니다)
+- 속도는 **초당 300KB 남짓**이에요 (실측) — 3MB 사진이면 10초쯤, 10MB 동영상이면 35초쯤
+- 사진은 눌러서 **원래 크기 ↔ 화면 맞추기**를 오갈 수 있어요
+- 파일은 32KB 조각으로 나눠 **세션 키로 암호화**해서 오고, 폰에서만 다시 하나로 붙습니다 —
+  중간에 저장되는 곳은 없어요
+- 브라우저가 못 여는 형식(아이폰 밖에서의 HEIC, mkv·avi 등)은 그렇게 알려주고, **경로를
+  터미널에 넣어주는 버튼**을 보여줘요 — 그 자리에서 `ffmpeg` 로 바꾸면 됩니다
+
 ### 폰에서 사진·스크린샷 첨부 (0.7.0+)
 
 폰 화면의 **클립(📎) 버튼**(PC 는 상단 바)으로 사진을 고르면, 사진이 **이 컴퓨터의
@@ -173,7 +190,7 @@ Claude Code 가 화면을 꽉 채우고 있을 때 `git status` 같은 걸 잠
 - **PC 는 스크린샷 파일을 터미널 위로 끌어다 놓으면(드래그&드롭)** 바로 첨부돼요 (📎 버튼은 폰 전용)
 - 스크린샷을 **복사해서 붙여넣기**(Ctrl+V) 해도 첨부돼요 (PC·폰 공통)
 - 사진은 보내기 전에 폰에서 **긴 변 1568px 로 줄여서** 올라가요(전송이 빠르고 인식 정확도는 그대로)
-- 저장된 사진은 **7일이 지나면 자동으로 지워져요**, 파일 권한은 본인만 읽기(600)
+- 저장된 사진은 **하루가 지나면 자동으로 지워져요**, 파일 권한은 본인만 읽기(600)
 - 사진도 터미널 화면과 똑같이 **세션 키로 암호화**해서 전송돼요
 
 ### 폰에서 마이크로 말하기 (음성 → 글자)
@@ -207,6 +224,23 @@ Claude Code 가 화면을 꽉 채우고 있을 때 `git status` 같은 걸 잠
 > 끄는 건 프로세스가 계속 살아있으니 그대로 꺼져요. 컨테이너를 완전히 내리려면 컴퓨터에서
 > `docker stop shellbase-agent` 를 쓰세요.
 
+### 터미널은 셸 시작 파일(rc)을 읽지 않아요
+
+폰에서 여는 터미널은 `~/.bashrc`(zsh 는 `~/.zshrc`) 같은 **시작 파일을 읽지 않고** 맨 셸로 뜹니다
+(`bash --norc --noprofile`, `zsh --no-rcs`, `fish --no-config`, PowerShell `-NoProfile`).
+
+시작 파일은 그 컴퓨터 앞에 앉은 사람이 자기 편하려고 꾸며둔 것이라, 그 컴퓨터에만 있는 명령을
+가리키는 별칭이 흔합니다. 그게 딸려오면 다른 환경에서 명령이 엉뚱하게 깨져요
+(`bash: gnuls: command not found` 같은 증상).
+
+- 대신 **에이전트를 켤 때의 환경변수(PATH 포함)를 그대로 물려받습니다.** 그래서 `shellbase` 를
+  실행할 수 있던 셸에서 켰다면 `claude` 같은 명령은 그대로 잘 찾습니다.
+- 시작 파일에서만 붙던 것(conda 초기화, 개인 별칭, 특정 도구 경로)은 안 따라옵니다.
+  필요하면 그 줄을 **에이전트를 켜는 쪽**에 넣거나, 세션 안에서 그때그때 불러 쓰세요
+  (예: `source ~/miniconda3/etc/profile.d/conda.sh`).
+- 예전처럼 시작 파일을 읽게 하려면 `SHELLBASE_SHELL_RC=1 shellbase start …` 로 켜세요.
+- 프롬프트는 꾸밈 없는 기본값(`bash-5.2$`)이 됩니다.
+
 ## 참고
 
 - `node-pty` 를 사용해서 설치 시 네이티브 모듈을 컴파일합니다. macOS는 Xcode Command Line Tools,

package/dist/agent.js

@@ -11,12 +11,13 @@ const { Terminal: HeadlessTerminal } = requireCjs('@xterm/headless');
 import { requireClient } from './auth.js';
 import { TERMINAL_CATEGORY, CONTROL_TOKEN, SESSION_ENV } from './config.js';
 import { startSleepGuard, stopSleepGuard } from './sleep-guard.js';
-import { encryptFrame, decryptFrame, generateFrameKey } from './crypto.js';
+import { encryptFrame, encryptBytes, decryptFrame, generateFrameKey, compress } from './crypto.js';
 import { registerDevice, heartbeatDevice, unregisterDevice, listOnlineNames, renameDevice, markSessionDone, keepDevice, } from './devices.js';
 import { promptApproval } from './prompt.js';
 import { touchRecentDir } from './recent-dirs.js';
 import { listDirs, createEntry, deleteEntry, renameEntry } from './browse.js';
 import { readTextFile, writeTextFile, chunkContent } from './files.js';
+import { MediaReader, statMedia } from './media.js';
 import { AUDIO_CHUNK_TTL_MS, MAX_AUDIO_BASE64, STT_SETUP_HINT, findSttServer, transcribe, } from './stt.js';
 import { loadOpenSessions, saveOpenSessions } from './open-sessions.js';
 import { pushSessionDone } from './push.js';
@@ -39,19 +40,40 @@ const RESTORE_SCROLLBACK_LINES = 300;
 // (빌드 로그·Claude Code 전체 다시 그리기 등) 프레임이 한도를 넘어 통째로 거부되고, 그 세션은 그 뒤로
 // 아무 화면도 못 받는다. 폰에는 "검은 화면에 글자 하나 없는" 상태로 보인다 (제보).
 //
-// 기준은 "글자 수" 가 아니라 UTF-8 **바이트 수** 다. 예전엔 12288 글자로 잘랐는데, 한글은 한 글자가
-// 3바이트라 같은 12288 글자라도 실제 크기가 3배까지 달라져서 어떤 때는 너무 크고(거부 위험) 어떤 때는
-// 필요 이상으로 잘게 쪼개졌다(조각 수가 늘수록 느리고 유실 확률도 올라간다).
-// 40KB → 암호화(base64) 후 약 55KB 로, 64KB 한도에 아직 여유가 있다. 이 크기면 화면 복원
-// (300줄 기준 35KB 안팎)이 **대개 한 번에** 다 담긴다 — 조각이 둘 이상이면 "지우기" 만 먼저
-// 도착하고 내용이 뒤따라오는 사이가 그대로 검은 화면으로 보이므로, 한 조각으로 끝내는 게 가장 좋다.
-const FRAME_BUDGET_BYTES = 40 * 1024;
+// 조각은 적을수록 좋다. 조각이 둘 이상이면 "화면 지우기" 만 먼저 도착하고 내용이 뒤따라오는
+// 사이가 그대로 검은 화면으로 보이고, 유실될 확률도 조각 수만큼 늘어난다.
+//
+// 기준은 **실제로 통로에 실리는 크기**다. 예전에는 원본을 정해진 바이트 수(40KB)로 자르고
+// "암호화하면 55KB쯤 되겠지" 하고 짐작했는데, 압축이 들어오면 그 짐작이 아예 성립하지 않는다
+// (얼마나 줄어들지 미리 알 수 없다). 짐작이 크면 한도를 넘어 거부되고(=검은 화면), 작으면
+// 쓸데없이 잘게 쪼개진다(=느려짐). 그래서 아래 packOutput 이 압축·암호화까지 실제로 해보고
+// 이 값과 재본다 — 짐작할 일이 없어지고, 압축이 잘 되는 화면은 통째로 한 조각에 담긴다.
+// 64KB 한도에서 JSON 겉포장(kind/to/seq 등) 몫을 빼고 여유를 둔 값.
+const WIRE_BUDGET_BYTES = 56 * 1024;
 // 서버가 재는 기준이 예상과 다를 수도 있으니, "너무 크다" 고 거부당하면 스스로 절반씩 줄인다.
 // 이 아래로는 줄이지 않는다 (더 줄여도 안 되면 크기 문제가 아니다).
-const MIN_FRAME_BUDGET_BYTES = 8 * 1024;
+const MIN_WIRE_BUDGET_BYTES = 8 * 1024;
+// 이보다 작은 조각은 압축하지 않는다. gzip 은 머리말만 20바이트쯤 되므로 타자 한 글자가
+// 되비치는 것(수십 바이트)까지 압축하면 오히려 커진다. 큰 화면에서만 이득을 챙기면 된다.
+const GZIP_MIN_BYTES = 512;
+// 조각이 한도를 넘을 때 반으로 잘라 다시 재보는 횟수 상한 (2^12 = 4096 조각이면 어떤 경우도 넘친다).
+// 상한이 없으면 이상한 입력에서 영영 쪼개고 있을 수 있다.
+const MAX_PACK_DEPTH = 12;
 // 전송이 막혀 밀린 출력이 이만큼을 넘으면, 밀린 것을 하나하나 따라 보내는 대신 지금 화면을 통째로
 // 다시 보낸다 — 사용자가 보게 될 최종 화면은 어차피 같고, 훨씬 빨리 따라잡는다.
 const MAX_PENDING_OUTPUT = 256 * 1024;
+// 사진·동영상을 보낼 때 서버 답을 안 기다리고 잇달아 부치는 조각 수.
+// 하나씩 답을 기다리면 조각마다 왕복 한 번(실측 276ms)이 그대로 지연이 되어 3MB 사진에 몇 분이
+// 걸린다. 그렇다고 통째로 부치면 터미널 화면이 그 뒤로 밀린다 — 통로를 세션들이 나눠 쓰기 때문.
+//
+// **8이면 충분하다는 것은 실측으로 확인했다** (3MB 사진, 2026-08-21):
+// 16·32 로 넓혀도 빨라지지 않았다 (229 → 173 → 183KB/s). 병목이 "답을 기다리는 시간" 이 아니라
+// **통로의 굵기**라는 뜻이다. 그러니 더 넓혀봐야 터미널만 뒤로 밀린다.
+// 올리기만 하는 속도는 394KB/s — 폰은 받는 길이 따로라 실제로는 이쪽에 가깝다.
+const MEDIA_WINDOW = 8;
+// 조각 하나가 실패했을 때 다시 부쳐보는 횟수. 이진 파일은 한 조각만 빠져도 아예 안 열리므로
+// 글자 파일보다 끈질기게 다시 보낸다.
+const MEDIA_RETRIES = 3;
 // 출력 전송 최소 간격. "마지막 전송 후 이 간격이 지났으면 바로 보내고, 아니면 그만큼만 기다렸다 모아서
 // 보낸다"(leading-edge 스로틀). 예전엔 문서의 "최소 100ms" 를 보수적으로 잡아 120ms 로 뒀는데, 실측해보니
 // 서버가 40회 연속 전송도 거부 없이 받아줬고 이 값이 타이핑 체감 지연의 주범이었음(입력·출력 양쪽에서
@@ -75,12 +97,29 @@ const PENALTY_INTERVAL_MS = 250;
 //
 // 그래서 고정값을 버리고 **실제 왕복 시간을 재서 스스로 조절**한다. 잘 나가면 조금씩 좁히고,
 // 실패하면 크게 벌린다(AIMD). 세션이 하나면 예전만큼 빠르고, 여러 개여도 스스로 안전한 값을 찾는다.
-const CHANNEL_GAP_MIN_MS = 12;
+//
+// 그런데 "간격 하나"로만 조절하는 것에도 한계가 있었다. 12ms 는 **초당 83건** 인데 서버 한도가
+// 초당 100건이라, 세션 하나가 띄엄띄엄 보낼 때는 남아돌지만 세션 셋이 쉬지 않고 보내면 그 83건이
+// 그대로 꽉 찬 상태로 계속된다 — 한도 코앞에 붙어서 달리는 셈이라 조금만 흔들려도 거부당했다.
+// 반대로 타자를 칠 때는 12ms 조차 아깝다(글자 하나가 나가는 데 그만큼 밀린다).
+//
+// 그래서 "**몰아 보내기 여유 + 꾸준한 속도**" 두 가지로 나눠 잡는다(토큰 버킷).
+//  · 조용하다가 갑자기 보낼 때는 여유분만큼 **간격 없이** 곧바로 나간다 (타자 체감이 좋아진다)
+//  · 그 여유를 다 쓰면 그때부터 꾸준한 속도로 묶인다 (한도에 붙어 달리지 않는다)
+// 즉 예전보다 순간적으로는 더 빠르고, 오래 이어질 때는 더 안전하다.
+const CHANNEL_GAP_MIN_MS = 20;
 const CHANNEL_GAP_MAX_MS = 200;
-const CHANNEL_GAP_START_MS = 12;
-// 실패했을 때 간격을 몇 배로 벌릴지 / 잘 나갈 때 얼마씩 좁힐지
+const CHANNEL_GAP_START_MS = 20;
+// 규정 속도보다 이만큼 앞질러 나가는 것은 봐준다 = 몰아 보낼 수 있는 여유.
+// 400ms 면 최소 간격 기준으로 20조각쯤을 간격 없이 연달아 부칠 수 있다. 조용했던 만큼만 쌓인다.
+const CHANNEL_BURST_MS = 400;
+// 실패했을 때 간격을 몇 배로 벌릴지
 const CHANNEL_GAP_GROW = 2;
-const CHANNEL_GAP_SHRINK_MS = 1;
+// 좁히는 것은 **시간**으로 한다. 예전에는 성공 한 번에 1ms 씩 좁혔는데, 200ms 까지 벌어지면
+// 되돌아오는 데 성공 188번이 필요했다 — 그 뒤로 뜸해진 세션은 한참을 느린 채로 남았다.
+// 이제는 마지막 실패로부터 이만큼 지날 때마다 한 단계씩 좁힌다 (조용해도 저절로 회복한다).
+const CHANNEL_RECOVER_MS = 5_000;
+const CHANNEL_GAP_SHRINK = 0.7;
 // 슬롯 예약이 이만큼 넘게 밀렸으면 = 통로가 막혔다는 뜻. 이때는 프레임을 **더 부치지 않고**
 // 출력을 계속 모은다(coalescing). 터미널은 "최종 화면"만 맞으면 되므로 중간 프레임을 합쳐도
 // 잃는 게 없다 — 오히려 막힌 통로에 프레임을 밀어 넣지 않아서 훨씬 빨리 따라잡는다.
@@ -114,23 +153,14 @@ const IDLE_MS = 4_000; // 이만큼 조용하면 "끝났다" 로 본다
 // 시간만 보면 "천천히 오래 타이핑한 것" 도 일하는 중으로 잘못 본다(글자마다 화면에 되비치므로).
 // 실제 작업은 출력량이 비교가 안 되게 많아서(회전 표시·중간 결과·빌드 로그) 양으로 걸러낸다.
 const BUSY_MIN_BYTES = 2048;
-// 보낼 글을 프레임 크기(UTF-8 바이트)에 맞춰 조각낸다.
-// 글자 중간에서 자르면 그 글자가 깨지므로(한글은 3바이트, 이모지는 4바이트) 반드시 글자 경계에서 자른다.
-function chunkByBytes(text, budget) {
-    const buf = Buffer.from(text, 'utf8');
-    if (buf.length <= budget)
-        return text ? [text] : [];
-    const parts = [];
-    let start = 0;
-    while (start < buf.length) {
-        let end = Math.min(buf.length, start + budget);
-        // UTF-8 에서 이어지는 바이트는 10xxxxxx 로 시작한다 — 거기서 끊으면 글자가 반쪽이 된다
-        while (end > start + 1 && end < buf.length && (buf[end] & 0xc0) === 0x80)
-            end--;
-        parts.push(buf.toString('utf8', start, end));
-        start = end;
-    }
-    return parts;
+// 반으로 자를 자리. 이모지처럼 두 칸을 차지하는 글자의 뒷짝 바로 앞에서 끊으면 글자가 깨지므로
+// 그때는 한 칸 옮긴다. (자바스크립트 글자열은 UTF-16 이라 0xDC00~0xDFFF 가 '뒷짝' 이다)
+function splitPoint(text) {
+    let mid = text.length >> 1;
+    const code = text.charCodeAt(mid);
+    if (code >= 0xdc00 && code <= 0xdfff)
+        mid += 1;
+    return Math.min(Math.max(mid, 1), text.length - 1);
 }
 // 폰의 폴더 탐색기를 열 때 "지금 셸이 있는 폴더"에서 시작하려면, 세션을 시작한 폴더가 아니라
 // 셸 프로세스의 실제 작업 폴더를 봐야 한다(사용자가 cd 로 옮겨 다니므로). 리눅스는 /proc 로 바로 알 수 있고,
@@ -156,6 +186,40 @@ function resolveShell() {
         return process.env.COMSPEC ?? 'powershell.exe';
     return process.env.SHELL ?? '/bin/bash';
 }
+// 폰에서 여는 터미널은 셸의 '시작 파일'(bash 의 ~/.bashrc, zsh 의 ~/.zshrc 같은 것)을 읽지 않는다.
+// 시작 파일은 그 컴퓨터의 사람이 앉아서 쓰려고 꾸며둔 것이라, 그 컴퓨터에만 있는 명령을 가리키는
+// 별칭이 흔하다. 그게 그대로 딸려오면 엉뚱한 곳에서 명령이 깨진다 (`gnuls: command not found`
+// 사건 — PLAN.md §8.12). 그래서 껍데기 셸만 띄우고, 실행에 필요한 경로·환경변수는 시작 파일이
+// 아니라 **에이전트를 켤 때의 환경**을 그대로 물려주는 쪽으로 통일한다 (sessionEnv 참고).
+// 예전처럼 시작 파일을 읽게 하려면 SHELLBASE_SHELL_RC=1 을 주고 에이전트를 다시 시작하면 된다.
+function shellArgs(shell) {
+    if (process.env.SHELLBASE_SHELL_RC)
+        return [];
+    const name = path.basename(shell).toLowerCase();
+    // 로그인용 파일(~/.profile 등)은 애초에 로그인 셸일 때만 읽히지만, 혹시 몰라 같이 막아둔다
+    if (name.includes('bash'))
+        return ['--norc', '--noprofile'];
+    if (name.includes('zsh'))
+        return ['--no-rcs'];
+    if (name.includes('fish'))
+        return ['--no-config'];
+    if (name.includes('pwsh') || name.includes('powershell'))
+        return ['-NoProfile'];
+    // sh·dash·ksh 는 이런 옵션이 없고 $ENV / $BASH_ENV 에 적힌 파일을 읽는다 — 그건 sessionEnv 에서 지운다
+    return [];
+}
+// 이 터미널이 어느 세션인지 환경변수로 심어둔다. 이 안에서 실행되는 모든 것(Claude Code,
+// 그리고 Claude Code 가 끝날 때 실행하는 `shellbase notify`)이 그대로 물려받으므로,
+// 알림이 왔을 때 어느 세션인지 바로 알 수 있다 (notify.ts).
+function sessionEnv(deviceId) {
+    const env = { ...process.env, [SESSION_ENV]: deviceId };
+    if (!process.env.SHELLBASE_SHELL_RC) {
+        // sh·dash·ksh 계열은 옵션 대신 이 변수에 적힌 파일을 시작하면서 읽는다 — 같이 비운다
+        delete env.ENV;
+        delete env.BASH_ENV;
+    }
+    return env;
+}
 function readControl(data, key) {
     if (typeof data !== 'string')
         return null;
@@ -243,28 +307,44 @@ export async function runAgent(options) {
     // 여기서 지킨다. 세션마다 따로 간격을 지켜도 세션이 여럿이면 채널로는 한도를 넘고, 넘는 순간부터
     // ack 이 안 돌아와 그 출력이 밀리고 화면이 멈춘다.
     //
-    // 간격은 **고정하지 않는다**. 잘 나가면 조금씩 좁히고(–1ms), 실패하면 두 배로 벌린다.
+    // 간격은 **고정하지 않는다**. 실패하면 두 배로 벌리고, 실패 없이 시간이 지나면 스스로 좁힌다.
     // 고정값은 "세션 하나에서 잰 값"이라 세션이 늘어나는 순간 그대로 무너졌다 (§상수 주석 참고).
     let channelGapMs = CHANNEL_GAP_START_MS;
+    let lastWidenAt = 0;
+    // 좁히기는 시간이 지나면 저절로 된다 — 프레임이 오가는 길목에서 확인한다.
+    // (예전에는 "성공 한 번에 1ms" 라, 뜸해진 세션은 영영 느린 채로 남았다)
     const easeChannelGap = () => {
-        if (channelGapMs > CHANNEL_GAP_MIN_MS) {
-            channelGapMs = Math.max(CHANNEL_GAP_MIN_MS, channelGapMs - CHANNEL_GAP_SHRINK_MS);
-        }
+        if (channelGapMs <= CHANNEL_GAP_MIN_MS)
+            return;
+        const now = Date.now();
+        if (now - lastWidenAt < CHANNEL_RECOVER_MS)
+            return;
+        lastWidenAt = now;
+        channelGapMs = Math.max(CHANNEL_GAP_MIN_MS, Math.round(channelGapMs * CHANNEL_GAP_SHRINK));
+        console.error(`통로가 한동안 조용해서 전송 간격을 ${channelGapMs}ms 로 되돌렸어요`);
     };
     const widenChannelGap = (why) => {
+        lastWidenAt = Date.now();
         if (channelGapMs >= CHANNEL_GAP_MAX_MS)
             return;
         channelGapMs = Math.min(CHANNEL_GAP_MAX_MS, Math.max(1, channelGapMs) * CHANNEL_GAP_GROW);
         console.error(`통로가 막혀서 전송 간격을 ${channelGapMs}ms 로 벌렸어요 (${why})`);
     };
+    // "이 시각 이후여야 규정 속도에 맞는다" 는 가상의 시계. 부칠 때마다 간격만큼 앞으로 간다.
+    // 조용히 있으면 이 시계가 현재보다 뒤처지는데, **그 뒤처진 만큼이 곧 몰아 보낼 여유**다.
     let nextSlotAt = 0;
-    // 지금 슬롯 예약이 얼마나 미래로 밀려 있는지. 이게 크면 = 통로가 막혔다는 뜻이고,
-    // 그때 프레임을 더 부치면 상황이 나빠지기만 한다 (예전에 3초씩 밀리던 직접 원인).
-    const slotLagMs = () => Math.max(0, nextSlotAt - Date.now());
+    // 지금 예약이 얼마나 미래로 밀려 있는지 (몰아 보내기 여유를 빼고 센다). 이게 크면 = 통로가
+    // 막혔다는 뜻이고, 그때 프레임을 더 부치면 상황이 나빠지기만 한다 (3초씩 밀리던 직접 원인).
+    const slotLagMs = () => Math.max(0, nextSlotAt - CHANNEL_BURST_MS - Date.now());
     const takeSendSlot = async () => {
         const now = Date.now();
-        const at = Math.max(now, nextSlotAt);
-        nextSlotAt = at + channelGapMs;
+        // 규정상 나갈 시각. 조용했으면 지금이고, 몰아 보내는 중이면 앞선 것들 뒤로 밀린다.
+        const due = Math.max(now, nextSlotAt);
+        nextSlotAt = due + channelGapMs;
+        // 규정보다 CHANNEL_BURST_MS 만큼 앞질러 나가는 것은 봐준다 — 조각 몇 개는 간격 없이 곧바로
+        // 나가고, 여유를 다 쓴 뒤에야 꾸준한 속도로 묶인다.
+        // (예약을 **부르는 즉시** 잡아두므로 부른 순서 = 나가는 순서는 그대로 지켜진다)
+        const at = Math.max(now, due - CHANNEL_BURST_MS);
         if (at > now)
             await new Promise((resolve) => setTimeout(resolve, at - now));
     };
@@ -298,17 +378,42 @@ export async function runAgent(options) {
         session.sendChain = next.then(() => undefined, () => undefined);
         return next;
     };
-    // 실제로 쓰는 조각 크기. 서버가 "너무 크다" 고 거부하면 절반으로 줄여서 스스로 맞춘다 —
-    // 크기 때문에 거부당하는 것은 다시 보내도 똑같이 거부되므로(= 검은 화면이 영영 안 풀린다),
-    // 재시도 전에 반드시 크기를 줄여야 한다.
-    let frameBudget = FRAME_BUDGET_BYTES;
-    const shrinkFrameBudget = (why) => {
-        if (frameBudget <= MIN_FRAME_BUDGET_BYTES)
+    // 실제로 쓰는 조각 크기 (통로에 실리는 크기 기준). 서버가 "너무 크다" 고 거부하면 절반으로
+    // 줄여서 스스로 맞춘다 — 크기 때문에 거부당하는 것은 다시 보내도 똑같이 거부되므로
+    // (= 검은 화면이 영영 안 풀린다), 재시도 전에 반드시 크기를 줄여야 한다.
+    let wireBudget = WIRE_BUDGET_BYTES;
+    const shrinkWireBudget = (why) => {
+        if (wireBudget <= MIN_WIRE_BUDGET_BYTES)
             return false;
-        frameBudget = Math.max(MIN_FRAME_BUDGET_BYTES, Math.floor(frameBudget / 2));
-        console.error(`조각 크기를 ${Math.round(frameBudget / 1024)}KB 로 줄였어요 (${why})`);
+        wireBudget = Math.max(MIN_WIRE_BUDGET_BYTES, Math.floor(wireBudget / 2));
+        console.error(`조각 크기를 ${Math.round(wireBudget / 1024)}KB 로 줄였어요 (${why})`);
         return true;
     };
+    // 보낼 글을 프레임 조각들로 만든다 — **압축·암호화까지 실제로 해보고 크기를 재서** 나눈다.
+    //
+    // 압축을 넣으면 "원본 몇 바이트로 자를까" 는 답이 없는 질문이 된다. 같은 40KB라도 색이 촘촘한
+    // 화면과 회전 표시만 도는 화면은 압축 후 크기가 열 배 넘게 차이 난다. 짐작해서 자르면 크게
+    // 잡을 땐 한도를 넘어 통째로 거부되고(폰은 새까만 화면), 작게 잡을 땐 한 조각이면 될 것을
+    // 다섯 조각으로 쪼갠다(조각 사이 틈 = 검은 화면, 유실 확률도 조각 수만큼).
+    //
+    // 그래서 짐작하지 않는다. 통째로 담아보고, 안 들어가면 반으로 잘라 다시 담아본다.
+    // 잘 압축되는 화면은 그대로 **한 조각**으로 끝난다 (실측: 25KB 출력 → 7KB, 약 4.8배).
+    const packOutput = (session, text) => {
+        const pack = (part, depth) => {
+            // 타자 한 글자가 되비치는 것까지 압축하면 머리말 때문에 오히려 커진다 — 큰 것만 압축한다
+            const useGz = session.gzipOk && Buffer.byteLength(part, 'utf8') >= GZIP_MIN_BYTES;
+            const data = useGz
+                ? encryptBytes(compress(part), session.frameKey)
+                : encryptFrame(part, session.frameKey);
+            // 한 글자까지 줄여도 안 들어가면 더 쪼갤 수가 없다 — 그냥 보내고 결과에 맡긴다
+            if (data.length <= wireBudget || part.length <= 1 || depth >= MAX_PACK_DEPTH) {
+                return [useGz ? { data, gz: true } : { data }];
+            }
+            const cut = splitPoint(part);
+            return [...pack(part.slice(0, cut), depth + 1), ...pack(part.slice(cut), depth + 1)];
+        };
+        return text ? pack(text, 0) : [];
+    };
     // 지금까지 나온 출력이 '보이지 않는 터미널' 에 다 반영되기를 기다린다.
     // (xterm 은 받은 글자를 곧바로가 아니라 조금 뒤에 처리한다 — 실측 확인)
     const drainScreen = (session) => new Promise((resolve) => {
@@ -341,7 +446,8 @@ export async function runAgent(options) {
         const results = await Promise.allSettled(parts.map((part, index) => sendFrame({
             kind: 'output',
             to: session.deviceId,
-            data: encryptFrame(part, session.frameKey),
+            data: part.data,
+            ...(part.gz ? { gz: true } : {}),
             // 복원 조각임을 표시해서, 폰이 다 모은 뒤 한 번에 그리게 한다 (검은 화면 방지)
             seq: index,
             total: parts.length,
@@ -355,7 +461,7 @@ export async function runAgent(options) {
             const message = String(reason?.message ?? reason);
             console.error(`출력 전송 실패 (${sent}/${parts.length} 조각만 나감):`, message);
             if (/too large|TOO_LARGE|size|크기/i.test(message))
-                shrinkFrameBudget(message);
+                shrinkWireBudget(message);
             session.sendPenaltyUntil = Date.now() + SEND_PENALTY_MS;
         }
         return sent;
@@ -384,15 +490,17 @@ export async function runAgent(options) {
         // 없다가 한꺼번에 쏟아지는 것처럼 보였다 — "타자가 2초 뒤에 몰아서 보인다" 의 정체.
         await enqueueSend(session, async () => {
             try {
-                // 프레임 한도를 넘지 않도록 나눠 보낸다 (한 덩이로 보내면 통째로 거부돼 화면이 멈춘다)
-                const parts = chunkByBytes(pending, frameBudget);
+                // 프레임 한도를 넘지 않도록 나눠 보낸다 (한 덩이로 보내면 통째로 거부돼 화면이 멈춘다).
+                // 압축이 되는 폰이면 대개 한 조각으로 끝난다 — 조각이 적을수록 빠르고 덜 유실된다.
+                const parts = packOutput(session, pending);
                 session.inFlight += parts.length;
                 // send() 를 부르는 순간 이미 통로로 나간다. 부른 순서 = 나가는 순서라서(실측 확인)
                 // 답을 기다리지 않아도 조각이 뒤섞이지 않는다.
                 const results = parts.map((part) => sendFrame({
                     kind: 'output',
                     to: session.deviceId,
-                    data: encryptFrame(part, session.frameKey),
+                    data: part.data,
+                    ...(part.gz ? { gz: true } : {}),
                 }));
                 void Promise.allSettled(results)
                     .then((settled) => {
@@ -405,7 +513,7 @@ export async function runAgent(options) {
                     const message = String(reason?.message ?? reason);
                     console.error(`출력 전송 실패 (${sent}/${parts.length} 조각만 나감):`, message);
                     if (/too large|TOO_LARGE|size|크기/i.test(message))
-                        shrinkFrameBudget(message);
+                        shrinkWireBudget(message);
                     session.sendPenaltyUntil = Date.now() + SEND_PENALTY_MS;
                     // 못 간 것을 다시 보내는 대신 **화면을 통째로 다시 맞춘다**.
                     // 답을 기다리지 않고 잇달아 부치기 때문에, 실패를 알게 된 시점에는 그 뒤의 출력이
@@ -498,7 +606,7 @@ export async function runAgent(options) {
                 }
                 // 화면을 먼저 지우고(2J·3J) 복원 내용을 보내야, 폰에 남아있던 예전 화면과 섞이지 않는다
                 const payload = `\x1b[H\x1b[2J\x1b[3J${snapshot}`;
-                const parts = chunkByBytes(payload, frameBudget);
+                const parts = packOutput(session, payload);
                 const sent = await enqueueSend(session, () => sendParts(session, parts));
                 if (sent < parts.length) {
                     // 화면을 지우라는 첫 조각만 도착하고 내용이 끊긴 상태 = 폰에는 **새까만 화면**만 남는다.
@@ -536,7 +644,7 @@ export async function runAgent(options) {
         // 두 번 연달아 실패하면 이유가 뭐라고 적혀 있든 크기부터 의심한다 — 같은 크기로 계속
         // 다시 보내봐야 같은 이유로 막히고, 그동안 폰은 계속 새까만 화면이다.
         if (session.restoreFails >= 2)
-            shrinkFrameBudget('화면 복원이 거듭 실패');
+            shrinkWireBudget('화면 복원이 거듭 실패');
         console.error(`화면 복원이 중간에 끊겼어요 ("${session.name}") — ${wait}ms 뒤 다시 보낼게요.`);
         session.restoreRetry = setTimeout(() => {
             session.restoreRetry = null;
@@ -674,15 +782,12 @@ export async function runAgent(options) {
             name: explicitName ?? (temporary ? `${defaultName(cwd)} (임시)` : defaultName(cwd)),
             cwd,
             rowId: '',
-            pty: pty.spawn(shell, [], {
+            pty: pty.spawn(shell, shellArgs(shell), {
                 name: 'xterm-256color',
                 cols: 80,
                 rows: 24,
                 cwd,
-                // 이 터미널이 어느 세션인지 환경변수로 심어둔다. 이 안에서 실행되는 모든 것(Claude Code,
-                // 그리고 Claude Code 가 끝날 때 실행하는 `shellbase notify`)이 그대로 물려받으므로,
-                // 알림이 왔을 때 어느 세션인지 바로 알 수 있다 (notify.ts).
-                env: { ...process.env, [SESSION_ENV]: deviceId },
+                env: sessionEnv(deviceId),
             }),
             screen: new HeadlessTerminal({
                 cols: 80,
@@ -714,6 +819,9 @@ export async function runAgent(options) {
             hookSeen: false,
             temporary,
             viewerSeenAt: Date.now(),
+            // 폰이 접속하면서 "압축 읽을 수 있다" 고 알려주기 전까지는 압축하지 않는다
+            gzipOk: false,
+            mediaId: null,
         };
         session.screen.loadAddon(session.serializer);
         session.pty.onData((data) => {
@@ -880,6 +988,13 @@ export async function runAgent(options) {
         // 폰에서 온 프레임 = 누군가 이 세션을 보고 있다는 뜻 (임시 터미널 정리·출력 게이트에 쓴다)
         const wasUnwatched = !hasViewer(session);
         session.viewerSeenAt = Date.now();
+        // 압축된 화면을 읽을 수 있는 폰인지. 접속할 때(connect_request)는 **그 폰이 말한 그대로** 맞춘다 —
+        // 옛 폰이 새로 붙으면 압축을 꺼야 하기 때문이다(못 읽는 폰에 보내면 화면이 통째로 깨진다).
+        // 그 밖의 프레임에서는 켜기만 한다(핑·크기변경에는 이 표시가 없을 수 있으므로 끄면 안 된다).
+        if (frame.kind === 'connect_request')
+            session.gzipOk = frame.gzOk === true;
+        else if (frame.gzOk)
+            session.gzipOk = true;
         // 안 보는 동안에는 실시간 프레임을 만들지 않으므로(pty.onData 참고), 다시 보기 시작하면
         // 그 사이 화면이 어떻게 바뀌었는지 알 길이 없다 — 지금 화면을 통째로 보내 맞춰준다.
         // connect_request 는 아래에서 어차피 복원하므로 여기서 두 번 하지 않는다.
@@ -1025,6 +1140,96 @@ export async function runAgent(options) {
                 console.log(`📱 폰에서 파일을 저장했어요: ${filePath}`);
             return;
         }
+        // 폰에서 사진·동영상·소리 파일 보기 — **두 걸음**으로 나눠서 준다.
+        //   ① { path } 만 오면 "무슨 파일이고 얼마나 큰지"(media_meta)만 알려준다
+        //   ② 폰이 { path, mid, start: true } 로 다시 물어야 그때 조각을 보낸다
+        // 한 걸음으로 하면 동영상을 잘못 누른 순간 수십 MB 가 통로로 쏟아진다. 크기를 먼저 알려주면
+        // 폰이 "40MB 예요, 받을까요?" 를 물어본 뒤에 시작할 수 있다.
+        if (frame.kind === 'read_media') {
+            const control = readControl(frame.data, session.frameKey);
+            if (!control || typeof control.path !== 'string')
+                return;
+            const filePath = control.path;
+            const mid = typeof control.mid === 'string' ? control.mid : '';
+            const fail = (reason) => void send({
+                kind: 'media_error',
+                to: session.deviceId,
+                data: encryptFrame(JSON.stringify({ path: filePath, mid, reason }), session.frameKey),
+            });
+            // 「그만두기」 — 보내던 것을 멈추기만 한다 (보내는 쪽이 조각마다 이 표를 확인한다)
+            if (control.stop) {
+                if (!mid || session.mediaId === mid)
+                    session.mediaId = null;
+                return;
+            }
+            const info = statMedia(filePath);
+            if (!info.ok) {
+                fail(info.reason);
+                return;
+            }
+            if (!control.start) {
+                void send({
+                    kind: 'media_meta',
+                    to: session.deviceId,
+                    data: encryptFrame(JSON.stringify({
+                        path: filePath,
+                        mid,
+                        mime: info.mime,
+                        kind: info.kind,
+                        size: info.size,
+                        total: info.total,
+                    }), session.frameKey),
+                });
+                return;
+            }
+            // 새 받기가 시작되면 앞서 보내던 것은 스스로 멈춘다 (표가 바뀌었으므로)
+            session.mediaId = mid;
+            void (async () => {
+                let reader;
+                try {
+                    reader = new MediaReader(info);
+                }
+                catch (err) {
+                    fail(`파일을 열지 못했어요: ${err.message}`);
+                    return;
+                }
+                try {
+                    for (let from = 0; from < info.total; from += MEDIA_WINDOW) {
+                        if (session.mediaId !== mid || session.closing)
+                            return;
+                        const to = Math.min(from + MEDIA_WINDOW, info.total);
+                        let pending = [];
+                        for (let index = from; index < to; index++)
+                            pending.push(index);
+                        for (let attempt = 0; attempt < MEDIA_RETRIES && pending.length > 0; attempt++) {
+                            const results = await Promise.allSettled(pending.map((index) => sendFrame({
+                                kind: 'media_chunk',
+                                to: session.deviceId,
+                                mid,
+                                seq: index,
+                                total: info.total,
+                                data: encryptBytes(reader.chunk(index), session.frameKey),
+                            })));
+                            if (session.mediaId !== mid)
+                                return;
+                            pending = pending.filter((_, at) => results[at].status === 'rejected');
+                        }
+                        if (pending.length > 0) {
+                            fail('보내는 도중에 통로가 막혔어요. 잠시 뒤 다시 받아보세요.');
+                            return;
+                        }
+                    }
+                    const label = { image: '사진', video: '동영상', audio: '소리', pdf: 'PDF' }[info.kind];
+                    console.log(`📱 폰으로 ${label} 을 보냈어요: ${filePath}`);
+                }
+                finally {
+                    reader.close();
+                    if (session.mediaId === mid)
+                        session.mediaId = null;
+                }
+            })();
+            return;
+        }
         // 폰에서 마이크로 말한 녹음 — 조각이 다 모이면 이 컴퓨터의 음성인식 서버로 넘겨 글자로 돌려준다.
         // 녹음은 인터넷의 다른 음성인식 서비스로 나가지 않고 이 컴퓨터 안에서만 처리된다.
         if (frame.kind === 'stt_audio') {

package/dist/crypto.js

@@ -1,4 +1,5 @@
 import crypto from 'node:crypto';
+import zlib from 'node:zlib';
 const ALGO = 'aes-256-gcm';
 const IV_LEN = 12;
 const TAG_LEN = 16;
@@ -9,15 +10,15 @@ const TAG_LEN = 16;
 export function generateFrameKey() {
     return crypto.randomBytes(32).toString('base64');
 }
-export function encryptFrame(plaintext, keyB64) {
+export function encryptBytes(plain, keyB64) {
     const key = Buffer.from(keyB64, 'base64');
     const iv = crypto.randomBytes(IV_LEN);
     const cipher = crypto.createCipheriv(ALGO, key, iv);
-    const ciphertext = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+    const ciphertext = Buffer.concat([cipher.update(plain), cipher.final()]);
     const authTag = cipher.getAuthTag();
     return Buffer.concat([iv, ciphertext, authTag]).toString('base64');
 }
-export function decryptFrame(payloadB64, keyB64) {
+export function decryptToBytes(payloadB64, keyB64) {
     const key = Buffer.from(keyB64, 'base64');
     const raw = Buffer.from(payloadB64, 'base64');
     const iv = raw.subarray(0, IV_LEN);
@@ -25,5 +26,24 @@ export function decryptFrame(payloadB64, keyB64) {
     const ciphertext = raw.subarray(IV_LEN, raw.length - TAG_LEN);
     const decipher = crypto.createDecipheriv(ALGO, key, iv);
     decipher.setAuthTag(authTag);
-    return Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString('utf8');
+    return Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+}
+export function encryptFrame(plaintext, keyB64) {
+    return encryptBytes(Buffer.from(plaintext, 'utf8'), keyB64);
+}
+export function decryptFrame(payloadB64, keyB64) {
+    return decryptToBytes(payloadB64, keyB64).toString('utf8');
+}
+// ── 압축 ────────────────────────────────────────────────────────────────────
+// 터미널 출력은 같은 것이 끝없이 반복된다(색 코드·회전 표시·화면 전체 다시 그리기). 실측으로
+// 5배 안팎 줄어드는데, 이 통로의 병목은 굵기가 아니라 **초당 보낼 수 있는 건수**라서 크기가
+// 줄면 조각 수가 그대로 줄어든다 — 조각 사이의 틈이 곧 검은 화면이었으므로 효과가 크다.
+//
+// 반드시 **압축 → 암호화** 순서다. 암호문은 무작위에 가까워서 뒤에 압축하면 오히려 커진다.
+// 압축 비용은 실측 0.68ms/256KB (level 6) 로 사실상 없다.
+export function compress(plaintext) {
+    return zlib.gzipSync(Buffer.from(plaintext, 'utf8'));
+}
+export function decompress(raw) {
+    return zlib.gunzipSync(raw).toString('utf8');
 }

package/dist/media.js

@@ -0,0 +1,139 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+// 폰에서 사진·동영상·소리 파일을 **보이게** 하는 부분.
+// 글자 파일(files.ts)과 통로는 같지만 다루는 것이 다르다:
+//   · 글자는 조각을 이어 붙이면 그만이지만, 이진 파일은 한 바이트라도 틀리면 아예 안 열린다
+//   · 크기가 글자 파일과 자릿수가 다르다 (메모 몇 KB ↔ 동영상 수십 MB)
+// 그래서 base64 를 한 겹 더 씌우지 않고 **바이트 그대로 암호화해서**(crypto.ts 의 encryptBytes)
+// 보낸다 — 같은 프레임에 3분의 1을 더 실을 수 있다.
+// 한 조각에 담는 원본 바이트 수. 암호화하면 base64 로 약 1.34배가 되므로
+// 32KB → 약 43KB 로, 프레임 한도(56KB)에 여유를 두고 들어간다.
+export const MEDIA_CHUNK_BYTES = 32 * 1024;
+// 이보다 큰 파일은 아예 보내지 않는다. 실시간 통로는 터미널 화면과 **같이 쓰는 길**이라
+// (세션 여럿이 채널 하나를 나눠 쓴다) 너무 큰 파일은 그동안 터미널을 굼뜨게 만든다.
+export const MAX_MEDIA_SIZE = 64 * 1024 * 1024;
+// 확장자로 어떤 종류인지 본다. 파일 안을 뜯어보지 않는 이유는, 폰 브라우저도 결국
+// 여기서 정한 종류(mime)를 믿고 재생하기 때문이다 — 판단 기준을 한 곳에만 두는 편이 낫다.
+const MIME_BY_EXT = {
+    // 사진
+    png: 'image/png',
+    jpg: 'image/jpeg',
+    jpeg: 'image/jpeg',
+    gif: 'image/gif',
+    webp: 'image/webp',
+    avif: 'image/avif',
+    bmp: 'image/bmp',
+    ico: 'image/x-icon',
+    heic: 'image/heic',
+    heif: 'image/heif',
+    tif: 'image/tiff',
+    tiff: 'image/tiff',
+    // 동영상
+    mp4: 'video/mp4',
+    m4v: 'video/mp4',
+    mov: 'video/quicktime',
+    webm: 'video/webm',
+    ogv: 'video/ogg',
+    mkv: 'video/x-matroska',
+    avi: 'video/x-msvideo',
+    // 소리
+    mp3: 'audio/mpeg',
+    m4a: 'audio/mp4',
+    aac: 'audio/aac',
+    wav: 'audio/wav',
+    ogg: 'audio/ogg',
+    oga: 'audio/ogg',
+    opus: 'audio/ogg',
+    flac: 'audio/flac',
+    // 문서 — 폰 브라우저가 그대로 띄워준다
+    pdf: 'application/pdf',
+};
+export function mediaMime(name) {
+    const ext = path.extname(name).slice(1).toLowerCase();
+    return MIME_BY_EXT[ext] ?? null;
+}
+export function mediaKind(name) {
+    const mime = mediaMime(name);
+    if (!mime)
+        return null;
+    if (mime.startsWith('image/'))
+        return 'image';
+    if (mime.startsWith('video/'))
+        return 'video';
+    if (mime.startsWith('audio/'))
+        return 'audio';
+    return 'pdf';
+}
+function expand(target) {
+    if (target.startsWith('~'))
+        return path.join(os.homedir(), target.slice(1));
+    return path.resolve(target);
+}
+// 보내기 전에 "이 파일이 뭔지, 몇 조각인지" 만 먼저 알아본다.
+// 폰은 이 답을 보고 큰 파일이면 "받을까요?" 를 한 번 물어본 뒤에야 받기를 시작한다.
+export function statMedia(target) {
+    const full = expand(target);
+    let stat;
+    try {
+        stat = fs.statSync(full);
+    }
+    catch {
+        return { ok: false, reason: `파일을 찾을 수 없어요: ${full}` };
+    }
+    if (stat.isDirectory())
+        return { ok: false, reason: '폴더는 열 수 없어요.' };
+    const mime = mediaMime(full);
+    const kind = mediaKind(full);
+    if (!mime || !kind)
+        return { ok: false, reason: '폰에서 보여줄 수 있는 형식이 아니에요.' };
+    if (stat.size === 0)
+        return { ok: false, reason: '파일이 비어 있어요.' };
+    if (stat.size > MAX_MEDIA_SIZE) {
+        return {
+            ok: false,
+            reason: `파일이 너무 커요 (${Math.round(stat.size / 1024 / 1024)}MB) — ` +
+                `${MAX_MEDIA_SIZE / 1024 / 1024}MB 까지만 보낼 수 있어요.`,
+        };
+    }
+    return {
+        ok: true,
+        full,
+        mime,
+        kind,
+        size: stat.size,
+        total: Math.ceil(stat.size / MEDIA_CHUNK_BYTES),
+    };
+}
+// 파일을 열어두고 조각을 하나씩 꺼내 쓰는 손잡이. 통째로 메모리에 올리지 않는 이유는,
+// 64MB 짜리를 여러 세션에서 동시에 열면 에이전트가 그만큼을 계속 들고 있게 되기 때문이다.
+export class MediaReader {
+    info;
+    fd;
+    constructor(info, fd) {
+        this.info = info;
+        this.fd = fd ?? fs.openSync(info.full, 'r');
+    }
+    chunk(index) {
+        const offset = index * MEDIA_CHUNK_BYTES;
+        const length = Math.min(MEDIA_CHUNK_BYTES, this.info.size - offset);
+        const buffer = Buffer.allocUnsafe(length);
+        let read = 0;
+        // 한 번에 다 안 읽히는 경우가 있어서(네트워크 드라이브 등) 다 찰 때까지 이어 읽는다
+        while (read < length) {
+            const got = fs.readSync(this.fd, buffer, read, length - read, offset + read);
+            if (got <= 0)
+                break;
+            read += got;
+        }
+        return read === length ? buffer : buffer.subarray(0, read);
+    }
+    close() {
+        try {
+            fs.closeSync(this.fd);
+        }
+        catch {
+            // 이미 닫혔으면 그만
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shellbase",
-  "version": "0.13.5",
+  "version": "0.14.0",
   "description": "내 컴퓨터 터미널(특히 Claude Code 세션)을 폰 브라우저로 실시간 접속하게 해주는 데스크톱 에이전트",
   "type": "module",
   "bin": {