elanous 0.2.23 → 0.2.24

package/src/task-agent/actions.ts

@@ -1,7 +1,7 @@
 import { copyFileSync, lstatSync, mkdirSync, realpathSync } from 'node:fs';
 import { join, relative, resolve, sep } from 'node:path';
 import { debug } from '../debug/log.js';
-import { judgeNextMove } from './judge.js';
+import { judgeNextMove, retryMoveOf, SAME_MOVE_FAILURE_LIMIT } from './judge.js';
 import { checkCompletionEvidence } from './completion-evidence.js';
 
 export type DeliveryKind = 'research-report' | 'artifact' | 'content';
@@ -65,6 +65,48 @@ export interface ActionDeps {
   /** 실패 한 번을 잠금 안에서 디스크에 더한다(다른 프로세스의 실패를 덮지 않게) · 더한 뒤의 값을 돌려준다. */
   incrementFailure?(key: string): number;
   observe(event: 'task-agent.action', data: { taskId: string; kind: NextActionKind; result: string; reason: string }): void;
+  /** 사다리 R4 — 실제로 할 재발사 수의 허용 목록(`taskAgent.liveMoves` 어휘). 없으면 종전 그대로(재발사에 목록 검사 없음) · 목록에 없는 수는 shadow. */
+  liveMoves?: ReadonlySet<string>;
+  /** 한 판단 회차의 발사 칸 — 호출부가 회차마다 새로 준다. 없으면 회당 상한 없음(종전). 발사를 시도할 때마다 `count` 가 오른다. */
+  retryLaunches?: { count: number };
+  /** mbp 부하 관문(OP 신호 `loadMax`) — 지금 1분 부하가 `loadMax` 이상이거나 못 읽으면 발사하지 않고 shadow. 없으면 관문 없음(종전). */
+  loadGate?: { loadMax: number; load1(): number | null };
+}
+
+/** 재발사는 한 판단 회차에 한 건만 발사한다. */
+export const RETRY_LAUNCHES_PER_CYCLE = 1;
+
+/** live 인데도 shadow 로 내릴 사유 — 없으면 발사해도 된다(재발사 아닌 수는 늘 없다). 기다림(wait)은 발사가 아니라 부하·회당 상한을 보지 않는다. */
+function retryShadowReason(action: NextAction, deps: ActionDeps): string | undefined {
+  if (action.kind !== 'retry') return undefined;
+  const move = retryMoveOf(action.variant);
+  if (deps.liveMoves && !deps.liveMoves.has(move)) return `${move} not in live allow-list`;
+  if (action.variant === 'wait') return undefined;
+  if (deps.loadGate) {
+    const load = deps.loadGate.load1();
+    if (load === null || !Number.isFinite(load)) return `load gate: load unreadable (loadMax ${deps.loadGate.loadMax})`;
+    if (load >= deps.loadGate.loadMax) return `load gate: load ${load} >= loadMax ${deps.loadGate.loadMax}`;
+  }
+  if (deps.retryLaunches && deps.retryLaunches.count >= RETRY_LAUNCHES_PER_CYCLE) return `one relaunch per cycle already used (${move})`;
+  return undefined;
+}
+
+/** 결정 카드가 «근거»로 쓰는 세 칸 — 막힌 과제의 서명 · 막힌 화면 · 리뷰 must-fix. */
+export interface DecisionCardEvidence { signature?: string; screen?: string; mustFix?: readonly string[] }
+
+/** 비지 않은 근거 칸 이름들 — 비어 있으면 카드를 올리지 않는다(근거 없는 카드 0). */
+export function decisionCardGrounds(evidence: DecisionCardEvidence | undefined): Array<'signature' | 'screen' | 'must-fix'> {
+  const grounds: Array<'signature' | 'screen' | 'must-fix'> = [];
+  if (evidence?.signature?.trim()) grounds.push('signature');
+  if (evidence?.screen?.trim()) grounds.push('screen');
+  if (evidence?.mustFix?.some(fix => typeof fix === 'string' && fix.trim())) grounds.push('must-fix');
+  return grounds;
+}
+
+/** `decisions raise` 인자 — 종전 실행부(`executeNextAction`)와 live 수(`executeLiveDecisionCard`)가 같은 카드 모양을 쓴다. */
+export function decisionRaiseArgs(input: { taskId: string; reason: string; risk?: NextAction['risk']; evidence: string }): string[] {
+  const category = input.risk === 'money' ? 'money' : input.risk === 'security' ? 'security' : input.risk === 'irreversible-publication' ? 'publish' : 'other';
+  return ['decisions', 'raise', '--title', `${input.taskId}: ${input.reason}`, '--category', category, '--s', `Task ${input.taskId} needs a decision.`, '--c', input.reason, '--ref', input.evidence, '--q', 'Which action should be taken?', '--option', 'h=Keep on hold:no automatic execution', '--option', 'p=Approve action:execute after approval', '--skip-recommend', 'requires human decision', '--no-xcheck', 'automated escalation'];
 }
 
 /** 실패 셈 키. 갈래가 있으면 갈래별로 센다(G2 — «다른 수»의 실패가 같은 칸에 쌓이지 않게). 없으면 종전 키 그대로. */
