deel-local-cli 1.10.0 → 1.13.0

package/src/tools/jobs.js

@@ -1,795 +1,876 @@
-/*
- * 뒤에서 계속 도는 명령.
- *
- * 왜 필요한가:
- *   Bash 는 명령이 **끝나야** 결과를 준다. 그래서 끝나지 않는 것을 못 돌린다 —
- *   `npm run dev`, `python -m http.server`, `vite`, `npm run watch` 가 전부 그렇다.
- *   전에는 이걸 시키면 120초를 기다렸다가 시간 초과로 죽였다. 화면에는
- *   `시간 초과로 중단됨` 만 남는다. 모델은 서버를 못 띄운 것으로 알고 포기하거나,
- *   더 나쁘게는 timeout 을 늘려서 다시 부른다 — 그러면 그 턴이 통째로 멈춘다.
- *
- *   만든 것을 **띄워서 확인**하는 것이 바이브코딩의 마지막 한 칸이다.
- *   Verify 가 "문법은 맞다" 까지 봐 주지만, 진짜로 뜨는지는 띄워 봐야 안다.
- *
- * 무엇을 하나:
- *   명령을 띄우고 **바로 돌아온다.** 출력은 여기에 쌓아 두고, 모델이 Jobs 로
- *   읽어 간다. 뜨자마자 죽는 경우(포트가 이미 물려 있다 등)가 흔해서, 띄운 직후
- *   잠깐 기다렸다가 그 사이 나온 것을 같이 준다 — 그 몇 줄이 대부분의 답이다.
- *
- * 지키는 선:
- *   · 안전 검사는 Bash 와 **똑같이** 거친다. 여기가 뒷문이 되면 안 된다.
- *     (checkCommand·checkPaths 는 부르는 쪽에서 이미 거친다 — index.js 참고)
- *   · deel 이 끝나면 전부 죽인다. 남겨 두면 사람이 모르는 프로세스가 계속 돈다.
- *     그건 '내가 안 띄운 서버가 포트를 물고 있는' 상태고, 원인을 못 찾는다.
- *   · 출력은 상한이 있다. watch 하나가 몇 시간 돌면 몇 GB 가 된다.
- */
-import { spawn, execFileSync } from 'node:child_process';
-import { decode as decodeBytes, consoleCodepage } from './encoding.js';
-import { 셸명령 } from './shell.js';
-import { 열쇠뺀환경 } from '../backend/mcp.js';
-import { 말, 세말 } from '../i18n/index.js';
-
-/* 결과 한 줄을 잇는다 — 빈 조각은 버린다(tools/index.js 의 이어 와 같은 것). */
-const 이어 = (...조각들) => 조각들.filter((x) => x != null && String(x) !== '').join(' · ');
-
-// 한 일감이 **들고 있을** 출력 상한. 넘으면 앞을 버리고 뒤를 남긴다 —
-// 오래 도는 것에서 필요한 건 언제나 **방금** 나온 쪽이다.
-const 출력상한 = 256 * 1024;
-/*
- * 한 번에 **모델에게 건넬** 상한. 위엣것과 다른 값이어야 한다.
- *
- * 둘을 같은 값으로 두면 watch 하나가 넘칠 때마다 Jobs 읽기 한 번이 256KB 를
- * 창에 쏟는다. 8k 모델이면 그 한 번으로 창이 끝나고, 큰 창에서도 대화가
- * 통째로 밀려 나간다. 게다가 넘친 직후에는 커서가 0 으로 돌아가 있어서
- * (담기 참고) '새것만' 달라고 해도 통째로 온다 — 그러니 여기가 막혀 있어야 한다.
- *
- * Bash 의 background 쪽은 처음부터 4,000자로 줄이고 있었는데 이 길만 뚫려 있었다.
- */
-const 건넬상한 = 4000;
-// 동시에 띄워 둘 수 있는 개수. 이보다 많아지면 사람이 못 따라간다.
-export const 최대일감 = 8;
-/*
- * **끝난** 일감을 몇 개까지 들고 있나.
- *
- * 바로 지우면 안 된다 — 마지막 출력을 읽으라고 남겨 두는 것이다. 그런데
- * 안 지우면 짧은 명령 서른 개에 항목 서른 개가 쌓이고, 하나가 최대 256KB 를
- * 들고 있으니 몇 MB 가 된다. 목록을 볼 때마다 그걸 전부 다시 푼다.
- *
- * 그래서 최근 것만 남기고 오래된 것부터 버린다. 도는 것은 여기 안 센다 —
- * 그건 최대일감 이 따로 막는다.
- */
-const 끝난것상한 = 8;
-/*
- * 죽인 뒤 남은 말을 얼마나 기다리나.
- *
- * 유닉스 쪽 SIGKILL 올려치기(800ms)보다 짧게 잡는다. 여기서 먼저 깨어나
- * '아직 사나' 를 보고, 살아 있으면 그 자리에서 곧장 끊기 때문이다.
- */
-const 죽는말기다림 = 700;
-
-// 명령을 셸에 넘기는 방법은 tools/shell.js 한 군데서 정한다. Bash 도구와 같은 값이어야
-// 한다 — 두 벌이 되면 한쪽만 고쳐지고, 윈도우에서 따옴표가 든 명령이 조용히 뭉개진다.
-export { 셸명령 };
-
-/**
- * 어떻게 띄우나 — spawn 에 넘길 것들.
- *
- * `detached` 가 이 함수가 있는 이유다. 윈도우는 `taskkill /t` 가 프로세스
- * 나무를 훑어 주지만 유닉스에는 그런 것이 없다. **띄울 때 무리(process group)를
- * 만들어 두지 않으면 나중에 손자를 가리킬 방법이 아예 없다.**
- *
- * `npm run dev` 는 npm → node → vite 로 내려가고, 포트를 무는 것은 맨 아래다.
- * sh 에 SIGTERM 만 보내면 그 아래가 그대로 남아서 — 사람 눈에 안 보이는 채로 —
- * 계속 돈다. 나중에 고칠 수 없는 종류라 띄우는 순간에 정해 둔다.
- *
- * 윈도우에서는 반대로 무리를 안 만든다. detached 는 거기서 새 콘솔 창을
- * 띄우는 쪽으로 작동해서, 조용히 돌아야 할 것이 화면에 튀어나온다.
- */
-export function 띄우기옵션(cwd) {
-  const win = process.platform === 'win32';
-  return {
-    cwd,
-    // 열쇠만 빼고 나머지는 그대로 물려준다 (backend/mcp.js 열쇠뺀환경 머리말).
-    env: 열쇠뺀환경(),
-    windowsHide: true,
-    detached: !win,
-    stdio: ['ignore', 'pipe', 'pipe'],
-  };
-}
-
-/**
- * 윈도우에서 pid 아래 나무를 통째로 끊는다.
- *
- * @returns {boolean} 나무를 **다 훑었나.** false 면 손자가 남아 있을 수 있으니,
- *   부르는 쪽은 뿌리(cmd.exe)를 죽이지 말고 다시 와야 한다.
- *
- * ── 실패 두 가지를 갈라야 한다 ──────────────────────────────────────────
- *
- *   · 「그런 프로세스 없다」 — 이미 죽은 것이다. 탈이 아니다.
- *   · **taskkill 이 제 상한에 걸려 잘렸다** — 나무를 다 못 훑었다.
- *
- * 뒤엣것을 앞엣것처럼 넘기고 뿌리를 죽여 버리면 손자가 영영 못 찾는 채로
- * 남는다. 뿌리가 죽은 뒤에는 `taskkill /pid` 가 「프로세스를 못 찾았습니다」 로
- * 끝나서 다시 부를 수조차 없다.
- *
- * ── 무엇으로 가르나: err.killed 가 아니다 ───────────────────────────────
- *
- * 처음에는 `!err?.killed` 로 갈랐다. **그게 늘 참이었다.** 비동기 execFile 의
- * 콜백은 상한에 걸리면 err.killed 를 true 로 주는데, execFileSync 는 안 준다.
- * 그래서 「나무를 다 못 훑었다」 가 한 번도 안 나왔고, 뿌리를 살려 두는 분기는
- * 처음부터 닿지 않는 코드였다 — 이 판의 대표 기능이 통째로 헛돈 셈이다.
- *
- * 실제로 재 보고 갈랐다(윈도우 11 · Node 20):
- *
- *   상한에 걸림        killed=undefined  signal=SIGTERM  code=ETIMEDOUT  status=null
- *   없는 pid 를 죽임    killed=undefined  signal=null     code=undefined  status=128
- *
- * 갈리는 자리는 **signal 과 code** 다. 아래 검사(test/jobs.test.js 의
- * '★ taskkill 이 잘린 것과 이미 죽은 것을 가른다')가 이 값을 못박아 둔다.
- */
-export function 나무끊기(pid, 상한 = 1500) {
-  if (process.platform !== 'win32' || !pid) return true;
-  try {
-    execFileSync('taskkill', ['/pid', String(pid), '/t', '/f'],
-      { windowsHide: true, stdio: 'ignore', timeout: 상한 });
-    return true;
-  } catch (err) {
-    return !잘렸나(err);
-  }
-}
-
-/** 이 오류가 「상한에 걸려 잘렸다」 인가. 아니면 그냥 0 이 아닌 값으로 끝난 것이다. */
-export function 잘렸나(err) {
-  return err?.code === 'ETIMEDOUT' || err?.signal != null || err?.killed === true;
-}
-
-/**
- * 유닉스에서 pid 가 이끄는 **무리째** 죽인다.
- *
- * 음수 pid 는 '그 무리 전부' 라는 뜻이다 — 띄울 때 detached 로 무리를 만들어
- * 둔 것과 짝이다. 이걸 안 하고 kid.kill() 만 하면 sh 나 npm 만 죽고 그 아래
- * vite 가 포트를 문 채로 남는다. 무엇이 물고 있는지 못 찾는, 제일 나쁜 자리다.
- *
- * 먼저 곱게 말하고(TERM), 안 들으면 끊는다(KILL). 곧장 KILL 로 가면 dev 서버가
- * 임시 파일이나 소켓을 치울 틈이 없다.
- *
- * **띄울 때 무리를 안 만들었으면 여기서 할 수 있는 것이 없다.** 나중에 무리를
- * 만들어 줄 방법은 없다 — 그래서 이 판단이 띄우는 자리와 짝을 이뤄야 한다.
- * (Bash 도구가 한동안 이 짝을 안 맞춰서, 윈도우만 고쳐지고 유닉스는 그대로였다.)
- */
-export function 무리끊기(pid, { 곧장 = false, 늦게 = 800 } = {}) {
-  if (process.platform === 'win32' || !pid) return;
-  if (곧장) {
-    try { process.kill(-pid, 'SIGKILL'); } catch { /* 이미 죽음 */ }
-    return;
-  }
-  try { process.kill(-pid, 'SIGTERM'); } catch { /* 무리가 없거나 이미 죽음 */ }
-  try {
-    const 시계 = setTimeout(() => { try { process.kill(-pid, 'SIGKILL'); } catch { /* 죽었다 */ } }, 늦게);
-    시계.unref?.();
-  } catch { /* 끝나는 중이면 타이머를 못 건다 — 부르는 쪽이 곧장 으로 다시 온다 */ }
-}
-
-/**
- * 프로세스 나무를 통째로 끝낸다. 자식만 죽이면 손자가 남아 포트를 계속 문다.
- *
- * 윈도우에서 taskkill 을 **기다린다.** 전에는 execFile(비동기)로 불렀는데,
- * 그러면 두 가지가 조용히 어긋난다.
- *
- *   1. 바로 아래 kid.kill() 이 먼저 돌아 cmd 를 죽인다. 나무의 뿌리가 없어진
- *      뒤에 taskkill 이 뜨므로 손자 — `npm run dev` 의 진짜 서버 — 를 못 찾고,
- *      그놈은 그대로 남아 포트를 문다. 죽이라고 말은 했는데 안 죽는다.
- *   2. process 의 'exit' 에서 부를 때는 **아예 안 돈다.** 그 자리에서는
- *      비동기 일감이 하나도 실행되지 않는다. 끄려고 걸어 둔 마지막 그물이
- *      정작 제일 흔한 끝맺음(그냥 종료)에서 통째로 비어 있었던 셈이다.
- *
- * 그래서 동기로 부른다. 여기서 멈추는 몇십 ms 로 '안 죽은 서버' 를 없앤다.
- * test/jobs.test.js 의 '프로세스가 진짜 멈춘다' 가 이 자리를 지킨다.
- */
-function 나무죽이기(kid, { 파이프끊기: 끊을까 = true, 곧장 = false, 상한 = 1500, 뿌리살리기 = true } = {}) {
-  if (!kid) return true;
-  let 나무끊었나 = true;
-  if (process.platform === 'win32' && kid.pid) {
-    /*
-     * 상한은 부르는 쪽이 정한다. 여기는 끝날 때도 지나가는 자리라
-     * (process 'exit'), 일감마다 몇 초씩 기다리면 deel 이 멈춘 것처럼 보인다.
-     * 그래서 기본은 짧다. 사람이 「끝내」 라고 시킨 자리에서는 길게 준다 —
-     * 거기서는 몇백 ms 늦는 것보다 안 죽는 것이 훨씬 나쁘다.
-     */
-    나무끊었나 = 나무끊기(kid.pid, 상한);
-    /*
-     * 나무를 다 못 훑었으면 뿌리를 살려 둔다. 부르는 쪽이 다시 온다.
-     *
-     * 딱 한 자리만 예외다 — 더 이상 다시 올 수 없는 자리(프로그램이 끝나는
-     * 길)에서는 뿌리라도 죽인다. 둘 다 살려 두는 것보다는 낫다.
-     */
-    if (!나무끊었나 && 뿌리살리기) return false;
-  } else if (kid.pid) {
-    무리끊기(kid.pid, { 곧장 });
-  }
-  try { kid.kill(); } catch { /* 이미 죽음 */ }
-  if (끊을까) 파이프끊기(kid);
-  try { kid.unref(); } catch { /* 없으면 그만 */ }
-  return 나무끊었나;
-}
-
-/**
- * 파이프를 놓는다.
- *
- * 아이가 죽어도 stdout·stderr 를 붙들고 있으면 그 손잡이가 이벤트 루프를
- * 붙잡는다. unref() 는 프로세스 손잡이만 놓지 파이프는 안 놓는다.
- * 이걸 빠뜨리면 deel 이 할 일을 다 하고도 안 끝난다 — 사람 눈에는 멈춘 것이다.
- *
- * 다만 **죽이자마자 끊으면 안 된다.** 그 순간 파이프에는 아직 안 읽힌 것이
- * 남아 있고, 죽기 직전에 나온 몇 줄이 대개 제일 중요하다(서버가 뻗으며 남긴
- * 스택 트레이스가 거기 있다). 그래서 끝내기() 는 잠깐 기다렸다가 이걸 부른다.
- */
-function 파이프끊기(kid) {
-  try { kid?.stdout?.destroy(); } catch { /* 이미 닫힘 */ }
-  try { kid?.stderr?.destroy(); } catch { /* 이미 닫힘 */ }
-}
-
-/** 아직 살아 있나. 종료코드도 시그널도 없으면 안 죽은 것이다. */
-function 아직사나(kid) {
-  return !!kid && kid.exitCode == null && kid.signalCode == null;
-}
-
-/**
- * 죽인 뒤, 남은 말이 다 나오기를 잠깐 기다린다.
- *
- * 'close' 는 프로세스가 끝나고 **파이프까지 다 비워졌을 때** 온다. 그래서
- * 이걸 기다리면 죽는 순간 뱉은 것까지 손에 들어온다.
- *
- * 무한정 기다리지는 않는다 — 안 죽는 놈 하나가 그 턴을 통째로 잡아먹으면
- * 안 된다. 그리고 여기 시계는 unref 하지 않는다. 이 기다림이 지금 이벤트
- * 루프가 살아 있을 유일한 이유일 수 있어서, 놓아 버리면 그대로 끝난다.
- */
-function 죽는말기다리기(kid, ms) {
-  return new Promise((끝) => {
-    if (!kid || ms <= 0) return 끝();
-    let 됐나 = false;
-    const 마치기 = () => { if (됐나) return; 됐나 = true; clearTimeout(시계); 끝(); };
-    const 시계 = setTimeout(마치기, ms);
-    kid.once('close', 마치기);
-    kid.once('error', 마치기);
-  });
-}
-
-class 일감 {
-  constructor(번호, 명령, 설명) {
-    this.번호 = 번호;
-    this.명령 = 명령;
-    this.설명 = 설명 ?? null;
-    this.띄운때 = Date.now();
-    this.상태 = '도는중';       // 도는중 | 끝남 | 죽임
-    this.종료코드 = null;
-    this.시그널 = null;
-    this.조각들 = [];
-    this.바이트 = 0;
-    // 이 일감이 앞을 버린 적이 **있다**. 통째로 달라고 할 때의 사실이라,
-    // 한 번 서면 안 내려간다 — 지금 들고 있는 것이 처음부터가 아니라는 뜻이다.
-    this.앞잘림 = false;
-    // 지난번 읽어 간 뒤로 버렸다. **이번에 건네는 토막**에 대한 사실이라,
-    // 한 번 말하면 내린다. 이 둘을 한 칸으로 합치면 안 된다 (읽기() 참고).
-    this.막버렸다 = false;
-    this.읽은글자 = 0;
-    // 한 번 정하면 안 바꾼다. 바뀌면 읽은 자리가 조용히 어긋난다 (전체글 참고).
-    this.인코딩 = null;
-    // 담을 때마다 는다. 푼 글을 다시 써도 되는지를 이 숫자로 가른다 —
-    // 바이트 수로 가르면 버린 만큼 다시 담겼을 때 같은 값이 되어 못 알아챈다.
-    this.판 = 0;
-    this.푼것 = null;
-    this.kid = null;
-  }
-
-  담기(buf) {
-    if (!buf?.length) return;
-    this.조각들.push(Buffer.from(buf));
-    this.바이트 += buf.length;
-    this.판++;
-    if (this.바이트 <= 출력상한) return;
-    /*
-     * 앞을 버린다.
-     *
-     * 버리면 이미 읽은 글자 수가 뜻을 잃는다 — 앞이 사라졌으니 같은 자리가
-     * 아니다. 억지로 맞추려 들면 조용히 어긋난 글을 주게 되므로, 커서를
-     * 0 으로 돌리고 **앞이 잘렸다고 말한다.** 겹쳐 보이는 편이 낫다.
-     */
-    while (this.바이트 > 출력상한 && this.조각들.length > 1) {
-      this.바이트 -= this.조각들.shift().length;
-    }
-    this.앞잘림 = true;
-    this.막버렸다 = true;
-    this.읽은글자 = 0;
-  }
-
-  /*
-   * 쌓인 것을 글로 푼다.
-   *
-   * 조각마다 풀면 여러 바이트짜리 글자가 조각 경계에서 쪼개져 깨진다.
-   * 통째로 이어 붙여 한 번에 푼다.
-   *
-   * **인코딩은 한 번 정하면 안 바꾼다.** 이게 중요하다 — 읽은 자리(읽은글자)를
-   * 글자 수로 세고 있는데, 인코딩이 중간에 바뀌면 같은 앞부분이 다른 글자 수로
-   * 풀린다. 그러면 커서가 가리키던 자리가 조용히 어긋나서, 이미 준 글을 다시
-   * 주거나 새 글을 건너뛴다. 오류도 안 나고 로그에도 안 남는다.
-   *
-   * 실제로 그럴 수 있다. 인코딩 판정은 **버퍼 전체를 보는 어림짐작**이라,
-   * UTF-8 로 잘 풀리던 출력에 UTF-8 이 아닌 바이트가 하나 섞이는 순간
-   * 통째로 CP949 로 다시 읽힌다 — 한글 윈도우 콘솔에서 흔한 일이다.
-   */
-  전체글() {
-    if (!this.조각들.length) return '';
-    /*
-     * 안 바뀌었으면 지난번 것을 그대로 준다.
-     *
-     * `목록()` 이 일감마다 이걸 부른다 — 안 읽은 글자 수를 세려고. 그 한 번이
-     * 최대 256KB 를 이어 붙이고 통째로 다시 푸는 일이라, 끝난 것 여덟 개를
-     * 들고 있으면 목록 한 번에 2MB 를 푼다. 모델이 Jobs 를 부를 때마다.
-     */
-    if (this.푼것 && this.푼것.판 === this.판) return this.푼것.글;
-    const 다 = Buffer.concat(this.조각들);
-    if (this.인코딩) {
-      try {
-        const 글 = new TextDecoder(this.인코딩, { fatal: false }).decode(다);
-        this.푼것 = { 판: this.판, 글 };
-        return 글;
-      } catch { /* 이 Node 가 모르는 이름이면 아래로 내려가 다시 잰다 */ }
-    }
-    const 콘솔 = consoleCodepage() === 65001 ? 'utf-8' : null;
-    try {
-      const r = decodeBytes(다, { fallback: 콘솔 });
-      // 처음 한 번만 못 박는다. 아직 아무것도 안 쌓였을 때 정하면
-      // 표본이 너무 적어 엉뚱하게 잡히므로, 실제로 글이 나온 뒤에 정한다.
-      if (r.text) this.인코딩 = r.encoding;
-      this.푼것 = { 판: this.판, 글: r.text };
-      return r.text;
-    } catch { return 다.toString('utf8'); }
-  }
-
-  /**
-   * 지난번 읽은 뒤로 새로 나온 것만. 처음부터를 주면 통째로.
-   *
-   * `앞잘림` 은 **지금 건네는 이 글**에 대한 말이다. 묻는 방식에 따라 답이 다르다.
-   *
-   *   통째로 —  '이 일감은 앞을 버린 적이 있다.' 지금 주는 것이 처음부터가
-   *             아니라는 뜻이라, 버린 적이 있는 한 계속 사실이다.
-   *   새것만 —  '지금 주는 이 토막 **앞에 구멍이 있다.**' 버린 직후 한 번만
-   *             사실이고, 그 뒤에 나온 몇 줄은 멀쩡하다.
-   *
-   * 이 둘을 한 칸으로 합쳐 뒀더니, 한 번 넘친 일감은 **그 뒤로 영원히**
-   * "앞부분이 잘렸습니다" 를 달고 나왔다. 모델은 제가 받은 글에 앞이 빠졌다고
-   * 믿고 처음부터 다시 읽으러 가는데 — 로컬 모델에서 왕복 하나가 20~40초다 —
-   * 그렇게 받아 온 것에도 똑같이 그 말이 붙어 있다. 맴돌기 딱 좋은 자리였다.
-   * test/jobs.test.js 의 '온전한 새 출력에 잘렸다고 안 한다' 가 여기를 지킨다.
-   */
-  읽기({ 처음부터 = false } = {}) {
-    const 글 = this.전체글();
-    const 새것 = 처음부터 ? 글 : 글.slice(Math.min(this.읽은글자, 글.length));
-    this.읽은글자 = 글.length;
-    const 잘림 = 처음부터 ? this.앞잘림 : this.막버렸다;
-    // 통째로 읽어 갔으면 지금 들고 있는 것을 다 본 것이라, '바로 앞에 구멍이
-    // 있다' 는 경고도 같이 내린다. 다음에 또 버리면 그때 다시 선다.
-    this.막버렸다 = false;
-    return { 글: 새것, 앞잘림: 잘림 };
-  }
-
-  산햇수() { return Math.round((Date.now() - this.띄운때) / 1000); }
-}
-
-const 일감들 = new Map();
-let 다음번호 = 1;
-// 자리를 위해 지운 개수. **지웠으면 지웠다고 말하려고** 센다 —
-// 안 말하면 모델은 목록에 보이는 것이 전부인 줄 안다.
-let 치운것 = 0;
-
-/**
- * 끝난 일감이 쌓이는 것을 막는다.
- *
- * 오래된 것부터 버린다. 번호가 곧 띄운 순서라 그대로 쓴다. 방금 띄운 것을
- * 못 읽게 되면 안 되므로 **최근 쪽을 남긴다.**
- */
-function 끝난것치우기() {
-  const 끝난것 = [...일감들.values()].filter((j) => j.상태 !== '도는중').sort((a, b) => a.번호 - b.번호);
-  if (끝난것.length <= 끝난것상한) return;
-  for (const j of 끝난것.slice(0, 끝난것.length - 끝난것상한)) {
-    // 들고 있던 것도 같이 놓는다. 항목만 지우고 조각들을 안 놓으면 아무것도 안 준다.
-    j.조각들 = [];
-    j.푼것 = null;
-    일감들.delete(j.번호);
-    치운것++;
-  }
-}
-
-/**
- * 명령을 뒤에서 띄운다.
- *
- * @param 기다림 띄운 뒤 몇 ms 를 지켜보나. 그 사이에 죽으면 **띄우기 실패**로
- *   돌려준다. 포트가 이미 물려 있는 경우가 제일 흔한데, 그때 "떴습니다" 라고
- *   답하면 모델은 다음 단계로 넘어가고 사용자는 안 뜬 서버를 찾아다닌다.
- */
-export async function 띄우기(명령, { cwd, 설명 = null, 기다림 = 1500 } = {}) {
-  const 도는것 = [...일감들.values()].filter((j) => j.상태 === '도는중');
-  if (도는것.length >= 최대일감) {
-    return { error: `뒤에서 도는 명령이 이미 ${도는것.length}개입니다. Jobs 로 안 쓰는 것을 끝내고 다시 하세요.` };
-  }
-
-  const j = new 일감(다음번호++, 명령, 설명);
-  const shell = 셸명령(명령);
-  let kid;
-  try {
-    kid = spawn(shell.file, shell.args, {
-      ...띄우기옵션(cwd),
-      windowsVerbatimArguments: shell.verbatim,
-    });
-  } catch (err) {
-    return { error: `띄우지 못했습니다: ${String(err?.message ?? err)}` };
-  }
-  j.kid = kid;
-  일감들.set(j.번호, j);
-
-  kid.stdout?.on('data', (b) => j.담기(b));
-  kid.stderr?.on('data', (b) => j.담기(b));
-  kid.on('error', (err) => { j.담기(Buffer.from(`\n[띄우기 실패: ${err.message}]\n`)); j.상태 = '끝남'; j.종료코드 = -1; });
-  kid.on('close', (code, sig) => {
-    if (j.상태 === '죽임') return;
-    j.상태 = '끝남';
-    j.종료코드 = sig ? null : code;
-    j.시그널 = sig ?? null;
-    // 끝난 것이 쌓이지 않게. 도는 것은 최대일감 이 따로 막는다.
-    끝난것치우기();
-  });
-
-  // 뜨자마자 죽는지 잠깐 지켜본다. 그 몇 줄이 대부분의 답이다.
-  await 잠깐(j, 기다림);
-
-  const 본것 = j.읽기({ 처음부터: true });
-  if (j.상태 !== '도는중') {
-    일감들.delete(j.번호);
-    return {
-      떴나: false,
-      번호: j.번호,
-      종료코드: j.종료코드,
-      시그널: j.시그널,
-      출력: 본것.글,
-    };
-  }
-  return { 떴나: true, 번호: j.번호, 출력: 본것.글 };
-}
-
-function 잠깐(j, ms) {
-  return new Promise((끝) => {
-    if (ms <= 0) return 끝();
-    let 됐나 = false;
-    const 마치기 = () => { if (됐나) return; 됐나 = true; clearTimeout(시계); 끝(); };
-    const 시계 = setTimeout(마치기, ms);
-    시계.unref?.();
-    j.kid?.once('close', 마치기);
-    j.kid?.once('error', 마치기);
-  });
-}
-
-export function 목록() {
-  return [...일감들.values()].map((j) => ({
-    번호: j.번호,
-    명령: j.명령,
-    설명: j.설명,
-    상태: j.상태,
-    종료코드: j.종료코드,
-    시그널: j.시그널,
-    초: j.산햇수(),
-    안읽은글자: Math.max(0, j.전체글().length - j.읽은글자),
-  }));
-}
-
-export function 하나(번호) { return 일감들.get(Number(번호)) ?? null; }
-
-export function 읽기(번호, opts) {
-  const j = 하나(번호);
-  if (!j) return null;
-  const r = j.읽기(opts);
-  return { ...r, 상태: j.상태, 종료코드: j.종료코드, 시그널: j.시그널, 명령: j.명령, 초: j.산햇수() };
-}
-
-/**
- * 하나를 끝낸다.
- *
- * **기다렸다가 거둔다.** 죽이자마자 파이프를 끊으면 그 순간 아직 안 읽힌 것이
- * 통째로 사라지는데, 하필 그게 제일 중요한 몇 줄이다 — 서버가 뻗으면서 남긴
- * 스택 트레이스, 왜 죽었는지 적은 마지막 말. `마지막 출력:` 이라고 적어 놓고
- * 정작 마지막을 안 주면 안 적느니만 못하다.
- */
-export async function 끝내기(번호) {
-  const j = 하나(번호);
-  if (!j) return null;
-  if (j.상태 !== '도는중') { 일감들.delete(j.번호); return { 이미: true, 명령: j.명령 }; }
-  j.상태 = '죽임';
-  /*
-   * 사람이 시킨 자리라 넉넉히 기다린다.
-   *
-   * 검사를 통째로 돌릴 때처럼 컴퓨터가 바쁘면 taskkill 이 1.5초를 넘긴다.
-   * 그때 잘린 채로 넘어가면 손자가 남는데, 몇백 ms 빨리 돌아오는 것보다
-   * 안 죽은 서버 하나가 훨씬 비싸다.
-   */
-  const 넉넉히 = 6000;
-  나무죽이기(j.kid, { 파이프끊기: false, 상한: 넉넉히 });
-  await 죽는말기다리기(j.kid, 죽는말기다림);
-  /*
-   * 아직 살아 있으면 여기서 끊는다.
-   *
-   * 곧 목록에서 지울 참인데, 지우고 나면 이놈을 가리킬 방법이 없다. 안 죽은
-   * 채로 지우면 영영 못 찾는 프로세스가 하나 남는다 — 이 기능이 없애려던
-   * 바로 그 상태다. 유닉스에서 SIGTERM 을 안 듣는 놈이 여기로 온다.
-   * 윈도우에서는 나무를 다 못 훑어 뿌리를 살려 둔 경우가 여기로 온다.
-   *
-   * **뿌리살리기를 끈다.** 이걸 안 끄면 윈도우에서 taskkill 이 또 잘렸을 때
-   * 나무죽이기 가 kid.kill() 에 닿지도 못하고 그냥 돌아온다 — 「곧장」 이
-   * 윈도우에서는 아무 뜻이 없었다는 말이다. 여기는 마지막 자리라 뿌리라도
-   * 죽여야 한다. (모두끝내기 는 이미 그렇게 하고 있었다.)
-   */
-  if (아직사나(j.kid)) {
-    나무죽이기(j.kid, { 파이프끊기: false, 곧장: true, 상한: 넉넉히, 뿌리살리기: false });
-    /*
-     * 죽인 **직후에 살았나 물으면 안 된다.**
-     *
-     * 아직사나() 는 exitCode·signalCode 를 보는데, 그 값은 Node 가 종료를
-     * 실제로 **관찰한 뒤에** 채워진다. 동기 taskkill 이 돌아온 순간에는 아직
-     * 비어 있을 수 있다 — 그러면 멀쩡히 죽은 것을 「안 죽었다」 로 읽는다.
-     *
-     * 검사를 통째로 돌릴 때 이걸로 한 번 헛짚었다. 혼자 돌리면 초록이고
-     * 전체에서만 빨개졌다 — 컴퓨터가 바쁘면 관찰이 늦기 때문이다.
-     * 그러니 한 번 더 기다렸다가 묻는다.
-     */
-    await 죽는말기다리기(j.kid, 죽는말기다림);
-  }
-  파이프끊기(j.kid);
-  const 남은 = j.읽기({});
-  /*
-   * ★ 그러고도 안 죽었으면 **그렇다고 말한다.**
-   *
-   * 전에는 성패를 안 보고 늘 성공을 돌려줬다. 그러면 모델과 사람은 「끝냈습니다」
-   * 를 받는데 서버는 살아서 포트를 물고 있고, 목록에서도 지워져 다시 부를
-   * 방법이 없다. 이 파일 머리말이 스스로 적어 둔 「안 죽은 채로 지우면 영영
-   * 못 찾는 프로세스가 하나 남는다」 가 그대로 성립하고 있었다.
-   *
-   * 안 죽었으면 목록에 남긴다. 그래야 사람이 한 번 더 시킬 수 있다.
-   */
-  if (아직사나(j.kid)) {
-    j.상태 = '도는중';   // 지우지 않는다 — 다시 시킬 수 있어야 한다
-    return { 이미: false, 안죽음: true, 명령: j.명령, 초: j.산햇수(), 남은: 남은.글 };
-  }
-  일감들.delete(j.번호);
-  return { 이미: false, 명령: j.명령, 초: j.산햇수(), 남은: 남은.글 };
-}
-
-/**
- * 전부 끝낸다. deel 을 닫을 때 부른다.
- *
- * 이걸 빠뜨리면 사람이 안 띄운 서버가 계속 돈다. 다음에 켜서 `npm run dev` 를
- * 하면 "포트가 이미 쓰이는 중" 이 뜨는데, 무엇이 물고 있는지 알 길이 없다.
- */
-export function 모두끝내기() {
-  const n = [...일감들.values()].filter((j) => j.상태 === '도는중').length;
-  for (const j of 일감들.values()) {
-    if (j.상태 !== '도는중') continue;
-    j.상태 = '죽임';
-    /*
-     * 여기는 프로그램이 끝나는 길이라 **다시 올 기회가 없다.** 한 번 짧게
-     * 훑어 보고, 잘렸으면 한 번 더 길게 훑는다. 그러고도 안 되면 뿌리라도
-     * 죽인다 — 아무것도 안 죽이는 것보다 낫다.
-     */
-    if (!나무죽이기(j.kid)) 나무죽이기(j.kid, { 상한: 4000, 뿌리살리기: false });
-  }
-  일감들.clear();
-  return n;
-}
-
-/** 검사에서 판을 깨끗이 하려고 쓴다. */
-export function 비우기() { 모두끝내기(); 다음번호 = 1; 치운것 = 0; }
-
-// 어떤 길로 끝나든 남기지 않는다. repl·oneshot 이 부르는 것과 겹쳐도 무해하다.
-process.once('exit', () => { try { 모두끝내기(); } catch { /* 끝나는 중이라 할 수 있는 게 없다 */ } });
-
-/*
- * ── 도구 ──────────────────────────────────────────────────────────────
- *
- * 왜 Bash 안에 인자로 안 넣고 도구를 따로 두나:
- *   Bash 에 `job`·`kill` 같은 인자를 얹으면 스키마가 "명령을 실행한다" 와
- *   "일감을 본다" 두 가지를 한꺼번에 말하게 된다. 작은 모델은 그 자리에서
- *   command 없이 Bash 를 부르거나, 반대로 읽으려다 명령을 또 실행한다.
- *   하는 일이 다르면 도구를 나누는 편이 결국 싸다. 이 스키마는 아주 작다.
- */
-/*
- * 인자 이름 받이 — 한글 이름과 영문 이름을 **둘 다** 받는다.
- *
- * 모델은 한글 인자 이름을 자주 영어로 바꿔 보낸다. 추정이 아니라 이 저장소가
- * 겪은 일이다 — Task 는 이미 `목적 ?? purpose`, `할일 ?? task`, `모드 ?? mode`
- * 로 둘 다 받고 있다(agent/loop.js). 누군가 겪고 달아 둔 것이다.
- *
- * 여기에는 그게 없어서 `Jobs({job: 1, stop: true})` 가 **목록**을 돌려줬다.
- * 모델은 끄라고 시켰고 성공처럼 보이는 답을 받았는데 서버는 그대로 포트를
- * 문다 — 사람은 원인을 못 찾는다. 이 도구에서 제일 나쁜 실패다.
- *
- * 이름을 영문으로 **바꾸는** 것으로는 안 된다. 그러면 한글로 보내는 쪽이 같은
- * 구멍에 빠지고, 안 맞춘 이름(id·number)은 여전히 샌다. 둘 다 받고,
- * 못 알아들은 것은 못 알아들었다고 말한다.
- *
- * **목록은 여기 한 벌뿐이다.** 화면 이름표도 이걸 쓴다(repl.js·oneshot.js).
- * 두 벌이 되면 한쪽만 고쳐지고, 그때부터 화면과 실제가 어긋난다.
- */
-const 인자이름 = {
-  번호: ['job', 'job_id', 'jobId', 'id', 'number', '번호'],
-  끝내기: ['stop', 'kill', '끝내기'],
-  처음부터: ['from_start', 'fromStart', 'full', '처음부터'],
-};
-const 아는이름 = new Set(Object.values(인자이름).flat());
-
-/**
- * 준 인자에서 아는 것만 골라낸다.
- *
- * @returns {{번호: number|null, 끝내기: boolean, 처음부터: boolean, 준것: string[], 모르는것: string[]}}
- */
-export function 일감인자(args) {
-  const 준것 = Object.keys(args ?? {});
-  const 하나씩 = (이름) => {
-    for (const n of 인자이름[이름]) if (args?.[n] != null) return args[n];
-    return null;
-  };
-  const 날번호 = 하나씩('번호');
-  return {
-    번호: 날번호 == null ? null : Number(날번호),
-    끝내기: !!하나씩('끝내기'),
-    처음부터: !!하나씩('처음부터'),
-    준것,
-    모르는것: 준것.filter((k) => !아는이름.has(k)),
-  };
-}
-
-/**
- * 모델에게 건넬 만큼만 남긴다 — **뒤**를 남긴다.
- *
- * 오래 도는 것에서 사람이 찾는 것은 언제나 방금 나온 쪽이다. 앞을 남기면
- * 몇 시간 전 기동 로그를 주게 된다.
- *
- * 줄였으면 줄였다고 적는다. 안 적으면 모델은 그게 전부인 줄 알고,
- * 안 보이는 줄에 답이 있을 때 엉뚱한 결론으로 간다.
- */
-function 뒤만(글, 한도 = 건넬상한) {
-  const s = String(글 ?? '');
-  if (s.length <= 한도) return { 글: s, 줄임: false };
-  return {
-    글: `(앞 ${s.length - 한도}자는 길어서 줄였습니다 — 뒤쪽만 보여 줍니다)\n${s.slice(-한도)}`,
-    줄임: true,
-  };
-}
-
-/** 끝난 일감을 한 마디로. 시그널로 죽으면 종료코드가 null 이라 따로 말한다. */
-function 끝난말(r) {
-  if (r.시그널) return `${r.시그널} 로 죽음`;
-  return r.종료코드 === 0 ? '끝남' : `종료코드 ${r.종료코드}`;
-}
-
-export const JOBS_TOOL = {
-  schema: {
-    name: 'Jobs',
-    description: '뒤에서 도는 명령(Bash 의 background)을 보고·읽고·끝낸다.'
-      + ' job 없이 부르면 목록. job 을 주면 그동안 새로 나온 출력.'
-      + ' 서버를 띄웠으면 일이 끝날 때 반드시 stop 으로 정리해라.',
-    parameters: {
-      type: 'object',
-      properties: {
-        job: { type: 'number', description: '볼 일감 번호. 없으면 목록' },
-        stop: { type: 'boolean', description: 'true 면 그 일감을 끝낸다' },
-        from_start: { type: 'boolean', description: 'true 면 처음부터 다시 읽는다' },
-      },
-      required: [],
-    },
-  },
-  // 끝내기 는 죽는 순간 뱉은 말을 기다렸다 거두므로 비동기다 (끝내기 머리말 참고).
-  // runTool 이 await 로 부르니 도구가 비동기여도 된다 (tools/index.js).
-  async run(args) {
-    const 받은것 = 일감인자(args);
-    /*
-     * 준 것이 있는데 **하나도** 못 알아들었으면 목록으로 얼버무리면 안 된다.
-     *
-     * 목록을 돌려주면 그것도 성공한 답으로 보인다. 끄라고 시킨 모델은
-     * 껐다고 여기고 넘어가는데 서버는 그대로 돈다. 무엇을 받는지 알려 줘야
-     * 다음 걸음에서 고쳐 부른다.
-     *
-     * 인자가 **아예 없는** 것은 그냥 '목록 보기' 다 — 그건 오류가 아니다.
-     */
-    if (받은것.준것.length && 받은것.모르는것.length === 받은것.준것.length) {
-      return {
-        error: `모르는 인자입니다: ${받은것.모르는것.join(', ')}.`
-          + ' Jobs 는 번호(job) · 끝내기(stop) · 처음부터(from_start) 만 받습니다.'
-          + ' 번호 없이 부르면 목록입니다.',
-      };
-    }
-    const 번호 = 받은것.번호;
-    // 숫자가 아닌 것을 받으면 NaN 이 되고, 그대로 두면 `NaN번 일감이 없습니다`
-    // 라는 말이 모델에게 나간다. 무엇이 잘못됐는지 안 알려 주는 오류다.
-    if (번호 != null && !Number.isFinite(번호)) {
-      return { error: `번호는 숫자여야 합니다 (받은 것: ${JSON.stringify(args?.번호)}). 번호 없이 Jobs 를 불러 목록을 보세요.` };
-    }
-
-    if (번호 == null) {
-      /*
-       * 번호 없이 "끝내라" 고 하면 목록으로 얼버무리면 안 된다.
-       *
-       * 목록을 돌려주면 그건 성공한 답으로 보인다. 모델은 정리한 줄 알고
-       * "서버를 껐습니다" 라고 말하는데 서버는 그대로 돌고 있다.
-       * 도구가 시킨 일을 안 했으면 안 했다고 말해야 그 다음이 이어진다.
-       */
-      if (받은것.끝내기) {
-        const 도는것 = 목록().filter((j) => j.상태 === '도는중');
-        return {
-          error: '끝낼 일감 번호를 주세요. 번호 없이 끝내기만 주면 아무것도 안 끝냅니다.'
-            + (도는것.length
-              ? ` 지금 도는 것: ${도는것.map((j) => `${j.번호}번(${j.명령})`).join(' · ')}`
-              : ' 지금 도는 것이 없습니다.'),
-        };
-      }
-      const ls = 목록();
-      if (!ls.length) return { content: '뒤에서 도는 명령이 없습니다.', summary: 세말('count', 0) };
-      const 줄들 = ls.map((j) => {
-        const 상 = j.상태 === '도는중' ? `도는중 ${j.초}초` : j.시그널 ? `${j.시그널} 로 죽음` : `끝남 (종료코드 ${j.종료코드})`;
-        const 새것 = j.안읽은글자 ? ` · 안 읽은 출력 ${j.안읽은글자}자` : '';
-        return `  ${j.번호}. ${j.명령}  — ${상}${새것}`;
-      });
-      /*
-       * 자리를 위해 지운 것이 있으면 말한다.
-       *
-       * 안 말하면 모델은 여기 보이는 것이 이 세션에서 띄운 전부인 줄 안다.
-       * 아까 띄운 3번을 찾다가 없으니 "안 띄웠나 보다" 하고 다시 띄운다 —
-       * 그러면 포트가 물려서 안 뜨고, 왜 안 되는지도 모른다.
-       */
-      if (치운것) 줄들.push(`  (오래된 것 ${치운것}개는 자리를 위해 지웠습니다)`);
-      return { content: 줄들.join('\n'), summary: 세말('count', ls.length), 일감수: ls.length };
-    }
-
-    if (받은것.끝내기) {
-      const r = await 끝내기(번호);
-      if (!r) return { error: `${번호}번 일감이 없습니다. 번호 없이 Jobs 를 불러 목록을 보세요.` };
-      if (r.이미) return { content: `${번호}번은 이미 끝나 있었습니다: ${r.명령}`, summary: 말('sum.jobEndedAlready') };
-      /*
-       * ★ 안 죽었으면 「끝냈습니다」 라고 하지 않는다.
-       *
-       * 여기서 거짓말하면 모델은 다음 단계로 가고 사람은 포트를 문 채로 남은
-       * 서버를 못 찾는다 — 이 기능이 없애려던 바로 그 상태다. 목록에도
-       * 남겨 뒀으니 한 번 더 시킬 수 있다고 알려 준다.
-       */
-      if (r.안죽음) {
-        return {
-          error: `${번호}번이 안 끝났습니다 (${r.초}초 돌았습니다): ${r.명령}`
-            + '\n죽이라고 시켰는데 아직 살아 있습니다. 목록에 그대로 두었으니 한 번 더 시켜 보세요.'
-            + (r.남은 ? `\n\n마지막 출력:\n${뒤만(r.남은, 2000).글}` : ''),
-          summary: 말('sum.jobNotStopped'),
-        };
-      }
-      return {
-        content: `${번호}번을 끝냈습니다 (${r.초}초 돌았습니다): ${r.명령}`
-          + (r.남은 ? `\n\n마지막 출력:\n${뒤만(r.남은, 2000).글}` : ''),
-        summary: 이어(말('sum.jobStopped'), 말('unit.sec', { n: r.초 })),
-      };
-    }
-
-    const r = 읽기(번호, { 처음부터: 받은것.처음부터 });
-    if (!r) return { error: `${번호}번 일감이 없습니다. 번호 없이 Jobs 를 불러 목록을 보세요.` };
-    const 머리 = r.상태 === '도는중'
-      ? `${번호}번 (도는중 ${r.초}초): ${r.명령}`
-      : `${번호}번 (${r.시그널 ? `${r.시그널} 로 죽음` : `끝남 · 종료코드 ${r.종료코드}`}): ${r.명령}`;
-    // 새 출력이 없다는 것도 사실이다. 빈 글을 주면 모델은 못 읽은 줄 안다.
-    const 잘라낸 = 뒤만(r.글);
-    const 몸 = r.글.trim()
-      ? (r.앞잘림 ? '(앞부분은 너무 길어 잘렸습니다 — 뒤쪽만 남았습니다)\n' : '') + 잘라낸.글
-      : '(지난번 읽은 뒤로 새 출력이 없습니다)';
-    return {
-      content: `${머리}\n\n${몸}`,
-      summary: (r.상태 === '도는중' ? 이어(말('sum.jobRunning'), 말('unit.sec', { n: r.초 })) : 끝난말(r))
-        + (잘라낸.줄임 ? ' · 일부만' : ''),
-      // 끝난 일감이 종료코드 0 이 아니면 실패로 물들인다 — Bash 와 같은 규칙이다.
-      // 시그널로 죽은 것도 실패다 — 그때 종료코드는 null 이라 !== 0 으로 잡힌다.
-      failed: r.상태 !== '도는중' && r.종료코드 !== 0,
-    };
-  },
-};
+/*
+ * 뒤에서 계속 도는 명령.
+ *
+ * 왜 필요한가:
+ *   Bash 는 명령이 **끝나야** 결과를 준다. 그래서 끝나지 않는 것을 못 돌린다 —
+ *   `npm run dev`, `python -m http.server`, `vite`, `npm run watch` 가 전부 그렇다.
+ *   전에는 이걸 시키면 120초를 기다렸다가 시간 초과로 죽였다. 화면에는
+ *   `시간 초과로 중단됨` 만 남는다. 모델은 서버를 못 띄운 것으로 알고 포기하거나,
+ *   더 나쁘게는 timeout 을 늘려서 다시 부른다 — 그러면 그 턴이 통째로 멈춘다.
+ *
+ *   만든 것을 **띄워서 확인**하는 것이 바이브코딩의 마지막 한 칸이다.
+ *   Verify 가 "문법은 맞다" 까지 봐 주지만, 진짜로 뜨는지는 띄워 봐야 안다.
+ *
+ * 무엇을 하나:
+ *   명령을 띄우고 **바로 돌아온다.** 출력은 여기에 쌓아 두고, 모델이 Jobs 로
+ *   읽어 간다. 뜨자마자 죽는 경우(포트가 이미 물려 있다 등)가 흔해서, 띄운 직후
+ *   잠깐 기다렸다가 그 사이 나온 것을 같이 준다 — 그 몇 줄이 대부분의 답이다.
+ *
+ * 지키는 선:
+ *   · 안전 검사는 Bash 와 **똑같이** 거친다. 여기가 뒷문이 되면 안 된다.
+ *     (checkCommand·checkPaths 는 부르는 쪽에서 이미 거친다 — index.js 참고)
+ *   · deel 이 끝나면 전부 죽인다. 남겨 두면 사람이 모르는 프로세스가 계속 돈다.
+ *     그건 '내가 안 띄운 서버가 포트를 물고 있는' 상태고, 원인을 못 찾는다.
+ *   · 출력은 상한이 있다. watch 하나가 몇 시간 돌면 몇 GB 가 된다.
+ */
+import { spawn, execFileSync } from 'node:child_process';
+import { decode as decodeBytes, consoleCodepage } from './encoding.js';
+import { 셸명령 } from './shell.js';
+import { 열쇠뺀환경 } from '../backend/mcp.js';
+import { 말, 세말 } from '../i18n/index.js';
+
+/* 결과 한 줄을 잇는다 — 빈 조각은 버린다(tools/index.js 의 이어 와 같은 것). */
+const 이어 = (...조각들) => 조각들.filter((x) => x != null && String(x) !== '').join(' · ');
+
+// 한 일감이 **들고 있을** 출력 상한. 넘으면 앞을 버리고 뒤를 남긴다 —
+// 오래 도는 것에서 필요한 건 언제나 **방금** 나온 쪽이다.
+const 출력상한 = 256 * 1024;
+/*
+ * 한 번에 **모델에게 건넬** 상한. 위엣것과 다른 값이어야 한다.
+ *
+ * 둘을 같은 값으로 두면 watch 하나가 넘칠 때마다 Jobs 읽기 한 번이 256KB 를
+ * 창에 쏟는다. 8k 모델이면 그 한 번으로 창이 끝나고, 큰 창에서도 대화가
+ * 통째로 밀려 나간다. 게다가 넘친 직후에는 커서가 0 으로 돌아가 있어서
+ * (담기 참고) '새것만' 달라고 해도 통째로 온다 — 그러니 여기가 막혀 있어야 한다.
+ *
+ * Bash 의 background 쪽은 처음부터 4,000자로 줄이고 있었는데 이 길만 뚫려 있었다.
+ */
+const 건넬상한 = 4000;
+// 동시에 띄워 둘 수 있는 개수. 이보다 많아지면 사람이 못 따라간다.
+export const 최대일감 = 8;
+/*
+ * **끝난** 일감을 몇 개까지 들고 있나.
+ *
+ * 바로 지우면 안 된다 — 마지막 출력을 읽으라고 남겨 두는 것이다. 그런데
+ * 안 지우면 짧은 명령 서른 개에 항목 서른 개가 쌓이고, 하나가 최대 256KB 를
+ * 들고 있으니 몇 MB 가 된다. 목록을 볼 때마다 그걸 전부 다시 푼다.
+ *
+ * 그래서 최근 것만 남기고 오래된 것부터 버린다. 도는 것은 여기 안 센다 —
+ * 그건 최대일감 이 따로 막는다.
+ */
+const 끝난것상한 = 8;
+/*
+ * 죽인 뒤 남은 말을 얼마나 기다리나.
+ *
+ * 유닉스 쪽 SIGKILL 올려치기(800ms)보다 짧게 잡는다. 여기서 먼저 깨어나
+ * '아직 사나' 를 보고, 살아 있으면 그 자리에서 곧장 끊기 때문이다.
+ */
+const 죽는말기다림 = 700;
+
+// 명령을 셸에 넘기는 방법은 tools/shell.js 한 군데서 정한다. Bash 도구와 같은 값이어야
+// 한다 — 두 벌이 되면 한쪽만 고쳐지고, 윈도우에서 따옴표가 든 명령이 조용히 뭉개진다.
+export { 셸명령 };
+
+/**
+ * 어떻게 띄우나 — spawn 에 넘길 것들.
+ *
+ * `detached` 가 이 함수가 있는 이유다. 윈도우는 `taskkill /t` 가 프로세스
+ * 나무를 훑어 주지만 유닉스에는 그런 것이 없다. **띄울 때 무리(process group)를
+ * 만들어 두지 않으면 나중에 손자를 가리킬 방법이 아예 없다.**
+ *
+ * `npm run dev` 는 npm → node → vite 로 내려가고, 포트를 무는 것은 맨 아래다.
+ * sh 에 SIGTERM 만 보내면 그 아래가 그대로 남아서 — 사람 눈에 안 보이는 채로 —
+ * 계속 돈다. 나중에 고칠 수 없는 종류라 띄우는 순간에 정해 둔다.
+ *
+ * 윈도우에서는 반대로 무리를 안 만든다. detached 는 거기서 새 콘솔 창을
+ * 띄우는 쪽으로 작동해서, 조용히 돌아야 할 것이 화면에 튀어나온다.
+ */
+export function 띄우기옵션(cwd) {
+  const win = process.platform === 'win32';
+  return {
+    cwd,
+    // 열쇠만 빼고 나머지는 그대로 물려준다 (backend/mcp.js 열쇠뺀환경 머리말).
+    env: 열쇠뺀환경(),
+    windowsHide: true,
+    detached: !win,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  };
+}
+
+/**
+ * 윈도우에서 pid 아래 나무를 통째로 끊는다.
+ *
+ * @returns {boolean} 나무를 **다 훑었나.** false 면 손자가 남아 있을 수 있으니,
+ *   부르는 쪽은 뿌리(cmd.exe)를 죽이지 말고 다시 와야 한다.
+ *
+ * ── 실패 두 가지를 갈라야 한다 ──────────────────────────────────────────
+ *
+ *   · 「그런 프로세스 없다」 — 이미 죽은 것이다. 탈이 아니다.
+ *   · **taskkill 이 제 상한에 걸려 잘렸다** — 나무를 다 못 훑었다.
+ *
+ * 뒤엣것을 앞엣것처럼 넘기고 뿌리를 죽여 버리면 손자가 영영 못 찾는 채로
+ * 남는다. 뿌리가 죽은 뒤에는 `taskkill /pid` 가 「프로세스를 못 찾았습니다」 로
+ * 끝나서 다시 부를 수조차 없다.
+ *
+ * ── 무엇으로 가르나: err.killed 가 아니다 ───────────────────────────────
+ *
+ * 처음에는 `!err?.killed` 로 갈랐다. **그게 늘 참이었다.** 비동기 execFile 의
+ * 콜백은 상한에 걸리면 err.killed 를 true 로 주는데, execFileSync 는 안 준다.
+ * 그래서 「나무를 다 못 훑었다」 가 한 번도 안 나왔고, 뿌리를 살려 두는 분기는
+ * 처음부터 닿지 않는 코드였다 — 이 판의 대표 기능이 통째로 헛돈 셈이다.
+ *
+ * 실제로 재 보고 갈랐다(윈도우 11 · Node 20):
+ *
+ *   상한에 걸림        killed=undefined  signal=SIGTERM  code=ETIMEDOUT  status=null
+ *   없는 pid 를 죽임    killed=undefined  signal=null     code=undefined  status=128
+ *
+ * 갈리는 자리는 **signal 과 code** 다. 아래 검사(test/jobs.test.js 의
+ * '★ taskkill 이 잘린 것과 이미 죽은 것을 가른다')가 이 값을 못박아 둔다.
+ */
+export function 나무끊기(pid, 상한 = 1500) {
+  if (process.platform !== 'win32' || !pid) return true;
+  try {
+    execFileSync('taskkill', ['/pid', String(pid), '/t', '/f'],
+      { windowsHide: true, stdio: 'ignore', timeout: 상한 });
+    return true;
+  } catch (err) {
+    return !잘렸나(err);
+  }
+}
+
+/** 이 오류가 「상한에 걸려 잘렸다」 인가. 아니면 그냥 0 이 아닌 값으로 끝난 것이다. */
+export function 잘렸나(err) {
+  return err?.code === 'ETIMEDOUT' || err?.signal != null || err?.killed === true;
+}
+
+/**
+ * 유닉스에서 pid 가 이끄는 **무리째** 죽인다.
+ *
+ * 음수 pid 는 '그 무리 전부' 라는 뜻이다 — 띄울 때 detached 로 무리를 만들어
+ * 둔 것과 짝이다. 이걸 안 하고 kid.kill() 만 하면 sh 나 npm 만 죽고 그 아래
+ * vite 가 포트를 문 채로 남는다. 무엇이 물고 있는지 못 찾는, 제일 나쁜 자리다.
+ *
+ * 먼저 곱게 말하고(TERM), 안 들으면 끊는다(KILL). 곧장 KILL 로 가면 dev 서버가
+ * 임시 파일이나 소켓을 치울 틈이 없다.
+ *
+ * **띄울 때 무리를 안 만들었으면 여기서 할 수 있는 것이 없다.** 나중에 무리를
+ * 만들어 줄 방법은 없다 — 그래서 이 판단이 띄우는 자리와 짝을 이뤄야 한다.
+ * (Bash 도구가 한동안 이 짝을 안 맞춰서, 윈도우만 고쳐지고 유닉스는 그대로였다.)
+ */
+/**
+ * 그 무리가 아직 살아 있나. 죽었으면 false.
+ *
+ * 무리로 못 물어보면 **그 하나에게** 물어본다 — 위 신호주기() 와 같은 까닭이다.
+ * 무리가 없는 판에서 「무리가 없다 = 다 죽었다」 로 읽으면, 살아 있는 자식을
+ * 죽은 것으로 세고 그냥 지나간다.
+ */
+function 무리살아있나(pid) {
+  try { process.kill(-pid, 0); return true; } catch { /* 무리가 없다 */ }
+  try { process.kill(pid, 0); return true; } catch { return false; }
+}
+
+/**
+ * 동기로 잠깐 쉰다.
+ *
+ * `setTimeout` 이 아니라 이걸 쓰는 까닭은 아래 무리끊기 머리말에 있다 —
+ * 이 자리는 프로그램이 끝나는 길에서도 지나가고, 그 자리에서는 비동기
+ * 일감이 하나도 안 돈다.
+ */
+function 동기로쉬기(ms) {
+  try { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); }
+  catch { /* SharedArrayBuffer 가 막힌 판이면 그냥 지나간다 */ }
+}
+
+/**
+ * 신호를 보낸다. **무리째 못 보내면 그 하나에게라도 보낸다.**
+ *
+ * ── 왜 두 번 시도하나 ──────────────────────────────────────────────────
+ *
+ * `-pid` 는 「그 무리 전부」 라는 뜻이고, 그 무리는 띄울 때 `detached` 로
+ * 만들어 둔 것이다. 그런데 그게 늘 있으리라 믿으면 안 된다 —
+ *
+ *   · `detached` 가 안 먹은 판 (컨테이너 안, 이상한 실행 환경)
+ *   · 이미 무리 우두머리가 죽고 남은 놈이 딴 무리로 넘어간 자리
+ *
+ * 이런 자리에서 `kill(-pid, …)` 는 ESRCH 로 튕긴다. 그러면 여태는 그
+ * 자리에서 **아무것도 안 하고 돌아갔다.** 무리로 못 보냈다는 것이 「보낼
+ * 것이 없다」 는 뜻은 아닌데, 그렇게 다뤘다. 무리로 못 보내면 적어도 우리가
+ * 아는 그 하나(자식)에게는 보낸다 — 그게 손자를 못 잡더라도, 아무것도 안
+ * 하는 것보다는 낫다.
+ *
+ * @returns {boolean} 하나라도 닿았으면 true
+ */
+function 신호주기(pid, 신호) {
+  let 닿았나 = false;
+  try { process.kill(-pid, 신호); 닿았나 = true; } catch { /* 무리가 없다 */ }
+  if (!닿았나) {
+    try { process.kill(pid, 신호); 닿았나 = true; } catch { /* 그마저 죽었다 */ }
+  }
+  return 닿았나;
+}
+
+export function 무리끊기(pid, { 곧장 = false, 늦게 = 800 } = {}) {
+  if (process.platform === 'win32' || !pid) return;
+  if (곧장) {
+    신호주기(pid, 'SIGKILL');
+    return;
+  }
+  신호주기(pid, 'SIGTERM');
+
+  /*
+   * ── 올려치기를 **동기로** 한다 ────────────────────────────────────────
+   *
+   * 여기가 `setTimeout(…, 늦게).unref()` 였다. 두 가지가 어긋났다.
+   *
+   *   1. `unref()` 한 타이머는 **프로세스를 안 붙잡는다.** 시간 초과로
+   *      끊고 곧바로 끝나는 길에서는 그 타이머가 아예 안 뜬다. 즉 SIGTERM
+   *      을 무시하는 손자(제 신호 처리기를 단 dev 서버·watch 프로세스)는
+   *      그대로 살아남는다. 「죽이라고 말은 했는데 안 죽는」 자리다.
+   *   2. 부르는 쪽은 이 함수가 **돌아오면 끝난 줄로 안다.** 실제로는 아직
+   *      TERM 만 보낸 상태라, 바로 뒤에서 「진짜 멈췄나」 를 보면 살아 있다.
+   *      이 비대칭이 윈도우와 유닉스 사이에도 있었다 — 윈도우 쪽은
+   *      taskkill 을 동기로 기다린다(나무죽이기 머리말).
+   *
+   * 그래서 곱게 말한 뒤 **짧게 나눠 지켜보다가**, 그래도 살아 있으면 그
+   * 자리에서 끊는다. 얌전히 끝나는 무리는 첫 20ms 에 사라지므로 보통은
+   * 거의 안 기다린다. 안 죽는 놈에게만 `늦게` 만큼 쓴다.
+   */
+  const 조각 = 20;
+  for (let 쓴시간 = 0; 쓴시간 < 늦게; 쓴시간 += 조각) {
+    if (!무리살아있나(pid)) return;
+    동기로쉬기(조각);
+  }
+  /*
+   * 마지막 한 방은 **묻지 않고** 보낸다.
+   *
+   * 여기가 `if (무리살아있나(pid))` 였다. 그 물음은 틀릴 수 있다 — 권한이
+   * 없으면(EPERM) 살아 있는데도 「없다」 가 나오고, 그러면 안 죽이고 지나간다.
+   * 이미 죽은 것에 SIGKILL 을 보내는 값은 예외 하나뿐이고 그건 여기서 삼킨다.
+   * 안 죽은 것을 살려 보내는 값은 포트를 문 프로세스가 남는 것이다. 값이 다르다.
+   */
+  신호주기(pid, 'SIGKILL');
+}
+
+/**
+ * 프로세스 나무를 통째로 끝낸다. 자식만 죽이면 손자가 남아 포트를 계속 문다.
+ *
+ * 윈도우에서 taskkill 을 **기다린다.** 전에는 execFile(비동기)로 불렀는데,
+ * 그러면 두 가지가 조용히 어긋난다.
+ *
+ *   1. 바로 아래 kid.kill() 이 먼저 돌아 cmd 를 죽인다. 나무의 뿌리가 없어진
+ *      뒤에 taskkill 이 뜨므로 손자 — `npm run dev` 의 진짜 서버 — 를 못 찾고,
+ *      그놈은 그대로 남아 포트를 문다. 죽이라고 말은 했는데 안 죽는다.
+ *   2. process 의 'exit' 에서 부를 때는 **아예 안 돈다.** 그 자리에서는
+ *      비동기 일감이 하나도 실행되지 않는다. 끄려고 걸어 둔 마지막 그물이
+ *      정작 제일 흔한 끝맺음(그냥 종료)에서 통째로 비어 있었던 셈이다.
+ *
+ * 그래서 동기로 부른다. 여기서 멈추는 몇십 ms 로 '안 죽은 서버' 를 없앤다.
+ * test/jobs.test.js 의 '프로세스가 진짜 멈춘다' 가 이 자리를 지킨다.
+ */
+function 나무죽이기(kid, { 파이프끊기: 끊을까 = true, 곧장 = false, 상한 = 1500, 뿌리살리기 = true } = {}) {
+  if (!kid) return true;
+  let 나무끊었나 = true;
+  if (process.platform === 'win32' && kid.pid) {
+    /*
+     * 상한은 부르는 쪽이 정한다. 여기는 끝날 때도 지나가는 자리라
+     * (process 'exit'), 일감마다 몇 초씩 기다리면 deel 이 멈춘 것처럼 보인다.
+     * 그래서 기본은 짧다. 사람이 「끝내」 라고 시킨 자리에서는 길게 준다 —
+     * 거기서는 몇백 ms 늦는 것보다 안 죽는 것이 훨씬 나쁘다.
+     */
+    나무끊었나 = 나무끊기(kid.pid, 상한);
+    /*
+     * 나무를 다 못 훑었으면 뿌리를 살려 둔다. 부르는 쪽이 다시 온다.
+     *
+     * 딱 한 자리만 예외다 — 더 이상 다시 올 수 없는 자리(프로그램이 끝나는
+     * 길)에서는 뿌리라도 죽인다. 둘 다 살려 두는 것보다는 낫다.
+     */
+    if (!나무끊었나 && 뿌리살리기) return false;
+  } else if (kid.pid) {
+    무리끊기(kid.pid, { 곧장 });
+  }
+  try { kid.kill(); } catch { /* 이미 죽음 */ }
+  if (끊을까) 파이프끊기(kid);
+  try { kid.unref(); } catch { /* 없으면 그만 */ }
+  return 나무끊었나;
+}
+
+/**
+ * 파이프를 놓는다.
+ *
+ * 아이가 죽어도 stdout·stderr 를 붙들고 있으면 그 손잡이가 이벤트 루프를
+ * 붙잡는다. unref() 는 프로세스 손잡이만 놓지 파이프는 안 놓는다.
+ * 이걸 빠뜨리면 deel 이 할 일을 다 하고도 안 끝난다 — 사람 눈에는 멈춘 것이다.
+ *
+ * 다만 **죽이자마자 끊으면 안 된다.** 그 순간 파이프에는 아직 안 읽힌 것이
+ * 남아 있고, 죽기 직전에 나온 몇 줄이 대개 제일 중요하다(서버가 뻗으며 남긴
+ * 스택 트레이스가 거기 있다). 그래서 끝내기() 는 잠깐 기다렸다가 이걸 부른다.
+ */
+function 파이프끊기(kid) {
+  try { kid?.stdout?.destroy(); } catch { /* 이미 닫힘 */ }
+  try { kid?.stderr?.destroy(); } catch { /* 이미 닫힘 */ }
+}
+
+/** 아직 살아 있나. 종료코드도 시그널도 없으면 안 죽은 것이다. */
+function 아직사나(kid) {
+  return !!kid && kid.exitCode == null && kid.signalCode == null;
+}
+
+/**
+ * 죽인 뒤, 남은 말이 다 나오기를 잠깐 기다린다.
+ *
+ * 'close' 는 프로세스가 끝나고 **파이프까지 다 비워졌을 때** 온다. 그래서
+ * 이걸 기다리면 죽는 순간 뱉은 것까지 손에 들어온다.
+ *
+ * 무한정 기다리지는 않는다 — 안 죽는 놈 하나가 그 턴을 통째로 잡아먹으면
+ * 안 된다. 그리고 여기 시계는 unref 하지 않는다. 이 기다림이 지금 이벤트
+ * 루프가 살아 있을 유일한 이유일 수 있어서, 놓아 버리면 그대로 끝난다.
+ */
+function 죽는말기다리기(kid, ms) {
+  return new Promise((끝) => {
+    if (!kid || ms <= 0) return 끝();
+    let 됐나 = false;
+    const 마치기 = () => { if (됐나) return; 됐나 = true; clearTimeout(시계); 끝(); };
+    const 시계 = setTimeout(마치기, ms);
+    kid.once('close', 마치기);
+    kid.once('error', 마치기);
+  });
+}
+
+class 일감 {
+  constructor(번호, 명령, 설명) {
+    this.번호 = 번호;
+    this.명령 = 명령;
+    this.설명 = 설명 ?? null;
+    this.띄운때 = Date.now();
+    this.상태 = '도는중';       // 도는중 | 끝남 | 죽임
+    this.종료코드 = null;
+    this.시그널 = null;
+    this.조각들 = [];
+    this.바이트 = 0;
+    // 이 일감이 앞을 버린 적이 **있다**. 통째로 달라고 할 때의 사실이라,
+    // 한 번 서면 안 내려간다 — 지금 들고 있는 것이 처음부터가 아니라는 뜻이다.
+    this.앞잘림 = false;
+    // 지난번 읽어 간 뒤로 버렸다. **이번에 건네는 토막**에 대한 사실이라,
+    // 한 번 말하면 내린다. 이 둘을 한 칸으로 합치면 안 된다 (읽기() 참고).
+    this.막버렸다 = false;
+    this.읽은글자 = 0;
+    // 한 번 정하면 안 바꾼다. 바뀌면 읽은 자리가 조용히 어긋난다 (전체글 참고).
+    this.인코딩 = null;
+    // 담을 때마다 는다. 푼 글을 다시 써도 되는지를 이 숫자로 가른다 —
+    // 바이트 수로 가르면 버린 만큼 다시 담겼을 때 같은 값이 되어 못 알아챈다.
+    this.판 = 0;
+    this.푼것 = null;
+    this.kid = null;
+  }
+
+  담기(buf) {
+    if (!buf?.length) return;
+    this.조각들.push(Buffer.from(buf));
+    this.바이트 += buf.length;
+    this.판++;
+    if (this.바이트 <= 출력상한) return;
+    /*
+     * 앞을 버린다.
+     *
+     * 버리면 이미 읽은 글자 수가 뜻을 잃는다 — 앞이 사라졌으니 같은 자리가
+     * 아니다. 억지로 맞추려 들면 조용히 어긋난 글을 주게 되므로, 커서를
+     * 0 으로 돌리고 **앞이 잘렸다고 말한다.** 겹쳐 보이는 편이 낫다.
+     */
+    while (this.바이트 > 출력상한 && this.조각들.length > 1) {
+      this.바이트 -= this.조각들.shift().length;
+    }
+    this.앞잘림 = true;
+    this.막버렸다 = true;
+    this.읽은글자 = 0;
+  }
+
+  /*
+   * 쌓인 것을 글로 푼다.
+   *
+   * 조각마다 풀면 여러 바이트짜리 글자가 조각 경계에서 쪼개져 깨진다.
+   * 통째로 이어 붙여 한 번에 푼다.
+   *
+   * **인코딩은 한 번 정하면 안 바꾼다.** 이게 중요하다 — 읽은 자리(읽은글자)를
+   * 글자 수로 세고 있는데, 인코딩이 중간에 바뀌면 같은 앞부분이 다른 글자 수로
+   * 풀린다. 그러면 커서가 가리키던 자리가 조용히 어긋나서, 이미 준 글을 다시
+   * 주거나 새 글을 건너뛴다. 오류도 안 나고 로그에도 안 남는다.
+   *
+   * 실제로 그럴 수 있다. 인코딩 판정은 **버퍼 전체를 보는 어림짐작**이라,
+   * UTF-8 로 잘 풀리던 출력에 UTF-8 이 아닌 바이트가 하나 섞이는 순간
+   * 통째로 CP949 로 다시 읽힌다 — 한글 윈도우 콘솔에서 흔한 일이다.
+   */
+  전체글() {
+    if (!this.조각들.length) return '';
+    /*
+     * 안 바뀌었으면 지난번 것을 그대로 준다.
+     *
+     * `목록()` 이 일감마다 이걸 부른다 — 안 읽은 글자 수를 세려고. 그 한 번이
+     * 최대 256KB 를 이어 붙이고 통째로 다시 푸는 일이라, 끝난 것 여덟 개를
+     * 들고 있으면 목록 한 번에 2MB 를 푼다. 모델이 Jobs 를 부를 때마다.
+     */
+    if (this.푼것 && this.푼것.판 === this.판) return this.푼것.글;
+    const 다 = Buffer.concat(this.조각들);
+    if (this.인코딩) {
+      try {
+        const 글 = new TextDecoder(this.인코딩, { fatal: false }).decode(다);
+        this.푼것 = { 판: this.판, 글 };
+        return 글;
+      } catch { /* 이 Node 가 모르는 이름이면 아래로 내려가 다시 잰다 */ }
+    }
+    const 콘솔 = consoleCodepage() === 65001 ? 'utf-8' : null;
+    try {
+      const r = decodeBytes(다, { fallback: 콘솔 });
+      // 처음 한 번만 못 박는다. 아직 아무것도 안 쌓였을 때 정하면
+      // 표본이 너무 적어 엉뚱하게 잡히므로, 실제로 글이 나온 뒤에 정한다.
+      if (r.text) this.인코딩 = r.encoding;
+      this.푼것 = { 판: this.판, 글: r.text };
+      return r.text;
+    } catch { return 다.toString('utf8'); }
+  }
+
+  /**
+   * 지난번 읽은 뒤로 새로 나온 것만. 처음부터를 주면 통째로.
+   *
+   * `앞잘림` 은 **지금 건네는 이 글**에 대한 말이다. 묻는 방식에 따라 답이 다르다.
+   *
+   *   통째로 —  '이 일감은 앞을 버린 적이 있다.' 지금 주는 것이 처음부터가
+   *             아니라는 뜻이라, 버린 적이 있는 한 계속 사실이다.
+   *   새것만 —  '지금 주는 이 토막 **앞에 구멍이 있다.**' 버린 직후 한 번만
+   *             사실이고, 그 뒤에 나온 몇 줄은 멀쩡하다.
+   *
+   * 이 둘을 한 칸으로 합쳐 뒀더니, 한 번 넘친 일감은 **그 뒤로 영원히**
+   * "앞부분이 잘렸습니다" 를 달고 나왔다. 모델은 제가 받은 글에 앞이 빠졌다고
+   * 믿고 처음부터 다시 읽으러 가는데 — 로컬 모델에서 왕복 하나가 20~40초다 —
+   * 그렇게 받아 온 것에도 똑같이 그 말이 붙어 있다. 맴돌기 딱 좋은 자리였다.
+   * test/jobs.test.js 의 '온전한 새 출력에 잘렸다고 안 한다' 가 여기를 지킨다.
+   */
+  읽기({ 처음부터 = false } = {}) {
+    const 글 = this.전체글();
+    const 새것 = 처음부터 ? 글 : 글.slice(Math.min(this.읽은글자, 글.length));
+    this.읽은글자 = 글.length;
+    const 잘림 = 처음부터 ? this.앞잘림 : this.막버렸다;
+    // 통째로 읽어 갔으면 지금 들고 있는 것을 다 본 것이라, '바로 앞에 구멍이
+    // 있다' 는 경고도 같이 내린다. 다음에 또 버리면 그때 다시 선다.
+    this.막버렸다 = false;
+    return { 글: 새것, 앞잘림: 잘림 };
+  }
+
+  산햇수() { return Math.round((Date.now() - this.띄운때) / 1000); }
+}
+
+const 일감들 = new Map();
+let 다음번호 = 1;
+// 자리를 위해 지운 개수. **지웠으면 지웠다고 말하려고** 센다 —
+// 안 말하면 모델은 목록에 보이는 것이 전부인 줄 안다.
+let 치운것 = 0;
+
+/**
+ * 끝난 일감이 쌓이는 것을 막는다.
+ *
+ * 오래된 것부터 버린다. 번호가 곧 띄운 순서라 그대로 쓴다. 방금 띄운 것을
+ * 못 읽게 되면 안 되므로 **최근 쪽을 남긴다.**
+ */
+function 끝난것치우기() {
+  const 끝난것 = [...일감들.values()].filter((j) => j.상태 !== '도는중').sort((a, b) => a.번호 - b.번호);
+  if (끝난것.length <= 끝난것상한) return;
+  for (const j of 끝난것.slice(0, 끝난것.length - 끝난것상한)) {
+    // 들고 있던 것도 같이 놓는다. 항목만 지우고 조각들을 안 놓으면 아무것도 안 준다.
+    j.조각들 = [];
+    j.푼것 = null;
+    일감들.delete(j.번호);
+    치운것++;
+  }
+}
+
+/**
+ * 명령을 뒤에서 띄운다.
+ *
+ * @param 기다림 띄운 뒤 몇 ms 를 지켜보나. 그 사이에 죽으면 **띄우기 실패**로
+ *   돌려준다. 포트가 이미 물려 있는 경우가 제일 흔한데, 그때 "떴습니다" 라고
+ *   답하면 모델은 다음 단계로 넘어가고 사용자는 안 뜬 서버를 찾아다닌다.
+ */
+export async function 띄우기(명령, { cwd, 설명 = null, 기다림 = 1500 } = {}) {
+  const 도는것 = [...일감들.values()].filter((j) => j.상태 === '도는중');
+  if (도는것.length >= 최대일감) {
+    return { error: `뒤에서 도는 명령이 이미 ${도는것.length}개입니다. Jobs 로 안 쓰는 것을 끝내고 다시 하세요.` };
+  }
+
+  const j = new 일감(다음번호++, 명령, 설명);
+  const shell = 셸명령(명령);
+  let kid;
+  try {
+    kid = spawn(shell.file, shell.args, {
+      ...띄우기옵션(cwd),
+      windowsVerbatimArguments: shell.verbatim,
+    });
+  } catch (err) {
+    return { error: `띄우지 못했습니다: ${String(err?.message ?? err)}` };
+  }
+  j.kid = kid;
+  일감들.set(j.번호, j);
+
+  kid.stdout?.on('data', (b) => j.담기(b));
+  kid.stderr?.on('data', (b) => j.담기(b));
+  kid.on('error', (err) => { j.담기(Buffer.from(`\n[띄우기 실패: ${err.message}]\n`)); j.상태 = '끝남'; j.종료코드 = -1; });
+  kid.on('close', (code, sig) => {
+    if (j.상태 === '죽임') return;
+    j.상태 = '끝남';
+    j.종료코드 = sig ? null : code;
+    j.시그널 = sig ?? null;
+    // 끝난 것이 쌓이지 않게. 도는 것은 최대일감 이 따로 막는다.
+    끝난것치우기();
+  });
+
+  // 뜨자마자 죽는지 잠깐 지켜본다. 그 몇 줄이 대부분의 답이다.
+  await 잠깐(j, 기다림);
+
+  const 본것 = j.읽기({ 처음부터: true });
+  if (j.상태 !== '도는중') {
+    일감들.delete(j.번호);
+    return {
+      떴나: false,
+      번호: j.번호,
+      종료코드: j.종료코드,
+      시그널: j.시그널,
+      출력: 본것.글,
+    };
+  }
+  return { 떴나: true, 번호: j.번호, 출력: 본것.글 };
+}
+
+function 잠깐(j, ms) {
+  return new Promise((끝) => {
+    if (ms <= 0) return 끝();
+    let 됐나 = false;
+    const 마치기 = () => { if (됐나) return; 됐나 = true; clearTimeout(시계); 끝(); };
+    const 시계 = setTimeout(마치기, ms);
+    시계.unref?.();
+    j.kid?.once('close', 마치기);
+    j.kid?.once('error', 마치기);
+  });
+}
+
+export function 목록() {
+  return [...일감들.values()].map((j) => ({
+    번호: j.번호,
+    명령: j.명령,
+    설명: j.설명,
+    상태: j.상태,
+    종료코드: j.종료코드,
+    시그널: j.시그널,
+    초: j.산햇수(),
+    안읽은글자: Math.max(0, j.전체글().length - j.읽은글자),
+  }));
+}
+
+export function 하나(번호) { return 일감들.get(Number(번호)) ?? null; }
+
+export function 읽기(번호, opts) {
+  const j = 하나(번호);
+  if (!j) return null;
+  const r = j.읽기(opts);
+  return { ...r, 상태: j.상태, 종료코드: j.종료코드, 시그널: j.시그널, 명령: j.명령, 초: j.산햇수() };
+}
+
+/**
+ * 하나를 끝낸다.
+ *
+ * **기다렸다가 거둔다.** 죽이자마자 파이프를 끊으면 그 순간 아직 안 읽힌 것이
+ * 통째로 사라지는데, 하필 그게 제일 중요한 몇 줄이다 — 서버가 뻗으면서 남긴
+ * 스택 트레이스, 왜 죽었는지 적은 마지막 말. `마지막 출력:` 이라고 적어 놓고
+ * 정작 마지막을 안 주면 안 적느니만 못하다.
+ */
+export async function 끝내기(번호) {
+  const j = 하나(번호);
+  if (!j) return null;
+  if (j.상태 !== '도는중') { 일감들.delete(j.번호); return { 이미: true, 명령: j.명령 }; }
+  j.상태 = '죽임';
+  /*
+   * 사람이 시킨 자리라 넉넉히 기다린다.
+   *
+   * 검사를 통째로 돌릴 때처럼 컴퓨터가 바쁘면 taskkill 이 1.5초를 넘긴다.
+   * 그때 잘린 채로 넘어가면 손자가 남는데, 몇백 ms 빨리 돌아오는 것보다
+   * 안 죽은 서버 하나가 훨씬 비싸다.
+   */
+  const 넉넉히 = 6000;
+  나무죽이기(j.kid, { 파이프끊기: false, 상한: 넉넉히 });
+  await 죽는말기다리기(j.kid, 죽는말기다림);
+  /*
+   * 아직 살아 있으면 여기서 끊는다.
+   *
+   * 곧 목록에서 지울 참인데, 지우고 나면 이놈을 가리킬 방법이 없다. 안 죽은
+   * 채로 지우면 영영 못 찾는 프로세스가 하나 남는다 — 이 기능이 없애려던
+   * 바로 그 상태다. 유닉스에서 SIGTERM 을 안 듣는 놈이 여기로 온다.
+   * 윈도우에서는 나무를 다 못 훑어 뿌리를 살려 둔 경우가 여기로 온다.
+   *
+   * **뿌리살리기를 끈다.** 이걸 안 끄면 윈도우에서 taskkill 이 또 잘렸을 때
+   * 나무죽이기 가 kid.kill() 에 닿지도 못하고 그냥 돌아온다 — 「곧장」 이
+   * 윈도우에서는 아무 뜻이 없었다는 말이다. 여기는 마지막 자리라 뿌리라도
+   * 죽여야 한다. (모두끝내기 는 이미 그렇게 하고 있었다.)
+   */
+  if (아직사나(j.kid)) {
+    나무죽이기(j.kid, { 파이프끊기: false, 곧장: true, 상한: 넉넉히, 뿌리살리기: false });
+    /*
+     * 죽인 **직후에 살았나 물으면 안 된다.**
+     *
+     * 아직사나() 는 exitCode·signalCode 를 보는데, 그 값은 Node 가 종료를
+     * 실제로 **관찰한 뒤에** 채워진다. 동기 taskkill 이 돌아온 순간에는 아직
+     * 비어 있을 수 있다 — 그러면 멀쩡히 죽은 것을 「안 죽었다」 로 읽는다.
+     *
+     * 검사를 통째로 돌릴 때 이걸로 한 번 헛짚었다. 혼자 돌리면 초록이고
+     * 전체에서만 빨개졌다 — 컴퓨터가 바쁘면 관찰이 늦기 때문이다.
+     * 그러니 한 번 더 기다렸다가 묻는다.
+     */
+    await 죽는말기다리기(j.kid, 죽는말기다림);
+  }
+  파이프끊기(j.kid);
+  const 남은 = j.읽기({});
+  /*
+   * ★ 그러고도 안 죽었으면 **그렇다고 말한다.**
+   *
+   * 전에는 성패를 안 보고 늘 성공을 돌려줬다. 그러면 모델과 사람은 「끝냈습니다」
+   * 를 받는데 서버는 살아서 포트를 물고 있고, 목록에서도 지워져 다시 부를
+   * 방법이 없다. 이 파일 머리말이 스스로 적어 둔 「안 죽은 채로 지우면 영영
+   * 못 찾는 프로세스가 하나 남는다」 가 그대로 성립하고 있었다.
+   *
+   * 안 죽었으면 목록에 남긴다. 그래야 사람이 한 번 더 시킬 수 있다.
+   */
+  if (아직사나(j.kid)) {
+    j.상태 = '도는중';   // 지우지 않는다 — 다시 시킬 수 있어야 한다
+    return { 이미: false, 안죽음: true, 명령: j.명령, 초: j.산햇수(), 남은: 남은.글 };
+  }
+  일감들.delete(j.번호);
+  return { 이미: false, 명령: j.명령, 초: j.산햇수(), 남은: 남은.글 };
+}
+
+/**
+ * 전부 끝낸다. deel 을 닫을 때 부른다.
+ *
+ * 이걸 빠뜨리면 사람이 안 띄운 서버가 계속 돈다. 다음에 켜서 `npm run dev` 를
+ * 하면 "포트가 이미 쓰이는 중" 이 뜨는데, 무엇이 물고 있는지 알 길이 없다.
+ */
+export function 모두끝내기() {
+  const n = [...일감들.values()].filter((j) => j.상태 === '도는중').length;
+  for (const j of 일감들.values()) {
+    if (j.상태 !== '도는중') continue;
+    j.상태 = '죽임';
+    /*
+     * 여기는 프로그램이 끝나는 길이라 **다시 올 기회가 없다.** 한 번 짧게
+     * 훑어 보고, 잘렸으면 한 번 더 길게 훑는다. 그러고도 안 되면 뿌리라도
+     * 죽인다 — 아무것도 안 죽이는 것보다 낫다.
+     */
+    if (!나무죽이기(j.kid)) 나무죽이기(j.kid, { 상한: 4000, 뿌리살리기: false });
+  }
+  일감들.clear();
+  return n;
+}
+
+/** 검사에서 판을 깨끗이 하려고 쓴다. */
+export function 비우기() { 모두끝내기(); 다음번호 = 1; 치운것 = 0; }
+
+// 어떤 길로 끝나든 남기지 않는다. repl·oneshot 이 부르는 것과 겹쳐도 무해하다.
+process.once('exit', () => { try { 모두끝내기(); } catch { /* 끝나는 중이라 할 수 있는 게 없다 */ } });
+
+/*
+ * ── 도구 ──────────────────────────────────────────────────────────────
+ *
+ * 왜 Bash 안에 인자로 안 넣고 도구를 따로 두나:
+ *   Bash 에 `job`·`kill` 같은 인자를 얹으면 스키마가 "명령을 실행한다" 와
+ *   "일감을 본다" 두 가지를 한꺼번에 말하게 된다. 작은 모델은 그 자리에서
+ *   command 없이 Bash 를 부르거나, 반대로 읽으려다 명령을 또 실행한다.
+ *   하는 일이 다르면 도구를 나누는 편이 결국 싸다. 이 스키마는 아주 작다.
+ */
+/*
+ * 인자 이름 받이 — 한글 이름과 영문 이름을 **둘 다** 받는다.
+ *
+ * 모델은 한글 인자 이름을 자주 영어로 바꿔 보낸다. 추정이 아니라 이 저장소가
+ * 겪은 일이다 — Task 는 이미 `목적 ?? purpose`, `할일 ?? task`, `모드 ?? mode`
+ * 로 둘 다 받고 있다(agent/loop.js). 누군가 겪고 달아 둔 것이다.
+ *
+ * 여기에는 그게 없어서 `Jobs({job: 1, stop: true})` 가 **목록**을 돌려줬다.
+ * 모델은 끄라고 시켰고 성공처럼 보이는 답을 받았는데 서버는 그대로 포트를
+ * 문다 — 사람은 원인을 못 찾는다. 이 도구에서 제일 나쁜 실패다.
+ *
+ * 이름을 영문으로 **바꾸는** 것으로는 안 된다. 그러면 한글로 보내는 쪽이 같은
+ * 구멍에 빠지고, 안 맞춘 이름(id·number)은 여전히 샌다. 둘 다 받고,
+ * 못 알아들은 것은 못 알아들었다고 말한다.
+ *
+ * **목록은 여기 한 벌뿐이다.** 화면 이름표도 이걸 쓴다(repl.js·oneshot.js).
+ * 두 벌이 되면 한쪽만 고쳐지고, 그때부터 화면과 실제가 어긋난다.
+ */
+const 인자이름 = {
+  번호: ['job', 'job_id', 'jobId', 'id', 'number', '번호'],
+  끝내기: ['stop', 'kill', '끝내기'],
+  처음부터: ['from_start', 'fromStart', 'full', '처음부터'],
+};
+const 아는이름 = new Set(Object.values(인자이름).flat());
+
+/**
+ * 준 인자에서 아는 것만 골라낸다.
+ *
+ * @returns {{번호: number|null, 끝내기: boolean, 처음부터: boolean, 준것: string[], 모르는것: string[]}}
+ */
+export function 일감인자(args) {
+  const 준것 = Object.keys(args ?? {});
+  const 하나씩 = (이름) => {
+    for (const n of 인자이름[이름]) if (args?.[n] != null) return args[n];
+    return null;
+  };
+  const 날번호 = 하나씩('번호');
+  return {
+    번호: 날번호 == null ? null : Number(날번호),
+    끝내기: !!하나씩('끝내기'),
+    처음부터: !!하나씩('처음부터'),
+    준것,
+    모르는것: 준것.filter((k) => !아는이름.has(k)),
+  };
+}
+
+/**
+ * 모델에게 건넬 만큼만 남긴다 — **뒤**를 남긴다.
+ *
+ * 오래 도는 것에서 사람이 찾는 것은 언제나 방금 나온 쪽이다. 앞을 남기면
+ * 몇 시간 전 기동 로그를 주게 된다.
+ *
+ * 줄였으면 줄였다고 적는다. 안 적으면 모델은 그게 전부인 줄 알고,
+ * 안 보이는 줄에 답이 있을 때 엉뚱한 결론으로 간다.
+ */
+function 뒤만(글, 한도 = 건넬상한) {
+  const s = String(글 ?? '');
+  if (s.length <= 한도) return { 글: s, 줄임: false };
+  return {
+    글: `(앞 ${s.length - 한도}자는 길어서 줄였습니다 — 뒤쪽만 보여 줍니다)\n${s.slice(-한도)}`,
+    줄임: true,
+  };
+}
+
+/** 끝난 일감을 한 마디로. 시그널로 죽으면 종료코드가 null 이라 따로 말한다. */
+function 끝난말(r) {
+  if (r.시그널) return `${r.시그널} 로 죽음`;
+  return r.종료코드 === 0 ? '끝남' : `종료코드 ${r.종료코드}`;
+}
+
+export const JOBS_TOOL = {
+  schema: {
+    name: 'Jobs',
+    description: '뒤에서 도는 명령(Bash 의 background)을 보고·읽고·끝낸다.'
+      + ' job 없이 부르면 목록. job 을 주면 그동안 새로 나온 출력.'
+      + ' 서버를 띄웠으면 일이 끝날 때 반드시 stop 으로 정리해라.',
+    parameters: {
+      type: 'object',
+      properties: {
+        job: { type: 'number', description: '볼 일감 번호. 없으면 목록' },
+        stop: { type: 'boolean', description: 'true 면 그 일감을 끝낸다' },
+        from_start: { type: 'boolean', description: 'true 면 처음부터 다시 읽는다' },
+      },
+      required: [],
+    },
+  },
+  // 끝내기 는 죽는 순간 뱉은 말을 기다렸다 거두므로 비동기다 (끝내기 머리말 참고).
+  // runTool 이 await 로 부르니 도구가 비동기여도 된다 (tools/index.js).
+  async run(args) {
+    const 받은것 = 일감인자(args);
+    /*
+     * 준 것이 있는데 **하나도** 못 알아들었으면 목록으로 얼버무리면 안 된다.
+     *
+     * 목록을 돌려주면 그것도 성공한 답으로 보인다. 끄라고 시킨 모델은
+     * 껐다고 여기고 넘어가는데 서버는 그대로 돈다. 무엇을 받는지 알려 줘야
+     * 다음 걸음에서 고쳐 부른다.
+     *
+     * 인자가 **아예 없는** 것은 그냥 '목록 보기' 다 — 그건 오류가 아니다.
+     */
+    if (받은것.준것.length && 받은것.모르는것.length === 받은것.준것.length) {
+      return {
+        error: `모르는 인자입니다: ${받은것.모르는것.join(', ')}.`
+          + ' Jobs 는 번호(job) · 끝내기(stop) · 처음부터(from_start) 만 받습니다.'
+          + ' 번호 없이 부르면 목록입니다.',
+      };
+    }
+    const 번호 = 받은것.번호;
+    // 숫자가 아닌 것을 받으면 NaN 이 되고, 그대로 두면 `NaN번 일감이 없습니다`
+    // 라는 말이 모델에게 나간다. 무엇이 잘못됐는지 안 알려 주는 오류다.
+    if (번호 != null && !Number.isFinite(번호)) {
+      return { error: `번호는 숫자여야 합니다 (받은 것: ${JSON.stringify(args?.번호)}). 번호 없이 Jobs 를 불러 목록을 보세요.` };
+    }
+
+    if (번호 == null) {
+      /*
+       * 번호 없이 "끝내라" 고 하면 목록으로 얼버무리면 안 된다.
+       *
+       * 목록을 돌려주면 그건 성공한 답으로 보인다. 모델은 정리한 줄 알고
+       * "서버를 껐습니다" 라고 말하는데 서버는 그대로 돌고 있다.
+       * 도구가 시킨 일을 안 했으면 안 했다고 말해야 그 다음이 이어진다.
+       */
+      if (받은것.끝내기) {
+        const 도는것 = 목록().filter((j) => j.상태 === '도는중');
+        return {
+          error: '끝낼 일감 번호를 주세요. 번호 없이 끝내기만 주면 아무것도 안 끝냅니다.'
+            + (도는것.length
+              ? ` 지금 도는 것: ${도는것.map((j) => `${j.번호}번(${j.명령})`).join(' · ')}`
+              : ' 지금 도는 것이 없습니다.'),
+        };
+      }
+      const ls = 목록();
+      if (!ls.length) return { content: '뒤에서 도는 명령이 없습니다.', summary: 세말('count', 0) };
+      const 줄들 = ls.map((j) => {
+        const 상 = j.상태 === '도는중' ? `도는중 ${j.초}초` : j.시그널 ? `${j.시그널} 로 죽음` : `끝남 (종료코드 ${j.종료코드})`;
+        const 새것 = j.안읽은글자 ? ` · 안 읽은 출력 ${j.안읽은글자}자` : '';
+        return `  ${j.번호}. ${j.명령}  — ${상}${새것}`;
+      });
+      /*
+       * 자리를 위해 지운 것이 있으면 말한다.
+       *
+       * 안 말하면 모델은 여기 보이는 것이 이 세션에서 띄운 전부인 줄 안다.
+       * 아까 띄운 3번을 찾다가 없으니 "안 띄웠나 보다" 하고 다시 띄운다 —
+       * 그러면 포트가 물려서 안 뜨고, 왜 안 되는지도 모른다.
+       */
+      if (치운것) 줄들.push(`  (오래된 것 ${치운것}개는 자리를 위해 지웠습니다)`);
+      return { content: 줄들.join('\n'), summary: 세말('count', ls.length), 일감수: ls.length };
+    }
+
+    if (받은것.끝내기) {
+      const r = await 끝내기(번호);
+      if (!r) return { error: `${번호}번 일감이 없습니다. 번호 없이 Jobs 를 불러 목록을 보세요.` };
+      if (r.이미) return { content: `${번호}번은 이미 끝나 있었습니다: ${r.명령}`, summary: 말('sum.jobEndedAlready') };
+      /*
+       * ★ 안 죽었으면 「끝냈습니다」 라고 하지 않는다.
+       *
+       * 여기서 거짓말하면 모델은 다음 단계로 가고 사람은 포트를 문 채로 남은
+       * 서버를 못 찾는다 — 이 기능이 없애려던 바로 그 상태다. 목록에도
+       * 남겨 뒀으니 한 번 더 시킬 수 있다고 알려 준다.
+       */
+      if (r.안죽음) {
+        return {
+          error: `${번호}번이 안 끝났습니다 (${r.초}초 돌았습니다): ${r.명령}`
+            + '\n죽이라고 시켰는데 아직 살아 있습니다. 목록에 그대로 두었으니 한 번 더 시켜 보세요.'
+            + (r.남은 ? `\n\n마지막 출력:\n${뒤만(r.남은, 2000).글}` : ''),
+          summary: 말('sum.jobNotStopped'),
+        };
+      }
+      return {
+        content: `${번호}번을 끝냈습니다 (${r.초}초 돌았습니다): ${r.명령}`
+          + (r.남은 ? `\n\n마지막 출력:\n${뒤만(r.남은, 2000).글}` : ''),
+        summary: 이어(말('sum.jobStopped'), 말('unit.sec', { n: r.초 })),
+      };
+    }
+
+    const r = 읽기(번호, { 처음부터: 받은것.처음부터 });
+    if (!r) return { error: `${번호}번 일감이 없습니다. 번호 없이 Jobs 를 불러 목록을 보세요.` };
+    const 머리 = r.상태 === '도는중'
+      ? `${번호}번 (도는중 ${r.초}초): ${r.명령}`
+      : `${번호}번 (${r.시그널 ? `${r.시그널} 로 죽음` : `끝남 · 종료코드 ${r.종료코드}`}): ${r.명령}`;
+    // 새 출력이 없다는 것도 사실이다. 빈 글을 주면 모델은 못 읽은 줄 안다.
+    const 잘라낸 = 뒤만(r.글);
+    const 몸 = r.글.trim()
+      ? (r.앞잘림 ? '(앞부분은 너무 길어 잘렸습니다 — 뒤쪽만 남았습니다)\n' : '') + 잘라낸.글
+      : '(지난번 읽은 뒤로 새 출력이 없습니다)';
+    return {
+      content: `${머리}\n\n${몸}`,
+      summary: (r.상태 === '도는중' ? 이어(말('sum.jobRunning'), 말('unit.sec', { n: r.초 })) : 끝난말(r))
+        + (잘라낸.줄임 ? ' · 일부만' : ''),
+      // 끝난 일감이 종료코드 0 이 아니면 실패로 물들인다 — Bash 와 같은 규칙이다.
+      // 시그널로 죽은 것도 실패다 — 그때 종료코드는 null 이라 !== 0 으로 잡힌다.
+      failed: r.상태 !== '도는중' && r.종료코드 !== 0,
+    };
+  },
+};