elanous 0.2.41 → 0.2.43

package/src/agent-mission/tool-install.ts

@@ -1,11 +1,13 @@
-import { spawnSync } from 'node:child_process';
+import { spawn, spawnSync, type ChildProcess } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
-import { mkdtempSync, rmSync } from 'node:fs';
+import { existsSync, mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
-import { join, resolve } from 'node:path';
+import { delimiter, isAbsolute, join, resolve } from 'node:path';
 import { detectDistroFamily, toolInstallLine, type DistroFamily } from '../cli/doctor-distro.js';
 import { debug } from '../debug/log.js';
 import { emitDecision, type DecisionEvent } from '../live/detail-switch.js';
+import { checkClaudeSubscription } from './claude-subscription.js';
+import { claudeBackend, codexBackend, resolveBackendSpawn } from './driver.js';
 
 type RemedyTool = 'gh' | 'rg' | 'node' | 'codex' | 'jq' | 'ffmpeg';
 export type SmokeTool = RemedyTool | 'git';
@@ -26,6 +28,201 @@ export interface SmokeDeps {
   exec?: (cmd: string[], opts: { stdin?: string; timeoutMs: number }) => ExecResult;
 }
 
+export type AgentCli = 'claude' | 'codex';
+export type AgentCliDetection = {
+  agent: AgentCli;
+  /** null means the executable/version probe could not establish installation state. */
+  installed: boolean | null;
+  /** Sanitized semantic version only; raw CLI output is never exposed. */
+  version?: string;
+  executable: 'present' | 'missing' | 'unknown';
+  login: 'ready' | 'needed' | 'api-key' | 'unknown';
+  message: string;
+};
+
+/** The supported, non-privileged installer for each visible coding CLI. */
+export const AGENT_CLI_INSTALLERS: Record<AgentCli, { command: string; args: string[]; display: string }> = {
+  codex: { command: 'npm', args: ['install', '-g', '@openai/codex@latest'], display: 'npm install -g @openai/codex@latest' },
+  claude: { command: 'npm', args: ['install', '-g', '@anthropic-ai/claude-code'], display: 'npm install -g @anthropic-ai/claude-code' },
+};
+
+export type AgentCliPreparation = {
+  ready: boolean;
+  detection: AgentCliDetection;
+  installation: 'not-needed' | 'declined' | 'installed' | 'failed';
+  message: string;
+};
+
+type AgentCliRunner = (command: string, args: string[], options: {
+  encoding: 'utf8'; timeout: number; env: Record<string, string>;
+}) => ReturnType<typeof spawnSync>;
+
+export interface AgentCliPreparationDeps {
+  env?: Record<string, string | undefined>;
+  detect?: (agent: AgentCli, options: { env: Record<string, string | undefined>; runCli?: AgentCliRunner }) => AgentCliDetection;
+  runCli?: AgentCliRunner;
+  /** Must be an explicit user confirmation; no installer runs when it is absent or declines. */
+  confirmInstall?: (prompt: string) => boolean | Promise<boolean>;
+  /** Injection seam for tests. Production runs npm only after confirmInstall returns true. */
+  install?: (command: string, args: string[], options: { env: Record<string, string>; timeoutMs: number }) => { status: number | null; error?: { code?: string } | null } | Promise<{ status: number | null; error?: { code?: string } | null }>;
+  onStatus?: (line: string) => void;
+}
+
+function runAgentCliInstaller(command: string, args: string[], options: { env: Record<string, string>; timeoutMs: number }): Promise<{ status: number | null; error?: { code?: string } | null }> {
+  return new Promise((resolve) => {
+    const spawnInstaller = spawn as unknown as (file: string, args: string[], options: { env: Record<string, string>; stdio: 'ignore'; windowsHide: true }) => ChildProcess;
+    const child = spawnInstaller(command, args, { env: options.env, stdio: 'ignore', windowsHide: true });
+    let settled = false;
+    let timedOut = false;
+    let forceKill: ReturnType<typeof setTimeout> | undefined;
+    const timeout = setTimeout(() => {
+      timedOut = true;
+      child.kill('SIGTERM');
+      forceKill = setTimeout(() => child.kill('SIGKILL'), 2_000);
+    }, options.timeoutMs);
+    const finish = (result: { status: number | null; error?: { code?: string } | null }): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
+      if (forceKill) clearTimeout(forceKill);
+      resolve(result);
+    };
+    child.once('error', (error: Error & { code?: string }) => finish({ status: null, error }));
+    child.once('close', (status: number | null) => finish(timedOut
+      ? { status: null, error: { code: 'ETIMEDOUT' } }
+      : { status }));
+  });
+}
+
+function agentCliNotReadyMessage(detection: AgentCliDetection): string {
+  if (detection.installed === false) return `${detection.agent}: 설치되지 않음`;
+  if (detection.installed === null) return `${detection.agent}: 설치 상태 확인 불가`;
+  if (detection.login === 'api-key') return `${detection.agent}: API 키 인증은 감지했지만 구독 로그인이 필요합니다. ${detection.agent} login을 실행해 주세요`;
+  if (detection.login === 'needed') return `${detection.agent}: 로그인이 필요합니다. ${detection.agent} login을 실행해 주세요`;
+  return `${detection.agent}: 로그인 상태를 확인할 수 없습니다`;
+}
+
+/** Detect first, ask once before an official install, then re-detect before the caller launches. */
+export async function prepareAgentCli(
+  agent: AgentCli,
+  deps: AgentCliPreparationDeps = {},
+): Promise<AgentCliPreparation> {
+  const env = deps.env ?? process.env;
+  const detect = deps.detect ?? detectAgentCli;
+  const detectOptions = { env, ...(deps.runCli ? { runCli: deps.runCli } : {}) };
+  const installer = AGENT_CLI_INSTALLERS[agent];
+  let detection = detect(agent, detectOptions);
+  deps.onStatus?.(detection.message);
+  if (detection.installed === true && detection.login === 'ready') {
+    return { ready: true, detection, installation: 'not-needed', message: detection.message };
+  }
+  if (detection.installed !== false) {
+    return { ready: false, detection, installation: 'not-needed', message: agentCliNotReadyMessage(detection) };
+  }
+  if (!deps.confirmInstall || !await deps.confirmInstall(`설치할까요? ${installer.display}`)) {
+    return { ready: false, detection, installation: 'declined', message: `${agent}: 설치를 건너뛰었습니다` };
+  }
+
+  const install = deps.install ?? runAgentCliInstaller;
+  let result: { status: number | null; error?: { code?: string } | null };
+  try {
+    const backend = agent === 'codex' ? codexBackend : claudeBackend;
+    result = await install(installer.command, [...installer.args], {
+      env: resolveBackendSpawn(backend, env).env,
+      timeoutMs: 300_000,
+    });
+  } catch {
+    return { ready: false, detection, installation: 'failed', message: `${agent}: 설치 명령을 실행하지 못했습니다` };
+  }
+  if (result.status !== 0) {
+    const detail = result.error?.code === 'ENOENT' ? 'npm을 찾을 수 없습니다' : '설치 명령이 성공하지 않았습니다';
+    return { ready: false, detection, installation: 'failed', message: `${agent}: ${detail}` };
+  }
+
+  detection = detect(agent, detectOptions);
+  deps.onStatus?.(detection.message);
+  if (detection.installed !== true) {
+    return { ready: false, detection, installation: 'failed', message: `${agent}: 설치 뒤 버전 확인에 실패했습니다` };
+  }
+  if (detection.login !== 'ready') {
+    return { ready: false, detection, installation: 'installed', message: agentCliNotReadyMessage(detection) };
+  }
+  return { ready: true, detection, installation: 'installed', message: detection.message };
+}
+
+function agentVersion(agent: AgentCli, raw: string): { version?: string } | undefined {
+  const prefix = agent === 'claude' ? /^(?:Claude(?: Code)?\s+)?v?/i : /^(?:Codex(?:-CLI)?\s+)?v?/i;
+  const versioned = raw.replace(prefix, '');
+  // Probe output is untrusted: validate the semver shape but expose only a bounded numeric core.
+  const match = /^(\d+\.\d+\.\d+)(?:[-+][A-Za-z0-9.-]{1,40})?(?: \(Claude Code\))?$/i.exec(versioned);
+  if (!match) return undefined;
+  const parts = match[1]!.split('.');
+  return parts.every((part) => part.length <= 6) ? { version: match[1]! } : undefined;
+}
+
+function agentExecutableExists(command: string, env: Record<string, string>): boolean {
+  if (command.includes('/')) return existsSync(isAbsolute(command) ? command : resolve(command));
+  return (env.PATH ?? '').split(delimiter).some((directory) => existsSync(join(directory || process.cwd(), command)));
+}
+
+/** Inspect the local agent CLI without returning auth output or credential values. */
+export function detectAgentCli(
+  agent: AgentCli,
+  options: { env?: Record<string, string | undefined>; runCli?: AgentCliRunner } = {},
+): AgentCliDetection {
+  const backend = agent === 'claude' ? claudeBackend : codexBackend;
+  const spawn = resolveBackendSpawn(backend, options.env ?? process.env);
+  const runCli = options.runCli ?? spawnSync;
+  const run = (args: string[]) => runCli(agent, args, {
+    encoding: 'utf8', timeout: 5_000, env: spawn.env,
+  });
+  let versionResult: ReturnType<typeof spawnSync>;
+  try { versionResult = run(['--version']); }
+  catch (error) {
+    if ((error as { code?: string })?.code === 'ENOENT') {
+      const present = agentExecutableExists(spawn.cmd, spawn.env);
+      return { agent, installed: present ? null : false, executable: present ? 'unknown' : 'missing', login: 'unknown', message: present ? `${agent}: 실행 파일을 실행할 수 없어 상태 확인 불가` : `${agent}: 설치되지 않음` };
+    }
+    return { agent, installed: null, executable: 'unknown', login: 'unknown', message: `${agent}: 설치 여부 확인 불가` };
+  }
+  if ((versionResult.error as NodeJS.ErrnoException | undefined)?.code === 'ENOENT') {
+    const present = agentExecutableExists(spawn.cmd, spawn.env);
+    return { agent, installed: present ? null : false, executable: present ? 'unknown' : 'missing', login: 'unknown', message: present ? `${agent}: 실행 파일을 실행할 수 없어 상태 확인 불가` : `${agent}: 설치되지 않음` };
+  }
+  const rawVersion = `${versionResult.stdout ?? ''}\n${versionResult.stderr ?? ''}`.trim().split(/\r?\n/, 1)[0] ?? '';
+  const verifiedVersion = versionResult.status === 0 ? agentVersion(agent, rawVersion) : undefined;
+  if (!verifiedVersion) {
+    const executable = versionResult.status === null || versionResult.error ? 'unknown' : 'present';
+    return {
+      agent, installed: null, executable, login: 'unknown',
+      message: executable === 'present' ? `${agent}: 실행 파일 있음, 버전 확인 불가` : `${agent}: 설치 여부 확인 불가`,
+    };
+  }
+
+  let login: AgentCliDetection['login'] = 'unknown';
+  if (agent === 'claude') {
+    const auth = checkClaudeSubscription({ env: spawn.env, runCli });
+    login = auth.ok ? 'ready' : auth.reason === 'logged-out' || auth.reason === 'api-key' ? 'needed' : 'unknown';
+  } else {
+    try {
+      const auth = run(['login', 'status']);
+      const output = `${auth.stdout ?? ''}\n${auth.stderr ?? ''}`;
+      const normalized = output.trim();
+      if (auth.status === 0 && /^logged in using an api key\.?$/i.test(normalized)) login = 'api-key';
+      else if (auth.status === 0 && /^logged in(?: using (?:chatgpt|openai))?\.?$/i.test(normalized)) login = 'ready';
+      else if (/\bnot\b.*\blogged in\b|\blogged out\b|\blogout\b|\bplease log in\b|\brun codex login\b/i.test(normalized)) login = 'needed';
+    } catch { /* Keep authentication unknown when the probe itself fails. */ }
+  }
+  const message = login === 'ready'
+    ? `${agent}: 설치됨${verifiedVersion.version ? ` v${verifiedVersion.version}` : ''} · 로그인 확인됨`
+    : login === 'api-key'
+      ? `${agent}: 설치됨${verifiedVersion.version ? ` v${verifiedVersion.version}` : ''} · API 키 로그인됨 (구독 로그인 아님)`
+    : login === 'needed'
+      ? `${agent}: 설치됨${verifiedVersion.version ? ` v${verifiedVersion.version}` : ''} · 로그인 필요`
+      : `${agent}: 설치됨${verifiedVersion.version ? ` v${verifiedVersion.version}` : ''} · 로그인 상태 확인 불가`;
+  return { agent, installed: true, ...(verifiedVersion.version ? { version: verifiedVersion.version } : {}), executable: 'present', login, message };
+}
+
 function defaultExec(cmd: string[], opts: { stdin?: string; timeoutMs: number }): ExecResult {
   const result = spawnSync(cmd[0]!, cmd.slice(1), {
     input: opts.stdin, timeout: opts.timeoutMs, encoding: 'utf8',

package/src/agent-substrate/context-strategy.ts

@@ -39,9 +39,9 @@ export interface CompactionOutcome {
  *  선택 필드로 읽는다. 미설정(구 config·테스트)이면 기본 1(첫 앵커 pin). 0=비활성. */
 interface AutoCompactCfgWithAnchor { preserveFirstN?: number }
 
-/** context 전략 계약 — loop 이 매 턴(turn>0) 호출. 기본=2-tier compaction. 주입으로 교체(read-time projection 등). */
+/** context 전략 계약 — loop 이 mid-loop(turn>0) 호출. 기본=2-tier compaction. 주입으로 교체(read-time projection 등). */
 export interface ContextStrategy {
-  compact(messages: LLMMessage[], ctx: { model: string; sessionId?: string; config: unknown }): Promise<CompactionOutcome>;
+  compact(messages: LLMMessage[], ctx: { model: string; sessionId?: string; config: unknown; observedInputTokens?: number }): Promise<CompactionOutcome>;
 }
 
 /**
@@ -54,8 +54,8 @@ export function createDefaultContextStrategy(): ContextStrategy {
     async compact(messages, ctx): Promise<CompactionOutcome> {
       const { shouldAutoCompact } = require('../compact/auto.js') as typeof import('../compact/auto.js');
       const acCfg = ctx.config as Parameters<typeof shouldAutoCompact>[2];
-      const decision = shouldAutoCompact(messages, ctx.model, acCfg);
-      const beforeTokens = decision.usedTokens; // estimateMessagesTokens(messages) 동일 계측
+      const decision = shouldAutoCompact(messages, ctx.model, acCfg, ctx.observedInputTokens);
+      const beforeTokens = estimateMessagesTokens(messages);
       if (!decision.fire) {
         return { fired: false, messages, reduced: false, escalated: false, ratio: decision.ratio, usedTokens: decision.usedTokens, beforeTokens, afterTokens: beforeTokens };
       }

package/src/agent-substrate/self-review-cli.ts

@@ -20,7 +20,7 @@ import { dirname, join } from 'node:path';
 import { effectiveInstanceRoot } from '../instance/resolve.js';
 import { tierModel } from '../llm/model-defaults.js';
 import { buildReviewObservation, reviewIntentFingerprint, safeLogText } from './review-observation.js';
-import { checkCitedReviewPathsAtHead, citedReviewPaths } from './review-finding-key.js';
+import { checkCitedReviewPathsAtHead, citedReviewPaths, reviewFindingKey } from './review-finding-key.js';
 import { DEFAULT_REVIEW_BACKEND, defaultAcpReviewTimeoutSec } from './acp-reviewer.js';
 import { ZAI_OPENROUTER_FALLBACK_MODEL } from '../llm/zai-coding-plan.js';
 import { debug } from '../debug/log.js';
@@ -179,10 +179,90 @@ export interface SelfReviewCliOutcome {
 
 interface SavedReviewEvidence {
   heads: string[];
-  records: Array<{ head: string; reviewedAt: number }>;
+  records: Array<{ head: string; reviewedAt: number; model?: string }>;
+  loopRounds: Array<{ head: string; reviewedAt: number; state: 'clear' | 'stale-reopen' }>;
+  fixedFindings: string[];
+  priorFindings: string[];
   unreadableFiles: string[];
 }
 
+export interface ReviewLoopBreakerAssessment {
+  state: 'clear' | 'stale-reopen';
+  staleFindings: Array<{ finding: string; reason: 'fixed-finding-reopened' | 'author-test-evidence' }>;
+}
+
+export function assessReviewLoopBreaker(input: {
+  priorFindings: string[];
+  previouslyFixedFindings?: string[];
+  deltaFindings: Array<{ finding: string; status: 'fixed' | 'open' }>;
+  currentFindings: string[];
+  changedFiles: string[];
+}): ReviewLoopBreakerAssessment {
+  const changedTestFiles = new Set(input.changedFiles.filter((file) => /\.test\.[cm]?[jt]sx?$/i.test(file)));
+  const staleFindings: ReviewLoopBreakerAssessment['staleFindings'] = [];
+  const add = (finding: string, reason: ReviewLoopBreakerAssessment['staleFindings'][number]['reason']) => {
+    if (!staleFindings.some((entry) => reviewFindingKey(entry.finding).key === reviewFindingKey(finding).key)) staleFindings.push({ finding, reason });
+  };
+  for (const fixed of input.deltaFindings.filter((entry) => entry.status === 'fixed')) {
+    if (input.currentFindings.some((current) => reviewFindingKey(current).key === reviewFindingKey(fixed.finding).key)) {
+      add(fixed.finding, 'fixed-finding-reopened');
+    }
+  }
+  for (const fixed of input.previouslyFixedFindings ?? []) {
+    if (input.currentFindings.some((current) => reviewFindingKey(current).key === reviewFindingKey(fixed).key)) {
+      add(fixed, 'fixed-finding-reopened');
+    }
+  }
+  for (const prior of input.priorFindings) {
+    const priorPaths = new Set(citedReviewPaths(prior));
+    for (const current of input.currentFindings) {
+      const sameFinding = reviewFindingKey(prior).key === reviewFindingKey(current).key
+        || citedReviewPaths(current).some((path) => priorPaths.has(path));
+      if (!sameFinding) continue;
+      const citedChangedTest = [...changedTestFiles].some((file) => {
+        const escapedFile = file.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        return new RegExp('(?:^|[\\s`])' + escapedFile + ':\\d+(?::\\d+)?(?:\\b|[`),.;])').test(current);
+      });
+      if (citedChangedTest) add(current, 'author-test-evidence');
+    }
+  }
+  return { state: staleFindings.length ? 'stale-reopen' : 'clear', staleFindings };
+}
+
+function trailingStaleReopenRounds(rounds: SavedReviewEvidence['loopRounds']): number {
+  let count = 0;
+  for (const round of [...rounds].sort((a, b) => a.reviewedAt - b.reviewedAt).reverse()) {
+    if (round.state !== 'stale-reopen') break;
+    count++;
+  }
+  return count;
+}
+
+function savedFindingList(value: unknown): string[] {
+  const values = Array.isArray(value) ? value : typeof value === 'string' ? [value] : [];
+  return values.filter((entry): entry is string => typeof entry === 'string' && entry.trim().length > 0);
+}
+
+function reviewLoopBreakerLockPath(pr: string, root = effectiveInstanceRoot()): string {
+  return join(root, 'review-results', `review-loop-breaker-${pr}.json`);
+}
+
+function readReviewLoopBreakerLock(pr: string, root = effectiveInstanceRoot()): Record<string, unknown> | undefined {
+  try {
+    const value: unknown = JSON.parse(readFileSync(reviewLoopBreakerLockPath(pr, root), 'utf8'));
+    if (!value || typeof value !== 'object' || Array.isArray(value)) return undefined;
+    const record = value as Record<string, unknown>;
+    return record.pr === pr && typeof record.head === 'string' && COMMIT_OID.test(record.head)
+      && record.state === 'waiver-needed' ? record : undefined;
+  } catch { return undefined; }
+}
+
+function writeReviewLoopBreakerLock(pr: string, head: string, reason: string, root = effectiveInstanceRoot()): void {
+  const path = reviewLoopBreakerLockPath(pr, root);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, JSON.stringify({ pr, head, state: 'waiver-needed', reason, writtenAt: Date.now() }) + '\n');
+}
+
 interface SavedReviewForDelta {
   file: string;
   headCommit: string;
@@ -304,10 +384,13 @@ function savedReviewEvidence(
 ): SavedReviewEvidence {
   const dir = join(root, 'review-results');
   let names: string[];
-  try { names = readdirSync(dir); } catch { return { heads: [], records: [], unreadableFiles: [] }; }
+  try { names = readdirSync(dir); } catch { return { heads: [], records: [], loopRounds: [], fixedFindings: [], priorFindings: [], unreadableFiles: [] }; }
   const escapedPr = pr.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
   const matchingPrInName = new RegExp(`(?:^|-)${escapedPr}(?:-|\\.json$)`, 'i');
-  const records = new Map<string, { head: string; reviewedAt: number }>();
+  const records = new Map<string, { head: string; reviewedAt: number; model?: string }>();
+  const loopRounds = new Map<string, { head: string; reviewedAt: number; state: 'clear' | 'stale-reopen' }>();
+  const fixedFindings = new Map<string, string>();
+  let latestFindings: { reviewedAt: number; findings: string[] } | undefined;
   const unreadableFiles: string[] = [];
   for (const name of names) {
     if (!name.toLowerCase().endsWith('.json')) continue;
@@ -338,16 +421,40 @@ function savedReviewEvidence(
       const recordPath = join(dir, name);
       const reviewedAt = typeof result.reviewedAt === 'number' && Number.isFinite(result.reviewedAt)
         ? result.reviewedAt : statSync(recordPath).mtimeMs;
+      const findings = savedFindingList(result.mustFix);
+      if (!latestFindings || reviewedAt > latestFindings.reviewedAt) latestFindings = { reviewedAt, findings };
       const normalized = head.toLowerCase();
+      const model = [result.model, result.respondedModel, result.requestedModel]
+        .find((value): value is string => typeof value === 'string' && value.trim().length > 0);
       const existing = records.get(normalized);
-      if (!existing || reviewedAt > existing.reviewedAt) records.set(normalized, { head: normalized, reviewedAt });
+      if (!existing || reviewedAt > existing.reviewedAt) records.set(normalized, { head: normalized, reviewedAt, ...(model ? { model } : {}) });
+      const loopBreaker = result.loopBreaker;
+      if (loopBreaker && typeof loopBreaker === 'object' && !Array.isArray(loopBreaker)) {
+        const loopRecord = loopBreaker as Record<string, unknown>;
+        const state = loopRecord.state;
+        if (Array.isArray(loopRecord.fixedFindings)) for (const finding of loopRecord.fixedFindings) {
+          if (typeof finding === 'string' && finding.trim()) fixedFindings.set(reviewFindingKey(finding).key, finding);
+        }
+        if (state === 'clear' || state === 'stale-reopen') {
+          const prior = loopRounds.get(normalized);
+          if (!prior || reviewedAt > prior.reviewedAt) loopRounds.set(normalized, { head: normalized, reviewedAt, state });
+        }
+      }
+      if (Array.isArray(result.deltaFindings)) for (const entry of result.deltaFindings) {
+        if (!entry || typeof entry !== 'object' || Array.isArray(entry)) continue;
+        const delta = entry as Record<string, unknown>;
+        if (delta.status === 'fixed' && typeof delta.finding === 'string' && delta.finding.trim()) {
+          fixedFindings.set(reviewFindingKey(delta.finding).key, delta.finding);
+        }
+      }
     } catch {
       // A filename can associate an unreadable record with this PR; fail closed at the cap.
       if (nameSuggestsPr) { unreadableFiles.push(name); onUnreadable?.(name); }
     }
   }
   const saved = [...records.values()];
-  return { heads: saved.map(({ head }) => head), records: saved, unreadableFiles };
+  return { heads: saved.map(({ head }) => head), records: saved, loopRounds: [...loopRounds.values()],
+    fixedFindings: [...fixedFindings.values()], priorFindings: latestFindings?.findings ?? [], unreadableFiles };
 }
 
 export function savedReviewHeads(pr: string, root = effectiveInstanceRoot()): string[] {
@@ -1980,23 +2087,28 @@ async function runSelfReviewCliCommandPinned(
     const shouldPersistCapResult = previousRoundCount >= 5 && !opts.reviewerMixPrimaryLane;
     const reason = opts.overCapReason?.trim();
     const authorization = previousRoundCount >= 5 ? readCapOverride(pr) : undefined;
+    const capPreflightHead = previousRoundCount >= 5 ? prHeadCommit(pr, deps).value.toLowerCase() : undefined;
     deps.observeDoctorReview?.('round-counted', { pr, previousRoundCount, round: previousRoundCount + 1 });
     const opAllowed = previousRoundCount >= 5 && opAllowsReviewOverCap(pr);
     if (previousRoundCount >= 5) {
       deps.observeDoctorReview?.('cap-attempt', { pr, previousRoundCount, round: previousRoundCount + 1, reasonProvided: Boolean(reason), opAllowed }, { level: 'warn' });
     }
     if (previousRoundCount >= 5 && (!opAllowed || (!authorization && !reason && !opts.reviewerMixCapClaimed))) {
-      const refusalHead = prHeadCommit(pr, deps).value;
+      const refusalHead = capPreflightHead ?? prHeadCommit(pr, deps).value;
+      if (COMMIT_OID.test(refusalHead)) writeReviewLoopBreakerLock(pr, refusalHead, 'review-cap-exceeded');
       const message = !opAllowed
         ? `PR ${pr}: r5 상한 초과 리뷰는 OP traffic.json reviewOverCapAllow 허용 목록에 있어야 합니다.`
         : `PR ${pr}: 저장된 서로 다른 head 리뷰 ${previousRoundCount}개로 r5 상한에 도달했습니다. OP 허용 상태와 --over-cap-reason <사유>가 필요합니다.`;
-      deps.observeDoctorReview?.('cap-refused', { pr, head: refusalHead, previousRoundCount, round: previousRoundCount + 1, reason: opAllowed ? 'missing-reason' : 'not-op-allowlisted' }, { level: 'warn' });
+      deps.observeDoctorReview?.('cap-refused', { pr, head: refusalHead, previousRoundCount, round: previousRoundCount + 1,
+        reason: opAllowed ? 'missing-reason' : 'not-op-allowlisted' }, { level: 'warn' });
+      deps.log('review.loop-breaker', { pr, head: refusalHead, state: 'waiver-needed', reason: 'review-cap-exceeded', previousRoundCount }, { level: 'warn' });
       if (opts.sinceReview !== undefined) deps.log('review.delta-heal', {
         pr, cause: 'cap-refused', prescription: 'retain-explicit-refusal', result: 'refused', headCommit: refusalHead,
       }, { level: 'warn' });
       deps.error(message);
-      if (opts.json || opts.save !== undefined) results.push({ pr, error: message, reviewed: false, refusal: 'cap-refused',
-        ...(opts.sinceReview !== undefined ? { verdict: null, deltaOutcome: 'refused', deltaRefusal: 'cap-refused' } : {}),
+      if (opts.json || opts.save !== undefined) results.push({ pr, error: message, reviewed: false, refusal: 'waiver-needed', failureReason: 'waiver-needed',
+        loopBreaker: { state: 'waiver-needed', reason: 'review-cap-exceeded' },
+        ...(opts.sinceReview !== undefined ? { verdict: null, deltaOutcome: 'refused', deltaRefusal: 'waiver-needed' } : {}),
         previousRoundCount, headCommit: refusalHead });
       failed += 1;
       continue;
@@ -2042,6 +2154,17 @@ async function runSelfReviewCliCommandPinned(
       continue;
     }
     const diffRead = diffResult.read;
+    const loopLock = readReviewLoopBreakerLock(pr);
+    if (loopLock) {
+      const message = `PR ${pr}: 반복 리뷰 중단 (${String(loopLock.reason ?? 'waiver-needed')}); OP 웨이버가 필요합니다.`;
+      deps.observeDoctorReview?.('loop-breaker', { pr, head: diffRead.headCommit, state: 'waiver-needed', reason: loopLock.reason }, { level: 'warn' });
+      deps.log('review.loop-breaker', { pr, head: diffRead.headCommit, state: 'waiver-needed', reason: loopLock.reason }, { level: 'warn' });
+      if (opts.json || opts.save !== undefined) results.push({ pr, error: message, reviewed: false, verdict: null,
+        refusal: 'waiver-needed', failureReason: 'waiver-needed', loopBreaker: { state: 'waiver-needed', reason: loopLock.reason }, headCommit: diffRead.headCommit });
+      else deps.error(message);
+      failed += 1;
+      continue;
+    }
     const canonicalResultPath = COMMIT_OID.test(diffRead.headCommit)
       ? join(effectiveInstanceRoot(), 'review-results', `pr-${pr}-${diffRead.headCommit.slice(0, 12)}.json`)
       : undefined;
@@ -2073,7 +2196,8 @@ async function runSelfReviewCliCommandPinned(
       failed += 1;
       continue;
     }
-    if (previousRoundCount >= 5 && authorization && diffRead.headCommit.toLowerCase() === authorization.head && !opts.reviewerMixCapClaimed) {
+    if (previousRoundCount >= 5 && authorization && diffRead.headCommit.toLowerCase() === authorization.head
+      && !opts.reviewerMixCapClaimed) {
       const resultExists = canonicalResultPath && existsSync(canonicalResultPath);
       const message = resultExists
         ? `PR ${pr}: 동일 head 리뷰 결과가 이미 저장되어 있습니다: ${canonicalResultPath}`
@@ -2169,7 +2293,8 @@ async function runSelfReviewCliCommandPinned(
       diffRead.diff = delta;
       diffRead.baseCommit = mergeOnlyDeltaRange.base;
     }
-    if (previousRoundCount >= 5 && authorization && !opts.reviewerMixCapClaimed && !claimCapOverride(pr, diffRead.headCommit, authorization.reason, deps.now())) {
+    if (previousRoundCount >= 5 && authorization && !opts.reviewerMixCapClaimed
+      && !claimCapOverride(pr, diffRead.headCommit, authorization.reason, deps.now())) {
       const message = `PR ${pr}: 후속 head 승인 사용 기록을 남기지 못했습니다.`;
       deps.error(message);
       if (opts.json || opts.save !== undefined) results.push({ pr, error: message, reviewed: false, refusal: 'cap-refused', previousRoundCount, headCommit: diffRead.headCommit });
@@ -2554,6 +2679,9 @@ async function runSelfReviewCliCommandPinned(
     }
     const reviewDurationMs = Math.max(0, deps.now() - startedAt);
     let deltaReceipt: Record<string, unknown> = {};
+    let deltaFindingsForLoop: Array<{ finding: string; status: 'fixed' | 'open' }> = [];
+    // An unreviewed failure has no loop-breaker assessment; do not report a false `clear` round.
+    let loopBreakerOutput: Record<string, unknown> = {};
     if (deltaBase) {
       const assessed = assessDeltaReview(review, deltaBase);
       const inputRatio = reviewInputChars / deltaBase.reviewInputChars;
@@ -2576,6 +2704,7 @@ async function runSelfReviewCliCommandPinned(
           deltaInputChars: reviewInputChars, deltaDurationMs: reviewDurationMs, deltaEfficiency,
           deltaOutcome: 'refused', deltaRefusal: assessed.reason };
       } else {
+        deltaFindingsForLoop = assessed.deltaFindings;
         review = { ...review, reviewed: true, verdict: assessed.mustFix.length ? 'fail' : 'pass',
           mustFix: assessed.mustFix, shouldFix: [] };
         deltaReceipt = { basedOn: deltaBase.headCommit, basedOnReview: deltaBase.file,
@@ -2583,6 +2712,42 @@ async function runSelfReviewCliCommandPinned(
           deltaInputChars: reviewInputChars, deltaDurationMs: reviewDurationMs, deltaEfficiency, deltaOutcome: 'reviewed' };
       }
     }
+    if (review.reviewed === true) {
+      const loopAssessment = assessReviewLoopBreaker({
+        priorFindings: deltaBase?.mustFix ?? savedEvidence.priorFindings,
+        previouslyFixedFindings: savedEvidence.fixedFindings,
+        deltaFindings: deltaFindingsForLoop,
+        currentFindings: review.mustFix,
+        changedFiles: diffFilePaths(diffRead.diff.stdout),
+      });
+      const priorStreak = trailingStaleReopenRounds(savedEvidence.loopRounds);
+      const nextStreak = loopAssessment.state === 'stale-reopen' ? priorStreak + 1 : 0;
+      const fixedFindings = [...new Map([...savedEvidence.fixedFindings,
+        ...deltaFindingsForLoop.filter((entry) => entry.status === 'fixed').map((entry) => entry.finding)]
+      .map((finding) => [reviewFindingKey(finding).key, finding])).values()];
+      let loopState: 'clear' | 'stale-reopen' | 'waiver-needed' = loopAssessment.state;
+      let loopReason: string | undefined;
+      if (nextStreak >= 2) {
+        loopReason = 'two-consecutive-stale-reopen-rounds';
+        writeReviewLoopBreakerLock(pr, diffRead.headCommit, loopReason);
+        review = { ...review, reviewed: false, verdict: 'fail', failureReason: 'waiver-needed' };
+        loopState = 'waiver-needed';
+        if (deltaBase) deltaReceipt = { ...deltaReceipt, deltaOutcome: 'refused', deltaRefusal: 'waiver-needed' };
+      }
+      loopBreakerOutput = { loopBreaker: { state: loopState, fixedFindings,
+        ...(loopReason ? { reason: loopReason } : {}),
+        ...(loopAssessment.staleFindings.length ? { staleFindings: loopAssessment.staleFindings } : {}),
+        staleReopenRounds: nextStreak } };
+      if (loopState !== 'clear' || deltaBase || fixedFindings.length) {
+        deps.observeDoctorReview?.('loop-breaker', { pr, head: diffRead.headCommit, state: loopState,
+          ...(loopReason ? { reason: loopReason } : {}), staleReopenRounds: nextStreak,
+          staleFindingCount: loopAssessment.staleFindings.length });
+        deps.log('review.loop-breaker', { pr, head: diffRead.headCommit, state: loopState,
+          ...(loopReason ? { reason: loopReason } : {}), staleReopenRounds: nextStreak,
+          staleFindingCount: loopAssessment.staleFindings.length },
+        { level: loopState === 'clear' ? 'info' : 'warn' });
+      }
+    }
     reviewPin?.remove();
     // reviewCwdCommit 은 «최종 판정을 낸 LLM 이 실제로 그 cwd 를 받았을 때만» 싣는다(role 실패 → API 폴백이면 안 싣는다).
     const reviewedOnPin = Boolean(reviewPin) && (roleReview ? rolePinned : reviewRoute === 'acp-fallback' ? true : reviewRoute === 'acp' && useAcp);
@@ -2727,7 +2892,7 @@ async function runSelfReviewCliCommandPinned(
       ...(deltaBase ? {} : { deltaOutcome: review.reviewed === true && landingGateAdmitted ? 'healed-full-review' : 'refused' }),
       deltaHeal: { ...deltaHeal, result: deltaHealResult },
     } : {};
-    const resultOutput = { pr, model: selectedModel, ...jsonReview, reviewInputChars, reviewDurationMs,
+    const resultOutput = { pr, model: selectedModel, ...jsonReview, ...loopBreakerOutput, reviewInputChars, reviewDurationMs,
       ...(deltaBase ? deltaReceipt : {}), ...deltaHealOutput, ...reviewProvenance, ...respondedOutput, ...reviewerSelection,
       ...reviewCwdOutput, ...provenance, ...contextOutput, ...refusalOverride, ...landingGateFields,
       findingPathHeadChecks, pathWarnings, evidence: evidence.evidence, prDiffFiles: evidence.prDiffFiles,

package/src/agents/general-purpose.md

@@ -8,7 +8,7 @@ You are a sub-agent spawned by a parent task. The parent has delegated a focused
 
 ## What you have
 - A task description (the `prompt` argument the parent sent)
-- Full tool access: Bash, Read, Edit, Grep, WebFetch
+- Use the exact tool catalog supplied to this child. Standard CLI defaults are Bash, Read, Edit, Grep, and WebFetch; the TUI may provide a wider policy-filtered catalog.
 - Your own context window — what you read here does not pollute the parent's
 
 ## What you owe back