elanous 0.2.23 → 0.2.25

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. */
@@ -59,3 +157,68 @@ export function formatTaskAgentCover(row: CoverRow): string {
   const value = (count: number | null): string => count === null ? '-' : String(count);
   return `${row.verb}: TA ${value(row.byTaskAgent)}/${value(row.total)} (${row.ratio === null ? '-' : `${(row.ratio * 100).toFixed(1)}%`}) · live ${value(row.liveActions)} · shadow ${value(row.shadowActions)} · steward-transition ${row.stewardTransition}`;
 }
+
+/** 7동사의 이름 — 리뷰·착지·수리·검증·저작·구현·정리 (decision·deliver 는 7동사 밖이라 세지 않는다). */
+export type SevenVerbName = '리뷰' | '착지' | '수리' | '검증' | '저작' | '구현' | '정리';
+
+/** no-source 는 출처 배선이 아직 없는 동사 · unreadable 은 TASK-AGENT 행동 원장을 못 읽은 것이다. */
+export type SevenVerbState = 'live' | 'shadow-only' | 'none' | 'no-source' | 'unreadable';
+
+/** 7동사 출처 표의 한 칸 — source 는 그 동사를 관측하는 TASK-AGENT action kind, null 이면 출처가 아직 없다. */
+export interface SevenVerbSource {
+  verb: SevenVerbName;
+  source: Exclude<NextActionKind, 'decision' | 'deliver'> | null;
+}
+
+/** TA-THEME-VERBS-LIVE — 7동사와 출처 표(코드로 고정). 저작·구현·정리의 출처 배선은 다음 조각. */
+export const SEVEN_VERB_SOURCES: readonly SevenVerbSource[] = [
+  { verb: '리뷰', source: 'review' },
+  { verb: '착지', source: 'land' },
+  { verb: '수리', source: 'retry' },
+  { verb: '검증', source: 'green' },
+  { verb: '저작', source: null },
+  { verb: '구현', source: null },
+  { verb: '정리', source: null },
+];
+
+/** 동사 하나의 관측 — 원장을 못 읽었으면 liveDone·shadow 는 null(0 이 아니다). */
+export interface SevenVerbLiveRow {
+  verb: SevenVerbName;
+  source: SevenVerbSource['source'];
+  liveDone: number | null;
+  shadow: number | null;
+  state: SevenVerbState;
+}
+
+/** 합계 — liveVerbs 는 원장을 못 읽었으면 null(0 으로 쓰지 않는다) · measuredVerbs 는 출처 있는 동사 수. */
+export interface SevenVerbLive {
+  verbs: SevenVerbLiveRow[];
+  liveVerbs: number | null;
+  measuredVerbs: number;
+}
+
+/** live = 창 안에 result done 인 non-shadow 사건 ≥1. 원장이 null 이거나 절단되었으면 전부 unreadable. */
+export function measureSevenVerbLive(input: TaskAgentCoverInput): SevenVerbLive {
+  const unreadable = input.taskAgentActions === null || input.truncated?.taskAgentActions === true;
+  const verbs = SEVEN_VERB_SOURCES.map(({ verb, source }): SevenVerbLiveRow => {
+    if (unreadable) return { verb, source, liveDone: null, shadow: null, state: 'unreadable' };
+    if (source === null) return { verb, source: null, liveDone: null, shadow: null, state: 'no-source' };
+    const actions = input.taskAgentActions!.filter((action) => action.kind === source);
+    const liveDone = actions.filter((action) => action.result === 'done').length;
+    const shadow = actions.filter((action) => action.result === 'shadow').length;
+    return { verb, source, liveDone, shadow, state: liveDone >= 1 ? 'live' : shadow >= 1 ? 'shadow-only' : 'none' };
+  });
+  return {
+    verbs,
+    liveVerbs: unreadable ? null : verbs.filter((row) => row.state === 'live').length,
+    measuredVerbs: SEVEN_VERB_SOURCES.filter((row) => row.source !== null).length,
+  };
+}
+
+/** 한 줄 요약 — 못 읽었으면 n 자리를 `-` 로 적는다(0 으로 읽히지 않게). */
+export function formatSevenVerbLive(measurement: SevenVerbLive): string {
+  const total = SEVEN_VERB_SOURCES.length;
+  if (measurement.liveVerbs === null) return `${total}동사 live -/${total} · 못 잼(행동 원장 null·절단)`;
+  const noSource = measurement.verbs.filter((row) => row.state === 'no-source').map((row) => row.verb).join('·');
+  return `${total}동사 live ${measurement.liveVerbs}/${total}${noSource ? ` · 출처 없음 ${noSource}` : ''}`;
+}

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;
+}