elanous 0.2.18 → 0.2.19

package/src/task-agent/card-evidence.ts

@@ -0,0 +1,203 @@
+/**
+ * TA-CARD-RUN-LINK — 과제 카드의 런 id 로 그 런이 연 골 id · PR 을 런 원장에서 읽어 카드에 «한 번» 적는다.
+ * - 순수 판정 `bindCardEvidence(card, snapshot)` — 호스트 원장 → Pod 자식 원장(`pod-child-run`) → 호스트 logs 의
+ *   `self-implement.pod job-finished {childRunId, prUrl}` 순. 모르면 비운다(추측하지 않는다).
+ * - `refreshCardRunBinding` 은 `tasks show`·`tasks advance` 가 부른다 — 읽기 조회이고, 찾았을 때만 잠금 안에서 카드의
+ *   `goalId`·`pr {number,url}`(UX LOOP-INTERACT 계약 칸)을 비어 있을 때만 적는다 · 수동 근거(refSource manual)는 덮지 않는다.
+ * - 관측: `debug.log('task-agent', 'card-pr-bound', {card, runId, pr})`.
+ */
+import { existsSync } from 'node:fs';
+import { debug } from '../debug/log.js';
+import type { RunLedgerEntry } from '../self-implement/run-ledger.js';
+import { cardPrNumber, taskAgentStatePath, updateTaskCard, readTaskCard, type TaskCard } from './task-hand.js';
+
+const GOAL_ID = /^[a-f0-9]{16}$/;
+const PR_URL = /^https:\/\/github\.com\/[\w.-]+\/[\w.-]+\/pull\/(\d+)$/;
+const RUN_ID = /^run-[A-Za-z0-9_-]{4,64}$/;
+
+/** 카드 런 하나의 원장 사진 — host = 카드 런 원장(없으면 null) · children = `pod-child-run` 자식 원장 · podFinishes = 호스트 logs. */
+export interface CardRunSnapshot {
+  host: readonly RunLedgerEntry[] | null;
+  children: Readonly<Record<string, readonly RunLedgerEntry[] | null>>;
+  podFinishes?: ReadonlyArray<{ childRunId: string; prUrl: string }>;
+  /** 읽기 «실패»(원장·logs) — 부재(null)와 갈린다. 있으면 refresh 가 card-bind-failed 를 남긴다. */
+  readErrors?: readonly string[];
+}
+
+export interface CardRunEvidence {
+  goalId?: string;
+  pr?: { number: number; url?: string };
+  childRunId?: string;
+  /** 호스트 원장이 있었나 — 없으면 런이 아직 시작 전이거나 대기열로 갔다. */
+  ledgerFound: boolean;
+}
+
+function entryGoal(entry: RunLedgerEntry): string | undefined {
+  const value = entry.goalId ?? (typeof entry.data?.goalId === 'string' ? entry.data.goalId : undefined);
+  return typeof value === 'string' && GOAL_ID.test(value) ? value : undefined;
+}
+
+/**
+ * 그 PR 의 골 id — PR 의 `pr-opened` 줄 골이 먼저. 없으면 원장 전체의 골이 «하나뿐»이고 다른 PR 줄이 골을 싣지 않았을 때만
+ * 그 골(대응이 모호하면 비운다 — set-once 라 틀린 짝은 못 고친다).
+ */
+function goalIdOf(entries: readonly RunLedgerEntry[], prNumber: number): string | undefined {
+  const own = [...entries].reverse().find((entry) => entry.event === 'pr-opened' && entry.data?.number === prNumber && entryGoal(entry));
+  if (own) return entryGoal(own);
+  if (entries.some((entry) => entry.event === 'pr-opened' && entry.data?.number !== prNumber && entryGoal(entry))) return undefined;
+  const goals = new Set(entries.map(entryGoal).filter((value): value is string => value !== undefined));
+  return goals.size === 1 ? [...goals][0] : undefined;
+}
+
+function lastPr(entries: readonly RunLedgerEntry[]): { number: number; url?: string } | undefined {
+  for (let at = entries.length - 1; at >= 0; at--) {
+    const entry = entries[at]!;
+    if (entry.event !== 'pr-opened') continue;
+    const number = entry.data?.number;
+    if (!Number.isSafeInteger(number) || (number as number) <= 0) continue;
+    const url = typeof entry.data.url === 'string' && PR_URL.exec(entry.data.url)?.[1] === String(number) ? entry.data.url : undefined;
+    return { number: number as number, ...(url ? { url } : {}) };
+  }
+  return undefined;
+}
+
+/** 자식 런 id — 호스트 원장의 `pod-child-run` 만(호스트 런 자신은 빼고 · 순서 유지). */
+export function podChildRunIds(host: readonly RunLedgerEntry[] | null, runId?: string): string[] {
+  return [...new Set((host ?? []).filter((entry) => entry.event === 'pod-child-run' && typeof entry.data?.childRunId === 'string'
+    && RUN_ID.test(entry.data.childRunId) && entry.data.childRunId !== runId).map((entry) => entry.data.childRunId as string))];
+}
+
+/** 순수 — 카드 런의 골 id · PR. PR 은 호스트 → 자식(나중 자식 먼저) → job-finished 순으로 처음 찾은 것. */
+export function bindCardEvidence(card: Pick<TaskCard, 'runId'>, snapshot: CardRunSnapshot): CardRunEvidence {
+  if (!card.runId || !snapshot.host) return { ledgerFound: false };
+  const children = podChildRunIds(snapshot.host, card.runId).reverse();
+  const childLedgers = children.map((id) => [id, snapshot.children[id] ?? null] as const);
+  let pr = lastPr(snapshot.host);
+  let childRunId: string | undefined;
+  for (const [id, entries] of childLedgers) {
+    if (pr) break;
+    const found = entries ? lastPr(entries) : undefined;
+    if (found) { pr = found; childRunId = id; }
+  }
+  for (const id of children) {
+    if (pr) break;
+    const finish = [...(snapshot.podFinishes ?? [])].reverse().find((row) => row.childRunId === id && PR_URL.test(row.prUrl));
+    const number = finish ? Number(PR_URL.exec(finish.prUrl)![1]) : NaN;
+    if (finish && Number.isSafeInteger(number) && number > 0) { pr = { number, url: finish.prUrl }; childRunId = id; }
+  }
+  // 골 id 는 PR 을 낸 런의 것뿐이고 PR 과 함께만 — 자식이 냈으면 그 자식 원장의 골(아직 없으면 비움 · 나중 조회가 채운다),
+  // 호스트가 냈으면 호스트 골. PR 전에는 누가 낼지 모르니 골도 묶지 않는다(set-once 라 섞이면 못 고친다).
+  const childGoal = (id: string) => { const entries = snapshot.children[id]; return entries && pr ? goalIdOf(entries, pr.number) : undefined; };
+  const goalId = pr ? (childRunId ? childGoal(childRunId) : goalIdOf(snapshot.host, pr.number)) : undefined;
+  return { ledgerFound: true, ...(goalId ? { goalId } : {}), ...(pr ? { pr } : {}), ...(childRunId ? { childRunId } : {}) };
+}
+
+/** 원장·logs 읽기(시험 주입). */
+export interface CardRunEvidenceDeps {
+  loadLedger?: (runId: string) => RunLedgerEntry[] | null;
+  podFinishes?: (childRunIds: readonly string[], sinceIso: string) => Array<{ childRunId: string; prUrl: string }>;
+  now?: () => Date;
+}
+
+async function defaultLoadLedger(): Promise<(runId: string) => RunLedgerEntry[] | null> {
+  const { loadRunLedger, runLedgerDir, resolveFederatedRunLedgerDirectories } = await import('../self-implement/run-ledger.js');
+  let dirs: string[] = [runLedgerDir()];
+  // 연합 목록을 못 읽으면 이 우주만 읽되, 여기서 못 찾으면 «없음»이 아니라 실패로 올린다(card-bind-failed).
+  let federationFailure: unknown;
+  try { dirs = [...new Set([...dirs, ...resolveFederatedRunLedgerDirectories({})])]; } catch (error) { federationFailure = new Error(`federated run-ledger lookup failed: ${error instanceof Error ? error.message : String(error)}`); }
+  return ledgerLoader(dirs, (runId, dir) => loadRunLedger(runId, dir), federationFailure);
+}
+
+/** 디렉터리들에서 첫 원장 — 어디서도 못 찾았고 읽기(또는 연합 목록) 실패가 있었으면 부재(null)가 아니라 던진다. */
+export function ledgerLoader(dirs: readonly string[], load: (runId: string, dir: string) => RunLedgerEntry[] | null, priorFailure?: unknown): (runId: string) => RunLedgerEntry[] | null {
+  return (runId) => {
+    let failure: unknown = priorFailure;
+    for (const dir of dirs) {
+      try { const entries = load(runId, dir); if (entries) return entries; } catch (error) { failure ??= error; }
+    }
+    if (failure !== undefined) throw failure;
+    return null;
+  };
+}
+
+async function defaultPodFinishes(): Promise<NonNullable<CardRunEvidenceDeps['podFinishes']>> {
+  const { LogStore, logsDbPath } = await import('../mss/logging/log-store.js');
+  return (childRunIds, sinceIso) => {
+    const path = logsDbPath();
+    if (!childRunIds.length || !existsSync(path)) return [];
+    const store = LogStore.openReadOnly(path);
+    try {
+      const wanted = new Set(childRunIds);
+      const rows: Array<{ childRunId: string; prUrl: string }> = [];
+      const sinceMs = Date.parse(sinceIso);
+      for (const row of store.queryAll({ exactCategories: ['self-implement.pod'], events: ['job-finished'], ...(Number.isFinite(sinceMs) ? { sinceMs } : {}) })) {
+        let data: { childRunId?: unknown; prUrl?: unknown } | null = null;
+        try { data = row.data ? JSON.parse(row.data) : null; } catch { continue; }
+        if (typeof data?.childRunId === 'string' && wanted.has(data.childRunId) && typeof data.prUrl === 'string') rows.push({ childRunId: data.childRunId, prUrl: data.prUrl });
+      }
+      return rows;
+    } finally { store.close(); }
+  };
+}
+
+/** 카드 런의 원장 사진을 읽는다 — 읽기 실패는 «없음»(null)이다. */
+export async function readCardRunSnapshot(card: Pick<TaskCard, 'runId' | 'createdAt'>, deps: CardRunEvidenceDeps = {}): Promise<CardRunSnapshot> {
+  if (!card.runId) return { host: null, children: {} };
+  const load = deps.loadLedger ?? await defaultLoadLedger();
+  const readErrors: string[] = [];
+  const reason = (error: unknown) => (error instanceof Error ? error.message : String(error)).slice(0, 300);
+  const safe = (runId: string) => { try { return load(runId); } catch (error) { readErrors.push(`ledger ${runId}: ${reason(error)}`); return null; } };
+  const host = safe(card.runId);
+  const childIds = podChildRunIds(host, card.runId);
+  const children = Object.fromEntries(childIds.map((id) => [id, safe(id)]));
+  let podFinishes: Array<{ childRunId: string; prUrl: string }> = [];
+  const missing = childIds.filter((id) => !children[id] || !lastPr(children[id]!));
+  if (missing.length && (!host || !lastPr(host))) {
+    try { podFinishes = (deps.podFinishes ?? await defaultPodFinishes())(missing, card.createdAt); } catch (error) { readErrors.push(`logs: ${reason(error)}`); }
+  }
+  return { host, children, podFinishes, ...(readErrors.length ? { readErrors } : {}) };
+}
+
+/**
+ * 카드에 런 근거를 채운다 — 런 id 가 있고 아직 비어 있는 칸(goalId·pr)만, 잠금 안에서 «한 번».
+ * 찾지 못했으면 쓰지 않는다. 쓴(또는 그대로인) 카드를 돌려준다.
+ */
+export async function refreshCardRunBinding(cardId: string, statePath = taskAgentStatePath(), deps: CardRunEvidenceDeps = {}): Promise<{ card: TaskCard | undefined; evidence?: CardRunEvidence }> {
+  const card = readTaskCard(cardId, statePath);
+  // 수동 근거(refSource manual)는 덮지 않는다 · 둘 다 차 있으면 다시 읽지 않는다(한 번만).
+  if (!card?.runId || card.refSource === 'manual' || (card.pr !== undefined && card.goalId !== undefined)) return { card };
+  const snapshot = await readCardRunSnapshot(card, deps);
+  if (snapshot.readErrors?.length) {
+    try { debug.log('task-agent', 'card-bind-failed', { card: cardId, runId: card.runId, errors: snapshot.readErrors }); } catch { /* fail-soft */ }
+  }
+  const evidence = bindCardEvidence(card, snapshot);
+  // 이미 묶인 PR 이 있으면 «같은» PR(번호 ⊕ 낸 자식)을 다시 찾았을 때만 뒤늦은 골을 채운다.
+  const samePr = (current: TaskCard) => current.pr === undefined
+    || (evidence.pr !== undefined && cardPrNumber(current) === evidence.pr.number && current.runChildId === evidence.childRunId);
+  const wantsGoal = card.goalId === undefined && evidence.goalId && samePr(card);
+  const wantsPr = card.pr === undefined && evidence.pr;
+  if (!wantsGoal && !wantsPr) return { card, evidence };
+  const at = (deps.now ?? (() => new Date()))().toISOString();
+  const wrote = { pr: false };
+  const next = updateTaskCard(statePath, cardId, (current) => {
+    if (!current || current.runId !== card.runId || current.refSource === 'manual') return undefined;
+    const goal = current.goalId === undefined && evidence.goalId && samePr(current) ? evidence.goalId : undefined;
+    const pr = current.pr === undefined && evidence.pr ? evidence.pr : undefined;
+    if (!goal && !pr) return undefined;
+    wrote.pr = pr !== undefined;
+    return {
+      ...current,
+      ...(goal ? { goalId: goal } : {}),
+      ...(pr ? { pr, ...(evidence.childRunId && !current.runChildId ? { runChildId: evidence.childRunId } : {}) } : {}),
+      history: [
+        ...(current.history ?? []),
+        ...(goal ? [{ at, event: 'goal-bound', detail: goal, runId: current.runId! }] : []),
+        ...(pr ? [{ at, event: 'pr-bound', detail: pr.url ?? `#${pr.number}`, runId: current.runId!, pr: pr.number }] : []),
+      ],
+    };
+  });
+  if (wrote.pr && typeof next?.pr === 'object') {
+    try { debug.log('task-agent', 'card-pr-bound', { card: cardId, runId: next.runId ?? null, pr: next.pr.number, url: next.pr.url ?? null, childRunId: next.runChildId ?? null }); } catch { /* fail-soft */ }
+  }
+  return { card: next, evidence };
+}

