elanous 0.2.32 → 0.2.35

package/src/steward/triage-budget.ts

@@ -1,4 +1,6 @@
 import { createHash } from 'node:crypto';
+import { appendFileSync, mkdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
 import { debug } from '../debug/log.js';
 import type { TriageDecision, TriageIssue } from './triage.js';
 import { InvalidWorkingBackwardsDraft } from './working-backwards.js';
@@ -187,3 +189,195 @@ export async function draftWithinBudget<T>({ wishes, draft, concurrency = 4, per
   debug.log('steward.triage', 'draft-budget', stats);
   return { ...result, stats };
 }
+
+/** Consecutive healthy shadow ticks before a live move is safe to record. */
+export const LIVE_AFTER_TICKS = 3;
+
+/** Reasons a decision is a placeholder, not a judgment — they must never be reused as if they were fresh. */
+const TEMPORARY_WHYS = ['triage deferred — deadline', 'triage judgment timed out — human review',
+  'triage judgment unavailable — human review'];
+
+export function isTemporaryDecision(decision: TriageDecision): boolean {
+  return decision.rung === 'hitl' && decision.hitlReason === 'other' && TEMPORARY_WHYS.includes(decision.why);
+}
+
+export interface TriageTickCycle {
+  /** sha256 of this tick's sorted issue identifiers — the batch fingerprint. */
+  key: string;
+  /** Consecutive ticks (this one included) that carried the same fingerprint. */
+  ticks: number;
+}
+
+export interface TriageTickBudget {
+  cycle: TriageTickCycle;
+  deadlineMs: number;
+  perIssueMs: number;
+  concurrency: number;
+  /** `repeat-tick` when the same batch already arrived in the previous tick. */
+  basis: 'first-tick' | 'repeat-tick';
+}
+
+export type TriageItemOutcome = 'reused' | 'judged' | 'timed-out' | 'unavailable' | 'deferred';
+
+export interface TriageItemEvent {
+  /** 1-based position of the issue in this tick's batch. */
+  index: number;
+  /** Which tick cycle the item was judged in. */
+  cycle: number;
+  issue: string;
+  outcome: TriageItemOutcome;
+  /** No fresh judgment backs this item — the next tick (or a human) must pick it up. */
+  degraded: boolean;
+  why: string;
+}
+
+export interface TriageItemMetrics {
+  items: number;
+  fresh: number;
+  reused: number;
+  degraded: number;
+  byOutcome: Record<TriageItemOutcome, number>;
+}
+
+export interface TriageTickHealth {
+  degraded: string[];
+  /** Degraded last tick, freshly judged this tick. */
+  healed: string[];
+  health: 'healthy' | 'healing' | 'degraded';
+  /** Consecutive non-degraded shadow ticks. */
+  liveStreak: number;
+  /** Shadow has stayed healthy long enough that a live move is safe; the mode itself is not flipped here. */
+  liveEligible: boolean;
+  transition?: 'shadow→live' | 'live→shadow';
+}
+
+export interface TriageTickRecord extends TriageTickHealth {
+  at: string;
+  mode: string;
+  key: string;
+  ticks: number;
+  issues: number;
+  deadlineMs: number;
+  perIssueMs: number;
+  concurrency: number;
+  reused: number;
+  judged: number;
+  timedOut: number;
+  deferred: number;
+  events: TriageItemEvent[];
+}
+
+export function triageTickKey(issues: TriageIssue[]): string {
+  return createHash('sha256').update(JSON.stringify(issues.map(issue => issue.identifier).sort())).digest('hex').slice(0, 16);
+}
+
+/** The tick cycle: a batch that keeps re-arriving is the same cycle, counted up; a changed batch starts at 1. */
+export function triageTickCycle(previous: Pick<TriageTickRecord, 'key' | 'ticks'> | undefined, key: string): TriageTickCycle {
+  const ticks = previous && previous.key === key && Number.isFinite(previous.ticks) ? Math.max(1, previous.ticks) + 1 : 1;
+  return { key, ticks };
+}
+
+/**
+ * Budget derived from the tick cycle: the stage deadline is fixed per tick, but a repeat cycle widens each issue's
+ * slice (up to 3×) instead of re-running the same timeout on the batch that already ran out of window last tick.
+ */
+export function triageTickBudget({ cycle, issueCount, deadlineMs = 240_000, basePerIssueMs = 90_000, maxConcurrency = 8 }: {
+  cycle: TriageTickCycle;
+  issueCount: number;
+  deadlineMs?: number;
+  basePerIssueMs?: number;
+  maxConcurrency?: number;
+}): TriageTickBudget {
+  const count = Math.max(1, Math.floor(issueCount));
+  const concurrency = Math.max(1, Math.min(Math.max(1, Math.floor(maxConcurrency)), count));
+  const stretch = Math.min(Math.max(1, Math.floor(cycle.ticks)), 3);
+  return { cycle, deadlineMs, perIssueMs: Math.min(deadlineMs, basePerIssueMs * stretch), concurrency,
+    basis: cycle.ticks > 1 ? 'repeat-tick' : 'first-tick' };
+}
+
+/** One event per item: what actually happened to it this tick and whether that leaves it degraded. */
+export function triageItemEvents({ cycle, issues, decisions, previous = [] }: {
+  cycle: TriageTickCycle;
+  issues: TriageIssue[];
+  decisions: Array<TriageDecision & { inputHash?: string; deferred?: true }>;
+  previous?: Array<TriageDecision & { inputHash?: string }>;
+}): TriageItemEvent[] {
+  const judged = new Map(decisions.map(decision => [decision.issue, decision]));
+  const earlier = new Map(previous.map(decision => [decision.issue, decision]));
+  const events: TriageItemEvent[] = [];
+  for (const [index, issue] of issues.entries()) {
+    const decision = judged.get(issue.identifier);
+    const before = earlier.get(issue.identifier);
+    let outcome: TriageItemOutcome;
+    if (!decision) outcome = 'unavailable';
+    else if (decision.deferred === true) outcome = 'deferred';
+    else if (decision.why === 'triage judgment timed out — human review') outcome = 'timed-out';
+    else if (decision.why === 'triage judgment unavailable — human review') outcome = 'unavailable';
+    else if (before && before.inputHash !== undefined && before.inputHash === decision.inputHash &&
+      !before.deferred && !isTemporaryDecision(before)) outcome = 'reused';
+    else outcome = 'judged';
+    events.push({ index: index + 1, cycle: cycle.ticks, issue: issue.identifier, outcome,
+      degraded: outcome !== 'judged' && outcome !== 'reused',
+      why: decision?.why ?? 'triage decision missing' });
+  }
+  return events;
+}
+
+export function triageItemMetrics(events: TriageItemEvent[]): TriageItemMetrics {
+  const byOutcome: Record<TriageItemOutcome, number> = { reused: 0, judged: 0, 'timed-out': 0, unavailable: 0, deferred: 0 };
+  for (const event of events) byOutcome[event.outcome]++;
+  const reused = byOutcome.reused;
+  return { items: events.length, fresh: byOutcome.judged, reused,
+    degraded: events.filter(event => event.degraded).length, byOutcome };
+}
+
+/** Healing and the shadow→live transition, read off the previous real tick — never off an assumed one. */
+export function triageTickHealth({ previous, mode, events }: {
+  previous?: Pick<TriageTickRecord, 'mode' | 'degraded' | 'liveStreak'>;
+  mode: string;
+  events: TriageItemEvent[];
+}): TriageTickHealth {
+  const degraded = events.filter(event => event.degraded).map(event => event.issue);
+  const healed = (previous?.degraded ?? []).filter(issue => !degraded.includes(issue)).sort();
+  const health = healed.length ? 'healing' : degraded.length ? 'degraded' : 'healthy';
+  // Any degradation still present this tick resets the streak — a healed item next to a degraded one is not a healthy tick.
+  const liveStreak = mode === 'shadow' ? (degraded.length ? 0 : (previous?.mode === 'shadow' ? previous.liveStreak + 1 : 1)) : 0;
+  const transition = previous && previous.mode !== mode
+    ? (mode === 'live' && previous.mode === 'shadow' ? 'shadow→live'
+      : mode === 'shadow' && previous.mode === 'live' ? 'live→shadow' : undefined)
+    : undefined;
+  return { degraded, healed, health, liveStreak, liveEligible: mode === 'shadow' && liveStreak >= LIVE_AFTER_TICKS,
+    ...(transition ? { transition } : {}) };
+}
+
+export function triageTickLedgerPath(root: string): string {
+  return join(root, 'steward', 'triage-ticks.jsonl');
+}
+
+/** The real ticks that already ran, oldest first. A torn line is not a tick. */
+export function readTriageTicks(root: string, limit = 24): TriageTickRecord[] {
+  let text: string;
+  try { text = readFileSync(triageTickLedgerPath(root), 'utf8'); } catch { return []; }
+  const records: TriageTickRecord[] = [];
+  for (const line of text.split('\n')) {
+    if (!line.trim()) continue;
+    try {
+      const parsed: unknown = JSON.parse(line);
+      if (parsed && typeof parsed === 'object' && typeof (parsed as { mode?: unknown }).mode === 'string' &&
+        typeof (parsed as { key?: unknown }).key === 'string' && typeof (parsed as { ticks?: unknown }).ticks === 'number' &&
+        Array.isArray((parsed as { degraded?: unknown }).degraded) && Array.isArray((parsed as { events?: unknown }).events)) {
+        records.push(parsed as TriageTickRecord);
+      }
+    } catch { /* torn line */ }
+  }
+  return records.slice(-Math.max(1, limit));
+}
+
+export function appendTriageTick(root: string, record: TriageTickRecord): void {
+  try {
+    mkdirSync(join(root, 'steward'), { recursive: true });
+    appendFileSync(triageTickLedgerPath(root), `${JSON.stringify(record)}\n`);
+  } catch (error) {
+    debug.log('steward.triage', 'tick-ledger-failed', { reason: String(error) }, { level: 'warn' });
+  }
+}

package/src/steward/triage.ts

@@ -1,5 +1,5 @@
 import { randomUUID } from 'node:crypto';
-import { closeSync, existsSync, openSync, readFileSync, writeFileSync, mkdirSync, rmSync } from 'node:fs';
+import { closeSync, existsSync, openSync, readFileSync, writeFileSync, mkdirSync, renameSync, rmSync } from 'node:fs';
 import { launchModeOf, rescueAllows } from './rescue.js';
 import { join } from 'node:path';
 import { fetchLinearIssues } from '../connectors/linear.js';
@@ -130,7 +130,7 @@ export function trackTablePrompt(tracks?: Record<string, string>): string {
   return `\n담당 트랙(owner) — 아래 중 하나(${keys.map(k => JSON.stringify(k)).join('|')}) · 이슈가 어느 트랙 일인지:\n${keys.map(k => `- ${k}: ${tracks[k]}`).join('\n')}`;
 }
 
-export async function triageIssues(issues: TriageIssue[], judge?: NonNullable<StewardDeps['judge']>, decide: typeof emitDecision = emitDecision, tracks?: Record<string, string>, previous: Array<TriageDecision & { inputHash?: string }> = [], ask: StewardAsk = askSteward): Promise<TriageDecision[]> {
+export async function triageIssues(issues: TriageIssue[], judge?: NonNullable<StewardDeps['judge']>, decide: typeof emitDecision = emitDecision, tracks?: Record<string, string>, previous: Array<TriageDecision & { inputHash?: string }> = [], ask: StewardAsk = askSteward, budget?: { deadlineMs: number; perIssueMs: number; concurrency: number }): Promise<TriageDecision[]> {
   const started = judge ? 0 : Date.now();
   const classified: ClassifiedIssue[] = [];
   const classifiedIds = new Set<string>();
@@ -144,7 +144,7 @@ export async function triageIssues(issues: TriageIssue[], judge?: NonNullable<St
     decide({ kind: result.rung === 'hitl' ? 'ESCALATE' : 'ROUTE', what: result.issue, reason: result.why,
       purpose: 'steward triage', target: result.owner ? `${result.rung} · ${result.owner}` : String(result.rung), refs: { issue: result.issue } });
   };
-  const { decisions } = await triageWithinBudget({ issues, previous, tracks, judge: async (issue, observedIssues) => {
+  const { decisions } = await triageWithinBudget({ issues, previous, tracks, ...(budget ?? {}), judge: async (issue, observedIssues) => {
     try {
       if (judge) return parseJudgment(issue, await judge(issue, observedIssues ?? issues, tracks), tracks);
       const byRule = ruleJudgment(issue, observedIssues ?? issues);
@@ -328,13 +328,46 @@ function logStageFailure(root: string, stage: StewardStage, reason: string): voi
 }
 const SCHEDULE_CHECK_MS = 15 * 60_000;
 
+/** Atomic marker write: stage the payload at `<marker>.tmp-<pid>`, then renameSync it into place so a
+ *  crash mid-write never leaves a half-written marker for the next sync to trip over. */
+export function writeScheduleCheckMarker(
+  marker: string,
+  at: Date,
+  write: (path: string, data: string) => void = writeFileSync,
+): void {
+  const tmp = `${marker}.tmp-${process.pid}`;
+  try {
+    write(tmp, JSON.stringify({ at: at.toISOString() }));
+    renameSync(tmp, marker);
+  } catch (error) {
+    try { rmSync(tmp, { force: true }); } catch { /* Preserve the write or rename error. */ }
+    throw error;
+  }
+}
+
 /** Called by runStewardStage(sync) under its stage slot, never from the checker CLI. */
 async function checkStewardSchedules(root: string, settings: StewardSettings, deps: StewardDeps): Promise<void> {
   const now = (deps.now ?? (() => new Date()))();
   const marker = join(root, 'steward', 'schedule-check.json');
   let previous: { at?: string } = {};
-  try { previous = JSON.parse(readFileSync(marker, 'utf8')) as typeof previous; }
-  catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error; }
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(marker, 'utf8'));
+    if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)
+      && (!('at' in parsed) || typeof parsed.at === 'string')) {
+      previous = parsed as typeof previous;
+    } else {
+      debug.log('steward.schedule-check', 'marker-recovered', { reason: 'invalid-marker-shape' });
+    }
+  }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') { /* first run in this window — previous stays {} */ }
+    else if (error instanceof SyntaxError) {
+      // Corrupt marker bytes self-heal: previous stays {} so this check runs now and the fresh
+      // writeScheduleCheckMarker below replaces the broken file. The recovery is observed.
+      debug.log('steward.schedule-check', 'marker-recovered', { reason: redactSecretText(String(error)) });
+    }
+    else throw error;
+  }
   const elapsed = now.getTime() - Date.parse(previous.at ?? '');
   if (Number.isFinite(elapsed) && elapsed >= 0 && elapsed < SCHEDULE_CHECK_MS) return;
   const inventory = deps.scheduleInventory ?? (() => {
@@ -378,7 +411,7 @@ async function checkStewardSchedules(root: string, settings: StewardSettings, de
     debug.log('steward.schedule-check', 'routing', { ownerRequests, opEscalations, recovered });
   }
   debug.log('steward.schedule-check', 'checked', { count: checked.length, findings: findings.length, mode: settings.mode });
-  writeFileSync(marker, JSON.stringify({ at: now.toISOString() }));
+  writeScheduleCheckMarker(marker, now);
 }
 
 function readState(path: string): { issues: Record<string, string>; digestDay?: string } {
@@ -454,7 +487,24 @@ export async function runStewardStage(stage: 'sync' | 'triage' | 'schedule' | 'r
         Array.isArray(item.dependsOn) && item.dependsOn.every((dep: unknown) => typeof dep === 'string') &&
         typeof item.priority === 'number' && Number.isFinite(item.priority) && typeof item.why === 'string')) previous = parsed;
     } catch { /* Missing or corrupt previous judgments are an empty cache. */ }
-    writeFileSync(judgments, JSON.stringify(await triageIssues(issues, judge, deps.decide, settings.tracks, previous, deps.ask)));
+    const { appendTriageTick, readTriageTicks, triageItemEvents, triageItemMetrics, triageTickBudget, triageTickCycle,
+      triageTickHealth, triageTickKey } = await import('./triage-budget.js');
+    const ticks = readTriageTicks(root);
+    const cycle = triageTickCycle(ticks.at(-1), triageTickKey(issues));
+    const budget = triageTickBudget({ cycle, issueCount: issues.length });
+    const decisions = await triageIssues(issues, judge, deps.decide, settings.tracks, previous, deps.ask, budget);
+    writeFileSync(judgments, JSON.stringify(decisions));
+    const events = triageItemEvents({ cycle, issues, decisions, previous });
+    const metrics = triageItemMetrics(events);
+    const mode = settings.mode ?? 'shadow';
+    const health = triageTickHealth({ previous: ticks.at(-1), mode, events });
+    for (const event of events) debug.log('steward.triage', 'item-event', { ...event, health: health.health });
+    debug.log('steward.triage', 'tick', { cycle, basis: budget.basis, perIssueMs: budget.perIssueMs,
+      concurrency: budget.concurrency, ...metrics, ...health });
+    appendTriageTick(root, { at: new Date().toISOString(), mode, key: cycle.key, ticks: cycle.ticks, issues: issues.length,
+      deadlineMs: budget.deadlineMs, perIssueMs: budget.perIssueMs, concurrency: budget.concurrency,
+      reused: metrics.byOutcome.reused, judged: metrics.byOutcome.judged, timedOut: metrics.byOutcome['timed-out'],
+      deferred: metrics.byOutcome.deferred, ...health, events });
   } else if (stage === 'schedule') {
     const decisions = JSON.parse(readFileSync(judgments, 'utf8')) as TriageDecision[];
     const pending = new Set(decisions.flatMap(decision => decision.dependsOn));

package/src/task-agent/actions.ts

@@ -64,7 +64,7 @@ export interface ActionDeps {
   releaseLanding?(day: string): void;
   /** 실패 한 번을 잠금 안에서 디스크에 더한다(다른 프로세스의 실패를 덮지 않게) · 더한 뒤의 값을 돌려준다. */
   incrementFailure?(key: string): number;
-  observe(event: 'task-agent.action', data: { taskId: string; kind: NextActionKind; result: string; reason: string }): void;
+  observe(event: 'task-agent.action' | 'task-agent.entrance-denominator', data: ActionObservation): void;
   /** 사다리 R4 — 실제로 할 재발사 수의 허용 목록(`taskAgent.liveMoves` 어휘). 없으면 종전 그대로(재발사에 목록 검사 없음) · 목록에 없는 수는 shadow. */
   liveMoves?: ReadonlySet<string>;
   /** 한 판단 회차의 발사 칸 — 호출부가 회차마다 새로 준다. 없으면 회당 상한 없음(종전). 발사를 시도할 때마다 `count` 가 오른다. */
@@ -76,6 +76,49 @@ export interface ActionDeps {
 /** 재발사는 한 판단 회차에 한 건만 발사한다. */
 export const RETRY_LAUNCHES_PER_CYCLE = 1;
 
+export interface ActionObservation {
+  taskId: string;
+  kind: NextActionKind | 'entrance-tick';
+  result: string;
+  reason: string;
+  reviewed?: number;
+  allowed?: number;
+  refused?: number;
+  reasons?: Record<string, number>;
+}
+
+export interface EntranceCandidateReview {
+  taskId: string;
+  kind: NextActionKind;
+  refusal?: string;
+}
+
+export interface EntranceTickCandidate {
+  action: NextAction;
+  refusal?: string;
+}
+
+export interface EntranceRefusalDenominator {
+  reviewed: number;
+  allowed: number;
+  refused: number;
+  reasons: Record<string, number>;
+}
+
+/** Count a tick's candidate refusals without confusing special object keys with prototypes. */
+export function buildEntranceRefusalDenominator(reviews: readonly EntranceCandidateReview[]): EntranceRefusalDenominator {
+  const reasonCounts = new Map<string, number>();
+  let refused = 0;
+  for (const review of reviews) {
+    const reason = typeof review.refusal === 'string' ? review.refusal.trim() : '';
+    if (!reason) continue;
+    refused += 1;
+    reasonCounts.set(reason, (reasonCounts.get(reason) ?? 0) + 1);
+  }
+  const reasons = Object.fromEntries(reasonCounts) as Record<string, number>;
+  return { reviewed: reviews.length, allowed: reviews.length - refused, refused, reasons };
+}
+
 /** live 인데도 shadow 로 내릴 사유 — 없으면 발사해도 된다(재발사 아닌 수는 늘 없다). 기다림(wait)은 발사가 아니라 부하·회당 상한을 보지 않는다. */
 function retryShadowReason(action: NextAction, deps: ActionDeps): string | undefined {
   if (action.kind !== 'retry') return undefined;
@@ -264,6 +307,31 @@ export async function executeNextAction(action: NextAction, deps: ActionDeps): P
   return record('done', action.rationale);
 }
 
+/** Execute the allowed candidates in a caller-supplied tick and emit one isolated denominator event. */
+export async function executeEntranceTick(candidates: readonly EntranceTickCandidate[], deps: ActionDeps): Promise<string[]> {
+  const denominator = buildEntranceRefusalDenominator(candidates.map(({ action, refusal }) => ({
+    taskId: action.taskId,
+    kind: action.kind,
+    ...(typeof refusal === 'string' ? { refusal } : {}),
+  })));
+  const observeDenominator = (result: string) => {
+    try {
+      deps.observe('task-agent.entrance-denominator', {
+        taskId: candidates[0]?.action.taskId ?? 'entrance-tick',
+        kind: 'entrance-tick', result, reason: 'entrance refusal denominator', ...denominator,
+      });
+    } catch { /* Logging must not change the actions selected for this tick. */ }
+  };
+  const results: string[] = [];
+  for (const { action, refusal } of candidates) {
+    if (typeof refusal === 'string' && refusal.trim()) continue;
+    try { results.push(await executeNextAction(action, deps)); }
+    catch (error) { observeDenominator('failed'); throw error; }
+  }
+  observeDenominator(results.at(-1) ?? 'refused-all');
+  return results;
+}
+
 /** 재발사 문면 — 원문은 고치지 않고 앞에 둔다 · 갈래 문면 · must-fix · 직전 런 순서. */
 export function retryText(action: NextAction): string {
   const sections = [action.original];

package/src/task-agent/green-sweep.ts

@@ -28,6 +28,8 @@ export interface GreenSweepDecision {
   source: GreenSweepCandidate['source'];
   verdict: GreenSweepVerdict;
   reason: string;
+  /** Present when traffic hold state could not be read; preserves the decision reason while exposing its cause. */
+  holdDiagnostic?: string;
   evidence: string;
   existingEvidence: string;
   /** Preview only; a later live operation may persist this complete value. */
@@ -107,6 +109,7 @@ export function decideGreenSweep(input: {
   pr: GreenSweepPr | null;
   ancestor: boolean | null;
   hold: boolean | null;
+  holdDiagnostic?: string;
   repositoryMatches?: boolean | null;
   ambiguousAcrossCells?: boolean;
 }): GreenSweepDecision {
@@ -116,6 +119,7 @@ export function decideGreenSweep(input: {
     const landing = pr?.viaTrain ? ` via train #${pr.viaTrain.integrationPr}` : '';
     const evidence = `GREEN-FROM-LEDGER: PR #${candidate.pr}${landing}${mergeSha ? ` merged ${mergeSha}` : ''} · ${verdict} · ${reason}`;
     return { cell: item.id, pr: candidate.pr, mergeSha, source: candidate.source, verdict, reason,
+      ...(reason === 'hold-state-unreadable' && input.holdDiagnostic ? { holdDiagnostic: input.holdDiagnostic } : {}),
       evidence, existingEvidence: item.evidence ?? '', plannedEvidence: appendGreenSweepEvidence(item.evidence, evidence) };
   };
   if (item.status !== 'yellow' && item.status !== 'red') return result('skip', 'cell-not-yellow');

package/src/task-agent/harvest-unit.ts

@@ -0,0 +1,141 @@
+export type HarvestInput = {
+  ask?: unknown;
+  context?: unknown;
+  prior?: unknown;
+};
+
+export type ReviewInvocation = {
+  stdout: string;
+  stderr?: string;
+  exitCode: number | null;
+};
+
+export type HarvestResult = {
+  outcome: 'done' | 'rework' | 'needs-human' | 'failed';
+  result: Record<string, unknown>;
+  evidence: Record<string, unknown>;
+};
+
+type ReviewRecord = Record<string, unknown> & {
+  pr?: string | number;
+  reviewed?: boolean;
+  verdict?: string | null;
+  mustFix?: unknown;
+  model?: string;
+  headCommit?: string;
+  currentHeadCommit?: string;
+};
+
+function object(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function expectedHead(input: HarvestInput): string | undefined {
+  if (object(input.context) && typeof input.context.expectedHead === 'string' && input.context.expectedHead.trim()) return input.context.expectedHead.trim();
+  return undefined;
+}
+
+function normalizedPr(value: unknown): string | undefined {
+  const raw = typeof value === 'number' && Number.isSafeInteger(value) ? String(value) : typeof value === 'string' ? value.trim() : '';
+  const normalized = raw.replace(/^#/, '');
+  return /^\d+$/.test(normalized) ? normalized : undefined;
+}
+
+function previousAttempts(input: HarvestInput): number {
+  if (!object(input.prior)) return 0;
+  const result = object(input.prior.result) ? input.prior.result : input.prior;
+  const attempts = result.attempts;
+  return Number.isSafeInteger(attempts) && (attempts as number) >= 0 ? attempts as number : 0;
+}
+
+function parseReview(stdout: string): ReviewRecord | undefined {
+  try {
+    const parsed: unknown = JSON.parse(stdout.trim());
+    if (Array.isArray(parsed)) {
+      if (parsed.length !== 1) return undefined;
+      return object(parsed[0]) ? parsed[0] as ReviewRecord : undefined;
+    }
+    return object(parsed) ? parsed as ReviewRecord : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export async function runHarvestUnit(
+  input: HarvestInput,
+  invokeReview: (args: { pr: string; intent: string }) => Promise<ReviewInvocation>,
+): Promise<HarvestResult> {
+  const attempts = previousAttempts(input) + 1;
+  const prValue = object(input.context) ? input.context.pr : undefined;
+  const pr = normalizedPr(prValue);
+  if (!pr) {
+    return { outcome: 'failed', result: { attempts, error: 'context.pr must identify one pull request' }, evidence: { pr: pr || null, attempts } };
+  }
+
+  const context = object(input.context) ? input.context : {};
+  const hasContextIntent = Object.prototype.hasOwnProperty.call(context, 'reviewIntent');
+  const intentValue = context.reviewIntent;
+  const intent = hasContextIntent
+    ? typeof intentValue === 'string' ? intentValue.trim() : ''
+    : typeof input.ask === 'string' ? input.ask.trim() : '';
+  if (!intent) {
+    return { outcome: 'failed', result: { attempts, error: hasContextIntent ? 'context.reviewIntent must be a non-empty string' : 'context.reviewIntent or ask is required' }, evidence: { pr, attempts } };
+  }
+  const expected = expectedHead(input);
+  if (!expected || !/^[0-9a-f]{40}$/i.test(expected)) {
+    return { outcome: 'needs-human', result: { pr, attempts, reason: 'expected PR head is required' }, evidence: { pr, attempts, expectedHead: expected ?? null } };
+  }
+
+  let invocation: ReviewInvocation;
+  try {
+    invocation = await invokeReview({ pr: pr.replace(/^#/, ''), intent });
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    return { outcome: 'needs-human', result: { pr, attempts, reason: 'review could not be executed' }, evidence: { pr, attempts, error: reason } };
+  }
+
+  const review = parseReview(invocation.stdout);
+  if (!review || review.reviewed !== true || typeof review.headCommit !== 'string' || typeof review.currentHeadCommit !== 'string') {
+    return { outcome: 'needs-human', result: { pr, attempts, reason: 'review result is missing or incomplete' }, evidence: {
+      pr, attempts, exitCode: invocation.exitCode, stderr: invocation.stderr ?? '', stdout: invocation.stdout.slice(0, 4000),
+    } };
+  }
+  if (normalizedPr(review.pr) !== pr) {
+    return { outcome: 'needs-human', result: { pr, attempts, reason: 'review result belongs to a different pull request' }, evidence: {
+      pr, attempts, reviewedPr: review.pr ?? null, expectedHead: expected,
+    } };
+  }
+  if (invocation.exitCode !== 0) {
+    return { outcome: 'needs-human', result: { pr, attempts, reason: 'review command exited unsuccessfully' }, evidence: {
+      pr, attempts, exitCode: invocation.exitCode, stderr: invocation.stderr ?? '',
+    } };
+  }
+  if (review.headCommit !== review.currentHeadCommit || (expected !== undefined && review.headCommit !== expected)) {
+    return { outcome: 'needs-human', result: { pr, attempts, reason: 'review head is stale or differs from expected head' }, evidence: {
+      pr, attempts, expectedHead: expected ?? null, reviewedHead: review.headCommit, currentHead: review.currentHeadCommit,
+    } };
+  }
+  if (!['pass', 'warn', 'fail'].includes(review.verdict ?? '')) {
+    return { outcome: 'needs-human', result: { pr, attempts, reason: 'review verdict is missing or invalid' }, evidence: {
+      pr, attempts, verdict: review.verdict ?? null, headCommit: review.headCommit,
+    } };
+  }
+  if (!Array.isArray(review.mustFix) || !review.mustFix.every(item => typeof item === 'string' && item.trim().length > 0)) {
+    return { outcome: 'needs-human', result: { pr, attempts, reason: 'review mustFix field is invalid' }, evidence: { pr, attempts, headCommit: review.headCommit } };
+  }
+
+  const mustFix = review.mustFix as string[];
+  if ((review.verdict === 'fail' && mustFix.length === 0)
+    || ((review.verdict === 'pass' || review.verdict === 'warn') && mustFix.length > 0)) {
+    return { outcome: 'needs-human', result: { pr, attempts, reason: 'review verdict conflicts with mustFix findings' }, evidence: {
+      pr, attempts, verdict: review.verdict, mustFix, headCommit: review.headCommit,
+    } };
+  }
+  const evidence = {
+    pr, headCommit: review.headCommit, attempts, model: review.model ?? null, verdict: review.verdict ?? null,
+    reviewResultsJson: true, exitCode: invocation.exitCode,
+  };
+  return mustFix.length > 0
+    ? { outcome: 'rework', result: { pr, headCommit: review.headCommit, attempts, mustFix }, evidence }
+    : { outcome: 'done', result: { pr, headCommit: review.headCommit, attempts, mustFix: [] }, evidence };
+}