tabby-agentdeck 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 junggon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,240 @@
+# tabby-agentdeck
+
+Tabby 터미널 플러그인. **Claude Code · Codex 같은 AI 에이전트 CLI 를 여러 탭에 띄워 놓고 쓰는 사람**을 위한 것이다.
+
+터미널 뷰포트를 **4:3 으로 고정**하고 남는 공간에 **세션 목록 + 작업 상태 사이드바**를 그린다.
+어느 에이전트가 돌고 있고 어느 쪽이 내 입력을 기다리는지 탭을 옮겨 다니지 않고 한눈에 본다.
+거기에 에이전트 CLI 가 터미널에서 겪는 문제들(이미지 붙여넣기, 줄바꿈 키, pty 폭 어긋남)을 같이 손봐 둔다.
+
+```
+┌──────────────────────────────┬──────────────────┐
+│                              │ AGENT DECK    4   │
+│     터미널 (창 높이 × 4/3)     ├──────────────────┤
+│                              │ ● 진행중  리팩터링 │
+│     Tabby 순정 탭바는 숨김      │ ⏸ 승인대기 재빌드 │
+│                              │ ✔ 완료   테스트   │
+│                              │ ○ 대기            │
+│                              ├──────────────────┤
+│                              │ + 새 탭 │ 설정    │
+└──────────────────────────────┴──────────────────┘
+```
+
+## 기능
+
+| | 동작 |
+|---|---|
+| **4:3 기준 폭 계산** | 창 높이에서 폭을 역산해 `.content.main` 을 고정폭으로 만든다. 창 크기가 바뀌면 `ResizeObserver` 로 다시 계산 |
+| **사이드바 탭 관리** | 클릭=선택, `×`=닫기, 더블클릭=작업 이름 편집, 우클릭=상태 직접 지정 |
+| **스크롤** | 탭이 많아지면 목록 영역만 스크롤 |
+| **작업 상태** | 진행중 / 승인대기 / 완료 / 오류 / 대기 를 색·배지·경과시간으로 표시 |
+| **기본 프로필** | 새 탭을 항상 지정한 작업 루트에서 연다 |
+
+## 설치
+
+```powershell
+npm install
+npm run build
+powershell -NoProfile -ExecutionPolicy Bypass -File install.ps1 -Shortcut
+```
+
+`install.ps1` 은 두 가지를 한다.
+
+1. `%APPDATA%\tabby\plugins\node_modules\tabby-agentdeck` → 이 폴더로 junction 을 건다.
+   소스를 고치고 `npm run build` 만 하면 Tabby 재시작으로 반영된다.
+2. `-Shortcut` 을 주면 바탕화면에 **관리자 권한** 바로가기를 만든다.
+   Tabby 를 관리자로 띄우면 그 안의 모든 탭이 권한을 물려받으므로, 탭마다 UAC 창이 뜨는 것을 피할 수 있다.
+
+## 작업 이름과 상태
+
+사이드바 한 줄은 **작업 이름(라벨)** 과 **상태 배지** 로 이루어지고, 둘은 채우는 경로가 다르다.
+둘 다 **플러그인 코드만으로 돈다 — 설정도, 에이전트의 협조도 필요 없다.**
+
+### 작업 이름 — Enter 를 누르는 순간 입력창을 읽는다
+
+Enter 로 프롬프트를 보내는 그 순간, 화면에 그려져 있는 입력창(`❯ ...` 또는 `> ...`)을 읽어 40자로 잘라
+라벨에 넣는다 (`enterAsLabel`, 판정은 `src/prompt.ts`).
+
+- **키 입력이 아니라 화면을 읽는다.** 붙여넣기·↑ 히스토리·자동완성·IME 로 들어온 글자는 키 이벤트로
+  안 오거나 원문과 다르다. 화면에 실제로 그려진 것이 곧 보낼 내용이다.
+- **Enter 만 잡는다.** Shift+Enter / Ctrl+Enter 는 줄바꿈이라 아직 전송이 아니고, 그때 라벨을 바꾸면
+  쓰다 만 문장이 박힌다. IME 조합 확정용 Enter 도 제외한다. 이벤트는 관측만 하고 막지 않는다.
+- **머리글자는 앱·버전마다 다르다.** Claude Code 2.1.x 는 테두리 상자 대신 가로선 두 줄 사이에
+  `❯`(U+276F) 한 줄을 그린다. `>`(ASCII) 만 찾으면 라벨이 한 번도 안 바뀐다 — `src/prompt.ts` 는
+  `> ❯ › ❭ ➜` 를 모두 받고, 같은 꺾쇠를 쓰는 선택지 커서(`❯ 1. Yes`, `❯ No, exit`)는 배제한다.
+- 입력창 머리를 못 찾으면(일반 셸, y/n 확인 등) 라벨을 그대로 둔다 — 엉뚱한 문자열이 박히느니 낫다.
+- `labelAsTitle`(기본 true)이면 사이드바 제목 줄에 탭 제목 대신 이 라벨이 뜬다.
+
+> **왜 탭 제목을 쓰지 않나.** Claude Code 는 세션의 첫 작업을 요약해 콘솔 제목에 한 번 박고 그 뒤로
+> 갱신하지 않는다(2026-08-28 실측 — 작업이 네 번 바뀌는 동안 제목은 `◑ sendInput 한 줄 vs 두 줄 원인 파악`
+> 그대로였다). 제목만 보여주면 사이드바가 옛 작업 이름에, 셸이 붙인 엉뚱한 문자열에 박혀 있게 된다.
+
+> **왜 에이전트 훅을 쓰지 않나.** 훅으로 받으면 쓰는 사람이 `~/.claude/settings.json` 을 손봐야 하고
+> 플러그인이 그걸 대신 깔아줄 수도 없다. 게다가 훅 경로는 에이전트마다 규약이 다르다.
+> 설정이 하나도 없는 상태에서 도는 경로를 기본으로 둔다.
+
+### 상태 — 출력과 화면 패턴으로 추론한다
+
+PTY 출력이 흐르면 `진행중`, `idleAfterMs`(기본 2.5초) 동안 조용하면 `대기` 로 돌아간다.
+`Do you want to`, `❯ 1. Yes`, `(y/n)` 같은 패턴이 보이면 `승인대기`.
+Claude Code 가 제목에 넣는 스피너(`◐ ✳ ...`)도 진행중으로 읽는다.
+
+### 직접 지정하고 싶을 때
+
+- 사이드바에서 **우클릭 → 상태 고르기**, **더블클릭 → 이름 편집**.
+- 셸 스크립트 안에서라면 콘솔 제목을 `[AD:<status>] <라벨>` 로 바꾼다. 접두사는 표시에서 지워진다.
+
+  ```powershell
+  $host.UI.RawUI.WindowTitle = "[AD:waiting] 배포 승인 대기"
+  powershell -NoProfile -File hooksgentdeck-status.ps1 -Status running -Label "결제 버그 수정"
+  ```
+
+  status 는 `running` / `waiting` / `done` / `error` / `idle`.
+  이렇게 지정한 상태는 **고정**되어 자동 감지가 덮어쓰지 않는다(배지에 점선 밑줄).
+  우클릭 → `↺ 자동 감지로` 로 해제한다.
+
+  이 경로는 **셸 안에서 직접 실행할 때만** 통한다. 에이전트의 훅에서 부르면 안 된다 —
+  훅은 파이프 stdio 로 떠서 터미널 콘솔에 붙어 있지 않으므로 제목이 pty 까지 오지 않는다(2026-08-28 실측).
+
+## 키
+
+| 키 | 동작 |
+|---|---|
+| `Ctrl+Enter` / `Shift+Enter` | 줄바꿈 — Claude Code 가 줄바꿈으로 받는 `0x0A`(= `Ctrl+J`) 를 보낸다. `agentdeck-newline` 핫키 |
+| 우클릭 | 선택이 있으면 복사, 없으면 붙여넣기. 길게(기본 250ms) 누르면 컨텍스트 메뉴 |
+| `Ctrl+V` | 붙여넣기. **클립보드에 이미지만 있으면 리터럴 `0x16`(Ctrl+V)을 그대로 흘려보낸다** — Claude Code 도 Codex 도 이 키로 클립보드를 직접 읽는다. `agentdeck-paste` 핫키 |
+| (미배정) | `agentdeck-toggle` — 사이드바/4:3 즉시 on-off |
+
+> `Ctrl+V` 는 플러그인이 기동할 때 `agentdeck-paste` 에 자동으로 넣는다(`claimCtrlV`).
+> 동시에 Tabby 순정 `hotkeys.paste` 에서는 `Ctrl-V` 를 **뺀다** — 둘 다 걸려 있으면 한 번 눌러 두 번 붙는다.
+>
+> **왜 이미지는 `Ctrl+V` 가 아니라 `Alt+V` 였나**: 터미널의 붙여넣기는 "클립보드 *텍스트* 를 키 입력처럼
+> PTY 에 써넣는" 동작이다. PTY 는 바이트 스트림이라 이미지가 지나갈 길이 없고, 터미널 안에서 도는 앱은
+> OS 클립보드에 손댈 수 없다. Claude Code 는 자기가 클립보드를 직접 읽어서 이 문제를 푸는데,
+> `Alt+V` 가 그 "지금 클립보드를 읽어라" 신호다. 즉 두 키는 *붙여넣는 주체* 가 다르다
+> (`Ctrl+V` = 터미널이 넣어줌 / `Alt+V` = 앱이 직접 읽음). 사용자가 그걸 구분할 이유는 없으므로
+> agentdeck 이 클립보드를 미리 보고 갈라준다. 텍스트가 같이 들어 있으면(엑셀·워드 복사 등) 텍스트를 우선한다.
+> config.yaml 을 손으로 고쳐도 되지만, Tabby 는 종료할 때 메모리에 있던 설정을 다시 써서 손댄 값을 되돌린다.
+> 대가로 터미널 앱에 리터럴 `Ctrl+V`(0x16, quoted-insert)를 보낼 수 없다 — 필요하면 `claimCtrlV: false`.
+
+## 설정
+
+Tabby 설정 파일(`%APPDATA%\tabby\config.yaml`)의 `agentDeck` 아래에서 조절한다.
+
+| 키 | 기본값 | 설명 |
+|---|---|---|
+| `enabled` | `true` | 사이드바 + 4:3 레이아웃 on/off |
+| `aspectW` / `aspectH` | `4` / `3` | 터미널 뷰포트 비율 |
+| `sidebarMin` / `sidebarMax` | `200` / `560` | 사이드바 폭 범위(px) |
+| `idleAfterMs` | `2500` | 이 시간 동안 출력이 없으면 `대기` 로 |
+| `autoDetect` | `true` | 출력·제목 패턴으로 상태 추론 |
+| `showElapsed` | `true` | 경과 시간 표시 |
+| `keepRenderingWhenHidden` | `true` | 창이 가려져 있어도 사이드바를 갱신한다. 끄면 Chromium 이 rAF·타이머를 스로틀해 상태 변화가 최대 1분까지 늦게 보인다 |
+| `enterAsLabel` | `true` | Enter 로 프롬프트를 보낼 때 입력창 원문을 작업 라벨로 삼는다. 이게 라벨의 기본 경로다 |
+| `notifyChannel` | `false` | 외부 통보 채널(TCP + 상태 파일 폴링)을 연다. 라벨·상태는 코드가 스스로 채우므로 기본은 꺼 둔다 |
+| `labelAsTitle` | `true` | 사이드바 제목 줄에 탭 제목 대신 작업 라벨을 쓴다. 라벨이 없는 탭은 제목 그대로. Tabby 의 탭 제목 자체는 건드리지 않는다 |
+| `claimCtrlV` | `true` | 기동 시 `agentdeck-paste` 에 `Ctrl-V` 를 보정해 넣고, 순정 `hotkeys.paste` 에서는 뺀다 |
+| `pasteImageWithCtrlV` | `true` | 클립보드에 이미지만 있으면 텍스트 붙여넣기 대신 이미지 붙여넣기 키를 흘려보낸다 |
+| `imagePasteKey` | `alt-v` | 그때 보낼 키. `ctrl-v`(0x16) 는 Claude Code·Codex 둘 다 동작한다. `alt-v`(ESC v) 는 Claude Code 전용 폴백 |
+| `claimRightClick` | `true` | 우클릭을 플러그인이 직접 처리한다(Tabby 의 `terminal.rightClick` 은 `off` 로 내린다). Tabby 리스너가 겹쳐 붙어 붙여넣기가 2중으로 들어가던 문제 회피 |
+| `rightClickMenuMs` | `250` | 이 시간 이상 누르고 있으면 붙여넣기 대신 컨텍스트 메뉴 |
+| `terminalOpacity` | `75` | 터미널 배경 불투명도(%). 100 미만이면 컬러스킴 배경색에 알파를 넣어 `tabby-background` 의 배경 이미지가 비친다. 100 = 순정 복구 |
+| `sidebarOpacity` | `75` | 사이드바 / 창 여백 불투명도(%). 같은 목적 |
+| `redrawKickMs` | `900` | 탭이 열리고 이 시간 뒤 pty 폭을 한 번 흔들어 TUI 첫 화면 잔상을 지운다. 0 이면 끔 |
+| `rootProfileCwd` | `<작업 루트 경로>` | 새 탭이 열릴 경로 |
+| `rootProfileArgs` | `-NoLogo -ExecutionPolicy Bypass` | 셸 인자 |
+| `rootProfileAdmin` | `false` | `true` 면 탭마다 UAC 승격 |
+
+`agentdeck-toggle` 핫키에 키를 배정하면 사이드바/4:3 을 즉시 껐다 켤 수 있다(Settings → Hotkeys).
+
+### 폭이 정해지는 순서
+
+1. 터미널 폭을 `창 높이 × 4/3` 으로 잡는다.
+2. 남는 폭을 사이드바에 주되 `sidebarMin`~`sidebarMax` 로 자른다.
+3. **그러고도 폭이 남으면 4:3 을 포기하고 터미널이 흡수한다** — 오른쪽에 빈 띠를 남기지 않기 위해서다.
+
+그래서 넓은 모니터에서는 실제 비율이 4:3 보다 옆으로 길어진다.
+정확히 4:3 을 원하면 `sidebarMax` 를 `창 너비 − 창 높이 × 4/3` 으로 맞춘다.
+예를 들어 2560×1440 창(터미널 높이 약 1370)이라면 `2560 − 1827 ≈ 730`.
+
+```yaml
+agentDeck:
+  sidebarMax: 730
+```
+
+## 알려진 문제
+
+### Tabby 1.0.235 에서 새 탭이 열리지 않음
+
+```
+Error: ENOENT, node_modules\node-pty\lib\conpty_console_list_agent
+not found in ...\resources\app.asar
+```
+
+Tabby 설치본의 패키징 버그다. 해당 파일은 `app.asar.unpacked` 에 있는데 node-pty 가 `app.asar` 안에서 찾는다.
+플러그인과는 무관하며, ConPTY 를 끄면 이 코드 경로를 타지 않는다.
+
+```yaml
+# %APPDATA%\tabby\config.yaml
+terminal:
+  useConPTY: false
+```
+
+### npm 전역 명령(`claude` 등)이 실행 정책에 막힘
+
+`claude` 는 `.ps1` 래퍼라 기본 실행 정책(Restricted)에서 로드되지 않는다.
+`rootProfileArgs` 의 `-ExecutionPolicy Bypass` 가 이를 해결한다 — **해당 세션에만** 적용되고 시스템 정책은 건드리지 않는다.
+
+## 개발
+
+```powershell
+npm run watch     # 소스 감시 빌드
+```
+
+Tabby 를 `--remote-debugging-port=9222` 로 띄우면 CDP 로 내부 상태를 들여다볼 수 있다.
+플러그인이 `window.__agentdeck` 에 `app` / `config` / `status` / `relayout()` / `render()` 를 노출한다.
+
+```js
+window.__agentdeck.status.debug   // { attached, outputs, oscHits, titleHits }
+```
+
+## 구조
+
+| 파일 | 역할 |
+|---|---|
+| `src/index.ts` | NgModule — provider 등록, 서비스 기동 |
+| `src/deck.service.ts` | 사이드바 DOM, 4:3 레이아웃, 세션·제목 감시 |
+| `src/detect.ts` | 출력·제목에서 상태를 읽어내는 규칙 |
+| `src/status.service.ts` | 탭별 상태 보관 |
+| `src/decorator.ts` | Tabby 공식 확장점(TerminalDecorator) 경유 출력 구독 |
+| `src/profile.service.ts` | 작업 루트 프로필 등록 |
+| `src/notify.service.ts` | Claude Code 훅이 남긴 상태 파일을 읽어 탭에 반영 |
+| `src/config.ts` | 기본 설정값 |
+| `src/hotkeys.ts` | 핫키 선언 |
+
+### 구현하며 부딪힌 것들
+
+- **탭은 래퍼에 싸여 있다.** `app.tabs` 의 원소는 `SplitTabComponent` 이고 터미널은 그 자식이다.
+  상태 키를 정규화하지 않으면 자식에 쓰고 부모를 읽어 영영 매칭되지 않는다.
+- **래퍼가 자식보다 먼저 목록에 들어온다.** 한 번 훑고 "감시 완료" 로 표시하면 빈 래퍼만 잡고 끝난다.
+  pane 은 호출될 때마다 다시 훑는다.
+- **`HotkeysService` 는 `HotkeyProvider` 들을 주입받는다.** provider 생성자에서 그것을 다시 주입하면
+  순환 의존으로 부분 초기화된 인스턴스가 넘어온다(`Cannot read properties of undefined`). 핫키 구독은 다른 서비스에서.
+- **CSS 로만 폭을 바꾸면 pty 가 따라오지 않을 수 있다.** Tabby 의 xterm 은 `attach()` **맨 끝**에서야
+  `ResizeObserver` 를 건다(`tabby-terminal/dist/index.js:40979`). 그 앞에는 `await` 가 여러 개 있어서,
+  탭이 붙는 도중(`tabOpened$`/`tabsChanged$`)에 `.content.main` 폭을 바꾸면 그 변경이 아무에게도 관측되지 않고
+  유실된다. 결과: xterm 은 넓은데 pty 는 옛 폭 그대로 → Claude Code 같은 전체화면 TUI 가 화면보다 좁게 그리고
+  오른쪽에 지워지지 않은 옛 프레임이 박혀 있다. 창을 복원→최대화로 흔들면 OS 리사이즈 경로를 타서 즉시 복구된다
+  (2026-08-28 실측). 그래서 `relayout()` 은 폭이 바뀔 때마다, 그리고 `frontendReady$` 때
+  `frontend.fitAddon.fit()` 을 직접 호출한다. 숨겨진 탭은 컨테이너 폭이 0 이라 건너뛴다.
+
+- **입력창 머리글자를 `>` 로 가정한 것이 라벨이 안 바뀌던 진짜 원인이다.** 앞서 "화면 아래 14줄만
+  읽어서" 로 진단해 스캔 기준을 커서 줄로 옮겼는데도 증상이 그대로였다. 실제 원인은 정규식 —
+  Claude Code 2.1.252 의 입력창은 `❯`(U+276F) 로 시작해서 `/^>\s*/` 에 절대 걸리지 않았다.
+  CDP 로 읽은 xterm 버퍼 원문이 증거다(2026-09-01):
+  `"────────…"`, `"❯ "`, `"────────…"`, `"  ⏵⏵ auto mode on (shift+tab to cycle)"`.
+  같은 실수를 반복하지 않으려면 `readPromptLine` 이 빈손일 때 남기는
+  `enter-label miss ... tail=` 진단 라인(커서 주변 4줄 원문)을 먼저 볼 것 —
+  "버퍼를 못 읽음" 과 "머리를 못 찾음" 을 이 줄 하나로 가른다.
+
+- **`package.json` 에 `author` 가 없으면 플러그인이 조용히 로드되지 않는다.**
+  Tabby 의 `parsePluginInfo` 가 `author.name` 을 읽다가 예외를 삼킨다.