package/src/task-agent/completion-evidence.ts

@@ -0,0 +1,126 @@
+import { readFileSync, statSync } from 'node:fs';
+import { extname, isAbsolute, relative, resolve, sep } from 'node:path';
+import type { Database } from 'bun:sqlite';
+import type { DecisionLedger } from '../decisions/decision-ledger.js';
+import { getLastStatus } from '../domains/schedule-registry.js';
+
+export type CompletionEvidenceKind = 'research-report' | 'artifact' | 'content' | 'ops-action' | 'watch-brief' | 'decision-support';
+export interface CompletionEvidenceDeps {
+  ledger?: Pick<DecisionLedger, 'list'>;
+  schedulesDb?: Database;
+}
+
+/** A missing record is negative evidence; a failed read is explicitly unmeasured. No store is opened or mutated here. */
+export function checkCompletionEvidence(
+  kind: CompletionEvidenceKind,
+  input: { dir: string; ref: string },
+  deps: CompletionEvidenceDeps = {},
+): { ok: boolean; ref: string; missing: string[] } {
+  const missing: string[] = [];
+  const add = (item: string) => { if (!missing.includes(item)) missing.push(item); };
+  const pathFor = (ref: string): string | null => {
+    const root = resolve(input.dir);
+    const path = resolve(root, ref);
+    const rel = relative(root, path);
+    return !isAbsolute(ref) && rel !== '..' && !rel.startsWith(`..${sep}`) ? path : null;
+  };
+  const read = (path: string): string | null => {
+    try { return readFileSync(path, 'utf8'); }
+    catch (error) {
+      add((error as NodeJS.ErrnoException).code === 'ENOENT' ? '파일' : '못 쟀다: 파일 읽기');
+      return null;
+    }
+  };
+  const file = () => {
+    const path = pathFor(input.ref);
+    if (!path) add('못 쟀다: 경로');
+    return path;
+  };
+
+  switch (kind) {
+    case 'research-report': {
+      const path = file();
+      if (!path) break;
+      if (extname(path).toLowerCase() !== '.md') { add('md 파일'); break; }
+      const text = read(path);
+      if (text === null) break;
+      const sources = new Set([...text.matchAll(/https?:\/\/[^\s<>"')\]]+/g)].map((match) => match[0]!.replace(/[.,;]+$/, '')));
+      if (sources.size < 2) add('출처');
+      if (!/^#{1,6}\s*반대 근거\s*$/m.test(text)) add('반대 근거');
+      break;
+    }
+    case 'artifact':
+    case 'content': {
+      const path = file();
+      if (!path) break;
+      try {
+        const stat = statSync(path);
+        if (!stat.isFile() || stat.size === 0) add('파일 크기');
+      } catch (error) { add((error as NodeJS.ErrnoException).code === 'ENOENT' ? '파일' : '못 쟀다: 파일 크기'); }
+      const stem = path.slice(0, path.length - extname(path).length);
+      let preview = false;
+      for (const ext of ['.png', '.pdf', '.html']) {
+        const candidate = `${stem}${ext}`;
+        if (candidate === path) continue;
+        try {
+          const stat = statSync(candidate);
+          if (stat.isFile() && stat.size > 0) preview = true;
+        } catch (error) {
+          if ((error as NodeJS.ErrnoException).code !== 'ENOENT') add('못 쟀다: 미리보기 읽기');
+        }
+      }
+      if (extname(path).toLowerCase() === '.md' && !missing.includes('파일')) {
+        const text = read(path);
+        if (text !== null && /^#{1,6}\s+\S.*$/m.test(text)) preview = true;
+      }
+      if (!preview && !missing.some((item) => item.startsWith('못 쟀다: 미리보기') || item === '못 쟀다: 파일 읽기')) add('미리보기');
+      break;
+    }
+    case 'ops-action': {
+      const path = pathFor('execution.jsonl');
+      if (!path) { add('못 쟀다: 경로'); break; }
+      let text: string;
+      try { text = readFileSync(path, 'utf8'); }
+      catch (error) {
+        add((error as NodeJS.ErrnoException).code === 'ENOENT' ? '실행 기록' : '못 쟀다: 실행 기록 읽기');
+        break;
+      }
+      let execution = false;
+      let readback = false;
+      for (const line of text.split('\n').filter((line) => line.trim())) {
+        let record: unknown;
+        try { record = JSON.parse(line); }
+        catch { add('못 쟀다: 실행 기록 해석'); continue; }
+        if (!record || typeof record !== 'object') { add('못 쟀다: 실행 기록 해석'); continue; }
+        const entry = record as { id?: unknown; type?: unknown };
+        if (entry.id !== input.ref) continue;
+        if (entry.type === 'execution') execution = true;
+        if (entry.type === 'readback') readback = true;
+      }
+      if (!missing.includes('못 쟀다: 실행 기록 해석')) {
+        if (!execution) add('실행 기록');
+        if (!readback) add('되읽기');
+      }
+      break;
+    }
+    case 'watch-brief': {
+      if (!deps.schedulesDb) { add('못 쟀다: 스케줄 DB'); break; }
+      try {
+        const row = deps.schedulesDb.query('SELECT id FROM schedule_registry WHERE id = ?').get(input.ref);
+        if (!row) add('일정');
+        else if (getLastStatus(deps.schedulesDb, input.ref) !== 'ok') add('도착');
+      } catch { add('못 쟀다: 스케줄 DB 읽기'); }
+      break;
+    }
+    case 'decision-support': {
+      if (!deps.ledger) { add('못 쟀다: 결정 원장'); break; }
+      try {
+        if (!deps.ledger.list({ status: 'all' }).some((entry) => entry.id === input.ref)) add('결정 기록');
+      } catch { add('못 쟀다: 결정 원장 읽기'); }
+      break;
+    }
+    default:
+      add('못 쟀다: 증거 종류');
+  }
+  return { ok: missing.length === 0, ref: input.ref, missing };
+}

package/src/task-agent/judge.ts

@@ -6,6 +6,7 @@
  */
 import type { SupervisorStopReason } from '../self-dev/run-supervisor.js';
 import type { NextActionKind, RetryVariant } from './actions.js';
+import type { CompletionKind } from './task-hand.js';
 
 export type TaskMove =
   | 'propose-green'
@@ -27,6 +28,11 @@ export interface TaskJudgeInput {
   mustFix?: readonly string[];
   /** 수마다 누적 실패 수. */
   failures?: Partial<Record<TaskMove, number>>;
+  deliveryEvidence?: { ok: boolean; files: readonly string[]; reason: string };
+  /** 과제 종결 종류(§A4b③) — 비거나 code-pr 이면 종전처럼 PR 병합이 종결이다. */
+  completion?: CompletionKind;
+  /** code-pr 밖 종류의 확인 증거(`completion-evidence.ts` 판독). 비면 «아직 못 받았다» — 통과로 읽지 않는다. */
+  evidence?: { ok: boolean; ref: string };
 }
 
 export interface TaskJudgement {
@@ -64,7 +70,19 @@ const EXECUTOR_VARIANT: Partial<Record<TaskMove, RetryVariant>> = {
 };
 
 function base(input: TaskJudgeInput): Omit<TaskJudgement, 'executorKind'> {
+  if (input.deliveryEvidence) return input.deliveryEvidence.ok
+    ? { move: 'propose-green', stage: 'closing', reason: `전달 근거 확인: ${input.deliveryEvidence.files.join(', ')}` }
+    : { move: 'wait', stage: 'waiting', reason: input.deliveryEvidence.reason };
   const stop = input.stopReason;
+  const kind = input.completion;
+  if (kind !== undefined && kind !== 'code-pr') {
+    const ref = input.evidence?.ref?.trim() ?? '';
+    // green 은 추적 가능한 근거(비지 않은 ref)가 있을 때만 — ok 인데 ref 가 비면 «증거 없음»으로 읽는다.
+    if (input.evidence?.ok === true && ref) return { move: 'propose-green', stage: 'closing', reason: `확인 증거 ${ref} 근거로 칸 green 제안 — ${kind}` };
+    if (input.evidence?.ok === false) return { move: 'narrow-relaunch', stage: 'repairing', reason: `확인 증거 미충족(${ref || '근거 없음'}) — ${kind} · 범위를 좁혀 재발사` };
+    // 증거가 아직 없다 — 완주·종료 미관측이면 증거를 기다린다(PR 병합은 이 종류의 종결이 아니다). 그 밖의 종료 어휘는 아래 표 그대로.
+    if (stop === 'converged' || stop === undefined) return { move: 'wait', stage: 'observing', reason: `확인 증거 대기 — ${kind}${input.evidence?.ok === true ? ' (ref 비어 있음)' : ''}` };
+  }
   const merged = input.prState === 'MERGED' && input.pr !== undefined && input.pr !== '';
   if (merged) {
     return { move: 'propose-green', stage: 'closing', reason: `병합된 PR ${input.pr} 근거로 칸 green 제안` };

package/src/task-agent/live-moves.ts

@@ -0,0 +1,176 @@
+/**
+ * TA-JUDGE-LIVE-SAFE — 판단부의 «안전한 수» 둘만 실제로 한다(10-07 승인 · 그 밖의 수는 그림자 그대로).
+ *
+ * - `review`: 수확 가능 런의 PR 에 elanous 리뷰를 «한 번» 요청한다 — PR 머리(sha)마다 한 번(카드 `reviewRequests` 이력).
+ *   요청만 한다: 결과로 착지·재발사로 잇지 않는다(실행부 `executeNextAction` 의 review→land 사슬을 타지 않는다).
+ * - `propose-green`: 카드에 green «제안»(`greenProposal`)만 적는다 — 체크리스트는 손대지 않는다.
+ * - 설정 `taskAgent.liveMoves`(config > env `ELANOUS_TASK_AGENT_LIVE_MOVES` > 없음). 모르는 항목은 경고하고 버린다.
+ * - 관측: 실행한 수마다 `debug.log('task-agent', 'live-move', {kind, card, ok, detail, live:true})`.
+ */
+import { spawn, spawnSync } from 'node:child_process';
+import { resolve } from 'node:path';
+import { debug } from '../debug/log.js';
+import type { DetachedSpawn } from '../cli/tasks-cli.js';
+import { taskAgentStatePath, updateTaskCard, type TaskCard } from './task-hand.js';
+
+export const TASK_AGENT_LIVE_MOVES = ['review', 'propose-green'] as const;
+export type TaskAgentLiveMove = typeof TASK_AGENT_LIVE_MOVES[number];
+export const TASK_AGENT_LIVE_MOVES_ENV = 'ELANOUS_TASK_AGENT_LIVE_MOVES';
+
+export interface LiveMovesResolution { moves: ReadonlySet<TaskAgentLiveMove>; source: 'config' | 'env' | 'default'; ignored: string[] }
+
+/** 설정 > 환경 > 없음. 모르는 항목은 허용으로 읽지 않는다 — 경고 관측만 남기고 버린다. */
+export function resolveTaskAgentLiveMoves(
+  configured: unknown,
+  env: Record<string, string | undefined> = process.env,
+  log: (category: string, event: string, data: Record<string, unknown>) => void = (c, e, d) => debug.log(c, e, d, { level: 'warn' }),
+): LiveMovesResolution {
+  let raw: unknown[];
+  let source: LiveMovesResolution['source'];
+  if (configured !== undefined) { raw = Array.isArray(configured) ? configured : [configured]; source = 'config'; }
+  else if (env[TASK_AGENT_LIVE_MOVES_ENV]?.trim()) { raw = env[TASK_AGENT_LIVE_MOVES_ENV]!.split(',').map((entry) => entry.trim()).filter(Boolean); source = 'env'; }
+  else return { moves: new Set(), source: 'default', ignored: [] };
+  const moves = new Set<TaskAgentLiveMove>();
+  const ignored: string[] = [];
+  for (const entry of raw) {
+    if (typeof entry === 'string' && (TASK_AGENT_LIVE_MOVES as readonly string[]).includes(entry)) moves.add(entry as TaskAgentLiveMove);
+    else ignored.push(typeof entry === 'string' ? entry : JSON.stringify(entry));
+  }
+  if (ignored.length) {
+    try { log('task-agent', 'live-moves-ignored', { ignored, source, allowed: [...TASK_AGENT_LIVE_MOVES] }); } catch { /* fail-soft */ }
+  }
+  return { moves, source, ignored };
+}
+
+/** 운영 설정에서 읽는다 — 읽기 실패는 «없음»(순수 그림자)이다. */
+export async function configuredTaskAgentLiveMoves(): Promise<ReadonlySet<TaskAgentLiveMove>> {
+  try {
+    const { getUserConfig } = await import('../user-config.js');
+    return resolveTaskAgentLiveMoves(getUserConfig().taskAgent?.liveMoves).moves;
+  } catch { return new Set(); }
+}
+
+export interface LiveMoveDeps {
+  statePath?: string;
+  now?: () => Date;
+  /** PR 머리 sha·상태 — 시험은 주입한다. 기본은 `gh pr view`(작업 트리 cwd). */
+  prHead?: (pr: number, cwd?: string) => Promise<{ head: string; state: string } | null>;
+  /** 리뷰 요청(떼어 띄운다) — 시험은 반드시 주입한다. */
+  requestReview?: (pr: number, intent: string, cwd?: string) => Promise<void>;
+  log?: (category: string, event: string, data: Record<string, unknown>) => void;
+}
+
+/** `executed` = 부작용을 실제로 냈다(리뷰를 띄웠다 · 제안을 적었다). ok 이지만 이미 한 수(같은 머리·이미 제안)면 false. */
+export interface LiveMoveResult { kind: TaskAgentLiveMove; card: string | null; ok: boolean; executed: boolean; detail: string }
+
+/** 받은 환경 그대로 먼저 묻고, 실패하면 프록시만 뺀 환경으로 한 번 더(이 저장소의 gh 운영 관행 — 프록시 경유가 gh 를 깨는 호스트). */
+export type GhRun = (args: string[], options: { env: NodeJS.ProcessEnv; cwd?: string }) => { status: number | null; stdout: string };
+const runGh: GhRun = (args, options) => spawnSync('gh', args, { encoding: 'utf8', timeout: 30_000, env: options.env, ...(options.cwd ? { cwd: options.cwd } : {}) });
+
+export async function defaultPrHead(pr: number, cwd?: string, gh: GhRun = runGh): Promise<{ head: string; state: string } | null> {
+  const view = (env: NodeJS.ProcessEnv) => gh(['pr', 'view', String(pr), '--json', 'headRefOid,state'], { env, ...(cwd ? { cwd } : {}) });
+  let out = view(process.env);
+  if (out.status !== 0) {
+    const noProxy = { ...process.env };
+    for (const key of ['HTTPS_PROXY', 'https_proxy', 'HTTP_PROXY', 'http_proxy']) delete noProxy[key];
+    out = view(noProxy);
+  }
+  if (out.status !== 0) return null;
+  try {
+    const value = JSON.parse(out.stdout) as { headRefOid?: unknown; state?: unknown };
+    return typeof value.headRefOid === 'string' && /^[a-f0-9]{40}$/i.test(value.headRefOid) && typeof value.state === 'string'
+      ? { head: value.headRefOid, state: value.state } : null;
+  } catch { return null; }
+}
+
+/** 리뷰 요청 argv — 진입점 · 같은 우주(`--config-dir`) · `self review <PR> --json --intent`. */
+export function liveReviewArgs(entry: string, configDir: string, pr: number, intent: string): string[] {
+  return [resolve(entry), '--config-dir', configDir, 'self', 'review', String(pr), '--json', '--intent', intent];
+}
+
+/**
+ * 지금 도는 진입점으로 같은 우주의 리뷰를 떼어 띄운다 — 기다리지 않는다(결과는 self review 자기 관측에 남는다).
+ * `opts` 는 시험 몫(spawn·진입점·우주) — 기본은 실물.
+ */
+export async function defaultRequestReview(pr: number, intent: string, cwd?: string, opts: { spawn?: DetachedSpawn; entry?: string; configDir?: string } = {}): Promise<void> {
+  const { spawnDetachedConfirmed, ELANOUS_CLI_ENTRY } = await import('../cli/tasks-cli.js');
+  const { getElanousConfigDirOverride } = await import('../elanous-config-dir.js');
+  const { effectiveInstanceRoot } = await import('../instance/resolve.js');
+  const configDir = opts.configDir ?? getElanousConfigDirOverride() ?? effectiveInstanceRoot();
+  await spawnDetachedConfirmed(opts.spawn ?? (spawn as unknown as DetachedSpawn), process.execPath, liveReviewArgs(opts.entry ?? ELANOUS_CLI_ENTRY, configDir, pr, intent), undefined, cwd);
+}
+
+export function liveReviewIntent(card: TaskCard, runId: string | null, stopReason: string): string {
+  const goal = card.text.split('\n')[0]!.trim().slice(0, 300);
+  return [
+    `목표: ${goal}`,
+    `수용기준: 과제 카드 ${card.id} 원문 —\n${card.text.trim().slice(0, 4000)}`,
+    `직전 반영분: 런 ${runId ?? '-'} 이 ${stopReason} 로 멈춤 — 수확 가능`,
+    '의도적 범위 경계: task-agent live review 요청(TA-JUDGE-LIVE-SAFE) — 리뷰만 한다 · 착지·재발사는 이 요청의 결정이 아니다',
+  ].join('\n');
+}
+
+/** 실행한 수를 관측에 남긴다(`live-move`). */
+function observe(deps: LiveMoveDeps, result: LiveMoveResult): LiveMoveResult {
+  try { (deps.log ?? ((c, e, d) => debug.log(c, e, d)))('task-agent', 'live-move', { ...result, live: true }); } catch { /* fail-soft */ }
+  return result;
+}
+
+/**
+ * 단위는 «관측한 머리»다 — `self review` 에 머리 고정 인자가 없어, 관측~리뷰 시작 사이에 머리가 바뀌면 새 머리가
+ * 다음 틱에 한 번 더 요청될 수 있다(초과는 많아야 한 번 · 리뷰는 읽기 전용이라 착지·재발사로 번지지 않는다).
+ */
+/** `review` — PR 머리마다 한 번. 카드에 먼저 적고(잠금 안) 그다음 띄운다 · 띄우기 실패는 카드에 오류로 남기고 같은 머리는 다시 안 띄운다. */
+export async function executeLiveReview(card: TaskCard | undefined, pr: number | undefined, ctx: { runId: string | null; stopReason: string; cwd?: string }, deps: LiveMoveDeps = {}): Promise<LiveMoveResult> {
+  const kind = 'review' as const;
+  if (!card) return observe(deps, { kind, executed: false, card: null, ok: false, detail: 'no task card — stays shadow' });
+  if (!pr || !Number.isSafeInteger(pr) || pr < 1) return observe(deps, { kind, executed: false, card: card.id, ok: false, detail: 'no PR — stays shadow' });
+  // PR 의 저장소(그 PR 을 낸 결과의 작업 트리)를 모르면 보류한다 — 다른 저장소에서 gh·self review 를 돌리지 않게.
+  if (!ctx.cwd) return observe(deps, { kind, executed: false, card: card.id, ok: false, detail: `PR #${pr} worktree unknown — stays shadow` });
+  let head: { head: string; state: string } | null;
+  try { head = await (deps.prHead ?? defaultPrHead)(pr, ctx.cwd); } catch { head = null; }
+  if (!head) return observe(deps, { kind, executed: false, card: card.id, ok: false, detail: `PR #${pr} head unknown` });
+  if (head.state !== 'OPEN') return observe(deps, { kind, executed: false, card: card.id, ok: false, detail: `PR #${pr} is ${head.state}` });
+  const path = deps.statePath ?? taskAgentStatePath();
+  const at = (deps.now ?? (() => new Date()))().toISOString();
+  const claim = { claimed: false, missing: false };
+  updateTaskCard(path, card.id, (current) => {
+    if (!current) { claim.missing = true; return undefined; }
+    // 머리 «이력»으로 본다 — A→B→A 로 돌아와도 A 는 다시 요청하지 않는다.
+    if ((current.reviewRequests ?? []).some((entry) => entry.pr === pr && entry.head === head!.head)) return undefined;
+    claim.claimed = true;
+    return { ...current, reviewRequests: [...(current.reviewRequests ?? []), { pr, head: head!.head, at }] };
+  });
+  if (claim.missing) return observe(deps, { kind, executed: false, card: card.id, ok: false, detail: 'task card not in state file' });
+  if (!claim.claimed) return observe(deps, { kind, executed: false, card: card.id, ok: true, detail: `already requested for #${pr} head ${head.head.slice(0, 12)}` });
+  try {
+    await (deps.requestReview ?? defaultRequestReview)(pr, liveReviewIntent(card, ctx.runId, ctx.stopReason), ctx.cwd);
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    updateTaskCard(path, card.id, (current) => current?.reviewRequests?.some((entry) => entry.pr === pr && entry.head === head!.head && entry.at === at)
+      ? { ...current, reviewRequests: current.reviewRequests.map((entry) => entry.pr === pr && entry.head === head!.head && entry.at === at ? { ...entry, error: reason } : entry) }
+      : undefined);
+    return observe(deps, { kind, executed: false, card: card.id, ok: false, detail: `review request failed for #${pr} head ${head.head.slice(0, 12)}: ${reason}` });
+  }
+  return observe(deps, { kind, executed: true, card: card.id, ok: true, detail: `review requested for #${pr} head ${head.head.slice(0, 12)}` });
+}
+
+/** `propose-green` — 비지 않은 근거가 있을 때만 카드에 제안을 적는다(한 번). 체크리스트는 쓰지 않는다. */
+export function executeLiveGreenProposal(card: TaskCard | undefined, evidence: Record<string, string>, deps: LiveMoveDeps = {}): LiveMoveResult {
+  const kind = 'propose-green' as const;
+  if (!card) return observe(deps, { kind, executed: false, card: null, ok: false, detail: 'no task card — stays shadow' });
+  const refs = Object.fromEntries(Object.entries(evidence).filter(([, ref]) => typeof ref === 'string' && ref.trim()));
+  if (!Object.keys(refs).length) return observe(deps, { kind, executed: false, card: card.id, ok: false, detail: 'no evidence ref — not proposed' });
+  const path = deps.statePath ?? taskAgentStatePath();
+  const proposal = { at: (deps.now ?? (() => new Date()))().toISOString(), checklistId: card.checklistId ?? null, evidence: refs };
+  const wrote = { proposed: false, missing: false };
+  updateTaskCard(path, card.id, (current) => {
+    if (!current) { wrote.missing = true; return undefined; }
+    if (current.greenProposal) return undefined;
+    wrote.proposed = true;
+    return { ...current, greenProposal: proposal };
+  });
+  if (wrote.missing) return observe(deps, { kind, executed: false, card: card.id, ok: false, detail: 'task card not in state file' });
+  if (!wrote.proposed) return observe(deps, { kind, executed: false, card: card.id, ok: true, detail: 'already proposed' });
+  return observe(deps, { kind, executed: true, card: card.id, ok: true, detail: `green proposed (${Object.values(refs).join(', ')}) · checklist untouched` });
+}

package/src/task-agent/mission.ts

@@ -12,7 +12,9 @@
 import { randomBytes } from 'node:crypto';
 import { debug } from '../debug/log.js';
 import type { SelfDevDecomposition } from '../self-dev/decompose.js';
+import { refreshCardRunBinding, type CardRunEvidenceDeps } from './card-evidence.js';
 import {
+  cardPrNumber,
   handTask,
   nextMoveFor,
   readTaskAgentState,
@@ -245,11 +247,19 @@ async function defaultEvidenceReader(ref: number | string): Promise<'merged' | '
   return predecessorState(ref);
 }
 
-/** 조각 카드마다 근거를 모은다 — PR 번호가 있으면 그것, 없으면 골 id. 읽기 실패는 pending(미착지). */
+/**
+ * 조각의 착지 근거 하나 — PR 번호 › 골 id. 수동(`--pr`/`--goal`)이든 런 원장 묶기든 같은 칸이다(TA-CARD-RUN-LINK) —
+ * 수동이 적히면 `refSource: 'manual'` 이라 묶기가 다시 채우지 않는다(수동이 덮는다).
+ */
+export function pieceRef(piece: Pick<TaskCard, 'pr' | 'goalId'>): number | string | undefined {
+  return cardPrNumber(piece) ?? piece.goalId;
+}
+
+/** 조각 카드마다 근거를 모은다 — `pieceRef` 순. 읽기 실패는 pending(미착지). */
 export async function collectPieceEvidence(pieces: readonly TaskCard[], read: PieceEvidenceReader = defaultEvidenceReader): Promise<Record<string, PieceEvidence>> {
   const out: Record<string, PieceEvidence> = {};
   for (const piece of pieces) {
-    const ref = piece.pr ?? piece.goalId;
+    const ref = pieceRef(piece);
     if (ref === undefined) { out[piece.id] = 'no-ref'; continue; }
     let state: 'merged' | 'waiting' | 'blocked';
     try { state = await read(ref); } catch { state = 'waiting'; }
@@ -275,8 +285,9 @@ export function recordPieceRef(pieceId: string, ref: { pr?: number; goalId?: str
     // green 제안 뒤 근거를 바꾸면 제안이 바뀐 근거와 어긋난다 — 제안된 미션의 조각 근거는 잠근다.
     if (tasks[current.mission]?.greenProposal) { refused.reason = `미션 ${current.mission} 은 이미 green 제안됐다 — 근거를 바꾸지 않는다`; return undefined; }
     // 근거는 하나만 — 새 근거가 옛 근거를 «교체»한다(정정한 골 id 뒤에 옛 PR 이 남아 우선되지 않게).
-    const { pr: _oldPr, goalId: _oldGoal, ...rest } = current;
-    return { ...rest, ...(ref.pr !== undefined ? { pr: ref.pr } : { goalId: ref.goalId! }) };
+    // 런 묶기가 적은 자식 런도 함께 지운다 — 수동 근거를 옛 Pod 자식 런의 결과처럼 보이지 않게.
+    const { pr: _oldPr, goalId: _oldGoal, runChildId: _oldChild, ...rest } = current;
+    return { ...rest, ...(ref.pr !== undefined ? { pr: ref.pr } : { goalId: ref.goalId! }), refSource: 'manual' as const };
   });
   if (refused.reason || !card) throw new Error(refused.reason ?? `미션 조각 카드가 아니다: ${pieceId}`);
   try { debug.log('task-agent', 'mission-piece-ref', { pieceId, missionId: card.mission ?? null, pr: ref.pr ?? null, goalId: ref.goalId ?? null }); } catch { /* fail-soft */ }
@@ -295,6 +306,8 @@ export interface AdvanceMissionOptions {
   statePath?: string;
   launcher?: TaskLauncher;
   readEvidence?: PieceEvidenceReader;
+  /** 런 id 가 있는 조각의 런 근거(PR·골 id) 읽기(시험 주입) — `false` 면 묶지 않는다. */
+  runEvidence?: CardRunEvidenceDeps | false;
   now?: () => Date;
 }
 
@@ -344,6 +357,19 @@ async function advanceMissionOnce(missionId: string, opts: AdvanceMissionOptions
   const clock = opts.now ?? (() => new Date());
   // live 인데 발사기가 없으면 claim 을 적기 «전»에 멈춘다 — live 표지가 발사 없이 남아 영영 안 넘겨지지 않게.
   if (mode === 'live' && !opts.launcher) throw new Error('--live 인데 launcher 가 없다');
+  const before = readTaskAgentState<{ tasks?: Record<string, TaskCard> }>(path).tasks ?? {};
+  if (!before[missionId]?.pieces) throw new Error(`미션 카드가 아니다: ${missionId}`);
+  // 런 id 가 있고 PR·골 id 중 빈 칸이 있는 조각 — 원장에서 묶어 둔다(제안 끝난 미션은 건드리지 않는다 · 실패는 근거 없음).
+  if (opts.runEvidence !== false && !before[missionId]!.greenProposal) {
+    for (const id of before[missionId]!.pieces!) {
+      const piece = before[id];
+      if (!piece?.runId || piece.refSource === 'manual' || (piece.pr !== undefined && piece.goalId !== undefined)) continue;
+      try { await refreshCardRunBinding(id, path, opts.runEvidence ?? {}); } catch (error) {
+        // 근거 없음으로 본다(미착지) — 원장 부재와 갈리게 실패는 남긴다.
+        try { debug.log('task-agent', 'card-bind-failed', { card: id, runId: piece.runId, via: 'advance', error: error instanceof Error ? error.message : String(error) }); } catch { /* fail-soft */ }
+      }
+    }
+  }
   const all = readTaskAgentState<{ tasks?: Record<string, TaskCard> }>(path).tasks ?? {};
   const mission = all[missionId];
   if (!mission?.pieces) throw new Error(`미션 카드가 아니다: ${missionId}`);
@@ -398,13 +424,13 @@ async function advanceMissionOnce(missionId: string, opts: AdvanceMissionOptions
     const proposal = {
       at: clock().toISOString(),
       checklistId: mission.checklistId ?? null,
-      evidence: Object.fromEntries(pieces.map((piece) => [piece.id, piece.pr !== undefined ? `#${piece.pr}` : `goal:${piece.goalId}`])),
+      evidence: Object.fromEntries(pieces.map((piece) => { const ref = pieceRef(piece); return [piece.id, typeof ref === 'number' ? `#${ref}` : `goal:${ref}`]; })),
     };
     const wrote = { proposed: false, stale: false };
     updateTaskCard(path, missionId, (current, tasks) => {
       if (!current || current.greenProposal) return undefined;
       // 조회에 쓴 근거가 잠금 안에서도 그대로일 때만 — 조회 도중 근거가 바뀌었으면 다음 호출이 다시 본다.
-      if (pieces.some((piece) => tasks[piece.id]?.pr !== piece.pr || tasks[piece.id]?.goalId !== piece.goalId)) { wrote.stale = true; return undefined; }
+      if (pieces.some((piece) => { const now = tasks[piece.id]; return (now ? cardPrNumber(now) : undefined) !== cardPrNumber(piece) || now?.goalId !== piece.goalId; })) { wrote.stale = true; return undefined; }
       wrote.proposed = true;
       return { ...current, greenProposal: proposal };
     });