tabby-agentdeck 0.2.1 → 1.0.0

package/dist/agents.d.ts

@@ -0,0 +1,126 @@
+/**
+ * 에이전트 프로필 — "클로드든 코덱스든 제미나이든 같은 포맷으로 쓴다" 를 위한 단일 출처.
+ *
+ * 상태 감지(detect.ts)·이미지 붙여넣기 키(deck.service.ts)·입력창 머리글자(prompt.ts)가
+ * 원래 각자 Claude Code 를 전제로 하드코딩돼 있었다. 새 CLI 를 하나 지원하려면 세 파일을
+ * 따로 고쳐야 했고, 어떤 값이 실측이고 어떤 값이 짐작인지도 코드에서 구분되지 않았다.
+ * 그래서 "무엇을 어떻게 알아보나" 를 프로필 한 덩이로 모았다 — 새 CLI 는 아래 배열에
+ * 항목 하나를 더하는 것으로 끝난다.
+ *
+ * **이 파일은 순수하다** — DOM·fs·tabby 를 건드리지 않는다. 그래야 노드에서 바로 테스트된다.
+ *
+ * 값의 출처 표기 규칙: 실측된 값에는 근거(날짜·파일)를 적고, 관측이 없는 값에는
+ * `근거 미확인` 을 적는다. 짐작을 실측처럼 적어두면 다음 사람이 그것을 근거로 또 짐작한다.
+ */
+export type AgentId = 'claude' | 'codex' | 'gemini' | 'unknown';
+/**
+ * 이미지 전용 클립보드일 때 흘려보낼 키.
+ *
+ * `config` 는 "이 에이전트가 무엇을 받는지 관측된 바가 없다" 는 뜻이다 — 그때는
+ * 예전처럼 사용자 설정(`agentDeck.imagePasteKey`)을 쓴다. 관측 없는 키를 단정해 보내면
+ * 아무 일도 안 일어나거나(Claude 에 0x16) 엉뚱한 문자가 입력창에 박힌다.
+ */
+export type ImagePasteKey = 'alt-v' | 'ctrl-v' | 'config';
+export interface AgentProfile {
+    id: AgentId;
+    /** 사람에게 보여줄 이름 (사이드바·진단에 쓴다) */
+    label: string;
+    /** 프로세스 이름/명령줄에서 이 에이전트를 알아보는 조각 (소문자 비교) */
+    processHints: string[];
+    /** 탭 제목에서 알아보는 조각 (소문자 비교) */
+    titleHints: string[];
+    /** "사람 입력을 기다린다" 로 볼 화면 문구 */
+    waitingPatterns: RegExp[];
+    /** "지금 일하는 중" 으로 볼 화면 문구 */
+    busyPatterns: RegExp[];
+    /**
+     * "사용량 한도에 걸려 턴이 끊겼다" 로 볼 화면 문구.
+     *
+     * 왜 대기·작업중과 따로 두나 — 한도는 둘 중 어느 것도 아니다. 사람이 승인할 것이 없고
+     * 리셋 시각까지 기다려야 하는 상태라 배지·정렬·알림이 모두 다르게 취급한다
+     * (`api.ts` `limited`, `order.ts`, `alert.service.ts`).
+     *
+     * 왜 필요했나 — 0.9.0 까지 `limited` 는 훅(`claudeHooks.ts` 의 `StopFailure`
+     * `error=rate_limit`)으로만 왔고 **화면 문구 경로가 아예 없었다.** 그래서 훅이 없는
+     * CLI(codex·gemini)는 한도에 걸려도 배지가 `running`/`error` 로 남았다.
+     *
+     * **`patternsProven` 규칙과의 관계** — 이것도 화면 문구이므로 위 세 필드와 똑같이 다룬다.
+     * 실측이 없으면 `[]` 로 비우고, 실측이 없는 프로필의 판정에는 합집합 것이 쓰인다
+     * (`detectProfileFor`). 합집합은 모든 프로필의 값을 모으므로(`buildUnion`), 한 프로필에서
+     * 실측된 한도 문구는 `patternsProven: false` 인 프로필에서도 그대로 쓰인다 —
+     * codex 가 정확히 그 경우다(한도 문구만 실측, 대기·작업중은 미관측).
+     */
+    limitedPatterns: RegExp[];
+    /** 콘솔 제목에 넣는 작업중 표식(스피너 등) */
+    busyTitleMarks: string[];
+    /** 이미지 전용 클립보드일 때 흘려보낼 키 */
+    imagePasteKey: ImagePasteKey;
+    /** 입력창 머리글자 후보 — 라벨을 읽는 쪽(prompt.ts)이 쓸 값. 여기서는 데이터만 들고 있는다 */
+    promptHeads: string[];
+    /**
+     * 입력창에서 프롬프트를 뽑을 때 쓸 화면 모양 (`prompt.ts` 의 `PromptShape` 와 구조가 같다).
+     *
+     * **타입을 `prompt.ts` 에서 import 하지 않는다** — 그쪽은 순수 모듈이고 여기서 역참조하면
+     * 의존이 한 바퀴 돈다. 구조만 맞으면 TS 가 받아준다.
+     *
+     * 생략하면 `prompt.ts` 의 기본값이 쓰인다. **claude 는 일부러 생략한다** — 그 기본값 자체가
+     * Claude Code 2.1.x 실측으로 만들어진 값이라(`prompt.ts` `DEFAULT_PROMPT_SHAPE` 주석),
+     * 여기서 좁혀 적으면 같은 값을 두 곳에 두게 되고 한쪽만 고쳐질 위험만 생긴다.
+     */
+    promptShape?: {
+        heads?: string[];
+        choiceWords?: string[];
+        ruleChars?: string[];
+    };
+    /** 화면 깨짐 판정에 쓸 모양 (`screen.ts` 의 `ScreenShape` 와 구조가 같다). 위와 같은 이유로 claude 는 생략 */
+    screenShape?: {
+        ruleChars?: string[];
+        heads?: string[];
+        choiceWords?: string[];
+    };
+    /**
+     * 화면 문구(`waitingPatterns` · `busyPatterns` · `limitedPatterns` · `busyTitleMarks`)가
+     * **실측된** 프로필인가.
+     *
+     * false 면 상태 판정에는 이 프로필 대신 합집합의 문구를 쓴다(`detectProfileFor`).
+     * 왜 이 갈래가 필요한가 — 프로필을 붙이는 순간 판정이 그 프로필 안으로 좁아지는데,
+     * 관측이 없는 에이전트에서 그건 **개선이 아니라 퇴행**이다. 예를 들어 Codex 가 실제로
+     * `esc to interrupt` 를 쓰거나 제목에 스피너를 넣는다면, 0.5.0 은 (합집합 하나로 모든 탭을
+     * 판정했으므로) 그걸 잡았는데 프로필을 붙인 0.6.0 은 놓친다.
+     * 그래서 **실측이 있는 값만 좁게 쓴다** — 실측되면 이 값을 true 로 올리면 된다.
+     *
+     * `imagePasteKey` 처럼 이미 실측된 필드는 이 값과 무관하게 프로필 것을 쓴다.
+     */
+    patternsProven: boolean;
+}
+/** 지원하는 에이전트 목록 — 새 CLI 는 여기에 한 덩이 추가하면 된다 */
+export declare const AGENT_PROFILES: AgentProfile[];
+export declare const UNKNOWN_PROFILE: AgentProfile;
+/** 프로필을 모르는 상황(감지 전/실패)에서 쓰는 합집합 — 0.5.0 까지의 동작과 같다 */
+export declare function unionProfile(): AgentProfile;
+/** 아이디로 프로필을 집는다 — 모르는 아이디면 합집합을 준다(호출부에 null 검사를 강요하지 않는다) */
+export declare function profileFor(id: AgentId | undefined | null): AgentProfile;
+/**
+ * **상태 판정(detect.ts)에 넘길** 프로필. 화면 문구가 실측되지 않은 에이전트는 그 세 필드만
+ * 합집합으로 갈아 준다 — 나머지 필드(이미지 키·머리글자·라벨)는 프로필 것을 그대로 쓴다.
+ *
+ * 왜 이 함수가 따로 있나 — 프로필을 붙이는 것만으로 판정이 좁아지면 관측이 없는 에이전트에서는
+ * **퇴행**이다. 0.5.0 은 합집합 하나로 모든 탭을 판정했으므로, 예컨대 Codex 가 실제로
+ * `esc to interrupt` 를 찍고 있었다면 그때는 잡혔는데 프로필을 붙인 뒤로는 놓치게 된다
+ * (유닛 C 가 그 리스크를 보고했고, 그래서 배리어에서 이 갈래를 넣었다).
+ *
+ * 즉 **좁히는 것은 실측이 있을 때만** 한다. Codex/Gemini 화면 문구가 관측되면 그 프로필의
+ * `patternsProven` 을 true 로 올리면 이 함수가 자동으로 프로필 값을 쓴다.
+ */
+export declare function detectProfileFor(id: AgentId | undefined | null): AgentProfile;
+/**
+ * 이 탭에서 도는 에이전트가 뭔지 — 프로세스 이름/명령줄을 먼저 보고, 없으면 탭 제목으로 본다.
+ *
+ * 프로세스를 먼저 보는 이유: npm 전역 래퍼를 거치면 명령줄이 node/pwsh 로만 보일 수 있어
+ * 제목이 보조 근거가 되지만, 제목은 셸이 아무 문자열이나 넣을 수 있어 신뢰도가 낮다.
+ * 두 근거 안에서의 에이전트 판정 순서는 `MATCH_ORDER` — claude 가 맨 뒤다.
+ *
+ * @param processNames 프로세스 트리에서 모은 `command name` 을 이어붙인 문자열
+ * @param title 탭 제목(+ 사용자 지정 제목)
+ */
+export declare function identifyAgent(processNames: string, title: string): AgentId;

