elanous 0.2.22 → 0.2.24

package/src/task-agent/review-prior-fix.ts

@@ -0,0 +1,146 @@
+/**
+ * REVIEW-CONVERGE-PRIOR-FIX — TA 가 같은 PR 에 «다시» 거는 리뷰가 직전 라운드를 보게 한다.
+ *
+ * - 왜: `liveReviewIntent` 의 «직전 반영분» 칸은 늘 «런 X 이 Y 로 멈춤 — 수확 가능» 고정 문면이었다 — 직전 리뷰의 must-fix 도,
+ *   그 뒤 바뀐 머리 범위도 없었다. 그래서 리뷰어가 head 마다 PR 전체를 처음부터 다시 보고 «새» must-fix 를 하나씩 냈고
+ *   (실측 10-11 PR #26030: ecd32f7c02 → c35d7be0cd 라운드마다 새 지적) REJUDGE 상한 3 에 걸려 TA 경로가 닫혔다.
+ * - 무엇을: 같은 PR 의 «두 번째 이후» 리뷰 요청에서만 intent 에 ① 직전 머리 → 지금 머리 diff 요약(파일·줄 수)
+ *   ② 직전 리뷰의 must-fix 목록(결과 파일 `review-results/<card>-<pr>-<head12>.json` — 못 읽으면 «직전 결과 미회수»)
+ *   ③ 스코프 경계 한 줄(바뀌지 않은 줄의 새 must-fix 는 근거 줄을 대라)을 싣는다. 첫 리뷰는 종전 문면 그대로다.
+ * - 하지 않는 것: 판정 로직(must-fix 0 규칙 · #25962 · #26036)은 손대지 않는다. 새 결함을 «금지»하지 않는다 — 근거 줄을 요구할 뿐이다.
+ * - 관측: `task-agent` · `review-prior-fix-filled {card, pr, fromHead, toHead, priorMustFix}`(호출부가 남긴다).
+ */
+import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import type { TaskCard } from './task-hand.js';
+
+const SHA40 = /^[0-9a-f]{40}$/i;
+const MAX_ITEMS = 10;
+const MAX_ITEM_CHARS = 600;
+const MAX_FILES = 20;
+
+export const PRIOR_RESULT_NOT_RECOVERED = '직전 결과 미회수';
+export const PRIOR_FIX_SCOPE_LINE = '이번 리뷰는 직전 must-fix 가 해결됐는지 ⊕ 그 사이 바뀐 줄에서 새 결함이 생겼는지를 본다 · 직전에 이미 본 바뀌지 않은 줄에서 새 must-fix 를 만들지 말 것(새 결함이 확실하면 근거 줄을 대라)';
+
+type ReviewRequest = NonNullable<TaskCard['reviewRequests']>[number];
+
+export interface PriorDiffFile { path: string; added: number | null; deleted: number | null }
+export interface PriorDiff { files: PriorDiffFile[]; added: number; deleted: number }
+/** 직전 머리 → 지금 머리 diff — 못 재면 null(«0 줄»이 아니라 «미측정»). */
+export type PriorDiffReader = (cwd: string | undefined, fromHead: string, toHead: string) => PriorDiff | null;
+
+export type PriorMustFix =
+  | { status: 'recovered'; items: string[] }
+  | { status: 'not-recovered'; reason: string };
+
+export interface PriorFixContext {
+  fromHead: string;
+  toHead: string;
+  diff: PriorDiff | null;
+  mustFix: PriorMustFix;
+}
+
+/** 같은 PR 의 직전 요청 — 지금 머리가 아닌 것 중 마지막(띄우기 오류가 난 요청은 리뷰가 안 돌았으니 건너뛴다). */
+export function priorReviewRequest(requests: readonly ReviewRequest[] | undefined, pr: number, head: string): ReviewRequest | undefined {
+  return (requests ?? []).filter((entry) => entry.pr === pr && entry.head !== head && !entry.error && SHA40.test(entry.head)).at(-1);
+}
+
+/**
+ * 결과 파일에서 must-fix «문면»을 읽는다 — `self review --json` 의 결과 줄(뒤에서부터 첫 결과 모양)만.
+ * 결과 모양 판정은 `parseReviewResultOutput` 과 같다(PR 번호 ⊕ (verdict ⊕ mustFix 배열 | error 문자열)).
+ */
+export function readPriorMustFix(path: string | undefined, pr: number, read: (path: string) => string = (p) => readFileSync(p, 'utf8')): PriorMustFix {
+  if (!path) return { status: 'not-recovered', reason: 'no result path' };
+  let text: string;
+  try { text = read(path); } catch (error) {
+    const code = (error as NodeJS.ErrnoException)?.code;
+    return { status: 'not-recovered', reason: code === 'ENOENT' ? 'result file not created' : `result file unreadable (${code ?? 'error'})` };
+  }
+  const lines = text.split('\n').map((line) => line.trim()).filter(Boolean);
+  for (let i = lines.length - 1; i >= 0; i -= 1) {
+    const line = lines[i]!;
+    if (!line.startsWith('{')) continue;
+    let value: unknown;
+    try { value = JSON.parse(line); } catch { continue; }
+    if (!value || typeof value !== 'object' || Array.isArray(value)) continue;
+    const v = value as Record<string, unknown>;
+    const isResult = v.pr !== undefined && (('verdict' in v && Array.isArray(v.mustFix)) || typeof v.error === 'string');
+    if (!isResult) continue;
+    const prRaw = typeof v.pr === 'number' ? v.pr : typeof v.pr === 'string' ? Number(String(v.pr).replace(/^#/, '')) : NaN;
+    if (prRaw !== pr) return { status: 'not-recovered', reason: `result PR ${Number.isFinite(prRaw) ? prRaw : 'unknown'} does not match #${pr}` };
+    if (typeof v.error === 'string') return { status: 'not-recovered', reason: `prior review error: ${v.error.slice(0, 200)}` };
+    if (v.reviewed === false) return { status: 'not-recovered', reason: 'prior review did not run (reviewed:false)' };
+    if (!Array.isArray(v.mustFix) || !v.mustFix.every((fix) => typeof fix === 'string')) return { status: 'not-recovered', reason: 'must-fix list unreadable' };
+    return { status: 'recovered', items: v.mustFix as string[] };
+  }
+  return { status: 'not-recovered', reason: text.trim() ? 'output has no JSON result line' : 'result file empty' };
+}
+
+/** 기본 diff — `git diff --numstat <from> <to>`(그 PR 의 저장소 cwd). 커밋이 없거나 git 이 실패하면 null. */
+export const defaultPriorDiff: PriorDiffReader = (cwd, fromHead, toHead) => {
+  if (!SHA40.test(fromHead) || !SHA40.test(toHead)) return null;
+  const out = spawnSync('git', ['diff', '--numstat', fromHead, toHead], { encoding: 'utf8', timeout: 20_000, ...(cwd ? { cwd } : {}) });
+  if (out.error || out.status !== 0 || typeof out.stdout !== 'string') return null;
+  return parseNumstat(out.stdout);
+};
+
+export function parseNumstat(text: string): PriorDiff {
+  const files: PriorDiffFile[] = [];
+  let added = 0;
+  let deleted = 0;
+  for (const line of text.split('\n')) {
+    const match = /^(\d+|-)\t(\d+|-)\t(.+)$/.exec(line);
+    if (!match) continue;
+    const a = match[1] === '-' ? null : Number(match[1]);
+    const d = match[2] === '-' ? null : Number(match[2]);
+    files.push({ path: match[3]!, added: a, deleted: d });
+    added += a ?? 0;
+    deleted += d ?? 0;
+  }
+  return { files, added, deleted };
+}
+
+/** 두 번째 이후 리뷰의 맥락 — 직전 요청이 없으면 null(첫 리뷰 · 종전 문면). */
+export function buildPriorFixContext(
+  card: TaskCard, pr: number, head: string,
+  opts: { cwd?: string; priorDiff?: PriorDiffReader; readFile?: (path: string) => string } = {},
+): PriorFixContext | null {
+  const prior = priorReviewRequest(card.reviewRequests, pr, head);
+  if (!prior) return null;
+  let diff: PriorDiff | null;
+  try { diff = (opts.priorDiff ?? defaultPriorDiff)(opts.cwd, prior.head, head); } catch { diff = null; }
+  return { fromHead: prior.head, toHead: head, diff, mustFix: readPriorMustFix(prior.resultPath, pr, opts.readFile) };
+}
+
+/** «직전 반영분» 블록 — 종전 런 줄 다음에 붙는다. */
+export function priorFixBlock(ctx: PriorFixContext): string {
+  const lines = [`직전 리뷰 머리 → 지금 머리: ${ctx.fromHead.slice(0, 12)} → ${ctx.toHead.slice(0, 12)}`];
+  if (ctx.diff) {
+    lines.push(`그 사이 바뀐 것: 파일 ${ctx.diff.files.length}개 · +${ctx.diff.added} −${ctx.diff.deleted}`);
+    for (const file of ctx.diff.files.slice(0, MAX_FILES)) lines.push(`  - ${file.path} (+${file.added ?? '?'} −${file.deleted ?? '?'})`);
+    if (ctx.diff.files.length > MAX_FILES) lines.push(`  - … 외 ${ctx.diff.files.length - MAX_FILES}개`);
+  } else {
+    lines.push('그 사이 바뀐 것: diff 미측정(이 저장소에서 두 머리를 비교하지 못했다)');
+  }
+  if (ctx.mustFix.status === 'recovered') {
+    if (ctx.mustFix.items.length === 0) lines.push('직전 리뷰 must-fix: 0건');
+    else {
+      lines.push(`직전 리뷰 must-fix ${ctx.mustFix.items.length}건:`);
+      ctx.mustFix.items.slice(0, MAX_ITEMS).forEach((item, index) => lines.push(`  ${index + 1}. ${item.replace(/\s+/g, ' ').trim().slice(0, MAX_ITEM_CHARS)}`));
+      if (ctx.mustFix.items.length > MAX_ITEMS) lines.push(`  … 외 ${ctx.mustFix.items.length - MAX_ITEMS}건`);
+    }
+  } else {
+    lines.push(`직전 리뷰 must-fix: ${PRIOR_RESULT_NOT_RECOVERED} (${ctx.mustFix.reason}) — 목록이 없다고 «0건»으로 읽지 말 것`);
+  }
+  return lines.join('\n');
+}
+
+/** 관측 칸 — must-fix 수(미회수면 null). */
+export function priorFixObservation(cardId: string, pr: number, ctx: PriorFixContext): Record<string, unknown> {
+  return {
+    card: cardId, pr, fromHead: ctx.fromHead, toHead: ctx.toHead,
+    priorMustFix: ctx.mustFix.status === 'recovered' ? ctx.mustFix.items.length : null,
+    ...(ctx.mustFix.status === 'not-recovered' ? { priorResult: 'not-recovered', priorResultReason: ctx.mustFix.reason } : {}),
+    diffFiles: ctx.diff ? ctx.diff.files.length : null,
+  };
+}

package/src/task-agent/review-result-capture.ts

@@ -0,0 +1,218 @@
+/**
+ * TA-REVIEW-RESULT-CAPTURE — live `review` 수가 떼어 띄운 `self review --json` 의 결과를 «파일로» 받아 카드에 되돌린다.
+ *
+ * - 왜: `defaultRequestReview` 는 리뷰를 떼어 띄우고(stdio ignore) spawn 만 확인했다 — `self review` 는 PR 코멘트를 안 달고
+ *   결과를 `--json` stdout ⊕ logs 에만 낸다. stdout 을 버리니 TA 는 판정을 영영 못 받았다(카드 줄 «result not received»).
+ * - 무엇을: 띄울 때 자식 stdout 을 `<상태 파일 디렉터리>/review-results/<card>-<pr>-<head12>.json` 로 받는다(떼어 띄움 유지 ·
+ *   TA 루프는 안 막는다). 경로는 `reviewRequests[]` 항목 ⊕ live-move 줄에 `resultPath` 로 싣는다.
+ * - 회수: 다음 TA 판단 틱(`recordTaskAgentShadowMove`) · `tasks show <card>` 가 그 파일을 읽어 같은 카드 history 에
+ *   `live-move-result` 줄을 «한 번» 덧붙인다. 파일이 «대기 상한» 지나도 결과가 없으면 `review process produced no result` 줄.
+ *   지어내지 않는다 — 읽은 JSON 의 칸만 옮긴다.
+ * - 관측: `task-agent` · `review-result-captured` / `review-result-missing`.
+ */
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { debug } from '../debug/log.js';
+import { LIVE_MOVE_RESULT_EVENT, readTaskAgentState, updateTaskCard, type TaskCard, type TaskCardEvent } from './task-hand.js';
+
+export const REVIEW_RESULT_MISSING_EFFECT = 'review process produced no result';
+/** 결과 파일은 있는데 읽지 못했다(EACCES 등) — «결과 없음»과 가른다(결과가 있었을 수 있다). */
+export const REVIEW_RESULT_UNREADABLE_EFFECT = 'review result file unreadable';
+/** 리뷰 한 판(1차 ⊕ 폴백 · ACP 300s 상한 여러 번)을 넉넉히 덮는 대기 상한 — 이 안에는 «아직»으로 본다. */
+export const REVIEW_RESULT_WAIT_MS = 90 * 60_000;
+
+const SHA40 = /^[0-9a-f]{40}$/i;
+
+/** 결과 파일 경로 — 카드 상태 파일 옆 `review-results/` · 카드 id 는 파일 이름에 안전한 글자만. */
+export function reviewResultPath(statePath: string, cardId: string, pr: number, head: string): string {
+  const safe = (value: string) => value.replace(/[^A-Za-z0-9._-]/g, '_');
+  return join(dirname(statePath), 'review-results', `${safe(cardId)}-${pr}-${safe(head.slice(0, 12))}.json`);
+}
+
+export interface ParsedReviewResult {
+  pr?: number;
+  verdict: string | null;
+  reviewed: boolean | null;
+  /** must-fix 목록이 문자열 배열일 때만 수 — 아니면 null(«0» 이 아니라 «모름»). */
+  mustFix: number | null;
+  reviewRoute: string | null;
+  /** 리뷰가 읽은 머리(`headCommit`) — 40자 sha 일 때만. */
+  head: string | null;
+  error: string | null;
+}
+
+/**
+ * `self review --json` stdout 을 해석한다 — 그 stdout 에는 다른 줄이 섞일 수 있어 «뒤에서부터» 첫 JSON 객체 줄을 쓴다.
+ * 못 읽으면 null(쓰는 중이거나 자식이 죽었다 — 판단은 호출자가 시각으로 한다).
+ */
+export function parseReviewResultOutput(text: string): ParsedReviewResult | null {
+  const lines = text.split('\n').map((line) => line.trim()).filter(Boolean);
+  for (let i = lines.length - 1; i >= 0; i -= 1) {
+    const line = lines[i]!;
+    if (!line.startsWith('{')) continue;
+    let value: unknown;
+    try { value = JSON.parse(line); } catch { continue; }
+    if (!value || typeof value !== 'object' || Array.isArray(value)) continue;
+    const v = value as Record<string, unknown>;
+    // 결과 «모양»일 때만 확정한다 — `self review --json` 의 결과는 PR 번호 ⊕ (판정 칸 ⊕ must-fix 목록 | 오류 문자열)이다.
+    //   다른 JSON 줄(중간 로그)을 결과로 확정하면 뒤에 나온 진짜 판정을 중복 방지가 영영 막는다.
+    const isResult = v.pr !== undefined && (('verdict' in v && Array.isArray(v.mustFix)) || typeof v.error === 'string');
+    if (!isResult) continue;
+    const prRaw = typeof v.pr === 'number' ? v.pr : typeof v.pr === 'string' ? Number(String(v.pr).replace(/^#/, '')) : NaN;
+    return {
+      ...(Number.isSafeInteger(prRaw) && prRaw > 0 ? { pr: prRaw } : {}),
+      verdict: typeof v.verdict === 'string' ? v.verdict : null,
+      reviewed: typeof v.reviewed === 'boolean' ? v.reviewed : null,
+      mustFix: Array.isArray(v.mustFix) && v.mustFix.every((fix) => typeof fix === 'string') ? v.mustFix.length : null,
+      reviewRoute: typeof v.reviewRoute === 'string' ? v.reviewRoute : null,
+      head: typeof v.headCommit === 'string' && SHA40.test(v.headCommit) ? v.headCommit : null,
+      error: typeof v.error === 'string' ? v.error : null,
+    };
+  }
+  return null;
+}
+
+type ReviewRequest = NonNullable<TaskCard['reviewRequests']>[number];
+
+function alreadyCaptured(card: TaskCard, resultPath: string): boolean {
+  return (card.history ?? []).some((item) => item.event === LIVE_MOVE_RESULT_EVENT && item.resultPath === resultPath);
+}
+
+/** 회수 대기 중인 요청 — 결과 경로가 있고 · 띄우기 오류가 없고 · 아직 결과 줄이 없는 것. */
+export function pendingReviewResults(card: TaskCard): ReviewRequest[] {
+  return (card.reviewRequests ?? []).filter((entry) => typeof entry.resultPath === 'string' && entry.resultPath && !entry.error && !alreadyCaptured(card, entry.resultPath));
+}
+
+export interface CaptureReviewResultsOptions {
+  /** 이 카드들만 본다 — 없으면 상태 파일의 모든 카드. */
+  cardIds?: readonly string[];
+  now?: () => Date;
+  /** 시험 seam — 결과 파일 읽기(없으면 ENOENT 를 던진다). */
+  readFile?: (path: string) => string;
+  log?: (category: string, event: string, data: Record<string, unknown>) => void;
+}
+
+export type ReviewResultCapture =
+  | { card: string; pr: number; resultPath: string; status: 'captured'; entry: TaskCardEvent }
+  | { card: string; pr: number; resultPath: string; status: 'missing'; entry: TaskCardEvent }
+  | { card: string; pr: number; resultPath: string; status: 'pending' };
+
+/**
+ * 대기 중인 리뷰 결과를 회수한다 — 던지지 않는다(상태 파일 읽기 실패는 빈 결과 · 관측만).
+ * 결과 줄은 카드 잠금 안에서 «아직 없을 때만» 덧붙인다(두 틱이 겹쳐도 한 줄).
+ */
+export function captureReviewResults(statePath: string, opts: CaptureReviewResultsOptions = {}): ReviewResultCapture[] {
+  const log = opts.log ?? ((c: string, e: string, d: Record<string, unknown>) => debug.log(c, e, d));
+  const emit = (event: string, data: Record<string, unknown>) => { try { log('task-agent', event, data); } catch { /* fail-soft */ } };
+  let tasks: Record<string, TaskCard>;
+  try { tasks = readTaskAgentState<{ tasks?: Record<string, TaskCard> }>(statePath).tasks ?? {}; } catch (error) {
+    emit('review-result-capture-failed', { statePath, reason: (error instanceof Error ? error.message : String(error)).slice(-300) });
+    return [];
+  }
+  const ids = opts.cardIds ?? Object.keys(tasks);
+  // 시각은 대기 중인 요청을 «처음 볼 때»만 읽는다 — 회수할 것이 없으면 시계도 안 건드린다(종전 틱과 같다).
+  let nowValue: Date | undefined;
+  const nowOf = () => (nowValue ??= (opts.now ?? (() => new Date()))());
+  const waitMs = REVIEW_RESULT_WAIT_MS;
+  const read = opts.readFile ?? ((path: string) => readFileSync(path, 'utf8'));
+  const out: ReviewResultCapture[] = [];
+  for (const id of ids) {
+    const card = tasks[id];
+    if (!card) continue;
+    for (const request of pendingReviewResults(card)) {
+      const resultPath = request.resultPath!;
+      let text: string | null = null;
+      let readError: string | null = null;
+      let unreadable = false;
+      try { text = read(resultPath); } catch (error) {
+        unreadable = (error as NodeJS.ErrnoException)?.code !== 'ENOENT';
+        readError = unreadable ? (error instanceof Error ? error.message : String(error)).slice(-200) : 'result file not created';
+      }
+      const output = text !== null ? parseReviewResultOutput(text) : null;
+      // 요청한 PR 의 결과만 확정한다 — 다른 PR 번호(또는 번호 없음)의 결과는 이 카드 결과로 옮기지 않는다.
+      const parsed = output && output.pr === request.pr ? output : null;
+      const mismatch = output && !parsed ? `result PR ${output.pr ?? 'unknown'} does not match requested #${request.pr}` : null;
+      const now = nowOf();
+      const requestedAt = Date.parse(request.at);
+      const waitedMs = Number.isFinite(requestedAt) ? now.getTime() - requestedAt : null;
+      let entry: TaskCardEvent;
+      let status: 'captured' | 'missing';
+      if (parsed) {
+        status = 'captured';
+        entry = {
+          at: now.toISOString(), event: LIVE_MOVE_RESULT_EVENT, kind: 'review', pr: request.pr,
+          ...(parsed.head ? { head: parsed.head } : {}),
+          verdict: parsed.verdict, reviewed: parsed.reviewed, mustFix: parsed.mustFix, reviewRoute: parsed.reviewRoute,
+          resultPath,
+          effect: `review result captured · verdict ${parsed.verdict ?? 'none'} · reviewed ${parsed.reviewed ?? 'unknown'} · must-fix ${parsed.mustFix ?? 'unknown'}`,
+          ...(parsed.error ? { detail: parsed.error.slice(0, 300) } : {}),
+        };
+      } else if (waitedMs !== null && waitedMs >= waitMs) {
+        status = 'missing';
+        const reason = readError ?? mismatch ?? (text !== null && text.trim() ? 'output has no JSON result line' : 'result file empty');
+        entry = {
+          at: now.toISOString(), event: LIVE_MOVE_RESULT_EVENT, kind: 'review', pr: request.pr, head: request.head,
+          resultPath, effect: unreadable ? REVIEW_RESULT_UNREADABLE_EFFECT : REVIEW_RESULT_MISSING_EFFECT, detail: `${reason} after ${Math.round(waitedMs / 60_000)}m (requested ${request.at})`,
+        };
+      } else {
+        out.push({ card: id, pr: request.pr, resultPath, status: 'pending' });
+        continue;
+      }
+      let wrote = false;
+      try {
+        updateTaskCard(statePath, id, (current) => {
+          // 잠금 안에서 다시 본다 — 그 사이 요청이 오류로 바뀌었거나 없어졌거나 이미 회수됐으면 쓰지 않는다.
+          if (!current || !pendingReviewResults(current).some((entry) => entry.resultPath === resultPath && entry.pr === request.pr)) return undefined;
+          wrote = true;
+          return { ...current, history: [...(current.history ?? []), entry] };
+        });
+      } catch (error) {
+        emit('review-result-capture-failed', { card: id, pr: request.pr, resultPath, reason: (error instanceof Error ? error.message : String(error)).slice(-300) });
+        continue;
+      }
+      if (!wrote) continue;
+      if (status === 'captured') {
+        emit('review-result-captured', { card: id, pr: request.pr, requestedHead: request.head, head: entry.head ?? null, verdict: entry.verdict, reviewed: entry.reviewed, mustFix: entry.mustFix, reviewRoute: entry.reviewRoute, resultPath });
+      } else {
+        emit('review-result-missing', { card: id, pr: request.pr, head: request.head, resultPath, waitedMs, reason: entry.detail });
+      }
+      out.push({ card: id, pr: request.pr, resultPath, status, entry });
+    }
+  }
+  return out;
+}
+
+/**
+ * 다음 수 판단의 입력 — 카드에 회수된 리뷰 결과 중 «그 머리(`head`)»의 «가장 최근» 결과가 실제로 돈(reviewed) pass 이고
+ * 리뷰한 머리가 40자 sha 일 때만 `selfReview` 모양으로 돌려준다(슈퍼바이저가 나르는 `self-implement-cli` 의 규칙과 같다 ·
+ * must-fix 수는 읽었을 때만). 머리마다 고르므로 여러 머리의 결과가 어떤 순서로 회수돼도 지금 머리의 판정만 본다.
+ * 그 밖(fail·warn·미실행·없음·다른 머리)은 undefined — 판단부 입력을 비워 둔다(«통과»로 읽지 않는다).
+ */
+export function capturedSelfReview(card: TaskCard | undefined, pr: number, head: string): { verdict: 'pass'; head: string; mustFixCount?: number } | undefined {
+  if (!SHA40.test(head)) return undefined;
+  const latest = (card?.history ?? []).filter((item) => item.event === LIVE_MOVE_RESULT_EVENT && item.kind === 'review' && item.pr === pr
+    && item.effect !== REVIEW_RESULT_MISSING_EFFECT && item.effect !== REVIEW_RESULT_UNREADABLE_EFFECT && typeof item.head === 'string' && item.head.toLowerCase() === head.toLowerCase()).at(-1);
+  // 결과 줄의 detail 은 리뷰 오류(`error`)일 때만 실린다 — 오류가 섞인 결과는 pass 후보가 아니다.
+  if (!latest || latest.detail || latest.reviewed !== true || latest.verdict !== 'pass' || !latest.head || !SHA40.test(latest.head)) return undefined;
+  return { verdict: 'pass', head: latest.head, ...(typeof latest.mustFix === 'number' ? { mustFixCount: latest.mustFix } : {}) };
+}
+
+/**
+ * TA-LAND-WARN-MUSTFIX0 — land 입력용: 그 머리의 «가장 최근» 회수 결과가 실제로 돈(reviewed) 리뷰이고 오류가 없으며
+ * verdict 가 pass «또는» warn 이면 돌려준다(정본 규칙 «warn ⊕ must-fix 0 = 통과» · #25941 canAuto · #25962).
+ * must-fix 수는 읽었을 때만 싣는다 — 0 인지는 호출부·land 관문이 본다(모르면 거부 · fail-closed).
+ * `capturedSelfReview`(판단부 입력 · pass 만)는 그대로 둔다 — 멈춤 시점 판단부의 정합은 이 함수의 몫이 아니다.
+ */
+export function capturedLandReview(card: TaskCard | undefined, pr: number, head: string): { verdict: 'pass' | 'warn'; head: string; reviewed: true; mustFixCount?: number } | undefined {
+  if (!SHA40.test(head)) return undefined;
+  const latest = (card?.history ?? []).filter((item) => item.event === LIVE_MOVE_RESULT_EVENT && item.kind === 'review' && item.pr === pr
+    && item.effect !== REVIEW_RESULT_MISSING_EFFECT && item.effect !== REVIEW_RESULT_UNREADABLE_EFFECT && typeof item.head === 'string' && item.head.toLowerCase() === head.toLowerCase()).at(-1);
+  if (!latest || latest.detail || latest.reviewed !== true || (latest.verdict !== 'pass' && latest.verdict !== 'warn') || !latest.head || !SHA40.test(latest.head)) return undefined;
+  return { verdict: latest.verdict, head: latest.head, reviewed: true, ...(typeof latest.mustFix === 'number' ? { mustFixCount: latest.mustFix } : {}) };
+}
+
+/** 그 PR 에 회수된 «돈 pass» 결과가 하나라도 있나 — 지금 머리를 조회(gh)할지 정하는 싼 검사. */
+export function hasCapturedPass(card: TaskCard | undefined, pr: number): boolean {
+  return (card?.history ?? []).some((item) => item.event === LIVE_MOVE_RESULT_EVENT && item.kind === 'review' && item.pr === pr
+    && !item.detail && item.reviewed === true && item.verdict === 'pass' && typeof item.head === 'string' && SHA40.test(item.head));
+}

package/src/task-agent/run-adopt.ts

@@ -0,0 +1,136 @@
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { basename, dirname, isAbsolute, join, resolve, sep } from 'node:path';
+import { debug } from '../debug/log.js';
+import { launchBindingRunIds, launchRegistryDir, readLaunchBinding } from '../harness/launch-registry.js';
+import { launchStampFromLedger } from '../harness/launch-stamp.js';
+import { normalizeRunId } from '../harness/harness-space.js';
+import { effectiveInstanceRoot } from '../instance/resolve.js';
+import { loadRunLedger, runLedgerDir } from '../self-implement/run-ledger.js';
+import { TASK_SEATS, updateTaskCard, type TaskCard, type TaskSeat } from './task-hand.js';
+
+export interface RunBirth {
+  runId: string;
+  goalPath?: string;
+  cwd: string;
+  runsDir?: string;
+  env: Readonly<Record<string, string | undefined>>;
+}
+
+export interface RunAdoptDeps {
+  /** 카드 상태 파일(시험 주입). 없으면 우주 뿌리(`instanceRoot`) 아래 `task-agent-actions.json` = `taskAgentStatePath()`. */
+  statePath?: string;
+  /** 우주 뿌리 해석 seam — 기본 `effectiveInstanceRoot()`(state·runsDir 를 만드는 같은 공용 해석). */
+  instanceRoot?: () => string;
+  registryDir?: string;
+  knownChecklistIds?: ReadonlySet<string>;
+  now?: () => Date;
+  log?: (category: string, event: string, data: Record<string, unknown>) => void;
+}
+
+export type RunAdoptSkipReason = 'handed' | 'already-carded' | 'pod-child' | 'other-universe' | 'universe-mismatch';
+export type RunAdoptResult = { card: TaskCard; adopted: true } | { adopted: false; reason: RunAdoptSkipReason };
+
+function seatFromGoal(path: string | undefined): TaskSeat | undefined {
+  const seat = path?.replaceAll('\\', '/').match(/\/(?:seat-state|seats)\/(OP|TC|MK|UX)\//)?.[1];
+  return seat as TaskSeat | undefined;
+}
+
+function goalText(path: string | undefined, cwd: string): string {
+  if (!path) return '';
+  try {
+    const fullPath = isAbsolute(path) ? path : resolve(cwd, path);
+    return readFileSync(fullPath, 'utf8');
+  } catch { return ''; }
+}
+
+function checklistFromText(text: string, known: ReadonlySet<string>): string | undefined {
+  const explicit = /칸\s+([A-Za-z0-9][A-Za-z0-9_-]*)/.exec(text)?.[1];
+  if (explicit) return explicit;
+  const title = /(?:^|\n)제목:\s*([A-Za-z0-9][A-Za-z0-9_-]*?)-\d+\s+—/m.exec(text)?.[1];
+  return title && known.has(title) ? title : undefined;
+}
+
+/** 경로 정규화 — 심볼릭 링크(`/var`↔`/private/var` 등)·상대·후행 슬래시를 같은 값으로. 없는 꼬리는 있는 조상의 실경로에 붙인다. */
+function canonicalPath(path: string): string {
+  const absolute = resolve(path);
+  let head = absolute;
+  const tail: string[] = [];
+  while (!existsSync(head)) {
+    const parent = dirname(head);
+    if (parent === head) return absolute;
+    tail.unshift(basename(head));
+    head = parent;
+  }
+  try { return join(realpathSync(head), ...tail); } catch { return absolute; }
+}
+
+/** Adopt only a run belonging to this universe. The universe root is resolved once (`effectiveInstanceRoot()` unless a
+ *  state path is injected) and both the card state file and the run's `runsDir` are compared against it after canonical
+ *  path resolution. The runId check and write share updateTaskCard's lock.
+ *  A birth without `runsDir` cannot prove its universe and is skipped as `other-universe` (conservative); a `runsDir` that is
+ *  not `<root>/self-dev-runs` is skipped as `universe-mismatch` with both paths observed — never silently. */
+export function adoptRunCard(birth: RunBirth, deps: RunAdoptDeps = {}): RunAdoptResult {
+  const root = deps.statePath ? dirname(deps.statePath) : (deps.instanceRoot ?? effectiveInstanceRoot)();
+  const statePath = deps.statePath ?? join(root, 'task-agent-actions.json');
+  const log = deps.log ?? ((category: string, event: string, data: Record<string, unknown>) => debug.log(category, event, data));
+  const skip = (reason: RunAdoptSkipReason, extra: Record<string, unknown> = {}): RunAdoptResult => {
+    log('task-agent', 'run-adopt-skipped', { runId: birth.runId, reason, ...extra });
+    return { adopted: false, reason };
+  };
+  if (birth.env.ELANOUS_TASK_CARD_ID) return skip('handed');
+  if (birth.env.ELANOUS_POD_NAME) return skip('pod-child');
+  if (!birth.runsDir) return skip('other-universe', { statePath, runsDir: null });
+  const expectedRunsDir = canonicalPath(join(root, 'self-dev-runs'));
+  const runsDir = canonicalPath(birth.runsDir);
+  if (runsDir !== expectedRunsDir) return skip('universe-mismatch', { statePath, runsDir: birth.runsDir, expectedRunsDir, canonicalRunsDir: runsDir });
+  if (!birth.runId || birth.runId !== normalizeRunId(birth.runId) || birth.runId.includes(sep)) throw new Error(`invalid runId: ${birth.runId}`);
+  const text = goalText(birth.goalPath, birth.cwd);
+  const firstLine = text.split(/\r?\n/).find(line => line.trim())?.trim() ?? `harness run ${birth.runId}`;
+  let stamp = launchStampFromLedger(null);
+  try { stamp = launchStampFromLedger(loadRunLedger(birth.runId, runLedgerDir(root))); } catch { /* unreadable stamp is unknown */ }
+  const origin = stamp.entrance;
+  const actor = stamp.actor;
+  const seat = TASK_SEATS.find(candidate => candidate === actor) ?? seatFromGoal(birth.goalPath);
+  const checklistId = checklistFromText(text, deps.knownChecklistIds ?? new Set());
+  const id = `ta-${birth.runId}`;
+  let adopted = false;
+  const card = updateTaskCard(statePath, id, (current, tasks) => {
+    if (current || Object.values(tasks).some(candidate => candidate.runId === birth.runId)) return undefined;
+    adopted = true;
+    const at = (deps.now ?? (() => new Date()))().toISOString();
+    return {
+      id, text: firstLine, status: 'launched', runId: birth.runId,
+      ...(birth.goalPath ? { goal: birth.goalPath } : {}),
+      ...(seat ? { seat } : {}),
+      ...(checklistId ? { checklistId } : {}),
+      createdAt: at, history: [{ at, event: 'adopted', detail: origin }],
+    };
+  });
+  if (!adopted || !card) return skip('already-carded');
+  log('task-agent', 'run-adopted', { card: card.id, runId: birth.runId, origin, seat: seat ?? null, checklistId: checklistId ?? null });
+  return { card, adopted: true };
+}
+
+/** Explicit backfill for old launch bindings (`elanous tasks adopt-runs`); not part of the launch-time path.
+ *  The binding's launch-time `podName`/`taskCardId` stand in for the env, so Pod children and handed runs are skipped.
+ *  Bindings written before those fields existed carry no marker — the host registry is per-host `$TMPDIR`, and a Pod
+ *  child writes its binding inside its Pod, so such legacy rows are host-launched runs. */
+export function adoptUncardedRuns(deps: RunAdoptDeps = {}): { scanned: number; adopted: number; skipped: Partial<Record<RunAdoptSkipReason, number>> } {
+  const dir = deps.registryDir ?? launchRegistryDir();
+  const skipped: Partial<Record<RunAdoptSkipReason, number>> = {};
+  let scanned = 0;
+  let adopted = 0;
+  for (const runId of launchBindingRunIds(dir)) {
+    scanned++;
+    const binding = readLaunchBinding(runId, dir);
+    if (!binding?.runsDir) {
+      skipped['other-universe'] = (skipped['other-universe'] ?? 0) + 1;
+      (deps.log ?? ((category, event, data) => debug.log(category, event, data)))('task-agent', 'run-adopt-skipped', { runId, reason: 'other-universe' });
+      continue;
+    }
+    const result = adoptRunCard({ runId, cwd: binding.cwd, goalPath: binding.goalPath, runsDir: binding.runsDir, env: { ELANOUS_POD_NAME: binding.podName, ELANOUS_TASK_CARD_ID: binding.taskCardId } }, deps);
+    if (result.adopted) adopted++;
+    else skipped[result.reason] = (skipped[result.reason] ?? 0) + 1;
+  }
+  return { scanned, adopted, skipped };
+}