shellbase 0.9.0 → 0.10.0

package/README.md

@@ -117,6 +117,7 @@ shellbase start --no-restore     # 복구하지 않고 이 폴더 세션 하나
 | 하고 싶은 것 | 폰에서 하는 법 |
 |---|---|
 | 세션 하나 더 열기 | 목록 화면의 **`+ 새 세션`**, 또는 터미널 화면의 기기 이름(▾) → **`+ 이 컴퓨터에서 새 세션 열기`** (열리면 그 세션으로 바로 넘어가요) |
+| 잠깐 쓸 터미널 열기 | 터미널 화면 위쪽의 **`+ 임시 터미널`** — 지금 폴더에 하나 더 띄워요 (목록에 안 남고, 나가면 사라져요) |
 | 세션 갈아타기 | 터미널 화면 위쪽의 **기기 이름(▾)** 탭 → 원하는 세션 선택 |
 | 세션 끄기 | 목록의 **전원 아이콘**, 또는 터미널 화면의 기기 이름(▾) → **이 세션 끄기** |
 | 화면만 닫기 | `← 목록` 으로 나가기 — 컴퓨터의 세션은 계속 살아있어요 |
@@ -132,6 +133,20 @@ shellbase start --no-restore     # 복구하지 않고 이 폴더 세션 하나
   종료돼요(그 대신 다음 실행 때 자동 복구됩니다). 세션을 하나만 끄고 싶으면 폰에서 그 세션의 `✕` 를
   쓰세요 — 나머지 세션은 그대로 유지돼요.
 
+### 임시 터미널 (0.10.0+)
+
+Claude Code 가 화면을 꽉 채우고 있을 때 `git status` 같은 걸 잠깐 쳐보려고 터미널을 하나 더 열곤 하는데,
+그렇게 연 터미널이 목록에 계속 쌓이는 게 문제였어요. 터미널 화면 위쪽의 **`+ 임시 터미널`** 로 연 것은
+**한 번 쓰고 버리는** 터미널이에요.
+
+- 세션 목록에도, 상단 칩 줄에도 **안 보여요** (지금 보고 있는 동안만 칩으로 보입니다)
+- 그 화면에서 나가면 **스스로 종료**돼요 — 다만 **방금까지 뭔가 돌고 있었으면 끄지 않고 목록에 남깁니다**
+  (하던 일이 조용히 사라지면 안 되니까요)
+- 컴퓨터를 재시작해도 **되살아나지 않아요** (정식 세션만 복구 대상)
+- 브라우저를 그냥 닫아버린 경우엔, 아무도 안 보고 화면도 조용한 채로 **5분**이 지나면 컴퓨터가 알아서 정리해요
+- 계속 쓰고 싶어지면 **`임시 · 계속 쓰기`** 를 누르세요 — 정식 세션이 되고 이름의 `(임시)` 표시도 떨어져요
+- 임시 터미널에는 **Claude 자동 시작이 적용되지 않아요** (명령 하나 치려고 여는 것이라 빈 터미널로 열립니다)
+
 ### 파일 보기·편집
 
 `📁 폴더 찾기` 목록에는 폴더와 함께 **파일**도 나와요. 파일을 탭하면 편집기가 열리고, 고친 뒤 `저장` 을

package/dist/agent.js

@@ -12,7 +12,7 @@ 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 { registerDevice, heartbeatDevice, unregisterDevice, listOnlineNames, renameDevice, markSessionDone, } from './devices.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 } from './browse.js';
@@ -23,6 +23,11 @@ import { IMAGE_CHUNK_TTL_MS, pruneImages, saveImage } from './images.js';
 import { watchDoneNotes } from './notify.js';
 import { hookAsked, hookState, installHook, rememberHookAsked } from './claude-hook.js';
 const HEARTBEAT_MS = 20_000;
+// 임시 터미널 정리 — 보는 사람도 없고(폰에서 아무 신호도 없고) 화면도 조용한 채로 이만큼 지나면 닫는다.
+// 폰은 보고 있는 동안 10초마다 신호(ping)를 보내므로, 앱을 닫거나 다른 세션으로 넘어가면 신호가 끊긴다.
+// 5분이나 두는 이유: 폰 화면이 잠기면 타이머가 멈춰서 신호도 잠깐 끊기기 때문 (잠깐 자리를 비운 것과 구분).
+const TEMP_ORPHAN_MS = 5 * 60 * 1000;
+const TEMP_SWEEP_MS = 60 * 1000;
 // 올린 사진 정리 주기 — 보관 기한이 하루라, 오래 켜둔 컴퓨터에서도 반나절 안에 치워진다
 const IMAGE_SWEEP_MS = 6 * 60 * 60 * 1000;
 const APPROVAL_TIMEOUT_MS = 30_000;