package/dist/api.d.ts

@@ -0,0 +1,21 @@
+/** 사이드바에 표시되는 작업 상태 */
+export type WorkStatus = 'idle' | 'running' | 'waiting' | 'done' | 'error';
+export interface StatusStyle {
+    icon: string;
+    label: string;
+    color: string;
+}
+/** 상태별 표시 규칙 — 사이드바 배지와 좌측 컬러바에 함께 쓰인다 */
+export declare const STATUS_STYLES: Record<WorkStatus, StatusStyle>;
+export interface TabState {
+    /** 현재 상태 */
+    status: WorkStatus;
+    /** 작업 이름 (사용자 지정 또는 훅이 보낸 값) */
+    label: string;
+    /** 상태가 마지막으로 바뀐 시각 */
+    since: number;
+    /** true = 수동/훅 지정. 자동 감지가 덮어쓰지 않는다 */
+    pinned: boolean;
+    /** 마지막 PTY 출력 시각 */
+    lastOutput: number;
+}

package/dist/config.d.ts

@@ -0,0 +1,179 @@
+import { ConfigProvider } from 'tabby-core';
+/** @hidden */
+export declare class AgentDeckConfigProvider extends ConfigProvider {
+    defaults: {
+        agentDeck: {
+            /** 레이아웃/사이드바 전체 on-off */
+            enabled: boolean;
+            /** 터미널 뷰포트 가로:세로 비율 */
+            aspectW: number;
+            aspectH: number;
+            /**
+             * 사이드바 폭 제한 (px).
+             * sidebarMax 를 키우면 사이드바가 그만큼 넓어지고, 그래도 남는 폭은 터미널이 흡수한다
+             * (4:3 보다 "창을 꽉 채운다" 가 우선). config.yaml 의 agentDeck 아래에서 조절한다.
+             */
+            sidebarMin: number;
+            sidebarMax: number;
+            /**
+             * 훅이 상태를 밀어 넣는 TCP 채널의 포트 (127.0.0.1 전용).
+             *
+             * Windows 임시 포트 범위(49152~65535) 아래로 잡는다 — 그 위 번호는 OS 가
+             * 다른 프로세스에 먼저 내줄 수 있어 기동 순서에 따라 충돌한다.
+             * 이 번호가 물려 있으면 0(임의 포트)으로 물러나고, 실제 번호는 어느 쪽이든
+             * `%LOCALAPPDATA%\tabby-agentdeck\port` 에 적히므로 훅은 그 파일만 보면 된다.
+             */
+            notifyPort: number;
+            /**
+             * 외부 통보 채널(TCP + 상태 파일 폴링)을 열지.
+             *
+             * 기본은 꺼 둔다 — 라벨은 Enter 시점 입력창에서(`enterAsLabel`), 상태는 출력 패턴에서
+             * 플러그인이 스스로 얻으므로 바깥에서 밀어 넣어 줄 것이 없다. 켜 두면 쓰지도 않는
+             * 400ms 폴링과 포트 점유만 남는다. 외부 도구가 상태를 직접 보고하고 싶을 때만 켠다.
+             */
+            notifyChannel: boolean;
+            /** PTY 출력이 이 시간(ms) 이상 없으면 running -> idle */
+            idleAfterMs: number;
+            /** 출력 패턴으로 상태를 자동 추론할지 */
+            autoDetect: boolean;
+            /** 사이드바에 경과 시간 표시 */
+            showElapsed: boolean;
+            /**
+             * 창이 가려져 있어도 사이드바를 계속 갱신한다 (Electron backgroundThrottling 해제).
+             *
+             * 끄면 Chromium 기본 동작으로 돌아간다 — 창이 hidden 이면 rAF 가 멈추고 타이머가
+             * 1초, 5분 이상 가려지면 분당 1회까지 느려져서 훅이 보낸 done 이 화면에 늦게 뜬다.
+             * 켜 두면 훅 보고가 바로 보이는 대신 가려진 동안에도 렌더 비용이 조금 든다
+             * (사이드바 DOM 갱신뿐이라 미미하다).
+             */
+            keepRenderingWhenHidden: boolean;
+            /**
+             * 사이드바의 제목 줄에 탭 제목 대신 작업 라벨을 쓴다.
+             * Claude Code 는 세션 시작 때 붙인 콘솔 제목을 계속 들고 있어서 다음 작업으로
+             * 넘어가도 안 바뀐다(2026-08-28 실측) — 제목만 보여주면 사이드바가 옛 작업 이름에
+             * 박혀 있게 된다. 라벨이 없는 탭은 그대로 제목을 보여준다.
+             * Tabby 의 탭 제목 자체(customTitle)는 건드리지 않는다 — 앱이 넣는 제목을
+             * 가리지 않아야 그게 갱신되는지 계속 관측할 수 있다.
+             */
+            labelAsTitle: boolean;
+            /**
+             * Enter 로 프롬프트를 보낼 때 그 원문을 작업 라벨로 삼는다 (claimEnterLabel 주석 참고).
+             * 훅도 콘솔 제목도 못 믿는 배포 환경에서 라벨을 최신으로 유지하는 유일한 경로다.
+             * Shift+Enter / Ctrl+Enter(줄바꿈)는 잡지 않는다.
+             */
+            enterAsLabel: boolean;
+            /**
+             * Ctrl+V 를 agentdeck 이 직접 받는다 (document 캡처 단계에서 한 번만).
+             *
+             * 핫키(`agentdeck-paste`)로 받던 시절에는 Tabby 가 같은 keydown 을 두 경로로
+             * HotkeysService 에 밀어 넣어 한 번 눌러 두 번 붙는 일이 남아 있었다
+             * (deck.service.ts `ensurePasteHotkey` 주석에 원인). 캡처로 옮기고 전파를 끊으면서
+             * 경로가 하나로 정리됐다.
+             *
+             * false 로 두면 터미널 앱에 리터럴 Ctrl+V(0x16, quoted-insert)를 보낼 수 있다
+             */
+            claimCtrlV: boolean;
+            /**
+             * 클립보드에 이미지만 있으면 Ctrl+V 로도 이미지가 들어가게 한다.
+             *
+             * 터미널 붙여넣기는 "클립보드 텍스트를 PTY 에 써넣는" 동작이라 이미지는 지나갈 수가 없다.
+             * 대신 에이전트 CLI 는 자기가 OS 클립보드를 직접 읽는 키를 따로 두므로,
+             * 이미지일 때만 그 키를 흘려보낸다 (어떤 키인지는 `imagePasteKey`).
+             */
+            pasteImageWithCtrlV: boolean;
+            /**
+             * 이미지 전용 클립보드일 때 흘려보낼 키의 **기본값**. `'alt-v'`(ESC v) | `'ctrl-v'`(0x16).
+             *
+             * 평소에는 이 값이 쓰이지 않는다 — 탭에서 도는 앱을 보고 자동으로 갈라 보내기 때문이다
+             * (Claude Code = ESC v / Codex = 0x16, `deck.service.ts` `sendImagePasteKey` 주석에 실측).
+             * 앱을 못 알아낼 때(SSH 세션 등)의 폴백으로만 쓴다.
+             *
+             * Claude Code 는 PTY 로 들어온 0x16 에 반응하지 않는 것이 실측됐으므로
+             * (`.agentdeck-diag.log` 2026-08-28T09:33:47~48 에 `paste image (ctrl-v)` 5줄, 이미지 미삽입)
+             * 폴백은 더 널리 먹히는 ESC v 로 둔다.
+             */
+            imagePasteKey: string;
+            /**
+             * 우클릭(붙여넣기 / 선택 시 복사)을 agentdeck 이 직접 처리한다.
+             * Tabby 자체 처리를 끄고(terminal.rightClick = 'off') 캡처 단계에서 한 번만
+             * 처리하므로, 핸들러가 두 번 걸려 붙여넣기가 2중으로 들어가던 문제가 사라진다.
+             * false 로 두면 Tabby 순정 동작으로 되돌아간다
+             */
+            claimRightClick: boolean;
+            /** 우클릭을 이 시간(ms) 이상 누르고 있으면 붙여넣기 대신 컨텍스트 메뉴 */
+            rightClickMenuMs: number;
+            /**
+             * 터미널 배경 불투명도 (%). 100 이면 순정(완전 불투명).
+             *
+             * tabby-background 플러그인은 배경 이미지를 `.content-tab-active::before`
+             * (position:fixed, z-index:-1) 로 **모든 내용 뒤에** 깐다. 그런데 xterm 은
+             * 컬러스킴의 `background` 색으로 셀을 직접 칠하므로, 그 색에 알파가 없으면
+             * 이미지는 터미널 영역에서 100% 가려진다 — "배경 이미지를 넣었는데 아무 데도 안 보인다"
+             * 의 정체가 이것이다(2026-08-28 실측: colorScheme.background = '#171717' 불투명).
+             * Tabby 는 xterm 을 `allowTransparency: true` 로 만들기 때문에 알파만 넣어주면 비친다.
+             *
+             * 그래서 agentdeck 이 기동 시 `terminal.colorScheme.background` 를 8자리 hex 로 바꿔준다.
+             * 100 으로 되돌리면 알파를 떼어 원래 색으로 복구한다 (되돌리기 가능).
+             */
+            terminalOpacity: number;
+            /** 사이드바 배경 불투명도 (%). 터미널과 같은 이유로 배경 이미지가 비치게 한다 */
+            sidebarOpacity: number;
+            /**
+             * 새 탭에서 첫 화면이 깨질 때, 세션이 열린 뒤 이 시간(ms)에 pty 크기를 한 번 흔든다.
+             * 0 이면 끄기. 자세한 이유는 deck.service 의 kickPtySize 주석 참고
+             */
+            redrawKickMs: number;
+            /**
+             * 기동 후 이 시간(ms)에 **창을 복원→최대화로 한 번 흔든다**. 0 이면 끄기.
+             *
+             * pty 크기 흔들기(redrawKickMs)가 놓치는 경우를 위한 최종 보험이다. 사용자가 손으로
+             * 하던 바로 그 동작이고, OS 가 진짜 SIGWINCH 를 두 번 내므로 TUI 가 반드시 다시 그린다.
+             * 창이 최대화 상태일 때만 동작한다 — 아니면 창 상태를 멋대로 바꾸게 되므로.
+             */
+            startupWindowKickMs: number;
+            /**
+             * 작업 루트 전용 프로필을 만들고 기본 프로필로 삼는다.
+             *
+             * 에이전트 CLI 는 "어느 폴더에서 떴는가" 가 곧 작업 대상이라 새 탭마다 cd 하게 되는데,
+             * 그걸 없애려는 기능이다. 기본은 꺼져 있다 — 남의 PC 에 설치되자마자 프로필을 만들고
+             * 기본값을 가로채면 곤란하므로, 쓰려는 사람이 `rootProfileCwd` 를 채우고 켜야 한다.
+             */
+            rootProfile: boolean;
+            rootProfileName: string;
+            rootProfileCwd: string;
+            rootProfileCommand: string;
+            /**
+             * -ExecutionPolicy Bypass 가 필요한 이유: npm 전역 명령(claude 등)은 .ps1 래퍼인데
+             * 기본 실행 정책(Restricted)에서는 로드가 막힌다. 이 인자는 해당 세션에만 적용되고
+             * 시스템/사용자 정책은 건드리지 않는다.
+             */
+            rootProfileArgs: string[];
+            /**
+             * 탭에 주입할 환경변수. Claude Code 등 TUI 는 이 값들이 없으면 색 지원을 낮게 잡아
+             * 흑백에 가깝게 렌더된다 (Windows 는 TERM 이 기본으로 비어 있다).
+             */
+            rootProfileEnv: {
+                TERM: string;
+                COLORTERM: string;
+                FORCE_COLOR: string;
+            };
+            /** true 면 탭마다 UAC 승격 (Tabby 자체를 관리자로 띄웠다면 불필요) */
+            rootProfileAdmin: boolean;
+            /** 기본 프로필 지정을 이미 했는지 — 사용자 선택을 매번 덮어쓰지 않기 위한 플래그 */
+            rootProfileClaimed: boolean;
+        };
+        hotkeys: {
+            'agentdeck-toggle': any[];
+            /**
+             * Claude Code 는 0x0A(Ctrl+J)를 줄바꿈으로 받는다. Tabby 로 옮겨 왔으니
+             * Ctrl+Enter / Shift+Enter 로도 같은 바이트를 보낸다
+             */
+            'agentdeck-newline': string[];
+            /**
+             * Tabby 순정 `paste` 대신 이걸 쓴다 — 클립보드가 이미지인지 텍스트인지 보고
+             * 갈라야 하는데 순정 paste 는 텍스트만 알기 때문
+             */
+            'agentdeck-paste': string[];
+        };
+    };
+}