elanous 0.2.22 → 0.2.24

package/src/task-agent/land-worktree.ts

@@ -0,0 +1,201 @@
+/**
+ * TA-LAND-WORKTREE — task agent 의 머리 고정 착지(`pr land --pr N --expected-head <sha>`)를 PR 머리 트리에서 부른다.
+ *
+ * - 왜: `pr land --expected-head` 는 «로컬 HEAD = 고정 머리 · 깨끗한 트리 · 현재 가지 = PR 가지»를 요구한다. 로컬 런은 런 작업
+ *   트리가 그 머리라 넘었지만, Pod 런 PR 은 호스트에 그 머리의 트리가 없다 — 카드의 대상 저장소(호스트 checkout)는 다른 머리라
+ *   관문을 영영 못 넘었다(2026-10-11 #26030 · `✗ expected-head: … matching local HEAD and clean worktree required`).
+ * - 무엇을: 그 cwd 의 HEAD 가 PR 머리와 다를 때만, `<state>/land-worktrees/<card>-<pr>-<head12>` 에 임시 워크트리를 만든다 —
+ *   `git fetch origin pull/N/head` 로 머리를 받고(그 sha 인지 확인), PR 가지 이름(headRefName)의 로컬 가지를 그 머리에 둔다
+ *   (`pr land` 는 현재 가지 = PR 가지를 요구한다 · detached 는 거부된다). 같은 이름의 로컬 가지가 «다른» 커밋에 있으면 만들지
+ *   않는다(남의 가지를 덮지 않는다). 의존성은 호스트 재게이트와 같은 함수(`provideCheckoutDependencies`)로 빌린다.
+ *   land 가 끝나면 성공이든 실패든 걷는다(`git worktree remove --force` ⊕ prune ⊕ 우리가 만든 가지만 지운다).
+ * - 관측: `task-agent` · `land-worktree {card, pr, head, created, removed, reason}`.
+ */
+import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { debug } from '../debug/log.js';
+import { runGitCommand } from '../git-fs/runner.js';
+
+export type GitRun = (cwd: string, args: string[]) => { status: number | null; stdout: string; stderr: string };
+const defaultGit: GitRun = (cwd, args) => {
+  const r = runGitCommand(cwd, args, { encoding: 'utf-8' });
+  return { status: r.status, stdout: String(r.stdout ?? ''), stderr: String(r.stderr ?? '') };
+};
+
+export interface LandWorktreeInput { card: string; pr: number; head: string; branch: string | undefined; repoCwd: string; statePath: string }
+export type LandWorktreeRemoval = { removed: boolean; reason?: string; /** 이 호출이 만든 가지를 지웠나 — 만든 가지가 없으면 null. */ branchRemoved?: boolean | null };
+export interface LandWorktree { cwd: string; cleanup: () => LandWorktreeRemoval }
+
+export interface LandWorktreeDeps {
+  git?: GitRun;
+  /** 시험 seam — 의존성 빌리기(기본 = 호스트 재게이트의 `provideCheckoutDependencies`). */
+  provideDeps?: (worktree: string, sourceRoot: string) => Promise<void> | void;
+}
+
+const safe = (value: string) => value.replace(/[^A-Za-z0-9._-]/g, '_');
+export function landWorktreePath(statePath: string, card: string, pr: number, head: string): string {
+  return join(dirname(statePath), 'land-worktrees', `${safe(card)}-${pr}-${safe(head.slice(0, 12))}`);
+}
+
+/** cwd 의 HEAD — 못 읽으면 null. */
+export function localHead(cwd: string, git: GitRun = defaultGit): string | null {
+  try {
+    const r = git(cwd, ['rev-parse', 'HEAD']);
+    const out = r.stdout.trim();
+    return r.status === 0 && /^[0-9a-f]{40}$/i.test(out) ? out : null;
+  } catch { return null; }
+}
+
+async function defaultProvideDeps(worktree: string, sourceRoot: string): Promise<void> {
+  const { spawnSync } = await import('node:child_process');
+  const { provideCheckoutDependencies } = await import('../self-implement/host-regate.js');
+  const install = (cwd: string) => {
+    const r = spawnSync('bun', ['install', '--frozen-lockfile'], { cwd, encoding: 'utf8', timeout: 600_000 });
+    if (r.status !== 0) throw new Error(`bun install failed in ${cwd}: ${(r.stderr || r.stdout || '').trim().slice(-200)}`);
+  };
+  provideCheckoutDependencies(worktree, sourceRoot, '', 'typescript', install);
+  // apps/pwa 는 «빌리기만» 한다 — 호스트에 설치돼 있을 때 링크하고, 아니면 설치하지 않는다(PWA 를 안 건드리는 PR 의 착지를 설치 실패로
+  //   막지 않게 · PWA 빌드가 필요한 PR 이면 `pr land` 의 자기 관문이 그 결손을 말한다).
+  if (existsSync(join(worktree, 'apps/pwa')) && existsSync(join(sourceRoot, 'apps/pwa', 'node_modules', 'next', 'package.json'))) {
+    provideCheckoutDependencies(worktree, sourceRoot, 'apps/pwa', 'next', install);
+  }
+}
+
+/** 그 경로가 이 저장소에 등록된 워크트리인가 — `git worktree list --porcelain`. 목록을 못 읽으면 null(«미등록»으로 읽지 않는다). */
+function registered(git: GitRun, repoCwd: string, path: string): boolean | null {
+  const list = git(repoCwd, ['worktree', 'list', '--porcelain']);
+  if (list.status !== 0) return null;
+  // macOS 의 /var → /private/var 처럼 같은 자리가 다른 철자로 나온다 — 실경로로 맞춘다(못 풀면 그대로).
+  const real = (p: string): string => { try { return realpathSync(p); } catch { return resolve(p); } };
+  const want = real(path);
+  return list.stdout.split('\n').some((line) => line.startsWith('worktree ') && real(line.slice('worktree '.length).trim()) === want);
+}
+
+/** 이 저장소의 git 공통 디렉터리(실경로) — 못 읽으면 null. */
+function commonDir(git: GitRun, repoCwd: string): string | null {
+  const r = git(repoCwd, ['rev-parse', '--path-format=absolute', '--git-common-dir']);
+  if (r.status !== 0 || !r.stdout.trim()) return null;
+  try { return realpathSync(r.stdout.trim()); } catch { return null; }
+}
+const ownerPath = (path: string) => `${path}.owner`;
+
+/**
+ * 걷기 — git 이 지운 것만 «지웠다»고 한다. git 이 거부하면(잠긴 트리 등) 파일을 임의로 지우지 않고 사유를 낸다.
+ * 등록이 «없는» 자리는 «우리 저장소가 만든 자리»임이 표지(`<path>.owner` = 이 저장소의 git 공통 디렉터리)로 확인될 때만 파일로 지운다
+ * (등록 전에 죽은 시도의 잔여) — 확인 못 하면(다른 저장소 · 사용자 파일일 수 있다) 지우지 않는다.
+ */
+function removeWorktree(git: GitRun, repoCwd: string, path: string): { removed: boolean; reason?: string } {
+  const isRegistered = registered(git, repoCwd, path);
+  if (isRegistered === null) return { removed: false, reason: 'git worktree list unreadable — not removing anything' };
+  if (!isRegistered && !existsSync(path)) { git(repoCwd, ['worktree', 'prune']); return { removed: true }; }
+  // 등록됐든 아니든, «우리 저장소가 만든 land 자리»임이 표지로 확인될 때만 지운다 — 같은 자리의 남의 트리·파일을 지우지 않게.
+  let owner: string | null = null;
+  try { owner = readFileSync(ownerPath(path), 'utf8').trim(); } catch { owner = null; }
+  const mine = commonDir(git, repoCwd);
+  if (!owner || !mine || owner !== mine) return { removed: false, reason: 'path not proven to be this repository\'s land worktree (no owner mark) — not deleting' };
+  const dropOwner = () => { try { rmSync(ownerPath(path), { force: true }); } catch { /* best effort */ } };
+  if (isRegistered) {
+    const removed = git(repoCwd, ['worktree', 'remove', '--force', path]);
+    if (removed.status !== 0) return { removed: false, reason: `git worktree remove failed: ${(removed.stderr || removed.stdout).trim().slice(-200)}` };
+    git(repoCwd, ['worktree', 'prune']);
+    if (existsSync(path)) return { removed: false, reason: 'worktree path still present after git worktree remove' };
+    dropOwner();
+    return { removed: true };
+  }
+  try { rmSync(path, { recursive: true, force: true }); } catch (error) { return { removed: false, reason: `unregistered leftover not removed: ${String(error).slice(-200)}` }; }
+  git(repoCwd, ['worktree', 'prune']);
+  if (existsSync(path)) return { removed: false, reason: 'leftover path still present' };
+  dropOwner();
+  return { removed: true };
+}
+
+/** `created` — 트리를 만들었었나(모르면 null) · `removed` — 만들었다면 걷었나(만든 적 없거나 모르면 null). */
+export type LandWorktreeFailure = { reason: string; created: boolean | null; removed: boolean | null };
+
+/** PR 머리 트리를 만든다 — 못 만들면 이유 ⊕ 만들었다 걷었는지(관측용). 던지지 않는다. */
+export async function createLandWorktree(input: LandWorktreeInput, deps: LandWorktreeDeps = {}): Promise<LandWorktree | LandWorktreeFailure> {
+  const git = deps.git ?? defaultGit;
+  const path = landWorktreePath(input.statePath, input.card, input.pr, input.head);
+  const head = input.head.toLowerCase();
+  const branch = input.branch;
+  const fail = (reason: string, created: boolean | null = false, removed: boolean | null = null): LandWorktreeFailure => ({ reason, created, removed });
+  if (!branch) return fail('PR head branch name unknown');
+  if (!/^[0-9a-f]{40}$/.test(head)) return fail('PR head is not a full sha');
+  // 지난 시도가 남긴 같은 자리는 먼저 걷는다(같은 PR·머리 · 재사용하지 않는다 — 상태를 모르는 트리에서 착지하지 않게).
+  if (existsSync(path) || registered(git, input.repoCwd, path) !== false) {
+    const stale = removeWorktree(git, input.repoCwd, path);
+    if (!stale.removed) return fail(`stale land worktree could not be removed: ${stale.reason}`);
+  }
+  const fetched = git(input.repoCwd, ['fetch', 'origin', `pull/${input.pr}/head`]);
+  if (fetched.status !== 0) return fail(`fetch pull/${input.pr}/head failed: ${(fetched.stderr || fetched.stdout).trim().slice(-200)}`);
+  const fetchedHead = git(input.repoCwd, ['rev-parse', 'FETCH_HEAD']);
+  if (fetchedHead.status !== 0 || fetchedHead.stdout.trim().toLowerCase() !== head) return fail(`fetched PR head ${fetchedHead.stdout.trim().slice(0, 12) || '?'} ≠ ${head.slice(0, 12)}`);
+  const branchHead = (): string | null => {
+    const r = git(input.repoCwd, ['rev-parse', '--verify', '--quiet', `refs/heads/${branch}`]);
+    return r.status === 0 ? r.stdout.trim().toLowerCase() : null;
+  };
+  const existingHead = branchHead();
+  if (existingHead && existingHead !== head) return fail(`local branch ${branch} exists at ${existingHead.slice(0, 12)} (not the PR head) — not overwriting it`);
+  const mine = commonDir(git, input.repoCwd);
+  if (!mine) return fail('git common directory unreadable');
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    // 표지를 먼저 — 등록 전에 죽어도 다음 시도가 «우리 잔여»임을 확인하고 걷을 수 있게.
+    writeFileSync(ownerPath(path), mine);
+  } catch (error) { return fail(`land worktree parent unavailable: ${String(error).slice(-200)}`); }
+  // `-b` 는 가지가 이미 있으면 아무것도 만들지 않고 실패한다 — 그래서 «우리가 만든 가지»는 add 가 성공했을 때만 참이다.
+  let added: ReturnType<GitRun>;
+  try {
+    added = existingHead
+      ? git(input.repoCwd, ['worktree', 'add', path, branch])
+      : git(input.repoCwd, ['worktree', 'add', '-b', branch, path, head]);
+  } catch (error) {
+    // 던졌다 — 실패와 같게 다룬다(아래에서 부분 생성물을 걷는다).
+    added = { status: null, stdout: '', stderr: (error instanceof Error ? error.message : String(error)).slice(-200) };
+  }
+  if (added.status !== 0) {
+    // add 가 실패했다 — 가지는 우리 것이 아니다(경합으로 남이 만들었을 수 있다). 트리 자리만 정리한다.
+    const addReason = `git worktree add failed: ${(added.stderr || added.stdout).trim().slice(-200)}`;
+    // 트리를 전혀 못 만들었으면 표지만 걷고 removed 는 «해당 없음»(null). 일부라도 남았으면(등록·경로) 걷고 그 결과를 싣는다.
+    if (!existsSync(path) && registered(git, input.repoCwd, path) === false) {
+      try { rmSync(ownerPath(path), { force: true }); } catch { /* best effort */ }
+      return fail(addReason, false, null);
+    }
+    const partial = removeWorktree(git, input.repoCwd, path);
+    return fail(`${addReason} · partial tree ${partial.removed ? 'removed' : `not removed: ${partial.reason}`}`, null, partial.removed);
+  }
+  const createdBranch = !existingHead;
+  const cleanup = (): LandWorktreeRemoval => {
+    const out = removeWorktree(git, input.repoCwd, path);
+    if (!createdBranch) return { ...out, branchRemoved: null };
+    // 우리가 만든 가지만, 그리고 아직 그 머리에 있을 때만 지운다(그 사이 남이 옮겼으면 남긴다) — 결과는 관측에 싣는다.
+    if (!out.removed) return { ...out, branchRemoved: false };
+    if (branchHead() !== head) return { ...out, branchRemoved: false, reason: `branch ${branch} moved or gone — left as is` };
+    const deleted = git(input.repoCwd, ['branch', '-D', branch]);
+    return deleted.status === 0 ? { ...out, branchRemoved: true } : { ...out, branchRemoved: false, reason: `branch -D failed: ${(deleted.stderr || deleted.stdout).trim().slice(-200)}` };
+  };
+  const abort = (reason: string): LandWorktreeFailure => { const out = cleanup(); return fail(out.reason ? `${reason} · cleanup: ${out.reason}` : reason, true, out.removed); };
+  // 만든 뒤의 준비·검증은 어떤 예외에도 걷고 돌아온다(실패해도 임시 트리를 남기지 않는다).
+  try {
+    try {
+      await (deps.provideDeps ?? defaultProvideDeps)(path, input.repoCwd);
+    } catch (error) {
+      return abort(`dependencies unavailable: ${(error instanceof Error ? error.message : String(error)).slice(-200)}`);
+    }
+    if (localHead(path, git)?.toLowerCase() !== head) return abort('land worktree HEAD is not the PR head');
+    // `pr land` 는 현재 가지 = PR 가지를 요구한다 — 의존성 준비가 가지를 바꿨으면 부르기 «전»에 멈춘다.
+    const current = git(path, ['branch', '--show-current']);
+    if (current.status !== 0 || current.stdout.trim() !== branch) return abort(`land worktree branch is ${current.stdout.trim() || 'detached'} (expected ${branch})`);
+    // `pr land --expected-head` 는 깨끗한 트리를 요구한다 — 의존성 준비가 추적 파일을 바꿨으면 부르기 «전»에 멈춘다(시도를 쓰지 않게).
+    const status = git(path, ['status', '--porcelain']);
+    if (status.status !== 0 || status.stdout.trim()) return abort(`land worktree not clean after dependency setup: ${status.stdout.trim().split('\n').slice(0, 3).join(' · ').slice(0, 200) || 'status unreadable'}`);
+  } catch (error) {
+    return abort(`land worktree check threw: ${(error instanceof Error ? error.message : String(error)).slice(-200)}`);
+  }
+  return { cwd: path, cleanup };
+}
+
+export function observeLandWorktree(data: { card: string; pr: number; head: string; created: boolean | null; removed: boolean | null; branchRemoved?: boolean | null; reason: string },
+  log?: (category: string, event: string, data: Record<string, unknown>) => void): void {
+  try { (log ?? ((c, e, d) => debug.log(c, e, d)))('task-agent', 'land-worktree', data); } catch { /* fail-soft */ }
+}

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

