coxpit 4.5.0 → 4.7.0

package/src/db/index.ts

@@ -44,6 +44,7 @@ export async function ensureSchema(): Promise<void> {
       prompt TEXT NOT NULL DEFAULT '',
       status TEXT NOT NULL DEFAULT 'open',
       design_capture_id INTEGER,
+      outputs TEXT NOT NULL DEFAULT '[]',
       created_at INTEGER DEFAULT (unixepoch())
     );
     CREATE TABLE IF NOT EXISTS agent_runs (
@@ -98,4 +99,6 @@ export async function ensureSchema(): Promise<void> {
   try { await client.execute("ALTER TABLE agent_runs ADD COLUMN model TEXT NOT NULL DEFAULT ''"); } catch { /* exists */ }
   try { await client.execute('ALTER TABLE tasks ADD COLUMN group_id INTEGER'); } catch { /* exists */ }
   try { await client.execute('ALTER TABLE tasks ADD COLUMN closed_at INTEGER'); } catch { /* exists */ }
+  try { await client.execute("ALTER TABLE task_groups ADD COLUMN coord_session_id TEXT NOT NULL DEFAULT ''"); } catch { /* exists */ }
+  try { await client.execute("ALTER TABLE tasks ADD COLUMN outputs TEXT NOT NULL DEFAULT '[]'"); } catch { /* exists */ }
 }

package/src/db/schema.ts

@@ -37,6 +37,7 @@ export const taskGroups = sqliteTable('task_groups', {
   id: integer('id').primaryKey({ autoIncrement: true }),
   kind: text('kind').notNull().default('goal'), // 'goal' | 'swarm'
   title: text('title').notNull(),
+  coordSessionId: text('coord_session_id').notNull().default(''), // L2 — 읽기전용 Ask 코디네이터의 재개 세션(--resume 키)
   createdAt: integer('created_at', { mode: 'timestamp' }),
 });
 
@@ -48,6 +49,7 @@ export const tasks = sqliteTable('tasks', {
   prompt: text('prompt').notNull().default(''),
   status: text('status').notNull().default('open'), // open | done
   designCaptureId: integer('design_capture_id'), // 선택 — 프롬프트에 DESIGN CONTEXT 주입
+  outputs: text('outputs').notNull().default('[]'), // 산출물 계약 — 선언한 타입 JSON 배열(answer|code|doc|page|file). 빈 배열 = 계약 없음.
   parentRunId: integer('parent_run_id'), // 에이전트 셀프 오케스트레이션 — 이 태스크를 발사한 run
   groupId: integer('group_id'), // task_groups — goal/swarm 형제 묶음(수동 태스크는 NULL)
   closedAt: integer('closed_at', { mode: 'timestamp' }), // 닫힌 시각(아카이브 정렬·표시)

package/src/orchestrator.ts

@@ -13,6 +13,57 @@ import { runShellOn, spawnShellOn, shq, type MachineTarget } from './exec';
 import { broadcast } from './hub';
 import { getProvider, type Provider } from './providers';
 
+// ── 산출물 계약(deliverable contract) ─────────────────────────
+/** 산출물 타입 5종 — 태스크가 선언할 수 있는 계약 항목. */
+export const OUTPUT_TYPES = ['answer', 'code', 'doc', 'page', 'file'] as const;
+export type OutputType = (typeof OUTPUT_TYPES)[number];
+const OUTPUT_SET = new Set<string>(OUTPUT_TYPES);
+
+/** 임의 입력 → 유효한 산출물 타입 배열(중복 제거, 순서 보존). API·저장 공용. */
+export function normalizeOutputs(input: unknown): OutputType[] {
+  if (!Array.isArray(input)) return [];
+  const seen = new Set<string>();
+  const out: OutputType[] = [];
+  for (const v of input) {
+    if (typeof v === 'string' && OUTPUT_SET.has(v) && !seen.has(v)) {
+      seen.add(v);
+      out.push(v as OutputType);
+    }
+  }
+  return out;
+}
+
+/** tasks.outputs(JSON 문자열) → 산출물 타입 배열. 파싱 실패는 빈 배열. */
+export function parseOutputs(raw: string | null | undefined): OutputType[] {
+  if (!raw) return [];
+  try { return normalizeOutputs(JSON.parse(raw)); } catch { return []; }
+}
+
+/** 프롬프트에 붙는 Deliverables 블록(A3). declared 는 비어있지 않다. */
+function deliverablesNote(declared: OutputType[]): string {
+  const human: Record<OutputType, string> = {
+    answer: 'an answer', code: 'code changes', doc: 'a Markdown doc',
+    page: 'an HTML page', file: 'a file',
+  };
+  const list = declared.map((t) => human[t]).join(', ');
+  return '\n\n--- COXPIT DELIVERABLES (required) ---\n' +
+    `Deliverables (required): ${list}.\n` +
+    'Produce each as a real file in the repo (docs as .md, pages as .html). Register every ' +
+    'deliverable in .coxpit/outputs.json as a JSON array of {path,type,title}. End with a final ' +
+    'message stating the answer.\n' +
+    '--- END COXPIT DELIVERABLES ---';
+}
+
+/** 계산된 출력 카드(computeRunOutputs 반환) — 보드가 오른쪽 컬럼에 렌더. */
+export interface RunOutputCard {
+  type: OutputType;
+  title: string;
+  path?: string;
+  required: boolean;
+  present: boolean;
+  meta: string;
+}
+
 /** 에이전트 실행 커맨드. 드라이런=모의 stream-json + 실제 파일 1건 변경. */
 function agentCommand(provider: Provider, prompt: string, real: boolean, model = ''): string {
   if (real) return provider.launchCmd(prompt, model || undefined);
@@ -59,6 +110,11 @@ export function resolveAgentToken(token: string): number | null {
   return agentTokens.get(token) ?? null;
 }
 
+/** run 이 지금 살아 있는가(자식 프로세스 보유). aggregate 뷰의 live/steerable 판정용. */
+export function isRunLive(runId: number): boolean {
+  return liveChildren.has(runId);
+}
+
 /** 에이전트 프롬프트에 붙는 능력 고지 — 독립 하위작업을 병렬 서브런으로 뺄 수 있다.
  * 파일 기반: 기본 권한(claude acceptEdits · codex workspace-write)이 네트워크를 막아도
  * 파일 쓰기는 되므로, spawn 요청을 워크트리의 .coxpit/spawn.json 으로 받는다. */
@@ -236,6 +292,11 @@ async function loadContext(runId: number): Promise<RunContext | null> {
     }
   }
 
+  // 산출물 계약 — task.outputs 가 비어있지 않으면 Deliverables 블록 주입(디자인 캡처와 같은 시임).
+  // launchRun/launchGroupTask 는 모두 loadContext 를 거치므로 여기서 한 번에 커버.
+  const declared = parseOutputs(task.outputs);
+  if (declared.length) prompt += deliverablesNote(declared);
+
   return {
     runId,
     machine: { slug: m.slug, kind: m.kind, address: m.address, sshUser: m.sshUser },
@@ -549,6 +610,152 @@ export async function getRunDocs(runId: number): Promise<{
   return { ok: true, docs };
 }
 
+// ── computeRunOutputs — 산출물 카드 계산(A2/A4) ──────────────────
+interface OutputsManifestItem { path?: string; type?: string; title?: string }
+
+/** run 의 최종 답변 텍스트 — result 이벤트(payload JSON) 우선, 없으면 exitSummary. */
+async function runAnswerText(run: typeof agentRuns.$inferSelect): Promise<string> {
+  const evs = await db.select().from(agentEvents).where(eq(agentEvents.runId, run.id));
+  for (let i = evs.length - 1; i >= 0; i--) {
+    if (evs[i]!.kind !== 'result') continue;
+    try {
+      const o = JSON.parse(evs[i]!.payload) as { result?: string };
+      if (typeof o.result === 'string' && o.result.trim()) return o.result.trim();
+    } catch { /* 비-JSON result — exitSummary 로 폴백 */ }
+  }
+  return (run.exitSummary || '').trim();
+}
+
+/** 확장자 → 파생 카드 타입. code/file 은 group 만, 실제 타입은 code|page|doc|file. */
+function extType(p: string): OutputType {
+  if (/\.(md|markdown)$/i.test(p)) return 'doc';
+  if (/\.(html?|htm)$/i.test(p)) return 'page';
+  if (/\.(png|jpe?g|gif|webp|svg|bmp|ico|avif)$/i.test(p)) return 'file';
+  return 'code';
+}
+
+/** status --porcelain 한 줄 → 상대경로(따옴표·상태코드 제거). */
+function porcelainPath(line: string): string {
+  return line.slice(3).trim().replace(/^"|"$/g, '');
+}
+
+/**
+ * run 의 산출물 카드 목록을 계산(주문형, A4). 병합 순서:
+ *  (a) worktree 의 .coxpit/outputs.json 매니페스트(있으면) — declared 딜리버러블
+ *  (b) git status --porcelain → 확장자 분류(.md=doc·.html=page·이미지=file·그 외=code 집계 1장)
+ *  (c) result 이벤트의 answer 텍스트
+ * 각 카드: required = type ∈ task.outputs. declared 인데 산출물 없으면 present:false 플레이스홀더.
+ * worktree 소멸 → doc/page 는 loadRunDocs 스냅샷 폴백, code/file 은 unavailable, answer 는 이벤트.
+ */
+export async function computeRunOutputs(runId: number): Promise<RunOutputCard[]> {
+  const rr = await db.select().from(agentRuns).where(eq(agentRuns.id, runId)).limit(1);
+  const run = rr[0];
+  if (!run) return [];
+  const tr = await db.select().from(tasks).where(eq(tasks.id, run.taskId)).limit(1);
+  const task = tr[0];
+  const declared = parseOutputs(task?.outputs);
+  const declaredSet = new Set<OutputType>(declared);
+
+  const ctx = await loadContext(runId);
+  const wt = run.worktreePath;
+  // worktree 가 실제로 머신에 살아있는가(정리 후에는 스냅샷 폴백).
+  let wtAlive = false;
+  if (ctx && wt) {
+    const t = await runShellOn(ctx.machine, `test -d ${shq(wt)} && echo yes`, 8000).catch(() => ({ stdout: '' }));
+    wtAlive = (t.stdout || '').includes('yes');
+  }
+
+  const cards: RunOutputCard[] = [];
+  const present = new Set<OutputType>();
+  const codeFiles: string[] = [];
+  const fileCards: RunOutputCard[] = [];
+  const docByPath = new Map<string, RunOutputCard>();
+
+  // (c) answer — 이벤트에서(worktree 생사 무관하게 항상 회수 가능)
+  const answer = await runAnswerText(run);
+  if (answer) {
+    present.add('answer');
+    cards.push({ type: 'answer', title: 'Final answer', required: declaredSet.has('answer'), present: true, meta: 'from the run\'s final message' });
+  }
+
+  // (a) 매니페스트 — path→title 힌트로 파생 카드 제목을 예쁘게(있으면). 없으면 git 분류로 폴백.
+  const manifestTitle = new Map<string, string>();
+  if (wtAlive && ctx && wt) {
+    const mf = await runShellOn(ctx.machine, `head -c 200000 ${shq(ppath.join(wt, '.coxpit/outputs.json'))} 2>/dev/null`, 8000)
+      .catch(() => ({ ok: false, stdout: '' }));
+    if (mf.ok && mf.stdout.trim()) {
+      try {
+        const arr = JSON.parse(mf.stdout) as unknown;
+        for (const it of (Array.isArray(arr) ? arr : []) as OutputsManifestItem[]) {
+          if (it && typeof it === 'object' && typeof it.path === 'string' && typeof it.title === 'string') {
+            manifestTitle.set(it.path, it.title);
+          }
+        }
+      } catch { /* 매니페스트 깨짐 — git 분류로 폴백 */ }
+    }
+  }
+
+  if (wtAlive && ctx && wt) {
+    // (b) git status --porcelain 분류
+    const ls = await runShellOn(ctx.machine, `git -C ${shq(wt)} status --porcelain`, 15000).catch(() => ({ ok: false, stdout: '' }));
+    if (ls.ok) {
+      const paths = ls.stdout.split('\n').map(porcelainPath).filter(Boolean);
+      for (const p of paths) {
+        if (p.startsWith('.coxpit/')) continue; // 오케스트레이션 파일은 산출물 아님
+        const t = extType(p);
+        if (t === 'doc' || t === 'page') {
+          present.add(t);
+          docByPath.set(p, { type: t, title: manifestTitle.get(p) || p, path: p, required: declaredSet.has(t), present: true, meta: t === 'doc' ? 'rendered markdown' : 'live HTML page' });
+        } else if (t === 'file') {
+          present.add('file');
+          fileCards.push({ type: 'file', title: manifestTitle.get(p) || p, path: p, required: declaredSet.has('file'), present: true, meta: 'file preview' });
+        } else {
+          codeFiles.push(p);
+        }
+      }
+    }
+  } else {
+    // worktree 소멸 — doc/page 는 스냅샷 폴백, code/file 은 unavailable.
+    const snap = await loadRunDocs(runId);
+    for (const d of snap.docs) {
+      const t: OutputType = d.kind === 'html' ? 'page' : 'doc';
+      present.add(t);
+      docByPath.set(d.path, { type: t, title: manifestTitle.get(d.path) || d.path, path: d.path, required: declaredSet.has(t), present: true, meta: 'worktree cleaned — snapshot only' });
+    }
+    if (run.filesChanged > 0) {
+      // 변경은 있었으나 worktree 가 사라져 code/file diff 를 못 준다.
+      if (declaredSet.has('code')) cards.push({ type: 'code', title: 'Code changes', required: true, present: false, meta: 'worktree cleaned — diff unavailable' });
+      if (declaredSet.has('file')) cards.push({ type: 'file', title: 'File', required: true, present: false, meta: 'worktree cleaned — file unavailable' });
+    }
+  }
+
+  // doc/page 카드 편입(경로 순)
+  for (const c of docByPath.values()) cards.push(c);
+  // file 카드 편입
+  for (const c of fileCards) cards.push(c);
+  // code — 여러 파일을 한 장의 diff 카드로 집계(worktree 라이브일 때만 생성됨)
+  if (codeFiles.length) {
+    present.add('code');
+    cards.push({
+      type: 'code',
+      title: 'Code changes',
+      required: declaredSet.has('code'),
+      present: true,
+      meta: `${codeFiles.length} file(s) — colored diff`,
+    });
+  }
+
+  // declared 인데 산출물이 없으면 ⚠ present:false 플레이스홀더(soft policy).
+  // future: strict mode — auto-steer "produce the missing <type>"
+  for (const t of declared) {
+    if (present.has(t)) continue;
+    if (cards.some((c) => c.type === t && c.present === false)) continue; // worktree-gone 폴백이 이미 추가
+    cards.push({ type: t, title: `Missing ${t}`, required: true, present: false, meta: '산출물 미충족' });
+  }
+
+  return cards;
+}
+
 /**
  * base 동기화 — 오래 사는 세션의 worktree 에 base 브랜치 최신을 머지한다.
  * 충돌 시 자동 abort — 그땐 steer 로 에이전트에게 머지를 맡기라고 안내.
@@ -668,6 +875,25 @@ export async function openWorkbench(repoId: number, title: string): Promise<{
   return { ok: true, detail: 'workbench open', taskId: task.id, runId };
 }
 
+/**
+ * 그룹에 속한 태스크 1개를 만들고 run 1개를 발사한다(공용 helper).
+ * planFanout(plan 형제) 과 /api/groups/:id/spawn(＋New attempt) 이 공유하는
+ * "태스크 생성(groupId 각인) → run 생성 → 브로드캐스트 → launchRun" 몸통.
+ */
+export async function launchGroupTask(
+  groupId: number, repoId: number, title: string, prompt: string, real: boolean,
+): Promise<{ id: number; title: string; runId: number }> {
+  const rp = await db.select().from(repos).where(eq(repos.id, repoId)).limit(1);
+  const machineId = rp[0]!.machineId;
+  const tIns = await db.insert(tasks).values({ repoId, title: title.slice(0, 140), prompt, groupId }).returning();
+  const task = tIns[0]!;
+  const rIns = await db.insert(agentRuns).values({ taskId: task.id, machineId, agent: 'claude-code', status: 'pending' }).returning();
+  const run = rIns[0]!;
+  broadcast({ type: 'run', runId: run.id, taskId: task.id, status: 'pending', agent: run.agent, branch: '', filesChanged: 0 });
+  void launchRun(run.id, real);
+  return { id: task.id, title: task.title, runId: run.id };
+}
+
 /**
  * Plan fan-out — 스웜의 입구. 목표 하나를 받아 플래너 에이전트가 repo 를 읽고
  * 독립 실행 가능한 하위 태스크들로 분해 → 각 태스크를 count 1 로 자동 발사한다.
@@ -728,13 +954,7 @@ export async function planFanout(repoId: number, goal: string, real: boolean): P
 
   const created: Array<{ id: number; title: string; runId: number }> = [];
   for (const t of plan) {
-    const tIns = await db.insert(tasks).values({ repoId, title: t.title, prompt: t.prompt, groupId }).returning();
-    const task = tIns[0]!;
-    const rIns = await db.insert(agentRuns).values({ taskId: task.id, machineId: m.id, agent: 'claude-code', status: 'pending' }).returning();
-    const run = rIns[0]!;
-    broadcast({ type: 'run', runId: run.id, taskId: task.id, status: 'pending', agent: run.agent, branch: '', filesChanged: 0 });
-    void launchRun(run.id, real);
-    created.push({ id: task.id, title: t.title, runId: run.id });
+    created.push(await launchGroupTask(groupId, repoId, t.title, t.prompt, real));
   }
   return { ok: true, detail: `${created.length} task(s) launched`, tasks: created };
 }
@@ -795,6 +1015,117 @@ export async function reviewTask(taskId: number, real: boolean): Promise<{ ok: b
   }
 }
 
+/**
+ * Ask 코디네이터 — 읽기 전용, 재개 가능한 그룹 스코프 Q&A.
+ * 그룹의 형제 run 들에서 {title,status,agent,filesChanged} + 정착 run 의 bounded diff 요약을
+ * 모아 컨텍스트로 주고, 질문에 답만 한다. worktree 를 열지도, run 을 발사하지도, 파일을 쓰지도,
+ * steer 하지도 않는다 — getRunDiff(읽기)와 텍스트 반환뿐. (reviewTask 를 대화형·재개형으로 변형)
+ *
+ * 세션: 첫 호출은 1회용(`bin -p <prompt> --output-format json`)으로 session_id 를 캡처해
+ * task_groups.coord_session_id 에 저장. 이후 호출은 provider.resumeCmd 로 진짜 대화를 잇는다.
+ * 드라이(real=false / COXPIT_AGENT_REAL off)는 결정적 mock + 합성 세션 id 반환(크레딧 0, e2e 안전).
+ */
+export async function askGroupCoordinator(
+  groupId: number, message: string, real: boolean,
+): Promise<{ ok: boolean; detail: string; answer?: string }> {
+  const gr = await db.select().from(taskGroups).where(eq(taskGroups.id, groupId)).limit(1);
+  const group = gr[0];
+  if (!group) return { ok: false, detail: 'group not found' };
+  const msg = message.trim();
+  if (!msg) return { ok: false, detail: 'empty message' };
+
+  // 그룹의 형제 run 들(태스크 조인) — bounded 컨텍스트만.
+  const gts = await db.select().from(tasks).where(eq(tasks.groupId, groupId));
+  const rows: Array<{ run: typeof agentRuns.$inferSelect; task: typeof tasks.$inferSelect }> = [];
+  for (const t of gts) {
+    const trs = await db.select().from(agentRuns).where(eq(agentRuns.taskId, t.id));
+    for (const run of trs) rows.push({ run, task: t });
+  }
+  rows.sort((a, b) => a.run.id - b.run.id);
+
+  // repo/machine 은 그룹의 아무 태스크에서 상속(형제는 같은 repo 공유). read-only 는 repo 본체에서.
+  const anyTask = rows[0]?.task ?? gts[0];
+  let machine: MachineTarget | null = null;
+  let repoPath = '';
+  if (anyTask) {
+    const rp = await db.select().from(repos).where(eq(repos.id, anyTask.repoId)).limit(1);
+    const repo = rp[0];
+    if (repo) {
+      repoPath = repo.path;
+      const mr = await db.select().from(machines).where(eq(machines.id, repo.machineId)).limit(1);
+      const m = mr[0];
+      if (m) machine = { slug: m.slug, kind: m.kind, address: m.address, sshUser: m.sshUser };
+    }
+  }
+
+  // bounded 컨텍스트: run 요약 + 정착 run 의 diff 요약(각 ~1500자, 합 ~12k 상한).
+  const SETTLED = ['done', 'failed', 'stopped', 'merged'];
+  const sections: string[] = [];
+  let budget = 12000;
+  for (const { run, task } of rows) {
+    let sec = `### run r${run.id} — ${task.title.slice(0, 80)}\n`
+      + `status: ${run.status} · agent: ${run.agent} · files changed: ${run.filesChanged}`;
+    if (SETTLED.includes(run.status) && budget > 0) {
+      const d = await getRunDiff(run.id).catch(() => ({ ok: false, diff: '', stat: '' }));
+      const raw = (d.ok ? (d.diff || d.stat || '(no changes)') : '(worktree gone — diff unavailable)');
+      const cap = Math.min(1500, Math.max(0, budget));
+      const clip = raw.slice(0, cap);
+      budget -= clip.length;
+      sec += `\nDiff summary:\n\`\`\`diff\n${clip}\n\`\`\``;
+    }
+    sections.push(sec);
+  }
+
+  const preamble =
+    `You are a READ-ONLY coordinator for a goal with these parallel attempts. `
+    + `Answer the question about their state and diffs. Do NOT propose running commands, `
+    + `do NOT modify files, do NOT suggest editing anything — you can only observe and explain.`;
+  const context = `Goal: ${group.title}\n\n${sections.join('\n\n') || '(no runs yet)'}`;
+
+  // 드라이: 결정적 mock 답변 + 합성 세션 id(첫 호출 시 저장, 이후 재사용). e2e 크레딧 0.
+  if (!real) {
+    const done = rows.filter((r) => SETTLED.includes(r.run.status)).length;
+    const running = rows.filter((r) => r.run.status === 'running').length;
+    const answer = `[dry coordinator] ${rows.length} attempt(s) · ${done} settled · ${running} running.\n`
+      + `Q: ${msg.slice(0, 120)}\n`
+      + `(rehearsal answer — read-only; run with Real agent for a substantive reply.)`;
+    if (!group.coordSessionId) {
+      const synth = 'dry-coord-' + randomBytes(6).toString('hex');
+      await db.update(taskGroups).set({ coordSessionId: synth }).where(eq(taskGroups.id, groupId));
+    }
+    return { ok: true, detail: 'rehearsal answer', answer };
+  }
+
+  if (!machine || !repoPath) return { ok: false, detail: 'group has no repo to run the coordinator from' };
+
+  // 첫 호출 = 1회용(session_id 캡처), 이후 = resume(대화 이어가기). 둘 다 파일 미변경 read-only.
+  const provider = getProvider('claude-code');
+  let cmd: string;
+  const resuming = !!group.coordSessionId;
+  if (resuming) {
+    // resume 은 stream-json 을 내지만 여기선 마지막 result 만 필요 — json 으로 강제 재래핑 불가하므로
+    // 세션 id 는 이미 있으니 resumeCmd(대화)로 잇고, 최종 텍스트는 result 라인에서 추출한다.
+    cmd = `cd ${shq(repoPath)} && ${provider.resumeCmd(group.coordSessionId, `${preamble}\n\n${context}\n\nQuestion: ${msg}`)} --output-format json`;
+  } else {
+    const oneShot = `${preamble}\n\n${context}\n\nQuestion: ${msg}`;
+    cmd = `cd ${shq(repoPath)} && ${config.agent.bin} -p ${shq(oneShot)} --output-format json`;
+  }
+  const r = await runShellOn(machine, cmd, 300000);
+  if (!r.ok) return { ok: false, detail: 'coordinator failed: ' + (r.stderr || r.stdout).trim().slice(0, 300) };
+  try {
+    const envelope = JSON.parse(r.stdout.trim()) as { result?: string; session_id?: string };
+    const answer = (envelope.result ?? '').trim();
+    if (!answer) throw new Error('empty answer');
+    // 첫 호출에서만 세션 각인(이후엔 유지). resume 응답도 같은 세션이라 덮어써도 무해.
+    if (typeof envelope.session_id === 'string' && envelope.session_id && envelope.session_id !== group.coordSessionId) {
+      await db.update(taskGroups).set({ coordSessionId: envelope.session_id }).where(eq(taskGroups.id, groupId));
+    }
+    return { ok: true, detail: resuming ? 'resumed' : 'answered', answer };
+  } catch (e) {
+    return { ok: false, detail: 'could not parse coordinator answer: ' + String(e).slice(0, 200) };
+  }
+}
+
 export interface IntegrateResult {
   runId: number;
   status: 'merged' | 'conflict' | 'skipped';
@@ -980,5 +1311,120 @@ export async function cleanupRun(runId: number): Promise<{ ok: boolean; detail:
     ` ; git -C ${shq(ctx.repoPath)} branch -D ${shq(run.branch)} 2>&1 || true`,
     20000,
   );
+  // 세션·worktree 는 이제 없다 — 스테일 포인터를 비운다. 안 그러면 getRunTermInfo 가
+  // 죽은 tmux 이름을 계속 돌려줘 /ws/term/:id 가 없는 세션에 attach 를 시도한다(closed task 버그).
+  await setRun(runId, { worktreePath: '', tmuxWindow: '' });
   return { ok: true, detail: rm.stdout.trim().slice(0, 300) };
 }
+
+// ── 고아 worktree 회수(reclaim) ────────────────────────────────
+// run worktree 는 종종 node_modules 를 품어 ~180MB 의 디스크 빚이 된다. Close 는
+// cleanupRun 으로 이미 정리하지만, 실패·에러·데몬 재시작으로 고아가 된 run 은
+// (검수용으로) worktree 를 남겨두므로 쌓인다. 이를 안전하게 되찾는 길.
+//
+// 안전 규칙(핵심): running/preparing/pending/'done' run 은 절대 대상 아님 —
+// 활성 작업이거나(진행 중), 성공했지만 아직 머지 안 됐을 수 있는 작업이므로.
+
+/** 회수 대상 판정용 안전 상태 집합 — task 가 closed 이거나 run 상태가 이 중 하나. */
+const RECLAIM_STATUSES = new Set(['failed', 'error', 'stopped']);
+
+export interface ReclaimableWorktree {
+  runId: number;
+  path: string;
+  branch: string;
+  taskId: number;
+  reason: string; // 'task closed' | 'failed' | 'error' | 'stopped'
+  exists: boolean; // worktree dir 가 아직 디스크에 있나(false = 이미 수동 삭제됨)
+  sizeKb?: number; // best-effort du -sk (실패 시 생략)
+}
+
+/**
+ * 안전하게 회수 가능한 worktree 목록. worktreePath 가 비어있지 않은 모든 run 중
+ * (a) task 가 closed 이거나 (b) run 상태 ∈ {failed, error, stopped} 인 것만.
+ * running/preparing/pending/'done'/'open'/'merged' 는 절대 포함하지 않는다
+ * (활성 또는 성공-미머지 가능성). exists=디스크 잔존 여부, sizeKb=best-effort du.
+ */
+export async function listReclaimableWorktrees(): Promise<ReclaimableWorktree[]> {
+  const allRuns = (await db.select().from(agentRuns)).filter((r) => !!r.worktreePath);
+  // task 상태 룩업(closed 판정용)
+  const taskById = new Map<number, typeof tasks.$inferSelect>();
+  for (const t of await db.select().from(tasks)) taskById.set(t.id, t);
+
+  const out: ReclaimableWorktree[] = [];
+  for (const run of allRuns) {
+    if (isRunLive(run.id)) continue; // 라이브 자식 보유 = 실행 중, 절대 건드리지 않음
+    const task = taskById.get(run.taskId);
+    const taskClosed = task?.status === 'closed';
+    const statusReclaim = RECLAIM_STATUSES.has(run.status);
+    if (!taskClosed && !statusReclaim) continue; // done/open/merged/running/preparing/pending 제외
+    const reason = taskClosed ? 'task closed' : run.status;
+
+    // worktree 잔존 여부 + best-effort 사이즈(로컬만 정확; 원격은 machine 경유).
+    const ctx = await loadContext(run.id).catch(() => null);
+    let exists = false;
+    let sizeKb: number | undefined;
+    if (ctx) {
+      const chk = await runShellOn(ctx.machine, `test -d ${shq(run.worktreePath)} && echo yes`, 8000)
+        .catch(() => ({ stdout: '' as string }));
+      exists = (chk.stdout || '').includes('yes');
+      if (exists) {
+        // du 는 큰 트리에서 느릴 수 있어 타임아웃으로 가드 — 실패해도 목록은 낸다.
+        const du = await runShellOn(ctx.machine, `du -sk ${shq(run.worktreePath)} 2>/dev/null | cut -f1`, 8000)
+          .catch(() => ({ ok: false as boolean, stdout: '' as string }));
+        const n = parseInt((du.stdout || '').trim(), 10);
+        if (du.ok && Number.isFinite(n) && n > 0) sizeKb = n;
+      }
+    }
+    out.push({ runId: run.id, path: run.worktreePath, branch: run.branch, taskId: run.taskId, reason, exists, sizeKb });
+  }
+  return out;
+}
+
+/**
+ * 회수 실행 — 대상 run(전체 또는 runIds 부분집합)의 worktree 를 되찾는다.
+ * dir 가 아직 있으면 cleanupRun 재사용(tmux kill + git worktree remove + branch -D + 포인터 blank).
+ * dir 가 이미 수동 삭제됐으면 git worktree prune + branch -D + DB 포인터 blank 만.
+ * 마지막에 영향받은 repo 마다 git worktree prune 1회(스테일 메타데이터 정리).
+ * 멱등 — 다시 돌려도 안전(이미 회수된 run 은 worktreePath 가 비어 목록에서 빠짐).
+ */
+export async function pruneWorktrees(runIds?: number[]): Promise<{
+  removed: Array<{ runId: number; detail: string }>; count: number;
+}> {
+  const reclaimable = await listReclaimableWorktrees();
+  const want = runIds && runIds.length ? new Set(runIds) : null;
+  const targets = want ? reclaimable.filter((r) => want.has(r.runId)) : reclaimable;
+
+  const removed: Array<{ runId: number; detail: string }> = [];
+  const affectedRepoPaths = new Map<string, MachineTarget>(); // repoPath -> machine (prune 대상)
+
+  for (const t of targets) {
+    const ctx = await loadContext(t.runId).catch(() => null);
+    if (ctx) affectedRepoPaths.set(ctx.repoPath, ctx.machine);
+    if (t.exists) {
+      // dir 잔존 — cleanupRun 이 tmux·worktree remove --force·branch -D·포인터 blank 를 모두 처리.
+      const res = await cleanupRun(t.runId).catch((e) => ({ ok: false, detail: String(e).slice(0, 200) }));
+      removed.push({ runId: t.runId, detail: res.detail || (res.ok ? 'removed' : 'cleanup failed') });
+    } else if (ctx) {
+      // dir 는 이미 수동 삭제 — git 이 여전히 스테일 worktree 를 물고 있다. prune + branch -D + 포인터 blank.
+      const r = await runShellOn(
+        ctx.machine,
+        `git -C ${shq(ctx.repoPath)} worktree prune 2>&1` +
+        `${t.branch ? ` ; git -C ${shq(ctx.repoPath)} branch -D ${shq(t.branch)} 2>&1 || true` : ''}`,
+        20000,
+      ).catch(() => ({ stdout: '' as string }));
+      await setRun(t.runId, { worktreePath: '', tmuxWindow: '' });
+      removed.push({ runId: t.runId, detail: (r.stdout || '').trim().slice(0, 200) || 'dir already gone — pruned metadata' });
+    } else {
+      // context 없음(repo/machine 소실) — 최소한 DB 포인터라도 비운다.
+      await setRun(t.runId, { worktreePath: '', tmuxWindow: '' });
+      removed.push({ runId: t.runId, detail: 'context missing — cleared DB pointer' });
+    }
+  }
+
+  // repo 마다 worktree prune 1회 — 스테일 메타데이터를 확실히 청소(멱등).
+  for (const [repoPath, machine] of affectedRepoPaths) {
+    await runShellOn(machine, `git -C ${shq(repoPath)} worktree prune 2>/dev/null || true`, 15000).catch(() => { /* best-effort */ });
+  }
+
+  return { removed, count: removed.length };
+}