deel-local-cli 1.0.1 → 1.1.0

package/README.en.md

@@ -20,10 +20,12 @@ Zero dependencies · Node 20+ · Exactly one place your source can go
  │ Sends to this machine 127.0.0.1:11434  ← nowhere else        │
  │ Link     streaming · tools · reasoning control               │
  │ Folder   C:\work\myproject                                   │
+ │ Approval ⏵⏵ 자동 승인  — nothing is asked; /undo is the net   │
+ │          Shift+Tab to change  ·  Tab completes a / command   │
  │ This PC  337 skills · 127 commands · 42 plugins              │
  ╰──────────────────────────────────────────────────────────────╯
 
- ▏myproject · qwen2.5-coder:7b ▏ ▰▰▱▱▱▱▱▱▱▱ 22% 28k/128k ▏ ◎ 종합 · ◇ medium·절약 · auto
+ ▏myproject · qwen2.5-coder:7b ▏ ▰▰▱▱▱▱▱▱▱▱ 22% 28k/128k ▏ ◎ 종합 · ◇ medium·절약 · ⏵⏵ 자동
  ❯ unify the logging style
 
   ❊ Grep(console.log)
@@ -201,6 +203,136 @@ $ deel scan
 
 Switch with `/model` mid-conversation — **the conversation carries over.**
 
