coxpit 4.6.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 (
@@ -99,4 +100,5 @@ export async function ensureSchema(): Promise<void> {
   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

@@ -49,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);
@@ -241,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 },
@@ -554,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 로 에이전트에게 머지를 맡기라고 안내.
@@ -1109,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 };
+}

package/src/server.ts

@@ -1,7 +1,7 @@
-import { readFile, readdir } from 'node:fs/promises';
+import { readFile, readdir, realpath, stat } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { resolve as presolve, dirname as pdirname, join as pjoin } from 'node:path';
+import { resolve as presolve, dirname as pdirname, join as pjoin, sep as psep } from 'node:path';
 import { createRequire } from 'node:module';
 import { randomBytes } from 'node:crypto';
 import Fastify, { type FastifyInstance } from 'fastify';
@@ -13,7 +13,7 @@ import { db } from './db';
 import { machines, repos, tasks, agentRuns, agentEvents, designCaptures, shareLinks, taskGroups } 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 } from './orchestrator';
+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 } from './orchestrator';
 import { openTerm } from './term';
 import { addSink, removeSink, broadcast } from './hub';
 import { getProvider, listProviders } from './providers';
@@ -50,6 +50,19 @@ function mdLiteHTML(src: string): string {
   return s;
 }
 
+/** 확장자 → content-type 추론(파일 미리보기용). 미지 = octet-stream. */
+function contentTypeFor(path: string): string {
+  const ext = (path.split('.').pop() ?? '').toLowerCase();
+  const map: Record<string, string> = {
+    png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', gif: 'image/gif',
+    webp: 'image/webp', svg: 'image/svg+xml', bmp: 'image/bmp', ico: 'image/x-icon',
+    avif: 'image/avif', pdf: 'application/pdf', txt: 'text/plain; charset=utf-8',
+    md: 'text/plain; charset=utf-8', json: 'application/json', csv: 'text/csv; charset=utf-8',
+    html: 'text/html; charset=utf-8', htm: 'text/html; charset=utf-8',
+  };
+  return map[ext] ?? 'application/octet-stream';
+}
+
 /** 공유 페이지 Documents 섹션 — md 는 mdLiteHTML, html 은 sandbox iframe. */
 function shareDocsHTML(docs: Array<{ path: string; kind: string; content: string }>): string {
   if (!docs.length) return '';
@@ -242,6 +255,23 @@ export async function buildServer(): Promise<FastifyInstance> {
     return { total: total0, rows };
   });
 
+  // 회수 가능한 고아 worktree — closed task 또는 failed/error/stopped run 의 worktree 만.
+  // running/preparing/pending/done 은 절대 포함 안 됨(활성·성공-미머지 보호). authGate 뒤.
+  app.get('/api/worktrees', async () => {
+    const items = await listReclaimableWorktrees();
+    const totalKb = items.reduce((s, w) => s + (w.sizeKb || 0), 0);
+    return { items, totalKb };
+  });
+
+  // 회수 실행 — body.runIds(선택 부분집합) 또는 전체. cleanupRun 재사용 + git worktree prune.
+  app.post('/api/worktrees/prune', async (req) => {
+    const b = (req.body ?? {}) as { runIds?: number[] };
+    const runIds = Array.isArray(b.runIds)
+      ? b.runIds.map((n) => Number(n)).filter((n) => Number.isInteger(n))
+      : undefined;
+    return pruneWorktrees(runIds);
+  });
+
   // ─── 머신 레지스트리 ────────────────────────────────────────────
   app.get('/api/machines', async () => ({ machines: await db.select().from(machines) }));
 
