shellbase 0.1.10 → 0.2.0

package/dist/agent.js

@@ -0,0 +1,375 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import crypto from 'node:crypto';
+import * as pty from 'node-pty';
+import { requireClient } from './auth.js';
+import { TERMINAL_CATEGORY, CONTROL_TOKEN } from './config.js';
+import { startSleepGuard, stopSleepGuard } from './sleep-guard.js';
+import { encryptFrame, decryptFrame, generateFrameKey } from './crypto.js';
+import { registerDevice, heartbeatDevice, unregisterDevice, listOnlineDirs } from './devices.js';
+import { promptApproval } from './prompt.js';
+import { touchRecentDir } from './recent-dirs.js';
+import { listDirs } from './browse.js';
+import { loadOpenSessions, saveOpenSessions } from './open-sessions.js';
+const HEARTBEAT_MS = 20_000;
+const APPROVAL_TIMEOUT_MS = 30_000;
+const SCROLLBACK_MAX = 16_000;
+// 서버가 전송 속도를 최소 100ms 간격으로 제한해서(RATE_LIMITED), 그보다 짧은 간격으로 보내면 출력이
+// 많은 순간에 거부될 수 있음. 그렇다고 매번 고정 간격을 기다리면 한두 글자 출력도 불필요하게 지연되니,
+// "마지막 전송 후 이 간격이 지났으면 바로 보내고, 아니면 그만큼만 기다렸다 모아서 보낸다"로 처리한다.
+const MIN_SEND_INTERVAL_MS = 120;
+// 실수나 버그로 세션이 무한정 늘어나는 것을 막는 상한 (한 컴퓨터에서 이 이상 필요한 경우는 사실상 없음)
+const MAX_SESSIONS = 20;
+function resolveShell() {
+    if (process.platform === 'win32')
+        return process.env.COMSPEC ?? 'powershell.exe';
+    return process.env.SHELL ?? '/bin/bash';
+}
+// 폰이 보내는 제어 프레임(끄기 / 새 세션 / 폴더 목록)은 그 세션의 키로 풀려야만 받아들인다.
+// 키는 devices 테이블의 내 row 에만 있고 RLS 로 주인만 읽을 수 있으니, 복호화에 성공했다는 것 자체가
+// "주인이 보낸 요청"이라는 증거가 된다 (입력 승인과는 별개 — 승인은 타이핑 권한용).
+function readControl(data, key) {
+    if (typeof data !== 'string')
+        return null;
+    try {
+        const parsed = JSON.parse(decryptFrame(data, key));
+        if (!parsed || parsed.token !== CONTROL_TOKEN)
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+export async function runAgent(options) {
+    const { cb, memberId } = await requireClient();
+    const me = await cb.auth.getMe();
+    const accountAutoApprove = me.custom_data?.auto_approve === true;
+    const autoApprove = options.autoApprove === true || accountAutoApprove;
+    const primaryCwd = options.dir ? path.resolve(options.dir) : process.cwd();
+    // 이름 앞부분(컴퓨터를 가리키는 부분) — 이 프로세스가 나중에 만드는 세션들이 물려받는다.
+    // 도커 안에서는 os.hostname() 이 컨테이너 ID라서, --name 을 준 경우 그걸 쓰는 게 알아보기 좋음.
+    const hostLabel = options.name ?? os.hostname();
+    const shell = resolveShell();
+    const sessions = new Map();
+    function defaultName(cwd) {
+        return cwd === os.homedir() ? hostLabel : `${hostLabel} · ${path.basename(cwd)}`;
+    }
+    function persistOpenSessions() {
+        saveOpenSessions([...sessions.values()]
+            .filter((session) => !session.closing)
+            .map((session) => ({ dir: session.cwd, name: session.name })));
+    }
+    const send = async (frame) => {
+        try {
+            await channel.send(frame, { includeSelf: false });
+        }
+        catch (err) {
+            console.error('전송 실패:', err.message);
+        }
+    };
+    const flush = async (session) => {
+        session.pendingFlush = null;
+        if (!session.outBuffer)
+            return;
+        const chunk = session.outBuffer;
+        session.outBuffer = '';
+        session.lastSentAt = Date.now();
+        await send({
+            kind: 'output',
+            to: session.deviceId,
+            data: encryptFrame(chunk, session.frameKey),
+        });
+    };
+    const scheduleFlush = (session) => {
+        if (session.pendingFlush !== null)
+            return;
+        const wait = Math.max(0, MIN_SEND_INTERVAL_MS - (Date.now() - session.lastSentAt));
+        session.pendingFlush = setTimeout(() => void flush(session), wait);
+    };
+    // stdin 은 프로세스에 하나뿐이라, 세션이 여러 개일 때 승인 프롬프트가 겹치지 않게 한 번에 하나씩 묻는다
+    let approvalChain = Promise.resolve();
+    function askApproval(session) {
+        session.approvalInFlight = true;
+        approvalChain = approvalChain
+            .then(async () => {
+            if (session.closing)
+                return;
+            const approved = autoApprove
+                ? true
+                : await promptApproval(`\n📱 "${session.name}" 세션에 모바일 접속 요청이 왔어요. 입력을 허용할까요? (y/N, 30초 내 미응답 시 자동 거부): `, APPROVAL_TIMEOUT_MS);
+            session.inputApproved = approved;
+            session.approvalInFlight = false;
+            await send({
+                kind: approved ? 'connect_approved' : 'connect_denied',
+                to: session.deviceId,
+            });
+        })
+            .catch((err) => {
+            session.approvalInFlight = false;
+            console.error('접속 승인 처리 실패:', err.message);
+        });
+    }
+    async function createSession(dir, explicitName) {
+        const cwd = path.resolve(dir);
+        if (sessions.size >= MAX_SESSIONS) {
+            throw new Error(`세션은 한 번에 최대 ${MAX_SESSIONS}개까지 열 수 있어요.`);
+        }
+        let stat;
+        try {
+            stat = fs.statSync(cwd);
+        }
+        catch {
+            throw new Error(`그런 폴더가 없어요: ${cwd}`);
+        }
+        if (!stat.isDirectory())
+            throw new Error(`폴더가 아니라 파일이에요: ${cwd}`);
+        const session = {
+            deviceId: `desktop-${crypto.randomUUID()}`,
+            frameKey: generateFrameKey(),
+            name: explicitName ?? defaultName(cwd),
+            cwd,
+            rowId: '',
+            pty: pty.spawn(shell, [], {
+                name: 'xterm-256color',
+                cols: 80,
+                rows: 24,
+                cwd,
+                env: process.env,
+            }),
+            scrollback: '',
+            inputApproved: false,
+            approvalInFlight: false,
+            outBuffer: '',
+            lastSentAt: 0,
+            pendingFlush: null,
+            closing: false,
+        };
+        session.pty.onData((data) => {
+            session.outBuffer += data;
+            // 최근 출력을 조금 들고 있다가, 모바일이 (재)접속했을 때 놓친 화면 대신 다시 보여줌
+            session.scrollback = (session.scrollback + data).slice(-SCROLLBACK_MAX);
+            scheduleFlush(session);
+        });
+        session.pty.onExit(() => {
+            console.log(`"${session.name}" 세션의 셸이 종료돼서 세션도 닫아요.`);
+            void closeSession(session, { deliberate: true });
+        });
+        // 프레임 배분표에 먼저 올린 뒤 목록에 등록한다 — 폰 목록에 뜬 세션은 항상 요청을 받을 수 있는 상태
+        // (실시간 프레임은 저장되지 않아서, 등록이 먼저면 그 사이 요청이 그대로 사라짐 — §8.20)
+        sessions.set(session.deviceId, session);
+        try {
+            session.rowId = await registerDevice(cb, {
+                ownerId: memberId,
+                deviceId: session.deviceId,
+                deviceName: session.name,
+                cwd,
+                frameKey: session.frameKey,
+                favoriteDirs: touchRecentDir(cwd),
+            });
+        }
+        catch (err) {
+            sessions.delete(session.deviceId);
+            session.pty.kill();
+            throw err;
+        }
+        persistOpenSessions();
+        return session;
+    }
+    // deliberate=true: 사용자가 일부러 닫은 것 → 재시작 복구 목록에서도 빠진다
+    async function closeSession(session, opts) {
+        if (session.closing)
+            return;
+        session.closing = true;
+        if (session.pendingFlush !== null)
+            clearTimeout(session.pendingFlush);
+        await flush(session);
+        sessions.delete(session.deviceId);
+        if (session.rowId) {
+            try {
+                await unregisterDevice(cb, session.rowId);
+            }
+            catch {
+                // 삭제 실패해도 계속 진행 — 폰 목록에 남으면 거기서 지울 수 있음
+            }
+        }
+        try {
+            session.pty.kill();
+        }
+        catch {
+            // 이미 죽었으면 무시
+        }
+        if (opts.deliberate)
+            persistOpenSessions();
+        console.log(`"${session.name}" 세션을 닫았어요. (남은 세션 ${sessions.size}개)`);
+        if (sessions.size === 0) {
+            console.log('열린 세션이 없어서 에이전트도 종료해요.');
+            await shutdownProcess();
+        }
+    }
+    let shuttingDown = false;
+    // 프로세스 종료(Ctrl+C, SIGTERM, 마지막 세션 닫힘) — 열린 세션 목록 파일은 그대로 남겨서
+    // 컴퓨터·컨테이너가 다시 뜰 때 복구할 수 있게 한다 (일부러 닫은 세션은 이미 목록에서 빠져 있음)
+    async function shutdownProcess() {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        clearInterval(heartbeat);
+        for (const session of [...sessions.values()]) {
+            session.closing = true;
+            if (session.pendingFlush !== null)
+                clearTimeout(session.pendingFlush);
+            await flush(session);
+            if (session.rowId) {
+                try {
+                    await unregisterDevice(cb, session.rowId);
+                }
+                catch {
+                    // 무시 — 폰 목록에서 수동으로 지울 수 있음
+                }
+            }
+            try {
+                session.pty.kill();
+            }
+            catch {
+                // 무시
+            }
+        }
+        sessions.clear();
+        stopMessages();
+        stopSleepGuard();
+        try {
+            await channel.unsubscribe();
+        }
+        catch {
+            // 이미 끊겼으면 무시
+        }
+        cb.realtime.disconnect();
+        process.exit(0);
+    }
+    // 실시간 연결은 프로세스에 하나만 — userId 는 UUID 형태를 "인증된 멤버 전용"으로 취급해서 거부하므로
+    // 접두사를 붙여 UUID 로 보이지 않게 만든다. 프레임 배분은 userId 가 아니라 frame.to 로 한다.
+    await cb.realtime.connect({ userId: `agent-${crypto.randomUUID()}` });
+    const channel = await cb.realtime.subscribe(TERMINAL_CATEGORY);
+    // 이 채널은 앱의 모든 멤버가 공유하므로, 프레임 내용(data)은 세션별 키로 암호화해서 주고받는다.
+    const stopMessages = channel.onMessage((msg) => {
+        const frame = msg.data;
+        if (!frame)
+            return;
+        const session = sessions.get(frame.to);
+        if (!session || session.closing)
+            return;
+        if (frame.kind === 'connect_request') {
+            // 화면 보기는 승인 여부와 무관하게 항상 되므로, 승인을 묻기 전에 최근 화면부터 먼저 채워줌
+            if (session.scrollback) {
+                void send({
+                    kind: 'output',
+                    to: session.deviceId,
+                    data: encryptFrame(session.scrollback, session.frameKey),
+                });
+            }
+            if (session.approvalInFlight)
+                return;
+            askApproval(session);
+            return;
+        }
+        if (frame.kind === 'kill') {
+            if (!readControl(frame.data, session.frameKey))
+                return;
+            console.log(`\n📱 폰에서 "${session.name}" 세션을 끄라고 요청했어요 — 정리할게요.`);
+            void closeSession(session, { deliberate: true });
+            return;
+        }
+        if (frame.kind === 'list_dirs') {
+            const control = readControl(frame.data, session.frameKey);
+            if (!control)
+                return;
+            const listing = listDirs(typeof control.dir === 'string' && control.dir ? control.dir : session.cwd);
+            void send({
+                kind: 'dirs',
+                to: session.deviceId,
+                data: encryptFrame(JSON.stringify(listing), session.frameKey),
+            });
+            return;
+        }
+        if (frame.kind === 'new_session') {
+            const control = readControl(frame.data, session.frameKey);
+            if (!control || typeof control.dir !== 'string')
+                return;
+            const dir = control.dir;
+            void (async () => {
+                try {
+                    const created = await createSession(dir);
+                    console.log(`\n📱 폰 요청으로 새 세션을 열었어요: "${created.name}" (${created.cwd})`);
+                }
+                catch (err) {
+                    const reason = err.message;
+                    console.error(`\n📱 폰이 요청한 새 세션을 못 열었어요: ${reason}`);
+                    await send({
+                        kind: 'new_session_failed',
+                        to: session.deviceId,
+                        data: encryptFrame(reason, session.frameKey),
+                    });
+                }
+            })();
+            return;
+        }
+        if (frame.kind === 'input' && typeof frame.data === 'string') {
+            if (!session.inputApproved)
+                return;
+            try {
+                session.pty.write(decryptFrame(frame.data, session.frameKey));
+            }
+            catch (err) {
+                console.error('입력 복호화 실패 (다른 세션 키로 온 프레임?):', err.message);
+            }
+            return;
+        }
+        if (frame.kind === 'resize' && frame.cols && frame.rows) {
+            session.pty.resize(frame.cols, frame.rows);
+        }
+    });
+    const heartbeat = setInterval(() => {
+        for (const session of sessions.values()) {
+            if (session.closing || !session.rowId)
+                continue;
+            heartbeatDevice(cb, session.rowId).catch((err) => console.error(`하트비트 실패(${session.name}):`, err.message));
+        }
+    }, HEARTBEAT_MS);
+    startSleepGuard();
+    process.on('SIGINT', () => void shutdownProcess());
+    process.on('SIGTERM', () => void shutdownProcess());
+    // 복구 목록은 첫 세션을 만들기 전에 읽어둔다 — createSession 이 목록 파일을 현재 상태로 덮어쓰므로,
+    // 나중에 읽으면 방금 만든 첫 세션 하나만 남아 이전 세션들이 사라진다 (실제 테스트에서 잡힌 버그)
+    const savedRecords = options.restore === false ? [] : loadOpenSessions();
+    // ── 첫 세션(사용자가 실행한 그 폴더)
+    const primary = await createSession(primaryCwd, options.name ?? defaultName(primaryCwd));
+    console.log(`"${primary.name}" 세션을 시작했어요 (작업 폴더: ${primary.cwd})`);
+    if (autoApprove) {
+        console.log(`⚠️  자동 승인이 켜져 있어요${accountAutoApprove ? ' (계정 설정)' : ' (--auto-approve)'} — 접속 요청을 묻지 않고 자동 승인해요. 내 계정에 들어올 수 있는 사람은 누구나 곧바로 입력할 수 있어요.`);
+    }
+    // ── 지난번에 열려 있던 세션 복구 (컴퓨터·컨테이너 재시작 후 자동으로 원래 상태로)
+    if (options.restore === false) {
+        console.log('이전 세션 복구는 건너뛰어요 (--no-restore)');
+        return;
+    }
+    const saved = savedRecords.filter((entry) => entry.dir !== primary.cwd);
+    if (saved.length === 0)
+        return;
+    // 같은 컴퓨터에서 `shellbase start` 를 또 실행한 경우, 이미 살아있는 세션을 중복으로 띄우지 않는다
+    const liveDirs = await listOnlineDirs(cb).catch(() => new Set());
+    for (const entry of saved) {
+        if (liveDirs.has(entry.dir)) {
+            console.log(`  건너뜀 (이미 켜져 있어요): ${entry.dir}`);
+            continue;
+        }
+        try {
+            const restored = await createSession(entry.dir, entry.name);
+            console.log(`  복구: "${restored.name}" (${restored.cwd})`);
+        }
+        catch (err) {
+            console.log(`  건너뜀 (${err.message})`);
+        }
+    }
+}

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { Command } from 'commander';
 import { login, logout, whoami } from './auth.js';
-import { startSession } from './session.js';
+import { runAgent } from './agent.js';
 // 실시간 기능(realtime.subscribe)이 Node 의 네이티브 WebSocket(Node 22+)에 의존해서,
 // Node 20 에서는 조용히 SSE 모드로 떨어져 "네트워크가 막혔다"는 헷갈리는 에러만 남기고 죽는다.
 // 미리 버전을 확인해서 원인을 바로 알려준다.
@@ -33,12 +33,13 @@ program
 });
 program
     .command('start')
