elanous 0.2.15 → 0.2.17

package/src/self-implement/app-api-budget.ts

@@ -0,0 +1,166 @@
+import { execFile as execFileCb } from 'node:child_process';
+import { promisify } from 'node:util';
+import { debug } from '../debug/log.js';
+import { releaseGitDiffPaths, releasePrFilePaths } from '../self-dev/release-path-guard.js';
+
+const defaultExecFile = promisify(execFileCb);
+const GIT_TIMEOUT = 20_000;
+
+export type AppApiExecFile = (
+  file: string,
+  args: readonly string[],
+  opts: { cwd: string; encoding: 'utf8'; timeout: number; maxBuffer?: number; env?: NodeJS.ProcessEnv },
+) => Promise<{ stdout: string; stderr?: string }>;
+
+let execFileImpl: AppApiExecFile = (file, args, opts) => defaultExecFile(file, [...args], opts);
+
+/** Tests inject the `gh` runner. Production keeps `execFile`. */
+export function setAppApiExecFileForTest(impl: AppApiExecFile | undefined): void {
+  execFileImpl = impl ?? ((file, args, opts) => defaultExecFile(file, [...args], opts));
+}
+
+/** App-token `gh` calls only. Caller names are fixed strings; the token value is never logged. */
+const GH_APP_CALLERS = {
+  'post-pr-comment-history': 'postPrComment',
+  'post-pr-comment': 'postPrComment',
+  'find-pr-comment': 'findPrComment',
+  'edit-pr-comment': 'editPrComment',
+  'add-pr-label-list': 'addPrLabel',
+  'add-pr-label-create': 'addPrLabel',
+  'add-pr-label': 'addPrLabel',
+  'read-pr-files': 'readPrFiles',
+} as const;
+
+export type GhAppCaller = keyof typeof GH_APP_CALLERS;
+
+export const APP_API_RATE_LIMIT_RETRY_CAP_MS = 15 * 60_000;
+
+export class AppApiRateLimitError extends Error {
+  readonly rateLimited = true as const;
+  readonly status: 403 | 429;
+  readonly resetAtMs: number | undefined;
+  constructor(message: string, status: 403 | 429, resetAtMs: number | undefined) {
+    super(message);
+    this.name = 'AppApiRateLimitError';
+    this.status = status;
+    this.resetAtMs = resetAtMs;
+  }
+}
+
+export function isAppApiRateLimitFailure(status: number | undefined, text: string, remaining?: string): boolean {
+  if (remaining === '0') return true;
+  if (status !== undefined && status !== 403 && status !== 429) return false;
+  return /API rate limit exceeded|rate limit/i.test(text) && (status === 403 || status === 429 || status === undefined);
+}
+
+function ghHeader(stderr: string, name: string): string | undefined {
+  const match = new RegExp(`^${name}:\\s*(.*)$`, 'im').exec(stderr);
+  return match?.[1]?.trim();
+}
+
+function ghStatusCode(stderr: string, error: unknown): number | undefined {
+  const fromHeader = ghHeader(stderr, 'HTTP') ?? ghHeader(stderr, 'status');
+  const headerCode = fromHeader ? Number.parseInt(fromHeader, 10) : NaN;
+  if (Number.isFinite(headerCode)) return headerCode;
+  const text = `${stderr}\n${error instanceof Error ? error.message : String(error ?? '')}`;
+  const match = /\b(403|429)\b/.exec(text);
+  return match ? Number(match[1]) : undefined;
+}
+
+/** Wait until X-RateLimit-Reset, never longer than 15 minutes. Returns false when the reset is already past or unreadable. */
+export async function waitForAppApiRateLimitReset(
+  resetAtMs: number | undefined,
+  now = Date.now(),
+  sleep: (ms: number) => Promise<void> = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+): Promise<boolean> {
+  if (resetAtMs === undefined || !Number.isFinite(resetAtMs)) return false;
+  const waitMs = Math.min(Math.max(0, resetAtMs - now), APP_API_RATE_LIMIT_RETRY_CAP_MS);
+  if (waitMs <= 0) return false;
+  await sleep(waitMs);
+  return true;
+}
+
+export async function runGhApp(
+  caller: GhAppCaller,
+  args: readonly string[],
+  opts: { cwd: string; encoding: 'utf8'; timeout: number; maxBuffer?: number; env: NodeJS.ProcessEnv },
+): Promise<{ stdout: string; stderr: string }> {
+  let stdout = '';
+  let stderr = '';
+  let status: number | undefined;
+  let error: unknown;
+  try {
+    const result = await execFileImpl('gh', args, opts);
+    stdout = result.stdout;
+    stderr = result.stderr ?? '';
+    status = 200;
+  } catch (caught) {
+    error = caught;
+    const failed = caught as { stdout?: string; stderr?: string };
+    stdout = typeof failed.stdout === 'string' ? failed.stdout : '';
+    stderr = typeof failed.stderr === 'string' ? failed.stderr : '';
+    status = ghStatusCode(stderr, caught);
+  }
+  const remaining = ghHeader(stderr, 'X-RateLimit-Remaining');
+  debug.log('github.app-api', 'call', {
+    caller: GH_APP_CALLERS[caller],
+    endpoint: args.filter((arg) => !arg.startsWith('-')).at(-1) ?? 'gh',
+    status: status ?? 0,
+    remaining: remaining ?? '',
+  });
+  if (error) {
+    const text = `${stderr}\n${error instanceof Error ? error.message : String(error)}`;
+    if (isAppApiRateLimitFailure(status, text, remaining)) {
+      const reset = ghHeader(stderr, 'X-RateLimit-Reset');
+      const resetSeconds = reset ? Number(reset) : NaN;
+      throw new AppApiRateLimitError(
+        text.trim() || 'API rate limit exceeded',
+        status === 429 ? 429 : 403,
+        Number.isFinite(resetSeconds) ? resetSeconds * 1000 : undefined,
+      );
+    }
+    throw error;
+  }
+  return { stdout, stderr };
+}
+
+export async function readPrFilesWithRateLimitFallback(input: {
+  number: number;
+  cwd: string;
+  base?: string;
+  env: NodeJS.ProcessEnv;
+  sleep?: (ms: number) => Promise<void>;
+  now?: () => number;
+}): Promise<string[]> {
+  const env = input.env;
+  const endpoint = [
+    'api', '--paginate', '--slurp', '--method', 'GET', '-f', 'per_page=100',
+    `repos/{owner}/{repo}/pulls/${input.number}/files`,
+  ];
+  const ghOpts = { cwd: input.cwd, encoding: 'utf8' as const, timeout: GIT_TIMEOUT, maxBuffer: 64 * 1024 * 1024, env };
+  const fromApi = async () => releasePrFilePaths(JSON.parse((await runGhApp('read-pr-files', endpoint, ghOpts)).stdout));
+  const fromGit = async (): Promise<string[]> => {
+    const base = input.base ?? 'origin/main';
+    const { stdout } = await execFileImpl('git', ['diff', '--find-renames', '--name-status', '-z', `${base}...HEAD`], {
+      cwd: input.cwd, encoding: 'utf8', timeout: GIT_TIMEOUT, maxBuffer: 64 * 1024 * 1024,
+    });
+    return releaseGitDiffPaths(stdout);
+  };
+  try {
+    return await fromApi();
+  } catch (error) {
+    if (!(error instanceof AppApiRateLimitError)) throw error;
+    try {
+      return await fromGit();
+    } catch (gitError) {
+      const waited = await waitForAppApiRateLimitReset(error.resetAtMs, input.now?.() ?? Date.now(), input.sleep);
+      if (!waited) throw error;
+      try {
+        return await fromApi();
+      } catch (retryError) {
+        if (retryError instanceof AppApiRateLimitError) throw retryError;
+        throw gitError;
+      }
+    }
+  }
+}

