coxpit 5.27.6 → 6.1.0

package/src/server.ts

@@ -13,6 +13,7 @@ import { loginPageHTML } from './login';
 import {
   authMode, authIsOpen, verifyKey, storeKey, clearStored, isExposedBind, signSession, SESSION_COOKIE,
   clientKey, rateCheck, rateFail, rateReset, setupAllowed,
+  captureKey, captureKeyIsFixed, rotateCaptureKey, verifyCaptureKey,
 } from './authkey';
 import { config } from './config';
 import { readSettings, writeSettings } from './settings';
@@ -20,14 +21,17 @@ import { db } from './db';
 import { machines, repos, tasks, agentRuns, agentEvents, designCaptures, shareLinks, taskGroups, secrets } from './db/schema';
 import { BOOKMARKLET_JS } from './design';
 import { runShellOn, shq } from './exec';
-import { launchRun, cleanupRun, stopRun, getRunDiff, loadRunDocs, mergeRun, getRunTermInfo, steerRun, exportRun, prRun, integrateRuns, planFanout, reviewTask, syncRun, openWorkbench, spawnSubtasks, listSubtasks, resolveAgentToken, taskCloseRisk, launchGroupTask, isRunLive, askGroupCoordinator, computeRunOutputs, normalizeOutputs, listReclaimableWorktrees, pruneWorktrees, noopSignal, groupOverlap, landTarget, mergePreview, startLandResolve, listDocuments, verifyRun, openSessionAt, deleteSession, getScrollback, getSessionChat } from './orchestrator';
+import { launchRun, cleanupRun, stopRun, getRunDiff, loadRunDocs, mergeRun, getRunTermInfo, steerRun, exportRun, prRun, integrateRuns, planFanout, reviewTask, syncRun, openWorkbench, spawnSubtasks, listSubtasks, resolveAgentToken, taskCloseRisk, launchGroupTask, isRunLive, liveInPlaceRun, askGroupCoordinator, computeRunOutputs, normalizeOutputs, listReclaimableWorktrees, pruneWorktrees, worktreeDisk, listOrphanTmux, killTmuxSessions, noopSignal, groupOverlap, landTarget, mergePreview, startLandResolve, listDocuments, verifyRun, openSessionAt, deleteSession, getScrollback, getRunPwd, getSessionChat } from './orchestrator';
 import { openTerm } from './term';
+import { attach as agentAttach, feed as agentFeed, input as agentInput, onExit as agentExit, detach as agentDetach, allAgentStates, spottedPorts } from './agentstate';
+import { scanListeners, scanPort, killPid, dropCache as dropListenerCache } from './procscan';
 import { addSink, removeSink, broadcast } from './hub';
 import { getProvider, listProviders } from './providers';
 import { remoteState, setServe, setFunnel } from './remote';
 import { BOARD_HTML } from './board';
 import { COCKPIT_HTML } from './cockpit';
-import { listDir as fsListDir, readForView as fsReadForView, readRaw as fsReadRaw, writeText as fsWriteText, findFiles as fsFindFiles, uploadFile as fsUploadFile } from './files';
+import { listDir as fsListDir, readForView as fsReadForView, readRaw as fsReadRaw, writeText as fsWriteText, findFiles as fsFindFiles, uploadFile as fsUploadFile, withinFilesRoot } from './files';
+import { ensureWorkDoc, readWorkDoc, writeWorkDoc, removeWorkDoc, workDocPath, workDocSize } from './workdoc';
 
 const require_ = createRequire(import.meta.url);
 
