tabby-agentdeck 0.3.0 → 1.0.0

package/README.md

@@ -4,19 +4,21 @@ Tabby 터미널 플러그인. **Claude Code · Codex 같은 AI 에이전트 CLI
 
 터미널 뷰포트를 **4:3 으로 고정**하고 남는 공간에 **세션 목록 + 작업 상태 사이드바**를 그린다.
 어느 에이전트가 돌고 있고 어느 쪽이 내 입력을 기다리는지 탭을 옮겨 다니지 않고 한눈에 본다.
+에이전트가 만든 문서·그림은 **미리보기 패널**에서 터미널 옆에 띄워 확인한다.
 거기에 에이전트 CLI 가 터미널에서 겪는 문제들(이미지 붙여넣기, 줄바꿈 키, pty 폭 어긋남)을 같이 손봐 둔다.
 
 ```
-┌──────────────────────────────┬──────────────────┐
-│                              │ AGENT DECK    4   │
-│     터미널 (창 높이 × 4/3)     ├──────────────────┤
-│                              │ ● 진행중  리팩터링 │
-│     Tabby 순정 탭바는 숨김      │ ⏸ 승인대기 재빌드 │
-│                              │ ✔ 완료   테스트   │
-│                              │ ○ 대기            │
-│                              ├──────────────────┤
-│                              │ + 새 탭 │ 설정    │
-└──────────────────────────────┴──────────────────┘
+┌────────────────────┬──────────────────┬──────────────────┐
+│                    │ note.md   ＋ ⟳ ✕ │ AGENT DECK    4  │
+│  터미널 (4:3 기준)   ├──────────────────┼──────────────────┤
+│                    │ note.md  shot.png│ ● 진행중  리팩터링 │
+│  Tabby 순정 탭바는   ├──────────────────┤ ⏸ 승인대기 재빌드 │
+│  숨김               │ # 제목            │ ✔ 완료   테스트   │
+│                    │ 본문이 그려진다     │ ○ 대기            │
+│                    │ [그림]            ├──────────────────┤
+│                    │ 742 B · 방금      │ + 새 탭 │ 설정    │
+└────────────────────┴──────────────────┴──────────────────┘
+      터미널              미리보기 패널        세션 목록
 ```
 
 Windows 에서 만들고 검증했다. 상태 통보 훅은 PowerShell 스크립트라 Windows 전용이고, 그 외 기능은 플랫폼을 가리지 않는다.
@@ -27,9 +29,21 @@ Windows 에서 만들고 검증했다. 상태 통보 훅은 PowerShell 스크립
 |---|---|
 | **4:3 기준 폭 계산** | 창 높이에서 폭을 역산해 터미널을 고정폭으로 만든다. 남는 폭은 사이드바가 갖고, 그러고도 남으면 터미널이 흡수한다 |
 | **사이드바 탭 관리** | 클릭=선택, `×`=닫기, 더블클릭=작업 이름 편집, 우클릭=상태 직접 지정 |
+| **검색 · 상태 필터** | 헤더 아래 검색창으로 제목·작업이름·작업폴더를 좁히고, 상태 칩을 눌러 그 상태만 본다. Esc 로 해제 |
+| **순서 바꾸기** | 사이드바 줄을 끌어 옮긴다(순정 탭바 순서도 함께). 목록 끝에 커서를 대고 있으면 **저절로 흘러가** 화면 밖 자리로도 한 손짓에 옮긴다. 상태순 정렬이 켜져 있으면 막고 이유를 알린다 |
+| **키보드로 다루기** | `Ctrl+Shift+L` 로 목록에 들어가 `↑↓` 로 훑고 Enter 로 고른다. **훑는 동안 탭은 바뀌지 않는다** — 지나가는 탭의 출력이 화면을 채우지 않게 포커스와 선택을 갈랐다. `Ctrl+W` 로 지금 탭(목록에서는 포커스 줄)을 닫는다 |
+| **결과물 미리보기** | 에이전트가 만진 md · 이미지 · 표(csv/tsv) · 코드를 터미널 옆 패널에서 본다. 화면에 찍힌 경로를 스스로 주우므로 Claude Code · Codex · Gemini 를 가리지 않는다 |
+| **끌어다 놓기** | 파일을 패널에 놓으면 바로 열리고, **터미널 위에 놓으면** `패널에 띄우기` / `경로 붙여넣기` 를 물어본다 |
+| **변경 보기** | 같은 패널의 `변경` 탭이 작업트리의 `git diff` 를 보여준다 — 파일 목록 · `+N -M` · 줄번호 붙은 유니파이드 diff. 누가 고쳤는지와 무관하게 성립한다 |
+| **`파일:라인` 참조** | diff 나 코드 보기에서 줄을 누르면 그 위치를 터미널에 넣는다(Shift+클릭=범위). "이 줄 고쳐" 를 타이핑 없이 |
+| **스테이지 · 커밋** | `변경` 탭에서 파일 딱지를 눌러 `git add`/`unstage` 하고, 메시지를 적어 커밋한다. **두 번 눌러야 커밋된다**(첫 누름은 확인 대기) |
+| **세션 그룹** | 탭을 작업 폴더(프로젝트)별로 묶고 접는다. 그룹이 하나뿐이면 헤더를 그리지 않고 순서도 건드리지 않는다 |
+| **한글 조합 보정** | 조합 중인 음절이 커서를 따라가거나 새 줄로 내려가지 않게, pty 에 쓰기 전에 조합이 끝나기를 기다린다 |
+| **에이전트 프로필** | 어느 CLI 가 도는 탭인지 알아내고(프로세스 → 제목) 그에 맞는 규칙을 쓴다. 새 CLI 지원은 프로필 한 덩이 추가로 끝난다 |
 | **마우스 도킹** | 헤더를 끌어 좌/우/상/하 어느 가장자리에나 붙이고, 경계선을 끌어 크기를 바꾼다 |