+### It adapts to whatever model is attached
+
+If you move between models, any number tuned for one of them is wrong for all the others.
+So **no number is hardcoded.**
+
+There are two axes. They are easy to confuse, so they have separate commands.
+
+| | What it measures | Command |
+|---|---|---|
+| **Window size** | how much it can hold | `/ctx` |
+| **Model grade** | how much it can do on its own | `/grade` |
+
+They do not move together. A 3B model with a 128k window exists; so does a very good model
+with 32k. Treat them as one axis and you hold one back while overrunning the other.
+
+**Derived from window size** (`src/agent/budget.js`):
+
+| | 8k | 32k | 131k | 655k |
+|---|---|---|---|---|
+| Steps per turn (code) | 16 | 48 | 192 | 200 |
+| `Read` lines | 200 | 384 | 1,536 | 4,000 |
+| `Glob` results | 50 | 192 | 768 | 1,000 |
+| `Outline` lines | 120 | 480 | 1,920 | 2,500 |
+| `WebFetch` chars | 4,000 | 12,800 | 51,200 | 120,000 |
+| Subtask summary | 400 | 1,600 | 4,000 | 4,000 |
+
+**Derived from model grade** (`src/agent/grade.js`):
+
+| | small | medium | large |
+|---|---|---|---|
+| Files per `Write` | 3 | 6 | 12 |
+| Split-writing threshold | 200 lines | 400 lines | 800 lines |
+| Spell out the procedure | yes | yes | **no — give the goal** |
+| Require verification | yes | yes | **yes** (grade-independent) |
+
+The grade is decided like this:
+
+1. **First guess from the name.** `qwen2.5-coder-7b` -> small, `llama-3.3-70b` -> large.
+   Version numbers (`2.5`) and quantisation tags (`q4_k_m`) are not read as sizes.
+   A name that says nothing means **medium**, not small — a corporate gateway is exactly
+   that case, and the models behind one are usually big. Guessing small holds them back.
+2. **Corrected by what actually happened.** Truncated tool arguments, empty answers,
+   failed edits and repeats are counted. A model labelled 70B that truncates every step is
+   dropped to **small**; a 7B that runs ten clean steps is raised one level. The name is a
+   guess; what happened is a fact.
+3. **You win if you say so.** `/grade large`, and `/grade auto` hands it back.
+
+The status line shows `◈ small?`. The question mark means **still a guess** — a guess is
+not presented with the same face as something measured.
+
+The grade only changes **how much hand-holding you get**. Working scope, approval mode,
+undo and the audit log are identical at every grade. There is no "it is a good model, so
+skip verification" — that is exactly how a good model's mistake goes unnoticed.
+
+### Small windows get a smaller fixed share
+
+The system prompt and the tool definitions go out **in full on every request**. Compaction
+(`/compact`) cannot shrink them. Once that share passes half the window there is no room
+left however well you fold, and it looks like "the model suddenly got stupid".
+
+Adding three tools (`Outline`, `Verify`, `Task`) pushed it to **49%** at 8k. Dropping a
+tool would have fixed it — and would have made small models capable of different things,
+which is the thing to avoid. The descriptions were trimmed to the window instead.
+
+| | 8k | 16k | 32k+ |
+|---|---|---|---|
+| Base rules | short form | short form | full |
+| Mode description | short form | short form | full |
+| Tool descriptions | 90 chars | 140 chars | 220 / full |
+| Obvious param descriptions | dropped | kept | kept |
+| Descriptions inside array items | dropped | dropped | kept |
+| **Fixed share** | **2,712 tokens (33%)** | 3,290 (21%) | 4,745 (4% at 131k) |
+
+The **folder brief** adds roughly 80 more tokens at 8k (below). That value varies by
+folder, so it is not in the table.
+
+**Tool names and arguments are untouched.** What is possible is identical in every window;
+what disappears is only the argument for *why* to use a tool. Large windows keep it,
+because that argument earns its keep — those two sentences are what make a model call
+`Outline` before `Read`.
+
+A test pins these numbers (`test/compact.test.js`).
+
+### On startup it reads what kind of project this folder is
+
+Started in a folder of someone else's code, the model began knowing nothing. So it
+retraced the same three steps every time — scan the top level, read `package.json`, find
+out how tests are run. **On a local model each step is 20-40 seconds, so two minutes go
+by before the work even starts.**
+
+The worse case is the model *skipping* those three steps. Then it creates files by its
+own conventions without knowing what the project already uses — a `requirements.txt`
+dropped into an npm project.
+
+The answers are all knowable at startup, so they are read once and put in the prompt.
+
+The brief itself is written in Korean, like everything else deel puts on screen — this is
+deel's own folder, wrapped here for width:
+
+```
+--- 이 폴더 ---                         (this folder)
+node 프로젝트 (deel-local-cli) · git main
+돌릴 수 있는 것: npm start · npm test · npm run bench · npm run chat · npm run check ·
+                 npm run coverage · npm run demo · npm run diagnose      (runnable)
+위쪽: bin/ src/ test/ LICENSE README.en.md README.md package.json report.txt   (top level)
+위쪽 한 겹만 본 것이다. 안을 알아야 하면 Outline 을 불러라.
+   (top level only — call Outline to see inside)
+```
+
+**Nothing is invented.** Runnable commands are copied verbatim from `scripts` in
+`package.json`. Advertising a command that does not exist means the model calls it,
+fails, and spends the steps you just saved looking for the real one.
+
+**The last line matters.** What is listed is the top level and `package.json`, nothing
+inside subfolders. Without saying so, the model treats this as a map of the whole project
+and stops calling `Outline` — at which point the brief costs more than it saves.
+
+| Not done | Why |
+|---|---|
+| No `git` subprocess | `.git/HEAD` is read directly. Spawning one freezes startup for seconds on a large repo |
+| No directory walk | Top level **only**. Descending is slow on large repos, and only one line goes in the prompt anyway |
+| Not re-read each turn | Once, at startup. A prompt that changes mid-conversation makes it impossible to tell why an answer changed |
+
+It scales with the window — 10 entries and 4 commands at 8k, 24 and 8 on a large one.
+If only one thing survives a narrow window it is the **commands**. The top-level listing
+can be recovered with one `Glob`; "tests run with `npm test`" requires opening
+`package.json`.
+
+7ms on a folder with 600 files (`test/project.test.js`).
+
 ---
 
 ## Slash commands
@@ -212,6 +344,7 @@ Names follow Claude Code / Codex conventions.
 | `/help` | Command list |
 | `/context` | What is consuming the context window |
 | `/ctx [auto\|number]` | Context **length** — re-read it off the model, or set it yourself |
+| `/grade [small\|medium\|large\|auto]` | Model **grade** — how much it does on its own. A different axis from `/ctx` |
 | `/out [number\|auto]` | Cap on a **single reply** — raise it when large files get cut |
 | `/compact` | Summarise and fold older turns |
 | `/clear` | Clear the conversation (keeps link and rules) |
@@ -245,6 +378,18 @@ Discovered plugin commands are invoked as `/<plugin>:<name>`, with `$ARGUMENTS`
 server or loaded a different model, `/scan save` then `/model` switches over without losing
 the conversation.
 
