elanous 0.2.18 → 0.2.20

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

@@ -0,0 +1,276 @@
+/**
+ * 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 { statSync } from 'node:fs';
+import { isAbsolute, resolve } from 'node:path';
+import { debug } from '../debug/log.js';
+import { findGitDir } from '../git-fs/locate.js';
+import { getUserConfig } from '../user-config.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·상태(·브랜치·URL) — 시험은 주입한다. 기본은 `gh pr view`(작업 트리 cwd). */
+  prHead?: (pr: number, cwd?: string) => Promise<PrHeadView | null>;
+  /** TA-LIVE-REVIEW-POD — 작업 트리가 없는 런(Pod)의 리뷰 저장소 후보. 기본은 카드 project.target → harness.defaultRepo → 호스트 checkout. */
+  repoCandidates?: (card: TaskCard) => readonly ReviewRepoCandidate[];
+  /** 리뷰 요청(떼어 띄운다) — 시험은 반드시 주입한다. */
+  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;
+  /** TA-LIVE-REVIEW-POD — 작업 트리 없이 리뷰 저장소를 찾았을 때(또는 못 찾았을 때)의 근거 한 줄. */
+  reviewRepo?: { resolved: boolean; source?: ReviewRepoCandidate['source']; cwd?: string; proof?: 'head-sha' | 'branch'; reason: string };
+}
+
+export interface PrHeadView { head: string; state: string; branch?: string; url?: string }
+
+/** 리뷰 저장소 후보 — 과제를 넘길 때 카드가 안 대상 · 하니스 기본 저장소(harness.defaultRepo · harness.repo 의 로컬 뿌리) · 호스트 checkout. */
+export interface ReviewRepoCandidate { source: 'card.project' | 'harness.defaultRepo' | 'host'; cwd: string }
+
+/** 기본 후보 — 존재하는 디렉터리만 · 같은 경로는 한 번. 읽기 실패는 그 후보를 뺀다(없음 ≠ 통과). */
+export function defaultReviewRepoCandidates(card: TaskCard, opts: { defaultRepo?: () => string | undefined; hostRoot?: () => string | undefined } = {}): ReviewRepoCandidate[] {
+  const raw: ReviewRepoCandidate[] = [];
+  if (card.project?.target && isAbsolute(card.project.target)) raw.push({ source: 'card.project', cwd: card.project.target });
+  try {
+    const configured = opts.defaultRepo ? opts.defaultRepo() : getUserConfig().harness?.defaultRepo;
+    if (configured && isAbsolute(configured)) raw.push({ source: 'harness.defaultRepo', cwd: configured });
+  } catch { /* 후보에서 뺀다 */ }
+  try {
+    const host = opts.hostRoot ? opts.hostRoot() : findGitDir(process.cwd())?.root;
+    if (host) raw.push({ source: 'host', cwd: host });
+  } catch { /* 후보에서 뺀다 */ }
+  const seen = new Set<string>();
+  const out: ReviewRepoCandidate[] = [];
+  for (const candidate of raw) {
+    if (!isAbsolute(candidate.cwd)) continue;
+    const cwd = resolve(candidate.cwd);
+    if (seen.has(cwd)) continue;
+    seen.add(cwd);
+    try { if (statSync(cwd).isDirectory()) out.push({ source: candidate.source, cwd }); } catch { /* 없는 디렉터리는 뺀다 */ }
+  }
+  return out;
+}
+
+/**
+ * TA-LIVE-REVIEW-POD — 작업 트리가 없을 때(Pod 런) 리뷰 cwd 를 정한다.
+ * 후보 저장소에서 `gh pr view <pr>` 가 «런이 낸 머리»(기록된 sha · 없으면 런의 브랜치)를 돌려줄 때만 그 저장소를 쓴다 —
+ * «다른 저장소에서 gh·self review 를 돌리지 않는다»(TA-JUDGE-LIVE-SAFE)는 계약을 지킨다. 못 정하면 이유 한 줄.
+ */
+export async function resolveReviewRepo(
+  card: TaskCard, pr: number,
+  produced: { headCommit?: string; branch?: string; prUrl?: string } | undefined,
+  deps: LiveMoveDeps = {},
+): Promise<{ resolved: true; cwd: string; source: ReviewRepoCandidate['source']; proof: 'head-sha' | 'branch'; view: PrHeadView; reason: string } | { resolved: false; reason: string }> {
+  // 호출자가 런 근거를 «안 넘긴» 것과 런이 «기록하지 않은» 것은 다른 사실이다 — 섞어 적지 않는다.
+  if (produced === undefined) return { resolved: false, reason: 'caller passed no run evidence (produced) — head/branch not checked' };
+  // 기록된 머리가 «있으면» 그것만 근거다 — 모양이 틀린 sha 를 브랜치로 대체하지 않는다(확인 못 한 머리로 리뷰하지 않게).
+  if (produced?.headCommit !== undefined && !/^[0-9a-f]{40}$/i.test(produced.headCommit)) {
+    return { resolved: false, reason: `run head ${JSON.stringify(produced.headCommit.slice(0, 40))} is not a full commit sha` };
+  }
+  const expectedHead = produced?.headCommit?.toLowerCase();
+  const expectedBranch = produced?.branch?.trim() || undefined;
+  if (!expectedHead && !expectedBranch) return { resolved: false, reason: 'run result carries no PR head or branch to confirm against' };
+  let candidates: readonly ReviewRepoCandidate[];
+  try { candidates = (deps.repoCandidates ?? defaultReviewRepoCandidates)(card); } catch { candidates = []; }
+  if (!candidates.length) return { resolved: false, reason: 'no target repository (card project · harness.defaultRepo · host checkout)' };
+  const sameUrl = (a: string, b: string) => a.trim().replace(/\/+$/, '').toLowerCase() === b.trim().replace(/\/+$/, '').toLowerCase();
+  const misses: string[] = [];
+  for (const candidate of candidates) {
+    let view: PrHeadView | null;
+    try { view = await (deps.prHead ?? defaultPrHead)(pr, candidate.cwd); } catch { view = null; }
+    if (!view) { misses.push(`${candidate.source}: PR #${pr} unreadable`); continue; }
+    if (produced?.prUrl && view.url && !sameUrl(view.url, produced.prUrl)) { misses.push(`${candidate.source}: PR url ${view.url} ≠ run ${produced.prUrl}`); continue; }
+    if (expectedHead) {
+      if (view.head.toLowerCase() !== expectedHead) { misses.push(`${candidate.source}: head ${view.head.slice(0, 12)} ≠ run ${expectedHead.slice(0, 12)}`); continue; }
+      return { resolved: true, cwd: candidate.cwd, source: candidate.source, proof: 'head-sha', view, reason: `${candidate.source} PR #${pr} head matches run` };
+    }
+    if (view.branch !== expectedBranch) { misses.push(`${candidate.source}: branch ${view.branch ?? '?'} ≠ run ${expectedBranch}`); continue; }
+    // 브랜치 근거는 sha 보다 약하다 — 같은 PR(저장소 · 번호)임을 URL 로 «양쪽 다» 확인할 때만 쓴다.
+    if (!produced?.prUrl || !view.url) { misses.push(`${candidate.source}: branch matches but PR url unconfirmed (run ${produced?.prUrl ?? 'none'} · repo ${view.url ?? 'none'})`); continue; }
+    return { resolved: true, cwd: candidate.cwd, source: candidate.source, proof: 'branch', view, reason: `${candidate.source} PR #${pr} head branch matches run` };
+  }
+  return { resolved: false, reason: misses.join(' · ') };
+}
+
+/** 받은 환경 그대로 먼저 묻고, 실패하면 프록시만 뺀 환경으로 한 번 더(이 저장소의 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<PrHeadView | null> {
+  const view = (env: NodeJS.ProcessEnv) => gh(['pr', 'view', String(pr), '--json', 'headRefOid,headRefName,state,url'], { 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; headRefName?: unknown; state?: unknown; url?: unknown };
+    return typeof value.headRefOid === 'string' && /^[a-f0-9]{40}$/i.test(value.headRefOid) && typeof value.state === 'string'
+      ? {
+        head: value.headRefOid, state: value.state,
+        ...(typeof value.headRefName === 'string' && value.headRefName ? { branch: value.headRefName } : {}),
+        ...(typeof value.url === 'string' && value.url ? { url: value.url } : {}),
+      } : 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; produced?: { headCommit?: string; branch?: string; prUrl?: 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 의 저장소를 모르면 보류한다 — 다른 저장소에서 gh·self review 를 돌리지 않게. 작업 트리가 없으면(Pod 런 ·
+  // TA-LIVE-REVIEW-POD) 후보 저장소 중 «런이 낸 PR 머리»가 확인되는 곳만 쓰고, 못 정하면 이유 한 줄을 관측에 싣는다.
+  let cwd = ctx.cwd;
+  let head: PrHeadView | null = null;
+  let reviewRepo: LiveMoveResult['reviewRepo'];
+  if (!cwd) {
+    const found = await resolveReviewRepo(card, pr, ctx.produced, deps);
+    if (!found.resolved) {
+      return observe(deps, { kind, executed: false, card: card.id, ok: false, detail: `PR #${pr} worktree unknown — stays shadow`, reviewRepo: { resolved: false, reason: found.reason } });
+    }
+    cwd = found.cwd;
+    head = found.view;
+    reviewRepo = { resolved: true, source: found.source, cwd: found.cwd, proof: found.proof, reason: found.reason };
+  } else {
+    try { head = await (deps.prHead ?? defaultPrHead)(pr, cwd); } catch { head = null; }
+  }
+  const withRepo = (result: LiveMoveResult): LiveMoveResult => reviewRepo ? { ...result, reviewRepo } : result;
+  if (!head) return observe(deps, withRepo({ kind, executed: false, card: card.id, ok: false, detail: `PR #${pr} head unknown` }));
+  if (head.state !== 'OPEN') return observe(deps, withRepo({ 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, withRepo({ kind, executed: false, card: card.id, ok: false, detail: 'task card not in state file' }));
+  if (!claim.claimed) return observe(deps, withRepo({ 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), 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, withRepo({ kind, executed: false, card: card.id, ok: false, detail: `review request failed for #${pr} head ${head.head.slice(0, 12)}: ${reason}` }));
+  }
+  return observe(deps, withRepo({ 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 */ }
@@ -285,7 +296,7 @@ export function recordPieceRef(pieceId: string, ref: { pr?: number; goalId?: str
 
 /** 이미 넘긴 조각인가 — live 는 live 넘김·발사·발사 실패면 다시 안 넘긴다 · shadow 는 어떤 넘김이든 있으면 안 넘긴다. */
 function alreadyHanded(card: TaskCard, mode: 'shadow' | 'live'): boolean {
-  if (card.status === 'launched' || card.status === 'launch-failed') return true;
+  if (card.status === 'launched' || card.status === 'launch-failed' || card.status === 'failed') return true;
   if (!card.handed) return false;
   return mode === 'shadow' || card.handed.mode === 'live';
 }
@@ -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 };
     });

