deel-local-cli 1.6.0 → 1.6.1

package/README.en.md

@@ -100,7 +100,7 @@ This page is the **summary**. Each section links to the detail behind it.
 | [Speed and spend](docs/en/tuning.md) | Per-stage effort · the prefix cache · context length |
 | [Safety and corporate review](docs/en/safety.md) | Undo · working scope · audit log · the review package |
 | [Configuration](docs/en/config.md) · [Development](docs/en/develop.md) | Env vars · run flags · running the tests · folder layout |
-| [Release notes](docs/en/releases.md) | [1.6.0](docs/en/releases.md#160) · [1.5.8](docs/en/releases.md#158) · [1.5.7](docs/en/releases.md#157) · [1.5.6](docs/en/releases.md#156) · [1.5.5](docs/en/releases.md#155) · [1.5.4](docs/en/releases.md#154) · [1.5.3](docs/en/releases.md#153) · [1.5.2](docs/en/releases.md#152) · [1.5.1](docs/en/releases.md#151) · [1.5.0](docs/en/releases.md#150) · [1.4.3](docs/en/releases.md#143) · [1.4.2](docs/en/releases.md#142) · [1.4.1](docs/en/releases.md#141) · [1.4.0](docs/en/releases.md#140) · [1.3.0](docs/en/releases.md#130) · [1.2.0](docs/en/releases.md#120) |
+| [Release notes](docs/en/releases.md) | [1.6.1](docs/en/releases.md#161) · [1.6.0](docs/en/releases.md#160) · [1.5.8](docs/en/releases.md#158) · [1.5.7](docs/en/releases.md#157) · [1.5.6](docs/en/releases.md#156) · [1.5.5](docs/en/releases.md#155) · [1.5.4](docs/en/releases.md#154) · [1.5.3](docs/en/releases.md#153) · [1.5.2](docs/en/releases.md#152) · [1.5.1](docs/en/releases.md#151) · [1.5.0](docs/en/releases.md#150) · [1.4.3](docs/en/releases.md#143) · [1.4.2](docs/en/releases.md#142) · [1.4.1](docs/en/releases.md#141) · [1.4.0](docs/en/releases.md#140) · [1.3.0](docs/en/releases.md#130) · [1.2.0](docs/en/releases.md#120) |
 
 ---
 
@@ -536,7 +536,12 @@ their cost; here is why.
 **A file saved as CP949 is written back as CP949.** The encoding is never changed.
 Excel (`.xlsx`) is read as CSV — read-only.
 
-> **More** — Encoding · Excel
+Old formats (`.ppt`, `.doc`, `.xls`, `.rtf`) are read by **borrowing the LibreOffice already
+on this machine** — the same terms on which deel borrows `rg`, and nothing is ever installed.
+With no converter it **says so definitively and stops**: what is missing, what you can do about
+it, and not to open the file again. Turn it off with `DEEL_CONVERT=off`.
+
+> **More** — Encoding · Excel · borrowing a converter
 >
 > **[Korean documents and Excel read →](docs/en/documents.md#korean-text-and-excel)**
 
@@ -993,6 +998,7 @@ so one run tells you everything.
 
 | Version | What changed |
 |---|---|
+| **[1.6.1](docs/en/releases.md#161)** | The places that made a turn spin in circles — the fence blocking `/dev/null` · old documents it could not read · images vanishing from files |
 | **[1.6.0](docs/en/releases.md#160)** | The things that did not work on a corporate network — proxy · 429 · Windows shell · 50k-file repos · PDF · clipboard paste · editor resume |
 | **[1.5.8](docs/en/releases.md#158)** | A 5MB document showed 8 lines out of 919 · a regex read as a path blocked the command |
 | **[1.5.7](docs/en/releases.md#157)** | Korean folders on macOS made your own files "out of scope" · paste · ESC |

package/README.md

@@ -101,7 +101,7 @@
 | [속도와 씀씀이](docs/ko/tuning.md) | 단계별 추론 강도 · 프리픽스 캐시 · 컨텍스트 길이 |
 | [안전망과 사내 반입](docs/ko/safety.md) | 되돌리기 · 작업 범위 · 감사기록 · 심사 서류 |
 | [설정](docs/ko/config.md) · [개발](docs/ko/develop.md) | 환경변수 · 실행 옵션 · 검사 돌리기 · 폴더 구조 |
-| [릴리스 노트](docs/ko/releases.md) | [1.6.0](docs/ko/releases.md#160) · [1.5.8](docs/ko/releases.md#158) · [1.5.7](docs/ko/releases.md#157) · [1.5.6](docs/ko/releases.md#156) · [1.5.5](docs/ko/releases.md#155) · [1.5.4](docs/ko/releases.md#154) · [1.5.3](docs/ko/releases.md#153) · [1.5.2](docs/ko/releases.md#152) · [1.5.1](docs/ko/releases.md#151) · [1.5.0](docs/ko/releases.md#150) · [1.4.3](docs/ko/releases.md#143) · [1.4.2](docs/ko/releases.md#142) · [1.4.1](docs/ko/releases.md#141) · [1.4.0](docs/ko/releases.md#140) · [1.3.0](docs/ko/releases.md#130) · [1.2.0](docs/ko/releases.md#120) |
+| [릴리스 노트](docs/ko/releases.md) | [1.6.1](docs/ko/releases.md#161) · [1.6.0](docs/ko/releases.md#160) · [1.5.8](docs/ko/releases.md#158) · [1.5.7](docs/ko/releases.md#157) · [1.5.6](docs/ko/releases.md#156) · [1.5.5](docs/ko/releases.md#155) · [1.5.4](docs/ko/releases.md#154) · [1.5.3](docs/ko/releases.md#153) · [1.5.2](docs/ko/releases.md#152) · [1.5.1](docs/ko/releases.md#151) · [1.5.0](docs/ko/releases.md#150) · [1.4.3](docs/ko/releases.md#143) · [1.4.2](docs/ko/releases.md#142) · [1.4.1](docs/ko/releases.md#141) · [1.4.0](docs/ko/releases.md#140) · [1.3.0](docs/ko/releases.md#130) · [1.2.0](docs/ko/releases.md#120) |
 
 ---
 
@@ -513,7 +513,12 @@ PDF 는 **못 읽은 쪽을 못 읽었다고 말합니다.** 스캔본·암호·
 빈 글로 넘기지 않고 그 자리에 까닭을 적습니다 — 빈 글은 「그런 내용이 없다」로
 읽히기 때문입니다.
 
-> **자세히** — 인코딩 · 엑셀 · hwpx/docx/pptx · PDF
+옛 형식(`.ppt`·`.doc`·`.xls`·`.rtf`)은 **이 PC 에 깔린 LibreOffice 를 빌려서**
+읽습니다 — `rg` 를 빌려 쓰는 것과 같은 원칙으로, 아무것도 설치하지 않습니다.
+없으면 **없다고 못 박고 끝냅니다**(무엇이 없어서 못 하는지, 무엇을 하면 되는지,
+그리고 「다시 열지 말라」까지). 끄려면 `DEEL_CONVERT=off`.
+
+> **자세히** — 인코딩 · 엑셀 · hwpx/docx/pptx · PDF · 변환기 빌려 쓰기
 >
 > **[한글 문서와 엑셀 읽기 →](docs/ko/documents.md#한글-문서와-엑셀)**
 
@@ -984,6 +989,7 @@ zip 은 진짜 `unzip` 으로, tar 는 진짜 `tar` 가 만든 것을 읽혀 교
 
 | 판 | 무엇이 바뀌었나 |
 |---|---|
+| **[1.6.1](docs/ko/releases.md#161)** | 헛도는 턴을 만들던 자리들 — 울타리가 `/dev/null` 까지 막던 것 · 옷 문서를 못 읽던 것 · 파일에서 그림이 사라지던 것 |
 | **[1.6.0](docs/ko/releases.md#160)** | 사내망에서 안 되던 것들 — 프록시 · 429 · 윈도우 셸 · 5만 개 저장소 · PDF · 캡처 붙여넣기 · 에디터 이어하기 |
 | **[1.5.8](docs/ko/releases.md#158)** | 5MB 문서를 919줄 중 8줄만 보던 것 · 정규식을 경로로 읽어 명령을 막던 것 |
 | **[1.5.7](docs/ko/releases.md#157)** | 맥 한글 폴더에서 제 파일이 「범위 밖」이던 것 · 붙여넣기 · ESC |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deel-local-cli",
-  "version": "1.6.0",
+  "version": "1.6.1",
   "description": "로컬 모델·사내 게이트웨이 전용 코딩 에이전트 CLI — 외부 의존성 0개 / Zero-dependency coding agent CLI for local LLMs and private gateways",
   "type": "module",
   "license": "MIT",
@@ -51,7 +51,7 @@
     "verify": "node test/no-bundle.test.js && node test/network.test.js && node test/web.test.js",
     "bench": "node test/edit-bench.js",
     "demo": "node test/demo.js",
-    "check": "node --check bin/deel.js && node --check src/repl.js && node --check src/oneshot.js && node --check src/commands.js && node --check src/agent/loop.js && node --check src/agent/session.js && node --check src/agent/effort.js && node --check src/agent/modes.js && node --check src/agent/route.js && node --check src/agent/models.js && node --check src/agent/grade.js && node --check src/agent/mention.js && node --check src/agent/project.js && node --check src/tools/encoding.js && node --check src/tools/excel-com.js && node --check src/tools/excel.js && node --check src/tools/xlsx.js && node --check src/tools/docs.js && node --check src/tools/pdf.js && node --check src/tools/clipboard.js && node --check src/agent/compact.js && node --check src/agent/store.js && node --check src/agent/sessionui.js && node --check src/backend/adapter.js && node --check src/backend/ctxsize.js && node --check src/backend/probe.js && node --check src/backend/detect.js && node --check src/backend/http.js && node --check src/backend/retry.js && node --check src/backend/proxy.js && node --check src/backend/azure.js && node --check src/backend/vision.js && node --check src/backend/quota.js && node --check src/backend/scan.js && node --check src/backend/scanui.js && node --check src/tools/index.js && node --check src/tools/desc.en.js && node --check src/tools/lsp.js && node --check src/lsp/rpc.js && node --check src/lsp/servers.js && node --check src/lsp/client.js && node --check src/lsp/diag.js && node --check src/tools/fsutil.js && node --check src/tools/ignore.js && node --check src/tools/fastgrep.js && node --check src/tools/edit-match.js && node --check src/tools/webfetch.js && node --check src/tools/todo.js && node --check src/tools/jobs.js && node --check src/tools/shell.js && node --check src/skills/discover.js && node --check src/plugins/manage.js && node --check src/pack/zip.js && node --check src/pack/tar.js && node --check src/pack/selfpack.js && node --check src/safety/guard.js && node --check src/safety/undo.js && node --check src/safety/audit.js && node --check src/safety/keystore.js && node --check src/safety/policy.js && node --check src/safety/network.js && node --check src/setup.js && node --check src/report.js && node --check src/config.js && node --check src/completion.js && node --check src/ui/diff.js && node --check src/ui/ansi.js && node --check src/ui/status.js && node --check src/ui/level.js && node --check src/ui/prompt.js && node --check src/ui/spinner.js && node --check src/ui/motion.js && node --check src/ui/office.js && node --check src/ui/notify.js && node --check src/ui/intro.js && node --check src/ui/banner.js && node --check src/ui/export.js && node --check src/i18n/index.js && node --check src/i18n/ko.js && node --check src/i18n/en.js && node --check src/i18n/ja.js && node --check src/i18n/zh.js && node --check src/preview/serve.js && node --check src/ui/working.js && node --check src/ui/inputbox.js && node --check src/ui/wrap.js && node --check src/ui/md.js && node --check src/agent/threads.js && node --check src/agent/evolve.js && node --check src/agent/pins.js && node --check src/agent/card.js && node --check src/agent/preset.js && node --check src/agent/evidence.js && node --check src/agent/commit.js && node --check src/agent/review.js && node --check src/acp/jsonrpc.js && node --check src/acp/map.js && node --check src/acp/serve.js && node --check src/pack/sbom.js && node --check src/safety/secrets.js && echo OK",
+    "check": "node --check bin/deel.js && node --check src/repl.js && node --check src/oneshot.js && node --check src/commands.js && node --check src/agent/loop.js && node --check src/agent/session.js && node --check src/agent/effort.js && node --check src/agent/modes.js && node --check src/agent/route.js && node --check src/agent/models.js && node --check src/agent/grade.js && node --check src/agent/mention.js && node --check src/agent/project.js && node --check src/tools/encoding.js && node --check src/tools/excel-com.js && node --check src/tools/excel.js && node --check src/tools/xlsx.js && node --check src/tools/docs.js && node --check src/tools/convert.js && node --check src/tools/pdf.js && node --check src/tools/clipboard.js && node --check src/agent/compact.js && node --check src/agent/store.js && node --check src/agent/sessionui.js && node --check src/backend/adapter.js && node --check src/backend/ctxsize.js && node --check src/backend/probe.js && node --check src/backend/detect.js && node --check src/backend/http.js && node --check src/backend/retry.js && node --check src/backend/proxy.js && node --check src/backend/azure.js && node --check src/backend/vision.js && node --check src/backend/quota.js && node --check src/backend/scan.js && node --check src/backend/scanui.js && node --check src/tools/index.js && node --check src/tools/desc.en.js && node --check src/tools/lsp.js && node --check src/lsp/rpc.js && node --check src/lsp/servers.js && node --check src/lsp/client.js && node --check src/lsp/diag.js && node --check src/tools/fsutil.js && node --check src/tools/ignore.js && node --check src/tools/fastgrep.js && node --check src/tools/edit-match.js && node --check src/tools/webfetch.js && node --check src/tools/todo.js && node --check src/tools/jobs.js && node --check src/tools/shell.js && node --check src/skills/discover.js && node --check src/plugins/manage.js && node --check src/pack/zip.js && node --check src/pack/tar.js && node --check src/pack/selfpack.js && node --check src/safety/guard.js && node --check src/safety/undo.js && node --check src/safety/audit.js && node --check src/safety/keystore.js && node --check src/safety/policy.js && node --check src/safety/network.js && node --check src/setup.js && node --check src/report.js && node --check src/config.js && node --check src/completion.js && node --check src/ui/diff.js && node --check src/ui/ansi.js && node --check src/ui/status.js && node --check src/ui/level.js && node --check src/ui/prompt.js && node --check src/ui/spinner.js && node --check src/ui/motion.js && node --check src/ui/office.js && node --check src/ui/notify.js && node --check src/ui/intro.js && node --check src/ui/banner.js && node --check src/ui/export.js && node --check src/i18n/index.js && node --check src/i18n/ko.js && node --check src/i18n/en.js && node --check src/i18n/ja.js && node --check src/i18n/zh.js && node --check src/preview/serve.js && node --check src/ui/working.js && node --check src/ui/inputbox.js && node --check src/ui/wrap.js && node --check src/ui/md.js && node --check src/agent/threads.js && node --check src/agent/evolve.js && node --check src/agent/pins.js && node --check src/agent/card.js && node --check src/agent/preset.js && node --check src/agent/evidence.js && node --check src/agent/commit.js && node --check src/agent/review.js && node --check src/acp/jsonrpc.js && node --check src/acp/map.js && node --check src/acp/serve.js && node --check src/pack/sbom.js && node --check src/safety/secrets.js && echo OK",
     "coverage": "node test/coverage.mjs",
     "prepublishOnly": "npm run check && npm test"
   },

package/src/acp/serve.js

@@ -402,6 +402,12 @@ export async function acp(opts = {}) {
             말하기(`\n\n_(${ev.why} — 다시 답을 받습니다)_\n\n`);
             break;
 
+          // 답이 천장에서 잘렸고 더 못 올린다. 조용히 끝내면 에디터에는 중간에서
+          // 끊긴 답만 남아서, 사람은 모델이 대충 답한 줄 안다.
+          case 'capped':
+            말하기(`\n\n_(답이 ${ev.cap.toLocaleString()} 토큰에서 잘렸습니다 — 터미널에서 \`/out 32k\` 로 상한을 올리거나, 파일은 나눠 쓰게 하세요)_\n\n`);
+            break;
+
           // 서버가 잠깐 막아 기다리는 중. 아직 흘러간 글이 없으니 답을 새로 시작하지는 않는다.
           case 'backoff':
             말하기(`\n\n_(${옮긴말('loop.backoff', 알림채움(ev))})_\n\n`);

package/src/agent/loop.js

@@ -320,11 +320,30 @@ export async function* run(session, ctx, userText, { signal = null, 깊이 = 0,
    * 여기까지 오지 않는다 — 막히는 것은 글로 되묻고 턴을 닫는 쪽뿐이다.
    */
   let 민적 = false;
+  /*
+   * 인사에는 안 민다.
+   *
+   * 「안녕」 한 마디에 모델이 "안녕하세요! 무엇을 도와드릴까요?" 라고 답하면
+   * 그건 **맞는 답**이다. 그런데 그 말이 되묻는말에 걸려서 되밀렸다 —
+   *
+   *   ❯ 안녕
+   *     ▌ 안녕하세요! 무엇을 도와드릴까요?
+   *     ↺ 읽기만 하고 끝내려고 해서 한 번 되밀었습니다
+   *     ▌ 안녕하세요! 반갑습니다.
+   *     ── 6.8초
+   *
+   * 인사 한 마디에 모델을 두 번 부른다. 로컬 모델에서 그 왕복이 6.8초다.
+   * 되밀기는 「시킨 일을 안 하고 되돌려준」 자리를 잡으라고 만든 것인데,
+   * 인사는 시킨 일이 없다. 시킨 것이 없으면 안 한 것도 없다.
+   */
+  const 인사인가 = /^(안녕[가-힣]*|반(가|갑)[가-힣]*|하이|ㅎㅇ+|헬로[우가-힣]*|고마[가-힣]*|감사[가-힣]*|수고[가-힣]*|hi|hello|hey|yo|thanks?|thank you|테스트|test|ok(ay)?|네|응)[\s!.~?ㅎㅋ,]*$/i
+    .test(String(userText ?? '').trim());
   const 되묻는말 = /무엇을\s*도와|무엇을\s*해\s*드릴|원하시는\s*(작업|것)|어떤\s*(작업|것)\s*(을|부터)|말씀해\s*주세요|알려\s*주세요|지시해\s*주세요|어떻게\s*할까요|해\s*드릴까요|진행할까요|what would you like|how can i (help|assist)|let me know (what|which|how)|shall i\b|would you like me to/i;
 
   /** 이번 답을 되밀까. 밀 이유를 돌려주고, 아니면 null. */
   const 밀어줄까 = (글) => {
     if (민적 || 깊이) return null;
+    if (인사인가) return null;                            // 시킨 것이 없으면 안 한 것도 없다
     if (손댄파일.size) return null;                       // 뭐라도 바꿨으면 일은 한 것이다
     if (!모드.tools.includes('Write')) return null;         // 안 바꾸는 모드는 그게 맞다
     const 말 = String(글 ?? '').trim();
@@ -479,15 +498,38 @@ export async function* run(session, ctx, userText, { signal = null, 깊이 = 0,
        */
       const full = Math.max(cap, fullCap(room));
       const 낮춘생각 = level === 'off' || level === 'low' ? level : shiftLevel(level, -1);
+      let 마지막상한 = cap;
       if (wasCut(msg) && (full > cap || 낮춘생각 !== level)) {
         yield {
           type: 'retry',
           why: full > cap ? '대답이 상한에서 잘렸습니다' : '대답이 잘렸습니다 — 생각을 줄여 자리를 냅니다',
           from: cap, to: full, think: 낮춘생각,
         };
+        마지막상한 = full;
         yield* askModel(full, 낮춘생각);
       }
 
+      /*
+       * 우리가 할 수 있는 것을 다 했는데도 잘렸다 — 여기서 입을 다물면 안 된다.
+       *
+       * 상한도 올려 봤고 생각도 줄여 봤는데 여전히 잘렸으면, 남은 일은 사람
+       * 몫이다. 그런데 여태 그냥 조용히 끝냈다. 화면에는 중간에서 끊긴 답만
+       * 남는다 — 사람 눈에는 모델이 게을러서 대충 답한 것으로 보이니 같은 것을
+       * 다시 시키고, 같은 자리에서 또 잘린다. 몇 분씩 가는 로컬 모델에서
+       * 이 왕복은 비싸다.
+       *
+       * 안 되는 것은 **까닭과 손댈 자리를 같이** 말한다 (`/out`).
+       * 다시 부른 뒤에 보는 것이 중요하다. 부르기 전에 판정하면, 상한을 올려
+       * 멀쩡히 끝난 답에까지 경고가 붙는다 — 그러면 곧 아무도 안 읽는다.
+       */
+      if (wasCut(msg)) {
+        yield {
+          type: 'capped',
+          cap: 마지막상한,
+          정한값: conn.maxTokens ?? conn.maxOut ?? null,
+        };
+      }
+
       /*
        * 빈 답을 성공으로 넘기지 않는다.
        *

package/src/agent/session.js

@@ -50,6 +50,7 @@ const BASE_RULES = `너는 deel 다. 사용자의 작업 폴더 안에서 코드
 - 같은 도구를 같은 인자로 다시 부르지 않는다. 결과는 같다. 본 것은 기억하고 다음으로 넘어간다.
 - 사용자가 볼 범위를 못 박아 말하면 그 범위를 지킨다. 안 그러면 필요한 만큼 찾아본다.
 - 명령 실행이 필요하면 Bash 를 쓴다. 되돌릴 수 없는 명령은 막히니 다른 방법을 찾는다.
+- 중간 파일이 필요하면 /tmp 말고 .deel/tmp/ 에 쓴다. 작업 폴더 밖은 막힌다.
 - 사용자에게 답할 때는 한국어로, 짧게. 코드를 통째로 붙여넣지 말고 무엇이 달라졌는지 말한다.
 
 다음에도 쓸 것은 남긴다:
@@ -130,6 +131,7 @@ Rules:
 - Do not call the same tool with the same arguments twice. The result will be the same. Remember what you saw and move on.
 - If the user names the scope to look at, stay inside it. Otherwise look as far as you need.
 - Use Bash when you need to run a command. Commands that cannot be undone are blocked, so find another way.
+- If you need a scratch file, write it under .deel/tmp/, not /tmp. Outside the working folder is blocked.
 - Answer the user in English, briefly. Do not paste whole files back — say what changed.
 
 Keep what will be needed again:

package/src/repl.js

@@ -1700,6 +1700,20 @@ export async function chatLoop(opts = {}) {
             if (session.level === '개발자' && ev.from) say(`     ${c.gray(clip(ev.from, 110))}`);
             break;
 
+          /*
+           * 답이 천장에서 잘렸고 우리가 더 해 줄 것이 없다.
+           *
+           * 조용히 넘기면 화면에는 중간에서 끊긴 답만 남는다 — 사람은 모델이
+           * 대충 답한 줄 알고 같은 것을 다시 시키고, 같은 자리에서 또 잘린다.
+           * 손댈 자리를 그 자리에서 알려 준다.
+           */
+          case 'capped':
+            clearThinking();
+            say(`  ${mark.warn} ${c.gray(`답이 ${c.white(ev.cap.toLocaleString())} 토큰에서 잘렸습니다`)}`
+              + `${ev.정한값 ? c.gray(' (직접 정하신 상한입니다)') : c.gray(' — 더 못 올리는 천장입니다')}`);
+            say(`     ${c.gray('한 번에 더 길게 받으려면')} ${c.cyan('/out 32k')}${c.gray('. 파일을 쓰는 중이었다면 Append 로 나눠 쓰게 하세요.')}`);
+            break;
+
           case 'compact_failed':
             접기멈춤();
             say(`  ${c.gray(`(접지 못했습니다: ${ev.why})`)}`);

package/src/safety/guard.js

@@ -194,6 +194,8 @@ export function checkCommand(cmd) {
 export function checkPaths(cmd, scope) {
   if (!scope) return true;
   for (const t of 경로낱말(String(cmd))) {
+    // 자료가 아닌 자리는 울타리를 안 묻는다 (봐주는자리 머리말).
+    if (봐주는자리(t)) continue;
     let abs;
     try { abs = scope.resolve(t); }
     catch (e) {
@@ -282,6 +284,65 @@ export function 코드조각인가(낱말) {
   return false;
 }
 
+/*
+ * ── 울타리 밖이지만 막을 까닭이 없는 자리 ───────────────────────────────
+ *
+ * 울타리는 **사람의 자료**를 지키려고 있다. 그런데 두 가지가 자료가 아닌데도
+ * 같이 막혀서, 모델이 할 수 있는 일을 못 하게 만들고 있었다.
+ *
+ *   ▶ Bash(soffice --convert-to txt 보고서.pptx > /dev/null 2>&1)
+ *     └ 막힘 — 작업 범위 밖입니다: /dev/null
+ *   ▶ Bash(ls -l /usr/bin/strings)
+ *     └ 막힘 — 작업 범위 밖입니다: /usr/bin/strings
+ *
+ * 앞엣것은 **아무것도 저장되지 않는 자리**다. `2>/dev/null` 은 셸 명령 절반이
+ * 달고 다니는데, 그 한 조각 때문에 명령 전체가 거절됐다. 뒤엣것은 **이 PC 에
+ * 무엇이 깔렸는지 보는 것**이다. 그걸 못 보면 모델은 우회로를 못 찾는다 —
+ * 못 읽는 문서를 만났을 때 변환기가 있는지조차 확인할 수 없다.
+ *
+ * 실제로 그래서 헛돌았다. 문서를 못 읽었고, 변환하려니 막혔고, 남은 길이
+ * 없으니 같은 문을 계속 두드렸다. 1.5.8 에서 한 번 겪은 것과 같은 모양인데
+ * 그때는 걸린 명령 하나만 풀고 같은 갈래를 안 훑었다.
+ *
+ * **넓히는 것은 이 둘뿐이다.** 남의 홈 · /etc · /var · /tmp 는 그대로 막는다.
+ * 프로그램이 든 폴더는 자료가 아니고, 거기 쓰는 것은 어차피 OS 가 막는다.
+ */
+const 버리는자리 = new Set([
+  '/dev/null', '/dev/stdout', '/dev/stderr', '/dev/tty',
+  'nul', 'nul:', '\\\\.\\nul',            // 윈도우
+]);
+
+/**
+ * 프로그램이 사는 자리. 자료가 아니라 실행파일이다.
+ *
+ * **전부 소문자로 적는다** — 견줄 때 소문자로 낮춰서 보기 때문이다.
+ * `/Applications` 처럼 대문자를 섞어 적으면 그 줄만 조용히 안 걸린다.
+ */
+const 프로그램자리 = [
+  '/bin', '/sbin', '/usr/bin', '/usr/sbin', '/usr/libexec',
+  '/usr/local/bin', '/usr/local/sbin',
+  '/opt/homebrew/bin', '/opt/homebrew/sbin', '/opt/local/bin',
+  '/snap/bin', '/applications',           // 맥은 앱 꾸러미 안에 실행파일이 있다
+  'c:/windows', 'c:/program files', 'c:/program files (x86)',
+];
+
+/**
+ * 이 경로는 울타리를 안 물어도 되는 자리인가.
+ *
+ * @returns {string|null} 봐 주는 까닭. 아니면 null
+ */
+export function 봐주는자리(경로) {
+  const p = String(경로 ?? '').replace(/\\/g, '/');
+  const 낮춤 = p.toLowerCase().replace(/\/+$/, '');
+  if (버리는자리.has(낮춤)) return '아무것도 저장되지 않는 자리';
+  // 한 칸 아래까지만 본다. `/usr/bin/strings` 는 되고 `/usr/bin/../../Users/남` 은
+  // 여기 오기 전에 resolve 로 펴져서 이 목록에 안 걸린다.
+  for (const 자리 of 프로그램자리) {
+    if (낮춤 === 자리 || 낮춤.startsWith(`${자리}/`)) return '프로그램이 있는 자리';
+  }
+  return null;
+}
+
 /** 명령줄에서 경로처럼 보이는 낱말만 골라낸다. */
 export function 경로낱말(cmd) {
   const out = [];

package/src/tools/convert.js

@@ -0,0 +1,287 @@
+// 이미 깔려 있는 변환기를 빌려 쓴다. 아무것도 설치하지 않는다.
+//
+// ── 왜 이걸 만드나 ──────────────────────────────────────────────────────
+//
+// 사내 자료는 형식이 제각각이다. 이름은 .pptx 인데 속은 옛 .ppt 이고, .doc 이고,
+// .rtf 다. deel 은 hwpx·docx·pptx·xlsx·pdf 를 직접 읽지만 그 밖은 못 읽는다.
+// 그때 여태 이렇게 끝났다 —
+//
+//   ◧ Read(보고서.pptx)
+//     └ pptx 모양이 아닙니다 — 깨졌거나 다른 형식입니다.
+//
+// 길이 없으니 모델은 같은 파일을 몇 번씩 다시 열었다. 그런데 정작 그 PC 에는
+// LibreOffice 가 깔려 있었다. 사람이 그 파일을 열어 보는 바로 그 프로그램이다.
+//
+// ── 빌려 쓰기의 규칙 ────────────────────────────────────────────────────
+//
+// 1.6.0 에서 `rg` 를 빌려 쓴 것과 **같은 원칙**이다 (tools/fastgrep.js).
+//
+//   · 아무것도 설치하지 않는다. 없으면 없다고 말하고 끝낸다.
+//   · 있는지 한 번만 본다. 매번 물으면 없는 PC 에서 그 실패가 계속 쌓인다.
+//   · 끌 수 있다 (`DEEL_CONVERT=off`). 결과가 의심될 때 견줄 자리가 있어야 한다.
+//   · 셸을 안 거친다. 파일 이름에 빈칸·따옴표·한글이 들어와도 그대로 넘긴다.
+//   · 결과는 **작업 폴더 안**(.deel/tmp/)에 떨군다. 밖에 쓰면 울타리를 우리
+//     손으로 넘는 셈이고, 남긴 것을 거둘 자리도 없어진다.
+//
+// 바뀐 글만 쓰고 원본은 한 글자도 안 건드린다. 변환은 읽기의 곁길이다.
+import { spawnSync } from 'node:child_process';
+import {
+  existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync,
+} from 'node:fs';
+import { basename, extname, join } from 'node:path';
+
+/** 변환해서 읽어 볼 만한 확장자. 여기 없는 것은 손대지 않는다. */
+const 바꿔볼확장자 = new Set([
+  '.ppt', '.doc', '.xls',      // 옛 Office (OLE 복합문서)
+  '.rtf', '.odt', '.odp', '.ods', '.wpd',
+  '.pptx', '.docx', '.xlsx',   // 겉만 그 이름이고 속이 다른 것
+  '.hwp',                       // 구형 한글 — soffice 가 읽는 판이 있다
+]);
+
+/**
+ * 우리가 **영영 직접은 못 읽는** 갈래. 바꿔볼확장자 의 부분집합이다.
+ *
+ * 둘을 가르는 이유가 있다. `.pptx` 가 안 읽히는 것은 「깨졌거나 속이 다르다」는
+ * 뜻이라 docs.js 가 이미 정체를 짚어 준다 — 그 말이 우리 말보다 낫다. 반면
+ * `.ppt` 는 정체가 분명하고 우리에게 길이 없다. 그때만 「없다」고 못 박는다.
+ */
+const 직접못읽는확장자 = new Set([
+  '.ppt', '.doc', '.xls', '.xlt', '.rtf', '.odt', '.odp', '.ods', '.wpd', '.hwp',
+]);
+
+/** 이 파일을 변환해서 읽어 볼까. */
+export function 바꿔볼까(경로) {
+  return 바꿔볼확장자.has(extname(String(경로 ?? '')).toLowerCase());
+}
+
+/** 바꾸는 것 말고는 길이 없는 갈래인가. */
+export function 직접못읽나(경로) {
+  return 직접못읽는확장자.has(extname(String(경로 ?? '')).toLowerCase());
+}
+
+/*
+ * 이 PC 에 깔린 soffice 를 찾는다.
+ *
+ * PATH 에 없는 자리가 흔하다 — 맥은 앱 꾸러미 안에, 윈도우는 Program Files
+ * 밑에 있고 둘 다 PATH 에 안 걸린다. 사람이 쓰는 그 프로그램이 눈앞에 있는데
+ * "없습니다" 라고 말하는 것이 제일 아깝다.
+ */
+const soffice자리 = [
+  '/Applications/LibreOffice.app/Contents/MacOS/soffice',
+  'C:\\Program Files\\LibreOffice\\program\\soffice.exe',
+  'C:\\Program Files (x86)\\LibreOffice\\program\\soffice.exe',
+  '/usr/bin/soffice', '/usr/local/bin/soffice', '/opt/homebrew/bin/soffice',
+  '/snap/bin/libreoffice',
+];
+
+/*
+ * ── 윈도우에서 `.cmd` 는 그냥 못 띄운다 ─────────────────────────────────
+ *
+ * scoop·choco 로 깐 것은 `soffice.cmd` 같은 껍데기다. 그걸 spawnSync 로 그냥
+ * 부르면 **EINVAL** 이 난다(Node 20 부터 막혔다). 그러면 우리는 "이 PC 에
+ * 변환기가 없습니다" 라고 말하게 되는데 — 사람은 눈앞에서 그 프로그램을 쓰고
+ * 있다. 있다고 해 놓고 안 되는 것 다음으로 나쁜 것이 이것이다.
+ *
+ * `shell: true` 로 넘기면 되긴 하지만 node 가 DEP0190 경고를 내고, 그 지적이
+ * 맞다 — 경로에 빈칸이 있으면 그대로 깨진다. 사내 PC 의 `C:\Program Files\…`
+ * 가 정확히 그 꼴이다.
+ *
+ * 그래서 언어 서버 쪽에서 쓰는 것과 **같은 방법**을 쓴다 (lsp/client.js).
+ * `cmd /s /c` 는 뒤엣것이 따옴표로 시작해 따옴표로 끝나면 바깥 한 쌍을 떼어
+ * 내므로, 한 겹 더 둘러서 넘긴다.
+ */
+function 부르기(cmd, 인자, opts = {}) {
+  const 셸필요 = process.platform === 'win32' && /\.(cmd|bat)$/i.test(String(cmd));
+  if (!셸필요) return spawnSync(cmd, 인자, { encoding: 'utf8', windowsHide: true, ...opts });
+  const 몰아쓰기 = `""${cmd}" ${인자.map((a) => `"${a}"`).join(' ')}"`;
+  return spawnSync(process.env.ComSpec || 'cmd.exe', ['/d', '/s', '/c', 몰아쓰기], {
+    encoding: 'utf8', windowsHide: true, windowsVerbatimArguments: true, ...opts,
+  });
+}
+
+function 돌아가나(cmd, 인자) {
+  const r = 부르기(cmd, 인자, { timeout: 15000 });
+  return !r.error && r.status === 0;
+}
+
+let 본것 = null;
+
+/**
+ * 쓸 수 있는 변환기. 한 번만 찾는다.
+ *
+ * @returns {{soffice: string|null, textutil: boolean, 왜: string|null}}
+ */
+export function 변환기찾기({ 다시 = false, env = process.env, platform = process.platform } = {}) {
+  if (본것 && !다시) return 본것;
+  if (env.DEEL_CONVERT === 'off') {
+    본것 = { soffice: null, textutil: false, 왜: 'DEEL_CONVERT=off 로 꺼 두었습니다' };
+    return 본것;
+  }
+  let soffice = null;
+  if (돌아가나('soffice', ['--version'])) soffice = 'soffice';
+  else {
+    for (const p of soffice자리) {
+      if (existsSync(p) && 돌아가나(p, ['--version'])) { soffice = p; break; }
+    }
+  }
+  // textutil 은 맥에만 있고 .doc·.rtf 를 아주 빨리 바꾼다. soffice 보다 먼저 쓴다.
+  const textutil = platform === 'darwin' && 돌아가나('textutil', ['-info', '/dev/null']);
+  본것 = { soffice, textutil, 왜: null };
+  return 본것;
+}
+
+/** 검사가 원래대로 돌려놓을 때. */
+export function 변환기잊기() { 본것 = null; return null; }
+
+/** 사람에게 보여줄 한 줄. */
+export function 변환기말(찾은것 = 변환기찾기()) {
+  if (찾은것.왜) return 찾은것.왜;
+  const 것들 = [];
+  if (찾은것.soffice) 것들.push('soffice');
+  if (찾은것.textutil) 것들.push('textutil');
+  return 것들.length ? `${것들.join(' · ')} 를 빌려 씁니다` : '이 PC 에 쓸 수 있는 변환기가 없습니다';
+}
+
+/*
+ * 못 바꿨을 때 하는 말.
+ *
+ * 여기가 「안 된다고 확실히 말하는」 자리다. 여태 이 자리에서 나간 말은
+ * `바이너리 파일입니다 — 텍스트로 읽을 수 없습니다` 한 줄이었다. 그 말에는
+ * 까닭도 길도 없어서, 모델은 같은 파일을 Read 로 또 열거나 Bash 로 우회로를
+ * 찾다 울타리에 막히고, 그 왕복으로 컨텍스트만 탔다.
+ *
+ * 그래서 세 가지를 한꺼번에 말한다 — 무엇이라서 못 읽는지, 이 PC 에 무엇이
+ * 없어서 못 바꾸는지, 사람이 무엇을 하면 되는지. 그리고 **다시 열지 말라**고
+ * 못 박는다. 다시 열어도 결과가 같은 것은 우리가 아는 사실이다.
+ */
+export function 못바꿈말(보인이름, 확장자, 찾은것 = 변환기찾기()) {
+  const 갈래 = String(확장자 ?? '').replace(/^\./, '').toLowerCase();
+  const 없다 = !찾은것.soffice && !찾은것.textutil;
+  const 길 = 없다
+    ? '이 PC 에 LibreOffice(soffice)가 없어서 바꿔 읽을 수도 없습니다.'
+    : '이 PC 의 변환기로 바꿔 봤지만 글이 안 나왔습니다.';
+  return `${보인이름} 은 deel 이 직접 못 읽는 형식입니다 (.${갈래}).\n`
+    + `${길}\n`
+    + `해결: 원래 프로그램에서 ${새이름(갈래)} 로 저장한 뒤 다시 주세요.`
+    + (없다 ? ' 또는 LibreOffice 를 설치하면 deel 이 빌려 씁니다.' : '')
+    + '\n**같은 파일을 다시 Read 하지 마세요. 결과는 같습니다.**';
+}
+
+/** 그 갈래를 무엇으로 저장하면 읽히는지. */
+function 새이름(갈래) {
+  if (갈래 === 'ppt') return 'pptx';
+  if (갈래 === 'doc' || 갈래 === 'rtf' || 갈래 === 'odt' || 갈래 === 'wpd') return 'docx';
+  if (갈래 === 'xls' || 갈래 === 'ods') return 'xlsx';
+  if (갈래 === 'odp') return 'pptx';
+  if (갈래 === 'hwp') return 'hwpx';
+  return 'pdf 나 txt';
+}
+
+/** 떨굴 자리. 작업 폴더 안이라야 한다. */
+export function 임시자리(root) {
+  return join(root, '.deel', 'tmp');
+}
+
+/**
+ * 문서를 글로 바꿔서 읽는다.
+ *
+ * @param {string} abs   읽을 파일 (절대경로)
+ * @param {string} root  작업 폴더 — 바꾼 것을 여기 안에 떨군다
+ * @returns {{ok:true, text:string, 쓴것:string} | {ok:false, 왜:string, 없음?:boolean}}
+ */
+export function 글로바꾸기(abs, root, { timeout = 90000, 찾은것 = null } = {}) {
+  const 있는것 = 찾은것 ?? 변환기찾기();
+  if (!있는것.soffice && !있는것.textutil) {
+    return { ok: false, 없음: true, 왜: 있는것.왜 ?? '이 PC 에 변환기가 없습니다' };
+  }
+  if (!existsSync(abs)) return { ok: false, 왜: `없는 파일입니다: ${abs}` };
+
+  const 받을곳 = 임시자리(root);
+  try { mkdirSync(받을곳, { recursive: true }); } catch (err) {
+    return { ok: false, 왜: `바꿔 놓을 자리를 못 만들었습니다: ${err.message}` };
+  }
+
+  /*
+   * textutil 을 먼저 본다 (맥).
+   *
+   * soffice 는 처음 뜰 때 몇십 초가 걸린다 — 실제로 20초를 재 봤다. textutil 은
+   * OS 에 붙어 있는 것이라 곧바로 답한다. 둘 다 되는 자리면 빠른 쪽이 맞다.
+   */
+  const 확장자 = extname(abs).toLowerCase();
+  if (있는것.textutil && ['.doc', '.rtf', '.odt', '.docx'].includes(확장자)) {
+    const 나온것 = join(받을곳, `${basename(abs, 확장자)}.txt`);
+    const r = 부르기('textutil', ['-convert', 'txt', '-output', 나온것, abs], { timeout });
+    if (!r.error && r.status === 0 && existsSync(나온것)) {
+      const text = readFileSync(나온것, 'utf8');
+      // soffice 쪽과 같은 규칙 — 읽었으면 사본을 남기지 않는다.
+      try { rmSync(나온것, { force: true }); } catch { /* 임시치우기가 거둔다 */ }
+      return { ok: true, text, 쓴것: 'textutil', 파일: 나온것 };
+    }
+  }
+
+  if (!있는것.soffice) return { ok: false, 없음: true, 왜: '이 파일을 바꿀 변환기가 없습니다' };
+
+  /*
+   * soffice 는 결과 파일 이름을 제가 정한다.
+   *
+   * 그래서 넣기 전에 폴더에 무엇이 있었는지 적어 두고, 나온 뒤에 늘어난 것을
+   * 찾는다. 이름을 미리 짐작하면 확장자가 겹치거나 다른 판에서 어긋난다.
+   *
+   * -env:UserInstallation 을 따로 주는 까닭: soffice 는 이미 떠 있는 제 인스턴스가
+   * 있으면 새 부탁을 그쪽에 넘기고 **곧바로 끝나 버린다.** 사람이 LibreOffice 를
+   * 열어 둔 PC 에서 변환이 조용히 아무것도 안 하는 것이 그 모습이다. 우리 몫의
+   * 프로필을 따로 주면 그 일이 안 생긴다.
+   */
+  const 프로필 = join(받을곳, '.soffice-profile');
+  const 전 = new Set(existsSync(받을곳) ? readdirSync(받을곳) : []);
+  const r = 부르기(있는것.soffice, [
+    `-env:UserInstallation=file:///${프로필.replace(/\\/g, '/').replace(/^\/+/, '')}`,
+    '--headless', '--norestore',
+    '--convert-to', 'txt:Text',
+    '--outdir', 받을곳,
+    abs,
+  ], { timeout });
+
+  if (r.error) {
+    return { ok: false, 왜: `변환기를 못 돌렸습니다: ${r.error.message}` };
+  }
+  const 새로생긴것 = (existsSync(받을곳) ? readdirSync(받을곳) : [])
+    .filter((f) => !전.has(f) && f.toLowerCase().endsWith('.txt'));
+  if (!새로생긴것.length) {
+    const 끄트머리 = String(r.stderr || r.stdout || '').trim().split('\n').slice(-2).join(' ').slice(0, 200);
+    return { ok: false, 왜: `변환기가 글을 못 뽑았습니다${끄트머리 ? ` (${끄트머리})` : ''}` };
+  }
+  const 나온것 = join(받을곳, 새로생긴것[0]);
+  let text = '';
+  try { text = readFileSync(나온것, 'utf8'); } catch (err) {
+    return { ok: false, 왜: `바꾼 글을 못 읽었습니다: ${err.message}` };
+  } finally {
+    /*
+     * 읽었으면 곧바로 지운다.
+     *
+     * 글은 이미 손에 있다. 남겨 두면 **사람 문서의 알맹이가 사본으로 작업
+     * 폴더에 쌓인다** — 그대로 커밋되거나 압축되어 나갈 수 있는 자리다.
+     * 나중에 거두겠다는 약속은 세션이 죽으면 안 지켜진다. 지금 지운다.
+     */
+    try { rmSync(나온것, { force: true }); } catch { /* 못 지우면 임시치우기가 거둔다 */ }
+  }
+  return { ok: true, text, 쓴것: 'soffice', 파일: 나온것 };
+}
+
+/** 떨궈 둔 것을 거둔다. 검사와 세션 끝에서 부른다. */
+export function 임시치우기(root) {
+  const 자리 = 임시자리(root);
+  if (!existsSync(자리)) return 0;
+  let 몇개 = 0;
+  for (const f of readdirSync(자리)) {
+    const p = join(자리, f);
+    try {
+      // 사람이 넣어 둔 것은 안 건드린다. 우리가 만든 것만 거둔다.
+      if (f === '.soffice-profile' || (statSync(p).isFile() && f.toLowerCase().endsWith('.txt'))) {
+        rmSync(p, { recursive: true, force: true });
+        몇개++;
+      }
+    } catch { /* 못 지워도 다음에 지운다 */ }
+  }
+  return 몇개;
+}

package/src/tools/docs.js

@@ -56,6 +56,77 @@ export function looksOldHwp(경로, buf) {
   return buf.length >= 8 && buf.readUInt32LE(0) === 0xe011cfd0 && buf.readUInt32LE(4) === 0xe11ab1a1;
 }
 
+/*
+ * ── 겉과 속이 다를 때, 속이 무엇인지 말한다 ─────────────────────────────
+ *
+ * 여태는 이랬다 —
+ *
+ *   ◧ Read(보고서.pptx)
+ *     └ pptx 모양이 아닙니다 — 겉은 pptx 인데 속이 zip 꾸러미가 아닙니다.
+ *       깨졌거나 다른 형식입니다.
+ *
+ * 「깨졌거나 다른 형식」 은 **아무것도 안 알려 준다.** 깨진 것이면 할 일이
+ * 없고, 다른 형식이면 바꾸면 되는데 둘을 안 갈라 줬다. 그래서 모델은 같은
+ * 파일을 몇 번씩 다시 열어 봤다 — 답이 매번 같은데도.
+ *
+ * 앞 몇 바이트만 보면 무엇인지 거의 다 안다. 알면 길도 같이 줄 수 있다.
+ * 옛 hwp 안내(아래)가 이미 그렇게 하고 있었는데, 이쪽만 안 하고 있었다.
+ */
+const 서명들 = [
+  { 이름: '옛 Office 파일 (.ppt · .doc · .xls)', 바이트: [0xd0, 0xcf, 0x11, 0xe0, 0xa1, 0xb1, 0x1a, 0xe1] },
+  { 이름: 'PDF', 바이트: [0x25, 0x50, 0x44, 0x46] },                     // %PDF
+  { 이름: 'RTF 문서', 바이트: [0x7b, 0x5c, 0x72, 0x74, 0x66] },           // {\rtf
+  { 이름: 'PNG 그림', 바이트: [0x89, 0x50, 0x4e, 0x47] },
+  { 이름: 'JPEG 그림', 바이트: [0xff, 0xd8, 0xff] },
+  { 이름: 'gzip 압축', 바이트: [0x1f, 0x8b] },
+  { 이름: '7z 압축', 바이트: [0x37, 0x7a, 0xbc, 0xaf] },
+  { 이름: 'RAR 압축', 바이트: [0x52, 0x61, 0x72, 0x21] },
+];
+
+/** 앞 몇 바이트로 정체를 짚는다. 모르면 null. */
+export function 속내용(buf) {
+  if (!Buffer.isBuffer(buf) || buf.length < 2) return null;
+  for (const s of 서명들) {
+    if (s.바이트.every((b, i) => buf[i] === b)) return s.이름;
+  }
+  const 앞 = buf.subarray(0, 200).toString('latin1').trim().toLowerCase();
+  if (/^<(!doctype html|html|\?xml)/.test(앞)) return 앞.startsWith('<?xml') ? 'XML 글' : 'HTML 글';
+  // 남은 것이 전부 읽을 수 있는 글자면 그냥 글 파일이다.
+  const 이상한바이트 = buf.subarray(0, 512).filter((b) => b < 9 || (b > 13 && b < 32)).length;
+  if (!이상한바이트) return '그냥 글 파일';
+  return null;
+}
+
+/**
+ * 겉과 속이 다를 때 하는 말. **길을 같이 준다.**
+ *
+ * @param {string} 갈래  겉으로 본 갈래 (pptx · docx · hwpx)
+ * @param {string|null} 속  속내용() 이 짚은 것
+ */
+export function 겉속다름말(갈래, 속) {
+  const 머리 = `겉은 ${갈래} 인데 속이 다릅니다`;
+  if (!속) {
+    return `${머리} — 무엇인지 알아보지 못했습니다 (zip 꾸러미가 아닙니다).\n`
+      + '  파일이 깨졌을 수 있습니다. 이 파일로는 더 해 볼 것이 없으니 사용자에게 알리세요.';
+  }
+  if (속.startsWith('옛 Office')) {
+    return `${머리} — 실제로는 ${속} 입니다.\n`
+      + `  이름만 ${갈래} 로 바뀐 옛 형식이라 이 도구로는 못 읽습니다.\n`
+      + `  PowerPoint·Word 에서 열어 ${갈래} 로 다시 저장하거나,\n`
+      + `  soffice 가 깔려 있으면 soffice --headless --convert-to ${갈래} <파일> 로 바꾸세요.`;
+  }
+  if (속 === 'PDF') {
+    return `${머리} — 실제로는 PDF 입니다.\n`
+      + `  확장자만 ${갈래} 입니다. 파일 이름을 .pdf 로 바꿔서 Read 하면 그대로 읽힙니다.`;
+  }
+  if (속 === 'HTML 글' || 속 === 'XML 글' || 속 === '그냥 글 파일') {
+    return `${머리} — 실제로는 ${속} 입니다.\n`
+      + '  글 파일이라 확장자를 .txt 로 바꾸거나 그대로 Bash 로 읽을 수 있습니다.';
+  }
+  return `${머리} — 실제로는 ${속} 입니다.\n`
+    + `  ${갈래} 로 읽을 수 있는 파일이 아닙니다. 이 파일로는 더 해 볼 것이 없으니 사용자에게 알리세요.`;
+}
+
 /** 구형 hwp 를 만났을 때 하는 말. 길을 같이 준다. */
 export function 옛hwp안내(보인이름) {
   return `구형 hwp 형식이라 읽지 못합니다: ${보인이름}\n`
@@ -176,7 +247,7 @@ export function readDoc(경로또는버퍼) {
   }
   if (!갈래) return { ok: false, error: '어떤 문서인지 모르는 경로입니다' };
   if (!looksZip(buf)) {
-    return { ok: false, error: `${갈래} 모양이 아닙니다 — 겉은 ${갈래} 인데 속이 zip 꾸러미가 아닙니다. 깨졌거나 다른 형식입니다.` };
+    return { ok: false, error: 겉속다름말(갈래, 속내용(buf)), 끝났다: true };
   }
 
   let 꾸러미;

package/src/tools/index.js

@@ -1,7 +1,7 @@
 // 도구. 이름과 인자를 Claude Code 와 같게 맞춘다 —
 // 그래야 그 관례로 쓰인 스킬·명령이 그대로 먹는다.
 import { writeFileSync, appendFileSync, readFileSync, existsSync, mkdirSync, statSync, renameSync, cpSync, rmSync } from 'node:fs';
-import { dirname, join, relative, sep } from 'node:path';
+import { dirname, extname, join, relative, sep } from 'node:path';
 import { execFile } from 'node:child_process';
 import { globToRegex, walk, readText, readTextFull, 내부살림 } from './fsutil.js';
 import { 건너뜀말 } from './ignore.js';
@@ -23,7 +23,8 @@ import { allow as allowedIn } from '../agent/modes.js';
 import { 도구정의, 이름풀기 } from '../backend/mcp.js';
 import { isExcelPath, readExcel, toText as excelText, summarize as excelSummary } from './excel.js';
 import { isDocPath, readDoc, toText as docText, summarize as docSummary, looksOldHwp, 옛hwp안내, 문서는못고침 } from './docs.js';
-import { isPdfPath, readPdf, toText as pdfText, summarize as pdfSummary, 못읽은말, pdf는못고침 } from './pdf.js';
+import { 바꿔볼까, 직접못읽나, 변환기찾기, 글로바꾸기, 못바꿈말 } from './convert.js';
+import { isPdfPath, readPdf, toText as pdfText, summarize as pdfSummary, 못읽은말, pdf는못고침, 한쪽도못읽음말 } from './pdf.js';
 import { diffLines } from '../ui/diff.js';
 import { 읽을줄수, 찾을개수, 찾을줄수, 설명길이 } from '../agent/budget.js';
 import { 도구설명EN } from './desc.en.js';
@@ -123,6 +124,56 @@ export function 붙박이그림줄이기(줄들) {
   return { 줄들: 나온것, 알림, 줄인바이트, 몇개 };
 }
 
+/*
+ * ── 안 보여 준 것을 지우게 두면 안 된다 ─────────────────────────────────
+ *
+ * 위 붙박이그림줄이기 는 **읽을 때만** 그림을 뺀다. 파일은 그대로다. 그런데
+ * 그 다음이 문제였다 — 모델은 그렇게 받은 글을 손봐서 Write 로 통째로 덮어쓴다.
+ * 그러면 제가 못 본 그림은 새 내용에 없다. **사용자 파일에서 그림이 사라진다.**
+ *
+ * 실제로 이렇게 났다 (사내 보고서 HTML):
+ *
+ *   ◧ Read(보고서.html)   1425줄 · 그림 8.0MB 생략
+ *   ◈ Write(보고서.html)  1420줄          ← 8MB 짜리 그림 일곱 개가 여기서 없어진다
+ *
+ * 오류는 없다. 화면도 멀쩡하다. 파일을 열어 봐야 안다 — 그림이 있던 자리에
+ * 깨진 아이콘만 남는다. 몇 주 뒤에 알아채면 되돌릴 방법도 없다.
+ *
+ * 안 보여 준 것에 대한 책임은 우리에게 있다. 모델은 최선을 다한 것이다 —
+ * 있는 줄 몰랐던 것을 지킬 수는 없다. 그러니 여기서 막는다.
+ *
+ * 세는 방식이 중요하다. **생략 표시가 있나** 로만 보면 모자란다. 모델이 그
+ * 줄을 통째로 지워 버리는 경우가 더 흔하고, 그때는 표시도 같이 사라진다.
+ * 그래서 **개수를 견준다** — 있던 것보다 줄었으면 잃은 것이다.
+ */
+export function 박힌그림수(글) {
+  return (String(글 ?? '').match(그림자리) ?? []).length;
+}
+
+/**
+ * 이 덮어쓰기가 박힌 그림을 잃게 하나.
+ *
+ * @returns {string|null} 막을 이유. 잃는 것이 없으면 null.
+ */
+function 그림잃나(abs, 새내용) {
+  if (!existsSync(abs)) return null;
+  let 옛것;
+  try { 옛것 = readTextFull(abs).text; } catch { return null; }
+  const 있던것 = 박힌그림수(옛것);
+  if (!있던것) return null;
+  const 남는것 = 박힌그림수(새내용);
+  if (남는것 >= 있던것) return null;
+
+  const 잃는것 = 있던것 - 남는것;
+  const 생략표시 = /…\([\d.]+\s*[KMG]?B 생략\)…/.test(새내용);
+  return `이 파일에 박혀 있는 그림 ${있던것}개 중 ${잃는것}개가 새 내용에 없습니다 — 덮어쓰면 사라집니다.\n`
+    + (생략표시
+      ? '  Read 가 보여준 「…(생략)…」 표시를 그대로 되쓰셨습니다. 그건 그림이 아니라 자리 표시입니다.\n'
+      : '  Read 는 그림 자리를 빼고 보여줍니다. 못 본 것이라 새로 쓸 때 빠진 것입니다.\n')
+    + '  통째로 덮어쓰지 말고 **Edit 으로 고칠 자리만** 바꾸세요. 그러면 그림은 파일에 그대로 남습니다.\n'
+    + '  정말 그림을 빼는 것이 목적이면 사용자에게 먼저 확인하세요.';
+}
+
 // 엑셀 파일에 쓰려 할 때 하는 말. 왜 안 되는지와, 그럼 어떻게 하는지를 같이 준다.
 /**
  * 이 자리에 글을 써 넣으면 안 되는 파일인가.
@@ -279,7 +330,18 @@ function 엑셀은못고침(보인이름) {
  */
 async function 엑셀읽기(abs, args, ctx) {
   const r = await readExcel(abs, { askPassword: ctx.askPassword ?? null });
-  if (!r.ok) return { error: r.error };
+  if (!r.ok) {
+    /*
+     * 옛 `.xls` 는 엑셀 COM 말고는 길이 없었다. 그래서 엑셀이 없는 PC —
+     * 맥과 리눅스가 전부 여기다 — 에서는 그냥 실패로 끝났다. 이 PC 에
+     * LibreOffice 가 있으면 그것이 곧 길이다. 표는 아니고 글이지만,
+     * 아무것도 못 읽는 것보다 낫다.
+     */
+    const 빌린것 = 빌려읽기(abs, ctx, r.error);
+    if (빌린것) return 빌린것;
+    if (직접못읽나(abs)) return { error: 못바꿈말(ctx.scope.show(abs), extname(abs)), 끝났다: true };
+    return { error: r.error };
+  }
 
   const { text, 잘림 } = excelText(r.sheets);
   const 말 = [...(r.notes ?? []), ...잘림];
@@ -299,9 +361,55 @@ async function 엑셀읽기(abs, args, ctx) {
  * 엑셀읽기와 같은 규칙 — ctx.seen 에 안 넣는다. 넣으면 Edit 이 '이 파일 고칠
  * 수 있다' 고 오해한다. 문서는 이 도구로 고치는 물건이 아니다.
  */
+/**
+ * 우리가 못 읽는 문서를 **이미 깔린 변환기**로 한 번 더 해 본다 (tools/convert.js).
+ *
+ * `rg` 를 빌려 쓰는 것과 같은 원칙이다 — 아무것도 설치하지 않고, 있으면 쓰고,
+ * 없으면 없다고 말한다. 여기가 붙기 전에는 이렇게 끝났다:
+ *
+ *   ◧ Read(보고서.pptx)
+ *     └ pptx 모양이 아닙니다 — 깨졌거나 다른 형식입니다.
+ *
+ * 정작 그 PC 에는 LibreOffice 가 깔려 있었다. 사람이 그 파일을 열어 보는 바로
+ * 그 프로그램이다. 그런데 모델은 그걸 부를 수도 없었고(울타리에 막혔다),
+ * 있는지 볼 수도 없었다.
+ *
+ * @returns {object|null} 읽어냈으면 도구 결과. 못 하면 null (부르는 쪽이 원래 오류를 낸다)
+ */
+function 빌려읽기(abs, ctx, 원래오류) {
+  if (!바꿔볼까(abs)) return null;
+  const root = ctx.scope?.root;
+  if (!root) return null;
+
+  // ctx.변환기 는 검사에서 가짜 변환기를 끼우는 자리다. 진짜 LibreOffice 를
+  // 깔아야만 확인되는 검사는 아무도 안 돌린다.
+  const 있는것 = ctx.변환기 ?? 변환기찾기();
+  if (!있는것.soffice && !있는것.textutil) return null;
+
+  const r = 글로바꾸기(abs, root, { 찾은것: 있는것 });
+  if (!r.ok || !r.text.trim()) return null;
+
+  const 줄수 = r.text.split('\n').length;
+  return {
+    content: clip(
+      `${r.text}\n\n(deel 이 직접 못 읽는 형식이라 이 PC 의 ${r.쓴것} 로 글만 뽑아 보여준 것입니다.`
+      + ' 원본은 한 글자도 안 바뀌었습니다. 이 파일은 Edit/Write 로 고칠 수 없습니다 —'
+      + ` 고쳐야 하면 새 파일에 쓰세요.)\n(원래 못 읽은 까닭: ${String(원래오류).split('\n')[0]})`,
+    ),
+    summary: `${r.쓴것} 로 바꿔 읽음 · ${줄수}줄`,
+  };
+}
+
 function 문서읽기(abs, ctx) {
   const r = readDoc(abs);
-  if (!r.ok) return { error: r.error };
+  if (!r.ok) {
+    // 우리가 못 읽는다고 끝이 아니다. 이 PC 에 변환기가 있으면 빌려 본다.
+    const 빌린것 = 빌려읽기(abs, ctx, r.error);
+    if (빌린것) return 빌린것;
+    // 끝났다 를 그대로 넘긴다. 여기서 떨구면 docs.js 가 「다시 열어도 같다」고
+    // 판정해 놓은 것이 루프까지 못 가서, 되풀이 억제가 안 걸린다.
+    return { error: r.error, ...(r.끝났다 ? { 끝났다: true } : {}) };
+  }
   const { text, 잘림 } = docText(r.덩이들);
   return {
     content: clip(
@@ -328,6 +436,19 @@ function pdf읽기(abs, ctx) {
   if (!r.ok) return { error: r.error };
   const { text, 잘림 } = pdfText(r);
   const 못 = 못읽은말(r);
+  /*
+   * 한 쪽도 못 읽었으면 **실패다.** 성공으로 돌려주면 안 된다.
+   *
+   * 여태 「글이 하나도 없는 PDF 입니다」를 본문으로 돌려줬다. 그러면 도구는
+   * 성공한 것이 되어 되풀이 감지도, 배움도, 재시도 억제도 하나도 안 걸린다.
+   * 그래서 모델은 같은 파일을 몇 번씩 다시 열었고, 그때마다 같은 답을 받았다.
+   */
+  // text 로 재면 안 된다 — 못 읽은 쪽에도 `--- 3쪽 ---` 와 「못 읽었습니다」가
+  // 들어가서 글이 있는 것처럼 보인다. 실제 문단이 하나라도 나왔는지로 가른다.
+  const 글나온쪽 = (r.덩이들 ?? []).some((d) => (d.문단들 ?? []).some((p) => String(p).trim()));
+  if (!글나온쪽) {
+    return { error: 한쪽도못읽음말(r, ctx.scope.show(abs)), 끝났다: true };
+  }
   return {
     content: clip(
       `${text || '(글이 하나도 없는 PDF 입니다.)'}
@@ -503,6 +624,9 @@ function 한파일쓰기(args, ctx) {
     // 확장자로 고르지 않고 실제 내용으로 본다 — 사내 파일은 확장자가 제각각이다.
     const 바이너리막기 = 바이너리인가(abs);
     if (바이너리막기) return { error: 바이너리막기 };
+    // 우리가 안 보여 준 그림을 모델이 지우게 두지 않는다 (그림잃나 머리말).
+    const 그림막기 = 그림잃나(abs, args.content);
+    if (그림막기) return { error: 그림막기 };
     ctx.history.snapshot(abs, 'Write');
     const existed = existsSync(abs);
     // 덮어쓰기 전 내용. 바뀐 자리를 보여주려면 지금 떠 놔야 한다.
@@ -796,10 +920,32 @@ export const TOOLS = {
       if (abs.toLowerCase().endsWith('.hwp')) {
         try {
           const 머리 = readFileSync(abs);
-          if (looksOldHwp(abs, 머리)) return { error: 옛hwp안내(ctx.scope.show(abs)) };
+          if (looksOldHwp(abs, 머리)) {
+            // 여기도 먼저 빌려 본다. 이 PC 에 변환기가 있으면 안내문보다 글이 낫다.
+            const 안내 = 옛hwp안내(ctx.scope.show(abs));
+            return 빌려읽기(abs, ctx, 안내) ?? { error: 안내 };
+          }
         } catch { /* 아래 일반 읽기가 제 오류를 낸다 */ }
       }
 
+      /*
+       * 옛 Office(.ppt·.doc·.xls·.rtf·.odt…)가 여기서 걸린다.
+       *
+       * 위의 갈래들과 달리 우리는 이걸 아예 못 읽는다. 그냥 두면 아래 일반
+       * 읽기가 `바이너리 파일입니다` 로 끝냈다 — 까닭도 길도 없는 거절이라
+       * 모델이 같은 문을 계속 두드린다. 사내 자료에 제일 흔한 갈래가 하필
+       * 이것들이다.
+       *
+       * 그래서 여기서 두 갈래로 끝낸다. 이 PC 에 변환기가 있으면 빌려 읽고,
+       * 없으면 **없다고 못 박고 끝낸다**(끝났다: true → 되풀이 억제가 걸린다).
+       */
+      if (직접못읽나(abs)) {
+        const 보인이름 = ctx.scope.show(abs);
+        const 빌린것 = 빌려읽기(abs, ctx, `${보인이름} 을 deel 이 직접 못 읽습니다.`);
+        if (빌린것) return 빌린것;
+        return { error: 못바꿈말(보인이름, extname(abs)), 끝났다: true };
+      }
+
       const 읽음 = readTextFull(abs);
       // 무엇으로 읽었는지 기억해 둔다. 나중에 고칠 때 같은 것으로 되돌려 써야 한다.
       // 안 그러면 사내 CP949 문서가 한 번 고치는 것만으로 UTF-8 이 되어 버린다.
@@ -816,9 +962,23 @@ export const TOOLS = {
       const more = lines.length > start + count ? `\n… 전체 ${lines.length}줄 중 ${start + count}줄까지` : '';
       ctx.seen.add(abs);
       const 별난인코딩 = 읽음.encoding !== 'utf-8';
+      /*
+       * 요약에는 **실제로 건넨 줄 수**를 적는다.
+       *
+       * 여태 파일의 전체 줄 수를 적었다. 그래서 32k 모델에서 1,425줄짜리
+       * 파일을 열면 모델은 384줄만 받는데 화면에는 `1425줄` 이 찍혔다 —
+       * 사람은 다 읽은 줄 알고 "왜 저걸 못 고치지" 를 되풀이한다. 잘렸다는
+       * 말은 모델에게 가는 본문에만 있었고, 보는 사람에게는 없었다.
+       *
+       * budget.js 의 읽을줄수 머리말에 이 함정이 그대로 적혀 있는데
+       * (「화면에는 2,000줄이라고만 떠서 사람은 잘 읽은 줄 안다」) 정작
+       * 이 줄은 안 고쳐져 있었다.
+       */
+      const 준줄수 = slice.length;
+      const 다못줌 = start + count < lines.length || start > 0;
       return {
         content: clip(body + more + 줄인것.알림),
-        summary: `${lines.length}줄`
+        summary: (다못줌 ? `${준줄수}/${lines.length}줄 (일부만)` : `${lines.length}줄`)
           + (줄인것.줄인바이트 ? ` · 그림 ${몇KB(줄인것.줄인바이트)} 생략` : '')
           + (별난인코딩 ? ` · ${encLabel(읽음.encoding)}` : ''),
       };

package/src/tools/pdf.js

@@ -1290,8 +1290,50 @@ export function toText(r, { maxChars = 최대글자 } = {}) {
 export function summarize(r) {
   if (!r?.ok) return '';
   const 통째로못읽음 = (r.못읽은쪽 ?? []).filter((x) => !x.일부).length;
-  const 뒤 = 통째로못읽음 ? ` · ${통째로못읽음}쪽 못 읽음` : '';
-  return `pdf · ${r.쪽수}쪽${뒤}`;
+  if (!통째로못읽음) return `pdf · ${r.쪽수}쪽`;
+  /*
+   * **왜** 못 읽었는지를 화면 요약에 올린다.
+   *
+   * 여태 `11쪽 못 읽음` 까지만 찍혔다. 까닭은 모델에게 가는 본문에만 있었다.
+   * 그런데 그 둘은 사람이 할 일이 완전히 다르다 — 스캔본이면 OCR 을 찾아야
+   * 하고, 글꼴 표가 없는 것이면 원본에서 다시 뽑으면 된다. 화면만 보는 사람은
+   * 그 갈림길을 못 본 채 "왜 안 읽히지" 만 되풀이한다.
+   */
+  const 까닭들 = new Set((r.못읽은쪽 ?? []).filter((x) => !x.일부).map((x) => 짧은까닭(x.왜)));
+  const 왜 = 까닭들.size === 1 ? ` (${[...까닭들][0]})` : '';
+  return `pdf · ${r.쪽수}쪽 · ${통째로못읽음}쪽 못 읽음${왜}`;
+}
+
+/** 화면 한 줄에 들어갈 만큼 줄인 까닭. */
+function 짧은까닭(왜) {
+  const s = String(왜 ?? '');
+  if (/ToUnicode/.test(s)) return '글꼴에 /ToUnicode 표 없음';
+  if (/스캔|OCR/.test(s)) return '글이 없는 쪽 — 스캔본일 수 있음';
+  if (/빈 쪽/.test(s)) return '빈 쪽';
+  if (/압축|못 풀/.test(s)) return '내용을 못 풀었음';
+  return s.length > 28 ? `${s.slice(0, 28)}…` : s;
+}
+
+/**
+ * 한 쪽도 글을 못 꺼냈을 때 하는 말. **길을 같이 준다.**
+ *
+ * 이건 성공이 아니라 실패다. 여태는 「글이 하나도 없는 PDF 입니다」를 본문으로
+ * 돌려줬는데, 그러면 도구는 성공한 것이 되어 되풀이 감지도 배움도 안 걸린다.
+ * 모델은 같은 파일을 계속 다시 열었다.
+ */
+export function 한쪽도못읽음말(r, 보인이름) {
+  const 까닭들 = [...new Set((r?.못읽은쪽 ?? []).map((x) => String(x.왜)))];
+  const 줄 = [`${r?.쪽수 ?? 0}쪽을 전부 글로 못 읽었습니다: ${보인이름}`];
+  for (const 왜 of 까닭들.slice(0, 3)) 줄.push(`  · ${왜}`);
+  if (까닭들.some((x) => /ToUnicode/.test(x))) {
+    줄.push('  글꼴이 글자표를 안 싣고 있어 되돌릴 수 없습니다. 이 PDF 를 만든 원본');
+    줄.push('  (pptx·docx 등)이 있으면 그쪽을 읽으세요. 훨씬 정확합니다.');
+  } else {
+    줄.push('  글이 그림으로만 들어 있습니다. 이 도구로는 더 해 볼 것이 없습니다 —');
+    줄.push('  OCR 이 필요하거나, 이 PDF 를 만든 원본 파일을 읽어야 합니다.');
+  }
+  줄.push('  **같은 파일을 다시 Read 하지 마세요. 결과는 같습니다.**');
+  return 줄.join('\n');
 }
 
 /**