package/dist/alert.service.d.ts

@@ -0,0 +1,87 @@
+import { NgZone } from '@angular/core';
+import { AppService, ConfigService } from 'tabby-core';
+import { WorkStatusService } from './status.service';
+/**
+ * 창이 뒤로 가 있을 때의 OS 알림.
+ *
+ * 사이드바는 창이 보일 때만 의미가 있다. 에이전트 탭을 여섯 개쯤 굴리면서 Slack·VS 를 보고
+ * 있으면 어느 탭이 `승인대기` 로 멈춰 있어도 알 길이 없어서, 돌아와 보면 몇 분씩 놀고 있던
+ * 일이 잦았다. 그래서 상태가 **`waiting` / `error` 로 넘어가는 순간** 창이 포커스를 잃은
+ * 상태면 OS 쪽에 세 가지로 알린다.
+ *
+ * 1. **작업표시줄 깜빡임** (`flashFrame`) — 창이 포커스를 받으면 끈다. `alertFlash`
+ * 2. **작업표시줄 뱃지** — 지금 `waiting`+`error` 인 탭 수를 아이콘 위에 얹는다. Windows 에는
+ *    `setBadgeCount` 가 없어서 `setOverlayIcon` 에 캔버스로 그린 원+숫자를 넣는다.
+ *    전이 순간만이 아니라 상태가 바뀔 때마다 갱신해 실제 개수를 따라간다. `alertBadge`
+ * 3. **OS 토스트** (`Notification`) — 기본은 끔. 누르면 창을 앞으로 가져오고 그 탭을 고른다. `alertToast`
+ *
+ * 창이 앞에 있을 때는 아무것도 하지 않는다 — 사이드바가 이미 보이고 있다.
+ * Electron 을 만지는 모든 곳은 try/catch 로 감싼다. 알림이 안 되는 것은 불편이지만
+ * 예외가 새어 나가 다른 배선을 죽이는 것은 사고다.
+ */
+export declare class AgentDeckAlertService {
+    private app;
+    private config;
+    private zone;
+    private status;
+    /** 탭별로 마지막에 본 상태 — "전이" 를 판정하려고 들고 있는다 */
+    private last;
+    /** flashFrame(true) 를 걸어 둔 상태인가 — 포커스가 오면 끈다 */
+    private flashing;
+    /** 마지막으로 그린 뱃지 숫자 (0 = 안 그림). 같은 숫자면 다시 그리지 않는다 */
+    private badgeShown;
+    /** 뱃지 그림 캐시 — key 는 `${count}:${color}` */
+    private badgeCache;
+    /**
+     * 진단/검증용 카운터 — CDP 에서 `__agentdeck.alert` 로 읽는다.
+     * `forceUnfocused` 를 true 로 두면 포커스 판정을 건너뛰고 "창이 뒤에 있다" 로 친다
+     * (테스트 인스턴스가 앞에 떠 있는 상태에서 알림 경로를 밟아 보려고)
+     */
+    debug: {
+        flashes: number;
+        badgeCount: number;
+        badgeDraws: number;
+        toasts: number;
+        transitions: number;
+        lastFocused: boolean;
+        forceUnfocused: boolean;
+    };
+    constructor(app: AppService, config: ConfigService, zone: NgZone, status: WorkStatusService);
+    init(): void;
+    private setup;
+    /**
+     * 상태가 바뀔 때마다 — 뱃지는 항상 실제 개수로 맞추고,
+     * 알림 상태로 **새로 들어온** 탭이 있고 창이 뒤에 있으면 깜빡임/토스트를 낸다
+     */
+    private onChanged;
+    private countAlerting;
+    /** `@electron/remote` 의 현재 창. 못 잡으면 null — 호출부는 전부 null 을 감안한다 */
+    private win;
+    private nativeImage;
+    /**
+     * 창이 앞에 있나. Electron 의 판정을 우선하고(devtools 를 따로 띄워도 본창 기준으로 본다),
+     * remote 를 못 잡으면 DOM 의 `document.hasFocus()` 로 대신한다
+     */
+    private isFocused;
+    private flash;
+    private stopFlash;
+    /**
+     * 작업표시줄 아이콘 위의 숫자를 지금 개수로 맞춘다. 0 이면 지운다.
+     * `alertBadge` 가 꺼져 있으면 그려 둔 것이 있을 때만 지우고 끝낸다
+     */
+    private updateBadge;
+    /**
+     * 원 위에 숫자를 얹은 오버레이 이미지. 오류 탭이 하나라도 있으면 오류색, 아니면 승인대기색.
+     * Windows 오버레이는 16px 기준이라 16@1x + 32@2x 두 표현을 넣는다 (고배율에서 흐려지지 않게).
+     * `addRepresentation` 을 못 쓰는 빌드면 32px 하나로 물러난다
+     */
+    private badgeImage;
+    /** 오프스크린 canvas 에 원+숫자를 그려 data URL 로 돌려준다 */
+    private drawBadge;
+    /** OS 토스트. 누르면 창을 앞으로 가져오고 그 탭을 고른다 */
+    private toast;
+    /** 토스트 tag 용 탭 식별자 — 객체 자체는 문자열이 안 되니 인덱스로 대신한다 */
+    private tabKey;
+    /** deck.service 와 같은 파일(`~/.agentdeck-diag.log`)에 남긴다 — 회전·시각 표기는 `diag.ts` 가 한다 */
+    private diag;
+}

