elanous 0.2.22 → 0.2.24

package/src/task-agent/parent-host.ts

@@ -12,6 +12,7 @@
  * 기본 OFF — `taskAgent.parentHost` 가 없고 `ELANOUS_TA_PARENT_HOST` 도 없으면 아무것도 바뀌지 않는다.
  */
 import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
 import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { debug } from '../debug/log.js';
@@ -29,8 +30,13 @@ export interface ParentHostConfig {
   configDir?: string;
   /** 원격 부모에 줄 `--pod-pool`(원격 kube context 이름이 HQ 와 다를 때). */
   podPool?: string;
+  /** Maximum simultaneous parent approvals on this host; absent means one conservative slot. */
+  approvalCapacity?: number;
 }
 
+/** A list opts into multi-host selection; the legacy object retains its original launch behavior. */
+export type ParentHostSetting = Partial<ParentHostConfig> | readonly Partial<ParentHostConfig>[];
+
 export const PARENT_HOST_ENV = 'ELANOUS_TA_PARENT_HOST';
 const DEFAULT_REMOTE_ELANOUS = '$HOME/.local/share/elanous/bin/elanous';
 const DEFAULT_REMOTE_CONFIG_DIR = '$HOME/.elanous';
@@ -40,14 +46,94 @@ const HOST_RE = /^[A-Za-z0-9][A-Za-z0-9._@-]{0,127}$/;
  * 켜졌나 — env 가 이긴다(`off`·`0`·빈 값이면 끔). env 가 호스트를 주면 나머지 칸(cwd 등)은 설정에서 받는다.
  * cwd 가 없으면 켜지지 않는다(어디서 띄울지 모르는 원격 발사는 하지 않는다).
  */
