elanous 0.2.19 → 0.2.20

package/src/self-dev/pr-preview.ts

@@ -8,6 +8,8 @@ export interface PreviewOptions {
   scenario?: string;
   /** Main-based combined preview: only existing config paths may be enabled. */
   flags?: readonly string[];
+  /** PR heads to preview together on main when no feature flags exist. */
+  bundlePrs?: readonly number[];
   commentPr?: number;
 }
 export interface PreviewResult {
@@ -35,14 +37,50 @@ export interface PreviewDeps {
   probePwa?: (url: string) => Promise<boolean>;
 }
 
-const SCENARIOS: Record<string, string> = {
-  S2: '/help', S3: '/status', S6: '/now', S7: '/term list', S8: '/model', S9: '/harness',
+const SCENARIOS: Record<string, { input: string; expected: string; matches: (snapshot: string) => boolean }> = {
+  // GOODHART (#24844 review): a group head (`▸ 시작`) or the echoed `/help` is not the list. The /help modal
+  // (help-from-registry.ts) prints one `/name  description` row per command; the «시작» group alone has six.
+  // Pass only when at least three other start-group commands are listed as rows.
+  S2: { input: '/help', expected: 'help command list (/status, /model, /clear ... rows)', matches: (s) =>
+    ['status', 'model', 'clear', 'new', 'resume'].filter((name) => new RegExp(`(?:^|\\s)/${name}(?: \\([^)]*\\))?\\s{2,}\\S`, 'mu').test(s)).length >= 3 },
+  S3: { input: '/status', expected: 'model and connection', matches: (s) => /모델|model/iu.test(s) && /연결|connection/iu.test(s) },
+  S6: { input: '/now', expected: 'current runs or schedules', matches: (s) => /지금|도는 런|스케줄|running|schedule/iu.test(s) },
+  S7: { input: '/term list', expected: 'terminal/PTY list', matches: (s) => /terminal|pty|터미널/iu.test(s) },
+  S8: { input: '/model', expected: 'model choices', matches: (s) => /빠름|보통|깊음|terra|sol|luna|선택/iu.test(s) },
+  S9: { input: '/harness', expected: 'harness usage or stages', matches: (s) => /usage:.*harness|저작|구현|리뷰|착지/iu.test(s) },
 };
 
+/**
+ * Lines of `after` that were not already on `before`'s screen (multiset by line, trailing spaces ignored).
+ * A prefix check is not enough: the PTY re-renders and scrolls, so the previous scenario's answer can
+ * reappear anywhere on the next screen (#24844 review). A repeated line is conservatively treated as old.
+ */
+export function previewFreshLines(before: string, after: string): string {
+  const seen = new Map<string, number>();
+  for (const line of before.split('\n')) {
+    const key = line.trimEnd();
+    if (key) seen.set(key, (seen.get(key) ?? 0) + 1);
+  }
+  return after.split('\n').filter((line) => {
+    const key = line.trimEnd();
+    if (!key) return false;
+    const left = seen.get(key) ?? 0;
+    if (left > 0) { seen.set(key, left - 1); return false; }
+    return true;
+  }).join('\n');
+}
+
+/** Whether a fresh screen region shows the scenario's expected answer (exported for the preview tests). */
+export function previewScenarioMatches(scenario: string, fresh: string): boolean {
+  const entry = Object.hasOwn(SCENARIOS, scenario) ? SCENARIOS[scenario] : undefined;
+  if (!entry) throw new Error(`TUI-COMFORT §4: unsupported scenario ${scenario}`);
+  return entry.matches(fresh);
+}
+
 export function previewScenarioInput(scenario: string): string {
   const text = Object.hasOwn(SCENARIOS, scenario) ? SCENARIOS[scenario] : undefined;
   if (!text) throw new Error(`TUI-COMFORT §4: unsupported scenario ${scenario}; available: ${Object.keys(SCENARIOS).join(', ')}`);
-  return text;
+  return text.input;
 }
 
 const defaultRun: NonNullable<PreviewDeps['run']> = (command, args, cwd, timeoutMs = 120_000) => {
@@ -60,13 +98,18 @@ export async function runPrPreview(options: PreviewOptions, deps: PreviewDeps =
   if (isPr && !Number.isSafeInteger(Number(target))) throw new Error('preview: invalid PR number');
   if (/^\d+$/u.test(target) && !isPr) throw new Error('preview: invalid PR number');
   if (options.commentPr !== undefined && (!Number.isSafeInteger(options.commentPr) || options.commentPr <= 0)) throw new Error('preview: invalid --comment-pr');
+  const bundlePrs = options.bundlePrs ?? [];
+  if (bundlePrs.length && (target !== 'main' || (options.flags?.length ?? 0) > 0)) throw new Error('preview: --bundle-pr requires main without feature flags');
+  if (bundlePrs.length && (new Set(bundlePrs).size !== bundlePrs.length || bundlePrs.some((pr) => !Number.isSafeInteger(pr) || pr <= 0))) throw new Error('preview: invalid or duplicate --bundle-pr');
   if (target === 'main' && options.commentPr === undefined) throw new Error('preview: main ⊕ flags requires --comment-pr <PR number> to publish the result');
   if (isPr && options.commentPr !== undefined && options.commentPr !== Number(target)) throw new Error('preview: --comment-pr must match the target PR');
   const flags = options.flags ?? [];
   if (flags.length && target !== 'main') throw new Error('preview: --flag requires main (main ⊕ feature flags)');
   if (flags.some((flag) => !/^[a-zA-Z][\w-]*(?:\.[a-zA-Z][\w-]*)+$/u.test(flag))) throw new Error('preview: --flag expects an existing dotted config path');
-  const scenario = options.scenario ?? 'S2';
-  const input = previewScenarioInput(scenario);
+  const scenarios = (options.scenario ?? 'S2').split(',').map((id) => id.trim());
+  if (scenarios.length === 0 || new Set(scenarios).size !== scenarios.length) throw new Error('preview: duplicate or empty scenario');
+  for (const id of scenarios) previewScenarioInput(id);
+  const scenario = scenarios.join(',');
   const check = (command: string, args: readonly string[], cwd: string, timeout?: number): string => {
     const r = run(command, args, cwd, timeout);
     if (r.status !== 0) throw new Error(`preview: ${command} ${args.join(' ')} failed: ${(r.stdout + '\n' + r.stderr).slice(-600)}`);
@@ -99,6 +142,16 @@ export async function runPrPreview(options: PreviewOptions, deps: PreviewDeps =
     const pr = JSON.parse(check('gh', ['pr', 'view', String(prNumber), '--json', 'headRefOid,headRefName'], root)) as { headRefOid?: string; headRefName?: string };
     if (pr.headRefName !== target || pr.headRefOid !== head || (branchPrHead !== undefined && branchPrHead !== head)) throw new Error('preview: branch does not match the target PR head; use the PR number');
   }
+  const bundleHeads = bundlePrs.map((number) => {
+    const pr = JSON.parse(check('gh', ['pr', 'view', String(number), '--json', 'number,headRefOid'], root)) as { number?: number; headRefOid?: string };
+    if (pr.number !== number || !/^[0-9a-f]{40}$/iu.test(pr.headRefOid ?? '')) throw new Error(`preview: PR #${number} head is unavailable`);
+    const oid = pr.headRefOid!;
+    if (run('git', ['cat-file', '-e', `${oid}^{commit}`], root).status !== 0) {
+      check('git', ['fetch', '--no-tags', 'origin', `pull/${number}/head`], root, 120_000);
+      if (check('git', ['rev-parse', '--verify', 'FETCH_HEAD^{commit}'], root) !== oid) throw new Error(`preview: PR #${number} head changed while fetching; retry`);
+    }
+    return { number, oid };
+  });
   const directory = (deps.makeDir ?? (() => {
     const previews = join(root, '.elanous-test', 'previews');
     mkdirSync(previews, { recursive: true });
@@ -112,6 +165,11 @@ export async function runPrPreview(options: PreviewOptions, deps: PreviewDeps =
   try {
     check('git', ['worktree', 'add', '--detach', worktree, head], root);
     added = true;
+    for (const { number, oid } of bundleHeads) {
+      const current = JSON.parse(check('gh', ['pr', 'view', String(number), '--json', 'number,headRefOid'], root)) as { number?: number; headRefOid?: string };
+      if (current.number !== number || current.headRefOid !== oid) throw new Error(`preview: PR #${number} head changed while preparing bundle; retry`);
+      check('git', ['-c', 'user.name=elanous-preview', '-c', 'user.email=preview@localhost', 'merge', '--no-ff', '--no-edit', oid], worktree, 120_000);
+    }
     check('bun', ['install', '--frozen-lockfile'], worktree, 300_000);
     check('bun', ['install', '--frozen-lockfile'], join(worktree, 'apps/pwa'), 300_000);
     for (const flag of flags) {
@@ -145,17 +203,27 @@ export async function runPrPreview(options: PreviewOptions, deps: PreviewDeps =
     if (pty.held !== true || !/^pty_[\w-]+$/u.test(pty.ptyId ?? '')) throw new Error('preview: B-1 held TUI did not return a PTY reference');
     heldPty = pty.ptyId;
     const snapshotArgs = ['bin/elanous.mjs', '--test', 'pty', 'snapshot', pty.ptyId!] as const;
-    const before = check('bun', snapshotArgs, worktree);
-    check('bun', ['bin/elanous.mjs', '--test', 'pty', 'text', pty.ptyId!, input, '--enter'], worktree);
-    // A constant sleep misses slow frames under load — poll until the screen answers (≤ 20s).
-    let snapshot = '';
-    for (let attempt = 0; attempt < 20; attempt++) {
-      await wait(1000);
-      snapshot = check('bun', snapshotArgs, worktree);
-      if (snapshot && snapshot !== 'ok' && snapshot !== before) break;
+    const rows: string[] = [];
+    const snapshots: string[] = [];
+    for (const id of scenarios) {
+      const { input, expected, matches } = SCENARIOS[id]!;
+      const before = check('bun', snapshotArgs, worktree);
+      check('bun', ['bin/elanous.mjs', '--test', 'pty', 'text', pty.ptyId!, input, '--enter'], worktree);
+      // A constant sleep misses slow frames under load — poll until this scenario's expected response (≤ 20s).
+      let snapshot = '';
+      let matched = false;
+      for (let attempt = 0; attempt < 20; attempt++) {
+        await wait(1000);
+        snapshot = check('bun', snapshotArgs, worktree);
+        const fresh = previewFreshLines(before, snapshot);
+        matched = snapshot !== 'ok' && snapshot !== before && matches(fresh);
+        if (matched) break;
+      }
+      const observed = snapshot && snapshot !== 'ok' && snapshot !== before;
+      rows.push(`| TUI-COMFORT §4 ${id} | \`${input}\` → ${matched ? `expected ${expected} matched` : `friction: expected ${expected} not found${observed ? '' : ' (no response within 20s)'}`} |`);
+      snapshots.push(`<details><summary>Inner PTY snapshot ${id}</summary>\n\n\`\`\`text\n${snapshot.slice(-3000).replaceAll('```', "'''")}\n\`\`\`\n</details>`);
     }
-    if (!snapshot || snapshot === 'ok' || snapshot === before) throw new Error('preview: inner PTY did not show a response to the scenario input within 20s');
-    report = `| Check | Observation |\n|---|---|\n| head | \`${head}\` |\n| B-1 version | ${version.slice(0, 120)} |\n| P-1 PWA | \`${endpoint}/app/\` served the built PWA |\n| TUI-COMFORT §4 ${scenario} | \`${input}\` → snapshot captured |\n\n<details><summary>Inner PTY snapshot</summary>\n\n\`\`\`text\n${snapshot.slice(-3000).replaceAll('```', "'''")}\n\`\`\`\n</details>`;
+    report = `| Check | Observation |\n|---|---|\n| head | \`${head}\` |${bundleHeads.length ? `\n| bundled PR heads | ${bundleHeads.map(({ number, oid }) => `#${number} \`${oid}\``).join(' ⊕ ')} |` : ''}\n| B-1 version | ${version.slice(0, 120)} |\n| P-1 PWA | \`${endpoint}/app/\` served the built PWA |\n${rows.join('\n')}\n\n${snapshots.join('\n\n')}`;
   } catch (error) {
     report = `| Check | Friction |\n|---|---|\n| head | \`${head}\` |\n| TUI-COMFORT §4 ${scenario} | ${String(error).replaceAll('|', '\\|').slice(0, 700)} |`;
   } finally {
@@ -167,7 +235,7 @@ export async function runPrPreview(options: PreviewOptions, deps: PreviewDeps =
     }
     (deps.dispose ?? ((dir) => rmSync(dir, { recursive: true, force: true })))(directory);
   }
-  const status = report.includes('| Friction |') ? 'friction' : 'passed';
+  const status = report.includes('| Friction |') || report.includes('→ friction:') ? 'friction' : 'passed';
   const body = `## PR preview — ${target} (${status})\n\n${report}`;
   if (prNumber === undefined) throw new Error('preview: cannot comment without a PR number');
   check('gh', ['pr', 'comment', String(prNumber), '--body', body], root);

package/src/self-implement/blocked-draft-policy.ts

@@ -1,6 +1,107 @@
+import type { AbandonedClassification } from './abandoned-classification.js';
+
 /** Environment interruptions have a resumable branch, not a human draft decision. */
 export function blockedDraftDisposition(classification: string | undefined): 'open-draft' | 'preserve-branch' {
   return classification === 'provider-error' || classification === 'quota-exhausted' || classification === 'credential-failure'
     ? 'preserve-branch'
     : 'open-draft';
 }
+
+/**
+ * DRAFT-NOT-ARCHIVE (RFC-draft-pr-accumulation-root-fix R1 · 첫 조각)
+ *
+ * S: 멈춘 런은 산출을 draft PR 로 남겼다 — PR 이 «실패 보관소»가 되어 열린 PR 이 200 을 넘고 겹침 검사가 눈이 멀었다.
+ * C: 닫힌 147건 중 사람이 실제로 봐야 했던 것은 «주인 자리» 47건뿐이었다.
+ * Q: 어느 멈춤이 PR 을 열 자격이 있나?
+ * A: 사람 판단이 필요한 멈춤(needs-owner)만. 나머지(harvestable)는 수확 가지 `salvage/<run>/<leaf>` ⊕ 런 원장의 «사유 · 다음 수»로 남긴다.
+ *    `tools.selfImplement.draftOnStop` = 'always'(기본 · 종전) | 'needs-owner-only'.
+ */
+export type DraftOnStopMode = 'needs-owner-only' | 'always';
+export const DRAFT_ON_STOP_MODES = ['needs-owner-only', 'always'] as const satisfies readonly DraftOnStopMode[];
+export const DEFAULT_DRAFT_ON_STOP: DraftOnStopMode = 'always';
+
+/** landable = 승인된 산출(merge-approved-abandoned) — 다음 수가 `pr land` 이므로 수확 가지로 숨기지 않고 PR 로 남긴다(⛔ needs-owner 라벨은 안 단다). */
+export type StopClass = 'needs-owner' | 'harvestable' | 'landable';
+
+const LANDABLE: ReadonlySet<string> = new Set<AbandonedClassification>(['merge-approved-abandoned']);
+
+/** 사람(주인 자리)이 골·계약·처분을 정해야 풀리는 멈춤. 모르는 분류는 «needs-owner» 쪽으로 기운다(⛔ 산출을 PR 밖으로 숨기지 않는다). */
+const NEEDS_OWNER: ReadonlySet<string> = new Set<AbandonedClassification>([
+  'contract-conflict',
+  'goal-unconvergeable-candidate',
+  'pr-declined',
+]);
+
+const HARVESTABLE: ReadonlySet<string> = new Set<AbandonedClassification>([
+  'implementation-deficit',
+  'report-deficit',
+  'artifact-deficit',
+  'run-deadline-exceeded',
+  'already-satisfied',
+  'quota-exhausted',
+  'provider-error',
+  'credential-failure',
+]);
+
+export function stopClassFor(classification: string | undefined): StopClass {
+  if (classification && NEEDS_OWNER.has(classification)) return 'needs-owner';
+  if (classification && LANDABLE.has(classification)) return 'landable';
+  if (classification && HARVESTABLE.has(classification)) return 'harvestable';
+  return 'needs-owner';
+}
+
+const NEXT_MOVE: Record<string, string> = {
+  'implementation-deficit': '수확 가지에서 같은 골을 이어 돌린다(resume 1회) — 그래도 멈추면 needs-owner',
+  'report-deficit': '수확 가지에서 완료 증거·보고를 보강해 다시 게이트에 올린다',
+  'artifact-deficit': '수확 가지에서 요구 산출물을 채워 다시 돌린다',
+  'run-deadline-exceeded': '수확 가지에서 이어 돌리거나, 산출이 작으면 골을 쪼개 재발사한다',
+  'merge-approved-abandoned': '승인된 산출이다 — 이 PR 을 착지 경로(pr land)로 올린다',
+  'already-satisfied': '고칠 것이 없다 — 재발사하지 말고 카드를 닫는다',
+  'quota-exhausted': '용량 회복 뒤 수확 가지에서 이어 돌린다',
+  'provider-error': 'provider 복구 뒤 수확 가지에서 이어 돌린다',
+  'credential-failure': '인증 복구 뒤 수확 가지에서 이어 돌린다',
+  'contract-conflict': '주인 자리가 골의 상충 기준을 정정한다',
+  'goal-unconvergeable-candidate': '주인 자리가 되풀이된 must-fix 와 골 계약을 대조해 골을 다시 쓰거나 쪼갠다',
+  'pr-declined': '주인 자리가 거절 사유를 반영할지 골을 다시 정할지 정한다',
+};
+
+export function nextMoveFor(classification: string | undefined): string {
+  return (classification && NEXT_MOVE[classification]) ?? '주인 자리가 중단 사유를 읽고 처분을 정한다(분류 못 함)';
+}
+
+export type DraftOnStopDecision =
+  | { action: 'open-draft'; stopClass: StopClass; mode: DraftOnStopMode; ownerLabel?: string }
+  | { action: 'salvage-branch'; stopClass: 'harvestable'; mode: 'needs-owner-only' };
+
+/** 'always' 는 종전 그대로(라벨도 그대로). 'needs-owner-only' 는 harvestable → 수확 가지 · needs-owner·landable → draft ⊕ 주인 자리 라벨.
+ *  ⛔ 자리를 모르면 자리 라벨을 «안 단다»(OP 로 추측해 달면 «안다»고 말하는 셈이다) — `elanous:needs-owner` 만 남는다. */
+export function decideDraftOnStop(input: { mode: DraftOnStopMode; classification: string | undefined; seat?: string }): DraftOnStopDecision {
+  const stopClass = stopClassFor(input.classification);
+  if (input.mode !== 'needs-owner-only') return { action: 'open-draft', stopClass, mode: 'always' };
+  if (stopClass === 'harvestable') return { action: 'salvage-branch', stopClass, mode: 'needs-owner-only' };
+  const ownerLabel = ownerSeatLabel(input.seat);
+  return { action: 'open-draft', stopClass, mode: 'needs-owner-only', ...(ownerLabel ? { ownerLabel } : {}) };
+}
+
+const SEATS = ['OP', 'TC', 'MK', 'UX'] as const;
+
+/** 주인 자리 라벨 — `helper-repair` 가 읽는 `elanous:seat-<자리>` 꼴. 아는 자리일 때만 낸다(모르면 undefined). */
+export function ownerSeatLabel(seat: string | undefined): string | undefined {
+  const trimmed = seat?.trim().toUpperCase();
+  return trimmed && (SEATS as readonly string[]).includes(trimmed) ? `elanous:seat-${trimmed}` : undefined;
+}
+
+/** 런 하나의 수확 가지 — `salvage/run-<6hex>/<가지 잎>`. 잎이 `-r<6hex>` 로 끝나면 `selectRunSalvageRefs` 가 그대로 찾는다. */
+export function salvageBranchForRun(runId: string, branch: string): string {
+  // `salvage-branches.ts` `runSuffixKey` 와 같은 규칙 — 그 모듈은 실행 러너를 끌고 와 user-config 가 부를 수 없다.
+  const key = /^(?:run-)?([0-9a-f]{6})/i.exec(runId.trim())?.[1]?.toLowerCase();
+  const runShort = key ? `run-${key}` : (runId.replace(/[^A-Za-z0-9_-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 24) || 'run-unknown');
+  const leaf = branch.replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^[-.]+|[-.]+$/g, '').replace(/\.\.+/g, '.').replace(/\.lock$/i, '-lock') || 'branch';
+  return `salvage/${runShort}/${leaf}`;
+}
+
+export function parseDraftOnStopMode(raw: unknown): { mode: DraftOnStopMode; invalid: boolean } {
+  if (raw === undefined) return { mode: DEFAULT_DRAFT_ON_STOP, invalid: false };
+  if (typeof raw === 'string' && (DRAFT_ON_STOP_MODES as readonly string[]).includes(raw)) return { mode: raw as DraftOnStopMode, invalid: false };
+  return { mode: DEFAULT_DRAFT_ON_STOP, invalid: true };
+}

package/src/self-implement/execution-clarification.ts

@@ -15,6 +15,10 @@ import { appendRunLedgerEntry, type RunLedgerWriter } from './run-ledger.js';
 
 export interface ExecutionClarificationContext {
   runId: string;
+  outsideFiles?: readonly string[];
+  /** Full outside count — when larger than `outsideFiles`, the card says how many names it does not show. */
+  outsideCount?: number;
+  declaredPaths?: readonly string[];
   budget?: ClarificationContext['budget'];
   pendingQuestionCount?: number;
   config?: { hitl?: { executionDeadlineMinutes?: number } };
@@ -71,6 +75,13 @@ export async function askAtExecution(
 
   const request = toAskUserQuestionRequest(decision);
   if (!request) throw new Error('Execution clarification policy approved a question without a valid wire request.');
+  if (candidate.id === 'execution_scope' && ctx.outsideFiles) {
+    const sibling = (file: string) => ctx.declaredPaths === undefined ? 'unknown'
+      : file.endsWith('.test.ts') && ctx.declaredPaths.includes(file.replace(/\.test\.ts$/, '.ts')) ? 'yes' : 'no';
+    const hidden = Math.max(0, (ctx.outsideCount ?? ctx.outsideFiles.length) - ctx.outsideFiles.length);
+    const details = `Run ID: ${ctx.runId}\nOutside files:\n${ctx.outsideFiles.map(file => `- ${file} (declared-path sibling test: ${sibling(file)})`).join('\n')}${hidden > 0 ? `\n- … ${hidden} more outside file(s) not shown — inspect the worktree diff before expanding scope` : ''}`;
+    for (const question of request.questions) question.question += `\n\n${details}`;
+  }
   const configured = ctx.config === undefined
     ? getUserConfig().hitl?.executionDeadlineMinutes
     : ctx.config.hitl?.executionDeadlineMinutes;

package/src/self-implement/gate-env-retry.ts

@@ -0,0 +1,83 @@
+// ── GATE-ENV-RETRY (0.2.20 P1) — 환경 결손 gate 실패는 «게이트만» 다시 돈다 ─────────────
+//
+// S: 하니스 후반 gate 가 «환경 결손»(시험 결과 미수신 · git index.lock 경합 · tsc 힙 OOM ·
+//    「측정 불가」 · 네트워크/레지스트리 타임아웃)을 자식 실패와 같은 칸으로 받아,
+//    재작업 없이 `abandoned` 로 런을 끝냈다.
+// C: 📏 10-06 — TASK-AGENT 런 PR #24438 «test-result-unavailable · escalating without rework» ·
+//    NESTEDGUARD3 baseline index.lock 경합 · tsc 힙 OOM «could not measure».
+//    구현은 멀쩡한데 «잰 쪽»이 넘어졌고, 그 구현이 버려진 칸으로 셌다.
+// Q: 구현을 버리지 않고 잴 수 있나?
+// A: ⓐ 이 판정자가 «환경 결손»이라 말하면 짧게 쉬고 gate «만» 다시 돈다(기본 2회).
+//    ⓑ 그래도 결손이면 브랜치·PR 을 남기고 `harvestable` 로 끝낸다(「버림」이 아니라 「수확 대기」).
+//
+// ⛔ 틀리는 방향이 비대칭이다(`self-dev/execution-transient.ts` 와 같은 계산):
+//    도입 실패를 「환경」으로 부르면 → 자식 결손이 재작업 없이 수확 칸으로 빠진다.
+//    ⇒ `introduced > 0` 또는 자식 책임이 «있음»이면 무조건 거짓. 어휘는 좁게 둔다.
+// ⛔ `budget-exceeded`·`module-load-error` 는 넣지 않는다 — 다시 재도 같은 값이 나온다.
+
+/** 환경 결손의 종류 — 관측(로그)과 PR 문면에 그대로 실린다. */
+export type GateEnvDeficitKind =
+  | 'test-result-unavailable'
+  | 'infrastructure-failure'
+  | 'git-lock'
+  | 'out-of-memory'
+  | 'unmeasured'
+  | 'network-timeout';
+
+export type GateEnvDeficitVerdict =
+  | { readonly envDeficit: true; readonly kind: GateEnvDeficitKind }
+  | { readonly envDeficit: false; readonly reason: 'passed' | 'introduced' | 'child-responsible' | 'non-retryable-reason' | 'no-env-signal' };
+
+export interface GateEnvDeficitInput {
+  readonly passed: boolean;
+  readonly log?: string;
+  readonly reflectGateFacts?: {
+    readonly introduced?: number;
+    readonly unknownReason?: string;
+    readonly childResponsibility?: string;
+  };
+}
+
+/** unknownReason 중 «다시 재면 풀릴 수 있는» 것만. */
+const RETRYABLE_UNKNOWN_REASONS: ReadonlySet<string> = new Set(['test-result-unavailable', 'infrastructure-failure']);
+
+/** unknownReason 중 «다시 재도 같은 값이 나오는» 것 — 로그에 환경 어휘가 섞여 있어도 이 사유가 이긴다. */
+const NON_RETRYABLE_UNKNOWN_REASONS: ReadonlySet<string> = new Set(['budget-exceeded', 'module-load-error']);
+
+/** 로그 어휘 — ⛔ 좁게(위 비대칭). 순서가 곧 우선순위. */
+const LOG_PATTERNS: ReadonlyArray<readonly [GateEnvDeficitKind, RegExp]> = [
+  ['git-lock', /index\.lock|another git process seems to be running|cannot lock ref/i],
+  ['out-of-memory', /javascript heap out of memory|heap out of memory|oomkilled|fatal error: .*allocation failed/i],
+  ['unmeasured', /could not measure|측정 불가/i],
+  ['network-timeout', /\b(?:ETIMEDOUT|ECONNRESET|EAI_AGAIN|ENOTFOUND)\b|registry\.npmjs\.org.*(?:timeout|timed out)|network timeout|socket hang up/i],
+];
+
+/**
+ * 순수: 실패한 gate 결과가 «환경 결손»인가를 판정한다.
+ * ⛔ 도입 실패(`introduced > 0`)·자식 책임 있음은 언제나 거짓 — 그 동작은 바꾸지 않는다.
+ */
+export function classifyGateEnvDeficit(gate: GateEnvDeficitInput): GateEnvDeficitVerdict {
+  if (gate.passed) return { envDeficit: false, reason: 'passed' };
+  const facts = gate.reflectGateFacts;
+  if ((facts?.introduced ?? 0) > 0) return { envDeficit: false, reason: 'introduced' };
+  if (facts?.childResponsibility !== undefined && facts.childResponsibility !== 'none') {
+    return { envDeficit: false, reason: 'child-responsible' };
+  }
+  if (facts?.unknownReason !== undefined && NON_RETRYABLE_UNKNOWN_REASONS.has(facts.unknownReason)) {
+    return { envDeficit: false, reason: 'non-retryable-reason' };
+  }
+  if (facts?.unknownReason !== undefined && RETRYABLE_UNKNOWN_REASONS.has(facts.unknownReason)) {
+    return { envDeficit: true, kind: facts.unknownReason as GateEnvDeficitKind };
+  }
+  const log = gate.log ?? '';
+  for (const [kind, pattern] of LOG_PATTERNS) {
+    if (pattern.test(log)) return { envDeficit: true, kind };
+  }
+  return { envDeficit: false, reason: 'no-env-signal' };
+}
+
+/** 기본 재시도 정책 — 짧게 쉬고 gate 만 최대 2회. */
+export const DEFAULT_GATE_ENV_RETRY = { attempts: 2, delayMs: 20_000 } as const;
+
+/** 수확 대기로 남길 때 PR·종료 사유에 싣는 표지. */
+export const GATE_ENV_DEFICIT_HARVESTABLE_MARK = 'env-deficit, harvestable';