@@ -578,7 +608,7 @@ export async function buildServer(): Promise<FastifyInstance> {
   });
 
   app.post('/api/tasks', async (req, reply) => {
-    const b = (req.body ?? {}) as { repoId?: number; title?: string; prompt?: string; designCaptureId?: number };
+    const b = (req.body ?? {}) as { repoId?: number; title?: string; prompt?: string; designCaptureId?: number; outputs?: unknown };
     const repoId = Number(b.repoId);
     const title = (b.title ?? '').trim();
     if (!repoId || !title) return reply.code(400).send({ error: 'repoId and title required' });
@@ -590,7 +620,9 @@ export async function buildServer(): Promise<FastifyInstance> {
       if (!dc[0]) return reply.code(404).send({ error: 'design capture not found' });
       designCaptureId = dc[0].id;
     }
-    const ins = await db.insert(tasks).values({ repoId, title, prompt: b.prompt ?? '', designCaptureId }).returning();
+    // 산출물 계약(선택) — {answer,code,doc,page,file} 만 허용, 중복 제거, JSON 문자열로 저장.
+    const outputs = normalizeOutputs(b.outputs);
+    const ins = await db.insert(tasks).values({ repoId, title, prompt: b.prompt ?? '', designCaptureId, outputs: JSON.stringify(outputs) }).returning();
     return reply.code(201).send({ ok: true, task: ins[0] });
   });
 
@@ -791,6 +823,8 @@ export async function buildServer(): Promise<FastifyInstance> {
       runId: run.id, taskId: task.id, title: task.title, status: run.status,
       agent: run.agent, model: run.model, branch: run.branch, filesChanged: run.filesChanged,
       live: isRunLive(run.id), steerable: isSteerable(run),
+      // 수렴 콕핏 결정 행용: 태스크 닫힘 여부 + worktree 생존(터미널 가드·머지 가능성 판단).
+      taskStatus: task.status, hasWorktree: !!run.worktreePath,
     }));
     const runIds = g.rows.map((x) => x.run.id);
     // 이벤트: 그룹 run 전체에서 최근 200개(id 순, 오래된 것 먼저 — 방 피드는 append-only).
@@ -930,6 +964,96 @@ export async function buildServer(): Promise<FastifyInstance> {
     return { ok: true, docs, source };
   });
 