package/src/task-agent/shadow.ts

@@ -5,14 +5,18 @@
  * - 입력은 슈퍼바이저 결과에 «이미 실려 있는» 값만 쓴다(네트워크 호출 0): 종료 어휘 ·
  *   PR 번호/병합 여부(`prNumber`·`merged`). 리뷰 판정·must-fix 는 결과에 없으므로 비운다
  *   («통과»로 읽지 않는다 — 판단부가 review 수를 고른다).
- * - 실행부는 언제나 shadow 로 부른다: «했을 수»만 기록하고 명령은 하나도 돌리지 않는다.
- *   설정 `taskAgent.mode=live` 도 이 경로에는 먹지 않는다(실행은 `autopilot task-agent-action` 몫).
+ * - 슈퍼바이저의 기본 호출은 shadow: «했을 수»만 기록하고 명령·복사는 하나도 돌리지 않는다.
+ *   전달 과제의 명시적 live 호출만 파일을 복사한다. 설정 `taskAgent.mode=live` 는 기본 호출에 먹지 않는다.
  * - 관측: `debug.log('task-agent', 'shadow-move', …)` → `elanous logs --category task-agent`.
  */
+import { lstatSync, readFileSync, readdirSync, realpathSync } from 'node:fs';
+import { extname, join, relative, resolve } from 'node:path';
 import { debug } from '../debug/log.js';