-| **작업 상태** | 진행중 / 승인대기 / 한도 도달 / 완료 / 오류 / 대기 를 색·배지·경과시간으로 표시 |
+| **작업 상태** | 진행중 / 승인대기 / 한도 도달 / 완료 / 오류 / 대기 를 색·배지·경과시간으로 표시. 훅이 없어도 화면 문구로 판정하고, **왜 멈췄는지**(승인 대상·한도)를 배지에 붙인다 |
 | **상태별 집계** | 헤더 오른쪽에 상태별 탭 수를 `⏸ 2 ● 3 ○ 1` 처럼 급한 순서(승인대기 → 오류 → 한도 도달 → 진행중 → 완료 → 대기)로 보여준다. `sortByStatus` 를 켜면 같은 순서로 탭이 정렬된다 |
+| **서브에이전트 개수** | 그 세션이 백그라운드 에이전트를 몇 개 돌리고 있는지 줄에 `❖3` 으로 보인다. 대화 기록에서 **띄운 것과 끝난 것을 대조**해 세므로 훅이 알려주지 않아도 맞는다 |
 | **작업 이름** | Enter 로 프롬프트를 보내는 순간 입력창 원문을 읽어 라벨로 삼는다 |
 | **Claude Code 훅 연동** | 설정 창에서 한 번 설치하면 에이전트가 상태를 직접 알려준다 (선택) |
 | **기본 프로필** | 새 탭을 항상 지정한 작업 루트에서 연다 |
@@ -79,6 +93,18 @@ Shift+Enter / Ctrl+Enter 는 줄바꿈이라 라벨을 바꾸지 않고, 입력
   훅 보고는 플러그인이 탭 셸에 심은 `AGENTDECK_TAB` 환경변수로 어느 탭인지 확정한다
   (0.2.2 이전에 열린 탭·재시작으로 복원된 탭은 프로세스 계보로 폴백).
 
+### 어느 에이전트인지 알아내는 법
+
+탭마다 **어떤 CLI 가 도는지** 알아내고(자식 프로세스 이름 → 안 잡히면 탭 제목), 그 에이전트의 규칙을 쓴다.
+지금 아는 것은 Claude Code · Codex CLI · Gemini CLI 셋이고, 새 CLI 는 프로필 한 덩이를 더하면 된다.
+
+프로필이 정하는 것 — 상태 문구(대기·작업중), 제목 스피너, **이미지 붙여넣기 키**(Claude=`ESC v` / Codex=`0x16`),
+입력창 머리글자. 셸만 떠 있는 탭은 `알 수 없음` 이고, 그때는 아는 규칙을 모두 합쳐 판정한다.
+
+> **관측된 값만 좁게 쓴다.** Codex·Gemini 의 화면 문구는 이 리포에서 관측된 바가 없어, 그 두 에이전트는
+> 상태 판정에 합집합(= 예전과 같은 규칙)을 쓴다. 프로필을 붙였다는 이유로 판정이 예전보다 나빠지면
+> 개선이 아니기 때문이다. 실측이 생기면 그 프로필의 `patternsProven` 을 켜면 된다.
+
 ### 직접 지정
 
 - 사이드바에서 **우클릭 → 상태 고르기**, **더블클릭 → 이름 편집**.
@@ -92,6 +118,24 @@ Shift+Enter / Ctrl+Enter 는 줄바꿈이라 라벨을 바꾸지 않고, 입력
   직접 지정한 상태는 **고정**되어 자동 감지가 덮어쓰지 않는다(배지에 점선 밑줄). 우클릭 → `↺ 자동 감지로` 로 해제한다.
   이 경로는 셸 안에서 직접 실행할 때만 통한다 — 에이전트 훅에서는 콘솔 제목이 터미널까지 오지 않는다.
 
+### 서브에이전트 몇 개 돌고 있나
+
+Claude Code 가 백그라운드로 에이전트를 띄우면 그 개수가 줄에 `❖3` 으로 붙는다.
+줄에 마우스를 올리면 무엇이 도는지 목록과 가장 오래된 것의 경과가 나온다.
+
+세는 방법은 **그 세션의 대화 기록에서 띄운 것과 끝난 것을 대조**하는 것이다
+(`~/.claude/projects/*/<세션 id>.jsonl`). 훅이 알려 주는 값이 아니라 기록이 근거이므로,
+훅이 상태를 안 보내는 동안에도 개수는 맞는다. 세션과 탭을 잇는 것은 훅이 쓰는 상태 파일이라
+**훅을 설치하지 않으면 이 표시도 나오지 않는다**(`notifyChannel` 이 꺼져 있어도 마찬가지다).
+
+기록 파일은 수십 MB까지 자라므로 **자란 만큼만** 읽는다 — 2초에 한 번 크기만 확인하고,
+커진 경우에만 그 뒤쪽을 읽어 누적한다. 처음 붙는 세션은 한 번 전체를 훑어야 해서
+개수가 몇 초 늦게 나타날 수 있다.
+
+한 가지 알아 둘 것 — 에이전트를 Esc 로 취소하거나 CLI 가 죽으면 **끝났다는 기록이 안 남아**
+개수가 줄지 않을 수 있다. 그걸 시간으로 감추지 않는다(진짜 오래 도는 것을 지우게 된다).
+대신 툴팁의 경과가 계속 늘어나므로 그것으로 알아볼 수 있다.
+
 ### 알림
 
 창이 다른 앱 뒤에 가 있을 때(포커스 없음) 어느 탭이 `승인대기` · `오류` · `한도 도달` 로 넘어가면 OS 쪽에 알린다 —