@@ -201,7 +205,14 @@ function ptyMax(): number | null {
 }
 
 export async function buildServer(): Promise<FastifyInstance> {
-  const app = Fastify({ logger: true });
+  // 로거: 쿼리스트링의 캡처 키(?k=…)가 데몬 로그에 평문으로 남지 않게 가린다(issue #13).
+  // (프록시/엣지 로그는 데몬이 못 막지만, 캡처 키는 저가치·회전가능이라 감수 가능.)
+  const app = Fastify({ logger: {
+    redact: {
+      paths: ['req.url'],
+      censor: (v: unknown) => (typeof v === 'string' ? v.replace(/([?&]k=)[^&]*/g, '$1REDACTED') : v),
+    },
+  } });
   // 살아있는 웹 터미널 수 — pty 압력 조기경보(/api/health)용. openTerm 성공 시 +1, 소켓 close 시 -1.
   // 누수가 재발하면 이 값이 실제 열린 탭보다 커지지 않아도(닫을 때 감소), machine-wide ptmx 대비
   // 이 데몬의 부하를 노출한다. leak 재발 자체는 회귀 테스트(test/pty-fd.mjs)가 잡는다.
@@ -226,7 +237,14 @@ export async function buildServer(): Promise<FastifyInstance> {
   // 무인증 헬스(외부 감시용)
   app.get('/api/health', async () => {
     const max = ptyMax();
-    return { ok: true, name: 'coxpit', version: config.version, terminals: liveTerminals, ...(max ? { ptyMax: max } : {}) };
+    // v6.0 T6b — worktree 디스크 빚을 바깥(모니터링)에서도 볼 수 있게. 값은 캐시에서 나오고
+    // du 는 배경에서 돈다(health 는 기다리지 않는다). 없거나 0 이면 아예 싣지 않는다.
+    const wt = await worktreeDisk().catch(() => null);
+    return {
+      ok: true, name: 'coxpit', version: config.version, terminals: liveTerminals,
+      ...(max ? { ptyMax: max } : {}),
+      ...(wt && wt.count ? { worktrees: { count: wt.count, sizeKb: wt.sizeKb } } : {}),
+    };
   });
 
   // 플릿 보드(단일 페이지). 인증 게이트 적용됨(무인증 요청은 게이트가 login/setup 페이지로 응답).
@@ -368,6 +386,9 @@ export async function buildServer(): Promise<FastifyInstance> {
         return { ...r, events: (byRun.get(r.id) ?? []).slice(-EVENT_CAP), noop: sig.noop, noopReason: sig.reason };
       }),
       counts: { activeTasks: activeTasks.length, closedTasks: closedCount },
+      // 지금 터미널이 붙어 있는 run 의 에이전트 상태(runId → {state,detail,ts}).
+      // 하이드레이션용 — 새로 뜬 코크핏이 다음 agentstate 델타를 기다리지 않게. 붙어 있는 동안만 존재한다.
+      agentStates: allAgentStates(),
       // 보드 헤더 "어느 데몬에 붙어 있나" 표시용 (인증 뒤라 dbPath 노출 가능)
       // authOpen = 비밀번호 미설정 → Funnel(공개) 가드가 켜져야 함(원격접근 카드용)
       daemon: {
@@ -503,6 +524,17 @@ export async function buildServer(): Promise<FastifyInstance> {
     return pruneWorktrees(runIds);
   });
 
+  // v6.0 T6 — 고아 tmux 세션(위 worktree 회수와 같은 유지보수 가족). DB 에 run 기록이 없는 `coxpit-r*` 만 목록에 든다.
+  // 살아 있는 run 의 세션은 애초에 나오지 않고, 빈 셸이 아닌 것은 idle:false 로 표시만 된다.
+  app.get('/api/tmux/orphans', async () => ({ sessions: await listOrphanTmux() }));
+
+  // 선택 종료 — 이름 배열만 받는다. 서버가 고아 목록을 다시 떠서 그 안의 것만, '=' 정확 일치로 죽인다.
+  app.post('/api/tmux/orphans/kill', async (req, reply) => {
+    const b = (req.body ?? {}) as { sessions?: unknown };
+    if (!Array.isArray(b.sessions)) return reply.code(400).send({ error: 'sessions must be an array of session names' });
+    return killTmuxSessions(b.sessions.map((s) => String(s)));
+  });
+
   // ─── 머신 레지스트리 ────────────────────────────────────────────
   app.get('/api/machines', async () => ({ machines: await db.select().from(machines) }));
 
@@ -822,14 +854,13 @@ export async function buildServer(): Promise<FastifyInstance> {
   });
 
   // ─── Design Mode ───────────────────────────────────────────────