+import { readTaskAgentState, readTaskCard, taskAgentStatePath, type CompletionKind, type TaskCard } from './task-hand.js';
 import type { SupervisorJobResult, SupervisorStopReason } from '../self-dev/run-supervisor.js';
-import { executeNextAction, type NextAction } from './actions.js';
+import { executeNextAction, type DeliveryKind, type NextAction } from './actions.js';
 import { judgeNextMove, type TaskJudgeInput, type TaskJudgement } from './judge.js';
+import { configuredTaskAgentLiveMoves, executeLiveGreenProposal, executeLiveReview, type LiveMoveDeps, type LiveMoveResult, type TaskAgentLiveMove } from './live-moves.js';
 
 export interface TaskAgentShadowInput {
   runId: string | null;
@@ -27,23 +31,42 @@ export interface TaskAgentShadowMove {
   executorKind: TaskJudgement['executorKind'] | null;
   variant: TaskJudgement['executorVariant'] | null;
   reason: string;
-  /** 실행부 결과 — shadow 경로에서는 늘 'shadow'(실행부 밖의 수면 null). */
+  /** 실행부 결과 — 기본 shadow 경로에서는 'shadow'(실행부 밖의 수면 null). */
   executorResult: string | null;
   /** 실행부가 남긴 «했을 수» 문면. */
   wouldDo: string | null;
   pr: number | null;
+  /** TA-JUDGE-LIVE-SAFE — `taskAgent.liveMoves` 가 이 수를 실제로 했을 때만 실린다(없으면 종전 그대로 그림자). */
+  liveMove?: LiveMoveResult;
 }
 
 export interface TaskAgentShadowDeps {
   log?: (category: string, event: string, data: Record<string, unknown>) => void;
   /** 시험용 — shadow 실행부가 명령을 부르면 여기로 온다(정상이면 0회). */
   command?: (args: string[]) => Promise<{ status: number; stdout: string; stderr?: string }>;
+  readCard?: (taskId: string) => TaskCard | undefined;
+  /** Explicit live invocation only; supervisor's default hook always uses shadow. */
+  mode?: 'shadow' | 'live';
+  /** TA-JUDGE-LIVE-SAFE — 실제로 할 안전한 수(`review`·`propose-green`). 비면 설정 `taskAgent.liveMoves` 를 읽는다. */
+  liveMoves?: ReadonlySet<TaskAgentLiveMove>;
+  /** live 수의 부작용(리뷰 띄우기·PR 머리 조회·상태 파일) — 시험은 주입한다. */
+  live?: LiveMoveDeps;
 }
 
-/** 슈퍼바이저 결과에서 판단부 입력을 만든다 — 추가 조회 없이 이미 실린 값만. */
-export function shadowJudgeInput(stopReason: SupervisorStopReason, results: readonly SupervisorJobResult[]): TaskJudgeInput {
+/** 파일 산출물로 전달(elanous-out)하는 종결 종류 — 그 밖의 code-pr 밖 종류는 확인 증거를 판단부에서 기다린다. */
+const DELIVERY_KINDS: ReadonlySet<CompletionKind> = new Set<CompletionKind>(['research-report', 'artifact', 'content']);
+function isDeliveryKind(kind: CompletionKind | undefined): kind is DeliveryKind {
+  return kind !== undefined && DELIVERY_KINDS.has(kind);
+}
+
+/**
+ * 슈퍼바이저 결과에서 판단부 입력을 만든다 — 추가 조회 없이 이미 실린 값만.
+ * `completion` 은 카드의 종결 종류(§A4b③) — 있으면 판단부 입력에 싣는다(비면 종전 입력 그대로).
+ */
+export function shadowJudgeInput(stopReason: SupervisorStopReason, results: readonly SupervisorJobResult[], completion?: CompletionKind): TaskJudgeInput {
   const withPr = results.filter((result) => typeof result.prNumber === 'number' && result.prNumber > 0);
   const input: TaskJudgeInput = { stopReason };
+  if (completion !== undefined) input.completion = completion;
   if (withPr.length > 0) {
     input.pr = withPr[0]!.prNumber!;
     // 병합 여부만 결과에 실린다 — 닫힘(CLOSED)은 여기서 모른다. 병합이 아니면 OPEN 으로 둔다(판단부는 MERGED 만 본다).
@@ -52,24 +75,117 @@ export function shadowJudgeInput(stopReason: SupervisorStopReason, results: read
   return input;
 }
 
+export function selectDeliveryCandidates(worktreePath: string, kind: DeliveryKind): string[] {
+  const allowed = kind === 'research-report' ? new Set(['.md']) : new Set(['.md', '.html', '.pdf', '.png', '.pptx']);
+  try {
+    const root = realpathSync(worktreePath);
+    const gitMarker = join(root, '.git');
+    let gitPointer = '';
+    try { if (lstatSync(gitMarker).isFile()) gitPointer = readFileSync(gitMarker, 'utf8').trim(); }
+    catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error; }
+    const gitDir = gitPointer.startsWith('gitdir: ') ? resolve(root, gitPointer.slice(8)) : gitMarker;
+    const commonPointer = join(gitDir, 'commondir');
+    const sharedDir = (() => { try { return resolve(gitDir, readFileSync(commonPointer, 'utf8').trim()); } catch { return gitDir; } })();
+    let index: Buffer;
+    try { index = readFileSync(join(gitDir, 'index')); }
+    catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+      index = Buffer.alloc(12);
+      index.write('DIRC');
+      index.writeUInt32BE(2, 4);
+    }
+    const tracked = new Set<string>();
+    if (index.toString('ascii', 0, 4) !== 'DIRC' || ![2, 3].includes(index.readUInt32BE(4))) return [];
+    let offset = 12;
+    const count = index.readUInt32BE(8);
+    for (let i = 0; i < count; i++) {
+      const start = offset;
+      const flags = index.readUInt16BE(start + 60);
+      offset = start + 62;
+      if (flags & 0x4000) offset += 2;
+      const end = index.indexOf(0, offset);
+      if (end < 0) return [];
+      tracked.add(index.toString('utf8', offset, end));
+      offset = start + Math.ceil((end + 1 - start) / 8) * 8;
+    }
+    const ignored = (() => {
+      try { return readFileSync(join(root, '.gitignore'), 'utf8').split(/\r?\n/).map(line => line.trim()).filter(line => line && !line.startsWith('#')); }
+      catch { return [] as string[]; }
+    })();
+    const excluded = (() => {
+      try { return readFileSync(join(sharedDir, 'info', 'exclude'), 'utf8').split(/\r?\n/).map(line => line.trim()).filter(line => line && !line.startsWith('#')); }
+      catch { return [] as string[]; }
+    })();
+    const isIgnored = (name: string): boolean => [...ignored, ...excluded].some(pattern => {
+      const rule = pattern.replace(/^\//, '').replace(/\/$/, '');
+      if (rule.includes('*')) return new RegExp(`^${rule.split('*').map(part => part.replace(/[|\\{}()[\]^$+?.]/g, '\\$&')).join('.*')}$`).test(name);
+      return name === rule || name.startsWith(rule + '/') || name.split('/').includes(rule);
+    });
+    const candidates: string[] = [];
+    const walk = (dir: string): void => {
+      for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        if (entry.name === '.git' || entry.name === 'node_modules') continue;
+        const file = join(dir, entry.name);
+        const name = relative(root, file);
+        if (isIgnored(name)) continue;
+        if (entry.isDirectory()) { walk(file); continue; }
+        if (!entry.isFile()) continue;
+        if (allowed.has(extname(name).toLowerCase()) && !tracked.has(name) && lstatSync(file).isFile() && realpathSync(file) === file) candidates.push(name);
+      }
+    };
+    walk(root);
+    return candidates.sort();
+  } catch { return []; }
+}
+
+/** shadow-move 관측의 종결 종류 — 읽은 카드만 «비면 code-pr» 로 풀고, 조회 실패는 'unmeasured', 카드를 안 봤으면 null. */
+function shadowCompletion(card: TaskCard | undefined, lookupFailed: boolean): CompletionKind | 'unmeasured' | null {
+  if (card) return card.completion ?? 'code-pr';
+  return lookupFailed ? 'unmeasured' : null;
+}
+
 export async function recordTaskAgentShadowMove(input: TaskAgentShadowInput, deps: TaskAgentShadowDeps = {}): Promise<TaskAgentShadowMove> {
-  const judgeInput = shadowJudgeInput(input.stopReason, input.results);
-  const judgement = judgeNextMove(judgeInput);
+  const successful = input.results.find(result => result.ok === true && result.worktreePath);
+  let card: TaskCard | undefined;
+  let cardLookupFailed = false;
+  try {
+    card = successful ? (deps.readCard ?? readTaskCard)(successful.taskId) : undefined;
+    if (!card && successful && !deps.readCard) {
+      const tasks = readTaskAgentState<{ tasks?: Record<string, TaskCard> }>(taskAgentStatePath()).tasks ?? {};
+      const matches = Object.values(tasks).filter(candidate => candidate.status === 'launched' && candidate.text === successful.feature);
+      if (matches.length === 1) card = matches[0];
+    }
+  } catch {
+    // Card lookup is optional; preserve the original PR judgement when unavailable — but mark the completion kind as unmeasured.
+    cardLookupFailed = true;
+  }
+  const kind = card?.completion;
+  const judgeInput = shadowJudgeInput(input.stopReason, input.results, kind);
+  const delivery = successful?.worktreePath && card?.project?.target && isDeliveryKind(kind)
+    ? { kind, worktreePath: successful.worktreePath, projectTarget: card.project.target, files: selectDeliveryCandidates(successful.worktreePath, kind) }
+    : undefined;
+  const judgement: TaskJudgement = delivery
+    ? delivery.files.length
+      ? { move: 'wait', stage: 'observing', reason: '전달 후보 확인 — 산출물 판독 대기', executorKind: 'deliver' }
+      : { move: 'wait', stage: 'waiting', reason: '전달 후보 없음' }
+    : judgeNextMove(judgeInput);
+  if (cardLookupFailed) judgement.reason = `${judgement.reason} · 종결 종류 미확인(카드 조회 실패)`;
   let executorResult: string | null = null;
   let wouldDo: string | null = null;
   if (judgement.executorKind) {
     const action: NextAction = {
       kind: judgement.executorKind,
       ...(judgement.executorVariant ? { variant: judgement.executorVariant } : {}),
-      taskId: input.runId ?? 'run-unknown',
+      taskId: delivery ? card!.id : input.runId ?? 'run-unknown',
       rationale: judgement.reason,
-      pr: typeof judgeInput.pr === 'number' ? judgeInput.pr : 0,
+      pr: delivery ? 0 : typeof judgeInput.pr === 'number' ? judgeInput.pr : 0,
       runId: input.runId ?? '',
       original: [...new Set(input.results.map((result) => result.feature))].join(' · '),
-      checklistId: '',
+      checklistId: delivery ? card?.checklistId ?? '' : '',
+      ...(delivery ? { delivery } : {}),
     };
     executorResult = await executeNextAction(action, {
-      mode: 'shadow',
+      mode: delivery ? (deps.mode ?? 'shadow') : 'shadow',
       command: deps.command ?? (async () => { throw new Error('task-agent shadow path must not run commands'); }),
       observe: (_event, data) => { wouldDo = data.reason; },
     });
@@ -83,8 +199,69 @@ export async function recordTaskAgentShadowMove(input: TaskAgentShadowInput, dep
     reason: judgement.reason,
     executorResult,
     wouldDo,
-    pr: typeof judgeInput.pr === 'number' ? judgeInput.pr : null,
+    pr: delivery ? null : typeof judgeInput.pr === 'number' ? judgeInput.pr : null,
   };
-  (deps.log ?? ((category, event, data) => debug.log(category, event, data)))('task-agent', 'shadow-move', { ...move });
-  return move;
+  if (delivery && deps.mode !== 'live') {
+    move.wouldDo = `${move.wouldDo ?? 'would wait'} → ${join(delivery.projectTarget, 'elanous-out', card!.id)} (${delivery.files.join(', ')})`;
+  }
+  if (delivery && deps.mode === 'live') {
+    move.move = executorResult === 'done' ? 'propose-green' : 'wait';
+    move.reason = wouldDo ?? judgement.reason;
+    move.wouldDo = null;
+  }
+  const liveKind: TaskAgentLiveMove | null = move.move === 'review' || move.move === 'propose-green' ? move.move : null;
+  // 판단마다 해석한다 — 안전하지 않은 수를 판단할 때도 모르는 항목 경고가 남게(실행은 아래 두 수뿐).
+  const liveMoves = deps.liveMoves ?? await configuredTaskAgentLiveMoves();
+  const live = liveKind !== null && liveMoves.has(liveKind);
+  // 카드 id 는 모든 판단 관측에 싣는다(그림자 일치율을 카드로 잇는다) — 읽기 전용 조회.
+  // live 수는 «근거 결과»에 묶는다 — PR 수는 그 PR 을 낸 결과의 카드·작업 트리, 전달은 전달한 카드(다중 결과에서 남의 카드에 쓰지 않게).
+  const prResult = typeof judgeInput.pr === 'number' ? input.results.find((result) => result.prNumber === judgeInput.pr) : undefined;
+  const boundCard = delivery
+    ? card
+    : prResult
+      ? (card && successful?.taskId === prResult.taskId ? card : liveCardFor([prResult], deps))
+      : undefined;
+  // PR 에 묶인 수는 그 PR 의 카드만 관측에 싣는다(못 찾으면 null — 다른 결과의 카드로 대체하지 않는다).
+  const liveCard = prResult || delivery ? boundCard : card ?? (cardLookupFailed ? undefined : liveCardFor(input.results, deps));
+  let liveMove: LiveMoveResult | undefined;
+  if (live) {
+    if (liveKind === 'review') {
+      liveMove = await executeLiveReview(boundCard, prResult?.prNumber,
+        {
+          runId: input.runId, stopReason: input.stopReason,
+          ...(prResult?.worktreePath ? { cwd: prResult.worktreePath } : {}),
+          // TA-LIVE-REVIEW-POD — 작업 트리가 없는 런(Pod)은 «런이 낸 머리»로 리뷰 저장소를 확인한다.
+          ...(prResult && !prResult.worktreePath ? { produced: {
+            ...(prResult.checkedHeadCommit !== undefined ? { headCommit: prResult.checkedHeadCommit } : {}),
+            ...(prResult.branch ? { branch: prResult.branch } : {}),
+            ...(prResult.prUrl ? { prUrl: prResult.prUrl } : {}),
+          } } : {}),
+        }, { ...(deps.log ? { log: deps.log } : {}), ...deps.live });
+    } else {
+      const evidence: Record<string, string> = {};
+      if (boundCard && !delivery && judgeInput.prState === 'MERGED' && prResult) evidence[boundCard.id] = `#${prResult.prNumber}`;
+      else if (boundCard && delivery && deps.mode === 'live' && executorResult === 'done') evidence[boundCard.id] = join(delivery.projectTarget, 'elanous-out', boundCard.id);
+      liveMove = executeLiveGreenProposal(boundCard, evidence, { ...(deps.log ? { log: deps.log } : {}), ...deps.live });
+    }
+  }
+  // 판단한 수마다 live/shadow 를 남긴다 — OP 가 «오판 건수»·«그림자 일치율»을 카드·수 종류로 잰다.
+  (deps.log ?? ((category, event, data) => debug.log(category, event, data)))('task-agent', 'shadow-move', {
+    ...move, completion: shadowCompletion(card, cardLookupFailed), card: liveCard?.id ?? null, live, liveExecuted: liveMove?.executed ?? false, ...(liveMove ? { liveOk: liveMove.ok } : {}),
+  });
+  return liveMove ? { ...move, liveMove } : move;
+}
+
+/** live 수의 카드 — 성공한 결과가 없어도(수확 가능 런은 ok 가 아닐 수 있다) 결과의 taskId · 유일한 발사 문장으로 찾는다. */
+function liveCardFor(results: readonly SupervisorJobResult[], deps: TaskAgentShadowDeps): TaskCard | undefined {
+  try {
+    for (const result of results) {
+      const found = deps.readCard ? deps.readCard(result.taskId) : readTaskCard(result.taskId, deps.live?.statePath);
+      if (found) return found;
+    }
+    if (deps.readCard) return undefined;
+    const tasks = readTaskAgentState<{ tasks?: Record<string, TaskCard> }>(deps.live?.statePath ?? taskAgentStatePath()).tasks ?? {};
+    const features = new Set(results.map((result) => result.feature));
+    const matches = Object.values(tasks).filter(candidate => candidate.status === 'launched' && features.has(candidate.text));
+    return matches.length === 1 ? matches[0] : undefined;
+  } catch { return undefined; }
 }