+**Without typing**
+
+| Key | What it does |
+|---|---|
+| `Tab` | Completes the `/` command you are typing. Candidates appear under the box as you type |
+| `Shift+Tab` | Approval policy (`⏵⏵ auto` → `⏵ risky only` → `⏸ everything`) |
+| `Ctrl+O` | Work mode (`종합` → `코드` → `계획` → …) |
+| `↑` `↓` | Input history |
+| `Ctrl+C` | Stops the answer in progress; twice on an empty line quits |
+
+Korean IME composition, paste, `Ctrl+A/E` and backspace all keep working.
+
 ### Attaching a file with `@`
 
 Write `@` followed by a path and that file is sent along with your message.
@@ -411,7 +556,7 @@ the bottom.** Only the box is erased and redrawn — nothing above it is touched
 
   ── 4.2s · 3 tools · ↑3,900 ↓180
 
- ▏myproject · qwen2.5-coder:7b ▏ ▰▰▱▱▱▱▱▱ 22% ▏ ◎ 종합 · ◇ medium · auto
+ ▏myproject · qwen2.5-coder:7b ▏ ▰▰▱▱▱▱▱▱ 22% ▏ ◎ 종합 · ◇ medium · ⏵⏵ 자동
  ╭─────────────────────────────────────────────────────────────────────────────╮
  │ ❯ also shrink the aggregate helpers                                         │
  ╰─────────────────────────────────────────────────────────────────────────────╯
@@ -442,6 +587,127 @@ editor is how you break IME input first.
 
 ---
 