@@ -100,6 +144,109 @@ Shift+Enter / Ctrl+Enter 는 줄바꿈이라 라벨을 바꾸지 않고, 입력
 OS 토스트(`alertToast`)는 기본으로 꺼져 있다 — 켜면 토스트를 눌러 바로 그 탭으로 갈 수 있다.
 창이 앞에 있을 때는 셋 다 아무 일도 하지 않는다. 사이드바가 이미 보이고 있기 때문이다.
 
+## 결과물 미리보기 패널
+
+에이전트가 만든 것이 문서나 그림이면 터미널 안에서는 확인할 수 없다. 그래서 탐색기로 나가서 열게 되고,
+그 왕복 때문에 결과물을 안 보고 넘어간다. 그 자리를 메우는 패널이다 — 사이드바의 **▤** 버튼이나
+`agentdeck-view` 단축키로 여닫는다. 여닫은 상태는 다음 기동에도 복원된다.
+
+**보여주는 것**
+
+| 종류 | 어떻게 |
+|---|---|
+| `md` `markdown` `mdx` | 제목·표·목록·코드·인용·체크박스·이미지까지 그려서 보여준다. 문서 안의 이미지도 같이 뜬다 |
+| `png` `jpg` `gif` `webp` `svg` `bmp` `ico` `avif` | 원본 크기로(패널보다 크면 폭에 맞춰) 그린다 |
+| `csv` `tsv` | 표로 그린다. 따옴표로 감싼 칸(`"a,b"`)을 한 칸으로 읽는다 |
+| 코드·텍스트 (`.ts` `.cs` `.py` `.json` `.log` …) | 줄 번호를 붙여 보여준다 |
+
+**파일이 패널에 올라오는 세 경로**
+
+1. **화면에 찍힌 경로를 줍는다** — `Edited src/hero.tsx`, `Wrote D:\a\b.md`, `Read build.py` 처럼
+   에이전트가 만진 파일을 찍으면 그것을 최근 목록(위쪽 칩)에 쌓는다. **어느 에이전트든 통한다** —
+   훅이 있는 Claude Code 뿐 아니라 Codex·Gemini 도 경로는 화면에 찍기 때문이다.
+   상대경로는 그 탭의 작업 폴더로 풀고, 실제로 있는 파일만 올린다. 최근 목록은 **탭마다 따로**다.
+2. **끌어다 놓기** — 탐색기·에디터에서 파일을 패널에 떨어뜨린다.
+3. **경로 직접 입력** — **＋** 를 눌러 경로를 넣는다(`Enter` 로 열고 `Esc` 로 접는다).
+   **없는 파일이면 만들어 준다** — `Enter` 를 한 번 더 치면 (필요하면 상위 폴더까지) 만들고
+   곧바로 편집으로 들어간다. 메모 한 장 시작하려고 탐색기로 나갈 일이 없다. 두 번 치게 한 이유는
+   오타로 친 경로에 빈 파일이 조용히 생기면 나중에 그 오타를 찾는 값이 더 크기 때문이다.
+
+열어 둔 파일이 바뀌면 **스스로 다시 읽는다** — 에이전트가 문서를 고치는 동안 옆에서 따라간다.
+패널이 닫혀 있어도 **읽어는 둔다**(`문서 패널에 읽어두기`, 기본 켬) — 그리지만 않고 최근 칩과
+"다음에 열면 보여줄 파일" 을 계속 갈아 두므로, 작업이 한창일 때 `▤` 를 누르면 **그때까지 건드린
+파일들이 칩으로 쌓여 있고 본문은 가장 최근 파일**이다(`변경` 을 보고 있었으면 그 자리에서 diff 를
+다시 읽는다). 같은 파일이라도 여는 김에 다시 읽는다 — 닫힌 동안에는 파일 감시가 꺼져 있어서다.
+**여닫기는 사람 몫이 기본**이다 — 결과물이 나오는 순간 패널까지 저절로 열리기를 원하면
+**설정 → 미리보기 패널 → `패널 자동으로 열기`** 를 켠다(기본 꺼짐). 반대로 `읽어두기` 를 끄면
+아무것도 자동으로 하지 않는다 — 경로는 최근 칩에만 쌓이고 무엇을 볼지는 사람이 고른다.
+문서 안의 링크는 웹이면 브라우저로, 로컬 파일이면 이 패널에서 연다.
+
+**탭을 옮기면 패널도 그 탭 것으로 바뀐다** — 최근 칩과 `변경` 탭뿐 아니라 **본문도** 그 세션이
+마지막으로 보던 파일로 돌아간다. 아무것도 안 본 탭에서는 빈 화면이다. 옆에 남의 탭 문서가 떠 있으면
+그것이 지금 탭의 것이라고 착각하기 때문이다. 탭을 옮기는 것만으로 패널이 **열리지는 않는다** —
+닫혀 있으면 다음에 열 때 맞춰진다.
+
+**고쳐서 저장한다 — `✎`**
+
+읽기만 되면 오타 하나에도 에디터를 따로 열어야 하고, 그 왕복이 이 패널이 없애려던 것과 같다.
+`✎` 를 누르면 본문 자리가 편집기가 된다. `저장`(`Ctrl+S`) · `취소`(`Esc`).
+
+- 글자 파일(`md` · 코드 · 텍스트 · `csv`)만 편집한다. 이미지·바이너리에서는 버튼이 흐려진다.
+- **너무 큰 파일은 열지 않는다** (1.5MB 넘음). 보기는 앞부분만 읽어도 되지만 저장은 파일을 통째로
+  다시 쓰므로, 앞부분만 들고 저장하면 뒷부분이 사라진다. 그래서 전체를 읽을 수 있을 때만 연다.
+- **BOM 과 개행(CRLF/LF)을 원본 그대로 되돌린다.** 안 그러면 한 줄만 고쳐도 P4·git diff 가
+  파일 전체를 바뀐 것으로 본다.
+- 편집하는 동안에는 **아무도 화면을 덮지 못한다** — 파일 감시의 자동 재읽기도, 새 파일 따라가기도
+  비켜 간다. 그 사이 파일이 밖에서 바뀌었으면 저장할 때 한 번 더 묻는다(두 번째 누름이 덮어쓴다).
+- **읽기 전용 파일은 열자마자 알린다** (`읽기 전용` 표시). 다 쳐 놓고 저장할 때 알면 그 타이핑이
+  헛일이 되기 때문이다. 저장을 누르면 `읽기 전용이다 (P4 면 p4 edit 먼저) — 다시 누르면 속성을
+  풀고 저장한다` 로 한 번 막는다. **말없이 속성을 풀지 않는 이유** — 이 환경에서 읽기 전용의
+  정체는 대개 P4 에서 체크아웃하지 않은 파일이고, 체크아웃 없이 쓴 내용은 다음 `p4 sync` 에
+  조용히 덮인다.
+- 저장하지 않은 편집이 있으면 다른 파일이나 `변경` 탭으로 넘어가지 않는다.
+
+**찾는다 — `🔍` / `Ctrl+F`**
+
+대소문자를 가리지 않고 본문에서 찾아 표시하고, `Enter`(다음) · `Shift+Enter`(이전) 로 오간다.
+`Esc` 로 닫으면 표시만 걷히고 본문 글자는 그대로다. 편집 중이면 편집기 안에서 찾아 그 자리를
+선택한다. **`Ctrl+F` 는 패널 안에서만 듣는다** — 터미널의 `Ctrl+F`(less·vim)를 뺏지 않으려는 것이라,
+본문을 한 번 누른 뒤에 쓴다.
+
+패널 폭은 터미널과 닿는 경계선을 끌어 바꾼다. **패널을 열면 4:3 이 완화되고 터미널이 그만큼 좁아진다** —
+사이드바는 줄지 않는다. 울트라와이드에서는 패널을 열어도 4:3 이 그대로 유지된다.
+
+> 문서 안의 원문 HTML 은 **글자로만** 보여준다(태그로 만들지 않는다). 참조 링크(`[a][1]`)와 각주는 지원하지 않는다.
+
+### `변경` 탭 — 작업트리의 diff
+
+헤더 아래 `파일` / `변경` 스위치로 바꾼다. `변경` 은 그 탭의 작업 폴더에서 `git diff HEAD` 를 읽어
+
+- `3개 파일 · +716 -15` 요약과 파일 목록(상태 딱지 + `+N -M`). 파일명을 누르면 그 파일 diff 로 스크롤한다
+- 파일별 유니파이드 diff — 구/신 줄번호를 양쪽에 붙이고 추가·삭제·문맥·헝크를 색으로 가른다
+- 추적되지 않은 파일은 이름만 따로 (내용 diff 는 하지 않는다)
+
+를 보여준다. **에이전트를 가리지 않는 이유가 미리보기와 같다** — 근거가 훅이 아니라 git 작업트리라서
+누가 고쳤든 성립한다. 저장소가 아니거나 git 이 없거나 작업 폴더를 아직 모르면 그 사실을 한 줄로 알린다.
+
+#### 스테이지 · 커밋
+
+파일 줄 왼쪽의 딱지가 **스테이지 상태**다 — `unstaged` / `staged` / `both`(일부만 올라감) /
+`untracked` / `conflict`. 누르면 그 파일을 `git add` 하거나 되돌린다(`git reset`). 아래 줄에
+`staged N · unstaged M` 요약과 메시지 입력창, 커밋 버튼이 있다.
+
+**우발 커밋을 막는 네 겹 —**
+
+1. 메시지가 비어 있으면 버튼이 잠긴다
+2. 공백만 넣으면 거부하고 이유를 적는다
+3. 첫 누름은 커밋하지 않고 `커밋 확인` 으로 바뀐다(색도 경고색). **두 번째 누름**에 실행된다
+4. 확인 대기 중에 메시지를 고치면 그 대기가 풀린다 (다른 메시지로 잘못 커밋되지 않게)
+
+스테이지된 것이 없으면 커밋하지 않는다 — `git commit -a` 로 넓히지 않는다.
+
+> 작업 폴더는 **탭이 열릴 때의 cwd** 다. 셸에서 `cd` 로 옮겨도 Tabby 가 알려주는 값은 바뀌지 않으므로
+> (Windows 로컬 세션 실측), 다른 저장소를 보려면 그 폴더에서 새 탭을 연다.
+> `git` 은 상위 폴더로 올라가며 저장소를 찾는다 — 홈 디렉토리가 저장소면 아무 폴더에서나 그것이 잡힌다.
+
 ## 키
 
 | 키 | 동작 |
