elanous 0.2.22 → 0.2.24

package/src/task-agent/shadow.ts

@@ -16,7 +16,10 @@ import { readTaskAgentState, readTaskCard, taskAgentStatePath, type CompletionKi
 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 { configuredTaskAgentLiveMoves, executeLiveGreenProposal, executeLiveLand, executeLiveReview, type LiveMoveDeps, type LiveMoveResult, type TaskAgentLiveMove } from './live-moves.js';
+import { HARNESS_RUN_ID_ENV } from '../harness/harness-space.js';
+import { recordLiveMoveHistory } from './live-move-history.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';
 
 export interface TaskAgentShadowInput {
   runId: string | null;
@@ -25,7 +28,7 @@ export interface TaskAgentShadowInput {
   /** One judgement cycle can attempt at most one land, even across PRs. */
   cycleId?: string;
   /** Reviewed SHA is mandatory for land; a bare pass cannot authorize merging. */
-  selfReview?: { verdict: 'pass' | 'fail'; head: string };
+  selfReview?: { verdict: 'pass' | 'fail'; head: string; mustFixCount?: number };
 }
 
 export interface TaskAgentShadowMove {
@@ -55,6 +58,26 @@ export interface TaskAgentShadowDeps {
   liveMoves?: ReadonlySet<TaskAgentLiveMove>;
   /** live 수의 부작용(리뷰 띄우기·PR 머리 조회·상태 파일) — 시험은 주입한다. */
   live?: LiveMoveDeps;
+  /** 카드 조회 상태 파일(시험 주입 · 운영 파일을 건드리지 않게). 기본 = `live.statePath` ⊕ `taskAgentStatePath()`. */
+  statePath?: string;
+  /** Process env for the launched-run id (`ELANOUS_RUN_ID`) — test seam; default process.env. */
+  env?: NodeJS.ProcessEnv;
+}
+
+/** 카드 조회 상태 파일 — 조회 경로 전부가 같은 파일을 본다. */
+function cardStatePath(deps: TaskAgentShadowDeps): string {
+  return deps.statePath ?? deps.live?.statePath ?? taskAgentStatePath();
+}
+
+/** 카드 «원장»(기록·회수 대상) — 카드를 읽은 파일과 같다. 주입한 카드 리더(`readCard`)만 있으면 `live.statePath` 가 없을 때 모른다. */
+function cardLedgerPath(deps: TaskAgentShadowDeps): string | undefined {
+  return deps.readCard ? deps.live?.statePath : cardStatePath(deps);
+}
+
+/** live 수의 의존 — 실행부가 적는 원장(리뷰 요청·착지 시도)도 카드를 읽은 파일과 같게 맞춘다. */
+function liveMoveDeps(deps: TaskAgentShadowDeps): LiveMoveDeps {
+  const ledger = cardLedgerPath(deps);
+  return { ...(deps.log ? { log: deps.log } : {}), ...deps.live, ...(ledger ? { statePath: ledger } : {}) };
 }
 
 /** 파일 산출물로 전달(elanous-out)하는 종결 종류 — 그 밖의 code-pr 밖 종류는 확인 증거를 판단부에서 기다린다. */
@@ -149,23 +172,61 @@ function shadowCompletion(card: TaskCard | undefined, lookupFailed: boolean): Co
 }
 
 export async function recordTaskAgentShadowMove(input: TaskAgentShadowInput, deps: TaskAgentShadowDeps = {}): Promise<TaskAgentShadowMove> {
+  // TA-REVIEW-RESULT-CAPTURE — 판단 «전»에 지난 live review 의 결과 파일을 회수한다(카드 원장을 아는 때만 · 던지지 않는다).
+  //   대기 중인 요청이 없으면 아무것도 쓰지 않는다(결과 파일 없는 카드의 동작은 종전과 같다).
+  const reviewLedger = cardLedgerPath(deps);
+  if (reviewLedger) {
+    try { captureReviewResults(reviewLedger, { ...(deps.live?.now ? { now: deps.live.now } : {}), ...(deps.log ? { log: deps.log } : {}) }); } catch (error) {
+      // fail-soft — 판단은 계속하되 원인은 남긴다.
+      try { (deps.log ?? ((c, e, d) => debug.log(c, e, d, { level: 'warn' })))('task-agent', 'review-result-capture-failed', { statePath: reviewLedger, reason: (error instanceof Error ? error.message : String(error)).slice(-300) }); } catch { /* fail-soft */ }
+    }
+  }
   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;
+    card = successful ? (deps.readCard ? deps.readCard(successful.taskId) : readTaskCard(successful.taskId, cardStatePath(deps))) : undefined;
     if (!card && successful && !deps.readCard) {
-      const tasks = readTaskAgentState<{ tasks?: Record<string, TaskCard> }>(taskAgentStatePath()).tasks ?? {};
+      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);
   } 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);
-  if (input.selfReview) judgeInput.review = input.selfReview.verdict;
+  // 슈퍼바이저가 나른 리뷰가 없으면 그 PR 카드에 회수된 리뷰 결과(pass · 실제로 돈 리뷰 · 머리 sha)를 같은 입력 칸으로 쓴다.
+  let selfReview = input.selfReview;
+  let reviewFromCapture = false;
+  if (!selfReview && reviewLedger && typeof judgeInput.pr === 'number') {
+    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;
+      // 회수한 판정은 «리뷰한 머리»의 것이다 — 지금 PR 머리의 결과만 입력으로 쓴다(A 의 pass 로 B 를 land 쪽으로 보내지 않게 ·
+      //   여러 머리 결과가 역순으로 회수돼도 지금 머리 것을 고른다). 지금 머리 = 그 런 작업 트리에서 PR 머리 조회 ·
+      //   작업 트리가 없으면(Pod) 런이 낸 머리. 못 정하면 쓰지 않는다(종전처럼 review 수 → 새 머리면 새 리뷰).
+      if (prRun && hasCapturedPass(prCard, reviewedPr)) {
+        let currentHead: string | undefined;
+        if (prRun.worktreePath) {
+          const view = await (deps.live?.prHead ?? defaultPrHead)(reviewedPr, prRun.worktreePath).catch(() => null);
+          currentHead = view?.state === 'OPEN' ? view.head : undefined;
+        } else if (prRun.checkedHeadCommit && /^[0-9a-f]{40}$/i.test(prRun.checkedHeadCommit)) {
+          currentHead = prRun.checkedHeadCommit;
+        }
+        if (currentHead) selfReview = capturedSelfReview(prCard, reviewedPr, currentHead);
+      }
+      reviewFromCapture = selfReview !== undefined;
+    } catch (error) {
+      selfReview = undefined;
+      try { (deps.log ?? ((c, e, d) => debug.log(c, e, d, { level: 'warn' })))('task-agent', 'review-result-capture-failed', { pr: judgeInput.pr, reason: (error instanceof Error ? error.message : String(error)).slice(-300) }); } catch { /* fail-soft */ }
+    }
+  }
+  if (selfReview) judgeInput.review = selfReview.verdict;
   const delivery = successful?.worktreePath && card?.project?.target && isDeliveryKind(kind)
     ? { kind, worktreePath: successful.worktreePath, projectTarget: card.project.target, files: selectDeliveryCandidates(successful.worktreePath, kind) }
     : undefined;