-  // 캡처 키: 인증 off 면 자유, on 이면 ?k=<COXPIT_AUTH_PASS> (북마클릿은 basic 헤더 불가)
+  // 캡처 키 = 마스터 접근키와 분리된 저가치 전용 키(issue #13). 오직 이 캡처 엔드포인트만 허가한다.
+  // 인증 꺼짐이면 자유, 아니면 ?k=<capture key> 를 검증(마스터 접근키가 아니라 캡처 키로).
+  // setup(마스터 키 미설정) 상태여도 캡처 키는 독립적으로 존재하므로 캡처는 동작한다.
   const captureKeyOk = (req: { query?: unknown }): boolean => {
-    const m = authMode();
-    // 인증 꺼짐 → 자유. 아직 키 미설정(setup) → 캡처 불가(키가 없으니 증명 수단 없음).
-    if (m.mode === 'disabled') return true;
-    if (m.mode === 'setup') return false;
+    if (authMode().mode === 'disabled') return true;
     const k = ((req.query ?? {}) as { k?: string }).k ?? '';
-    return verifyKey(k, m);
+    return verifyCaptureKey(k);
   };
   const cors = (reply: { header: (k: string, v: string) => unknown }) => {
     reply.header('access-control-allow-origin', '*');
@@ -856,6 +887,11 @@ export async function buildServer(): Promise<FastifyInstance> {
 
   app.get('/api/design', async () => ({ captures: await db.select().from(designCaptures) }));
 
+  // 캡처 키 조회/회전 — 인증 게이트 뒤(EXEMPT 아님)라 인증된 보드 사용자만 접근한다.
+  // 보드가 이걸로 북마클릿 href(?k=…)를 만들고, 회전 버튼으로 새 키를 발급한다.
+  app.get('/api/design/capture-key', async () => ({ key: captureKey(), fixed: captureKeyIsFixed() }));
+  app.post('/api/design/capture-key/rotate', async () => ({ key: rotateCaptureKey(), fixed: captureKeyIsFixed() }));
+
   app.delete('/api/design/:id', async (req, reply) => {
     const id = Number((req.params as { id: string }).id);
     await db.delete(designCaptures).where(eq(designCaptures.id, id));
@@ -925,24 +961,100 @@ export async function buildServer(): Promise<FastifyInstance> {
     return { task: tr[0], runs };
   });
 
-  // 태스크 이름 변경(=세션 이름 변경). title 만 갱신.
+  // 태스크 이름 변경(=세션 이름 변경) + v6.0 S2 승격(repoId 재부모화).
+  // 둘 다 선택 — title 만 보내던 기존 호출은 그대로 동작한다. repoId 는 "이 작업이 어느
+  // 프로젝트 것인가"만 바꾼다: run 의 worktreePath 는 손대지 않으므로 터미널은 제 폴더에서 계속 돈다.
   app.patch('/api/tasks/:id', async (req, reply) => {
     const id = Number((req.params as { id: string }).id);
-    const b = (req.body ?? {}) as { title?: string };
+    const b = (req.body ?? {}) as { title?: string; repoId?: unknown };
+    const wantTitle = b.title !== undefined;
+    const wantRepo = b.repoId !== undefined && b.repoId !== null;
+    if (!wantTitle && !wantRepo) return reply.code(400).send({ error: 'title or repoId required' });
+
     const title = (b.title ?? '').trim();
-    if (!title) return reply.code(400).send({ error: 'title required' });
-    if (title.length > 140) return reply.code(400).send({ error: 'title too long (max 140)' });
+    if (wantTitle) {
+      if (!title) return reply.code(400).send({ error: 'title required' });
+      if (title.length > 140) return reply.code(400).send({ error: 'title too long (max 140)' });
+    }
     const tr = await db.select().from(tasks).where(eq(tasks.id, id)).limit(1);
-    if (!tr[0]) return reply.code(404).send({ error: 'not found' });
-    await db.update(tasks).set({ title }).where(eq(tasks.id, id));
-    broadcast({ type: 'task', taskId: id, title });
-    return { ok: true, title };
+    const task = tr[0];
+    if (!task) return reply.code(404).send({ error: 'not found' });
+
+    let repoId: number | undefined;
+    if (wantRepo) {
+      const wanted = Number(b.repoId);
+      if (!Number.isInteger(wanted)) return reply.code(400).send({ error: 'repoId must be an integer' });
+      const rr = await db.select().from(repos).where(eq(repos.id, wanted)).limit(1);
+      const repo = rr[0];
+      if (!repo) return reply.code(404).send({ error: 'repo not found' });
+      // 승격은 한 방향이다 — 프로젝트로 나가는 길만 있고, Scratch 버킷으로 밀어 넣는 길은 없다.
+      if (repo.kind === 'sessions') {
+        return reply.code(400).send({
+          error: 'cannot re-parent into the scratch bucket',
+          code: 'SCRATCH_BUCKET',
+          detail: 'the sessions bucket is not a project — pick a registered repo',
+        });
+      }
+      repoId = repo.id;
+    }
+    const patch: { title?: string; repoId?: number } = {};
+    if (wantTitle) patch.title = title;
+    if (repoId !== undefined) patch.repoId = repoId;
+    await db.update(tasks).set(patch).where(eq(tasks.id, id));
+    const outTitle = wantTitle ? title : task.title;
+    const outRepo = repoId ?? task.repoId;
+    broadcast({ type: 'task', taskId: id, title: outTitle, repoId: outRepo });
+    return { ok: true, title: outTitle, repoId: outRepo };
+  });
+
+  // ─── v6.0 Part W — WORK.md (작업의 공유 컨텍스트) ───────────────
+  // 정본은 데몬 데이터 디렉터리(~/.coxpit/work/<taskId>.md)에 산다 — git 트리 밖이라
+  // 어떤 worktree 의 diff 에도 뜨지 않고 브랜치가 갈려도 내용이 갈라지지 않는다.
+  // 읽기·쓰기는 **기존 파일 뷰어**(/api/fs/read·write)가 그대로 맡는 것이 기본이다:
+  // ~/.coxpit 은 기본 뷰어 루트(홈) 안이라 이미 통과한다(새 파일 창구를 만들지 않는다).
+  // 여기 셋은 그 앞뒤만 맡는다 — ① 처음 열 때 빈 파일을 만들어 주고(POST),
+  // ② COXPIT_DB/COXPIT_FILES_ROOT 조합 때문에 그 길이 막힌 경우의 대체 경로(GET/PUT).
+  const WORK_DOC_MAX = 512 * 1024;
+  const workTask = async (id: number) => (await db.select().from(tasks).where(eq(tasks.id, id)).limit(1))[0];
+
+  app.post('/api/tasks/:id/work', async (req, reply) => {
+    const id = Number((req.params as { id: string }).id);
+    if (!(await workTask(id))) return reply.code(404).send({ error: 'task not found' });
+    try {
+      const path = ensureWorkDoc(id);
+      // inRoot=true 면 클라이언트는 평소 쓰던 파일 뷰어 페인으로 그냥 연다.
+      return { ok: true, path, inRoot: withinFilesRoot(path), size: workDocSize(id) };
+    } catch (e: any) { return reply.code(500).send({ error: String(e?.message || e) }); }
+  });
+
+  app.get('/api/tasks/:id/work', async (req, reply) => {
+    const id = Number((req.params as { id: string }).id);
+    if (!(await workTask(id))) return reply.code(404).send({ error: 'task not found' });
+    const path = workDocPath(id);
+    const text = readWorkDoc(id);
+    // 뷰어가 /api/fs/read 에서 받던 모양 그대로 — 같은 렌더러가 손 안 대고 붙는다.
+    return { path, name: 'WORK.md', kind: 'md', size: Buffer.byteLength(text, 'utf8'), editable: true, text };
   });
 
+  app.put('/api/tasks/:id/work', async (req, reply) => {
+    const id = Number((req.params as { id: string }).id);
+    const b = (req.body ?? {}) as { content?: string };
+    if (typeof b.content !== 'string') return reply.code(400).send({ error: 'content required' });
+    if (Buffer.byteLength(b.content, 'utf8') > WORK_DOC_MAX) return reply.code(400).send({ error: 'content exceeds edit cap (512KB)' });
+    if (!(await workTask(id))) return reply.code(404).send({ error: 'task not found' });
+    try {
+      const { path, size } = writeWorkDoc(id, b.content);
+      return { ok: true, path, name: 'WORK.md', size };
+    } catch (e: any) { return reply.code(500).send({ error: String(e?.message || e) }); }
+  });
+
+  // 역할 이름(run.title) 상한 — 탭 한 칸에 들어가는 길이. 작업 이름(140)보다 짧게 둔다.
+  const RUN_TITLE_MAX = 60;
+
   // N개의 에이전트 run 을 만들고 각자 오케스트레이션 시작(fire-and-forget).
   app.post('/api/tasks/:id/run', async (req, reply) => {
     const id = Number((req.params as { id: string }).id);
-    const b = (req.body ?? {}) as { agent?: string; count?: number; real?: boolean; model?: string };
+    const b = (req.body ?? {}) as { agent?: string; count?: number; real?: boolean; model?: string; title?: string; inPlace?: boolean };
     const tr = await db.select().from(tasks).where(eq(tasks.id, id)).limit(1);
     const task = tr[0];
     if (!task) return reply.code(404).send({ error: 'task not found' });
@@ -957,16 +1069,36 @@ export async function buildServer(): Promise<FastifyInstance> {
     if (model && (model.length > 64 || !/^[\w.\-:/]*$/.test(model))) {
       return reply.code(400).send({ error: 'invalid model name' });
     }
+    // v6.0 T4 — 역할 이름(선택). 작업 안에서 이 run 이 무엇인지(구현·기타). 빈값 = 프로바이더 이름으로 표시.
+    const title = (b.title ?? '').trim().slice(0, RUN_TITLE_MAX);
+    // v6.0 P — 격리는 선택이다. in-place = repo 체크아웃 공유(순차) · worktree = 병렬(나중에 머지).
+    const inPlace = b.inPlace === true;
+    if (inPlace && count > 1) {
+      return reply.code(400).send({
+        error: 'IN_PLACE_FANOUT',
+        detail: 'in-place is sequential — one agent per checkout (count must be 1). launch in a worktree to fan out.',
+      });
+    }
+    // P3 — 한 체크아웃에 에이전트 둘은 서로를 덮어쓴다. 만들기 **전에** 막고 이유를 말한다.
+    if (inPlace) {
+      const busy = await liveInPlaceRun(task.repoId);
+      if (busy !== null) {
+        return reply.code(409).send({
+          error: 'IN_PLACE_BUSY',
+          detail: `r${busy} is already working in this checkout — steer it, or launch in a worktree`,
+        });
+      }
+    }
     const created: Array<typeof agentRuns.$inferSelect> = [];
     for (let i = 0; i < count; i++) {
       const ins = await db.insert(agentRuns)
-        .values({ taskId: id, machineId: rp[0].machineId, agent, model, status: 'pending' })
+        .values({ taskId: id, machineId: rp[0].machineId, agent, model, title, inPlace, status: 'pending' })
         .returning();
       created.push(ins[0]!);
     }
     // 보드가 taskId 를 알도록 생성 브로드캐스트 후 백그라운드 시작.
     for (const r of created) {
-      broadcast({ type: 'run', runId: r.id, taskId: id, status: 'pending', agent, branch: '', filesChanged: 0 });
+      broadcast({ type: 'run', runId: r.id, taskId: id, status: 'pending', agent, title, inPlace, branch: '', filesChanged: 0 });
       void launchRun(r.id, b.real);
     }
     return reply.code(202).send({ ok: true, runs: created.map((r) => ({ id: r.id, status: r.status })) });
@@ -1021,6 +1153,8 @@ export async function buildServer(): Promise<FastifyInstance> {
     for (const r of trs) cleanups.push({ runId: r.id, ...(await cleanupRun(r.id)) });
 
     await db.update(tasks).set({ status: 'closed', closedAt: new Date() }).where(eq(tasks.id, id));
+    // 작업이 닫히면 그 작업의 WORK.md 도 같이 사라진다(W1) — 공유 컨텍스트는 작업의 수명을 산다.
+    removeWorkDoc(id);
     broadcast({ type: 'task', taskId: id, status: 'closed' });
     return { ok: true, taskId: id, cleanups };
   });
@@ -1034,6 +1168,22 @@ export async function buildServer(): Promise<FastifyInstance> {
     return { run: rr[0], events };
   });
 
+  // v6.0 T4 — run 의 역할 이름 변경(탭 더블클릭). title 만 받는다.
+  // (세션 버킷 run 은 지금까지처럼 태스크 이름을 바꾼다 — 클라이언트가 갈라 부른다.)
+  app.patch('/api/runs/:id', async (req, reply) => {
+    const id = Number((req.params as { id: string }).id);
+    const b = (req.body ?? {}) as { title?: unknown };
+    const title = typeof b.title === 'string' ? b.title.trim() : '';
+    if (!title) return reply.code(400).send({ error: 'title required' });
+    if (title.length > RUN_TITLE_MAX) return reply.code(400).send({ error: `title too long (max ${RUN_TITLE_MAX})` });
+    const rr = await db.select().from(agentRuns).where(eq(agentRuns.id, id)).limit(1);
+    if (!rr[0]) return reply.code(404).send({ error: 'not found' });
+    await db.update(agentRuns).set({ title }).where(eq(agentRuns.id, id));
+    // status 를 싣지 않는다 — 이름 변경은 정착 이벤트가 아니다(보드의 settle 알림을 깨우지 않게).
+    broadcast({ type: 'run', runId: id, taskId: rr[0].taskId, title });
+    return { ok: true, title };
+  });
+
   app.post('/api/runs/:id/cleanup', async (req, reply) => {
     const id = Number((req.params as { id: string }).id);
     const rr = await db.select().from(agentRuns).where(eq(agentRuns.id, id)).limit(1);
@@ -1111,6 +1261,84 @@ export async function buildServer(): Promise<FastifyInstance> {
     return res;
   });
 
+  // 페인이 지금 서 있는 폴더 (v5.28 D-fix) — 터미널이 찍은 상대경로를 무엇 기준으로 풀지.
+  // 못 알아내면 200 + { ok:false, pwd:'' } — 클라이언트가 worktree 로 폴백한다(지어낸 경로는 없다).
+  app.get('/api/runs/:id/pwd', async (req, reply) => {
+    const id = Number((req.params as { id: string }).id);
+    const rr = await db.select().from(agentRuns).where(eq(agentRuns.id, id)).limit(1);
+    if (!rr[0]) return reply.code(404).send({ error: 'not found' });
+    return await getRunPwd(id);
+  });
+
+  // ─── 무엇이 듣고 있나 (v5.28 B) — 증거만 보이고, 판정하지 않는다 ──────────────
+  // 이 페인 체크아웃이 남긴 LISTEN 소켓 + 언제부터 떠 있는지(etime). stale 판정은 없다.
+  // pwd 는 §D-fix 의 getRunPwd(페인이 지금 서 있는 폴더) 를 그대로 쓰고, 못 알아내면
+  // worktree 로 물러선다 — 그러면 underPane 은 그 기준으로 읽힌다(기준을 응답에 같이 싣는다).
+  app.get('/api/runs/:id/listeners', async (req, reply) => {
+    const id = Number((req.params as { id: string }).id);
+    const rr = await db.select().from(agentRuns).where(eq(agentRuns.id, id)).limit(1);
+    const run = rr[0];
+    if (!run) return reply.code(404).send({ error: 'not found' });
+    const mr = await db.select().from(machines).where(eq(machines.id, run.machineId)).limit(1);
+    const m = mr[0];
+    if (!m) return reply.code(404).send({ error: 'machine gone' });
+    const live = await getRunPwd(id);
+    const pwd = live.pwd || run.worktreePath || '';
+    const res = await scanListeners(m, { pwd });
+    // 수동 포착 — Part A 가 이미 모으고 있는 꼬리를 한 번 훑을 뿐(탭을 더 달지 않는다).
+    return { ...res, machine: m.slug, pwd, spotted: spottedPorts(id) };
+  });
+
+  // 머신 + 포트 겨냥 조회 — "8210 은 누가 물고 있나". 어디서 왔든 그대로 보여준다.
+  // 주의: 파라미터 이름은 위의 `/api/machines/:slug` 와 같은 자리라 `:slug` 로 맞춘다(라우터 충돌 회피).
+  //    값은 slug 또는 숫자 id 둘 다 받는다.
+  const findMachine = async (key: string) => {
+    const bySlug = await db.select().from(machines).where(eq(machines.slug, key)).limit(1);
+    if (bySlug[0]) return bySlug[0];
+    const n = Number(key);
+    if (!Number.isInteger(n)) return null;
+    const byId = await db.select().from(machines).where(eq(machines.id, n)).limit(1);
+    return byId[0] ?? null;
+  };
+
+  app.get('/api/machines/:slug/port/:port', async (req, reply) => {
+    const { slug, port } = req.params as { slug: string; port: string };
+    const m = await findMachine(slug);
+    if (!m) return reply.code(404).send({ error: 'machine not found' });
+    const p = Number(port);
+    if (!Number.isInteger(p) || p < 1 || p > 65535) return reply.code(400).send({ error: 'port must be 1..65535' });
+    const res = await scanPort(m, p);
+    return { ...res, machine: m.slug, port: p };
+  });
+
+  // 정확히 그 pid 하나만, 이 머신에서만. 가드는 **서버 쪽**이다(클라이언트를 믿지 않는다):
+  //   ① pid 1 거부 ② 데몬 자신 거부(로컬) ③ **지금 다시 훑은 목록에 없으면 거부**.
+  //   ③ 이 있어서 이건 "임의 pid kill 엔드포인트"가 아니다 — 사람이 본 그 행만 죽는다.
+  // "포트 위 전부 죽이기" 같은 편의는 두지 않는다(무관한 프로세스를 같이 데려간다).
+  app.post('/api/machines/:slug/kill', async (req, reply) => {
+    const { slug } = req.params as { slug: string };
+    const m = await findMachine(slug);
+    if (!m) return reply.code(404).send({ error: 'machine not found' });
+    const b = (req.body ?? {}) as { pid?: unknown };
+    const pid = Math.floor(Number(b.pid));
+    if (!Number.isInteger(pid) || pid <= 0) return reply.code(400).send({ error: 'pid must be a positive integer' });
+    if (pid === 1) return reply.code(403).send({ error: 'refused: pid 1 is init' });
+    const isLocal = m.kind === 'local' || (m.address ?? '') === '';
+    if (isLocal && pid === process.pid) return reply.code(403).send({ error: 'refused: that is the coxpit daemon itself' });
+    // 지금 다시 훑는다 — 목록에 없는 pid 는 사람이 본 적 없는 pid 다.
+    dropListenerCache(m.slug);
+    const fresh = await scanListeners(m);
+    const row = fresh.listeners.find((l) => l.pid === pid);
+    if (!row) {
+      return reply.code(409).send({
+        error: 'refused: that pid is not listening on this machine right now',
+        detail: fresh.note || 're-scan found no such listener — nothing was signalled',
+      });
+    }
+    const r = await killPid(m, pid);
+    return reply.code(r.ok ? 200 : 409).send({ ...r, pid, port: row.port, machine: m.slug });
+  });
+
   // 수동 재검증 — repo.verifyCmd 를 이 run 의 worktree 에서 다시 실행(정착 자동검증과 동일 경로).
   app.post('/api/runs/:id/verify', async (req, reply) => {
     const id = Number((req.params as { id: string }).id);
@@ -1643,10 +1871,12 @@ export async function buildServer(): Promise<FastifyInstance> {
       return;
     }
     liveTerminals++;   // pty 압력 지표(/api/health) — close 에서 정확히 1회 감소
+    agentAttach(id);   // 에이전트 상태 추적 시작(refcount — 같은 run 에 여러 클라이언트가 붙어도 tracker 는 하나)
     let closed = false;
     // 백프레셔 — WS 송신 버퍼가 차면 pty 를 잠시 멈춰 폭주 방지
     let paused = false;
     term.onData((d) => {
+      agentFeed(id, d);
       try {
         socket.send(JSON.stringify({ t: 'o', d }));
         if (!paused && socket.bufferedAmount > 800_000) { paused = true; try { term.pause(); } catch { /* n/a */ } }
@@ -1657,16 +1887,16 @@ export async function buildServer(): Promise<FastifyInstance> {
     }, 200);
     const keepalive = setInterval(() => { try { socket.ping(); } catch { /* closed */ } }, 30_000);
 
-    term.onExit(() => { try { socket.send(JSON.stringify({ t: 'exit' })); socket.close(); } catch { /* closed */ } });
+    term.onExit(() => { agentExit(id); try { socket.send(JSON.stringify({ t: 'exit' })); socket.close(); } catch { /* closed */ } });
     socket.on('message', (raw: Buffer) => {
       try {
         const m = JSON.parse(raw.toString()) as { t?: string; d?: string; cols?: number; rows?: number };
-        if (m.t === 'i' && typeof m.d === 'string') term.write(m.d);
+        if (m.t === 'i' && typeof m.d === 'string') { agentInput(id); term.write(m.d); }
         else if (m.t === 'r' && m.cols && m.rows) term.resize(Math.max(20, Math.min(500, m.cols)), Math.max(5, Math.min(200, m.rows)));
       } catch { /* ignore */ }
     });
     socket.on('close', () => {
-      if (!closed) { closed = true; liveTerminals = Math.max(0, liveTerminals - 1); }
+      if (!closed) { closed = true; liveTerminals = Math.max(0, liveTerminals - 1); agentDetach(id); }
       clearInterval(drain); clearInterval(keepalive);
       try { term.kill(); } catch { /* gone */ }
     });

package/src/workdoc.ts

@@ -0,0 +1,65 @@
+// v6.0 Part W — WORK.md, 한 작업(work)의 공유 컨텍스트.
+//
+// 격리된 run 은 **과거에서 갈라져 나온다** — 형제가 방금 정한 것을 모른 채 base 에서 시작하고,
+// 그 run 의 세션은 내가 옆 터미널에 말한 내용을 들은 적이 없다. 파일 컨텍스트는 Part P(in-place)
+// 의 몫이고, **결정 컨텍스트는 이 파일의 몫**이다: 여기 적힌 것은 이 작업 아래 모든 세션에 따라붙는다.
+//
+// 정본은 git 트리 **밖**(데몬 데이터 디렉터리 = DB 옆)에 둔다 — 어떤 worktree 의 diff 도
+// 더럽히지 않고, 브랜치가 갈려도 내용이 갈라지지 않는다. 작업이 닫히면 같이 사라진다.
+//
+// ⚠️ 편집은 **다음 발사·steer** 부터 닿는다. 돌고 있는 턴에 끼어드는 마법은 없다.
+// (W4 harvest — 살아있는 run 이 자기 worktree 에 적은 줄을 watcher 가 여기로 모으는 일 — 은
+//  이번 단계에서 의도적으로 미룬다: 주입만으로도 사람이 큐레이션한 컨텍스트는 이미 전달된다.)
+import { mkdirSync, readFileSync, writeFileSync, existsSync, rmSync, statSync } from 'node:fs';
+import { dirname as pdirname, join as pjoin, resolve as presolve } from 'node:path';
+import { config } from './config';
+
+/** 데몬 데이터 디렉터리(= DB 가 사는 곳, 기본 ~/.coxpit) 아래의 work 폴더. */
+export function workDir(): string {
+  return pjoin(pdirname(presolve(config.dbPath)), 'work');
+}
+
+/** 한 작업의 정본 경로. 파일은 첫 쓰기 때 생긴다(없는 것과 빈 것은 같은 뜻). */
+export function workDocPath(taskId: number): string {
+  return pjoin(workDir(), `${taskId}.md`);
+}
+
+/** 내용(없으면 ''). 읽기 실패는 '' 로 — 컨텍스트 하나 때문에 발사가 막히면 안 된다. */
+export function readWorkDoc(taskId: number): string {
+  try { return readFileSync(workDocPath(taskId), 'utf8'); } catch { return ''; }
+}
+
+export function workDocSize(taskId: number): number {
+  try { return statSync(workDocPath(taskId)).size; } catch { return 0; }
+}
+
+/** 처음 열 때 빈 파일로 만들어 둔다 — 뷰어가 "없는 파일"에 걸려 넘어지지 않도록.
+ *  빈 파일은 주입되지 않으므로(아래 workContextBlock) 보일러플레이트가 새어나가지 않는다. */
+export function ensureWorkDoc(taskId: number): string {
+  const p = workDocPath(taskId);
+  mkdirSync(workDir(), { recursive: true });
+  if (!existsSync(p)) writeFileSync(p, '', 'utf8');
+  return p;
+}
+
+export function writeWorkDoc(taskId: number, content: string): { path: string; size: number } {
+  const p = workDocPath(taskId);
+  mkdirSync(workDir(), { recursive: true });
+  writeFileSync(p, content, 'utf8');
+  return { path: p, size: Buffer.byteLength(content, 'utf8') };
+}
+
+/** 작업이 닫히거나 지워질 때 함께 사라진다(정리 경로에서 호출). */
+export function removeWorkDoc(taskId: number): void {
+  try { rmSync(workDocPath(taskId), { force: true }); } catch { /* 없으면 그만 */ }
+}
+
+/**
+ * 프롬프트에 붙일 블록. **비어 있으면 아무것도 붙이지 않는다** — 없음은 깔끔해야지,
+ * 빈 블록으로 에이전트를 헷갈리게 하면 안 된다.
+ */
+export function workContextBlock(taskId: number): string {
+  const text = readWorkDoc(taskId).trim();
+  if (!text) return '';
+  return `\n\n## WORK CONTEXT (shared across this work's sessions — decisions recorded here bind you)\n${text}`;
+}