+### You don't have to type the whole command
+
+There are over thirty commands. The only person who has them memorised is the one who
+wrote them, and even he gets as far as `/mem…` and stops to wonder whether it was `memory`
+or `memo`. If the only recourse at that point is typing `/help` and scanning thirty lines,
+that isn't a command, it's a quiz.
+
+So they show up **while you type.**
+
+```
+ ╭─────────────────────────────────────────────────────────────────────────────╮
+ │ ❯ /mo                                                                       │
+ ╰─────────────────────────────────────────────────────────────────────────────╯
+   › /model [이름|list|models]   연결·모델 바꾸기 (이름 일부 · list · models)
+     /mode <모드>                승인 정책 — 얼마나 물어보나
+     /memory [지우기 <번호>|…]   대화가 끝나도 남는 기억 — 보기·지우기
+```
+
+`Tab` fills it in: all the way if only one matches, otherwise **only as far as they all
+agree** (`/mo` + Tab → `/mode`). It doesn't pick one for you, because deleting the wrong
+guess costs more than typing the rest. Commands that take an argument get a trailing space
+so you can keep going.
+
+Prefix matches come first and **substring matches follow** — typos cluster in the first
+character, so `/emo` still surfaces `/memory`. The moment you type a space (`/mode auto`)
+the list folds away: the command is already decided.
+
+The list sits **below** the box. Putting it inside would push what you are typing upward,
+so you could no longer see it.
+
+> No up/down selection. That would have to take over **input history** (up arrow), which
+> is used far more often. What is needed here isn't picking, it's recognising — and once
+> you recognise it, one `Tab` is enough.
+>
+> Commands hidden at the `쉬움` level still surface when you type their prefix. Hidden is
+> not the same as unavailable — someone who knows `/recall` should not be told it doesn't
+> exist because of a display setting.
+
+---
+
+### The box stays while it works
+
+Local models are slow. A single step can take tens of seconds, and if the bottom of the
+screen goes blank for that long, **people assume it hung and hit Ctrl+C** — losing work that
+was nearly done. So the border stays and only the contents change.
+
+```
+  ◧ Read(집계.py)
+    └ 6 lines
+
+ ▏myproject · qwen2.5-coder:7b ▏ ▰▱▱▱▱▱▱▱▱▱ 2% ▏ ◎ 종합 · ◇ medium · ⏵⏵ 자동 ▏ ↑3.8k ↓180
+ ╭─────────────────────────────────────────────────────────────────────────────╮
+ │ ⠹ 파일 들여다보는 중…                    12초 · 생각 1,240자 · Ctrl+C 중단 │
+ ╰─────────────────────────────────────────────────────────────────────────────╯
+```
+
+The phrase tracks **what is actually happening**. This is not decoration: a message that
+cycles at random stops being read after the second time, and from then on it is worth no
+more than a blank screen. One turn reads like this:
+
+```
+머리 굴리는 중        →  파일 들여다보는 중  →  코드 짜는 중   →  답 쓰는 중
+(turning it over)       (looking at files)     (writing code)    (writing the answer)
+```
+
+| Activity | Phrases |
+|---|---|
+| Thinking | 머리 굴리는 중 · 어떻게 할지 궁리하는 중 · 수 읽는 중 · 따져 보는 중 |
+| `Read` `Grep` `Glob` | 파일 들여다보는 중 · 코드 훑는 중 · 어디 있나 뒤지는 중 · 단서 찾는 중 |
+| `Write` `Edit` `Append` | 코드 짜는 중 · 고쳐 넣는 중 · 손보는 중 · 한 줄씩 옮기는 중 |
+| `Bash` | 명령 돌리는 중 · 터미널 두드리는 중 · 결과 기다리는 중 |
+| `WebFetch` | 문서 찾아보는 중 · 읽어 오는 중 |
+| Answering | 답 쓰는 중 · 정리해서 말하는 중 |
+| **Past 45 seconds** | 아직 하는 중 · 조금만 더 · 생각보다 오래 걸리는 중 |
+
+Within a category the phrase advances every 4 seconds — text frozen for 30 seconds reads as
+hung too. On the right: **elapsed time**, and while the model is reasoning, **how many
+characters of thinking have arrived**. One number that genuinely increases is what turns
+"still alive" from a claim into a fact.
+
+### What gets asked, and what just happens
+
+Whether your files change **with or without being asked** is the one thing that has to be
+readable at a glance. It sits on the right of the status line at all times.
+
+| Indicator | Command | What it asks about |
+|---|---|---|
+| `⏵⏵ 자동 승인` (auto) | `/mode auto` | Nothing is asked. `/undo` is the safety net |
+| `⏵ 위험만 확인` (risky only) | `/mode confirm` | Only irreversible commands. Files change unasked |
+| `⏸ 모두 확인` (everything) | `/mode strict` | Every file change and every command is confirmed first |
+
+`/mode` on its own lists all three and marks the current one with ●. The startup header
+spells it out in a sentence, so the glyph is enough from then on.
+
+**`Shift+Tab` cycles it without typing.** Each press moves one step and leaves a line
+saying where it went. Whatever you were typing stays put.
+
+```
+  ⏵ 위험만 확인  되돌릴 수 없는 명령만 물어봅니다. 파일은 안 묻고 고칩니다
+  자동 승인 → 위험만 확인 · Shift+Tab 으로 계속 바꿉니다
+```
+
+The cycle runs **loose → strict** (auto → risky only → everything → auto). A mistaken
+press only makes it ask more; it never drops you into "changes files unasked" in one hit.
+
+> That key used to cycle the work mode (`종합`, `코드`, …). The swap is about **who
+> reaches for it more often.** Work mode follows your request on its own, while approval
+> policy is what you want to change mid-task when a particular job deserves a look.
+> Work mode moved to `Ctrl+O`; `/work` still does the same thing.
+
+> It used to be the bare word `auto`. Next to `종합` and `medium·절약` it looked like just
+> another mode, and nothing on screen said that one of them meant **files change without
+> asking.**
+>
+> That also changed what gets truncated when space runs out. A corporate gateway model name
+> like `databricks-gpt-5-6-luna` eats twenty-three columns, and that alone was pushing the
+> approval indicator off the line entirely. Now **the model name shortens first** — you
+> already know what you are running; whether your files change unasked is what you need now.
+
+---
+
 ## Tools
 
 Names and arguments match Claude Code, so skills written for that convention work unchanged.
@@ -449,21 +715,233 @@ Names and arguments match Claude Code, so skills written for that convention wor
 | Tool | What it does |
 |---|---|
 | `Read` | Read a file (line numbers, `offset`/`limit`, **Excel as CSV**) |
-| `Write` | Write / overwrite a file |
+| `Write` | Write / overwrite a file (**several at once via the `files` array**) |
 | `Append` | Append to the end of a file — **how large files get written in pieces** |
-| `Edit` | Replace an exact string (`replace_all` supported) |
+| `Edit` | Replace an exact string (`replace_all`; **several sites at once via the `edits` array**) |
 | `Glob` | Find files by name pattern |
 | `Grep` | Regex search file contents |
-| `Bash` | Run a command |
+| `Bash` | Run a command (**`background: true` for anything that does not finish**) |
 | `Skill` | Expand a skill body (shown to the model only when skills exist) |
 | `WebFetch` | Read a web page (read-only; hidden under `--offline`) |
 | `Recall` | Search **past conversations** — the model digs up "that thing last time" itself |
 | `Remember` | One line that outlives the session — known from the start next time |
 | `TodoWrite` | Checklist — breaks long work into steps and shows progress |