@@ -157,7 +162,8 @@ export async function runAgent(options) {
     }
     function persistOpenSessions() {
         saveOpenSessions([...sessions.values()]
-            .filter((session) => !session.closing)
+            // 임시 터미널은 재시작 후 되살리지 않는다 — 한 번 쓰고 버리는 것이므로
+            .filter((session) => !session.closing && !session.temporary)
             .map((session) => ({ dir: session.cwd, name: session.name })));
     }
     const send = async (frame) => {
@@ -168,6 +174,13 @@ export async function runAgent(options) {
             console.error('전송 실패:', err.message);
         }
     };
+    // 이 세션이 보내는 것들을 한 줄로 세운다 — 앞의 것이 끝나야 다음 것이 나간다.
+    const enqueueSend = (session, task) => {
+        const next = session.sendChain.then(task, task);
+        // 하나가 실패해도 줄 전체가 멈추면 안 되므로, 줄에는 성공/실패를 흡수한 것만 남긴다
+        session.sendChain = next.then(() => undefined, () => undefined);
+        return next;
+    };
     const flush = async (session) => {
         session.pendingFlush = null;
         if (!session.outBuffer)
@@ -175,20 +188,70 @@ export async function runAgent(options) {
         const chunk = session.outBuffer;
         session.outBuffer = '';
         session.lastSentAt = Date.now();
+        await enqueueSend(session, async () => {
+            try {
+                await channel.send({
+                    kind: 'output',
+                    to: session.deviceId,
+                    data: encryptFrame(chunk, session.frameKey),
+                }, { includeSelf: false });
+            }
+            catch (err) {
+                // 실패한 출력을 그냥 버리면 폰 화면이 깨진 채로 남으니, 다음 전송 앞에 다시 붙여 순서대로 재시도한다
+                session.outBuffer = chunk + session.outBuffer;
+                session.sendPenaltyUntil = Date.now() + SEND_PENALTY_MS;
+                console.error('출력 전송 실패, 다시 시도해요:', err.message);
+                if (!session.closing)
+                    scheduleFlush(session);
+            }
+        });
+    };
+    // 폰이 "화면을 통째로 다시 달라"고 할 때 (처음 접속·재연결·크기 변경 뒤).
+    const sendRestore = async (session) => {
+        if (session.restoring) {
+            // 보내는 중에 또 요청이 왔다 — 지금 것이 끝난 뒤 한 번만 더 보낸다.
+            // 두 벌을 동시에 보내면 조각이 서로 끼어들어 폰 화면에 같은 내용이 두 번 그려진다.
+            session.restoreAgain = true;
+            return;
+        }
+        session.restoring = true;
         try {
-            await channel.send({
-                kind: 'output',
-                to: session.deviceId,
-                data: encryptFrame(chunk, session.frameKey),
-            }, { includeSelf: false });
+            do {
+                session.restoreAgain = false;
+                if (session.closing)
+                    return;
+                // 지금 화면 상태를 통째로 보낼 참이다. 아직 못 보낸 출력(outBuffer)은 이미 그 화면 안에
+                // 들어 있다 — pty.onData 가 outBuffer 와 screen 에 같이 넣기 때문. 그대로 두면 복원 직후
+                // 같은 내용이 한 번 더 나가서 화면에 두 번 찍힌다. 여기서 버린다.
+                // (아래 await 전까지는 끊기지 않고 실행되므로, 버리는 것과 찍어내는 것 사이에 새 출력이
+                //  끼어들 틈이 없다)
+                if (session.pendingFlush !== null) {
+                    clearTimeout(session.pendingFlush);
+                    session.pendingFlush = null;
+                }
+                session.outBuffer = '';
+                let snapshot;
+                try {
+                    snapshot = session.serializer.serialize({ scrollback: RESTORE_SCROLLBACK_LINES });
+                }
+                catch (err) {
+                    console.error('화면 복원 준비 실패:', err.message);
+                    return;
+                }
+                // 화면을 먼저 지우고(2J·3J) 복원 내용을 보내야, 폰에 남아있던 예전 화면과 섞이지 않는다
+                const payload = `\x1b[H\x1b[2J\x1b[3J${snapshot}`;
+                for (let i = 0; i < payload.length; i += RESTORE_CHUNK) {
+                    const part = payload.slice(i, i + RESTORE_CHUNK);
+                    await enqueueSend(session, () => send({
+                        kind: 'output',
+                        to: session.deviceId,
+                        data: encryptFrame(part, session.frameKey),
+                    }));
+                }
+            } while (session.restoreAgain);
         }
-        catch (err) {
-            // 실패한 출력을 그냥 버리면 폰 화면이 깨진 채로 남으니, 다음 전송 앞에 다시 붙여 순서대로 재시도한다
-            session.outBuffer = chunk + session.outBuffer;
-            session.sendPenaltyUntil = Date.now() + SEND_PENALTY_MS;
-            console.error('출력 전송 실패, 다시 시도해요:', err.message);
-            if (!session.closing)
-                scheduleFlush(session);
+        finally {
+            session.restoring = false;
         }
     };
     const scheduleFlush = (session) => {
@@ -265,7 +328,8 @@ export async function runAgent(options) {
             console.error('접속 승인 처리 실패:', err.message);
         });
     }
-    async function createSession(dir, explicitName) {
+    async function createSession(dir, explicitName, opts = {}) {
+        const temporary = opts.temporary === true;
         const cwd = path.resolve(dir);
         if (sessions.size >= MAX_SESSIONS) {
             throw new Error(`세션은 한 번에 최대 ${MAX_SESSIONS}개까지 열 수 있어요.`);
@@ -284,7 +348,9 @@ export async function runAgent(options) {
         const session = {
             deviceId,
             frameKey: generateFrameKey(),
-            name: explicitName ?? defaultName(cwd),
+            // 임시 터미널은 이름만 봐도 알 수 있게 (임시) 를 붙인다 — 목록에는 안 뜨지만
+            // 그 터미널을 보고 있는 동안 상단 칩에는 이 이름이 그대로 보인다
+            name: explicitName ?? (temporary ? `${defaultName(cwd)} (임시)` : defaultName(cwd)),
             cwd,
             rowId: '',
             pty: pty.spawn(shell, [], {
@@ -307,6 +373,9 @@ export async function runAgent(options) {
             inputApproved: false,
             approvalInFlight: false,
             outBuffer: '',
+            sendChain: Promise.resolve(),
+            restoring: false,
+            restoreAgain: false,
             lastSentAt: 0,
             sendPenaltyUntil: 0,
             pendingFlush: null,
@@ -317,6 +386,8 @@ export async function runAgent(options) {
             idleTimer: null,
             announcedFor: 0,
             hookSeen: false,
+            temporary,
+            viewerSeenAt: Date.now(),
         };
         session.screen.loadAddon(session.serializer);
         session.pty.onData((data) => {
@@ -341,6 +412,7 @@ export async function runAgent(options) {
                 cwd,
                 frameKey: session.frameKey,
                 favoriteDirs: touchRecentDir(cwd),
+                temporary,
             });
         }
         catch (err) {
@@ -394,6 +466,7 @@ export async function runAgent(options) {
         shuttingDown = true;
         clearInterval(heartbeat);
         clearInterval(imageSweep);
+        clearInterval(tempSweep);
         stopNotes();
         for (const session of [...sessions.values()]) {
             session.closing = true;
@@ -455,27 +528,11 @@ export async function runAgent(options) {
         const session = sessions.get(frame.to);
         if (!session || session.closing)
             return;
+        // 폰에서 온 프레임 = 누군가 이 세션을 보고 있다는 뜻 (임시 터미널 정리 판단에 쓴다)
+        session.viewerSeenAt = Date.now();
         if (frame.kind === 'connect_request') {
-            // 화면 보기는 승인 여부와 무관하게 항상 되므로, 승인을 묻기 전에 지금 화면부터 그대로 복원해준다.
-            // 화면을 먼저 지우고(2J·3J) 복원 내용을 보내야, 폰에 남아있던 예전 화면과 섞이지 않는다.
-            void (async () => {
-                let snapshot;
-                try {
-                    snapshot = session.serializer.serialize({ scrollback: RESTORE_SCROLLBACK_LINES });
-                }
-                catch (err) {
-                    console.error('화면 복원 준비 실패:', err.message);
-                    return;
-                }
-                const payload = `\x1b[H\x1b[2J\x1b[3J${snapshot}`;
-                for (let i = 0; i < payload.length; i += RESTORE_CHUNK) {
-                    await send({
-                        kind: 'output',
-                        to: session.deviceId,
-                        data: encryptFrame(payload.slice(i, i + RESTORE_CHUNK), session.frameKey),
-                    });
-                }
-            })();
+            // 화면 보기는 승인 여부와 무관하게 항상 되므로, 승인을 묻기 전에 지금 화면부터 그대로 복원해준다
+            void sendRestore(session);
             // 승인을 묻지 않는 기본 설정에서는 요청이 올 때마다 곧바로 답한다.
             // (예전엔 "승인 진행 중"이면 건너뛰었는데, 그 사이 온 요청은 영영 답을 못 받아서
             //  폰이 "승인 대기 중" 화면에 갇히는 일이 생겼음 — 자동 승인은 기다릴 게 없으므로 항상 응답)
@@ -500,6 +557,27 @@ export async function runAgent(options) {
             void closeSession(session, { deliberate: true });
             return;
         }
+        // 임시 터미널을 정식 세션으로 — 목록에 나타나고, 재시작해도 되살아나고, 스스로 정리되지 않는다
+        if (frame.kind === 'keep_session') {
+            if (!readControl(frame.data, session.frameKey))
+                return;
+            if (!session.temporary)
+                return;
+            const before = session.name;
+            session.temporary = false;
+            session.name = session.name.replace(/ \(임시\)$/, '');
+            keepDevice(cb, session.rowId, session.name)
+                .then(() => {
+                persistOpenSessions();
+                console.log(`📱 "${before}" 를 계속 쓰기로 바꿨어요 — 이제 목록에 남습니다.`);
+            })
+                .catch((err) => {
+                session.temporary = true;
+                session.name = before;
+                console.error('계속 쓰기 전환 실패:', err.message);
+            });
+            return;
+        }
         // 폰에서 세션 이름 바꾸기 — 컴퓨터를 가리키는 앞부분은 유지해서 목록의 컴퓨터 묶음이 깨지지 않게 한다
         if (frame.kind === 'rename') {
             const control = readControl(frame.data, session.frameKey);
@@ -715,10 +793,12 @@ export async function runAgent(options) {
             if (!control || typeof control.dir !== 'string')
                 return;
             const dir = control.dir;
+            // 폰의 「+ 터미널」 은 임시로, 「여기서 새 세션」 은 정식 세션으로 연다
+            const temporary = control.temporary === true;
             void (async () => {
                 try {
-                    const created = await createSession(dir);
-                    console.log(`\n📱 폰 요청으로 새 세션을 열었어요: "${created.name}" (${created.cwd})`);
+                    const created = await createSession(dir, undefined, { temporary });
+                    console.log(`\n📱 폰 요청으로 ${temporary ? '임시 ' : ''}세션을 열었어요: "${created.name}" (${created.cwd})`);
                 }
                 catch (err) {
                     const reason = err.message;
@@ -754,6 +834,22 @@ export async function runAgent(options) {
             }
         }
     });
+    // 임시 터미널 청소 — 폰이 창을 닫거나 앱이 죽어서 "끄기" 요청이 못 온 경우를 위한 안전망.
+    // (평소에는 폰이 그 터미널을 떠나는 순간 바로 끄기 요청을 보낸다)
+    const tempSweep = setInterval(() => {
+        const now = Date.now();
+        for (const session of sessions.values()) {
+            if (!session.temporary || session.closing)
+                continue;
+            if (now - session.viewerSeenAt < TEMP_ORPHAN_MS)
+                continue;
+            // 아무도 안 봐도 뭔가 돌고 있으면(출력이 계속 나오면) 끝날 때까지 기다린다
+            if (session.lastOutputAt && now - session.lastOutputAt < TEMP_ORPHAN_MS)
+                continue;
+            console.log(`🧹 임시 터미널 "${session.name}" 을(를) 아무도 안 봐서 정리해요.`);
+            void closeSession(session, { deliberate: true });
+        }
+    }, TEMP_SWEEP_MS);
     const heartbeat = setInterval(() => {
         for (const session of sessions.values()) {
             if (session.closing || !session.rowId)

package/dist/devices.js

@@ -11,6 +11,7 @@ export async function registerDevice(cb, params) {
             cwd: params.cwd,
             frame_key: params.frameKey,
             favorite_dirs: params.favoriteDirs,
+            temporary: params.temporary === true,
             last_seen_at: new Date().toISOString(),
         },
     });
@@ -47,6 +48,13 @@ export async function listOnlineNames(cb) {
     }
     return names;
 }
+// 임시 터미널을 "계속 쓰기" 로 바꿀 때 — 목록에 정식으로 남기고 이름에서 (임시) 표시를 뗀다.
+// 반대 방향(정식 → 임시)은 없다: 이미 쓰고 있던 터미널이 조용히 사라지는 건 사고이기 때문.
+export async function keepDevice(cb, rowId, deviceName) {
+    await cb.database.updateData(DEVICES_TABLE_ID, rowId, {
+        data: { temporary: false, device_name: deviceName },
+    });
+}
 // 폰에서 세션 이름을 바꿀 때 — 목록 row 의 표시 이름만 갱신한다 (세션 자체는 그대로 유지)
 export async function renameDevice(cb, rowId, deviceName) {
     await cb.database.updateData(DEVICES_TABLE_ID, rowId, { data: { device_name: deviceName } });

package/package.json

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