-export function resolveParentHost(config: Partial<ParentHostConfig> | undefined, env: NodeJS.ProcessEnv = process.env): ParentHostConfig | null {
+export function resolveParentHost(config: ParentHostSetting | undefined, env: NodeJS.ProcessEnv = process.env): ParentHostConfig | null {
+  return resolveParentHosts(config, env)[0] ?? null;
+}
+
+/** Each target is validated independently; an invalid entry cannot turn a valid list into a local-only launch. */
+export function resolveParentHosts(config: ParentHostSetting | undefined, env: NodeJS.ProcessEnv = process.env): ParentHostConfig[] {
   const fromEnv = env[PARENT_HOST_ENV];
-  if (fromEnv !== undefined && ['', '0', 'off', 'false', 'local'].includes(fromEnv.trim().toLowerCase())) return null;
-  const host = (fromEnv?.trim() || config?.host || '').trim();
-  if (!host || !HOST_RE.test(host)) return null;
-  const cwd = config?.cwd?.trim();
-  if (!cwd || !cwd.startsWith('/')) return null;
-  return { host, cwd, ...(config?.elanous ? { elanous: config.elanous } : {}), ...(config?.configDir ? { configDir: config.configDir } : {}), ...(config?.podPool ? { podPool: config.podPool } : {}) };
+  if (fromEnv !== undefined && ['', '0', 'off', 'false', 'local'].includes(fromEnv.trim().toLowerCase())) return [];
+  const configured = Array.isArray(config) ? config : [config];
+  const seen = new Set<string>();
+  const targets: ParentHostConfig[] = [];
+  if (fromEnv && Array.isArray(config) && !config.some((entry) => entry.host === fromEnv.trim())) return targets;
+  for (const entry of configured) {
+    if (fromEnv && Array.isArray(config) && entry?.host !== fromEnv.trim()) continue;
+    const host = (fromEnv?.trim() || entry?.host || '').trim();
+    const cwd = entry?.cwd?.trim();
+    if (!host || !HOST_RE.test(host) || !cwd || !cwd.startsWith('/') || seen.has(host)
+      || (Array.isArray(config) && entry?.approvalCapacity !== undefined
+        && (!Number.isSafeInteger(entry.approvalCapacity) || entry.approvalCapacity < 1))) continue;
+    seen.add(host);
+    targets.push({ host, cwd, ...(entry?.elanous ? { elanous: entry.elanous } : {}), ...(entry?.configDir ? { configDir: entry.configDir } : {}), ...(entry?.podPool ? { podPool: entry.podPool } : {}), ...(entry?.approvalCapacity !== undefined ? { approvalCapacity: entry.approvalCapacity } : {}) });
+    if (fromEnv) break; // Explicit host override selects one target only.
+  }
+  return targets;
+}
+
+/** Capacity sample is read on the host before launch. Unknown or saturated capacity is not a positive weight. */
+export interface ParentHostCapacity { approvalHeadroom: number; load: number }
+const CAPACITY_MARKER = '__ELANOUS_PARENT_CAPACITY__';
+const APPROVAL_MARKER = '__ELANOUS_PARENT_APPROVALS__';
+const LOAD_MARKER = '__ELANOUS_PARENT_LOAD__';
+/** Recent admission decisions are the host's measured approval backlog, not an inferred process count. */
+export function readParentHostCapacity(target: ParentHostConfig, ssh: SshRunner = defaultSshRunner): ParentHostCapacity | null {
+  const executable = remotePath(target.elanous ?? DEFAULT_REMOTE_ELANOUS);
+  const configDir = remotePath(target.configDir ?? DEFAULT_REMOTE_CONFIG_DIR);
+  const script = `parents=$(ps -Ao command) || exit 1; printf '%s\\n' "$parents" | awk '/[e]lanous.*harness (say|ask)/ { n++ } END { print "${CAPACITY_MARKER}" n+0 }'; `
+    + `${executable} --config-dir ${configDir} logs --event admit-by-usage --since 5m --json --limit 1000 || exit 1; `
+    + `printf '\\n${APPROVAL_MARKER}\\n'; `
+    + `cpu=$(ps -Ao %cpu=) || exit 1; printf '%s\\n' "$cpu" | awk '{ total += $1 } END { printf "${LOAD_MARKER}%.3f\\n", total+0 }'; `
+    + `cores=$(getconf _NPROCESSORS_ONLN 2>/dev/null || sysctl -n hw.ncpu 2>/dev/null) || exit 1; printf '${LOAD_MARKER}cores=%s\\n' "$cores"`;
+  try {
+    const result = ssh(target.host, script, 15_000);
+    if (result.status !== 0) return null;
+    const activeMatch = new RegExp(`^${CAPACITY_MARKER}(\\d+)$`, 'm').exec(result.stdout);
+    const boundary = result.stdout.indexOf(`\n${APPROVAL_MARKER}\n`);
+    const logsStart = result.stdout.indexOf('\n');
+    const cpuMatch = new RegExp(`^${LOAD_MARKER}([0-9]+(?:\\.[0-9]+)?)$`, 'm').exec(result.stdout);
+    const coresMatch = new RegExp(`^${LOAD_MARKER}cores=(\\d+)$`, 'm').exec(result.stdout);
+    if (!activeMatch || activeMatch.index !== 0 || logsStart < 0 || boundary < logsStart || !cpuMatch || !coresMatch) return null;
+    const active = Number(activeMatch[1]);
+    const cores = Number(coresMatch[1]);
+    const cpu = Number(cpuMatch[1]);
+    const capacity = target.approvalCapacity ?? 1;
+    if (!Number.isSafeInteger(active) || !Number.isSafeInteger(cores) || cores <= 0 || !Number.isFinite(cpu) || cpu < 0
+      || !Number.isSafeInteger(capacity) || capacity <= 0) return null;
+    const decisions = new Map<string, number>();
+    const logs = result.stdout.slice(logsStart, boundary).trim();
+    const rows = logs ? logs.split('\n').filter(Boolean) : [];
+    if (rows.length >= 1000) return null;
+    // `logs` prints newest first; apply older decisions first so the last recommendation wins.
+    for (const line of rows.reverse()) {
+      const row = JSON.parse(line) as { _meta?: unknown; category?: unknown; event?: unknown; data?: unknown };
+      if (row._meta) {
+        if (typeof row._meta === 'object' && row._meta !== null && (row._meta as { limitReached?: boolean }).limitReached) return null;
+        continue;
+      }
+      if (row.category !== 'pod-lease' || row.event !== 'admit-by-usage') return null;
+      const data = typeof row.data === 'string' ? JSON.parse(row.data) as { runId?: unknown; recommended?: unknown }
+        : row.data as { runId?: unknown; recommended?: unknown } | null;
+      if (typeof data?.runId !== 'string' || data.recommended === null) continue;
+      if (!Number.isSafeInteger(data.recommended) || (data.recommended as number) < 0) return null;
+      decisions.set(data.runId, data.recommended as number);
+    }
+    const waiting = [...decisions.values()].filter((n) => n === 0).length;
+    return { approvalHeadroom: Math.max(0, capacity - active - waiting), load: Math.max(0, cpu / (cores * 100)) };
+  } catch { return null; }
+}
+
+/** Weighted rendezvous: stable per run, no shared counter or dependence on dispatch order. */
+export function orderParentHosts(targets: readonly ParentHostConfig[], runId: string, capacities: Readonly<Record<string, ParentHostCapacity | null>>): ParentHostConfig[] {
+  return targets.map((target, index) => {
+    const sample = capacities[target.host];
+    const weight = sample && Number.isSafeInteger(sample.approvalHeadroom) && sample.approvalHeadroom > 0 && Number.isFinite(sample.load) && sample.load >= 0
+      ? sample.approvalHeadroom / (1 + sample.load) : 0;
+    const hash = createHash('sha256').update(`${runId}\0${target.host}`).digest();
+    const fraction = (hash.readUIntBE(0, 6) + 1) / (2 ** 48 + 1);
+    return { target, index, score: weight > 0 ? -Math.log(fraction) / weight : Infinity };
+  }).sort((a, b) => a.score - b.score || a.index - b.index).map(({ target }) => target);
 }
 
 /** `$HOME/…` 은 원격 셸이 풀도록 따옴표 밖에 둔다 — 나머지는 shellQuote. */
@@ -91,6 +177,20 @@ export const defaultSshRunner: SshRunner = (host, script, timeoutMs) => {
   return { status: result.status, stdout: result.stdout ?? '', stderr: result.stderr ?? (result.error ? String(result.error) : '') };
 };
 
+/** PID 재사용을 피하려면 살아 있는 프로세스의 command 가 이 카드의 런 id 도 실어야 한다. */
+export function remoteParentAlive(parentHost: { host: string; pid?: number; runId: string }, ssh: SshRunner = defaultSshRunner): 'alive' | 'dead' | 'unknown' {
+  if (!Number.isSafeInteger(parentHost.pid) || !parentHost.pid || parentHost.pid <= 0 || !/^run-[A-Za-z0-9_-]{4,64}$/.test(parentHost.runId)) return 'unknown';
+  try {
+    // `env ELANOUS_RUN_ID=… nohup` 은 exec 뒤 argv 에 남지 않는다. ps eww 가 부모의 환경을 command 와 함께 보여 준다.
+    // ⚠️ `eww` 는 «앞»에 둔다 — macOS(node-b) ps 는 `-o command= eww` 꼴을 `illegal argument: eww`(rc=1)로 거부해
+    // 늘 'unknown' 이 된다(10-10 node-b 실측). 없는 pid 는 rc=1 · 빈 출력 → 'dead'.
+    const result = ssh(parentHost.host, `ps eww -p ${parentHost.pid} -o command=`, 10_000);
+    if (result.status === 0) return result.stdout.trim() ? (result.stdout.split(/[^A-Za-z0-9_-]+/).includes(parentHost.runId) ? 'alive' : 'dead') : 'dead';
+    if (result.status === 1 && !result.stdout.trim() && !result.stderr.trim()) return 'dead';
+    return 'unknown';
+  } catch { return 'unknown'; }
+}
+
 /** 발사 전 점검 결과 — `gaps` 가 비어야 원격으로 띄운다. */
 export interface ParentHostPreflight { ok: boolean; gaps: string[]; facts: Record<string, string> }
 
@@ -117,13 +217,22 @@ export interface PreflightInput {
   ssh?: SshRunner;
 }
 
+/** 기준판 — `0.2.23-dev.0` → `0.2.23`(앞 x.y.z 만). 모양이 아니면 원문 그대로(= 정확히 같아야 통과). */
+export function releaseCore(version: string): string {
+  return /^(\d+\.\d+\.\d+)/.exec(version)?.[1] ?? version;
+}
+
 /** 순수 판정 — 원격 사실 → 막는 칸 목록. */
 export function judgeParentHostFacts(facts: Record<string, string>, input: Omit<PreflightInput, 'ssh' | 'target'> & { podPoolOverride?: boolean }): string[] {
   const gaps: string[] = [];
   if (facts.unreachable) gaps.push(`unreachable: ${facts.unreachable}`);
   else {
     if (!facts.version) gaps.push('remote-elanous-missing');
-    else if (facts.version !== input.localVersion) gaps.push(`version-mismatch: remote ${facts.version} ≠ HQ ${input.localVersion}`);
+    else if (facts.version !== input.localVersion) {
+      // 레일은 HQ 를 30분마다 올리고 원격은 한 주기 늦을 수 있다 — 기준판(x.y.z)이 같으면 막지 않고 경고만 남긴다(OP 10-09 13:17).
+      if (releaseCore(facts.version) !== releaseCore(input.localVersion)) gaps.push(`version-mismatch: remote ${facts.version} ≠ HQ ${input.localVersion}`);
+      else debug.log('task-agent.parent-host', 'version-drift', { remote: facts.version, hq: input.localVersion });
+    }
     if (facts.config !== '1') gaps.push('remote-config-missing');
     if (facts.podPool !== '1' && !input.podPoolOverride) gaps.push('remote-pod-pool-unset');
     if (facts.repo !== '1') gaps.push('remote-repo-missing');

package/src/task-agent/rejudge-on-head.ts

@@ -0,0 +1,352 @@
+/**
+ * TA-REJUDGE-ON-HEAD — 런이 멈춘 «뒤» PR 머리가 바뀌면 task agent 가 재게이트 · 리뷰 · land 를 다시 판단한다.
+ *
+ * - 왜: live 판단은 «런 멈춤 순간» 한 번뿐이다(run-supervisor → `recordTaskAgentShadowMove`). 그 뒤 사람이(또는 다른 런이)
+ *   must-fix 를 고쳐 push 해도 카드의 다음 수는 `wait` 로 남고, 새 머리를 재게이트·리뷰·착지하는 길이 없었다(2026-10-11 #26030:
+ *   호스트 재게이트 기록은 Pod 산출 머리 것뿐이고 손으로 고친 새 머리엔 없었다).
+ * - 한 틱(카드 하나 · `tasks rejudge`) — land 는 셋이 «모두» 지금 머리에 대해 참일 때만:
+ *   ① 재게이트: 지금 머리의 재게이트 기록(`card.regates[]`)이 없으면 기존 호스트 재게이트(`runHostRegate` · `noMerge` — 병합 없음 ·
+ *      ta-land-owner 와 같은 함수)를 «떼어 띄운» 자식(`tasks regate-run`)으로 한 번 돌린다 — 판단 틱을 막지 않는다. 결과
+ *      (`<state>/regate-results/<card>-<pr>-<head12>.json` · head · baseCommit · passed)는 다음 틱이 회수해 카드에 적는다.
+ *   ② 리뷰: 지금 머리로 리뷰를 요청한 적이 없으면 다시 요청한다(#25980 `executeLiveReview` 그대로 · 결과 회수도 그대로).
+ *   ③ land: 재게이트 통과 ⊕ 회수한 리뷰가 지금 머리의 pass «또는» warn ⊕ reviewed ⊕ must-fix 0(TA-LAND-WARN-MUSTFIX0)이면 겹침 증거 파일
+ *      (`<state>/overlap-evidence/<card>-<pr>-<head12>.json` = {pr, head, gate:{head, baseCommit, passed}, reviewResult} · #26023 꼴)을
+ *      쓰고 `executeLiveLand` 를 «다시 부른다»(판정 로직 무변경 · 증거를 완전히 못 갖추면 land 하지 않는다 — fail-closed).
+ *      LAND-ORDER-LEDGER — executeLiveLand 직후 겹침 쌍·착지 순서 원장(`land-order-ledger.ts` · `<state>/land-order-ledger.jsonl`)에
+ *      한 줄을 붙인다(같은 pr+head 한 줄 · 쓰기 실패는 삼킨다 — land 결과 무변 · 관측 `task-agent.land-order` appended|append-failed).
+ * - 상한: 같은 머리는 재게이트·리뷰 각 한 번 · 카드·PR 당 재게이트 `REJUDGE_HEAD_CAP` 번까지 — 넘으면 사유 줄을 남기고 멈춘다.
+ * - REJUDGE base-stale(OVERLAP-EVIDENCE-BASE-WINDOW 짝 · #26060): land 가 `base-stale-overlap`(재게이트 base 뒤 착지가 PR 파일을 건드렸다)으로
+ *   거절되면 그 시도는 `base-stale` 갈래로 적히고(judgement 1회 규칙과 섞이지 않는다), 다음 틱이 «같은 머리»를 새 base 위에서 한 번 더
+ *   재게이트한다(`staleBase` = 낡은 base · 멱등 키 = 머리 ⊕ staleBase · 상한에 포함). 그 재게이트가 통과하고 base 가 실제로 바뀌었을 때만
+ *   새 baseCommit 으로 증거를 다시 써 land 한다(`gateAt` 으로 앞 base-stale 시도를 소비) — 관측 `rejudge-on-head {step:'regate', reason:'base-stale-overlap …'}`.
+ * - 대상: 카드에 묶인 PR(URL 로 저장소 확인) ⊕ 그 PR 로 TA 가 이미 리뷰를 요청한 카드(= 런이 멈춰 TA 판단이 시작됐다).
+ * - 사람의 hold(draft PR)는 뒤집지 않는다 — 재게이트(`noMerge`)와 land 관문이 draft 를 거부한다.
+ * - 허용: 설정 `taskAgent.liveMoves` 그대로 — 재게이트·land 는 `propose-land`, 리뷰 재요청은 `review` 가 있을 때만(없으면 «했을 수»).
+ * - 관측: `task-agent` · `rejudge-on-head {card, pr, fromHead, toHead, step, decision, reason}` — 수가 난 판단은 카드 history 에도
+ *   한 줄(`event:'rejudge-on-head'` · 같은 머리·같은 단계·같은 판단은 한 번).
+ */
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { spawn } from 'node:child_process';
+import { dirname, join } from 'node:path';
+import { debug } from '../debug/log.js';
+import type { DetachedSpawn } from '../cli/tasks-cli.js';
+import { appendLandOrderRow, joinLandOrderRow } from './land-order-ledger.js';
+import { recordLiveMoveHistory } from './live-move-history.js';
+import { defaultPrHead, defaultReviewRepoCandidates, executeLiveLand, executeLiveReview, landRetryPending, type LiveMoveDeps, type LiveMoveResult, type PrHeadView, type ReviewRepoCandidate, type TaskAgentLiveMove } from './live-moves.js';
+import { capturedLandReview, captureReviewResults, parseReviewResultOutput, pendingReviewResults, type ParsedReviewResult } from './review-result-capture.js';
+import { cardPrNumber, readTaskCard, taskAgentStatePath, updateTaskCard, type TaskCard } from './task-hand.js';
+
+export const REJUDGE_ON_HEAD_EVENT = 'rejudge-on-head';
+/** 카드·PR 당 재게이트하는 머리 수 상한(머리가 바뀔 때마다 하나) — 넘으면 멈추고 사람에게 넘긴다. */
+export const REJUDGE_HEAD_CAP = 3;
+/** 떼어 띄운 재게이트 결과를 기다리는 상한 — 지나도 파일이 없으면 «결과 없음»으로 적는다(같은 머리는 다시 안 돌린다). */
+export const REGATE_RESULT_WAIT_MS = 90 * 60_000;
+
+export type RejudgeStep = 'regate' | 'review' | 'land' | 'target';
+export interface RejudgeOutcome { card: string; pr: number | null; fromHead: string | null; toHead: string | null; step: RejudgeStep; decision: string; reason: string }
+
+export interface RegateRequest { card: string; pr: number; head: string; repoRoot: string; resultPath: string }
+export interface RejudgeDeps {
+  live?: LiveMoveDeps;
+  liveMoves: ReadonlySet<TaskAgentLiveMove>;
+  /** 재게이트를 떼어 띄운다 — 시험은 주입한다. 기본은 `tasks regate-run` 자식(stdio ignore · 결과는 파일). */
+  requestRegate?: (request: RegateRequest) => Promise<void>;
+  log?: (category: string, event: string, data: Record<string, unknown>) => void;
+  /** 시험 seam — 결과 파일 읽기(없으면 ENOENT). */
+  readFile?: (path: string) => string;
+}
+
+const safe = (value: string) => value.replace(/[^A-Za-z0-9._-]/g, '_');
+export function regateResultPath(statePath: string, cardId: string, pr: number, head: string, staleBase?: string): string {
+  const suffix = staleBase ? `-from-${safe(staleBase.slice(0, 12))}` : '';
+  return join(dirname(statePath), 'regate-results', `${safe(cardId)}-${pr}-${safe(head.slice(0, 12))}${suffix}.json`);
+}
+
+/** REJUDGE base-stale — 이 재게이트(요청 시각 `since`) «뒤»에 같은 머리 land 가 base-stale 로 거절된 마지막 시도. */
+export function baseStaleAttemptAfter(card: Pick<TaskCard, 'landAttempts'>, pr: number, head: string, since: string): NonNullable<TaskCard['landAttempts']>[number] | undefined {
+  const from = Date.parse(since);
+  return (card.landAttempts ?? []).filter((entry) => entry.pr === pr && entry.head.toLowerCase() === head.toLowerCase() && entry.ok === false
+    && entry.class === 'base-stale' && Number.isFinite(from) && Date.parse(entry.at) >= from).at(-1);
+}
+export function overlapEvidencePath(statePath: string, cardId: string, pr: number, head: string): string {
+  return join(dirname(statePath), 'overlap-evidence', `${safe(cardId)}-${pr}-${safe(head.slice(0, 12))}.json`);
+}
+
+/** `tasks regate-run` 자식 argv — 같은 우주 · 같은 진입점. */
+export function regateRunArgs(entry: string, configDir: string, request: RegateRequest): string[] {
+  return [entry, '--config-dir', configDir, 'tasks', 'regate-run', '--card', request.card, '--pr', String(request.pr), '--head', request.head, '--repo', request.repoRoot, '--out', request.resultPath];
+}
+
+export async function defaultRequestRegate(request: RegateRequest, opts: { spawn?: DetachedSpawn; entry?: string; configDir?: string } = {}): Promise<void> {
+  const { spawnDetachedConfirmed, ELANOUS_CLI_ENTRY } = await import('../cli/tasks-cli.js');
+  const { getElanousConfigDirOverride } = await import('../elanous-config-dir.js');
+  const { effectiveInstanceRoot } = await import('../instance/resolve.js');
+  const configDir = opts.configDir ?? getElanousConfigDirOverride() ?? effectiveInstanceRoot();
+  await spawnDetachedConfirmed(opts.spawn ?? (spawn as unknown as DetachedSpawn), process.execPath, regateRunArgs(opts.entry ?? ELANOUS_CLI_ENTRY, configDir, request), undefined, request.repoRoot);
+}
+
+/** 재게이트 결과 파일 — `tasks regate-run` 이 쓴다. */
+export interface RegateResultFile { pr: number; head: string; passed: boolean; status?: string; baseCommit?: string; failures?: Array<{ step: string; detail: string }> }
+
+export function parseRegateResult(text: string, pr: number, head: string): RegateResultFile | null {
+  let value: unknown;
+  try { value = JSON.parse(text); } catch { return null; }
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  const v = value as Partial<RegateResultFile>;
+  if (v.pr !== pr || typeof v.head !== 'string' || v.head.toLowerCase() !== head.toLowerCase() || typeof v.passed !== 'boolean') return null;
+  // 모양이 틀린 칸은 결과로 받지 않는다(회수 중 예외로 다른 카드 판단까지 멈추지 않게) — 상한 뒤 «결과 없음»으로 적힌다.
+  if (v.baseCommit !== undefined && (typeof v.baseCommit !== 'string' || !/^[0-9a-f]{40}$/i.test(v.baseCommit))) return null;
+  if (v.status !== undefined && typeof v.status !== 'string') return null;
+  if (v.failures !== undefined && (!Array.isArray(v.failures) || !v.failures.every((f) => f && typeof f.step === 'string' && typeof f.detail === 'string'))) return null;
+  return v as RegateResultFile;
+}
+
+const sameUrl = (a: string, b: string) => a.trim().replace(/\/+$/, '').toLowerCase() === b.trim().replace(/\/+$/, '').toLowerCase();
+const sameHead = (a: string, b: string) => a.toLowerCase() === b.toLowerCase();
+
+/** 카드의 PR URL 과 같은 PR 을 돌려주는 후보 저장소 — 못 찾으면 이유. */
+async function resolveCardPr(card: TaskCard, pr: number, url: string, deps: LiveMoveDeps): Promise<{ cwd: string; view: PrHeadView } | { reason: string }> {
+  let candidates: readonly ReviewRepoCandidate[];
+  try { candidates = (deps.repoCandidates ?? defaultReviewRepoCandidates)(card); } catch { candidates = []; }
+  const misses: string[] = [];
+  for (const candidate of candidates) {
+    let view: PrHeadView | null;
+    try { view = await (deps.prHead ?? defaultPrHead)(pr, candidate.cwd); } catch { view = null; }
+    if (!view) { misses.push(`${candidate.source}: unreadable`); continue; }
+    if (!view.url || !sameUrl(view.url, url)) { misses.push(`${candidate.source}: url ${view.url ?? 'none'}`); continue; }
+    return { cwd: candidate.cwd, view };
+  }
+  return { reason: candidates.length ? misses.join(' · ') : 'no target repository (card project · harness.defaultRepo · host checkout)' };
+}
+
+/** 카드 하나를 다시 판단한다 — 던지지 않는다. 돌려주는 것은 이번 틱에 난 판단들(단계 순). */
+export async function rejudgeCardOnHead(cardId: string, deps: RejudgeDeps): Promise<RejudgeOutcome[]> {
+  const live = deps.live ?? {};
+  const statePath = live.statePath ?? taskAgentStatePath();
+  const now = () => (live.now ?? (() => new Date()))();
+  const log = deps.log ?? ((c: string, e: string, d: Record<string, unknown>) => debug.log(c, e, d));
+  const read = deps.readFile ?? ((path: string) => readFileSync(path, 'utf8'));
+  const outcomes: RejudgeOutcome[] = [];
+  const emit = (o: RejudgeOutcome, record: boolean): void => {
+    outcomes.push(o);
+    try { log('task-agent', REJUDGE_ON_HEAD_EVENT, { ...o }); } catch { /* fail-soft */ }
+    if (!record || o.pr === null) return;
+    try {
+      updateTaskCard(statePath, o.card, (current) => {
+        if (!current) return undefined;
+        const detail = `${o.fromHead ? o.fromHead.slice(0, 12) : '-'} → ${o.toHead ? o.toHead.slice(0, 12) : '-'} · ${o.reason}`;
+        // 같은 머리·같은 단계·같은 판단·같은 사유는 한 줄만 — 틱마다 쌓지 않되, 사유가 바뀌면 새 줄로 남긴다.
+        if ((current.history ?? []).some((item) => item.event === REJUDGE_ON_HEAD_EVENT && item.pr === o.pr && item.head === (o.toHead ?? undefined) && item.kind === o.step && item.effect === o.decision && item.detail === detail)) return undefined;
+        return { ...current, history: [...(current.history ?? []), {
+          at: now().toISOString(), event: REJUDGE_ON_HEAD_EVENT, kind: o.step, pr: o.pr!, ...(o.toHead ? { head: o.toHead } : {}), effect: o.decision, detail,
+        }] };
+      });
+    } catch (error) {
+      try { log('task-agent', 'rejudge-on-head-history-failed', { card: o.card, reason: (error instanceof Error ? error.message : String(error)).slice(-300) }); } catch { /* fail-soft */ }
+    }
+  };
+  const target = (decision: string, reason: string, pr: number | null = null, fromHead: string | null = null, toHead: string | null = null, record = false) => {
+    emit({ card: cardId, pr, fromHead, toHead, step: 'target', decision, reason }, record);
+    return outcomes;
+  };
+
+  // 지난 리뷰 결과부터 회수한다 — 같은 틱의 판단이 그 결과를 본다.
+  try { captureReviewResults(statePath, { cardIds: [cardId], ...(live.now ? { now: live.now } : {}), log }); } catch { /* 회수는 스스로 관측한다 */ }
+  let card: TaskCard | undefined;
+  try { card = readTaskCard(cardId, statePath); } catch (error) { return target('card-unreadable', String(error).slice(-200)); }
+  const pr = card ? cardPrNumber(card) : undefined;
+  if (!card || pr === undefined) return target('no-pr', 'card has no bound PR');
+  const reviews = (card.reviewRequests ?? []).filter((entry) => entry.pr === pr);
+  // 런이 멈춰 TA 가 이 PR 을 리뷰한 적이 있어야 재판정한다 — 도는 런의 PR 에 끼어들지 않는다.
+  if (!reviews.length) return target('not-started', 'no task-agent review on this PR yet (run not stopped/judged)', pr);
+  // 떼어 띄운 재게이트 결과를 «머리와 무관하게» 먼저 회수한다 — 결과가 나오기 전에 머리가 또 바뀌어도 그 머리의 결과는 카드에 남는다.
+  for (const pending of (card.regates ?? []).filter((entry) => entry.pr === pr && entry.passed === undefined && entry.resultPath)) {
+    let text: string | null = null;
+    try { text = read(pending.resultPath!); } catch { text = null; }
+    const result = text !== null ? parseRegateResult(text, pr, pending.head) : null;
+    const waited = now().getTime() - Date.parse(pending.at);
+    if (!result && !(waited >= REGATE_RESULT_WAIT_MS)) continue;
+    const patch = result
+      ? { passed: result.passed, ...(result.status ? { status: result.status } : {}), ...(result.baseCommit ? { baseCommit: result.baseCommit } : {}),
+        detail: result.passed ? 'passed' : `${result.failures?.[0]?.step ?? 'unknown'}: ${(result.failures?.[0]?.detail ?? '').replace(/\s+/g, ' ').slice(0, 200)}` }
+      : { passed: false, status: 'no-result', detail: `regate process produced no result after ${Math.round(waited / 60_000)}m` };
+    let wrote = false;
+    updateTaskCard(statePath, card.id, (current) => {
+      if (!current?.regates?.some((entry) => entry.pr === pr && entry.head === pending.head && entry.at === pending.at && entry.passed === undefined)) return undefined;
+      wrote = true;
+      return { ...current, regates: current.regates.map((entry) => entry.pr === pr && entry.head === pending.head && entry.at === pending.at ? { ...entry, ...patch } : entry) };
+    });
+    if (wrote) emit({ card: card.id, pr, fromHead: null, toHead: pending.head, step: 'regate', decision: patch.passed ? 'regate-passed' : 'regate-failed',
+      reason: `head ${pending.head.slice(0, 12)} · base ${(patch as { baseCommit?: string }).baseCommit?.slice(0, 12) ?? '-'} · ${patch.detail}` }, true);
+  }
+  card = readTaskCard(card.id, statePath) ?? card;
+  const regates = (card.regates ?? []).filter((entry) => entry.pr === pr);
+  // 런 멈춤 때 판단한 머리 — 리뷰 요청 중 «재판정이 낸 것»(history `rejudge-on-head` review-requested)을 뺀 마지막(Pod 재게이트가 잰 머리).
+  //   재판정이 낸 리뷰만 있는 머리는 아직 재게이트하지 않은 «새» 머리다(허용이 나중에 켜져도 재게이트·land 로 간다).
+  const rejudgeReviewed = new Set((card.history ?? []).filter((item) => item.event === REJUDGE_ON_HEAD_EVENT && item.kind === 'review' && item.effect === 'review-requested' && item.pr === pr && item.head)
+    .map((item) => item.head!.toLowerCase()));
+  const judgedHead = reviews.filter((entry) => !rejudgeReviewed.has(entry.head.toLowerCase())).at(-1)?.head ?? null;
+  // «마지막으로 재게이트한 머리» — 카드에 재게이트 기록이 없으면 런 멈춤 때 판단한 머리.
+  const fromHead = regates.at(-1)?.head ?? judgedHead;
+  const url = typeof card.pr === 'object' ? card.pr.url : undefined;
+  if (!url) return target('pr-url-unknown', 'card PR has no URL — repository unconfirmed, no gh/regate/review/land', pr, fromHead, null, true);
+  const found = await resolveCardPr(card, pr, url, live);
+  if ('reason' in found) return target('pr-unreadable', found.reason, pr, fromHead);
+  const { cwd, view } = found;
+  const toHead = view.head;
+  if (view.state !== 'OPEN') return target('pr-not-open', `PR #${pr} is ${view.state}`, pr, fromHead, toHead);
+  const step = (s: RejudgeStep, decision: string, reason: string, record: boolean) => emit({ card: card!.id, pr, fromHead, toHead, step: s, decision, reason }, record);
+
+  // 머리가 런 멈춤 때 그대로면 재판정하지 않는다 — 그 머리의 재게이트·리뷰·land 판단은 멈춤 때의 판단(슈퍼바이저 틱)이 이미 했다.
+  //   TA-LAND-RETRY-ON-INFRA — 단, 그 머리의 land 가 TA 쪽 인프라 결손으로 실패해 재시도가 남았으면 아래 ①②③ 을 그대로 탄다
+  //   (재게이트·회수한 리뷰·겹침 증거를 다시 갖춘 뒤에만 land — 관문은 그대로).
+  if (!regates.length && judgedHead && sameHead(toHead, judgedHead) && !landRetryPending(card, pr, toHead)) return target('head-unchanged', `PR #${pr} head is still the judged head`, pr, fromHead, toHead);
+
+  // ① 재게이트 — 지금 머리의 «마지막» 기록(REJUDGE base-stale 로 같은 머리를 다시 잰 기록이 뒤에 붙는다).
+  const regate = regates.filter((entry) => sameHead(entry.head, toHead)).at(-1);
+  // REJUDGE base-stale — 이 머리의 통과한 재게이트로 land 했더니 base-stale-overlap 으로 거절됐다 → 새 base 위에서 한 번 더 잰다.
+  const stale = regate?.passed === true ? baseStaleAttemptAfter(card, pr, toHead, regate.at) : undefined;
+  const staleBase = stale ? regate?.baseCommit : undefined;
+  if (stale && !staleBase) {
+    step('regate', 'not-regating', `base-stale-overlap on head ${toHead.slice(0, 12)} but the stale regate has no baseCommit — needs owner`, true);
+    return outcomes;
+  }
+  if (!regate || staleBase) {
+    const why = staleBase ? `base-stale-overlap — gate base ${staleBase.slice(0, 12)} went stale (${(stale!.reason ?? '').replace(/^base-stale-overlap:\s*/, '').slice(0, 160)})` : '';
+    if (regates.length >= REJUDGE_HEAD_CAP) {
+      step('regate', 'cap-reached', `${why ? `${why} · ` : ''}re-gated ${regates.length} times already (cap ${REJUDGE_HEAD_CAP}) — no more rejudge; needs owner`, true);
+      return outcomes;
+    }
+    if (!deps.liveMoves.has('propose-land')) step('regate', 'would-regate', `${why ? `${why} · ` : ''}propose-land not enabled in taskAgent.liveMoves — shadow`, false);
+    else {
+      const at = now().toISOString();
+      const resultPath = regateResultPath(statePath, card.id, pr, toHead, staleBase);
+      let claimed = false;
+      let capped = false;
+      updateTaskCard(statePath, card.id, (current) => {
+        const held = (current?.regates ?? []).filter((entry) => entry.pr === pr);
+        // 멱등 — 처음 재게이트는 «머리», base-stale 재게이트는 «머리 ⊕ 낡은 base» 가 키다(같은 머리·같은 base 로 두 번 안 잰다).
+        if (!current || held.some((entry) => sameHead(entry.head, toHead) && (staleBase ? entry.staleBase !== undefined && sameHead(entry.staleBase, staleBase) : true))) return undefined;
+        // 상한은 잠금 안의 «지금» 카드로 다시 잰다 — 다른 머리를 본 두 틱이 겹쳐도 상한을 넘지 않게.
+        if (held.length >= REJUDGE_HEAD_CAP) { capped = true; return undefined; }
+        claimed = true;
+        return { ...current, regates: [...(current.regates ?? []), { pr, head: toHead, at, resultPath, ...(staleBase ? { staleBase } : {}) }] };
+      });
+      if (capped) {
+        step('regate', 'cap-reached', `${why ? `${why} · ` : ''}re-gated ${REJUDGE_HEAD_CAP} times already (cap ${REJUDGE_HEAD_CAP} · claim-time recheck) — no more rejudge; needs owner`, true);
+        return outcomes;
+      }
+      if (claimed) {
+        try {
+          mkdirSync(dirname(resultPath), { recursive: true });
+          await (deps.requestRegate ?? defaultRequestRegate)({ card: card.id, pr, head: toHead, repoRoot: cwd, resultPath });
+          step('regate', 'regate-requested', `${why ? `${why} · re-gate on a new base · ` : ''}host regate (noMerge) launched detached → ${resultPath}`, true);
+        } catch (error) {
+          const detail = `regate launch failed: ${(error instanceof Error ? error.message : String(error)).slice(-200)}`;
+          updateTaskCard(statePath, card.id, (current) => current?.regates?.some((entry) => entry.pr === pr && entry.head === toHead && entry.at === at)
+            ? { ...current, regates: current.regates.map((entry) => entry.pr === pr && entry.head === toHead && entry.at === at ? { ...entry, passed: false, status: 'unmeasured', detail } : entry) }
+            : undefined);
+          step('regate', 'regate-failed', `${why ? `${why} · ` : ''}${detail}`, true);
+        }
+      }
+    }
+    // base-stale 재게이트는 그 결과가 나와야 land 한다 — 낡은 base 의 증거로 이번 틱에 다시 land 하지 않는다.
+    if (staleBase) return outcomes;
+  } else if (regate.passed === undefined) {
+    step('regate', 'awaiting-regate-result', 'host regate still running', false);
+  }
+
+  // ② 리뷰 — 지금 머리로 요청한 적이 없으면 다시(같은 머리는 한 번 · 상한은 ① 의 머리 수가 이미 막았다).
+  if (!reviews.some((entry) => sameHead(entry.head, toHead))) {
+    if (!deps.liveMoves.has('review')) step('review', 'would-review', 'review not enabled in taskAgent.liveMoves — shadow', false);
+    else {
+      const before = { reviewRequests: card.reviewRequests, landAttempts: card.landAttempts };
+      const result = await executeLiveReview(card, pr, { runId: card.runId ?? null, stopReason: 'rejudge-on-head', cwd }, { ...live, ...(deps.log ? { log: deps.log } : {}) });
+      recordMove(statePath, card.id, card.runId, 'review', result, pr, before, now, deps.log);
+      step('review', result.executed ? 'review-requested' : 'review-request-failed', result.detail, true);
+    }
+    return outcomes;
+  }
+  const latest = readTaskCard(card.id, statePath) ?? card;
+  if (pendingReviewResults(latest).some((entry) => entry.pr === pr && sameHead(entry.head, toHead))) {
+    step('review', 'awaiting-review-result', 'review result not captured yet', false);
+    return outcomes;
+  }
+  // TA-LAND-WARN-MUSTFIX0 — 정본 규칙: verdict ∈ {pass, warn} ⊕ reviewed ⊕ must-fix 가 «숫자 0» ⊕ 그 머리(모르면 통과 아님).
+  const review = capturedLandReview(latest, pr, toHead);
+  if (!review || review.mustFixCount !== 0) {
+    step('land', 'not-landing', review ? `review ${review.verdict} carries must-fix ${review.mustFixCount ?? 'unknown'}` : 'no captured review pass/warn for this head', true);
+    return outcomes;
+  }
+  if (!regate || regate.passed !== true) {
+    step('land', 'not-landing', regate ? (regate.passed === false ? `host regate not passed: ${regate.detail ?? regate.status ?? 'unknown'}` : 'host regate still running') : 'no host regate for this head', regate?.passed === false);
+    return outcomes;
+  }
+  // REJUDGE base-stale — 새 base 위 재게이트가 «같은» base 로 돌아왔다 — 증거가 또 낡았다고 거절될 것이므로 land 하지 않는다(재게이트도 멱등 키로 0).
+  if (regate.staleBase && regate.baseCommit && sameHead(regate.baseCommit, regate.staleBase)) {
+    step('land', 'not-landing', `base-stale-overlap — re-gate on head ${toHead.slice(0, 12)} returned the same base ${regate.staleBase.slice(0, 12)} (did not advance) — no land, no further re-gate on this base; needs owner`, true);
+    return outcomes;
+  }
+  if (!deps.liveMoves.has('propose-land')) { step('land', 'would-land', 'propose-land not enabled in taskAgent.liveMoves — shadow', false); return outcomes; }
+
+  // ③ land — 겹침 증거(#26023 꼴)를 «완전히» 쓴 뒤에만 executeLiveLand 를 그대로 부른다. 증거를 못 갖추면 land 하지 않는다(fail-closed).
+  const reviewResult = latest.reviewRequests?.find((entry) => entry.pr === pr && sameHead(entry.head, toHead))?.resultPath;
+  if (!reviewResult || !regate.baseCommit || !/^[0-9a-f]{40}$/i.test(regate.baseCommit)) {
+    step('land', 'not-landing', `overlap evidence incomplete — ${!reviewResult ? 'review result path missing' : 'regate baseCommit missing'}`, true);
+    return outcomes;
+  }
+  const overlapEvidence = overlapEvidencePath(statePath, card.id, pr, toHead);
+  // #26023 꼴 그대로 — 증거 «파일» 내용은 무변 · 아래 원장 조인이 같은 모양을 쓴다(cardId 는 메모리에서만 싣는다).
+  const overlapEvidenceContent = { pr, head: toHead, gate: { head: toHead, baseCommit: regate.baseCommit, passed: true }, reviewResult };
+  try {
+    mkdirSync(dirname(overlapEvidence), { recursive: true });
+    // 임시 파일에 쓰고 바꿔 끼운다 — 겹친 틱이 같은 경로를 다시 써도 land 가 반쯤 쓴 JSON 을 읽지 않게.
+    const tmp = `${overlapEvidence}.${process.pid}.${Date.now()}.tmp`;
+    writeFileSync(tmp, JSON.stringify(overlapEvidenceContent, null, 2));
+    renameSync(tmp, overlapEvidence);
+  } catch (error) {
+    step('land', 'not-landing', `overlap evidence write failed: ${(error instanceof Error ? error.message : String(error)).slice(-200)}`, true);
+    return outcomes;
+  }
+  const before = { reviewRequests: latest.reviewRequests, landAttempts: latest.landAttempts };
+  // 주기 id — base-stale 재게이트 뒤의 land 는 새 base 를 붙여 앞 land 의 주기 표시(모듈 전역)와 갈린다 · gateAt 이 앞 base-stale 시도를 소비한다.
+  const cycleId = `rejudge:${card.id}:${toHead}${regate.staleBase ? `:${regate.baseCommit.slice(0, 12)}` : ''}`;
+  const landed = await executeLiveLand(latest, pr, { runId: card.runId ?? null, cycleId, cwd, review, overlapEvidence, gateAt: regate.at },
+    { ...live, ...(deps.log ? { log: deps.log } : {}) });
+  // LAND-ORDER-LEDGER — executeLiveLand 직후 원장 한 줄(같은 pr+head 는 한 줄만). 쓰기가 실패해도 land 결과는 그대로(삼킨다).
+  const landOrderLog = (event: 'appended' | 'append-failed') => { try { log('task-agent.land-order', event, { pr, head: toHead }); } catch { /* fail-soft */ } };
+  try {
+    // review-results 파일을 못 읽으면 reviewVerdict 'missing' — 0 으로 쓰지 않는다(land 판정의 회수 결과와는 별개 파일).
+    let reviewForLedger: ParsedReviewResult | null = null;
+    try { reviewForLedger = parseReviewResultOutput(read(reviewResult)); } catch { reviewForLedger = null; }
+    appendLandOrderRow(statePath, joinLandOrderRow({
+      overlapEvidence: { ...overlapEvidenceContent, cardId: card.id },
+      reviewResult: reviewForLedger, landed, at: now().toISOString(),
+    }));
+    landOrderLog('appended');
+  } catch {
+    landOrderLog('append-failed');
+  }
+  recordMove(statePath, card.id, card.runId, 'propose-land', landed, pr, before, now, deps.log);
+  // TA-LAND-RETRY-ON-INFRA — 실패한 시도는 갈래·사유·재시도 여부를 사유 줄에 싣는다(다음 틱이 왜 다시 하는지/안 하는지).
+  const attempt = landed.landAttempt?.class
+    ? ` · land-class ${landed.landAttempt.class} (${landed.landAttempt.reason}) · attempt ${landed.landAttempt.attempt} · ${landed.landAttempt.class === 'base-stale' ? 'base-stale → re-gate on a new base next tick (cap counts)' : landed.landAttempt.retryAllowed ? 'retry allowed on this head' : 'no retry on this head'}`
+    : '';
+  step('land', landed.executed && landed.ok ? 'landed' : 'land-rejected', `${landed.detail}${attempt} · overlap-evidence ${overlapEvidence}`, true);
+  return outcomes;
+}
+
+function recordMove(statePath: string, cardId: string, runId: string | undefined, kind: TaskAgentLiveMove, result: LiveMoveResult, pr: number, before: Pick<TaskCard, 'reviewRequests' | 'landAttempts'>, now: () => Date, log?: RejudgeDeps['log']): void {
+  try {
+    recordLiveMoveHistory(statePath, cardId, { at: now().toISOString(), kind, executorResult: 'live', result, runId: runId ?? null, pr, before },
+      log ? (c, e, d) => log(c, e, d) : undefined);
+  } catch { /* recordLiveMoveHistory 는 스스로 관측한다 */ }
+}
+
+/** 재판정 대상 카드 — 묶인 PR ⊕ 그 PR 로 TA 리뷰를 요청한 적이 있는 카드. */
+export function rejudgeCandidates(tasks: Readonly<Record<string, TaskCard>>): string[] {
+  return Object.values(tasks).filter((card) => {
+    const pr = cardPrNumber(card);
+    return pr !== undefined && (card.reviewRequests ?? []).some((entry) => entry.pr === pr);
+  }).map((card) => card.id);
+}