+| `Outline` | See a folder's **skeleton only** — tens of times cheaper than reading it whole |
+| `Verify` | Check that what was built **actually works** |
+| `Task` | Run one chunk of a big job in a **separate context** |
+| `Jobs` | Inspect, read and stop **background commands** — the other half of `Bash`'s `background` |
+
+Seven tools here are not in Claude Code — `Append`, `Recall`, `Remember`, `Outline`,
+`Verify`, `Task`, `Jobs`. Each tool costs 150-400 tokens of schema on **every request**,
+so a test stops you every time the list grows (`test/loop.test.js`). The last four earned
+their cost; here is why.
+
+### Seeing a project's shape cheaply — `Outline`
+
+There used to be only two ways to understand someone else's code. `Glob` gives you paths;
+`Read` pulls a whole file into the window. **The middle was missing.**
+
+So the model started editing without knowing what lived where, and re-created functions
+that already existed somewhere else. It had not seen them — which is different from not
+knowing.
+
+```
+❉ Outline(src/ui)   12 files · 122 places
+
+src/ui/screen.js  (304 lines)
+     46  fn     상자쓸까
+     65  class  LineScreen
+     92  method 줄
+    198  class  BoxScreen
+```
+
+Reading that folder whole costs **25,612 tokens**; `Outline` costs **857** — 30x cheaper.
+An 8k model can see the shape of a whole project.
+
+It reads js/ts, py, java/kotlin, go, rust, c#, md, html, css, sh and json. Regex, not a
+parser (zero dependencies). So it **says what it could not read** — dropping those
+silently makes the model believe the file does not exist, and rebuild config that is
+already there.
+
+### Checking what was built — `Verify`
+
+The end of a turn used to say:
+
+```
+  ✓ index.html · 410 lines · 18.2KB
+```
+
+That proves the file **exists**, not that it **works**. An unclosed `<div>`, a
+`src="app.js"` pointing at nothing, a JS file one bracket short — all green.
+
+What can be run gets run (`node --check`, `py_compile`); what cannot gets read (HTML tag
+pairing, missing references, CSS braces, JSON).
+
+```
+⏺ Verify   1 broken · 3 checked
+```
+
+And the part that matters most — **what could not be checked is reported as such.**
+
+Arbitrary commands are **not** run here. That path has to be `Bash` alone: the approval
+gate and the safety checks live only there, so running commands from here would break the
+strict-mode promise in exactly this one spot. It tells you `npm test` exists instead.
+
+### Splitting big work off — `Task`
+
+Building eight files in one window means all eight files pile up in that window. On a 32k
+model it fills around the third or fourth, and once it fills, earlier turns get folded
+away. From then on the model has forgotten what it was building — **no error appears, the
+result just gets worse.** That was the root of "build me a dashboard" ending as a plan.
+
+`Task` runs that chunk in a **fresh conversation** and returns only a summary.
+
+```
+⌥ subtask  build the page skeleton   separate conversation · max 8 steps
+ │  ◆ Write(index.html +1)  2 files · 24 lines
+✓ subtask  build the page skeleton   done · 2 files · 2 steps
+```
+
+Peak conversation size while building the same four files (system prompt excluded):
+
+| | Peak |
+|---|---|
+| All in one window | 4,181 chars |
+| Split with `Task` | **2,113 chars** |
+
+The left column keeps growing with each file; the right one does not.
+
+**Every guard still applies.** A subtask runs inside the same working folder, follows the
+same approval mode, is undone **together with** its parent by one `/undo`, and lands in
+the audit log. There is no path for a subtask to edit files under a read-only mode
+(architect, plan, ask) — that is blocked both at the mode level and in the tool list.
+Nesting stops at two levels.
+
+### Commands that never finish — `Bash`'s `background` and `Jobs`
+
+`Bash` only returns once the command **ends**. So anything that does not end could not be
+run — `npm run dev`, `python -m http.server`, `vite`, `npm run watch`. Asking for one used
+to mean waiting 120 seconds and then a kill, leaving one line on screen.
+
+```
+  ▶ Bash(npm run dev)
+    └ 시간 초과로 중단됨 (120000ms)                              2분 0.0초
+       (timed out)
+```
+
+The model concludes the server would not start and gives up, or worse, raises `timeout`
+and calls again — which stalls the whole turn. **There was no way at all to start what
+you built and check it.** `Verify` gets you as far as "the syntax is valid"; whether it
+actually comes up requires bringing it up.
 