@@ -107,12 +254,75 @@ OS 토스트(`alertToast`)는 기본으로 꺼져 있다 — 켜면 토스트를
 | `Ctrl+Enter` / `Shift+Enter` | 줄바꿈 (`0x0A` 전송). `agentdeck-newline` |
 | `Ctrl+V` | 붙여넣기. 클립보드에 **이미지만** 있으면 텍스트 대신 이미지 붙여넣기 키를 앱에 넘긴다 — Claude Code·Codex 가 클립보드를 직접 읽는다. `agentdeck-paste` |
 | 우클릭 | 선택이 있으면 복사, 없으면 붙여넣기. 길게(기본 250ms) 누르면 컨텍스트 메뉴 |
+| `Ctrl+Shift+L` | 사이드바 목록에 포커스를 준다 / 같은 키로 터미널로 돌아온다. `agentdeck-focus-list` |
+| `Ctrl+W` | 지금 탭을 닫는다 — 터미널에서 누르면 **활성 탭**, 목록이 키보드를 가졌으면 **포커스 줄의 탭**. `keyboardNav` + `keyboardCloseTab` 이 켜져 있을 때만이고, 끄면 터미널의 앞 단어 지우기(`0x17`)로 그대로 흐른다 |
 | (미배정) | `agentdeck-toggle` — 사이드바/4:3 즉시 on-off |
 | (미배정) | `agentdeck-repair` — 화면 복구 |