@@ -72,6 +114,19 @@ export function failureKey(action: Pick<NextAction, 'taskId' | 'kind' | 'variant
   return JSON.stringify(action.variant ? [action.taskId, action.kind, action.variant] : [action.taskId, action.kind]);
 }
 
+/**
+ * 같은 «수»의 실패 수 — 상한 판정용. 셈 키(`failureKey`)는 종전 그대로 두되, 갈래 없는 재발사와 `narrow` 갈래는
+ * 같은 수(`narrow-relaunch` · `retryMoveOf`)라 두 키를 합쳐 본다(TA-LIVE-RETRY: 같은 과제·같은 수 3회 반복 0).
+ */
+export function sameMoveFailures(action: Pick<NextAction, 'taskId' | 'kind' | 'variant'>, deps: Pick<ActionDeps, 'failureCounts' | 'failures'>): number {
+  if (!deps.failureCounts) return deps.failures ?? 0;
+  if (action.kind !== 'retry' || retryMoveOf(action.variant) !== 'narrow-relaunch') return deps.failureCounts[failureKey(action)] ?? deps.failures ?? 0;
+  const bare = deps.failureCounts[failureKey({ taskId: action.taskId, kind: 'retry' })];
+  const narrow = deps.failureCounts[failureKey({ taskId: action.taskId, kind: 'retry', variant: 'narrow' })];
+  if (bare === undefined && narrow === undefined) return deps.failures ?? 0;
+  return (bare ?? 0) + (narrow ?? 0);
+}
+
 const RETRY_HINT: Record<Exclude<RetryVariant, 'wait'>, (action: NextAction) => string> = {
   narrow: action => `Narrow relaunch: previous run ${action.runId} made no progress. Halve the scope; keep the same acceptance line.`,
   salvage: action => `Salvage relaunch: continue from the salvage branch ${action.salvageBranch ?? `of run ${action.runId}`} — take its diff, do not restart from scratch.`,
@@ -89,18 +144,19 @@ export async function executeNextAction(action: NextAction, deps: ActionDeps): P
     deps.observe('task-agent.action', { taskId: action.taskId, kind: action.kind, result, reason });
     return result;
   };