package/src/self-implement/budget-gate.ts

@@ -9,6 +9,7 @@ import type { UsageSnapshot } from '../budget/types.js';
 import { debug } from '../debug/log.js';
 import {
   DEFAULT_BUDGET_GATE_MAX_USED_PERCENT,
+  LAUNCH_GROK_USED_PERCENT_CAP,
   type BudgetGateMaxUsedPercent,
   type BudgetGateOnShortfall,
 } from '../user-config.js';
@@ -137,16 +138,17 @@ function slotUsable(
     return { usable: measuredUsable || unmeasured, reason: formatCodexReason(input.codexCandidates, cap), ...(unmeasured ? { unmeasured: true } : {}) };
   }
   if (provider === GROK_PROVIDER) {
-    const cap = capFor(input.maxUsedPercent, GROK_PROVIDER);
+    const configured = capFor(input.maxUsedPercent, GROK_PROVIDER);
+    // 발사 관문은 `elanous usage` 와 같은 주간 사용률에 80% 상한을 실제로 적용한다.
+    // «못 쟀다»(undefined)는 통과가 아니다. decideBudget 은 설정 상한을 그대로 쓴다.
+    const cap = allowUnmeasured ? LAUNCH_GROK_USED_PERCENT_CAP : configured;
     const known = typeof input.grokUsedPercent === 'number' && Number.isFinite(input.grokUsedPercent);
-    const unmeasured = allowUnmeasured && !known;
-    const usable = unmeasured || (cap === undefined
+    const usable = cap === undefined
       ? known
-      : known && (input.grokUsedPercent as number) < cap);
+      : known && (input.grokUsedPercent as number) < cap;
     return {
       usable,
       reason: formatGrokReason(input.grokUsedPercent, cap),
-      ...(unmeasured ? { unmeasured: true } : {}),
     };
   }
   return { usable: false, reason: `${provider}: 예산 판정 없음` };