+  // ─── 산출물 계약(v4.7 P1) — 카드 목록 · 뷰어 콘텐츠 · 파일 바이트 ──
+  // 카드 목록: computeRunOutputs 로 병합(매니페스트+git status+answer). 404 = run 없음.
+  app.get('/api/runs/:id/outputs', 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' });
+    const outputs = await computeRunOutputs(id);
+    return { outputs };
+  });
+
+  // 뷰어 콘텐츠: answer/doc → md, page → html(둘 다 loadRunDocs 폴백 재사용).
+  // code 는 별도 콘텐츠 없음 — 클라이언트가 기존 /api/runs/:id/diff 를 재사용한다.
+  app.get('/api/runs/:id/output', async (req, reply) => {
+    const id = Number((req.params as { id: string }).id);
+    const q = (req.query ?? {}) as { type?: string; path?: string };
+    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' });
+    const type = (q.type ?? '').trim();
+    if (type === 'answer') {
+      const cards = await computeRunOutputs(id);
+      const has = cards.some((c) => c.type === 'answer' && c.present);
+      const content = has ? (rr[0].exitSummary || '') : '';
+      // answer 본문은 result 이벤트가 원천 — exitSummary 는 그 클립(≤500자)이라 여기선 이벤트 우선.
+      const evs = await db.select().from(agentEvents).where(eq(agentEvents.runId, id));
+      let answer = content;
+      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()) { answer = o.result.trim(); break; } } catch { /* skip */ }
+      }
+      return { kind: 'md', content: answer };
+    }
+    if (type === 'doc' || type === 'page') {
+      const wantKind = type === 'doc' ? 'md' : 'html';
+      const { docs } = await loadRunDocs(id); // worktree→snapshot 폴백 내장
+      const path = (q.path ?? '').trim();
+      const doc = path ? docs.find((d) => d.path === path) : docs.find((d) => d.kind === wantKind);
+      if (!doc) return reply.code(404).send({ error: 'output not found' });
+      return { kind: doc.kind === 'html' ? 'html' : 'md', content: doc.content };
+    }
+    if (type === 'code') {
+      // code 는 콘텐츠 뷰어가 없다 — 컬러 diff 는 클라이언트가 /api/runs/:id/diff 로 재사용.
+      return { kind: 'diff', diffUrl: `/api/runs/${id}/diff` };
+    }
+    return reply.code(400).send({ error: 'type must be one of answer|doc|page|code' });
+  });
+
+  // 파일 바이트(NEW · 보안 임계) — 이미지/바이너리 미리보기용 raw bytes.
+  // 가드: worktree 루트 기준으로 path 를 해석하고, realpath 가 worktree 밖으로
+  // 벗어나면(.. / 절대경로 / 심볼릭링크 탈출) 거부. 크기 상한 ~10MB. worktree 소멸 후 404.
+  const FILE_MAX = 10 * 1024 * 1024;
+  app.get('/api/runs/:id/file', async (req, reply) => {
+    const id = Number((req.params as { id: string }).id);
+    const q = (req.query ?? {}) as { path?: string };
+    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 rel = (q.path ?? '').trim();
+    if (!rel) return reply.code(400).send({ error: 'path required' });
+    // 절대경로 즉시 거부(worktree 밖 강제)
+    if (rel.startsWith('/') || /^[a-zA-Z]:[\\/]/.test(rel)) return reply.code(400).send({ error: 'path must be relative' });
+    if (!run.worktreePath) return reply.code(404).send({ error: 'no worktree' });
+
+    // 원격 머신 파일은 데몬 파일시스템에 없다 — export 와 동일하게 로컬 전용.
+    const mr = await db.select().from(machines).where(eq(machines.id, run.machineId)).limit(1);
+    const mach = mr[0];
+    const isRemote = !!mach && mach.kind !== 'local' && (mach.address ?? '') !== '';
+    if (isRemote) return reply.code(400).send({ error: 'remote file preview not supported' });
+
+    // worktree 루트를 realpath 로 정규화(심링크 해소된 canonical base).
+    let rootReal: string;
+    try { rootReal = await realpath(run.worktreePath); }
+    catch { return reply.code(404).send({ error: 'worktree gone' }); }
+    // 요청 경로 = 루트에 join 후 realpath — 심링크 탈출까지 잡는다.
+    const joined = presolve(rootReal, rel);
+    let targetReal: string;
+    try { targetReal = await realpath(joined); }
+    catch { return reply.code(404).send({ error: 'file not found' }); }
+    // realpath 결과가 worktree 루트 하위가 아니면 탈출 — 거부.
+    const rootWithSep = rootReal.endsWith(psep) ? rootReal : rootReal + psep;
+    if (targetReal !== rootReal && !targetReal.startsWith(rootWithSep)) {
+      return reply.code(403).send({ error: 'path escapes the worktree' });
+    }
+    let st;
+    try { st = await stat(targetReal); } catch { return reply.code(404).send({ error: 'file not found' }); }
+    if (!st.isFile()) return reply.code(404).send({ error: 'not a file' });
+    if (st.size > FILE_MAX) return reply.code(413).send({ error: 'file too large (>10MB)' });
+    const buf = await readFile(targetReal);
+    return reply.type(contentTypeFor(rel)).send(buf);
+  });
+
   // ─── 에이전트 셀프 오케스트레이션 (run 별 Bearer 토큰 — authGate 예외, 여기서 자체 검증) ──
   const agentAuth = (req: { headers: { authorization?: string } }): number | null => {
     const h = req.headers.authorization ?? '';
@@ -1043,7 +1167,13 @@ export async function buildServer(): Promise<FastifyInstance> {
     const rows = Math.max(5, Math.min(200, Number(q.rows) || 24));
     const info = await getRunTermInfo(id);
     if (!info) {
-      socket.send(JSON.stringify({ t: 'err', d: 'run or tmux session not found' }));
+      // tmuxWindow 가 없음 = 세션이 정리됐거나(닫힌 task·cleanup) run 미존재.
+      // 죽은 세션에 attach 를 시도하지 말고 명확한 사유로 닫는다.
+      const rr = await db.select().from(agentRuns).where(eq(agentRuns.id, id)).limit(1);
+      const d = rr[0]
+        ? 'terminal unavailable — worktree cleaned (run closed or cleaned up)'
+        : 'run not found';
+      socket.send(JSON.stringify({ t: 'err', d }));
       socket.close();
       return;
     }