-Only **three** tools here are not in Claude Code — `Append`, `Recall`, `Remember`. Each
-tool costs roughly 150 tokens of schema on **every request**, so a test stops you every
-time the list grows (`test/loop.test.js`).
+```
+  ▶ Bash(npm run dev)
+    └ 1번으로 띄움          (started as job 1)
+
+  ◈ Edit(src/App.jsx)
+    └ 1군데                 (1 site)
+
+  ◐ Jobs(1번)
+    └ 도는중 · 24초         (running · 24s)
+
+  ◐ Jobs(1번 · 끝내기)
+    └ 끝냄 · 41초           (stopped · 41s)
+```
+
+It starts and **returns immediately**. Output accumulates and `Jobs` reads it.
+
+**Something that did not start is never reported as started.** The job is watched briefly
+after launch, and if it dies in that window it comes back as a failure. The most common
+failure is a port already in use; reporting that as "started" sends the model on to the
+next step while you refresh a server that was never there.
+
+```
+  ▶ Bash(npm run dev)
+    └ 띄우자마자 끝났습니다 (종료코드 1).
+       (exited immediately, exit code 1)
+```
+
+| Guarantee | Detail |
+|---|---|
+| Safety checks | **Identical** to `Bash`. This must not become a back door |
+| Cleanup | Everything is killed when deel exits — **down to grandchildren**, and it says how many |
+| Retained | 256KB. Past that the front is dropped and **the drop is stated** |
+| Handed to the model | 4,000 chars. This **must** be a different number from the one above |
+| On stop | Waits for the dying output, and returns only once the process is **actually dead** |
+| Argument names | Korean and English both accepted (`번호`/`job`, `끝내기`/`stop`). Unrecognized ones **are reported** |
+| Count | Eight running. Finished jobs keep the most recent eight, and evictions **are stated** |
+
+Why two different caps: make them equal and every overflow of a `watch` job means
+one `Jobs` read dumps 256KB into the window. On an 8k model that single read ends
+the window.
+
+**Stopping a job does not close its pipes immediately.** At the moment the kill is
+issued there is still unread data in the pipe, and the last few lines before a
+death are the ones that matter — the stack trace a server leaves on the way down.
+Printing `last output:` and then withholding the last output is worse than not
+printing it. It also waits until the process is **confirmed dead** before dropping
+it from the list: dropping a live one means it can never be named again, which is
+the exact state this feature exists to prevent.
+
+Finished jobs are not dropped right away — they are kept so their final output can
+be read. Only the most recent eight survive; otherwise thirty short commands leave
+thirty entries, each holding up to 256KB.
+
+**Argument names are accepted in both Korean and English.** Models frequently
+translate Korean parameter names into English — not a guess, something this repo
+already hit (`Task` accepts both `목적` and `purpose`). `Jobs` did not, which meant:
+
+```
+Jobs({job: 1, stop: true})   ->   a listing comes back. The server keeps running.
+```
+
+The model asked for a stop and **got what looks like a success** while the port
+stays held. So both spellings are accepted, and when nothing is recognized it says
+so rather than falling back to a listing. The name mapping lives in exactly **one**
+place — the on-screen label reads it too. Two copies means the tool works while the
+label shows empty parentheses.
+
+**Killing grandchildren is where this quietly goes wrong.** `npm run dev` descends
+npm → node → vite, and the thing holding the port is at the bottom. Windows has
+`taskkill /t` to walk the tree; Unix has nothing equivalent, so the job is
+**started in its own process group** — after the fact there is no way to name a
+grandchild at all. Skip that and deel says "killed 3" while the server keeps running.
+
+Cleanup is where this quietly goes wrong. Skip it and a process nobody started keeps
+running. Next time you start a dev server you get "port already in use" with **no way to
+find what is holding it**. So `test/jobs.test.js` verifies the process actually died, via
+a file the child keeps appending to.
+
+`deel run` (one-shot mode) does the same. A batch job is hurt worst by missing this — the
+job reports done, the server keeps running, and the next job fails to bind the same port
+with nothing in the log to explain it.
+
+### Several at once — `Write`'s `files`, `Edit`'s `edits`
+
+One round trip is 20-40 seconds on a local model. Creating five files with five `Write`
+calls is two to three minutes of nothing but round trips. So they go in one array.
+
+```
+  ◈ Edit(src/app.js 외 2군데)
+    └ 2개 파일 · 3군데      (2 files · 3 sites)
+      ✓ src/app.js · 2군데
+      ✓ src/style.css · 1군데
+```
+
+**Editing is worth more than writing here.** Creating files happens once; editing happens
+continuously. Six edit sites at six round trips is minutes gone.
+
+| | Guaranteed |
+|---|---|
+| Applied in order | Editing one file twice is common. Each edit re-reads from disk, so later ones see earlier results |
+| One failure | The rest still run. Stopping at the first failure re-adds the round trips this was meant to remove |
+| On failure | "Resend only what failed — **and `Read` the file again first**" |
+| Undo | Still **one turn**. Six sites in one file is one `/undo` |
+| Single-site form | The result shape is byte-for-byte unchanged |
+
+It reports `2 files · 3 sites` rather than a single number. Editing one file at six sites
+is normal, so "3 files" would be false — and once the screen stops matching what you can
+count yourself, you stop trusting the screen.
 
 ### Finding past conversations, and remembering decisions
 