@@ -224,10 +285,10 @@ export async function recordTaskAgentShadowMove(input: TaskAgentShadowInput, dep
   const boundCard = delivery
     ? card
     : prResult
-      ? (card && successful?.taskId === prResult.taskId ? card : liveCardFor([prResult], deps))
+      ? (card && successful?.taskId === prResult.taskId ? card : liveCardFor([prResult], deps, input.runId))
       : undefined;
   // PR 에 묶인 수는 그 PR 의 카드만 관측에 싣는다(못 찾으면 null — 다른 결과의 카드로 대체하지 않는다).
-  const liveCard = prResult || delivery ? boundCard : card ?? (cardLookupFailed ? undefined : liveCardFor(input.results, deps));
+  const liveCard = prResult || delivery ? boundCard : card ?? (cardLookupFailed ? undefined : liveCardFor(input.results, deps, input.runId));
   let liveMove: LiveMoveResult | undefined;
   if (live) {
     if (liveKind === 'review') {
@@ -241,42 +302,121 @@ export async function recordTaskAgentShadowMove(input: TaskAgentShadowInput, dep
             ...(prResult.branch ? { branch: prResult.branch } : {}),
             ...(prResult.prUrl ? { prUrl: prResult.prUrl } : {}),
           } } : {}),
-        }, { ...(deps.log ? { log: deps.log } : {}), ...deps.live });
+        }, liveMoveDeps(deps));
     } else if (liveKind === 'propose-land') {
       liveMove = await executeLiveLand(boundCard, prResult?.prNumber,
-        { runId: input.runId, cycleId: input.cycleId, review: input.selfReview,
+        { runId: input.runId, cycleId: input.cycleId, review: selfReview,
           ...(prResult?.worktreePath ? { cwd: prResult.worktreePath } : {}),
           ...(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 });
+        }, liveMoveDeps(deps));
     } 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 });
+      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-LIVE-MOVE-CARD-HISTORY — live-move 수(review·propose-green·propose-land)는 실행이든 그림자든 그 카드 history 에 한 줄.
+  // 결정·실행이 끝난 «뒤»에 덧붙이기만 한다(반환값·관측 무변경) · 실패는 관측만(live-move 를 막지 않는다).
+  if (liveKind !== null) 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;
 }
 