+| (미배정) | `agentdeck-view` — 미리보기 패널 여닫기 (사이드바 `▤` 와 같다) |
+| (미배정) | `agentdeck-view-mode` — 패널의 `파일` / `변경` 모드 전환 |
 
 키 배정은 Tabby 설정 → 단축키의 `agentdeck-*` 항목에서 바꾼다.
-`Ctrl+V` 는 플러그인이 기동할 때 `agentdeck-paste` 에 넣고 순정 `hotkeys.paste` 에서는 뺀다(둘 다 있으면 두 번 붙는다).
-터미널 앱에 리터럴 `Ctrl+V`(0x16)를 보내야 하면 `claimCtrlV: false`.
+`Ctrl+V` 는 **핫키가 아니라 캡처 단계에서 한 번만** 처리한다. 그래서 기동할 때 순정 `hotkeys.paste` 와
+`agentdeck-paste` **양쪽에서** `Ctrl-V` 를 뺀다 — 핫키에 남겨 두면 Tabby 가 같은 키를 두 경로로 밀어 넣어
+한 번 눌러 두 번 붙는 일이 있었다(`docs/DEVELOPMENT.md` 에 원인).
+
+터미널 앱에 리터럴 `Ctrl+V`(0x16, quoted-insert)를 보내야 하면 `claimCtrlV: false`.
+그러면 우리도 잡지 않고 핫키에도 없으므로 xterm 이 0x16 을 그대로 PTY 로 흘린다 —
+**대신 그 상태에서는 `Ctrl+V` 붙여넣기 자체가 안 된다**(그게 이 설정의 목적이다).
+붙여넣기는 `Ctrl+Shift+V`·`Shift+Insert`(Tabby 순정) 또는 우클릭으로 한다.
+
+### 키보드로 사이드바 다루기
+
+`Ctrl+Shift+L` 로 목록에 들어간다. 마우스 없이 탭을 훑어보려고 만든 것이고, 규칙은 이렇다.
+
+| 키 | 하는 일 |
+|---|---|
+| `↑` `↓` | 줄 사이 이동. **활성 탭은 바뀌지 않는다** |
+| `Home` `End` | 첫 줄 / 마지막 줄 |
+| `Enter` | 탭 줄이면 그 탭으로 전환하고 키를 터미널에 돌려준다. 그룹 헤더면 접기/펴기 |
+| `Esc` | 검색어·필터가 걸려 있으면 **먼저 그것을 지운다**. 지울 게 없을 때 터미널로 나간다 |
+| `Tab` `Shift+Tab` | 검색창으로 |
+| `Ctrl+W` | 포커스 줄의 탭을 닫는다 (그룹 헤더에서는 아무 일도 하지 않는다). 목록 밖 — 터미널에서 누르면 활성 탭이다 |
+
+**포커스와 선택을 가른 이유** — 줄을 지날 때마다 탭이 바뀌면 그 탭의 출력이 화면을 덮고
+터미널 폭이 매번 다시 적용되어 화면이 튄다. 그러면 "어느 탭이었나" 를 훑어볼 수가 없다.
+그래서 `↑↓` 는 테두리(키보드 포커스)만 옮기고, 탭을 실제로 여는 것은 `Enter` 하나다.
+
+검색창과 목록은 `↓`(검색창 → 결과 첫 줄)와 `↑`(첫 줄 → 검색창)로 오간다.
+검색창의 `↑` 는 가로채지 않는다 — 한 줄 입력에서 `↑` 는 커서를 맨 앞으로 보내는
+편집 동작이고, 치던 검색어를 고칠 때 실제로 쓴다.
+
+포커스가 사이드바에 없는 동안에는 **키를 한 개도 가로채지 않는다**(리스너가 목록
+엘리먼트에 걸려 있어서 이벤트가 아예 오지 않는다). 그래도 끄고 싶으면 `keyboardNav: false`.
+
+`Ctrl+W` 만 예외다 — 그건 터미널에서도 받아야 하므로 **document 캡처 단계**에서 잡는다.
+대신 **닫을 탭이 정해졌을 때만** 키를 먹는다: 그룹 헤더에 포커스가 있거나 설정 화면 입력창이면
+그대로 흘린다. 핫키 테이블에 넣지 않은 이유도 그것이다 — Tabby 핫키는 등록만으로 키를 먹어서
+설정을 꺼도 터미널의 `Ctrl+W`(앞 단어 지우기)가 죽는다. 그 키를 그대로 쓰려면
+`keyboardCloseTab: false`(설정 창의 `Ctrl+W 로 탭 닫기`)로 끄면 되고 목록 조작은 남는다.
+닫기는 사이드바 `✕` 와 같은 경로라 돌아가는 프로세스가 있으면 Tabby 가 평소처럼 한 번 물어본다.
+
+### 한글 입력 — 조합 중인 음절이 커서를 따라가지 않게
+
+한글을 치다가 `Home` · `End` · `Shift+Enter` 를 누르면 **조합 중인 마지막 음절이 옮겨간 자리로 따라가는**
+문제가 있었다. 방향키만 멀쩡한데 그 차이가 원인이다 — xterm 은 자기 키 경로로 들어온 키에 대해서는
+조합을 **먼저 확정**하고 키를 보내지만, 그 경로를 거치지 않고 pty 에 바이트를 직접 쓰면
+(터미널 핫키·플러그인의 줄바꿈 전송) 확정이 `setTimeout` 으로 밀려 **바이트가 먼저, 음절이 나중**에 나간다.
+
+그래서 pty 에 쓰는 지점을 한 곳으로 모아, 쓰기 직전에 조합 상태를 보고
+
+- 조합 중이면 **조합이 끝나기를 기다렸다가** 쓴다
+- 확정 전송이 이미 예약돼 있으면 우리가 한 틱 물러난다
+- 상태를 못 읽으면 그냥 쓴다 (이 보정이 정상 입력을 막는 일은 없어야 한다)
+
+로 갈라 준다. 조합이 끝나지 않으면 0.4초 뒤에는 확정시키고 쓴다 — 입력이 안 나가는 것이 최악이다.
+
+> **왜 기다리나 (0.6.3).** 예전에는 조합 중이면 우리가 확정을 재촉하고 바로 썼다. 그런데 우리가
+> 확정시켜도 IME 는 자기 일정대로 확정을 한 번 더 알리고, 그때 음절이 **또** 나간다 — 그 두 번째가
+> 개행 뒤에 붙어 **문자가 새 줄로 내려갔다.** 지금은 IME 의 순서를 건드리지 않으므로 음절이 한 번만,
+> 개행보다 먼저 나간다.
+
+끄려면 `imeOrderGuard: false`.
 
 ### 화면 복구 (`↻`)
 
