elanous 0.2.25 → 0.2.28

package/src/task-agent/repair-worker.ts

@@ -0,0 +1,87 @@
+/** Detached HQ parent for one same-PR Pod repair. It never pushes or opens a PR. */
+import { spawn } from 'node:child_process';
+import { mkdirSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import type { RepairCommitResult } from './repair-branch-cas.js';
+import type { TaskChildLlm } from './task-hand.js';
+
+const SHA40 = /^[0-9a-f]{40}$/i;
+const SHA256 = /^[0-9a-f]{64}$/i;
+const MARKER = 'ELANOUS_POD_REPAIR_RESULT ';
+
+export interface RepairWorkerRequest {
+  card: string; pr: number; head: string; repo: string; resultPath: string;
+  entry: string; configDir: string; runId: string; seat?: string;
+  model: TaskChildLlm; goal: string;
+}
+
+export interface RepairWorkerResult {
+  pr: number; head: string; runId: string; ok: boolean; reason?: string;
+  job?: string; artifactDir?: string; result?: RepairCommitResult;
+}
+
+export function repairHarnessArgs(request: RepairWorkerRequest): string[] {
+  if (!Number.isSafeInteger(request.pr) || request.pr < 1 || !SHA40.test(request.head)
+    || !request.goal.trim() || !request.runId) throw new Error('repair worker request invalid');
+  return [request.entry, '--config-dir', request.configDir, 'harness', 'say', '--substrate', 'pod',
+    '--source', `pr:${request.pr}`, '--repair-commit-only', request.head,
+    ...(request.seat ? ['--seat', request.seat] : []), '--no-queue', '--no-auto-merge',
+    '--child-llm-provider', request.model.provider, '--child-llm-model', request.model.model,
+    ...(request.model.effort ? ['--child-llm-effort', request.model.effort] : []), '--', request.goal];
+}
+
+export function parseRepairMarker(output: string, pr: number, head: string, runId: string): Pick<RepairWorkerResult, 'job' | 'artifactDir' | 'result'> | null {
+  const line = output.split(/\r?\n/).reverse().find((entry: string) => entry.startsWith(MARKER));
+  if (!line) return null;
+  let value: unknown;
+  try { value = JSON.parse(line.slice(MARKER.length)); } catch { return null; }
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  const v = value as Record<string, unknown>;
+  if (v.pr !== pr || v.runId !== runId || typeof v.baseHead !== 'string' || v.baseHead.toLowerCase() !== head.toLowerCase()
+    || typeof v.commit !== 'string' || !SHA40.test(v.commit) || typeof v.bundleSha256 !== 'string' || !SHA256.test(v.bundleSha256)
+    || typeof v.job !== 'string' || !v.job || typeof v.artifactDir !== 'string' || !v.artifactDir.startsWith('/')) return null;
+  return { job: v.job, artifactDir: v.artifactDir,
+    result: { pr, baseHead: v.baseHead, runId, commit: v.commit, bundleSha256: v.bundleSha256 } };
+}
+
+export async function runRepairWorker(request: RepairWorkerRequest): Promise<RepairWorkerResult> {
+  const result: RepairWorkerResult = { pr: request.pr, head: request.head, runId: request.runId, ok: false };
+  try {
+    const args = repairHarnessArgs(request);
+    const child = spawn(process.execPath, args, {
+      cwd: request.repo, env: { ...process.env, ELANOUS_RUN_ID: request.runId }, stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    let output = '';
+    const append = (data: Buffer) => { output = (output + data.toString('utf8')).slice(-512_000); };
+    child.stdout?.on('data', append);
+    child.stderr?.on('data', append);
+    const code = await new Promise<number | null>((resolve, reject) => {
+      child.once('error', reject);
+      child.once('close', resolve);
+    });
+    const marker = parseRepairMarker(output, request.pr, request.head, request.runId);
+    if (code !== 0) result.reason = `harness exited ${code}: ${output.slice(-600)}`;
+    else if (!marker) result.reason = `repair artifact marker missing or invalid: ${output.slice(-600)}`;
+    else Object.assign(result, { ok: true, ...marker });
+  } catch (error) {
+    result.reason = error instanceof Error ? error.message : String(error);
+  }
+  mkdirSync(dirname(request.resultPath), { recursive: true });
+  const tmp = `${request.resultPath}.${process.pid}.tmp`;
+  writeFileSync(tmp, JSON.stringify(result));
+  renameSync(tmp, request.resultPath);
+  return result;
+}
+
+export function parseRepairWorkerResult(text: string, pr: number, head: string, runId: string): RepairWorkerResult | null {
+  let value: unknown;
+  try { value = JSON.parse(text); } catch { return null; }
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  const v = value as RepairWorkerResult;
+  if (v.pr !== pr || typeof v.head !== 'string' || v.head.toLowerCase() !== head.toLowerCase() || v.runId !== runId || typeof v.ok !== 'boolean') return null;
+  if (v.ok && (typeof v.artifactDir !== 'string' || !v.artifactDir.startsWith('/') || typeof v.job !== 'string' || !v.job
+    || !v.result || v.result.pr !== pr || typeof v.result.baseHead !== 'string'
+    || v.result.baseHead.toLowerCase() !== head.toLowerCase() || v.result.runId !== runId || !SHA40.test(v.result.commit)
+    || !SHA256.test(v.result.bundleSha256))) return null;
+  return v;
+}

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

@@ -13,15 +13,23 @@
 import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { isNoneSentinelFinding } from '../agent-substrate/pr-reviewer.js';
+import { repairReviewDigest } from './repair-review.js';
 import { debug } from '../debug/log.js';
-import { LIVE_MOVE_RESULT_EVENT, readTaskAgentState, updateTaskCard, type TaskCard, type TaskCardEvent } from './task-hand.js';
+import { LIVE_MOVE_RESULT_EVENT, cardPrNumber, readTaskAgentState, readTaskCard, updateTaskCard, type TaskCard, type TaskCardEvent } from './task-hand.js';
+import type { RejudgeDeps } from './rejudge-on-head.js';
 
 export const REVIEW_RESULT_MISSING_EFFECT = 'review process produced no result';
 /** 결과 파일은 있는데 읽지 못했다(EACCES 등) — «결과 없음»과 가른다(결과가 있었을 수 있다). */
 export const REVIEW_RESULT_UNREADABLE_EFFECT = 'review result file unreadable';
+/** Detached self review child: only this card and exact result file may trigger a completion tick. */
+export const TA_REVIEW_COMPLETION_CARD_ENV = 'ELANOUS_TA_REVIEW_COMPLETION_CARD';
+export const TA_REVIEW_COMPLETION_STATE_ENV = 'ELANOUS_TA_REVIEW_COMPLETION_STATE';
+export const TA_REVIEW_COMPLETION_RESULT_ENV = 'ELANOUS_TA_REVIEW_COMPLETION_RESULT';
 /** 리뷰 한 판(1차 ⊕ 폴백 · ACP 300s 상한 여러 번)을 넉넉히 덮는 대기 상한 — 이 안에는 «아직»으로 본다. */
 export const REVIEW_RESULT_WAIT_MS = 90 * 60_000;
 
+const reviewRejudgeInFlight = new Set<string>();
+
 const SHA40 = /^[0-9a-f]{40}$/i;
 
 /** 결과 파일 경로 — 카드 상태 파일 옆 `review-results/` · 카드 id 는 파일 이름에 안전한 글자만. */
@@ -88,6 +96,8 @@ export function pendingReviewResults(card: TaskCard): ReviewRequest[] {
 export interface CaptureReviewResultsOptions {
   /** 이 카드들만 본다 — 없으면 상태 파일의 모든 카드. */
   cardIds?: readonly string[];
+  /** A detached completion callback may only harvest its own result file. */
+  resultPaths?: readonly string[];
   now?: () => Date;
   /** 시험 seam — 결과 파일 읽기(없으면 ENOENT 를 던진다). */
   readFile?: (path: string) => string;
@@ -123,6 +133,7 @@ export function captureReviewResults(statePath: string, opts: CaptureReviewResul
     if (!card) continue;
     for (const request of pendingReviewResults(card)) {
       const resultPath = request.resultPath!;
+      if (opts.resultPaths && !opts.resultPaths.includes(resultPath)) continue;
       let text: string | null = null;
       let readError: string | null = null;
       let unreadable = false;
@@ -145,7 +156,7 @@ export function captureReviewResults(statePath: string, opts: CaptureReviewResul
           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,
+          resultPath, reviewSha256: repairReviewDigest(text!),
           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) } : {}),
         };
@@ -184,6 +195,59 @@ export function captureReviewResults(statePath: string, opts: CaptureReviewResul
   return out;
 }
 
+/** Run after the detached review child has fully written its JSON stdout. Never infer a card from PR alone. */
+export async function rejudgeCompletedTaskReview(
+  env: Record<string, string | undefined> = process.env,
+  rejudge?: (cardId: string, statePath: string) => Promise<unknown>,
+  rejudgeDeps?: RejudgeDeps,
+): Promise<boolean> {
+  const cardId = env[TA_REVIEW_COMPLETION_CARD_ENV];
+  const statePath = env[TA_REVIEW_COMPLETION_STATE_ENV];
+  const resultPath = env[TA_REVIEW_COMPLETION_RESULT_ENV];
+  if (!cardId || !statePath || !resultPath) return false;
+  const before = readTaskCard(cardId, statePath);
+  const bound = before?.reviewRequests?.find((item) => item.resultPath === resultPath);
+  if (before?.status !== 'launched' || before.taLand !== true || !bound || cardPrNumber(before) !== bound.pr
+    || !SHA40.test(bound.head) || (before.history ?? []).some((item) => item.event === 'async-result-rejudge' && item.resultPath === resultPath)) return false;
+  captureReviewResults(statePath, { cardIds: [cardId], resultPaths: [resultPath] });
+  const key = `${statePath}\0${cardId}\0${resultPath}`;
+  if (reviewRejudgeInFlight.has(key)) return false;
+  const card = readTaskCard(cardId, statePath);
+  const request = card?.reviewRequests?.find((item) => item.resultPath === resultPath);
+  if (card?.status !== 'launched' || card.taLand !== true || !request || cardPrNumber(card) !== request.pr
+    || !(card.history ?? []).some((item) => item.event === LIVE_MOVE_RESULT_EVENT && item.resultPath === resultPath && item.kind === 'review'
+      && item.pr === request.pr && SHA40.test(request.head) && SHA40.test(item.head ?? '')
+      && item.effect?.startsWith('review result captured') && item.reviewed === true && item.head?.toLowerCase() === request.head.toLowerCase())
+    || (card.history ?? []).some((item) => item.event === 'async-result-rejudge' && item.resultPath === resultPath)) return false;
+  reviewRejudgeInFlight.add(key);
+  try {
+    const run = async (): Promise<unknown> => {
+      if (rejudgeDeps) {
+        const { rejudgeShadowCard } = await import('./rejudge-on-head.js');
+        return rejudgeShadowCard(cardId, statePath, rejudgeDeps, { pr: request.pr, head: request.head, kind: 'review', resultPath });
+      } else if (rejudge) return rejudge(cardId, statePath);
+      else {
+        const { rejudgeAsyncResultCard } = await import('./rejudge-on-head.js');
+        return rejudgeAsyncResultCard(cardId, statePath, {}, { pr: request.pr, head: request.head, kind: 'review', resultPath });
+      }
+    };
+    const { requireCompletedHeadRejudge } = await import('./rejudge-on-head.js');
+    try { requireCompletedHeadRejudge(await run(), request.pr, request.head); }
+    catch { requireCompletedHeadRejudge(await run(), request.pr, request.head); } // Bounded retry; no marker on failed outcomes.
+    updateTaskCard(statePath, cardId, (current) => current?.status === 'launched' && current.taLand === true && cardPrNumber(current) === request.pr
+      && (current.reviewRequests ?? []).some((item) => item.pr === request.pr && SHA40.test(item.head) && item.head.toLowerCase() === request.head.toLowerCase() && item.resultPath === resultPath)
+      && (current.history ?? []).some((item) => item.event === LIVE_MOVE_RESULT_EVENT && item.resultPath === resultPath && item.kind === 'review'
+        && item.pr === request.pr && SHA40.test(item.head ?? '') && item.head?.toLowerCase() === request.head.toLowerCase()
+        && item.reviewed === true && item.effect?.startsWith('review result captured'))
+      && !(current.history ?? []).some((item) => item.event === 'async-result-rejudge' && item.resultPath === resultPath)
+      ? { ...current, history: [...(current.history ?? []), { at: new Date().toISOString(), event: 'async-result-rejudge', kind: 'review', pr: request.pr, head: request.head, resultPath, effect: 'completion callback succeeded' }] }
+      : undefined);
+  } finally {
+    reviewRejudgeInFlight.delete(key);
+  }
+  return true;
+}
+
 /**
  * 다음 수 판단의 입력 — 카드에 회수된 리뷰 결과 중 «그 머리(`head`)»의 «가장 최근» 결과가 실제로 돈(reviewed) pass 이고
  * 리뷰한 머리가 40자 sha 일 때만 `selfReview` 모양으로 돌려준다(슈퍼바이저가 나르는 `self-implement-cli` 의 규칙과 같다 ·

package/src/task-agent/shadow.ts

@@ -10,17 +10,22 @@
  * - 관측: `debug.log('task-agent', 'shadow-move', …)` → `elanous logs --category task-agent`.
  */
 import { lstatSync, readFileSync, readdirSync, realpathSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
 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 { readTaskAgentState, readTaskCard, taskAgentStatePath, TASK_CARD_PREFIX, type CompletionKind, type TaskCard } from './task-hand.js';
 import type { SupervisorJobResult, SupervisorStopReason } from '../self-dev/run-supervisor.js';
-import { executeNextAction, type DeliveryKind, type NextAction } from './actions.js';
-import { judgeNextMove, type TaskJudgeInput, type TaskJudgement } from './judge.js';
+import { executeNextAction, type ActionDeps, type DeliveryKind, type NextAction } from './actions.js';
+import { judgeNextMove, LIVE_RETRY_MOVES, type TaskJudgeInput, type TaskJudgement } from './judge.js';
 import { HARNESS_RUN_ID_ENV } from '../harness/harness-space.js';
-import { collectWiringEvidence, type WiringEvidenceDeps } from './card-evidence.js';
-import { recordLiveMoveHistory } from './live-move-history.js';
+import { appendRunLedgerEntry, loadRunLedger } from '../self-implement/run-ledger.js';
+import { collectWiringEvidence, readCardRunSnapshot, type WiringEvidenceDeps, type CardRunEvidenceDeps } from './card-evidence.js';
+import { remoteLedgerMirrorDir } from './parent-host.js';
+import { prodInstanceRoot } from '../instance/resolve.js';
+import { liveMoveHistoryEntry, recordLiveMoveHistory } from './live-move-history.js';
+import { updateTaskCard } from './task-hand.js';
 import { capturedSelfReview, captureReviewResults, hasCapturedPass } from './review-result-capture.js';
-import { configuredTaskAgentLiveMoves, defaultPrHead, executeLiveGreenProposal, executeLiveLand, executeLiveReview, type LiveMoveDeps, type LiveMoveResult, type TaskAgentLiveMove } from './live-moves.js';
+import { configuredTaskAgentLiveMoves, defaultPrHead, executeLiveDecisionCard, executeLiveGreenProposal, executeLiveLand, executeLiveReview, type LiveMoveDeps, type LiveMoveResult, type TaskAgentLiveMove } from './live-moves.js';
 
 export interface TaskAgentShadowInput {
   runId: string | null;
@@ -46,12 +51,16 @@ export interface TaskAgentShadowMove {
   pr: number | null;
   /** TA-JUDGE-LIVE-SAFE — `taskAgent.liveMoves` 가 이 수를 실제로 했을 때만 실린다(없으면 종전 그대로 그림자). */
   liveMove?: LiveMoveResult;
+  /** 원격 카드 결선이 미결일 때 런 원장 대기열 보존 결과. */
+  cardBinding?: 'pending' | 'queue-failed';
 }
 
 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 }>;
+  /** 재발사 live 실행부 명령(주입되지 않으면 shadow). */
+  command?: ActionDeps['command'];
+  /** 재발사 live 부하 관문(주입되지 않으면 shadow). */
+  loadGate?: ActionDeps['loadGate'];
   readCard?: (taskId: string) => TaskCard | undefined;
   /** Explicit live invocation only; supervisor's default hook always uses shadow. */
   mode?: 'shadow' | 'live';
@@ -65,8 +74,12 @@ export interface TaskAgentShadowDeps {
   wiring?: Omit<WiringEvidenceDeps, 'card'>;
   /** Process env for the launched-run id (`ELANOUS_RUN_ID`) — test seam; default process.env. */
   env?: NodeJS.ProcessEnv;
+  /** Remote pending-move ledger seam; defaults to the run ledger. */
+  queueMove?: typeof appendRunLedgerEntry;
 }
 
+export const REMOTE_CARD_MOVE_PENDING = 'task-agent-card-move-pending';
+
 /** 카드 조회 상태 파일 — 조회 경로 전부가 같은 파일을 본다. */
 function cardStatePath(deps: TaskAgentShadowDeps): string {
   return deps.statePath ?? deps.live?.statePath ?? taskAgentStatePath();
@@ -175,6 +188,13 @@ function shadowCompletion(card: TaskCard | undefined, lookupFailed: boolean): Co
 }
 
 export async function recordTaskAgentShadowMove(input: TaskAgentShadowInput, deps: TaskAgentShadowDeps = {}): Promise<TaskAgentShadowMove> {
+  const env = deps.env ?? process.env;
+  const remoteChild = !!env.ELANOUS_POD_NAME;
+  const hintedCard = env.ELANOUS_TASK_CARD_ID?.trim();
+  const pendingCardId = hintedCard?.startsWith(TASK_CARD_PREFIX) && hintedCard.length <= 63 && /^[A-Za-z0-9._-]+$/.test(hintedCard) ? hintedCard : null;
+  const parentRunId = env.ELANOUS_PARENT_RUN_ID?.trim() || null;
+  const matchesLaunchCard = (candidate: TaskCard | undefined): boolean => !!candidate && !!parentRunId
+    && candidate.id === pendingCardId && candidate.runId === parentRunId;
   // TA-REVIEW-RESULT-CAPTURE — 판단 «전»에 지난 live review 의 결과 파일을 회수한다(카드 원장을 아는 때만 · 던지지 않는다).
   //   대기 중인 요청이 없으면 아무것도 쓰지 않는다(결과 파일 없는 카드의 동작은 종전과 같다).
   const reviewLedger = cardLedgerPath(deps);
@@ -188,14 +208,22 @@ export async function recordTaskAgentShadowMove(input: TaskAgentShadowInput, dep
   let card: TaskCard | undefined;
   let cardLookupFailed = false;
   try {
-    card = successful ? (deps.readCard ? deps.readCard(successful.taskId) : readTaskCard(successful.taskId, cardStatePath(deps))) : undefined;
-    if (!card && successful && !deps.readCard) {
+    // Pod 에 발사 카드 id 가 있으면 그 id 만 믿는다. 같은 문장을 가진 다른 카드가 있어도 묶지 않는다.
+    if (remoteChild) {
+      if (pendingCardId) {
+        const found = deps.readCard ? deps.readCard(pendingCardId) : readTaskCard(pendingCardId, cardStatePath(deps));
+        if (matchesLaunchCard(found)) card = found;
+      }
+    } else if (successful) {
+      card = deps.readCard ? deps.readCard(successful.taskId) : readTaskCard(successful.taskId, cardStatePath(deps));
+    }
+    if (!card && successful && !deps.readCard && !remoteChild) {
       const tasks = readTaskAgentState<{ tasks?: Record<string, TaskCard> }>(cardStatePath(deps)).tasks ?? {};
       const matches = Object.values(tasks).filter(candidate => candidate.status === 'launched' && candidate.text === successful.feature);
       if (matches.length === 1) card = matches[0];
     }
     // TA-OWN-ALL-RUNS — 런 소유 카드: 입력 runId ⊕ 상속 ELANOUS_RUN_ID(Pod 자식의 부모 런) 중 카드 runId 와 «정확히» 같은 것만.
-    if (!card && !deps.readCard) card = runCardFor(input.runId, deps);
+    if (!card && !deps.readCard && !remoteChild) card = runCardFor(input.runId, deps);
   } catch {
     // Card lookup is optional; preserve the original PR judgement when unavailable — but mark the completion kind as unmeasured.
     cardLookupFailed = true;
@@ -209,7 +237,7 @@ export async function recordTaskAgentShadowMove(input: TaskAgentShadowInput, dep
     try {
       const reviewedPr = judgeInput.pr;
       const prRun = input.results.find((result) => result.prNumber === reviewedPr);
-      const prCard = prRun ? (card && successful?.taskId === prRun.taskId ? card : liveCardFor([prRun], deps, input.runId)) : undefined;
+      const prCard = prRun ? (remoteChild ? card : card && successful?.taskId === prRun.taskId ? card : liveCardFor([prRun], deps, input.runId)) : undefined;
       // 회수한 판정은 «리뷰한 머리»의 것이다 — 지금 PR 머리의 결과만 입력으로 쓴다(A 의 pass 로 B 를 land 쪽으로 보내지 않게 ·
       //   여러 머리 결과가 역순으로 회수돼도 지금 머리 것을 고른다). 지금 머리 = 그 런 작업 트리에서 PR 머리 조회 ·
       //   작업 트리가 없으면(Pod) 런이 낸 머리. 못 정하면 쓰지 않는다(종전처럼 review 수 → 새 머리면 새 리뷰).
@@ -239,6 +267,9 @@ export async function recordTaskAgentShadowMove(input: TaskAgentShadowInput, dep
       : { move: 'wait', stage: 'waiting', reason: '전달 후보 없음' }
     : judgeNextMove(judgeInput);
   if (cardLookupFailed) judgement.reason = `${judgement.reason} · 종결 종류 미확인(카드 조회 실패)`;
+  // 판단마다 해석한다 — 허용되지 않은 수를 판단할 때도 모르는 항목 경고가 남게.
+  const liveMoves = deps.liveMoves ?? await configuredTaskAgentLiveMoves();
+  const retryLaunches = { count: 0 };
   let executorResult: string | null = null;
   let wouldDo: string | null = null;
   if (judgement.executorKind) {
@@ -253,10 +284,13 @@ export async function recordTaskAgentShadowMove(input: TaskAgentShadowInput, dep
       checklistId: delivery ? card?.checklistId ?? '' : '',
       ...(delivery ? { delivery } : {}),
     };
+    const liveRetry = !delivery && deps.command !== undefined && deps.loadGate !== undefined
+      && (LIVE_RETRY_MOVES as readonly string[]).includes(judgement.move) && liveMoves.has(judgement.move as TaskAgentLiveMove);
     executorResult = await executeNextAction(action, {
-      mode: delivery ? (deps.mode ?? 'shadow') : 'shadow',
+      mode: delivery ? (deps.mode ?? 'shadow') : liveRetry ? 'live' : 'shadow',
       command: deps.command ?? (async () => { throw new Error('task-agent shadow path must not run commands'); }),
       observe: (_event, data) => { wouldDo = data.reason; },
+      ...(liveRetry ? { liveMoves, retryLaunches, loadGate: deps.loadGate } : {}),
     });
   }
   const move: TaskAgentShadowMove = {
@@ -278,20 +312,21 @@ export async function recordTaskAgentShadowMove(input: TaskAgentShadowInput, dep
     move.reason = wouldDo ?? judgement.reason;
     move.wouldDo = null;
   }
-  const liveKind: TaskAgentLiveMove | null = move.move === 'review' || move.move === 'propose-green' || move.move === 'propose-land' ? move.move : null;
-  // 판단마다 해석한다 — 허용되지 않은 수를 판단할 때도 모르는 항목 경고가 남게.
-  const liveMoves = deps.liveMoves ?? await configuredTaskAgentLiveMoves();
-  const live = liveKind !== null && liveMoves.has(liveKind);
+  const liveKind: TaskAgentLiveMove | null = move.move === 'review' || move.move === 'propose-green' || move.move === 'propose-land' || move.move === 'decision-card' ? move.move : null;
   // 카드 id 는 모든 판단 관측에 싣는다(그림자 일치율을 카드로 잇는다) — 읽기 전용 조회.
   // live 수는 «근거 결과»에 묶는다 — PR 수는 그 PR 을 낸 결과의 카드·작업 트리, 전달은 전달한 카드(다중 결과에서 남의 카드에 쓰지 않게).
   const prResult = typeof judgeInput.pr === 'number' ? input.results.find((result) => result.prNumber === judgeInput.pr) : undefined;
-  const boundCard = delivery
+  const candidateBoundCard = delivery
     ? card
     : prResult
-      ? (card && successful?.taskId === prResult.taskId ? card : liveCardFor([prResult], deps, input.runId))
-      : undefined;
+      ? (card && (successful?.taskId === prResult.taskId || (remoteChild && pendingCardId === card.id)) ? card : liveCardFor([prResult], deps, input.runId))
+      : liveKind === 'decision-card' ? card ?? liveCardFor(input.results, deps, input.runId) : undefined;
+  const boundCard = remoteChild && !matchesLaunchCard(candidateBoundCard) ? undefined : candidateBoundCard;
   // PR 에 묶인 수는 그 PR 의 카드만 관측에 싣는다(못 찾으면 null — 다른 결과의 카드로 대체하지 않는다).
-  const liveCard = prResult || delivery ? boundCard : card ?? (cardLookupFailed ? undefined : liveCardFor(input.results, deps, input.runId));
+  const candidateLiveCard = prResult || delivery ? boundCard : card ?? (cardLookupFailed ? undefined : liveCardFor(input.results, deps, input.runId));
+  const liveCard = remoteChild && !matchesLaunchCard(candidateLiveCard) ? undefined : candidateLiveCard;
+  // 원격 Pod 는 HQ 카드 파일을 갖지 않는다. id 를 전달받아도 현지 원장이 없으면 실행 수는 보류한다.
+  const live = liveKind !== null && liveMoves.has(liveKind) && (!remoteChild || boundCard !== undefined);
   let liveMove: LiveMoveResult | undefined;
   if (live) {
     if (liveKind === 'review') {
@@ -316,6 +351,17 @@ export async function recordTaskAgentShadowMove(input: TaskAgentShadowInput, dep
             ...(prResult.prUrl ? { prUrl: prResult.prUrl } : {}),
           } } : {}),
         }, liveMoveDeps(deps));
+    } else if (liveKind === 'decision-card') {
+      // Supervisor results carry failure text and reviewer must-fix items, but no screen tail.
+      // A stop reason alone is not evidence: the executor correctly raises no card when both are absent.
+      const evidenceResults = prResult ? [prResult] : input.results;
+      const signature = evidenceResults.find((result) => result.error?.message?.trim())?.error?.message;
+      const mustFix = evidenceResults.flatMap((result) => result.reviewMustFix ?? []);
+      liveMove = await executeLiveDecisionCard(boundCard, {
+        runId: input.runId, stopReason: input.stopReason, reason: move.reason,
+        ...(prResult ? { pr: prResult.prNumber } : {}),
+        evidence: { ...(signature ? { signature } : {}), mustFix },
+      }, liveMoveDeps(deps));
     } else {
       const evidence: Record<string, string> = {};
       if (boundCard && !delivery && judgeInput.prState === 'MERGED' && prResult) evidence[boundCard.id] = `#${prResult.prNumber}`;
@@ -323,11 +369,6 @@ export async function recordTaskAgentShadowMove(input: TaskAgentShadowInput, dep
       liveMove = executeLiveGreenProposal(boundCard, evidence, liveMoveDeps(deps));
     }
   }
-  // 판단한 수마다 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 } : {}),
-    ...(reviewFromCapture ? { reviewSource: 'captured-review-result' } : {}),
-  });
   // TA-WIRING-CHECK — 병합 PR 은 판단한 «뒤» 배선 근거를 관측만 한다(move 불변 · 실패는 unknown 으로 남기고 던지지 않는다).
   if (judgeInput.prState === 'MERGED' && typeof judgeInput.pr === 'number' && !delivery && liveCard) {
     try {
@@ -339,19 +380,51 @@ export async function recordTaskAgentShadowMove(input: TaskAgentShadowInput, dep
   }
   // TA-LIVE-MOVE-CARD-HISTORY — live-move 수(review·propose-green·propose-land)는 실행이든 그림자든 그 카드 history 에 한 줄.
   // 결정·실행이 끝난 «뒤»에 덧붙이기만 한다(반환값·관측 무변경) · 실패는 관측만(live-move 를 막지 않는다).
-  if (liveKind !== null) recordLiveMoveOnCard({
+  if (liveKind !== null && (liveKind !== 'decision-card' || live) && (!remoteChild || liveCard)) recordLiveMoveOnCard({
     liveKind, live, liveMove, card: live ? boundCard : liveCard, runId: input.runId,
     pr: prResult?.prNumber ?? (typeof judgeInput.pr === 'number' ? judgeInput.pr : undefined),
     shadowDetail: move.wouldDo ?? move.reason,
   }, deps);
-  return liveMove ? { ...move, liveMove } : move;
+  let cardBinding: TaskAgentShadowMove['cardBinding'];
+  if (liveKind !== null && !liveCard && remoteChild) {
+    const inheritedRunId = parentRunId || env[HARNESS_RUN_ID_ENV]?.trim() || null;
+    const reason = !parentRunId ? 'parent run id absent; HQ binding required'
+      : pendingCardId ? 'card id carried but ledger unavailable' : 'card id absent; parent run lookup required';
+    try {
+      if (!input.runId) throw new Error('runId absent');
+      (deps.queueMove ?? appendRunLedgerEntry)({
+        timestamp: new Date().toISOString(), runId: input.runId, event: REMOTE_CARD_MOVE_PENDING,
+        data: { id: randomUUID(), card: pendingCardId, parentRunId: inheritedRunId, kind: liveKind, pr: move.pr,
+          detail: move.wouldDo ?? move.reason, reason, executorResult: 'shadow' },
+      });
+      cardBinding = 'pending';
+    } catch (error) {
+      cardBinding = 'queue-failed';
+      try {
+        (deps.log ?? ((c, e, d) => debug.log(c, e, d)))('task-agent', 'card-binding-queue-failed',
+          { card: pendingCardId, runId: input.runId, parentRunId: inheritedRunId, kind: liveKind, reason: error instanceof Error ? error.message : String(error) });
+      } catch { /* queue failure remains visible in the return value */ }
+    }
+    if (cardBinding === 'pending') try {
+      (deps.log ?? ((c, e, d) => debug.log(c, e, d)))('task-agent', 'card-binding-pending',
+        { card: pendingCardId, runId: input.runId, parentRunId: inheritedRunId, kind: liveKind, reason });
+    } catch { /* queued evidence remains authoritative */ }
+  }
+  // 판단 관측은 원격 미결 수를 실제 원장에 기록한 결과까지 확정한 뒤 남긴다.
+  (deps.log ?? ((category, event, data) => debug.log(category, event, data)))('task-agent', 'shadow-move', {
+    ...move, completion: shadowCompletion(card, cardLookupFailed), card: liveCard?.id ?? pendingCardId,
+    live, liveExecuted: liveMove?.executed ?? false, ...(liveMove ? { liveOk: liveMove.ok } : {}),
+    ...(cardBinding ? { cardBinding } : {}),
+    ...(reviewFromCapture ? { reviewSource: 'captured-review-result' } : {}),
+  });
+  return { ...move, ...(liveMove ? { liveMove } : {}), ...(cardBinding ? { cardBinding } : {}) };
 }
 
 /**
  * 런 id 폴백 — 입력 runId(슈퍼바이저 · Pod 면 자식 런) → 상속 `ELANOUS_RUN_ID`(발사기가 넘긴 부모 런) 순으로,
  * 카드 runId 와 정확히 같고 그 카드가 하나뿐일 때만 쓴다. 못 찾으면 추측하지 않고 이유 한 줄을 남긴다(조용한 미스 0).
  */
-function runCardFor(runId: string | null | undefined, deps: TaskAgentShadowDeps): TaskCard | undefined {
+export function runCardFor(runId: string | null | undefined, deps: TaskAgentShadowDeps): TaskCard | undefined {
   const own = runId?.trim() || undefined;
   const inherited = (deps.env ?? process.env)[HARNESS_RUN_ID_ENV]?.trim() || undefined;
   if (!own && !inherited) return undefined;
@@ -370,6 +443,54 @@ function runCardFor(runId: string | null | undefined, deps: TaskAgentShadowDeps)
   return undefined;
 }
 
+/** HQ `tasks show` 가 원격 원장 거울의 미결 수를 카드에 회수한다. 부모→자식 원장 간선과 카드 id 를 함께 확인한다. */
+export async function replayRemoteCardMoves(cardId: string, statePath: string, evidenceDeps: CardRunEvidenceDeps = {},
+  log: (category: string, event: string, data: Record<string, unknown>) => void = (c, e, d) => debug.log(c, e, d)): Promise<number> {
+  const card = readTaskCard(cardId, statePath);
+  if (!card?.runId || !card.parentHost) return 0;
+  // 원격 부모와 동일 runId 의 HQ 국소 원장은 발사 영수증만 있을 수 있다. 이 회수는 원격 거울을 우선한다.
+  const loadLedger = evidenceDeps.loadLedger ?? ((runId: string) =>
+    loadRunLedger(runId, remoteLedgerMirrorDir(prodInstanceRoot(), card.parentHost!.host)));
+  const snapshot = await readCardRunSnapshot(card, { ...evidenceDeps, loadLedger });
+  if (snapshot.readErrors?.length) {
+    log('task-agent', 'card-binding-replay-failed', { card: cardId, runId: card.runId, reason: snapshot.readErrors.join(' · ') });
+    return 0;
+  }
+  // 카드 id 가 빠진 옛 원격 줄은 부모 runId 의 유일 카드일 때만 역조회한다.
+  const matches = Object.values(readTaskAgentState<{ tasks?: Record<string, TaskCard> }>(statePath).tasks ?? {})
+    .filter((candidate) => candidate.runId === card.runId);
+  let written = 0;
+  for (const [childRunId, entries] of Object.entries(snapshot.children)) {
+    for (const entry of entries ?? []) {
+      if (entry.event !== REMOTE_CARD_MOVE_PENDING) continue;
+      const data = entry.data;
+      const id = data.id;
+      const kind = data.kind;
+      const linked = data.card === cardId || (data.card == null && matches.length === 1 && matches[0]?.id === cardId);
+      const parentMatches = data.parentRunId == null || data.parentRunId === card.runId;
+      if (!linked || !parentMatches || typeof id !== 'string' || !/^[a-f0-9-]{36}$/i.test(id)
+        || !['review', 'propose-green', 'propose-land', 'decision-card'].includes(String(kind))) {
+        log('task-agent', 'card-binding-replay-skipped', { card: cardId, childRunId, pendingId: typeof id === 'string' ? id : null,
+          reason: !linked ? 'card mismatch or ambiguous runId' : !parentMatches ? 'parent run mismatch' : 'invalid pending move' });
+        continue;
+      }
+      const at = entry.timestamp ?? '';
+      if (!Number.isFinite(Date.parse(at))) continue;
+      const pr = Number.isSafeInteger(data.pr) && (data.pr as number) > 0 ? data.pr as number : undefined;
+      updateTaskCard(statePath, cardId, (current) => {
+        if (!current || current.runId !== card.runId || current.history.some((item) => item.sourceId === id)) return undefined;
+        const item = liveMoveHistoryEntry(current, { at, kind: kind as TaskAgentLiveMove, executorResult: 'shadow',
+          shadowDetail: typeof data.detail === 'string' ? data.detail : 'remote card binding pending', runId: childRunId,
+          ...(pr ? { pr } : {}) });
+        written++;
+        return { ...current, history: [...current.history, { ...item, sourceId: id }] };
+      });
+    }
+  }
+  if (written) log('task-agent', 'card-binding-replayed', { card: cardId, parentRunId: card.runId, written });
+  return written;
+}
+
 /**
  * 카드 history 에 live-move 한 줄 — 상태 파일은 카드를 읽은 곳과 같아야 한다: 주입한 경로(`live.statePath`) 또는
  * 기본 리더를 썼을 때의 기본 경로. 주입한 카드 리더(`readCard`)만 있고 경로가 없으면 그 카드의 원장을 모른다 — 적지 않는다.