+/**
+ * 런 id 폴백 — 입력 runId(슈퍼바이저 · Pod 면 자식 런) → 상속 `ELANOUS_RUN_ID`(발사기가 넘긴 부모 런) 순으로,
+ * 카드 runId 와 정확히 같고 그 카드가 하나뿐일 때만 쓴다. 못 찾으면 추측하지 않고 이유 한 줄을 남긴다(조용한 미스 0).
+ */
+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;
+  const tasks = Object.values(readTaskAgentState<{ tasks?: Record<string, TaskCard> }>(cardStatePath(deps)).tasks ?? {});
+  const tried: Array<{ source: 'run' | 'env'; id: string; bound: number }> = [];
+  for (const [source, id] of [['run', own], ['env', inherited]] as const) {
+    if (!id || tried.some((entry) => entry.id === id)) continue;
+    const bound = tasks.filter((candidate) => candidate.runId === id);
+    if (bound.length === 1) return bound[0];
+    tried.push({ source, id, bound: bound.length });
+  }
+  const reason = tried.map((entry) => `${entry.source === 'env' ? `env ${HARNESS_RUN_ID_ENV}` : 'runId'} ${entry.id}: ${entry.bound === 0 ? 'no card has this runId' : `${entry.bound} cards share this runId (ambiguous)`}`).join(' · ');
+  try {
+    (deps.log ?? ((c: string, e: string, d: Record<string, unknown>) => debug.log(c, e, d)))('task-agent', 'run-card-fallback-missed', { runId: own ?? null, inheritedRunId: inherited ?? null, tried, reason });
+  } catch { /* fail-soft */ }
+  return undefined;
+}
+
+/**
+ * 카드 history 에 live-move 한 줄 — 상태 파일은 카드를 읽은 곳과 같아야 한다: 주입한 경로(`live.statePath`) 또는
+ * 기본 리더를 썼을 때의 기본 경로. 주입한 카드 리더(`readCard`)만 있고 경로가 없으면 그 카드의 원장을 모른다 — 적지 않는다.
+ */
+function recordLiveMoveOnCard(
+  move: { liveKind: TaskAgentLiveMove; live: boolean; liveMove: LiveMoveResult | undefined; card: TaskCard | undefined; runId: string | null; pr: number | undefined; shadowDetail: string },
+  deps: TaskAgentShadowDeps,
+): void {
+  const log = deps.log ?? ((c: string, e: string, d: Record<string, unknown>) => debug.log(c, e, d, { level: 'warn' }));
+  // 모든 기록 실패(경로 해석 · 시각 · 쓰기 · 카드 없음)는 이유 한 줄로 남기고, live-move 의 반환은 막지 않는다.
+  const fail = (reason: string) => {
+    try {
+      log('task-agent', 'live-move-history-failed', {
+        card: move.card?.id ?? null, kind: move.liveKind, executorResult: move.live ? 'live' : 'shadow', executed: move.liveMove?.executed ?? false, reason,
+      });
+    } catch { /* fail-soft — 관측 seam 자체가 던져도 live-move 는 계속 */ }
+  };
+  try {
+    if (!move.card) { fail('no task card bound to this move'); return; }
+    const statePath = cardLedgerPath(deps);
+    if (!statePath) { fail('card ledger unknown (injected readCard without live.statePath)'); return; }
+    const card = move.card;
+    // live 인데 실행부 결과가 없으면 «무엇이 일어났는지» 모른다 — 줄을 지어내지 않고 이유를 남긴다.
+    if (move.live && !move.liveMove) { fail('live move returned no executor result'); return; }
+    // recordLiveMoveHistory 는 쓰기 실패를 스스로 관측하고 던지지 않는다.
+    recordLiveMoveHistory(statePath, card.id, {
+      at: (deps.live?.now ?? (() => new Date()))().toISOString(),
+      kind: move.liveKind,
+      ...(move.live ? { executorResult: 'live' as const, result: move.liveMove! } : { executorResult: 'shadow' as const, shadowDetail: move.shadowDetail }),
+      runId: move.runId,
+      ...(move.pr !== undefined ? { pr: move.pr } : {}),
+      // 실행부가 받은 카드(수 «전» 읽음) — 이번 수가 새로 적은 기록만 머리로 읽는다.
+      before: { reviewRequests: card.reviewRequests, landAttempts: card.landAttempts },
+    }, deps.log ? (c, e, d) => deps.log!(c, e, d) : undefined);
+  } catch (error) {
+    fail(`record preparation failed: ${(error instanceof Error ? error.message : String(error)).slice(-250)}`);
+  }
+}
+
 /** live 수의 카드 — 성공한 결과가 없어도(수확 가능 런은 ok 가 아닐 수 있다) 결과의 taskId · 유일한 발사 문장으로 찾는다. */