@@ -123,7 +333,7 @@ statusline 이 사라지거나 입력창 구분선이 화면 중간에서 끊기
 ## 설정
 
 **설정 창(설정 → AgentDeck)** 에는 실제로 바꿀 일이 있는 것만 있다 — 레이아웃 on/off, 마우스로 바꾼 배치 초기화,
-기동 시 탭 복원 끄기, Claude Code 훅 설치/제거, 작업 루트 프로필. 나머지는 Tabby 설정 파일(`%APPDATA%\tabby\config.yaml`)의
+기동 시 탭 복원 끄기, 미리보기 패널(열기 · 경로 자동 수집 · 새 파일 따라가기), Claude Code 훅 설치/제거, 작업 루트 프로필. 나머지는 Tabby 설정 파일(`%APPDATA%\tabby\config.yaml`)의
 `agentDeck` 아래에서 조절한다.
 
 | 키 | 기본값 | 설명 |
@@ -134,18 +344,40 @@ statusline 이 사라지거나 입력창 구분선이 화면 중간에서 끊기
 | `sidebarWidth` | `0` | 좌/우 도킹 시 폭(px). 0 = 화면비로 자동 계산 |
 | `sidebarHeight` | `200` | 상/하 도킹 시 높이(px) |
 | `sidebarMin` / `sidebarMax` | `200` / `560` | 자동 계산 폭의 범위(px). 넓은 모니터에서 정확히 4:3 을 원하면 `sidebarMax` 를 `창 너비 − 창 높이 × 4/3` 으로 |