-    .description('이 컴퓨터의 터미널을 열어서 폰 접속을 받을 수 있게 시작')
+    .description('이 컴퓨터의 터미널을 열어서 폰 접속을 받을 수 있게 시작 (한 프로세스가 여러 세션을 관리해요)')
     .option('--dir <path>', '이 폴더에서 터미널을 시작해요 (기본: 현재 폴더)')
     .option('--name <name>', '폰에서 보여줄 이 기기의 이름 (기본: 컴퓨터 이름)')
     .option('--auto-approve', '폰에서 접속할 때마다 묻지 않고 자동으로 승인해요 (편하지만, 내 계정에 접속하는 누구나 곧바로 입력할 수 있게 되니 주의)')
+    .option('--no-restore', '지난번에 열려 있던 세션들을 자동으로 다시 띄우지 않아요')
     .action(async (opts) => {
-    await startSession(opts);
+    await runAgent(opts);
 });
 program.parseAsync(process.argv).catch((err) => {
     console.error('실행 중 문제가 생겼어요:', err instanceof Error ? err.message : err);

package/dist/devices.js

@@ -27,3 +27,22 @@ export async function heartbeatDevice(cb, rowId) {
 export async function unregisterDevice(cb, rowId) {
     await cb.database.deleteData(DEVICES_TABLE_ID, rowId);
 }
+// 복구할 때 "이미 다른 프로세스가 띄워둔 세션"을 또 띄우지 않도록, 지금 살아있는 세션들의 작업 폴더를 모은다.
+// (같은 컴퓨터에서 `shellbase start` 를 두 번 실행하는 경우까지 안전하게 처리하기 위함)
+const ONLINE_WINDOW_MS = 30_000;
+export async function listOnlineDirs(cb) {
+    const dirs = new Set();
+    const { data } = await cb.database.getData(DEVICES_TABLE_ID, {
+        orderBy: 'last_seen_at',
+        orderDirection: 'desc',
+        limit: 100,
+    });
+    for (const row of data) {
+        if (row.data.status !== 'online')
+            continue;
+        if (Date.now() - new Date(row.data.last_seen_at).getTime() > ONLINE_WINDOW_MS)
+            continue;
+        dirs.add(row.data.cwd);
+    }
+    return dirs;
+}

package/dist/open-sessions.js

@@ -0,0 +1,27 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { CONFIG_DIR } from './config.js';
+// 지금 열려 있는 세션 목록을 파일로 남겨둬서, 컴퓨터·컨테이너가 재시작돼도 다시 띄울 수 있게 한다.
+// (devices 테이블 row 는 정상 종료 시 지워지도록 설계돼 있어서 복구 근거로 쓸 수 없음 — §8.8)
+const OPEN_SESSIONS_PATH = path.join(CONFIG_DIR, 'open-sessions.json');
+export function loadOpenSessions() {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(OPEN_SESSIONS_PATH, 'utf8'));
+        if (!Array.isArray(parsed))
+            return [];
+        return parsed.filter((entry) => entry && typeof entry.dir === 'string' && typeof entry.name === 'string');
+    }
+    catch {
+        return [];
+    }
+}
+export function saveOpenSessions(records) {
+    try {
+        fs.mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+        fs.writeFileSync(OPEN_SESSIONS_PATH, JSON.stringify(records, null, 2), { mode: 0o600 });
+    }
+    catch (err) {
+        // 저장에 실패해도 세션 자체는 정상 동작해야 함 (복구만 못 하게 됨)
+        console.error('열린 세션 목록 저장 실패:', err.message);
+    }
+}

package/package.json

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

package/dist/session.js

@@ -1,252 +0,0 @@
-import path from 'node:path';
-import os from 'node:os';
-import crypto from 'node:crypto';
-import * as pty from 'node-pty';
-import { requireClient } from './auth.js';
-import { TERMINAL_CATEGORY, CONTROL_TOKEN } from './config.js';
-import { startSleepGuard, stopSleepGuard } from './sleep-guard.js';
-import { encryptFrame, decryptFrame, generateFrameKey } from './crypto.js';
-import { registerDevice, heartbeatDevice, unregisterDevice } from './devices.js';
-import { promptApproval } from './prompt.js';
-import { touchRecentDir } from './recent-dirs.js';
-import { spawnSession } from './spawner.js';
-import { listDirs } from './browse.js';
-const HEARTBEAT_MS = 20_000;
-const APPROVAL_TIMEOUT_MS = 30_000;
-const SCROLLBACK_MAX = 16_000;
-function resolveShell() {
-    if (process.platform === 'win32')
-        return process.env.COMSPEC ?? 'powershell.exe';
-    return process.env.SHELL ?? '/bin/bash';
-}
-// 폰이 보내는 제어 프레임(끄기 / 새 세션)은 이 세션의 암호화 키로 풀려야만 받아들인다.
-// 키는 devices 테이블의 내 row 에만 있고 RLS 로 주인만 읽을 수 있으니, 복호화에 성공했다는 것
-// 자체가 "주인이 보낸 요청"이라는 증거가 된다 (입력 승인과 별개 — 승인은 타이핑 권한용).
-function readControl(data, key) {
-    if (typeof data !== 'string')
-        return null;
-    try {
-        const parsed = JSON.parse(decryptFrame(data, key));
-        if (!parsed || parsed.token !== CONTROL_TOKEN)
-            return null;
-        return parsed;
-    }
-    catch {
-        return null;
-    }
-}
-export async function startSession(options) {
-    const { cb, memberId } = await requireClient();
-    const cwd = options.dir ? path.resolve(options.dir) : process.cwd();
-    // 폴더 이름을 기본 이름에 넣어서, 같은 컴퓨터에서 여러 개 띄워도 폰 목록에서 구분되게 한다.
-    const defaultName = cwd === os.homedir() ? os.hostname() : `${os.hostname()} · ${path.basename(cwd)}`;
-    const deviceName = options.name ?? defaultName;
-    // realtime userId 는 UUID 형태를 "인증된 멤버 전용"으로 취급해서 거부하므로, 세션 식별자는
-    // 접두사를 붙여 UUID 로 보이지 않게 만든다. `shellbase start` 를 실행할 때마다 새로 발급 —
-    // 예전엔 컴퓨터당 하나로 고정돼있어서, 같은 컴퓨터에서 두 개를 동시에 띄우면 프레임이 서로
-    // 섞였음(둘 다 같은 deviceId 를 썼기 때문). 이제 세션(프로세스)마다 독립된 식별자를 가짐.
-    const device = {
-        deviceId: `desktop-${crypto.randomUUID()}`,
-        deviceName,
-        frameKey: generateFrameKey(),
-    };
-    // 계정 설정(웹의 "새 세션 자동 승인" 토글, custom_data.auto_approve)이 켜져 있으면
-    // --auto-approve 를 안 줘도 자동 승인. 계정 단위라 이 계정으로 로그인한 모든 컴퓨터에 적용됨.
-    const me = await cb.auth.getMe();
-    const accountAutoApprove = me.custom_data?.auto_approve === true;
-    const autoApprove = options.autoApprove === true || accountAutoApprove;
-    console.log(`"${deviceName}" 세션을 시작해요 (작업 폴더: ${cwd})`);
-    if (autoApprove) {
-        console.log(`⚠️  자동 승인이 켜져 있어요${accountAutoApprove ? ' (계정 설정)' : ' (--auto-approve)'} — 접속 요청을 묻지 않고 자동 승인해요. 내 계정에 들어올 수 있는 사람은 누구나 곧바로 입력할 수 있어요.`);
-    }
-    await cb.realtime.connect({ userId: device.deviceId });
-    const channel = await cb.realtime.subscribe(TERMINAL_CATEGORY);
-    // 이 채널은 앱의 모든 멤버가 공유하므로, 프레임 내용(data)은 기기별 키로 암호화해서 주고받는다.
-    // 다른 사람이 같은 채널을 구독해도 to/kind 정도만 보이고 실제 터미널 내용은 못 읽음.
-    const shell = resolveShell();
-    const ptyProcess = pty.spawn(shell, [], {
-        name: 'xterm-256color',
-        cols: 80,
-        rows: 24,
-        cwd,
-        env: process.env,
-    });
-    // PTY 출력은 모아서 전송 — 서버가 전송 속도를 최소 100ms 간격으로 제한해서(RATE_LIMITED), 그보다
-    // 짧은 간격으로 보내면 출력이 많은 순간(로그 스크롤 등)에 전송이 거부될 수 있음. 그렇다고 매번
-    // 고정 간격을 기다리면 한두 글자짜리 출력도 불필요하게 지연되니, "마지막 전송 후 이 간격이
-    // 지났으면 바로 보내고, 아니면 그만큼만 기다렸다 모아서 보낸다" 방식으로 평소 지연은 최소화하고
-    // 출력이 몰릴 때만 자동으로 묶이게 한다.
-    const MIN_SEND_INTERVAL_MS = 120;
-    let outBuffer = '';
-    let lastSentAt = 0;
-    let pendingFlush = null;
-    const flush = async () => {
-        pendingFlush = null;
-        if (!outBuffer)
-            return;
-        const chunk = outBuffer;
-        outBuffer = '';
-        lastSentAt = Date.now();
-        try {
-            await channel.send({
-                kind: 'output',
-                to: device.deviceId,
-                data: encryptFrame(chunk, device.frameKey),
-            }, { includeSelf: false });
-        }
-        catch (err) {
-            console.error('출력 전송 실패:', err.message);
-        }
-    };
-    const scheduleFlush = () => {
-        if (pendingFlush !== null)
-            return;
-        const wait = Math.max(0, MIN_SEND_INTERVAL_MS - (Date.now() - lastSentAt));
-        pendingFlush = setTimeout(() => void flush(), wait);
-    };
-    // 최근 출력을 조금 들고 있다가, 모바일이 (재)접속했을 때 놓친 화면 대신 다시 보여줌
-    let scrollback = '';
-    ptyProcess.onData((data) => {
-        outBuffer += data;
-        scrollback = (scrollback + data).slice(-SCROLLBACK_MAX);
-        scheduleFlush();
-    });
-    // 모바일이 접속을 시도하면 데스크톱에서 승인해야만 입력이 먹힘 (읽기/출력은 항상 흐름 —
-    // 이미 같은 계정으로 로그인했다는 전제이므로, 승인은 "지금 이 순간 내가 타이핑을 넘겨줄지"
-    // 확인하는 용도). 승인 전에 온 input 프레임은 무시.
-    let inputApproved = false;
-    let approvalInFlight = false;
-    const stopMessages = channel.onMessage((msg) => {
-        const frame = msg.data;
-        if (!frame || frame.to !== device.deviceId)
-            return;
-        if (frame.kind === 'connect_request') {
-            // 화면 보기는 승인 여부와 무관하게 항상 되므로, 승인 물어보기 전에 최근 화면부터 먼저 채워줌
-            // (끊겼다 재접속한 경우든, 처음 들어온 경우든 동일하게 "방금까지 뭐가 있었는지" 보여줌)
-            if (scrollback) {
-                channel
-                    .send({ kind: 'output', to: device.deviceId, data: encryptFrame(scrollback, device.frameKey) }, { includeSelf: false })
-                    .catch((err) => console.error('화면 복구 전송 실패:', err.message));
-            }
-            if (approvalInFlight)
-                return;
-            approvalInFlight = true;
-            const approval = autoApprove
-                ? Promise.resolve(true)
-                : promptApproval('\n📱 모바일에서 접속을 요청했어요. 입력을 허용할까요? (y/N, 30초 내 미응답 시 자동 거부): ', APPROVAL_TIMEOUT_MS);
-            approval
-                .then((approved) => {
-                inputApproved = approved;
-                approvalInFlight = false;
-                return channel.send({ kind: approved ? 'connect_approved' : 'connect_denied', to: device.deviceId }, { includeSelf: false });
-            })
-                .catch((err) => console.error('접속 승인 처리 실패:', err.message));
-            return;
-        }
-        // 폰에서 "이 세션 끄기" — 정상 종료 경로(shutdown)를 그대로 타서 목록에서도 스스로 지워진다.
-        if (frame.kind === 'kill') {
-            if (!readControl(frame.data, device.frameKey))
-                return;
-            console.log('\n📱 폰에서 이 세션을 끄라고 요청했어요 — 정리하고 종료할게요.');
-            void shutdown();
-            return;
-        }
-        // 폰의 폴더 탐색기 — 요청받은 경로의 하위 폴더 목록을 암호화해서 돌려준다 (세션 열 곳 고르기용)
-        if (frame.kind === 'list_dirs') {
-            const control = readControl(frame.data, device.frameKey);
-            if (!control)
-                return;
-            const listing = listDirs(typeof control.dir === 'string' && control.dir ? control.dir : cwd);
-            channel
-                .send({
-                kind: 'dirs',
-                to: device.deviceId,
-                data: encryptFrame(JSON.stringify(listing), device.frameKey),
-            }, { includeSelf: false })
-                .catch((err) => console.error('폴더 목록 전송 실패:', err.message));
-            return;
-        }
-        // 폰에서 "새 세션 열기" — 이 세션이 CLI 를 한 번 더 띄워주고, 새 세션은 폰 목록에 따로 나타난다.
-        if (frame.kind === 'new_session') {
-            const control = readControl(frame.data, device.frameKey);
-            if (!control || typeof control.dir !== 'string')
-                return;
-            // 이름 앞부분(컴퓨터를 가리키는 부분)만 물려줘서 "GB10 (Docker) · shellbase" 처럼 나오게 함
-            const result = spawnSession(control.dir, deviceName.split(' · ')[0]);
-            if (result.ok) {
-                console.log(`\n📱 폰 요청으로 새 세션을 열었어요 (${control.dir})`);
-                return;
-            }
-            console.error(`\n📱 폰이 요청한 새 세션을 못 열었어요: ${result.reason}`);
-            channel
-                .send({
-                kind: 'new_session_failed',
-                to: device.deviceId,
-                data: encryptFrame(result.reason, device.frameKey),
-            }, { includeSelf: false })
-                .catch((err) => console.error('실패 알림 전송 실패:', err.message));
-            return;
-        }
-        if (frame.kind === 'input' && typeof frame.data === 'string') {
-            if (!inputApproved)
-                return;
-            try {
-                ptyProcess.write(decryptFrame(frame.data, device.frameKey));
-            }
-            catch (err) {
-                console.error('입력 복호화 실패 (다른 기기 키로 보낸 프레임?):', err.message);
-            }
-        }
-        else if (frame.kind === 'resize' && frame.cols && frame.rows) {
-            ptyProcess.resize(frame.cols, frame.rows);
-        }
-    });
-    // 목록 등록은 "이제 프레임을 받을 수 있다"가 확실해진 지금(구독 + 메시지 핸들러 준비 완료) 한다.
-    // 예전엔 실시간 연결보다 먼저 등록해서, 폰이 목록에 뜨자마자 보낸 요청(특히 "세션 끄기")이
-    // 아직 구독 전인 세션에 닿지 못하고 그대로 사라지는 구간이 있었음 (실시간 프레임은 저장되지 않음).
-    const deviceRowId = await registerDevice(cb, {
-        ownerId: memberId,
-        deviceId: device.deviceId,
-        deviceName,
-        cwd,
-        frameKey: device.frameKey,
-        favoriteDirs: touchRecentDir(cwd),
-    });
-    const heartbeat = setInterval(() => {
-        heartbeatDevice(cb, deviceRowId).catch((err) => console.error('하트비트 실패:', err.message));
-    }, HEARTBEAT_MS);
-    startSleepGuard();
-    let shuttingDown = false;
-    const shutdown = async () => {
-        if (shuttingDown)
-            return;
-        shuttingDown = true;
-        if (pendingFlush !== null)
-            clearTimeout(pendingFlush);
-        clearInterval(heartbeat);
-        await flush();
-        stopMessages();
-        stopSleepGuard();
-        try {
-            await channel.unsubscribe();
-        }
-        catch {
-            // 이미 끊겼으면 무시
-        }
-        try {
-            await unregisterDevice(cb, deviceRowId);
-        }
-        catch {
-            // 삭제 실패해도 종료는 계속 진행 — 폰 목록에 남아있으면 나중에 수동으로 지울 수 있음
-        }
-        cb.realtime.disconnect();
-        ptyProcess.kill();
-        process.exit(0);
-    };
-    process.on('SIGINT', () => void shutdown());
-    process.on('SIGTERM', () => void shutdown());
-    ptyProcess.onExit(() => {
-        console.log('셸이 종료돼서 세션도 함께 종료해요.');
-        void shutdown();
-    });
-}

package/dist/spawner.js

@@ -1,49 +0,0 @@
-import { spawn } from 'node:child_process';
-import fs from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-// `shellbase` 는 bin 심볼릭 링크(예: /usr/local/bin/shellbase)로 실행되기도 하고 dist/cli.js 로
-// 직접 실행되기도 해서, 지금 돌아가는 진입점(process.argv[1])을 그대로 다시 쓰는 게 가장 확실하다.
-// 그게 비어있는 예외적인 경우에만 이 파일 옆의 cli.js 로 되돌아간다.
-function resolveEntry() {
-    const current = process.argv[1];
-    if (current && fs.existsSync(current))
-        return current;
-    return path.join(path.dirname(fileURLToPath(import.meta.url)), 'cli.js');
-}
-// nameLabel: 폰 목록에서 부모 세션과 같은 컴퓨터임을 알아보게 물려받는 이름 앞부분.
-// 도커 컨테이너 안에서는 os.hostname() 이 컨테이너 ID(예: 7a54a499a8f3)로 나와서 기본 이름이
-// "7a54a499a8f3 · shellbase" 처럼 알아보기 어려워짐 — 그래서 부모 이름을 물려준다.
-export function spawnSession(dir, nameLabel) {
-    const target = path.resolve(dir);
-    let stat;
-    try {
-        stat = fs.statSync(target);
-    }
-    catch {
-        return { ok: false, reason: `그런 폴더가 없어요: ${target}` };
-    }
-    if (!stat.isDirectory())
-        return { ok: false, reason: `폴더가 아니라 파일이에요: ${target}` };
-    try {
-        // 폰에서 띄우는 세션은 승인 물음에 대답할 터미널이 없다(stdio: 'ignore') — 그대로 두면 30초 뒤
-        // 자동 거부돼서 화면만 보이고 타이핑이 안 되는 세션이 된다. 요청을 보낸 쪽은 이미 이 세션의
-        // 암호화 키(주인만 읽을 수 있는 devices row)를 가지고 있음이 확인된 상태라 자동 승인으로 띄운다.
-        const args = [resolveEntry(), 'start', '--dir', target, '--auto-approve'];
-        if (nameLabel)
-            args.push('--name', `${nameLabel} · ${path.basename(target)}`);
-        const child = spawn(process.execPath, args, {
-            cwd: target,
-            env: process.env,
-            // 부모 세션을 Ctrl+C 로 껐을 때 폰에서 따로 만든 세션까지 같이 죽지 않도록 독립 프로세스로 띄움
-            // (각 세션은 폰 목록에서 개별적으로 끌 수 있음). 도커 컨테이너 안이라면 컨테이너가 멈출 때 함께 정리됨.
-            detached: true,
-            stdio: 'ignore',
-        });
-        child.unref();
-        return { ok: true };
-    }
-    catch (err) {
-        return { ok: false, reason: err.message };
-    }
-}