-function liveCardFor(results: readonly SupervisorJobResult[], deps: TaskAgentShadowDeps): TaskCard | undefined {
+function liveCardFor(results: readonly SupervisorJobResult[], deps: TaskAgentShadowDeps, runId?: string | null): TaskCard | undefined {
   try {
     for (const result of results) {
-      const found = deps.readCard ? deps.readCard(result.taskId) : readTaskCard(result.taskId, deps.live?.statePath);
+      const found = deps.readCard ? deps.readCard(result.taskId) : readTaskCard(result.taskId, cardStatePath(deps));
       if (found) return found;
     }
     if (deps.readCard) return undefined;
-    const tasks = readTaskAgentState<{ tasks?: Record<string, TaskCard> }>(deps.live?.statePath ?? taskAgentStatePath()).tasks ?? {};
+    const tasks = readTaskAgentState<{ tasks?: Record<string, TaskCard> }>(cardStatePath(deps)).tasks ?? {};
+    // TA-LIVE-LAND-2 — a Pod run's results carry the orchestrator task id, not the card id, and its feature may be the
+    // authored goal rather than the handed sentence. `tasks hand --live` launched this process with ELANOUS_RUN_ID = the
+    // card's runId (TA-CARD-RUN-LINK); the supervisor's runId may be the Pod child's. Either id bound to exactly one card is the match.
+    const inherited = (deps.env ?? process.env)[HARNESS_RUN_ID_ENV]?.trim();
+    for (const id of new Set([runId?.trim(), inherited].filter((value): value is string => !!value))) {
+      const bound = Object.values(tasks).filter((candidate) => candidate.runId === id);
+      if (bound.length === 1) return bound[0];
+    }
     const features = new Set(results.map((result) => result.feature));
     const matches = Object.values(tasks).filter(candidate => candidate.status === 'launched' && features.has(candidate.text));
+    // runId ⊕ 상속 ELANOUS_RUN_ID 는 위에서 이미 봤다(판단부의 runCardFor 가 미스 이유를 남긴다).
     return matches.length === 1 ? matches[0] : undefined;
   } catch { return undefined; }
 }

package/src/task-agent/task-hand.ts

@@ -8,28 +8,106 @@
  * - 관측: `debug.log('task-agent', 'handed', {taskId, seat, checklistId, mode})`.
  */
 import { execFileSync } from 'node:child_process';
-import { randomBytes } from 'node:crypto';
-import { mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { createHash, randomBytes } from 'node:crypto';
+import { mkdirSync, readFileSync, statSync, writeFileSync, type Stats } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { resolveDaemonHarnessTarget } from '../intake-plane/harness-target.js';
 import { HARNESS_RUN_ID_ENV, mintRunId, normalizeRunId } from '../harness/harness-space.js';
 import { debug } from '../debug/log.js';
 import { effectiveInstanceRoot } from '../instance/resolve.js';
 import { withFileLockSync } from '../storage/file-lock.js';
+import { checkCompletionEvidence, deliverableReceiptEvidence } from './completion-evidence.js';
+import { judgeNextMove } from './judge.js';
+
+export interface ResolveHandTextDeps {
+  cwd: string;
+  stat: (path: string) => Pick<Stats, 'isFile' | 'isDirectory'>;
+  readFile: (path: string, encoding: 'utf8') => string;
+}
+
+export type ResolvedHandText =
+  | { kind: 'unchanged'; text: string }
+  | { kind: 'inlined'; text: string; path: string; chars: number; sha256: string }
+  | { kind: 'rejected'; path: string; reason: '없다' | '디렉터리' | '읽기 실패' | '비었다' };
+
+function missingOrReadFailure(error: unknown): '없다' | '읽기 실패' {
+  const code = (error as NodeJS.ErrnoException | undefined)?.code;
+  return code === 'ENOENT' || code === 'ENOTDIR' ? '없다' : '읽기 실패';
+}
+
+/** 파일 판정만 한다. 관측과 카드 작성은 호출자가 결과에 따라 수행한다. */
+export function resolveHandText(text: string, deps: ResolveHandTextDeps = { cwd: process.cwd(), stat: statSync, readFile: readFileSync }): ResolvedHandText {
+  if (!text || /\s/.test(text)) return { kind: 'unchanged', text };
+  const path = resolve(deps.cwd, text);
+  const extension = /\.(?:md|markdown|txt)$/i.test(text);
+  let file: Pick<Stats, 'isFile' | 'isDirectory'>;
+  try { file = deps.stat(path); } catch (error) {
+    if (!extension) return { kind: 'unchanged', text };
+    return { kind: 'rejected', path, reason: missingOrReadFailure(error) };
+  }
+  if (!file.isFile() && !extension && !file.isDirectory()) return { kind: 'unchanged', text };
+  if (!file.isFile()) return { kind: 'rejected', path, reason: file.isDirectory() ? '디렉터리' : '읽기 실패' };
+  let content: string;
+  // stat 과 read 사이에 지워지거나 경로가 바뀌어도 사유는 같은 규칙(없다/읽기 실패)으로 가른다.
+  try { content = deps.readFile(path, 'utf8'); } catch (error) { return { kind: 'rejected', path, reason: missingOrReadFailure(error) }; }
+  const carried = content.trim();
+  if (!carried) return { kind: 'rejected', path, reason: '비었다' };
+  return { kind: 'inlined', text: content, path, chars: carried.length, sha256: createHash('sha256').update(carried).digest('hex') };
+}
 
 export const TASK_SEATS = ['OP', 'TC', 'MK', 'UX'] as const;
 export type TaskSeat = typeof TASK_SEATS[number];
 /** 과제 카드 id 접두 — `task show <id>` 가 이 접두로 TOX 태스크와 갈린다. */
 export const TASK_CARD_PREFIX = 'ta-';
+/** Pod Job 의 metadata.labels 에 붙일 카드 식별자 — 원장의 카드 id 와 정확히 같아야 한다. */
+export const TASK_CARD_LABEL = 'elanous.task-card';
+/**
+ * TA-LIVE-LAND-2 — run-level marker set by `tasks hand --ta-land` on the launched `harness say`. The Pod surface
+ * (`self-implement-pod.ts`) reads it: with `taskAgent.liveMoves` ∋ `propose-land` the host re-gates without merging so
+ * the task agent's `executeLiveLand` → `pr land --expected-head` owns the land. Without propose-land it is ignored.
+ */
+export const TA_LAND_ENV = 'ELANOUS_TA_LAND';
+export interface TaskCardLabelContext {
+  cardId: string;
+  labels: Record<typeof TASK_CARD_LABEL, string>;
+}
+
+/** 카드 원장을 변경하지 않는 Pod 라벨 맥락. 정규화하면 다른 카드와 충돌할 수 있으므로 유효하지 않은 id 는 거부한다. */
+export function taskCardLabelContext(card: Pick<TaskCard, 'id'>): TaskCardLabelContext {
+  const id = card.id;
+  if (!id.startsWith(TASK_CARD_PREFIX) || id.length > 63 || !/^[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?$/.test(id)) {
+    throw new Error(`Pod 라벨에 쓸 수 없는 과제 카드 id: ${id}`);
+  }
+  return { cardId: id, labels: { [TASK_CARD_LABEL]: id } };
+}
+
 /**
  * 과제 종결 종류(RFC-loop-agent-map §A4b③) — 비면 code-pr(PR 병합)로 읽는다.
  * code-pr 밖의 종류는 «확인 증거»(`judge.ts` TaskJudgeInput.evidence)로 종결한다 — 증거를 만드는 일은 DEFAULT-HANDS 몫.
  */
-export const COMPLETION_KINDS = ['code-pr', 'artifact', 'research-report', 'ops-action', 'content', 'watch-brief', 'decision-support'] as const;
+export const COMPLETION_KINDS = ['code-pr', 'artifact', 'research-report', 'ops-action', 'content', 'watch-brief', 'decision-support', 'deliverable'] as const;
 export type CompletionKind = typeof COMPLETION_KINDS[number];
 
-/** `run-bound`·`goal-bound`·`pr-bound` 은 runId(⊕ pr)를 싣는다 — 옛 카드의 칸은 at·event·detail 뿐이다. */
-export interface TaskCardEvent { at: string; event: string; detail?: string; runId?: string; pr?: number }
+/**
+ * `run-bound`·`goal-bound`·`pr-bound` 은 runId(⊕ pr)를 싣는다 — 옛 카드의 칸은 at·event·detail 뿐이다.
+ * TA-LIVE-MOVE-CARD-HISTORY — `live-move` 줄만 kind·executed·ok·executorResult·head·effect 를 더 싣는다(`live-move-history.ts`).
+ */
+export interface TaskCardEvent {
+  at: string; event: string; detail?: string; runId?: string; pr?: number;
+  /** `closed-by-hand` 줄만 — 닫은 사유 · 닫은 자리(`closeTaskCard`). */
+  reason?: string; by?: string;
+  kind?: string; executed?: boolean; ok?: boolean; executorResult?: 'shadow' | 'live'; head?: string; effect?: string;
+  /** TA-REVIEW-RESULT-CAPTURE — review live-move 줄 · 결과 줄(`live-move-result`)의 결과 파일 경로. */
+  resultPath?: string;
+  /** TA-REVIEW-RESULT-CAPTURE — `live-move-result` 줄만: 회수한 `self review --json` 의 칸(못 읽은 칸은 null). */
+  verdict?: string | null; reviewed?: boolean | null; mustFix?: number | null; reviewRoute?: string | null;
+}
+/** 카드 history 의 live-move 줄 이벤트 이름 — 상태 사유(«마지막 칸») 판정에서 뺀다. */
+export const LIVE_MOVE_HISTORY_EVENT = 'live-move';
+/** TA-REVIEW-RESULT-CAPTURE — 떼어 띄운 리뷰의 결과(또는 «결과 없음») 줄 — live-move 줄처럼 상태 사유 판정에서 뺀다. */
+export const LIVE_MOVE_RESULT_EVENT = 'live-move-result';
+/** HAND-MOVE-LEDGER — 자리가 손으로 마무리한 수 줄(`recordHandMove`) — 관측 기록이라 live-move 줄처럼 상태 사유 판정에서 뺀다. */
+export const HAND_MOVE_HISTORY_EVENT = 'hand-move';
 export interface TaskCardMove { kind: 'launch' | 'wait'; command?: string[]; reason: string }
 export interface TaskCard {
   id: string;
@@ -82,9 +160,46 @@ export interface TaskCard {
   /** 미션 카드만 — 모든 조각 착지 → 칸 green «제안»(체크리스트는 손대지 않는다 · OP/주인이 뒤집는다). */
   greenProposal?: { at: string; checklistId: string | null; evidence: Record<string, string> };
   /** TA-JUDGE-LIVE-SAFE — live `review` 수가 리뷰를 요청한 PR 머리들(머리마다 한 번 · 띄우기 실패면 error · 이력은 지우지 않는다). */
-  reviewRequests?: Array<{ pr: number; head: string; at: string; error?: string }>;
-  /** Live land attempts, claimed before invocation, once per PR head even if the command fails. */
-  landAttempts?: Array<{ pr: number; head: string; at: string; ok?: boolean; detail?: string }>;
+  reviewRequests?: Array<{ pr: number; head: string; at: string; error?: string; /** TA-REVIEW-RESULT-CAPTURE — 자식 `--json` stdout 을 받는 파일. */ resultPath?: string }>;
+  /**
+   * TA-REJUDGE-ON-HEAD — 런 멈춤 «뒤» 머리마다 한 번 돌린 호스트 재게이트(병합 없음 · 떼어 띄움). 결과는 `resultPath` 파일에서
+   * 다음 틱이 회수해 passed·status·baseCommit·detail 을 채운다(비어 있으면 아직 도는 중 · 없는 칸을 «통과»로 읽지 않는다).
+   */
+  regates?: Array<{ pr: number; head: string; at: string; resultPath?: string; passed?: boolean; status?: string; baseCommit?: string; detail?: string;
+    /** REJUDGE base-stale — 같은 머리를 새 base 위에서 다시 잰 재게이트면, land 가 낡았다고 거절한 앞 재게이트의 base(멱등 키 = 머리 ⊕ 이 base). */
+    staleBase?: string }>;
+  /**
+   * Live land attempts, claimed before invocation, once per PR head even if the command fails.
+   * TA-LAND-RETRY-ON-INFRA — a failed attempt carries `class`/`reason`: `infra` (TA-side, allow-listed) leaves one more attempt on
+   * the same head (`LAND_ATTEMPTS_PER_HEAD_ON_INFRA`); `judgement` · unknown reason · no class (older record) closes the head.
+   * REJUDGE base-stale — `base-stale` (overlap evidence gate base went stale with PR-file overlap) waits for a re-gate on a new base;
+   * only after that re-gate passes is the attempt consumed (`openLandAttempts`) and the same head may land once more.
+   */
+  landAttempts?: Array<{ pr: number; head: string; at: string; ok?: boolean; detail?: string; class?: 'infra' | 'judgement' | 'base-stale'; reason?: string }>;
+  /** TA-LIVE-LAND-2 — `tasks hand --ta-land`: this card's run leaves the merge to the task agent (propose-land). */
+  taLand?: true;
+  /** TASKS-HAND-CHILD-LLM — `tasks hand --child-llm <provider>/<model> [--child-llm-effort <level>]` → 발사 인자 `--child-llm-provider/-model/-effort`. */
+  childLlm?: TaskChildLlm;
+}
+
+/** 구현 자식 LLM 선택 — 하니스 `--child-llm-provider/--child-llm-model/--child-llm-effort` 로 그대로 넘긴다(검증 권위는 하니스). */
+export interface TaskChildLlm { provider: string; model: string; effort?: string }
+
+/**
+ * `<provider>/<model>` 을 «첫» `/` 에서만 가른다(모델 id 가 `/` 를 담을 수 있다).
+ * openrouter 는 하니스의 모델 id 가 `openrouter/` 접두를 포함하므로(`openrouter/z-ai/glm-5.3`) 전체 문자열을 모델로 둔다
+ * (`openrouter/openrouter/…` 처럼 접두를 이미 단 입력은 두 번 붙이지 않는다).
+ */
+export function parseChildLlm(value: string, effort?: string): TaskChildLlm {
+  // 원 값 그대로 본다 — 앞뒤 공백·개행도 «잘못된 값»이다(조용히 다듬지 않는다).
+  const slash = value.indexOf('/');
+  const provider = slash < 0 ? '' : value.slice(0, slash);
+  const rest = slash < 0 ? '' : value.slice(slash + 1);
+  if (!provider || !rest || /[\s\p{Cc}]/u.test(value)) throw new Error(`--child-llm 은 <provider>/<model> 이다(예: grok/grok-4.7): ${JSON.stringify(value)}`);
+  const model = provider === 'openrouter' && !rest.startsWith('openrouter/') ? `openrouter/${rest}` : rest;
+  if (effort === undefined) return { provider, model };
+  if (!effort || /[\s\p{Cc}]/u.test(effort)) throw new Error(`--child-llm-effort 가 비었거나 공백·제어 문자를 담았다: ${JSON.stringify(effort)}`);
+  return { provider, model, effort };
 }
 
 /** 런 원장에서 묶은 PR — url 은 원장(pr-opened · Pod job-finished)에 있을 때만(지어내지 않는다). */
@@ -95,6 +210,14 @@ export function cardPrNumber(card: Pick<TaskCard, 'pr'>): number | undefined {
   return typeof card.pr === 'number' ? card.pr : card.pr?.number;
 }
 
+/** A uniquely launched code-PR card may own a draft through its PR or its opening run. */
+export function draftTaskOwner(cards: readonly TaskCard[], draft: { number: number; runId?: string | null }): TaskCard | undefined {
+  const owners = cards.filter((card) => card.status === 'launched' && (card.completion ?? 'code-pr') === 'code-pr'
+    && card.seat && (card.runId || card.runChildId) && (cardPrNumber(card) === draft.number
+      || (draft.runId && (card.runId === draft.runId || card.runChildId === draft.runId))));
+  return owners.length === 1 ? owners[0] : undefined;
+}
+
 interface TaskAgentStateFile { tasks?: Record<string, TaskCard>; [key: string]: unknown }
 
 function isGitWorkTree(path: string): boolean {
@@ -170,9 +293,22 @@ export function readTaskCard(id: string, path = taskAgentStatePath()): TaskCard
   return readState(path).tasks?.[id];
 }
 
+export const CLOSED_BY_HAND_EVENT = 'closed-by-hand';
+
+/** 카드를 손으로 닫는다 — 상태를 `failed` 로 두고 history 에 한 줄(`closed-by-hand`)을 남긴다. 이미 손으로 닫은 카드는 그대로 돌려준다(멱등). */
+export function closeTaskCard(card: TaskCard, input: { reason: string; by: string; at: string }): TaskCard {
+  const reason = input.reason.trim();
+  if (!reason) throw new Error('닫는 사유(reason)가 비어 있다');
+  if (card.status === 'failed' && card.history.some((item) => item.event === CLOSED_BY_HAND_EVENT)) return card;
+  return { ...card, status: 'failed', history: [...card.history, { at: input.at, event: CLOSED_BY_HAND_EVENT, kind: CLOSED_BY_HAND_EVENT, detail: reason, reason, by: input.by }] };
+}
+
 /** 첫 수의 elanous 인자(진입점·--config-dir 앞붙임은 launcher 몫). */
-export function launchArgs(card: Pick<TaskCard, 'text' | 'seat'>): string[] {
-  return ['harness', 'say', ...(card.seat ? ['--seat', card.seat] : []), '--substrate', 'pod', '--merge-by-host', card.text];
+export function launchArgs(card: Pick<TaskCard, 'text' | 'seat' | 'childLlm'>): string[] {
+  const child = card.childLlm
+    ? ['--child-llm-provider', card.childLlm.provider, '--child-llm-model', card.childLlm.model, ...(card.childLlm.effort ? ['--child-llm-effort', card.childLlm.effort] : [])]
+    : [];
+  return ['harness', 'say', ...(card.seat ? ['--seat', card.seat] : []), '--substrate', 'pod', '--merge-by-host', ...child, card.text];
 }
 
 /**
@@ -186,7 +322,8 @@ export function nextMoveFor(card: TaskCard, landed?: ReadonlySet<string>): TaskC
   if (card.status !== 'launched' && unmet.length > 0) return { kind: 'wait', reason: `after ${unmet.join(', ')}${landed ? '' : ' · 착지 미확인'}` };
   if (card.status === 'handed') return { kind: 'launch', command: launchArgs(card), reason: '넘겨받은 과제 — 첫 발사' };
   if (card.status === 'launch-failed') return { kind: 'launch', command: launchArgs(card), reason: '직전 발사 실패 — 다시 발사' };
-  if (card.status === 'failed') return { kind: 'wait', reason: card.history.at(-1)?.detail ?? '런 실패 — PR·수확 가지 없음' };
+  // live-move·hand-move 줄(관측 기록)은 실패 사유가 아니다 — 그 줄을 뺀 마지막 칸이 사유다(live-move 줄 없는 카드는 종전과 같다).
+  if (card.status === 'failed') return { kind: 'wait', reason: card.history.filter((item) => item.event !== LIVE_MOVE_HISTORY_EVENT && item.event !== LIVE_MOVE_RESULT_EVENT && item.event !== HAND_MOVE_HISTORY_EVENT).at(-1)?.detail ?? '런 실패 — PR·수확 가지 없음' };
   return { kind: 'wait', reason: '발사됨 — 런 멈춤을 슈퍼바이저 그림자 판단(task-agent.shadow-move)이 받는다' };
 }
 
@@ -195,7 +332,7 @@ export function shellQuote(arg: string): string {
 }
 
 /** 발사기에 넘기는 연결 — env(`ELANOUS_RUN_ID`)를 자식 환경에 얹으면 하니스 런이 `runId` 로 돈다(`resolveRunIdentity` 상속). launchId 는 카드에만 남는 발사 토큰이다. */
-export interface TaskLaunchContext { runId: string; launchId: string; env: Record<string, string> }
+export interface TaskLaunchContext { runId: string; launchId: string; env: Record<string, string>; cardLabelContext?: TaskCardLabelContext }
 /** 발사기가 «이 런 id 로 띄웠다»고 돌려주는 영수증 — 없으면 카드에 런 id 를 적지 않는다(추측하지 않는다). */
 export interface TaskLaunchReceipt {
   runId?: string;
@@ -215,6 +352,11 @@ export interface HandTaskOptions {
   goal?: string;
   milestone?: string;
   live?: boolean;
+  /** TA-LIVE-LAND-2 — `--ta-land`: card field `taLand` ⊕ launch env `ELANOUS_TA_LAND=1`. */
+  taLand?: boolean;
+  /** TASKS-HAND-CHILD-LLM — `<provider>/<model>`(`parseChildLlm`) ⊕ 선택 추론 노력. effort 만 주면 거부. */
+  childLlm?: string;
+  childLlmEffort?: string;
   statePath?: string;
   /** `--live` 일 때만 불린다. */
   launcher?: TaskLauncher;
@@ -252,6 +394,29 @@ export class TaskLaunchError extends Error {
 
 export interface HandTaskResult { card: TaskCard; move: TaskCardMove; mode: 'shadow' | 'live'; launched: boolean; cwd?: string }
 
+/** Dispatch evidence for a handed deliverable card; unlike handTask, this never launches work. */
+export function dispatchDeliverableCompletion(id: string, input: { ref: string; receipt?: boolean }, path: string, now: () => Date = () => new Date()): boolean {
+  const card = readTaskCard(id, path);
+  if (card?.completion !== 'deliverable' || !card.project?.target || card.pr !== undefined || card.status === 'failed' || card.status === 'launch-failed') return false;
+  const evidence = checkCompletionEvidence('deliverable', { dir: card.project.target, ...input });
+  if (judgeNextMove({ completion: card.completion, evidence }).move !== 'propose-green') {
+    try { debug.log('task-agent', 'deliverable-rejected', { taskId: id, ref: input.ref, missing: evidence.missing }); } catch { /* fail-soft */ }
+    return false;
+  }
+  const receiptEvidence = deliverableReceiptEvidence(evidence.ref);
+  const at = now().toISOString();
+  let closed = false;
+  updateTaskCard(path, id, (current) => {
+    if (current?.completion !== 'deliverable' || current.pr !== undefined || current.greenProposal || !current.project || current.project.target !== card.project?.target || current.status === 'failed' || current.status === 'launch-failed') return undefined;
+    const fresh = checkCompletionEvidence('deliverable', { dir: current.project.target, ...input });
+    if (judgeNextMove({ completion: current.completion, evidence: fresh }).move !== 'propose-green') return undefined;
+    closed = true;
+    return { ...current, greenProposal: { at, checklistId: current.checklistId ?? null, evidence: { [id]: receiptEvidence } } };
+  });
+  try { debug.log('task-agent', closed ? 'deliverable-closed' : 'deliverable-rejected', { taskId: id, ref: evidence.ref, ...(closed ? {} : { missing: ['already-proposed-or-changed'] }) }); } catch { /* fail-soft */ }
+  return closed;
+}
+
 export async function handTask(opts: HandTaskOptions): Promise<HandTaskResult> {
   const text = opts.text.trim();
   if (!text) throw new Error('과제 한 줄이 비어 있다');
@@ -260,6 +425,8 @@ export async function handTask(opts: HandTaskOptions): Promise<HandTaskResult> {
   for (const [flag, value] of [['--goal', opts.goal], ['--milestone', opts.milestone]] as const) {
     if (value !== undefined && (!value.trim() || /\p{Cc}/u.test(value))) throw new Error(`${flag} id 가 비었거나 제어 문자를 담았다: ${JSON.stringify(value)}`);
   }
+  if (opts.childLlmEffort !== undefined && opts.childLlm === undefined) throw new Error('--child-llm-effort 는 --child-llm <provider>/<model> 과 함께 준다');
+  const childLlm = opts.childLlm !== undefined ? parseChildLlm(opts.childLlm, opts.childLlmEffort) : undefined;
   let project: TaskCard['project'];
   let targetIsGit: boolean | null = null;
   if (opts.project) {
@@ -287,6 +454,8 @@ export async function handTask(opts: HandTaskOptions): Promise<HandTaskResult> {
     ...(project ? { project } : {}),
     ...(opts.goal ? { goal: opts.goal } : {}),
     ...(opts.milestone ? { milestone: opts.milestone } : {}),
+    ...(opts.taLand === true ? { taLand: true as const } : {}),
+    ...(childLlm ? { childLlm } : {}),
     createdAt: now.toISOString(),
     status: 'handed',
     history: [],
@@ -310,12 +479,15 @@ export async function handTask(opts: HandTaskOptions): Promise<HandTaskResult> {
     if (!owned.ok) throw new TaskCardSupersededError(next.id);
   };
   writeCard(path, card);
-  try { debug.log('task-agent', 'handed', { taskId: id, seat: card.seat ?? null, checklistId: card.checklistId ?? null, mode, projectId: project?.id ?? null, targetIsGit }); } catch { /* fail-soft */ }
+  try { debug.log('task-agent', 'handed', { taskId: id, seat: card.seat ?? null, checklistId: card.checklistId ?? null, mode, projectId: project?.id ?? null, targetIsGit, taLand: card.taLand === true }); } catch { /* fail-soft */ }
+  if (childLlm) {
+    try { debug.log('task-agent', 'child-llm', { taskId: id, input: opts.childLlm, provider: childLlm.provider, model: childLlm.model, effort: childLlm.effort ?? null, mode }); } catch { /* fail-soft */ }
+  }
   if (mode === 'shadow') return { card, move, mode, launched: false, ...(project ? { cwd: project.target } : {}) };
   if (!opts.launcher) throw new Error('--live 인데 launcher 가 없다');
   const runId = mintRunId();
   const launchId = `tl-${randomBytes(6).toString('hex')}`;
-  const context: TaskLaunchContext = { runId, launchId, env: { [HARNESS_RUN_ID_ENV]: runId } };
+  const context: TaskLaunchContext = { runId, launchId, env: { [HARNESS_RUN_ID_ENV]: runId, ELANOUS_TASK_CARD_ID: card.id, ...(card.taLand ? { [TA_LAND_ENV]: '1' } : {}) }, cardLabelContext: taskCardLabelContext(card) };
   let receipt: void | TaskLaunchReceipt;
   try {
     receipt = await opts.launcher(move.command!, project?.target, context);