@@ -1045,7 +1523,7 @@ does not ask.
 
 | Mechanism | Detail |
 |---|---|
-| **Undo** | Snapshot before every write. `/undo` restores per turn |
+| **Undo** | Snapshot before every write. `/undo` restores per turn. **Includes moves and deletes done through `Bash`** |
 | **Change display** | The changed lines are shown on every edit; `/diff` for the whole session |
 | **Scope** | Outside the starting folder is refused, even if the model insists |
 | **Blocked commands** | Only irreversible ones (disk format, recursive delete, `--force` push) |
@@ -1065,6 +1543,37 @@ Undo history stores whole file contents, so repeated edits to large files add up
 it keeps the **most recent 50 turns** and drops the rest. What you just did is always
 undoable; `/status` shows how large the history currently is.
 
+### Files removed through `Bash` come back too
+
+The safety net covered `Write` and `Edit` only. But a model moving a file reaches for
+`Bash` — `mv old.js new.js`, `rm temp.txt`. The file was gone and `/undo` could do
+nothing about it. It was half a safety net.
+
+Now a mutating command snapshots the files it names beforehand, and **says what it saved,
+right there**.
+
+```
+  ▶ Bash(mv src/old.js src/new.js)
+    └ 성공
+      ↩ src/old.js 는 떠 뒀습니다 — /undo 로 되돌아갑니다
+         (saved src/old.js — /undo restores it)
+```
+
+`mv` and `rm` leave one "success" line on screen. From that line alone there is no way to
+tell whether it is reversible, so people either assume it is and move on, or assume it is
+not and get scared. So the fact is stated.
+
+**What cannot be saved is not hidden.** Shell-expanded wildcards (`rm *.tmp`), deletions
+inside a script, and whole directories are invisible here. In those cases the `↩` line
+simply does not appear — **it never claims "everything is reversible"**. False reassurance
+means people stop checking.
+
+Snapshotting casts a **wider** net than blocking does. The scope guard (`checkPaths`) only
+treats words containing a slash as paths — anything else would block legitimate commands —
+but `del target.txt`, with no slash, is the most common form there is. This is a reading
+site rather than a blocking one, so it scans broadly and saves a file only when one is
+actually there. A wrong guess costs nothing. Up to 24 per command.
+
 ### What it will not read
 
 Walking a folder turns up things that are not project files: the private stores other coding
@@ -1226,7 +1735,7 @@ If the working folder has `DEEL.md`, `CLAUDE.md` or `AGENTS.md`, it is loaded as
 ## Development
 
 ```bash
-npm test          Full suite (1,787 checks)
+npm test          Full suite (1,832 checks)
 npm run coverage  Which lines the tests actually execute
 npm run verify    Import + network checks only
 npm run bench     Edit success rate
@@ -1280,7 +1789,7 @@ Zero dependencies rules out c8 and nyc, so this reads Node's own
 `NODE_V8_COVERAGE` instead — nothing new to get through an import review. It picks up
 child processes too, so the `cli` suite that spawns `deel` counts like everything else.
 
-Currently **92% overall** (6,911 of 7,496 lines). Three files are deliberately left short.
+Currently **92% overall** (7,056 of 7,646 lines). Three files are deliberately left short.
 
 | File | Now | Why it stops there |
 |---|---|---|