package/src/self-implement/follow-up-goals.ts

@@ -0,0 +1,289 @@
+// FOLLOWUP-LOOP① — after a harness PR merges, leftover findings become one
+// follow-up goal draft. Default mode is shadow: record only. `live` also
+// enqueues through the same function as `harness queue add`.
+//
+// The test process injects every store. Nothing here opens the operational
+// ledger or queue unless the caller passes those seams.
+
+import { createHash } from 'node:crypto';
+import { appendFileSync, mkdirSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { addHarnessQueue, type QueueSeat } from '../harness/harness-queue.js';
+import { debug } from '../debug/log.js';
+import { withFileLockSync } from '../storage/file-lock.js';
+import { elanousStateRoot } from '../autopilot/state-paths.js';
+import { devVersion, listChecklist, parseOwner } from '../release-loop/checklist.js';
+import { getUserConfig } from '../user-config.js';
+
+export const FOLLOW_UP_DEPTH_LIMIT = 3;
+export const FOLLOW_UP_OP_CARD_REQUIRED = 'OP 카드 필요';
+
+const REMAINING_SECTION = '남은 조각';
+const SEATS = ['OP', 'TC', 'MK', 'UX'] as const;
+
+export type FollowUpMode = 'shadow' | 'live';
+
+export interface FollowUpDraftRecord {
+  prNumber: number;
+  cellId: string;
+  depth: number;
+  draftHash: string;
+  kind: 'draft' | 'op-card-required';
+  originalAskFirstLine: string;
+  remainings: readonly string[];
+  draft?: string;
+  note?: string;
+  queued: boolean;
+  /** live 대기열 넣기가 실패했을 때의 이유(초안은 그대로 남는다). */
+  enqueueError?: string;
+  seat?: QueueSeat;
+}
+
+export interface FollowUpMergeInput {
+  prNumber: number;
+  /** Result field set when the review budget is exhausted. */
+  followUpMustFix?: readonly string[];
+  /** Last review's non-blocking findings. */
+  shouldFix?: readonly string[];
+  /** Opened PR body — the «남은 조각» section is read verbatim. */
+  prBody?: string;
+  /** Original request. Only its first line enters the draft. */
+  feature: string;
+  /** Release-cell id. Absent means the goal file's GoalId, else the feature's first token. */
+  cellId?: string;
+  goalFile?: string;
+}
+
+export interface FollowUpSeams {
+  stateRoot?: string;
+  mode?: FollowUpMode;
+  /**
+   * Prior follow-up records for this cell, oldest first.
+   * Absent means the caller did not hand over a store — the test process writes nothing.
+   * Production `defaultSeams` always sets this to the state-root ledger.
+   */
+  readDrafts?: (cellId: string) => readonly FollowUpDraftRecord[];
+  appendDraft?: (record: FollowUpDraftRecord) => void;
+  /** Same function `harness queue add` calls. Injected in tests so the real queue is never opened. */
+  enqueue?: (input: { seat: QueueSeat; say: string; idempotencyKey: string }) => Promise<unknown> | unknown;
+  /** Release-cell owner (`TC`, `TC/rel`, …). Absent means look up the developing checklist. */
+  cellOwner?: (cellId: string) => string | undefined;
+  log?: (category: string, event: string, data?: unknown) => void;
+}
+
+export function followUpDraftsPath(stateRoot = elanousStateRoot()): string {
+  return join(stateRoot, 'follow-up', 'drafts.jsonl');
+}
+
+export function readFollowUpMode(read: () => { harness?: { followUp?: unknown } } = getUserConfig): FollowUpMode {
+  return read().harness?.followUp === 'live' ? 'live' : 'shadow';
+}
+
+/** Lines under a markdown heading «남은 조각», verbatim, without the bullet mark. */
+export function remainingPiecesFromPrBody(body: string | undefined): string[] {
+  if (!body) return [];
+  const lines = body.split(/\r?\n/);
+  const start = lines.findIndex((line) => line.trim() === `## ${REMAINING_SECTION}`);
+  if (start < 0) return [];
+  const out: string[] = [];
+  for (const line of lines.slice(start + 1)) {
+    if (/^#{1,6}\s/.test(line)) break;
+    const item = line.match(/^\s*[-*]\s+(.+?)\s*$/)?.[1];
+    if (item) out.push(item);
+  }
+  return out;
+}
+
+export function collectRemainings(input: Pick<FollowUpMergeInput, 'followUpMustFix' | 'shouldFix' | 'prBody'>): string[] {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const item of [
+    ...(input.followUpMustFix ?? []),
+    ...(input.shouldFix ?? []),
+    ...remainingPiecesFromPrBody(input.prBody),
+  ]) {
+    const text = item.trim();
+    if (!text || seen.has(text)) continue;
+    seen.add(text);
+    out.push(text);
+  }
+  return out;
+}
+
+export function followUpCellId(input: Pick<FollowUpMergeInput, 'cellId' | 'goalFile' | 'feature'>, readGoal: (path: string) => string = (path) => readFileSync(path, 'utf8')): string | undefined {
+  const explicit = input.cellId?.trim();
+  if (explicit) return explicit;
+  if (input.goalFile) {
+    try {
+      const goalId = readGoal(input.goalFile).match(/^- GoalId:\s*(\S+)\s*$/m)?.[1];
+      if (goalId) return goalId;
+    } catch { /* a missing goal file is not a cell id */ }
+  }
+  // 자리 발사 머리(`[MK 자리 · 0.2.16 체크리스트 칸 FOLLOWUP-LOOP · …]`)가 칸을 «명시»한 경우만 읽는다.
+  // 추정(요청문 첫 단어)으로는 기록하지 않는다 — 다른 골이 한 칸으로 합쳐져 깊이·담당이 틀린다.
+  // 자리 머리 줄만 본다 — 본문이 다른 칸을 언급해도 그 칸으로 기록하지 않는다.
+  // 저작 Pod 규칙(OP 10-06)에서 첫 줄은 `대상 경로:` 이고 머리는 둘째 줄이라, 앞의 `대상 경로:` 줄 하나는 건너뛴다.
+  const lines = input.feature.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+  const header = /^대상 경로:/u.test(lines[0] ?? '') ? lines[1] : lines[0];
+  return header?.match(/^\[(?:OP|MK|TC|UX) 자리 · [^\]]*?체크리스트 칸 ([A-Z][A-Z0-9-]*[A-Z0-9])(?: ·|\])/u)?.[1];
+}
+
+export function originalAskFirstLine(feature: string): string {
+  return feature.split(/\r?\n/).map((line) => line.trim()).find(Boolean) ?? '';
+}
+
+export function followUpDraftText(firstLine: string, remainings: readonly string[]): string {
+  return [
+    firstLine,
+    ...remainings,
+    'origin/main 에서 시작 · 남은 것만',
+  ].join('\n');
+}
+
+export function followUpDraftHash(text: string): string {
+  return createHash('sha256').update(text).digest('hex').slice(0, 16);
+}
+
+/** Chain length of follow-up goals already recorded for this cell, before this one. */
+export function followUpChainDepth(prior: readonly Pick<FollowUpDraftRecord, 'kind' | 'prNumber'>[]): number {
+  // 한 PR 이 «기록 → 대기열 확정» 두 줄을 남길 수 있으니 PR 번호로 센다.
+  return new Set(prior.filter((record) => record.kind === 'draft' || record.kind === 'op-card-required').map((record) => record.prNumber)).size;
+}
+
+/** Seat = the cell's owner. `TC/rel` keeps the seat `TC`. Unknown or absent owners go to OP (ONEDOOR). */
+export function seatForCellOwner(owner: string | undefined): QueueSeat {
+  if (!owner) return 'OP';
+  try {
+    const seat = parseOwner(owner.trim()).seat;
+    if ((SEATS as readonly string[]).includes(seat)) return seat as QueueSeat;
+  } catch { /* not a seat */ }
+  const head = owner.trim().split(/[/\s·]/)[0] ?? '';
+  return (SEATS as readonly string[]).includes(head) ? head as QueueSeat : 'OP';
+}
+
+function defaultReadDrafts(stateRoot: string, cellId: string): FollowUpDraftRecord[] {
+  let text = '';
+  try { text = readFileSync(followUpDraftsPath(stateRoot), 'utf8'); } catch { return []; }
+  const out: FollowUpDraftRecord[] = [];
+  for (const line of text.split('\n')) {
+    if (!line.trim()) continue;
+    try {
+      const record = JSON.parse(line) as FollowUpDraftRecord;
+      if (record.cellId === cellId) out.push(record);
+    } catch { /* a torn line does not invent a chain */ }
+  }
+  return out;
+}
+
+/** 같은 PR 은 칸과 무관하게 한 번 — 칸 id 가 달리 들어와도 다시 만들지 않는다. */
+function defaultPrRecorded(stateRoot: string, prNumber: number): boolean {
+  let text = '';
+  try { text = readFileSync(followUpDraftsPath(stateRoot), 'utf8'); } catch { return false; }
+  return text.split('\n').some((line) => {
+    if (!line.trim()) return false;
+    try { return (JSON.parse(line) as FollowUpDraftRecord).prNumber === prNumber; } catch { return false; }
+  });
+}
+
+function defaultAppendDraft(stateRoot: string, record: FollowUpDraftRecord): void {
+  const path = followUpDraftsPath(stateRoot);
+  mkdirSync(dirname(path), { recursive: true });
+  appendFileSync(path, `${JSON.stringify(record)}\n`);
+}
+
+function defaultCellOwner(cellId: string): string | undefined {
+  try {
+    return listChecklist(devVersion()).items.find((item) => item.id === cellId)?.owner;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Record one follow-up draft for a merged PR. Same PR is recorded once.
+ * Depth above {@link FOLLOW_UP_DEPTH_LIMIT} records «OP 카드 필요» instead of a draft.
+ * `live` enqueues; `shadow` (the default) only records. Returns null when nothing remains.
+ * Every failure is `debug.log` only — the merge result is the caller's to return unchanged.
+ */
+export async function recordFollowUpOnMerge(input: FollowUpMergeInput, seams: FollowUpSeams = {}): Promise<FollowUpDraftRecord | null> {
+  const log = seams.log ?? ((category, event, data) => { debug.log(category, event, data); });
+  try {
+    const remainings = collectRemainings(input);
+    if (remainings.length === 0) return null;
+    // No injected store and no explicit state root: this is the test process.
+    // Do not open the operational ledger or the harness queue.
+    // A test process handed the operational root (defaultSeams) is refused the same way.
+    const testProcess = process.env.NODE_ENV === 'test' || !!process.env.ELANOUS_TEST_HOME;
+    if (!seams.readDrafts && !seams.appendDraft && (!seams.stateRoot || (testProcess && seams.stateRoot === elanousStateRoot()))) return null;
+    const stateRoot = seams.stateRoot ?? elanousStateRoot();
+    const cellId = followUpCellId(input);
+    if (!cellId) {
+      log('self-implement.follow-up', 'draft-skipped-no-cell', { prNumber: input.prNumber });
+      return null;
+    }
+    const prior = (seams.readDrafts ?? ((id) => defaultReadDrafts(stateRoot, id)))(cellId);
+    if (prior.some((record) => record.prNumber === input.prNumber)) return null;
+    if (!seams.readDrafts && defaultPrRecorded(stateRoot, input.prNumber)) return null;
+    const depth = followUpChainDepth(prior) + 1;
+    const firstLine = originalAskFirstLine(input.feature);
+    const mode = seams.mode ?? readFollowUpMode();
+    const overDepth = depth > FOLLOW_UP_DEPTH_LIMIT;
+    const draft = overDepth ? undefined : followUpDraftText(firstLine, remainings);
+    const record: FollowUpDraftRecord = {
+      prNumber: input.prNumber,
+      cellId,
+      depth,
+      draftHash: followUpDraftHash(draft ?? `${firstLine}\n${FOLLOW_UP_OP_CARD_REQUIRED}`),
+      kind: overDepth ? 'op-card-required' : 'draft',
+      originalAskFirstLine: firstLine,
+      remainings,
+      ...(draft ? { draft } : {}),
+      ...(overDepth ? { note: FOLLOW_UP_OP_CARD_REQUIRED } : {}),
+      queued: false,
+    };
+    // 운영 원장은 «같은 PR 확인 ⊕ 첫 기록»을 한 잠금 안에서 한다 — 동시 병합 둘이 초안 둘을 만들지 않게.
+    const append = seams.appendDraft ?? ((row: FollowUpDraftRecord) => defaultAppendDraft(stateRoot, row));
+    const appendFirst = seams.appendDraft
+      ? (row: FollowUpDraftRecord) => { append(row); return true; }
+      : (row: FollowUpDraftRecord) => (mkdirSync(dirname(followUpDraftsPath(stateRoot)), { recursive: true }), withFileLockSync(`${followUpDraftsPath(stateRoot)}.lock`, () => {
+        if (defaultPrRecorded(stateRoot, row.prNumber)) return false;
+        defaultAppendDraft(stateRoot, row);
+        return true;
+      }));
+    if (!overDepth && mode === 'live' && draft) record.seat = seatForCellOwner((seams.cellOwner ?? defaultCellOwner)(cellId));
+    // 원장 기록을 먼저 확정한다 — 기록이 실패하면 대기열에 넣지 않는다(같은 PR 한 번 · 원장 밖 연결골 0).
+    if (!appendFirst(record)) return null;
+    if (!overDepth && mode === 'live' && draft && record.seat) {
+      const seat = record.seat;
+      if (testProcess && !seams.enqueue) return record;
+      try {
+        await (seams.enqueue ?? ((item) => addHarnessQueue({ seat: item.seat, say: item.say, idempotencyKey: item.idempotencyKey })))({
+          seat,
+          say: draft,
+          idempotencyKey: `follow-up:${input.prNumber}`,
+        });
+        record.queued = true;
+      } catch (error) {
+        // 대기열 넣기가 실패해도 초안은 남긴다 — 같은 PR 은 다시 오지 않으므로 여기서 잃으면 영영 없다.
+        // queued=false ⊕ enqueueError 로 원장에 남기고, 재투입은 같은 idempotencyKey 로 사람이·다음 수리 노드가 한다.
+        record.enqueueError = (error instanceof Error ? error.message : String(error)).slice(0, 300);
+        log('self-implement.follow-up', 'enqueue-failed', { prNumber: input.prNumber, seat, error: record.enqueueError });
+      }
+      // 대기열 결과를 원장에 한 줄 더 — 이 쓰기의 실패는 대기열 실패와 다른 사건이다.
+      try {
+        append({ ...record });
+      } catch (error) {
+        log('self-implement.follow-up', 'ledger-confirm-failed', {
+          prNumber: input.prNumber, seat, queued: record.queued, error: error instanceof Error ? error.message : String(error),
+        });
+      }
+    }
+    return record;
+  } catch (error) {
+    log('self-implement.follow-up', 'draft-failed', {
+      prNumber: input.prNumber,
+      error: error instanceof Error ? error.message : String(error),
+    });
+    return null;
+  }
+}

package/src/self-implement/frozen-merges.ts

@@ -2,9 +2,9 @@ import { closeSync, existsSync, mkdirSync, openSync, readFileSync, realpathSync,
 import { dlopen, FFIType } from 'bun:ffi';
 import { createHash } from 'node:crypto';
 import { dirname, join, resolve } from 'node:path';
-import { effectiveInstanceRoot } from '../instance/resolve.js';
+import { effectiveInstanceRoot, prodInstanceRoot } from '../instance/resolve.js';
 import { debug } from '../debug/log.js';
-import { beginLandingMerge, readLandingFreeze, type LandingFreeze } from '../release-loop/landing-freeze.js';
+import { beginLandingMerge, type LandingFreeze } from '../release-loop/landing-freeze.js';
 
 /** `manual`: the owning repository could not be determined — a sweep never resumes it; a person does. */
 export interface FrozenMerge { prNumber: number; headCommit: string; repoRoot: string; manual?: true; /** Host goal document, so a resumed merge can still apply its «이 칸 완료» declaration (CL-AUTO). */ goalFile?: string }
@@ -182,8 +182,10 @@ export function admitLandingMerge(
   root = effectiveInstanceRoot(),
   hooks: { afterQueue?: () => void } = {},
   claimKey?: { prNumber: number; repoRoot: string; headCommit?: string },
+  opts: { prodFreezeRoot?: string; forceReason?: string } = {},
 ): LandingAdmission {
   let entry: FrozenMerge | null | undefined;
+  const prodFreezeRoot = opts.prodFreezeRoot ?? prodInstanceRoot();
   // A held PR is merged by exactly one runner: the claim (repository + PR) is held from admission until the lander's
   // merge has ended. Its queue entry stays until that merge is confirmed — `end(true)` removes this lander's own head;
   // a failed or interrupted merge leaves it for the next resume sweep.
@@ -201,7 +203,7 @@ export function admitLandingMerge(
     } finally { landing.end(); held?.release(); }
   };
   for (;;) {
-    const landing = beginLandingMerge(root);
+    const landing = beginLandingMerge(root, new Date(), prodFreezeRoot, opts.forceReason);
     if (!landing.frozen) {
       if (!claim && claimKey) {
         const key = { prNumber: claimKey.prNumber, repoRoot: repoIdentity(claimKey.repoRoot), headCommit: claimKey.headCommit };
@@ -222,17 +224,19 @@ export function admitLandingMerge(
     if (!entry) return { kind: 'held', freeze: landing.frozen };
     queueFrozenMerge(entry, root);
     hooks.afterQueue?.();
-    if (readLandingFreeze(root)) return { kind: 'held', freeze: landing.frozen };
-    const mine = { ...entry, repoRoot: repoIdentity(entry.repoRoot) };
-    claim = claimFrozenMerge(mine, root);
-    if (!claim) return { kind: 'taken' };
-    // A resume sweep already merged and dequeued it between our queueing and our claim: nothing left to merge.
-    let stillHeld = false;
-    try { stillHeld = readQueue(root).some((item) => sameEntry(item, mine)); }
-    catch (error) { claim.release(); throw error; }
-    if (!stillHeld) { claim.release(); return { kind: 'taken' }; }
-    ownHead = mine;
-    debug.log('harness.merge', 'freeze-lifted-while-queueing', { pr: entry.prNumber });
+    const afterQueue = beginLandingMerge(root, new Date(), prodFreezeRoot, opts.forceReason);
+    if (afterQueue.frozen) return { kind: 'held', freeze: afterQueue.frozen };
+    try {
+      const mine = { ...entry, repoRoot: repoIdentity(entry.repoRoot) };
+      claim = claimFrozenMerge(mine, root);
+      if (!claim) return { kind: 'taken' };
+      // A resume sweep already merged and dequeued it between our queueing and our claim: nothing left to merge.
+      const stillHeld = readQueue(root).some((item) => sameEntry(item, mine));
+      if (!stillHeld) { claim.release(); return { kind: 'taken' }; }
+      ownHead = mine;
+      debug.log('harness.merge', 'freeze-lifted-while-queueing', { pr: entry.prNumber });
+    } catch (error) { claim?.release(); throw error; }
+    finally { afterQueue.end(); }
   }
 }
 
@@ -259,16 +263,17 @@ export async function sweepFrozenMerges(
   },
   root = effectiveInstanceRoot(),
   alreadyMerged: (entry: FrozenMerge) => boolean | Promise<boolean> = githubMergedAt,
+  prodFreezeRoot = prodInstanceRoot(),
 ): Promise<{ pending: number; merged: number }> {
-  const frozen = readLandingFreeze(root);
-  if (frozen) return { pending: readQueue(root).length, merged: 0 };
   const pending = readQueue(root);
   let merged = 0;
   for (const entry of pending) {
-    if (readLandingFreeze(root)) break;
-    const claim = claimFrozenMerge(entry, root);
-    if (!claim) continue; // another sweep or the original lander is on it
+    const guard = beginLandingMerge(root, new Date(), prodFreezeRoot);
+    if (guard.frozen) break;
+    let claim: { release: () => void } | null = null;
     try {
+      claim = claimFrozenMerge(entry, root);
+      if (!claim) continue; // another sweep or the original lander is on it
       if (!readQueue(root).some((item) => sameEntry(item, entry))) continue; // taken back by its lander
       if (entry.manual) { debug.log('harness.merge', 'resume-manual', { pr: entry.prNumber, repoRoot: entry.repoRoot }); continue; }
       if (!(await alreadyMerged(entry))) {
@@ -289,7 +294,7 @@ export async function sweepFrozenMerges(
       });
     } catch (error) {
       debug.log('harness.merge', 'resume-failed', { pr: entry.prNumber, error: String(error) });
-    } finally { claim.release(); }
+    } finally { guard.end(); claim?.release(); }
   }
   return { pending: readQueue(root).length, merged };
 }

package/src/self-implement/goal-author-clarification.ts

@@ -681,6 +681,87 @@ export function injectGoalDocumentClarificationOtherAnswer(document: string, que
  *    「답이 한 번도 안 들어가서 효과를 못 쟀다」***일 수 있다 — 두 무리 다 «답이 없는» 무리였다.
  *  ⛔ 무인 계약은 유지한다 — 대화형이 아니면 종전대로 지나가되 «그 사실을 값으로» 낸다.
  */
+export type GoalClarificationSelfAnswerPath = 'say-first' | 'ask' | 'rework';
+export type GoalClarificationSelfResolver = NonNullable<GoalAuthorClarificationResolutionDeps['selfResolve']>;
+
+/** Attempt only unanswered document questions; retain every unanswered line if evidence is insufficient. */
+export async function selfAnswerGoalDocumentClarifications(
+  document: string,
+  options: {
+    path: GoalClarificationSelfAnswerPath;
+    ask?: string;
+    evidence?: readonly string[];
+    resolver?: GoalClarificationSelfResolver;
+  },
+): Promise<{ document: string; asked: number; answered: number; unanswered: number; newlyAnswered: number }> {
+  const clarifications = parseGoalDocumentClarifications(document);
+  const pending = clarifications.filter((item) => !item.answered);
+  // The first say pass may already have self-answered some questions while authoring: count those,
+  // never re-ask them, and still attempt every question that is left unanswered.
+  const alreadySelfAnswered = options.path === 'say-first'
+    ? clarifications.filter((item) => item.answered && item.provenanceSource === 'self-authored').length
+    : 0;
+  let updated = document;
+  let answered = 0;
+  const evidence = options.evidence ?? document.split(/\r?\n/)
+    .filter((line) => /^(?:\s*- (?:\[code:|\[document:|TRACED PATHS|evidence:|Evidence:)|\s*-?\s*`?(?:src|test|scripts)\/[^\s`]+:\d+)/i.test(line))
+    .slice(0, 40);
+  for (const item of pending) {
+    if (parseGoalDocumentClarifications(updated).filter((entry) => entry.questionId === item.questionId).length !== 1) continue;
+    let response: Awaited<ReturnType<typeof resolveGoalAuthorClarification>>;
+    try { response = await resolveGoalAuthorClarification({
+      questionId: item.questionId,
+      kind: 'scope',
+      header: item.header,
+      question: item.question,
+      options: item.options.map((option) => ({ label: option.label, description: option.description })),
+      blocking: false,
+    }, {
+      selfResolve: options.resolver ?? defaultGoalAuthorSelfResolve,
+      evidence,
+      ask: options.ask,
+      selfResolutionSelected: true,
+    }); } catch {
+      // A resolver failure leaves this question unanswered; the remaining questions are still attempted.
+      continue;
+    }
+    if (response.answer === null || response.provenance?.source !== 'self-authored'
+      || response.answer.startsWith(DEFERRED_ANSWER_PREFIX)) continue;
+    try {
+      if (!response.answer.trim() || /[\r\n]/.test(response.answer)
+        || (!item.includeOther && !item.options.some((option) => option.label === response.answer))) continue;
+      const current = findUnansweredGoalDocumentClarification(updated, item.questionId);
+      const lines = updated.split(/\r?\n/);
+      const provenanceLines = current.provenanceLines ?? [];
+      for (const line of [...provenanceLines].sort((left, right) => right - left)) lines.splice(line, 1);
+      const answerLine = current.answerLine - provenanceLines.filter((line) => line < current.answerLine).length;
+      lines[answerLine] = `  - answer: ${response.answer}`;
+      lines.splice(answerLine + 1, 0,
+        '  - provenance.source: self-authored',
+        ...response.provenance.evidence!.map((entry) => `  - evidence: ${entry.replace(/[\r\n]/g, ' ')}`));
+      updateWhatToBuildRenderAnswers(lines, item.questionId, response.answer);
+      if (hasWhatToBuildUnansweredRenderAnswer(lines, item.questionId)) continue;
+      const candidate = lines.join(document.includes('\r\n') ? '\r\n' : '\n');
+      if (!parseGoalDocumentClarifications(candidate).some((entry) => entry.questionId === item.questionId
+        && entry.answered && entry.answer === response.answer && entry.provenanceSource === 'self-authored')) continue;
+      updated = candidate;
+      answered += 1;
+    } catch {
+      // Leave malformed or disallowed answers deferred.
+    }
+  }
+  const asked = pending.length + alreadySelfAnswered;
+  const unanswered = pending.length - answered;
+  const newlyAnswered = answered;
+  answered += alreadySelfAnswered;
+  debug.log('self-implement.clarification-escalation', 'self-answer', {
+    path: options.path, asked, answered, unanswered,
+    reason: unanswered === 0 ? 'answered' : 'insufficient-evidence',
+  });
+  return { document: updated, asked, answered, unanswered, newlyAnswered };
+}
+
+
 export type ClarificationIntakeMode = 'none' | 'deferred-noninteractive' | 'ask';
 
 export interface ClarificationIntakePlan {