@@ -0,0 +1,219 @@
+/**
+ * TA-LIVE-MOVE-CARD-HISTORY — live-move(실행 · 그림자)를 «그 카드의 history» 에 한 줄로 남긴다.
+ *
+ * - 왜: live-move 사건은 logs(`task-agent` · `live-move`)에만 남았다 — 운영 logs.db 는 상한 정리로 약 2시간 창이라
+ *   몇 시간 뒤엔 «0행»이 되고, 그 사건을 근거로 한 green 이 철회됐다(2026-10-10). 카드 원장은 정리되지 않는다.
+ * - 무엇을: `{ at, event:'live-move', kind, executed, ok, executorResult(shadow|live), detail, runId?, pr?, head?, effect }`.
+ *   `effect` 는 «그 수의 효과»를 아는 만큼만 — 모르면 `unknown`(지어내지 않는다).
+ * - 쓰기 길: `updateTaskCard`(실행부·`run-bound` 와 같은 잠금 · 같은 상태 파일). 기존 history 항목은 건드리지 않고 덧붙이기만.
+ * - 쓰기 실패는 live-move 를 막지 않는다 — 관측(`task-agent` · `live-move-history-failed`)만 남기고 돌아간다.
+ */
+import { debug } from '../debug/log.js';
+import type { LiveMoveResult, TaskAgentLiveMove } from './live-moves.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 는 그 리뷰 자기 관측에만 있다. */
+export const LIVE_REVIEW_EFFECT_REQUESTED = 'review requested · result not received (self review runs detached; verdict/must-fix/reviewRoute not reported back)';
+/** TA-REVIEW-RESULT-CAPTURE — 결과 파일로 받는 review: 결과는 다음 TA 틱 · `tasks show` 가 `live-move-result` 줄로 회수한다. */
+export const LIVE_REVIEW_EFFECT_PENDING = 'review requested · result pending (self review runs detached; --json result expected at resultPath, appended as live-move-result on a later TA tick or tasks show)';
+
+interface LiveMoveHistoryBase {
+  at: string;
+  /** 판단한 수의 종류(설정 어휘 그대로 — propose-land 는 propose-land). 실행부 결과의 kind('land')와 섞지 않는다. */
+  kind: TaskAgentLiveMove;
+  runId?: string | null;
+  pr?: number;
+  /** 수 «전»에 읽은 카드의 기록(머리 판정용) — 없으면 head 를 싣지 않는다. */
+  before?: Pick<TaskCard, 'reviewRequests' | 'landAttempts'>;
+}
+
+/**
+ * 호출부가 «아는 사실»을 명시한다 — live 는 실행부 결과가 «반드시» 있고, shadow 는 «실행부를 부르지 않았다»는 판단 사유가 있다.
+ * 결과 부재만으로 shadow·미실행을 단정하지 않게 둘을 타입으로 가른다.
+ */
+export type LiveMoveHistoryInput = LiveMoveHistoryBase & (
+  | { executorResult: 'live'; result: LiveMoveResult; shadowDetail?: never }
+  | { executorResult: 'shadow'; shadowDetail: string; result?: never }
+);
+
+/**
+ * 효과 한 줄 — 아는 만큼만.
+ * - shadow · 실행 안 됨 → `none — …`(부작용이 없었다는 것은 «안다»).
+ * - review 실행 → 요청만 했고 결과는 못 받았다(비동기).
+ * - land 성공 → «실행부가 ok 를 보고했다»만 적는다(병합 상태는 여기서 다시 확인하지 않는다) · 병합 sha 는 모른다.
+ * - propose-green 실행 → 칸 id.
+ * - 그 밖(land 실패 · 카드 갱신 실패 등) → `unknown`.
+ */
+export function liveMoveEffect(input: Pick<LiveMoveHistoryInput, 'executorResult' | 'result'>, checklistId?: string | null): string {
+  if (input.executorResult === 'shadow') return 'none — shadow (not executed)';
+  const result = input.result;
+  if (!result) return LIVE_MOVE_EFFECT_UNKNOWN;
+  if (!result.executed) return 'none — not executed';
+  if (result.kind === 'review' && result.ok) return result.resultPath ? LIVE_REVIEW_EFFECT_PENDING : LIVE_REVIEW_EFFECT_REQUESTED;
+  if (result.kind === 'land' && result.ok) return 'land reported ok by the executor (merge state not re-checked here) · merge sha not reported';
+  if (result.kind === 'propose-green' && result.ok) return `green proposed · checklist ${checklistId ?? '-'} (checklist untouched)`;
+  return LIVE_MOVE_EFFECT_UNKNOWN;
+}
+
+type MoveRecord = { pr: number; head: string; at: string };
+
+/**
+ * 실행한 머리 — 수 «전»에 읽은 카드(`before`)와 기록 시점 카드를 비교해, 그 PR 에 «이번 수 동안 새로 생긴» 기록
+ * (reviewRequests · landAttempts)이 정확히 하나일 때만 그 머리다. 둘 이상(겹친 수)·없음·실행 안 함·`before` 모름 → 싣지 않는다(지어내지 않는다).
+ */
+function executedHead(card: TaskCard, input: LiveMoveHistoryInput): string | undefined {
+  if (!input.result?.executed || input.pr === undefined || !input.before) return undefined;
+  const pick = (c: Pick<TaskCard, 'reviewRequests' | 'landAttempts'>): readonly MoveRecord[] =>
+    (input.kind === 'review' ? c.reviewRequests : input.kind === 'propose-land' ? c.landAttempts : undefined) ?? [];
+  const key = (entry: MoveRecord) => `${entry.pr}\u0000${entry.head}\u0000${entry.at}`;
+  const seen = new Set(pick(input.before).map(key));
+  const fresh = pick(card).filter((entry) => entry.pr === input.pr && !seen.has(key(entry)));
+  if (fresh.length !== 1) return undefined;
+  const entry = fresh[0]!;
+  // 귀속 확인 — 그 기록이 «이 결과»의 것임을 결과 쪽 사실로 맞춰 본다. 못 맞추면 싣지 않는다.
+  const result = input.result;
+  // land 결과는 머리를 싣지 않는다(detail = pr land 출력 꼬리) — 호출별 귀속 근거가 없으니 land 줄엔 head 를 싣지 않는다.
+  const attributed = input.kind === 'review' && result.detail.includes(entry.head.slice(0, 12));
+  return attributed ? entry.head : undefined;
+}
+
+export function liveMoveHistoryEntry(card: TaskCard, input: LiveMoveHistoryInput): TaskCardEvent {
+  const head = executedHead(card, input);
+  return {
+    at: input.at,
+    event: LIVE_MOVE_HISTORY_EVENT,
+    kind: input.kind,
+    executed: input.result?.executed ?? false,
+    // 실행 결과가 없으면(그림자) ok 는 «미상» — 칸을 싣지 않는다(참으로 기본값을 주지 않는다).
+    ...(input.result ? { ok: input.result.ok } : {}),
+    executorResult: input.executorResult,
+    // 자르지 않는다 — 실행부 detail 은 이미 짧게(≤300) 만들어지고, 오래 보존할 근거를 조용히 잘라 두지 않는다.
+    detail: input.result?.detail ?? input.shadowDetail ?? '',
+    ...(input.runId ? { runId: input.runId } : {}),
+    ...(input.pr !== undefined ? { pr: input.pr } : {}),
+    ...(head ? { head } : {}),
+    // TA-REVIEW-RESULT-CAPTURE — 실행한 review 만 결과 파일 경로를 싣는다(다른 수 · 그림자 줄은 종전 칸 그대로).
+    ...(input.result?.executed && input.result.resultPath ? { resultPath: input.result.resultPath } : {}),
+    effect: liveMoveEffect(input, card.checklistId ?? null),
+  };
+}
+
+export type LiveMoveHistoryOutcome = { written: true; entry: TaskCardEvent } | { written: false; reason: string };
+
+/**
+ * 카드 history 에 한 줄을 덧붙인다. 던지지 않는다 — 실패·카드 없음은 관측으로 남기고 결과로 돌려준다.
+ * `log` 는 호출자의 관측 seam(없으면 `debug.log`).
+ */
+export function recordLiveMoveHistory(
+  statePath: string, cardId: string, input: LiveMoveHistoryInput,
+  log: (category: string, event: string, data: Record<string, unknown>) => void = (c, e, d) => debug.log(c, e, d, { level: 'warn' }),
+): LiveMoveHistoryOutcome {
+  let entry: TaskCardEvent | undefined;
+  let missing = false;
+  let outcome: LiveMoveHistoryOutcome;
+  try {
+    updateTaskCard(statePath, cardId, (current) => {
+      if (!current) { missing = true; return undefined; }
+      entry = liveMoveHistoryEntry(current, input);
+      return { ...current, history: [...(current.history ?? []), entry] };
+    });
+    outcome = missing || !entry ? { 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', 'live-move-history-failed', {
+        card: cardId, kind: input.kind, executorResult: input.executorResult, executed: input.result?.executed ?? false, reason: outcome.reason,
+      });
+    } catch { /* fail-soft */ }
+  }
+  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;
+}