+| `sortByStatus` | `false` | 급한 순서(승인대기 → 오류 → 한도 → 진행중 → 완료 → 대기)로 정렬한다. 켜면 **드래그 재정렬은 막힌다** — 옮겨도 다음 렌더에 제자리로 돌아가기 때문 |
+| `groupByProject` | `true` | 탭을 작업 폴더별 그룹으로 묶는다. 그룹이 **하나뿐이면 헤더도 그리지 않고 순서도 바꾸지 않는다** |
+| `groupRoot` | `''` | 프로젝트 경계 기준 경로. 그 아래 첫 폴더를 한 그룹으로 접는다. 비우면 `rootProfileCwd` 를 쓴다 |
+| `collapsedGroups` | `[]` | 접어 둔 그룹 키. 헤더를 누르면 여기 쌓인다. 설정 창의 `모두 펼치기` 로 비운다 |
+| `viewerOpen` | `false` | 미리보기 패널이 열려 있나. `▤` / `agentdeck-view` 로 토글하거나 **새 파일을 주워 저절로 열리면** 여기 남아 다음 기동에 복원된다. 열림을 사람이 켜 두는 값이 아니다 |
+| `viewerDock` | `right` | 패널이 붙는 방향 `left` / `right`. 사이드바와 같은 쪽이면 사이드바가 창 가장자리(바깥) |
+| `viewerWidth` | `420` | 패널 폭(px). 경계선 드래그로 바뀐다. 좁은 창에서는 `창폭 − 320 − 140` 까지만 |
+| `searchBox` | `true` | 사이드바에 검색 줄을 보인다. 끄면 걸려 있던 필터도 함께 지운다(감춰진 필터는 만들지 않는다) |
+| `keyboardNav` | `true` | `Ctrl+Shift+L` 로 목록에 들어가 `↑↓`·Enter·Esc 로 다룬다. 포커스가 사이드바에 없으면 아무 키도 가로채지 않으므로 켜 둬서 잃는 것이 없다 |
+| `keyboardCloseTab` | `true` | `Ctrl+W` 로 탭을 닫는다 — 터미널에서는 활성 탭, 목록이 키보드를 가졌으면 포커스 줄의 탭. `keyboardNav` 를 끄면 이 값과 무관하게 꺼진다. 끄면 `Ctrl+W` 가 터미널로 그대로 간다(셸의 앞 단어 지우기) |
+| `keyboardNavWrap` | `false` | 목록 끝에서 `↑↓` 가 반대쪽으로 감긴다. 끄면 끝에서 멈춘다 — "맨 아래에 왔다" 가 보이고 목록이 통째로 튀지 않는다. 끝↔끝은 Home/End 로 |
+| `viewerScrape` | `true` | 화면에 찍힌 파일 경로를 주워 최근 목록에 쌓는다. 끄면 끌어다 놓기·경로 입력만 |
+| `viewerDropOpen` | `ask` | 터미널 위에 파일을 끌어다 놓았을 때 — `ask` 물어본다 / `always` 패널에 띄운다 / `paste` 경로를 붙여넣는다 / `never` 개입하지 않는다(순정) |
+| `viewerPreload` | `true` | 에이전트가 만진 파일을 **닫혀 있는 동안에도** 패널에 얹어 둔다(최근 칩 + 다음에 열 때 띄울 파일). 끄면 아무것도 자동으로 하지 않는다. 설정 창의 `문서 패널에 읽어두기` |
+| `viewerAutoOpen` | `false` | 새 파일을 주우면 **닫힌 패널을 스스로 연다.** 기본 꺼짐 — 여닫기는 사람 몫이고, 내용은 위 `viewerPreload` 가 채워 둔다. 설정 창의 `패널 자동으로 열기` |
+| `viewerFollowMode` | `''` | (옛 값) 0.18.0 부터 위 토글 두 개로 갈랐다. `open`/`show`/`manual` 이 적혀 있으면 기동 때 한 번 두 토글로 옮기고 비운다 |
+| `viewerFollow` | `true` | (더 옛 값) 0.17.0 에 `viewerFollowMode` 로 옮겼다. `false` 였으면 마이그레이션이 `viewerPreload: false` 로 읽고 기본값으로 되돌린다 |
+| `viewerRecentMax` | `12` | 최근 목록에 남겨 두는 파일 수 |
+| `imeOrderGuard` | `true` | pty 에 바이트를 쓰기 전에 조합 중인 한글 음절을 먼저 확정한다 (아래 "한글 입력") |
+| `releaseHomeEnd` | `true` | Home / End 를 Tabby 핫키에서 걷어내 xterm 순정 경로로 돌려준다 |
 | `idleAfterMs` | `2500` | 이 시간 동안 출력이 없으면 `대기` 로 |
 | `autoDetect` | `true` | 출력·제목 패턴으로 상태 추론 |
 | `showElapsed` | `true` | 경과 시간 표시 |
 | `sortByStatus` | `false` | 사이드바 탭을 상태 우선순위(승인대기 → 오류 → 한도 도달 → 진행중 → 완료 → 대기)로 정렬한다. 같은 상태끼리는 탭 순서 유지. 끄면 순정 탭바와 같은 순서 |
+| `dragAutoScroll` | `true` | 줄을 끌 때 목록 끝에서 저절로 스크롤된다. 끄면 손을 뗀 뒤 스크롤하고 다시 끌어야 하지만, 그 대신 **맨 끝 줄 뒤에 놓는 조작이 미끄러지지 않는다** |
 | `keepRenderingWhenHidden` | `true` | 창이 가려져 있어도 사이드바를 갱신한다. 끄면 상태 변화가 최대 1분까지 늦게 보일 수 있다 |
+| `subagentCount` | `true` | 사이드바 줄에 도는 서브에이전트 개수를 보인다. 0 개면 아무것도 그리지 않으므로 켜 둬서 잃는 것이 없다. 끄면 대화 기록을 **읽지도 않는다** |
 | `enterAsLabel` | `true` | Enter 로 프롬프트를 보낼 때 입력창 원문을 작업 라벨로 삼는다 |
 | `labelAsTitle` | `true` | 사이드바 제목 줄에 탭 제목 대신 작업 라벨을 쓴다. Tabby 의 탭 제목 자체는 건드리지 않는다 |
 | `noTabRecovery` | `false` | 기동 시 지난 탭을 복원하지 않는다 — Tabby `recoverTabs` 를 false 로 강제. 복원되는 건 셸뿐이고 안의 Claude 세션은 죽어 있어 의미가 없다 (설정 창에서 켠다) |
 | `notifyChannel` | `true` | 훅이 보낸 상태를 받는 통로(로컬 TCP + 상태 파일). 훅을 설치하면 자동으로 켜진다 |
 | `notifyPort` | `47500` | 그 TCP 포트(127.0.0.1 전용). 물려 있으면 임의 포트로 물러나고 실제 번호는 `%LOCALAPPDATA%\tabby-agentdeck\port` 에 적힌다 |
 | `hookPromptDismissed` | `false` | 기동 시 뜨는 훅 설치 안내를 다시 띄우지 않는다 |
