elanous 0.2.22 → 0.2.23

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

@@ -15,11 +15,13 @@ import { debug } from '../debug/log.js';
 import { LogStore, logsDbPath } from '../mss/logging/log-store.js';
 import type { RunLedgerEntry } from '../self-implement/run-ledger.js';
 import { cardPrNumber, taskAgentStatePath, updateTaskCard, readTaskCard, type TaskCard } from './task-hand.js';
-import { judgeNextMove } from './judge.js';
+import { judgeNextMove, type TaskJudgeInput } from './judge.js';
+import { remoteParentAlive, type SshRunner } from './parent-host.js';
 
 const GOAL_ID = /^[a-f0-9]{16}$/;
 const PR_URL = /^https:\/\/github\.com\/[\w.-]+\/[\w.-]+\/pull\/(\d+)$/;
 const RUN_ID = /^run-[A-Za-z0-9_-]{4,64}$/;
+const LATE_LAUNCH_FAILURE = 'failed/needs-relaunch — card-run-bound 뒤 10분 동안 Pod 발사 근거 없음';
 
 /** 카드 런 하나의 원장 사진 — host = 카드 런 원장(없으면 null) · children = `pod-child-run` 자식 원장 · podFinishes = 호스트 logs. */
 export interface CardRunSnapshot {
@@ -131,6 +133,7 @@ export interface CardRunEvidenceDeps {
   launchBound?: (runId: string) => boolean;
   dispatchPod?: (runId: string, sinceIso: string) => boolean;
   runExit?: (runId: string) => RunExit | undefined;
+  ssh?: SshRunner;
 }
 
 async function defaultLoadLedger(): Promise<(runId: string) => RunLedgerEntry[] | null> {
@@ -212,19 +215,53 @@ export async function readCardRunSnapshot(card: Pick<TaskCard, 'runId' | 'create
  * 찾지 못했으면 쓰지 않는다. 쓴(또는 그대로인) 카드를 돌려준다.
  */
 export async function refreshCardRunBinding(cardId: string, statePath = taskAgentStatePath(), deps: CardRunEvidenceDeps = {}): Promise<{ card: TaskCard | undefined; evidence?: CardRunEvidence }> {
-  const card = readTaskCard(cardId, statePath);
-  // 수동 근거(refSource manual)는 덮지 않는다 · 둘 다 차 있으면 다시 읽지 않는다(한 번만).
-  if (!card?.runId || card.refSource === 'manual' || (card.pr !== undefined && card.goalId !== undefined)) return { card };
+  let card = readTaskCard(cardId, statePath);
+  // 수동 근거(refSource manual)는 덮지 않는다 · 둘 다 차 있으면 다시 읽지 않는다(한 번만) —
+  // 단 «10분 발사 근거 없음»으로 failed 된 카드는 PR·골이 먼저 묶였어도 되살림 판정을 계속 받는다.
+  const awaitingRevival = card?.status === 'failed' && [...card.history].reverse().find((item) => item.event === 'failed')?.detail === LATE_LAUNCH_FAILURE;
+  if (!card?.runId || card.refSource === 'manual' || (card.pr !== undefined && card.goalId !== undefined && !awaitingRevival)) return { card };
+  const runId = card.runId;
   const snapshot = await readCardRunSnapshot(card, deps);
   if (snapshot.readErrors?.length) {
     try { debug.log('task-agent', 'card-bind-failed', { card: cardId, runId: card.runId, errors: snapshot.readErrors }); } catch { /* fail-soft */ }
   }
   const evidence = bindCardEvidence(card, snapshot);
-  if (card.status === 'launched' && !card.pr && !evidence.pr && !snapshot.readErrors?.length) {
+  let revived = false;
+  const lastFailure = [...card.history].reverse().find((item) => item.event === 'failed');
+  if (card.status === 'failed' && lastFailure?.event === 'failed' && lastFailure.detail === LATE_LAUNCH_FAILURE
+    && lastFailure.runId === runId && !snapshot.readErrors?.length) {
+    const afterFailure = (entry: RunLedgerEntry) => entry.runId === runId && Date.parse(entry.timestamp ?? '') > Date.parse(lastFailure.at);
+    const lateChild = (snapshot.host ?? []).some((entry) => entry.event === 'pod-child-run' && afterFailure(entry));
+    const prRows = [...(snapshot.host ?? []), ...Object.values(snapshot.children).flatMap((entries) => entries ?? [])]
+      .filter((entry) => entry.event === 'pr-opened' && entry.data?.number === evidence.pr?.number && (entry.runId === runId || entry.runId === evidence.childRunId));
+    // PR 근거는 원장 `pr-opened`(실패 뒤 시각) 또는 호스트 logs 의 `job-finished`(podFinishes · 시각 없음) — 후자는
+    // `pod-child-run` 자식에게만 붙고, failed 판정은 그 자식이 «없을 때»만 났으므로 지금 보이면 그 자체로 늦은 근거다.
+    const prFromJobFinished = !!evidence.pr && !!evidence.childRunId && prRows.length === 0
+      && (snapshot.podFinishes ?? []).some((row) => row.childRunId === evidence.childRunId && row.prUrl === evidence.pr?.url);
+    const latePr = !!evidence.pr && (prFromJobFinished || prRows.some((entry) => Date.parse(entry.timestamp ?? '') > Date.parse(lastFailure.at)));
+    let lateDispatch = false;
+    try { lateDispatch = (deps.dispatchPod ?? defaultDispatchPod)(runId, new Date(Date.parse(lastFailure.at) + 1).toISOString()); } catch { /* 읽기 실패는 근거가 아니다 */ }
+    if (lateChild || latePr || lateDispatch) {
+      const at = (deps.now ?? (() => new Date()))().toISOString();
+      const next = updateTaskCard(statePath, cardId, (current) => {
+        const failed = [...(current?.history ?? [])].reverse().find((item) => item.event === 'failed');
+        return current?.status === 'failed' && current.runId === runId && current.refSource !== 'manual'
+          && failed?.event === 'failed' && failed.detail === LATE_LAUNCH_FAILURE && failed.runId === runId && failed.at === lastFailure.at
+          ? { ...current, status: 'launched', history: [...current.history, { at, event: 'revived', detail: 'late launch evidence', runId }] } : undefined;
+      });
+      revived = next?.status === 'launched' && next.history.at(-1)?.event === 'revived' && next.history.at(-1)?.at === at;
+      if (revived) {
+        try { debug.log('task-agent', 'card-revived', { card: cardId, runId }); } catch { /* fail-soft */ }
+      }
+      card = next ?? card;
+    }
+  }
+  if (!card) return { card, evidence };
+  if (!revived && card.status === 'launched' && !card.pr && !evidence.pr && !snapshot.readErrors?.length) {
     const rows = [...(snapshot.host ?? []), ...Object.values(snapshot.children).flatMap((entries) => entries ?? [])];
     let exit: RunExit | undefined;
     let exitReadFailed = false;
-    try { exit = (deps.runExit ?? ((id) => readRunExits(effectiveInstanceRoot()).find((row) => row.runId === id)))(card.runId); }
+    try { exit = (deps.runExit ?? ((id) => readRunExits(effectiveInstanceRoot()).find((row) => row.runId === id)))(runId); }
     catch { exitReadFailed = true; }
     const finished = [...(snapshot.podFinishes ?? [])].reverse().find((item) => item.state === 'failed');
     const parentTerminal = [...(snapshot.host ?? [])].reverse().find((item) => item.event === 'run-status');
@@ -234,13 +271,21 @@ export async function refreshCardRunBinding(cardId: string, statePath = taskAgen
     const launched = rows.some((entry) => entry.event === 'pod-child-run');
     let dispatched = false;
     let dispatchReadFailed = false;
-    try { dispatched = (deps.dispatchPod ?? defaultDispatchPod)(card.runId, boundAt ?? card.createdAt); }
+    try { dispatched = (deps.dispatchPod ?? defaultDispatchPod)(runId, boundAt ?? card.createdAt); }
     catch { dispatchReadFailed = true; }
     let launchBound = false;
     let launchReadFailed = false;
-    try { launchBound = (deps.launchBound ?? ((id) => !!readLaunchBinding(id)))(card.runId); }
+    try { launchBound = (deps.launchBound ?? ((id) => !!readLaunchBinding(id)))(runId); }
     catch { launchReadFailed = true; }
-    const timedOut = !finished && !launched && !dispatched && !dispatchReadFailed && !exit && !exitReadFailed && !launchBound && !launchReadFailed && Number.isFinite(elapsed) && elapsed >= 600_000;
+    const missingLaunchTimedOut = !finished && !launched && !dispatched && !dispatchReadFailed && !exit && !exitReadFailed && !launchBound && !launchReadFailed && Number.isFinite(elapsed) && elapsed >= 600_000;
+    let remoteState: ReturnType<typeof remoteParentAlive> | undefined;
+    if (missingLaunchTimedOut && card.parentHost) {
+      remoteState = remoteParentAlive({ ...card.parentHost, runId }, deps.ssh);
+      if (remoteState !== 'dead') {
+        try { debug.log('task-agent', 'card-remote-parent-alive', { card: cardId, runId: card.runId, host: card.parentHost.host, pid: card.parentHost.pid, state: remoteState }); } catch { /* fail-soft */ }
+      }
+    }
+    const timedOut = missingLaunchTimedOut && (!card.parentHost || remoteState === 'dead');
     const hasPr = !!card.pr || !!evidence.pr;
     const exitHarvestBranch = exit?.lastLines?.some((line) => /(?:수확할 브랜치: |ELANOUS_POD_SALVAGE )(?:salvage\/|self-impl\/)[^\s]+/.test(line)) ?? false;
     const ledgerFailure = rows.find((entry) => entry.event === 'run-status' && entry.data?.runStatus === 'failed'
@@ -251,14 +296,15 @@ export async function refreshCardRunBinding(cardId: string, statePath = taskAgen
     const deadExit = (exit?.reason === STOP_CLASS_POD_FAILURE || exit?.reason === 'unknown') && exit.status !== null && exit.status !== 0;
     const podFailure = !noLaunchExit && (launched || dispatched) && (parentFailed && (finished || !!ledgerFailure || !!resultFailure) || deadExit)
       && (finished || ledgerFailure || resultFailure || deadExit);
-    const failure = podFailure ? judgeNextMove({ terminalRun: {
+    const terminalRun: TaskJudgeInput['terminalRun'] = podFailure ? {
       kind: STOP_CLASS_POD_FAILURE,
       reason: finished?.childError || (exit?.status != null ? `exit ${exit.status} · ${exit.reason || STOP_CLASS_POD_FAILURE}` : resultFailure ? 'result-without-error · failed' : finished ? `job-finished failed · ${STOP_CLASS_POD_FAILURE}` : `run-status failed · ${STOP_CLASS_POD_FAILURE}`),
       hasPr,
       hasHarvestBranch: exitHarvestBranch || rows.some((entry) => typeof entry.data?.harvestBranch === 'string' && !!entry.data.harvestBranch) || !!salvageBranchOf(rows),
-    } }) : noLaunchExit ? judgeNextMove({ terminalRun: { kind: STOP_CLASS_NO_LAUNCH, reason: `exit ${exit!.status} · ${exit!.reason}`, hasPr, hasHarvestBranch: false } })
-      : timedOut ? judgeNextMove({ terminalRun: { kind: STOP_CLASS_NO_LAUNCH, reason: 'card-run-bound 뒤 10분 동안 Pod 발사 근거 없음', hasPr: false, hasHarvestBranch: false } }) : undefined;
-    if (failure?.reason.startsWith('failed/')) {
+    } : noLaunchExit ? { kind: STOP_CLASS_NO_LAUNCH, reason: `exit ${exit!.status} · ${exit!.reason}`, hasPr, hasHarvestBranch: false }
+      : timedOut ? { kind: STOP_CLASS_NO_LAUNCH, reason: 'card-run-bound 뒤 10분 동안 Pod 발사 근거 없음', hasPr: false, hasHarvestBranch: false } : undefined;
+    const failure = judgeNextMove({ terminalRun });
+    if (terminalRun && failure.reason.startsWith('failed/')) {
       const at = (deps.now ?? (() => new Date()))().toISOString();
       const next = updateTaskCard(statePath, cardId, (current) => current?.status === 'launched' && current.runId === card.runId && !current.pr && current.refSource !== 'manual' ? {
         ...current, status: 'failed', history: [...current.history, { at, event: 'failed', detail: failure.reason, runId: card.runId }],

package/src/task-agent/judge.ts

@@ -76,9 +76,10 @@ function base(input: TaskJudgeInput): Omit<TaskJudgement, 'executorKind'> {
   if (input.deliveryEvidence) return input.deliveryEvidence.ok
     ? { move: 'propose-green', stage: 'closing', reason: `전달 근거 확인: ${input.deliveryEvidence.files.join(', ')}` }
     : { move: 'wait', stage: 'waiting', reason: input.deliveryEvidence.reason };
-  if (input.terminalRun && !input.terminalRun.hasPr && !input.terminalRun.hasHarvestBranch) {
-    const disposition = input.terminalRun.kind === STOP_CLASS_POD_FAILURE ? 'needs-owner' : 'needs-relaunch';
-    return { move: 'wait', stage: 'escalated', reason: `failed/${disposition} — ${input.terminalRun.reason.replace(/[\r\n]+/gu, ' ').trim() || input.terminalRun.kind}` };
+  if (input.terminalRun && !input.terminalRun.hasPr && !input.terminalRun.hasHarvestBranch && !input.pr) {
+    const disposition = input.terminalRun.kind === STOP_CLASS_POD_FAILURE ? 'needs-owner'
+      : input.terminalRun.kind === STOP_CLASS_NO_LAUNCH ? 'needs-relaunch' : undefined;
+    if (disposition) return { move: 'wait', stage: 'escalated', reason: `failed/${disposition} — ${input.terminalRun.reason.replace(/[\r\n]+/gu, ' ').trim() || input.terminalRun.kind}` };
   }
   const stop = input.stopReason;
   const kind = input.completion;

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,133 @@
+/**
+ * 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 { 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;
+}