-  if (deps.mode !== 'live') {
+  const shadowReason = deps.mode === 'live' ? retryShadowReason(action, deps) : undefined;
+  if (deps.mode !== 'live' || shadowReason) {
     const destination = action.delivery && action.kind === 'deliver'
       ? ` → ${join(action.delivery.projectTarget, 'elanous-out', action.taskId)}/${action.delivery.files.join(', ')}` : '';
-    return record('shadow', `would ${action.kind}${action.variant ? `:${action.variant}` : ''}: ${action.rationale}${destination}`);
+    return record('shadow', `would ${action.kind}${action.variant ? `:${action.variant}` : ''}: ${action.rationale}${destination}${shadowReason ? ` · shadow: ${shadowReason}` : ''}`);
   }
   const card = async (reason: string) => {
     const evidence = JSON.stringify({ runId: action.runId, pr: action.pr, mustFix: action.mustFix ?? [], history: action.history ?? [], selected: action.kind, reason });
-    const result = await deps.command(['decisions', 'raise', '--title', `${action.taskId}: ${reason}`, '--category', action.risk === 'money' ? 'money' : action.risk === 'security' ? 'security' : action.risk === 'irreversible-publication' ? 'publish' : 'other', '--s', `Task ${action.taskId} needs a decision.`, '--c', reason, '--ref', evidence, '--q', 'Which action should be taken?', '--option', 'h=Keep on hold:no automatic execution', '--option', 'p=Approve action:execute after approval', '--skip-recommend', 'requires human decision', '--no-xcheck', 'automated escalation']);
+    const result = await deps.command(decisionRaiseArgs({ taskId: action.taskId, reason, ...(action.risk ? { risk: action.risk } : {}), evidence }));
     return record(result.status === 0 ? 'decision' : 'failed', reason);
   };
   if (action.risk) return card(`risk: ${action.risk}`);
-  if ((deps.failureCounts?.[failureKey(action)] ?? deps.failures ?? 0) >= 2) return card('same task/action failed twice');
+  if (sameMoveFailures(action, deps) >= SAME_MOVE_FAILURE_LIMIT) return card('same task/action failed twice');
   if (action.kind === 'land') {
     if (!action.cwd) return card('landing worktree unknown');
     const view = await deps.command(['gh', 'pr', 'view', String(action.pr), '--json', 'labels']);
@@ -175,6 +231,7 @@ export async function executeNextAction(action: NextAction, deps: ActionDeps): P
   // 여기 닿는 종류는 land · retry 둘뿐이다(green·decision·review 는 위에서 끝난다).
   const args = action.kind === 'land' ? ['pr', 'land', '--cwd', action.cwd!] : ['harness', 'say', retryText(action)];
   const day = deps.landingDay ?? new Date().toLocaleDateString('en-CA', { timeZone: 'Asia/Seoul' });
+  if (action.kind === 'retry' && deps.retryLaunches) deps.retryLaunches.count++;
   const outcome = await deps.command(args);
   if (outcome.status !== 0) {
     if (action.kind === 'land') deps.releaseLanding?.(day);

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

@@ -5,6 +5,11 @@ import type { DecisionLedger } from '../decisions/decision-ledger.js';
 import { getLastStatus } from '../domains/schedule-registry.js';
 
 export type CompletionEvidenceKind = 'research-report' | 'artifact' | 'content' | 'ops-action' | 'watch-brief' | 'decision-support' | 'deliverable';
+/** Card evidence stays a string in the existing ledger; retain both the checked output reference and the confirmed receipt. */
+export function deliverableReceiptEvidence(ref: string): string {
+  return JSON.stringify({ ref, receipt: true });
+}
+
 export interface CompletionEvidenceDeps {
   ledger?: Pick<DecisionLedger, 'list'>;
   schedulesDb?: Database;

package/src/task-agent/cover.ts

@@ -1,3 +1,4 @@
+import { debug } from '../debug/log.js';
 import type { NextActionKind } from './actions.js';
 
 type CoverVerb = 'land' | 'review' | 'retry' | 'green';
@@ -21,16 +22,91 @@ export interface CoverRow {
 
 /** null means the source could not be read; [] means it was read and had no matching events. */
 export interface TaskAgentCoverInput {
-  taskAgentActions: readonly { kind: NextActionKind; result: string }[] | null;
+  taskAgentActions: readonly { kind: NextActionKind; result: string; reason?: string; taskId?: string }[] | null;
   allLands: readonly { step: string; ok: boolean }[] | null;
+  /** Card-ledger denominator for review·retry·green. undefined = not requested; null = ledger unreadable; [] = no cards. */
+  taskCards?: readonly { id: string }[] | null;
+  /** Daily launch and PR counts come from their independent event sources; null means unreadable. */
+  launched?: number | null;
+  cardPrs?: number | null;
+  /** null means the pending-landing age source could not be read; [] means no pending landings. */
+  pendingLandingAgeSeconds?: readonly number[] | null;
   /** A source reached the query safety limit; its aggregate is not known to be complete. */
   truncated?: { taskAgentActions: boolean; allLands: boolean };
 }
 
-/** Only land has an independent denominator. The other three verbs have no hand-work source yet. */
+export type LandingFailureReason = 'load' | 'oom' | 'time-limit' | 'conflict' | 'review' | 'other';
+export interface LandingThroughput {
+  launched: number | null;
+  cardPrs: number | null;
+  taskAgentLandings: number | null;
+  launchToPrRatio: number | null;
+  prToLandingRatio: number | null;
+  failureReasons: Record<LandingFailureReason, number> | null;
+  pendingLandings: number | null;
+  oldestPendingAgeSeconds: number | null;
+}
+
+const FAILURE_REASONS: readonly LandingFailureReason[] = ['load', 'oom', 'time-limit', 'conflict', 'review', 'other'];
+
+function landingFailureReason(action: { kind: NextActionKind; reason?: string }): LandingFailureReason {
+  const reason = action.reason ?? '';
+  if (/\boom\b|out[- ]of[- ]memory|oomkilled|메모리.{0,12}(초과|부족|킬)/i.test(reason)) return 'oom';
+  if (/timeout|timed out|time[- ]limit|deadline|시간.{0,12}(초과|한도)/i.test(reason)) return 'time-limit';
+  if (/conflict|merge conflict|충돌/i.test(reason)) return 'conflict';
+  if (action.kind === 'review' || /review|리뷰/i.test(reason)) return 'review';
+  if (/load|resource.{0,12}(pressure|exhaust|limit)|cpu.{0,8}load|부하|포화/i.test(reason)) return 'load';
+  return 'other';
+}
+
+/** Daily funnel, failure-reason distribution, and oldest pending-landing age. */
+export function measureLandingThroughput(input: TaskAgentCoverInput): LandingThroughput {
+  const actionsReadable = input.taskAgentActions !== null && input.truncated?.taskAgentActions !== true;
+  const taskAgentLandings = actionsReadable
+    ? input.taskAgentActions!.filter((action) => action.kind === 'land' && action.result === 'done').length
+    : null;
+  const failureReasons = actionsReadable
+    ? Object.fromEntries(FAILURE_REASONS.map((reason) => [reason, 0])) as Record<LandingFailureReason, number>
+    : null;
+  if (failureReasons && input.taskAgentActions) {
+    for (const action of input.taskAgentActions) {
+      if (action.result !== 'failed') continue;
+      const reason = landingFailureReason(action);
+      failureReasons[reason]++;
+    }
+  }
+  const launched = input.launched ?? null;
+  const cardPrs = input.cardPrs ?? null;
+  const pendingAges = input.pendingLandingAgeSeconds ?? null;
+  const launchToPrRatio = launched !== null && launched > 0 && cardPrs !== null ? cardPrs / launched : null;
+  const prToLandingRatio = cardPrs !== null && cardPrs > 0 && taskAgentLandings !== null ? taskAgentLandings / cardPrs : null;
+  return {
+    launched, cardPrs, taskAgentLandings, launchToPrRatio, prToLandingRatio, failureReasons,
+    pendingLandings: pendingAges === null ? null : pendingAges.length,
+    oldestPendingAgeSeconds: pendingAges === null || pendingAges.length === 0 ? null : Math.max(...pendingAges),
+  };
+}
+
+/** Unknown values stay unknown; empty pending queues are reported distinctly from unreadable ages. */
+export function formatLandingThroughput(row: LandingThroughput, period = '1d'): string {
+  const count = (value: number | null): string => value === null ? '-' : String(value);
+  const ratio = (value: number | null): string => value === null ? '-' : `${(value * 100).toFixed(1)}%`;
+  const failures = row.failureReasons === null ? '못 잼' :
+    `부하 ${row.failureReasons.load} · OOM ${row.failureReasons.oom} · 시간 한도 ${row.failureReasons['time-limit']} · 충돌 ${row.failureReasons.conflict} · 리뷰 ${row.failureReasons.review} · 기타 ${row.failureReasons.other}`;
+  const pendingAge = row.pendingLandings === null ? '못 잼'
+    : row.pendingLandings === 0 ? '없음'
+      : row.oldestPendingAgeSeconds === null ? '못 잼'
+        : row.oldestPendingAgeSeconds < 3600
+          ? `${Math.floor(row.oldestPendingAgeSeconds / 60)}분`
+          : `${(row.oldestPendingAgeSeconds / 3600).toFixed(1)}h`;
+  return `처리량(${period}) 발사 ${count(row.launched)} → 카드 PR ${count(row.cardPrs)} → TA 착지 ${count(row.taskAgentLandings)} (발사→PR ${ratio(row.launchToPrRatio)} · PR→착지 ${ratio(row.prToLandingRatio)}) · 착지 실패 ${failures} · 착지 대기 ${count(row.pendingLandings)}건, 최장 ${pendingAge}`;
+}
+
+/** Land uses the merge-step denominator; review·retry·green use the card ledger only when `taskCards` is given. */
 export function measureTaskAgentCover(input: TaskAgentCoverInput): CoverRow[] {
   const verbs: CoverVerb[] = ['land', 'review', 'retry', 'green'];
-  return verbs.map((verb) => {
+  const cardIds = input.taskCards ? new Set(input.taskCards.map((card) => card.id)) : null;
+  const rows = verbs.map((verb): CoverRow => {
     const actions = input.taskAgentActions?.filter((action) => action.kind === verb);
     const actionsUnreadable = actions === undefined || input.truncated?.taskAgentActions === true;
     const byTaskAgent = actionsUnreadable ? null : actions.filter((action) => action.result === 'done').length;
@@ -38,6 +114,19 @@ export function measureTaskAgentCover(input: TaskAgentCoverInput): CoverRow[] {
     const liveActions = actionsUnreadable ? null : actions.filter((action) => action.result !== 'shadow').length;
     const shadowActions = actionsUnreadable ? null : actions.filter((action) => action.result === 'shadow').length;
     const counts = { liveActions, shadowActions };
+    if (verb !== 'land' && input.taskCards !== undefined) {
+      if (actionsUnreadable || cardIds === null) return {
+        verb, byTaskAgent: null, total: null, observedActions, ratio: null, state: 'unreadable' as const,
+        ...counts, stewardTransition: 'unmeasured' as const,
+      };
+      const doneCards = new Set(actions.filter((action) => action.result === 'done' && action.taskId !== undefined && cardIds.has(action.taskId)).map((action) => action.taskId));
+      const total = cardIds.size;
+      const ratio = total === 0 ? null : doneCards.size / total;
+      return {
+        verb, byTaskAgent: doneCards.size, total, observedActions, ratio, state: total === 0 ? 'no-denominator' as const : 'measured' as const,
+        ...counts, stewardTransition: ratio === null ? 'unmeasured' as const : doneCards.size > 0 ? 'observed' as const : 'not-observed' as const,
+      };
+    }
     if (verb !== 'land') return {
       verb, byTaskAgent, total: null, observedActions, ratio: null,
       state: actionsUnreadable ? 'unreadable' : 'no-denominator',
@@ -52,6 +141,15 @@ export function measureTaskAgentCover(input: TaskAgentCoverInput): CoverRow[] {
       stewardTransition: ratio === null ? 'unmeasured' : byTaskAgent !== null && byTaskAgent > 0 ? 'observed' : 'not-observed',
     };
   });
+  if (input.taskCards !== undefined) {
+    try {
+      debug.log('task-agent.cover', 'by-card', {
+        cards: input.taskCards === null ? null : cardIds?.size,
+        verbs: rows.filter((row) => row.verb !== 'land').map(({ verb, byTaskAgent, total, state }) => ({ verb, byTaskAgent, total, state })),
+      });
+    } catch { /* fail-soft */ }
+  }
+  return rows;
 }
 
 /** A single human-readable line per verb; unknown numbers are never rendered as zero. */

package/src/task-agent/judge.ts

@@ -72,6 +72,22 @@ const EXECUTOR_VARIANT: Partial<Record<TaskMove, RetryVariant>> = {
   alternative: 'alternative',
 };
 
+/** 사다리 R4 — 실행부 허용 목록에 올릴 수 있는 재발사 계열 수(설정 `taskAgent.liveMoves` 어휘 그대로). */
+export const LIVE_RETRY_MOVES = ['narrow-relaunch', 'wait-retry', 'salvage-relaunch', 'alternative'] as const satisfies readonly TaskMove[];
+export type LiveRetryMove = typeof LIVE_RETRY_MOVES[number];
+
+const RETRY_MOVE_OF_VARIANT: Record<RetryVariant, LiveRetryMove> = {
+  narrow: 'narrow-relaunch',
+  wait: 'wait-retry',
+  salvage: 'salvage-relaunch',
+  alternative: 'alternative',
+};
+
+/** 실행부 `retry` 가 어느 수인가 — 갈래 없는 재발사(리뷰 fail 의 must-fix 재발사)는 «좁혀 재발사»다. */
+export function retryMoveOf(variant?: RetryVariant): LiveRetryMove {
+  return RETRY_MOVE_OF_VARIANT[variant ?? 'narrow'];
+}
+
 function base(input: TaskJudgeInput): Omit<TaskJudgement, 'executorKind'> {
   if (input.deliveryEvidence) return input.deliveryEvidence.ok
     ? { move: 'propose-green', stage: 'closing', reason: `전달 근거 확인: ${input.deliveryEvidence.files.join(', ')}` }

package/src/task-agent/land-order-ledger.ts

@@ -0,0 +1,95 @@
+/**
+ * TA-LAND-ORDER-LEDGER — 겹침 쌍·착지 순서 원장(첫 조각 · MK 0.2.24 칸 LAND-ORDER-LEDGER).
+ *
+ * - 왜: 재판정 틱이 같은 PR 의 여러 머리를 겹쳐 재게이트·land 하면서 «무엇이 먼저 착지했고 그때 리뷰·게이트가
+ *   무엇을 말했나»가 카드 이력 흐름에만 남는다. 착지 순서를 정하는 다음 소비자(L8 머지 큐 · OVERLAP-METRIC 집계 —
+ *   다음 조각)는 한 줄씩인 «원장» 모양이 필요하다 — 이 모듈은 그 행을 만들고 붙인다(순서 결정은 여기서 하지 않는다).
+ * - 행 = {pr, head, cardId, gateBase, reviewVerdict, mustFix, landOk, landClass, at} — `joinLandOrderRow` 가 순수하게
+ *   만들고(파일을 읽지 않는다) `appendLandOrderRow` 가 카드 상태 파일 옆 `land-order-ledger.jsonl`(JSONL) 에 붙인다.
+ * - reviewVerdict: review-results 파일(`review-result-capture.ts` 의 reviewResultPath 꼴)을 못 읽으면 'missing' —
+ *   0 으로 쓰지 않는다. mustFix 도 읽었을 때만 수로, 모르면 null(0 이 아니다).
+ * - 같은 pr+head 는 한 줄만 — 두 번 불러도 첫 줄이 그대로다(덮어쓰지 않는다).
+ * - 호출자: `rejudge-on-head.ts` ③ land 단계 — executeLiveLand 직후 한 번. 쓰기 실패는 호출자가 삼킨다(land 결과 무변).
+ * - 관측: `task-agent.land-order` · 'appended' | 'append-failed' {pr, head} — 호출자가 남긴다.
+ */
+import { appendFileSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import type { LiveMoveResult } from './live-moves.js';
+import type { ParsedReviewResult } from './review-result-capture.js';
+
+/** 원장 행 — 같은 pr+head 는 한 줄만. */
+export interface LandOrderRow {
+  pr: number;
+  head: string;
+  cardId: string;
+  /** 재게이트 base — 겹침 증거(#26023 꼴)의 `gate.baseCommit`. */
+  gateBase: string;
+  /** review-results 파일을 못 읽으면 'missing' — 0 으로 쓰지 않는다. */
+  reviewVerdict: string;
+  /** must-fix 수 — 읽었을 때만. 모르면 null(0 이 아니다). */
+  mustFix: number | null;
+  landOk: boolean;
+  /** 실패 갈래(infra|judgement|base-stale) — 갈래가 없으면(성공) null. */
+  landClass: string | null;
+  at: string;
+}
+
+/**
+ * 겹침 증거(#26023 꼴 `{pr, head, gate:{head, baseCommit, passed}, reviewResult}`) ⊕ 카드 식별.
+ * `cardId` 는 증거 «파일»에는 없는 칸이라 호출자가 메모리에서 싣는다(파일 형식은 무변).
+ */
+export interface LandOrderOverlapEvidence {
+  pr: number;
+  head: string;
+  cardId: string;
+  gate: { head: string; baseCommit: string; passed: boolean };
+  reviewResult?: string;
+}
+
+/** 원장 파일 — 카드 상태 파일 옆(reviewResultPath 와 같은 «옆» 규칙). */
+export function landOrderLedgerPath(statePath: string): string {
+  return join(dirname(statePath), 'land-order-ledger.jsonl');
+}
+
+/** 순수 함수 — 겹침 증거 ⊕ 회수한 리뷰 결과 ⊕ land 결과를 원장 한 행으로 합친다(파일을 읽지 않는다). */
+export function joinLandOrderRow(input: {
+  overlapEvidence: LandOrderOverlapEvidence;
+  /** review-results 파일을 읽어 해석한 결과 — 못 읽으면 null(→ reviewVerdict 'missing'). */
+  reviewResult: ParsedReviewResult | null;
+  landed: Pick<LiveMoveResult, 'ok' | 'landAttempt'>;
+  at: string;
+}): LandOrderRow {
+  return {
+    pr: input.overlapEvidence.pr,
+    head: input.overlapEvidence.head,
+    cardId: input.overlapEvidence.cardId,
+    gateBase: input.overlapEvidence.gate.baseCommit,
+    reviewVerdict: input.reviewResult?.verdict ?? 'missing',
+    mustFix: input.reviewResult?.mustFix ?? null,
+    landOk: input.landed.ok === true,
+    landClass: input.landed.landAttempt?.class ?? null,
+    at: input.at,
+  };
+}
+
+/** 원장에 한 줄 붙인다 — 같은 pr+head 가 이미 있으면 그대로(두 번 불러도 1행). 못 붙이면 던진다(호출자가 삼킨다). */
+export function appendLandOrderRow(statePath: string, row: LandOrderRow): void {
+  const ledgerPath = landOrderLedgerPath(statePath);
+  let existing: string;
+  try {
+    existing = readFileSync(ledgerPath, 'utf8');
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException)?.code !== 'ENOENT') throw error;
+    existing = '';
+  }
+  const samePair = (value: unknown): boolean => {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+    const entry = value as Partial<LandOrderRow>;
+    return entry.pr === row.pr && typeof entry.head === 'string' && entry.head.toLowerCase() === row.head.toLowerCase();
+  };
+  const seen = existing.split('\n').filter(Boolean).some((line) => {
+    try { return samePair(JSON.parse(line)); } catch { return false; }
+  });
+  if (seen) return;
+  appendFileSync(ledgerPath, `${JSON.stringify(row)}\n`);
+}

package/src/task-agent/live-move-history.ts

@@ -10,7 +10,7 @@
  */
 import { debug } from '../debug/log.js';
 import type { LiveMoveResult, TaskAgentLiveMove } from './live-moves.js';
-import { LIVE_MOVE_HISTORY_EVENT, updateTaskCard, type TaskCard, type TaskCardEvent } from './task-hand.js';
+import { HAND_MOVE_HISTORY_EVENT, LIVE_MOVE_HISTORY_EVENT, updateTaskCard, type TaskCard, type TaskCardEvent } from './task-hand.js';
 
 export const LIVE_MOVE_EFFECT_UNKNOWN = 'unknown';
 /** 리뷰는 떼어 띄운다(`defaultRequestReview` · stdio ignore) — 판정·must-fix·reviewRoute 는 그 리뷰 자기 관측에만 있다. */
@@ -131,3 +131,89 @@ export function recordLiveMoveHistory(
   }
   return outcome;
 }
+
+/**
+ * HAND-MOVE-LEDGER — 자리가 손으로 마무리한 수(기존 실패 면제 · diff 재적용 · 범위 자르기 · 쪼개기 · 다른 모델 의견)도
+ * 같은 원장 칸(카드 history)에 한 줄로 남긴다.
+ * - 어휘는 다섯뿐(`HAND_MOVE_KINDS`) — 모르는 kind 는 거부한다(지어낸 줄을 원장에 남기지 않는다).
+ * - 쓰기 길은 live-move 와 같은 `updateTaskCard` — 기존 history 항목은 건드리지 않고 덧붙이기만.
+ */
+/** 카드 history 의 hand-move 줄 이벤트 이름(정의는 task-hand.ts — 상태 사유 판정이 같은 상수로 뺀다). */
+export { HAND_MOVE_HISTORY_EVENT };
+
+/** 자리가 손으로 쓸 수 있는 수의 어휘(칸 문면 그대로 다섯) — 이 밖은 거부된다. */
+export const HAND_MOVE_KINDS = ['exempt-failure', 'reapply-diff', 'trim-scope', 'split', 'second-opinion'] as const;
+export type HandMoveKind = typeof HAND_MOVE_KINDS[number];
+
+export function isHandMoveKind(kind: string): kind is HandMoveKind {
+  return (HAND_MOVE_KINDS as readonly string[]).includes(kind);
+}
+
+export interface HandMoveHistoryInput {
+  /** 손으로 쓴 수의 종류 — `HAND_MOVE_KINDS` 밖이면 거부된다. */
+  kind: string;
+  /** 남긴 자리(예: OP·MK·TC·UX) — 누가 손으로 마무리했나. */
+  by: string;
+  /** 무엇을 했나 — 한 줄. */
+  detail: string;
+  /** 관련 PR(있으면). */
+  pr?: number;
+  /** 줄 시각(시험 주입 · 기본 지금). */
+  at?: string;
+}
+
+/** hand-move 줄의 history 칸 — `by` 는 `TaskCardEvent` 밖 칸이라 확장 인터페이스로 달린다. */
+export interface HandMoveHistoryEntry extends TaskCardEvent {
+  event: typeof HAND_MOVE_HISTORY_EVENT;
+  kind: HandMoveKind;
+  by: string;
+  detail: string;
+}
+
+export function handMoveHistoryEntry(input: HandMoveHistoryInput & { at: string; kind: HandMoveKind }): HandMoveHistoryEntry {
+  return {
+    at: input.at,
+    event: HAND_MOVE_HISTORY_EVENT,
+    kind: input.kind,
+    by: input.by,
+    detail: input.detail,
+    ...(input.pr !== undefined ? { pr: input.pr } : {}),
+  };
+}
+
+export type HandMoveHistoryOutcome = { written: true; entry: HandMoveHistoryEntry } | { written: false; reason: string };
+
+/**
+ * 자리가 손으로 마무리한 수 한 줄을 카드 history 에 덧붙인다(`recordLiveMoveHistory` 와 같은 길 · 같은 계약).
+ * 던지지 않는다 — 모르는 kind · 카드 없음 · 쓰기 실패는 관측으로 남기고 결과로 돌려준다.
+ */
+export function recordHandMove(
+  statePath: string, cardId: string, input: HandMoveHistoryInput,
+  log: (category: string, event: string, data: Record<string, unknown>) => void = (c, e, d) => debug.log(c, e, d, { level: 'warn' }),
+): HandMoveHistoryOutcome {
+  if (!isHandMoveKind(input.kind)) {
+    const reason = `unknown hand-move kind: ${input.kind} (known: ${HAND_MOVE_KINDS.join('|')})`;
+    try {
+      log('task-agent', 'hand-move-history-failed', { card: cardId, kind: input.kind, by: input.by, reason });
+    } catch { /* fail-soft */ }
+    return { written: false, reason };
+  }
+  const entry = handMoveHistoryEntry({ ...input, kind: input.kind, at: input.at ?? new Date().toISOString() });
+  let missing = false;
+  let outcome: HandMoveHistoryOutcome;
+  try {
+    updateTaskCard(statePath, cardId, (current) => {
+      if (!current) { missing = true; return undefined; }
+      return { ...current, history: [...(current.history ?? []), entry] };
+    });
+    outcome = missing ? { written: false, reason: 'task card not in state file' } : { written: true, entry };
+  } catch (error) {
+    outcome = { written: false, reason: (error instanceof Error ? error.message : String(error)).slice(-300) };
+  }
+  if (!outcome.written) {
+    try {
+      log('task-agent', 'hand-move-history-failed', { card: cardId, kind: input.kind, by: input.by, reason: outcome.reason });
+    } catch { /* fail-soft */ }
+  }
+  return outcome;
+}