-| `claimCtrlV` | `true` | 기동 시 `agentdeck-paste` 에 `Ctrl-V` 를 넣고 순정 `hotkeys.paste` 에서는 뺀다 |
+| `claimCtrlV` | `true` | `Ctrl+V` 를 캡처 단계에서 직접 처리한다. 기동 시 `hotkeys.paste`·`agentdeck-paste` **양쪽에서** `Ctrl-V` 를 뺀다(두 번 붙는 것 방지). `false` 면 리터럴 0x16 이 앱으로 가고 **붙여넣기는 안 된다** |
 | `pasteImageWithCtrlV` | `true` | 클립보드에 이미지만 있으면 텍스트 붙여넣기 대신 이미지 붙여넣기 키를 보낸다 |
 | `imagePasteKey` | `alt-v` | 그때 보낼 키. `ctrl-v`(0x16) 는 Claude Code·Codex 둘 다, `alt-v`(ESC v) 는 Claude Code 전용 |
 | `claimRightClick` | `true` | 우클릭을 플러그인이 처리한다 (Tabby 의 `terminal.rightClick` 은 `off` 로) |
@@ -153,7 +385,7 @@ statusline 이 사라지거나 입력창 구분선이 화면 중간에서 끊기
 | `terminalOpacity` | `75` | 터미널 배경 불투명도(%). 100 미만이면 `tabby-background` 의 배경 이미지가 비친다. 100 = 순정 |
 | `sidebarOpacity` | `75` | 사이드바 / 창 여백 불투명도(%) |
 | `clipBackgroundToTerminal` | `true` | `tabby-background` 이미지를 터미널 영역으로 잘라 사이드바 밑까지 비치지 않게 한다 |
-| `screenWatch` | `true` | 2초마다 화면이 깨졌는지 판정해 `~/.agentdeck-screen.log` 에 기록만 한다 (복구는 하지 않음) |
+| `screenWatch` | `true` | 2초마다 화면이 깨졌는지 판정해 `~/.agentdeck-screen.log` 에 기록만 한다 (복구는 하지 않음). 4MB 를 넘으면 `.1` 로 밀린다 |
 | `autoRepairScreen` | `false` | 깨졌다고 판정되면 조용히 화면 복구까지 한다 |
 | `autoRepairMinStreak` | `2` | 깨짐이 이만큼 연속으로 보여야 복구한다 (그리는 도중의 중간 프레임 오탐 방지) |
 | `autoRepairCooldownMs` | `10000` | 자동 복구 후 이만큼은 다시 하지 않는다 |
@@ -170,6 +402,27 @@ statusline 이 사라지거나 입력창 구분선이 화면 중간에서 끊기
 | `alertBadge` | `true` | 작업표시줄 아이콘 위에 `승인대기`+`오류`+`한도 도달` 탭 개수를 뱃지(원+숫자)로 얹는다. 0 이면 지운다 |
 | `alertToast` | `false` | 그때 OS 토스트도 띄운다. 누르면 창을 앞으로 가져오고 그 탭을 고른다 |
 
+## 문제 신고
+
+버그를 만났으면 **설정 → AgentDeck → 문제 신고 → `모으기`** 를 누른다.
+진단 로그를 zip 하나로 묶고 그 파일이 있는 폴더를 열어 주므로, 그 zip 을 이슈에 붙이면 된다.
+
+담기는 것
+
+| 파일 | 내용 |
+|---|---|
+| `report.txt` | 플러그인/Tabby/Electron 버전, OS, 설정 값(도킹·화면비·`useConPTY` 등), 이 세션의 최근 진단 200줄 |
+| `agentdeck-diag.log` | `~/.agentdeck-diag.log` — 세션 머리말, 배치·입력·pty 판정, 잡히지 않은 예외와 스택, 삼켜진 실패(`CATCH …`) |
+| `agentdeck-diag.log.1` | 그 직전 분량 (2MB 를 넘겨 밀려난 것) |
+| `agentdeck-screen.log` | **"화면 원문까지 넣기" 를 켤 때만.** 깨진 순간의 터미널 화면이 글자 그대로 들어간다 |
+
+알아 둘 것
+
+- 로그는 **기동해도 지워지지 않는다.** 2MB 를 넘길 때 `.1` 로 한 세대 밀리므로, 어제 겪은 문제도 대개 남아 있다.
+- 로그에는 **탭 제목과 열어 본 파일 경로**가 들어간다. 보내기 전에 열어 봐도 되고, 화면 원문은 기본으로 빠진다.
+- 설정 창을 열 수 없을 만큼 깨졌으면 devtools 콘솔에서 `__agentdeck.collectDiag()` — 같은 zip 을 만들고 경로를 돌려준다.
+  최근 진단 줄만 보려면 `__agentdeck.kickLog`.
+
 ## 알려진 문제
 
 ### Tabby 1.0.235 에서 새 탭이 열리지 않음

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

@@ -82,6 +82,6 @@ export declare class AgentDeckAlertService {
     private toast;
     /** 토스트 tag 용 탭 식별자 — 객체 자체는 문자열이 안 되니 인덱스로 대신한다 */
     private tabKey;
-    /** deck.service 와 같은 파일(`~/.agentdeck-diag.log`)에 남긴다. 실패해도 동작에는 영향 없다 */
+    /** deck.service 와 같은 파일(`~/.agentdeck-diag.log`)에 남긴다 — 회전·시각 표기는 `diag.ts` 가 한다 */
     private diag;
 }