package/dist/api.d.ts

@@ -1,5 +1,11 @@
-/** 사이드바에 표시되는 작업 상태 */
-export type WorkStatus = 'idle' | 'running' | 'waiting' | 'done' | 'error';
+/**
+ * 사이드바에 표시되는 작업 상태.
+ *
+ * `limited`(한도 도달)는 에이전트가 사용량 한도에 걸려 턴이 끊긴 상태다 — Claude Code 의
+ * `StopFailure` 훅이 `error: rate_limit` 로 알려준다. 사람이 승인할 것은 없고 리셋 시각까지 기다려야
+ * 하므로 승인대기와는 구분해서 보여준다 (2026-09-07 요청).
+ */
+export type WorkStatus = 'idle' | 'running' | 'waiting' | 'limited' | 'done' | 'error';
 export interface StatusStyle {
     icon: string;
     label: string;
@@ -12,6 +18,14 @@ export interface TabState {
     status: WorkStatus;
     /** 작업 이름 (사용자 지정 또는 훅이 보낸 값) */
     label: string;
+    /**
+     * 상태의 부연 — 훅이 보낸 문구를 줄인 것.
+     *  - waiting: 승인 이유 (예: `Bash 권한`, `입력 대기`) → 배지 `⏸ 승인대기 · Bash 권한`
+     *  - limited: 리셋 시각 (예: `12pm 리셋`) → 배지 `⛔ 한도 도달 · 12pm 리셋`
+     *  - error:   StopFailure 의 error 코드 (예: `overloaded`)
+     * 그 밖의 상태로 바뀌면 비운다 (status.service REASON_STATUSES)
+     */
+    reason: string;
     /** 상태가 마지막으로 바뀐 시각 */
     since: number;
     /** true = 수동/훅 지정. 자동 감지가 덮어쓰지 않는다 */

package/dist/claudeHooks.d.ts

@@ -4,7 +4,8 @@ export declare function notifyScriptPath(): string;
 /** 이 환경에서 훅을 걸 수 있나 — 통보 스크립트가 PowerShell 이라 Windows 전용이다 */
 export declare function hooksSupported(): boolean;
 /**
- * 우리 훅이 세 이벤트에 모두 걸려 있나 — 파일을 읽지 않는 순수 판정.
+ * 우리 훅이 PLAN 의 모든 이벤트에 걸려 있나 — 파일을 읽지 않는 순수 판정.
+ * 이벤트가 늘어난 버전으로 올라오면 옛 설치는 "설치 안 됨" 으로 보인다 — 설정 창에서 설치를 다시 누르면 된다.
  * 파일 접근과 분리해 둔 이유는 이 판단을 테스트로 묶어 두기 위해서다.
  */
 export declare function isMerged(settings: any): boolean;

package/dist/config.d.ts

@@ -17,11 +17,89 @@ export declare const LAYOUT_DEFAULTS: {
     sidebarWidth: number;
     /** 상/하 도킹일 때의 사이드바 높이 (px). 경계선 드래그로 바뀐다 */
     sidebarHeight: number;
+    /**
+     * 미리보기 패널이 붙는 방향 — 'right' | 'left'.
+     * 사이드바와 같은 쪽이면 사이드바가 창 가장자리(바깥), 패널이 터미널 쪽(안)에 앉는다.
+     */
+    viewerDock: string;
+    /** 미리보기 패널 폭 (px). 경계선 드래그로 바뀐다 */
+    viewerWidth: number;
 };
 /** @hidden */
 export declare class AgentDeckConfigProvider extends ConfigProvider {
     defaults: {
         agentDeck: {
+            /**
+             * 결과물 미리보기 패널(viewPanel.ts)이 지금 열려 있나.
+             *
+             * 사이드바 `▤` 버튼이나 `agentdeck-view` 핫키로 토글하면 이 값이 바뀌고,
+             * 다음 기동 때 그대로 복원한다 — 문서를 띄워 놓고 쓰는 사람에게는 그게 기본 화면이다.
+             */
+            viewerOpen: boolean;
+            /**
+             * 화면에 찍힌 파일 경로를 주워 최근 목록에 쌓는다.
+             *
+             * 에이전트를 가리지 않는 유일한 경로다 — Claude Code 처럼 훅이 있는 CLI 만 되는 게
+             * 아니라 Codex·Gemini 도 만진 파일을 화면에 찍기 때문이다(viewer.ts 주석).
+             * 비용은 탭당 400ms 마다 정규식 한 번이고, 끄면 수동으로 열 때만 쓰게 된다.
+             */
+            viewerScrape: boolean;
+            /**
+             * 에이전트가 만진 파일을 **패널에 미리 얹어 둔다** (닫혀 있어도).
+             *
+             * 기본 켬. 패널이 닫혀 있는 동안에도 최근 목록과 "다음에 열면 보여줄 파일" 을
+             * 계속 갈아 두므로, 작업이 한창일 때 `▤` 를 누르면 **그때까지 만진 파일들이
+             * 칩으로 쌓여 있고 본문은 가장 최근 파일**이다 (`변경` 모드였으면 그 자리에서
+             * diff 를 다시 읽는다). 끄면 아무것도 자동으로 하지 않는다 — 경로 수집만 남고
+             * 무엇을 볼지는 사람이 칩·`＋`·드롭으로 고른다.
+             *
+             * 이 값이 `false` 면 `viewerAutoOpen` 은 의미가 없다 (읽어두지 않으니 열 것도 없다).
+             */
+            viewerPreload: boolean;
+            /**
+             * 새 파일을 주우면 **닫힌 패널을 스스로 연다.**
+             *
+             * **기본 끔** (2026-09-10 유저 결정). 여닫기는 사람 몫이라는 뜻이다 — 작업 중에
+             * 패널이 저절로 열리면 터미널이 좁아지고 읽던 화면이 밀린다. 대신 위 `viewerPreload`
+             * 가 내용을 계속 채워 두므로, 열고 싶을 때 열면 이미 최신이다.
+             * 켜면 결과물이 나오는 순간 패널이 열리면서 그 파일을 띄운다.
+             */
+            viewerAutoOpen: boolean;
+            /**
+             * @deprecated 0.18.0 부터 `viewerPreload` + `viewerAutoOpen` 두 토글로 갈랐다.
+             *
+             * 목록(`open`/`show`/`manual`) 하나로는 "읽어두기" 와 "자동으로 열기" 가 한 축에
+             * 얹혀 있어서, 사람이 고를 때 두 결정을 한꺼번에 해야 했다. 남겨 두는 이유는
+             * 이미 값을 적어 둔 설정 파일 때문이고, 기동 때 한 번 두 토글로 옮긴 뒤 비운다
+             * (`migrateFollow`, deck.service 의 `migrateFollowConfig`).
+             */
+            viewerFollowMode: "" | "open" | "show" | "manual";
+            /**
+             * @deprecated 0.17.0 부터 `viewerFollowMode` 로, 0.18.0 부터 위 두 토글로 옮겼다.
+             *
+             * boolean 하나가 "자동으로 열기" 와 "새 파일로 바꾸기" 를 같이 쥐고 있어서,
+             * **"패널은 내가 열고 닫되 열어 둔 동안에는 따라와라"** 를 표현할 수 없었다.
+             * 마이그레이션이 `false` 를 읽고 나면 기본값(`true`)으로 되돌려 다시 읽지 않는다.
+             */
+            viewerFollow: boolean;
+            /**
+             * 패널 **밖**(터미널 위)에 파일을 끌어다 놓았을 때 무엇을 할지.
+             *
+             * 순정 Tabby 는 그 경로를 터미널에 붙여넣는다(그래서 `cat <경로>` 가 쉽다). 그 동작은
+             * 그대로 두고, **미리보기로 열지를 물어본다** — 자동으로 화면을 바꾸면 붙여넣기만
+             * 원했던 사람의 화면을 빼앗는다 (2026-09-09 유저: "한번 물어보긴 해야 할 듯").
+             *
+             *  - `ask`    : 확인 배너를 띄워 `패널에 띄우기` / `경로 붙여넣기` 를 고르게 한다 (기본)
+             *  - `always` : 묻지 않고 패널에 띄운다
+             *  - `paste`  : 묻지 않고 경로만 터미널에 붙여넣는다
+             *  - `never`  : 우리가 개입하지 않는다 — 순정 Tabby 동작 그대로
+             *
+             * 배너의 `다시 묻지 않기` 를 체크하고 버튼을 누르면 그 선택이 `always`/`paste` 로
+             * 저장된다. 되돌리려면 설정 창에서 `물어본다` 로 바꾼다.
+             */
+            viewerDropOpen: "ask" | "always" | "paste" | "never";
+            /** 최근 목록(패널 위쪽 칩)에 남겨 두는 파일 수 */
+            viewerRecentMax: number;
             /**
              * 훅이 상태를 밀어 넣는 TCP 채널의 포트 (127.0.0.1 전용).
              *
@@ -48,12 +126,149 @@ export declare class AgentDeckConfigProvider extends ConfigProvider {
              * 설정 창의 설치 버튼은 이 값과 무관하게 언제든 쓸 수 있다.
              */
             hookPromptDismissed: boolean;
+            /**
+             * 기동 시 지난 탭을 복원하지 않는다 (Tabby `recoverTabs` 를 false 로 강제).
+             *
+             * 복원되는 건 셸뿐이고 그 안의 Claude Code 세션은 이미 죽어 있어 의미가 없다.
+             * 켜면 항상 빈 상태(기본 프로필 새 탭)로 시작하고, 끄면 Tabby 순정 동작으로 돌아간다.
+             * 설정 창에서 토글한다 (recovery.service.ts).
+             */
+            noTabRecovery: boolean;
             /** PTY 출력이 이 시간(ms) 이상 없으면 running -> idle */
             idleAfterMs: number;
             /** 출력 패턴으로 상태를 자동 추론할지 */
             autoDetect: boolean;
             /** 사이드바에 경과 시간 표시 */
             showElapsed: boolean;
+            /**
+             * 세션이 지금 돌리고 있는 **백그라운드 서브에이전트 개수**를 줄에 보인다
+             * (`❖ 3`, 툴팁에 무엇을 시켜 놨는지 + 가장 오래된 것의 경과 시간).
+             *
+             * 기본으로 켠다 — 얻는 것이 "저 탭이 사람 없이도 일이 도는 중인지" 이고 그것을 볼
+             * 다른 수단이 없다(훅은 세션 **하나**의 상태만 알려 준다, `subagents.ts` 주석).
+             * 0 개면 아무것도 그리지 않으므로(deck.service `renderTab`) 서브에이전트를 안 쓰는
+             * 사람의 화면은 0.12.0 까지와 똑같다 — 켜 둬서 잃는 것이 없다.
+             *
+             * 비용은 세션당 **2초에 `stat` 한 번**이고, 파일이 자란 만큼만 비동기로 읽는다
+             * (실측 대화기록 13MB — 동기로 읽으면 UI 가 멈춘다).
+             * 끄면 읽기도 표시도 멈춘다: 끈 기능이 대화기록 파일을 계속 여는 일은 없다
+             * (`notify.service` `scanSubagents`).
+             */
+            subagentCount: boolean;
+            /**
+             * 사이드바 탭을 상태 우선순위(waiting → error → running → done → idle)로 정렬한다.
+             * 같은 상태끼리는 탭 순서를 지킨다. 기본은 끔 — 순정 탭바와 같은 탭 순서로 보인다.
+             * 헤더의 상태별 집계는 이 값과 무관하게 항상 보인다.
+             */
+            sortByStatus: boolean;
+            /**
+             * 사이드바 헤더 아래에 **세션 검색 줄**을 둔다 (제목 · 작업이름 · 작업 폴더로 좁히기,
+             * 헤더의 상태 칩을 눌러 그 상태만 보기).
+             *
+             * 기본으로 켠다 — 탭이 몇 개뿐일 때도 잃는 것은 26px 한 줄이고, 탭이 많아지는 순간
+             * 목록을 눈으로 훑는 비용이 그보다 훨씬 크다. 세로가 짧은 상/하 도킹에서 그 한 줄이
+             * 아까운 사람만 끄면 된다.
+             *
+             * **여기 저장하는 것은 기능 on/off 뿐이다.** 검색어와 상태 필터는 설정에 남기지 않는다
+             * (deck.service `searchQuery` 주석) — 다음 기동에 필터가 살아 있으면 목록이 좁혀진
+             * 채로 떠서 "탭이 사라졌다" 로 읽힌다. 그 오해는 이 기능이 주는 이득보다 비싸고,
+             * 되살릴 값어치도 없다(검색은 "지금 이것을 찾는다" 는 한순간의 행위다).
+             * 이 값을 끄면 걸려 있던 필터도 같이 지운다 — 감춰진 필터가 남는 것이 가장 위험하다.
+             */
+            searchBox: boolean;
+            /**
+             * 사이드바를 **키보드로** 다룬다 — 핫키(`agentdeck-focus-list`, 기본 `Ctrl-Shift-L`)로
+             * 목록에 들어가 ↑↓ 로 훑고, Enter 로 그 탭으로 전환, Esc 로 터미널에 돌아온다.
+             * 검색창에서 ↓ 를 누르면 결과 목록으로 내려가고, 첫 줄에서 ↑ 면 검색창으로 돌아온다.
+             * 그룹 헤더도 지나가며 Enter 로 접었다 펼 수 있다.
+             *
+             * **이동만으로는 탭이 바뀌지 않는다** (포커스 ≠ 선택). 여섯 개쯤 띄워 두고 훑을 때
+             * 줄마다 활성 탭이 바뀌면 터미널 화면이 계속 튀어 훑기 자체가 불가능하다
+             * (`deck.service.ts` `navFocus` 주석).
+             *
+             * 기본으로 켠다 — **포커스가 사이드바에 없는 동안은 키를 한 개도 가로채지 않는다.**
+             * 리스너가 document 가 아니라 목록 엘리먼트(`.ad-list`)에 걸려 있어서, 핫키를 누르거나
+             * 검색창에 들어가지 않으면 이벤트가 아예 오지 않는다(`wireListKeys` 주석).
+             * 끄면 핫키·검색창 ↓ 가 모두 no-op 이 되고 링도 그리지 않는다.
+             */
+            keyboardNav: boolean;
+            /**
+             * 목록 끝에서 ↑↓ 를 한 번 더 누르면 반대쪽 끝으로 감싼다.
+             *
+             * 기본은 끔 — 감싸면 "맨 아래에 왔다" 는 신호가 사라지고, 목록이 한 번에 위로 튀어
+             * 화면이 다시 그려진 것처럼 보인다. 끝에서 끝으로 갈 일은 Home/End 가 받는다.
+             *
+             * 켜도 **맨 위의 ↑ 는 검색창으로 나간다**(검색 줄이 보일 때). 그 경계를 감싸기에
+             * 내주면 목록에서 검색창으로 돌아갈 키가 없어진다 — 검색↔목록 왕복이 이 기능의
+             * 요구사항이라 감싸기보다 앞에 둔다 (`deck.service.ts` `moveNav`).
+             */
+            keyboardNavWrap: boolean;
+            /**
+             * `Ctrl+W` 로 지금 탭을 닫는다 (터미널에서 누르면 활성 탭, 목록이 키보드를 갖고
+             * 있으면 포커스 줄의 탭 — `nav.ts` `pickCloseTarget`).
+             *
+             * **`keyboardNav` 에 매달아 둔다** — 키보드로 목록을 훑다가 버릴 탭을 만나는 것이
+             * 이 키의 쓰임새이고, 키보드 조작을 끈 사람에게 터미널 키를 빼앗을 이유가 없다.
+             * 그래서 `keyboardNav` 가 꺼져 있으면 이 값이 `true` 여도 아무 일도 하지 않는다
+             * (설정 창에서도 줄이 사라진다 — `keyboardNavWrap` 과 같은 방식).
+             *
+             * 끄고 싶을 만한 이유가 분명히 있다: 셸·에이전트 CLI 에서 `Ctrl+W` 는 **앞 단어
+             * 지우기**(0x17)다. 그걸 그대로 쓰려면 이 값만 끄면 되고, 목록 키보드 조작은 남는다.
+             * 켠 상태에서도 우리가 키를 먹는 것은 **닫을 탭이 실제로 정해졌을 때뿐**이다 —
+             * 그룹 헤더에 포커스가 있거나 설정 화면 입력창이면 키를 그대로 흘린다.
+             * 닫기는 사이드바 `✕` 와 같은 경로라(`closeTab(tab, true)`) 돌아가는 프로세스가
+             * 있으면 Tabby 가 평소처럼 한 번 물어본다.
+             */
+            keyboardCloseTab: boolean;
+            /**
+             * 줄을 끌어 순서를 바꾸는 동안 커서를 **목록 끝에 대면 목록이 따라 스크롤된다.**
+             *
+             * 기본으로 켠다 — 없으면 탭이 많아 목록이 넘치는 순간 "화면 밖으로 옮기기" 가
+             * 아예 불가능해진다(손을 떼고 스크롤한 뒤 다시 끄는 왕복이 필요하다). 그게
+             * 0.12.0 의 드래그 재정렬에 남아 있던 구멍이다.
+             *
+             * 끄면 0.12.0 과 똑같이 동작한다 — 목록은 가만히 있고, 보이는 줄 사이에서만
+             * 옮긴다. 자동 스크롤을 꺼서 얻는 것이 있다: 가장자리 띠 안에서 화면이 흐르지
+             * 않으므로 **맨 끝 줄의 뒤에 놓는** 조작이 절대 미끄러지지 않는다. 띠를 줄 하나
+             * 두께로 좁혀 두긴 했지만(deck.service `DRAG_SCROLL_BAND_PX`) 그 조작을 자주
+             * 하는 사람에게는 이 스위치가 답이다.
+             *
+             * 속도·띠 두께는 설정으로 내지 않았다 — px/s 는 사람이 판단할 수 있는 숫자가
+             * 아니고, 띠 두께는 줄 높이에서 나온 값인데 줄 높이가 설정이 아니다.
+             * 이 값은 **드래그 중에만** 읽는다: 끌지 않을 때는 커서가 목록 끝에 얹혀 있어도
+             * 아무 일도 일어나지 않는다(hover 리스너를 두지 않았다).
+             */
+            dragAutoScroll: boolean;
+            /**
+             * 사이드바 탭을 **작업 폴더(프로젝트) 단위로 묶고** 그룹 헤더로 접을 수 있게 한다.
+             *
+             * 기본으로 켠다 — 그룹이 하나뿐이면 헤더를 아예 그리지 않으므로(deck.service `render`)
+             * 한 프로젝트만 쓰는 사람에게는 0.6.0 까지와 화면이 똑같고, 탭이 열 개를 넘겨
+             * 여러 프로젝트가 섞이는 순간에만 헤더가 생긴다. 즉 켜 둬서 잃는 것이 없다.
+             * 묶는 기준은 **탭이 태어난 cwd** 다 — 셸에서 `cd` 를 해도 따라오지 않으므로
+             * (docs/DEVELOPMENT.md 0.5.0 실측) 세션이 사는 동안 그룹이 흔들리지 않는다.
+             * 그룹 안의 탭 순서는 `sortByStatus` 를 그대로 따른다.
+             */
+            groupByProject: boolean;
+            /**
+             * 프로젝트 경계의 기준 폴더. 비우면 `rootProfileCwd` 를 쓴다.
+             *
+             * 이게 필요한 이유 — cwd 를 그대로 키로 쓰면 `D:\Project\a` 에서 띄운 탭과
+             * `D:\Project\a\sub` 에서 띄운 탭이 다른 그룹으로 갈린다(서브폴더에서 에이전트를
+             * 띄우는 건 흔하다). 이 값을 `D:\Project` 로 채워 두면 그 **직하 한 단계**가 그룹이
+             * 되어 둘이 같은 그룹에 들어온다(`group.ts` `groupKeyOf`).
+             * 둘 다 비면 cwd 자체가 키다 — 프로젝트들이 한 상위 폴더에 모여 있지 않은 경우다.
+             * 저장소 루트(`.git`)를 찾아 자동으로 정하지는 않는다 — 렌더는 초당 여러 번 불리므로
+             * 그때마다 디스크를 훑을 수 없다.
+             */
+            groupRoot: string;
+            /**
+             * 접어 둔 그룹 키 목록. 그룹 헤더를 클릭할 때마다 갱신되고 다음 기동에 복원된다.
+             *
+             * 키는 `group.ts` 가 정규화한 경로를 **소문자로 접은** 값이다(`foldGroupKey`) —
+             * 셸이 알려주는 경로의 대소문자·구분자가 기동마다 달라도 접힘이 유지돼야 하기 때문이다.
+             */
+            collapsedGroups: any[];
             /**
              * 창이 가려져 있어도 사이드바를 계속 갱신한다 (Electron backgroundThrottling 해제).
              *
@@ -80,6 +295,34 @@ export declare class AgentDeckConfigProvider extends ConfigProvider {
              * false 로 두면 터미널 앱에 리터럴 Ctrl+V(0x16, quoted-insert)를 보낼 수 있다
              */
             claimCtrlV: boolean;
+            /**
+             * Shift+Enter / Ctrl+Enter 를 캡처 단계에서 직접 줄바꿈으로 처리한다.
+             *
+             * 핫키(agentdeck-newline)에만 맡기면 한글 조합 중에 눌렀을 때 Shift 가 실리지
+             * 않은 Enter 로 도착해 전송돼 버린다 (deck.service.ts `claimShiftEnterKey` 주석).
+             * false 로 두면 예전처럼 핫키 경로만 쓴다.
+             */
+            claimShiftEnter: boolean;
+            /**
+             * Home / End 를 Tabby 핫키에서 걷어내 xterm 순정 경로로 돌려준다.
+             *
+             * 핫키로 두면 한글 조합 중에 눌렀을 때 조합 음절이 커서를 따라간다
+             * (deck.service.ts `releaseHomeEndHotkey` 주석에 원인). 방향키가 멀쩡한 이유도 같다 —
+             * 방향키는 핫키가 아니라서 xterm 이 조합을 먼저 확정하고 키를 보낸다.
+             */
+            releaseHomeEnd: boolean;
+            /**
+             * pty 에 바이트를 쓰기 전에 조합 중인 한글 음절을 먼저 확정시킨다.
+             *
+             * 핫키를 놓아주는 것(`releaseHomeEnd`)만으로는 부족했다 — 실사용 config.yaml 이
+             * 이미 `home: []` / `end: []` 인데도 조합 중 음절이 커서를 따라가는 증상이 재발했다
+             * (2026-09-08 사용자 재보고). 원인은 핫키가 아니라 **xterm 을 거치지 않는 pty 직접
+             * 쓰기**여서, 이 옵션은 그 쓰기 지점 전부를 한 진입점으로 모아 순서를 맞춘다
+             * (deck.service.ts `sendToPane` / `guardHomeEndComposition`, 기전은 `ime.ts`).
+             *
+             * false 로 두면 0.4.0 까지의 동작 그대로 — 조합 상태를 보지 않고 바로 쓴다.
+             */
+            imeOrderGuard: boolean;
             /**
              * 클립보드에 이미지만 있으면 Ctrl+V 로도 이미지가 들어가게 한다.
              *
@@ -194,6 +437,33 @@ export declare class AgentDeckConfigProvider extends ConfigProvider {
              * 항목 28 의 반전은 그 표본에는 해당하지 않았다.
              * 되살리려면 "앱이 pty 폭을 다시 읽게 만드는" 수단부터 찾을 것. 감지·채증(`screenWatch`)은 계속 돈다.
              */
+            /**
+             * **다시 켬 (2026-09-09).** 위 두 주석의 판단 근거가 오늘 채증으로 갈렸다.
+             *
+             * 껐던 이유는 "복구 수단이 이 유형에 안 듣는다" 였는데, 그 유형이 무엇이었는지가
+             * 오늘 실사용 8건으로 확정됐다 — **`xterm.cols != pty` 인 리사이즈 중간 프레임**이다
+             * (4건 전부, 0~3초 만에 스스로 복구, 화면 덤프는 앱 기준 정상). 거기에 `fit`+`nudge`
+             * 를 때렸으니 고쳐질 리가 없고 화면만 흔들렸다.
+             *
+             * 크기가 맞는데 깨진 나머지 4건(02:07:45~02:08:01, 자식 프로세스 stdout 이 TUI 를
+             * 덮어씀)은 26초를 버텼고, 이 유형은 `clearInputArea` + `Ctrl+L` 로 실제로 고쳐진다
+             * (회귀 PR8·PR9 가 격리 인스턴스에서 100~160ms 해소를 잰다).
+             *
+             * 그래서 **손댈 유형만 손대도록** `checkScreen` 에 크기 가드를 넣고 기본값을 켠다.
+             * 자동 경로가 하는 일은 사이드바 `↻` 한 번과 같다(잔상 지우기 + Ctrl+L, **흔들기 없음**).
+             *
+             * 켜기 직전에 "켜면 격리 인스턴스가 죽는다" 로 한 번 막혔는데, **그 죽음은 우리 코드가
+             * 아니었다** (2026-09-09 확정). `tools/test-instance.ps1 -Kill` 이 커맨드라인에
+             * `tabby-agentdeck-test` 가 든 Tabby 를 **전부** 죽이고 기동은 그 `ud` 폴더를 지운다 —
+             * 같은 저장소에서 두 세션이 동시에 회귀를 돌리면 서로의 인스턴스를 죽인다. 그때 CDP 는
+             * ECONNRESET 으로 끊기고 진단로그에 상대의 `setup start tabs=0` 이 이어 붙어 크래시처럼
+             * 보인다. 판별법 — **Crashpad 리포트가 비어 있으면 크래시가 아니라 누가 죽인 것이다**
+             * (`<ud>\Crashpad\reports`). 이름이 겹치지 않는 전용 인스턴스에서 다시 재니
+             * 기본 `true` 로 `probe-profile` 3회 연속 8 PASS / 0 FAIL 이었다.
+             *
+             * 끄고 싶으면 `%APPDATA%\tabby\config.yaml` 의 `agentDeck.autoRepairScreen: false`
+             * 한 줄이면 되고, 감지·채증(`screenWatch`)은 어느 쪽이든 돈다.
+             */
             autoRepairScreen: boolean;
             /**
              * 화면을 **보고 기록만** 한다 (복구는 하지 않는다).
@@ -258,6 +528,23 @@ export declare class AgentDeckConfigProvider extends ConfigProvider {
             };
             /** 기본 프로필 지정을 이미 했는지 — 사용자 선택을 매번 덮어쓰지 않기 위한 플래그 */
             rootProfileClaimed: boolean;
+            /**
+             * 창이 뒤에 있을 때(포커스 없음) 탭이 `승인대기`/`오류` 로 넘어가면 OS 쪽에 알린다.
+             * 창이 앞에 있으면 세 항목 모두 아무 일도 하지 않는다 — 사이드바가 이미 보이고 있다.
+             * 작업표시줄 아이콘을 깜빡인다(`flashFrame`). 창이 포커스를 받으면 멈춘다
+             */
+            alertFlash: boolean;
+            /**
+             * 작업표시줄 아이콘 위에 `승인대기`+`오류` 탭 개수를 뱃지로 얹는다.
+             * Windows 는 `setBadgeCount` 가 없어 오버레이 아이콘(원+숫자)으로 그린다.
+             * 이 값은 전이 순간이 아니라 상태가 바뀔 때마다 실제 개수로 갱신되고, 0 이면 지운다
+             */
+            alertBadge: boolean;
+            /**
+             * OS 토스트(`Notification`)까지 띄운다. 기본은 끔 — 탭이 여럿이면 시끄럽다.
+             * 토스트를 누르면 창을 앞으로 가져오고 그 탭을 고른다
+             */
+            alertToast: boolean;
             /**
              * 사이드바가 붙는 방향. 헤더를 잡고 창 가장자리로 끌어다 놓으면 바뀐다.
              * 'left' | 'right' | 'top' | 'bottom'
@@ -271,6 +558,13 @@ export declare class AgentDeckConfigProvider extends ConfigProvider {
             sidebarWidth: number;
             /** 상/하 도킹일 때의 사이드바 높이 (px). 경계선 드래그로 바뀐다 */
             sidebarHeight: number;
+            /**
+             * 미리보기 패널이 붙는 방향 — 'right' | 'left'.
+             * 사이드바와 같은 쪽이면 사이드바가 창 가장자리(바깥), 패널이 터미널 쪽(안)에 앉는다.
+             */
+            viewerDock: string;
+            /** 미리보기 패널 폭 (px). 경계선 드래그로 바뀐다 */
+            viewerWidth: number;
             /** 레이아웃/사이드바 전체 on-off */
             enabled: boolean;
             /** 터미널 뷰포트 가로:세로 비율 */
@@ -296,6 +590,17 @@ export declare class AgentDeckConfigProvider extends ConfigProvider {
              * 갈라야 하는데 순정 paste 는 텍스트만 알기 때문
              */
             'agentdeck-paste': string[];
+            /**
+             * 사이드바 목록에 키보드 포커스 (다시 누르면 터미널로 복귀).
+             *
+             * 기본값을 비워 두지 않은 이유 — 이것이 사이드바를 마우스 없이 만지는 **유일한
+             * 진입점**이라(목록은 tabindex=-1, `wireListKeys`) 안 묶여 있으면 기능이 없는 것과
+             * 같다. `Ctrl-Shift-L` 은 Tabby 순정 기본 핫키와 겹치지 않는다 — core·terminal·
+             * local·settings 네 패키지의 기본 조합을 훑어 확인했다(2026-09-09):
+             * 그쪽이 쓰는 것은 `Ctrl-Shift-{A,C,D,E,F,I,P,R,S,T,V,W,Z}`·방향키·Tab·PageUp/Down·
+             * Backspace·`-` 이다. 다른 플러그인과 부딪히면 설정 창에서 바꾼다.
+             */
+            'agentdeck-focus-list': string[];
         };
     };
 }