elanous 0.2.28 → 0.2.31

package/src/self-dev/shard-plan.ts

@@ -1,3 +1,5 @@
+import { isGateSpawnLaneFile } from './spawn-lane-files.js';
+
 export interface GateTestShard {
   id: string;
   files: string[];
@@ -5,6 +7,27 @@ export interface GateTestShard {
   plannedSeconds: number;
 }
 
+/** Keep real child/PTY tests out of ordinary self-gate shards, within the caller's shard budget. */
+export function planSelfGateSpawnSeparatedShards(
+  files: readonly string[],
+  rssMb: ReadonlyMap<string, number>,
+  seconds: ReadonlyMap<string, number>,
+  budgetGiB: number,
+  shardCount: number,
+): GateTestShard[] {
+  const unique = [...new Set(files)];
+  const spawn = unique.filter(isGateSpawnLaneFile);
+  const regular = unique.filter((file) => !isGateSpawnLaneFile(file));
+  if (!spawn.length || !regular.length) return planGateTestShards(unique, rssMb, seconds, budgetGiB, shardCount);
+  if (shardCount < 2) throw new Error('self gate spawn lane needs at least two shards when regular and spawn tests coexist');
+  const spawnCount = Math.min(3, spawn.length, shardCount - 1);
+  const planned = [
+    ...planGateTestShards(regular, rssMb, seconds, budgetGiB, shardCount - spawnCount),
+    ...planGateTestShards(spawn, rssMb, seconds, budgetGiB, spawnCount),
+  ];
+  return planned.map((shard, index) => ({ ...shard, id: `shard-${index + 1}` }));
+}
+
 /** RSS values are the per-file rss_mb observations; the budget is in GiB (1 GiB = 1024 MB here). */
 export function planGateTestShards(
   files: readonly string[],
@@ -50,3 +73,27 @@ export function planGateTestShards(
   }
   return shards;
 }
+
+/** OP FU (LAND-TRAIN-LIVE side) — opt-in `--fixed-shard-distribution`: no RSS/seconds measurement. Files are deduplicated,
+ *  sorted by code point (input-order independent) and dealt round-robin into at most `shardCount` shards; real child/PTY
+ *  tests keep their own lane exactly like the measured planner. Not a memory-safety guarantee — an over-budget shard
+ *  surfaces as its own run result (signal/exit/incomplete JUnit ⇒ unmeasured), never as a pass. No empty shards. */
+export function planFixedGateTestShards(files: readonly string[], shardCount: number): GateTestShard[] {
+  if (!Number.isSafeInteger(shardCount) || shardCount < 1) throw new Error('invalid shard count');
+  const sorted = [...new Set(files)].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+  const deal = (subset: readonly string[], count: number): string[][] => {
+    const buckets: string[][] = Array.from({ length: Math.min(count, subset.length) }, () => []);
+    subset.forEach((file, index) => buckets[index % buckets.length]!.push(file));
+    return buckets;
+  };
+  const spawn = sorted.filter(isGateSpawnLaneFile);
+  const regular = sorted.filter((file) => !isGateSpawnLaneFile(file));
+  let groups: string[][];
+  if (!spawn.length || !regular.length) groups = deal(sorted, shardCount);
+  else {
+    if (shardCount < 2) throw new Error('self gate spawn lane needs at least two shards when regular and spawn tests coexist');
+    const spawnCount = Math.min(3, spawn.length, shardCount - 1);
+    groups = [...deal(regular, shardCount - spawnCount), ...deal(spawn, spawnCount)];
+  }
+  return groups.map((group, index) => ({ id: `shard-${index + 1}`, files: group, plannedRssMb: 0, plannedSeconds: 0 }));
+}

package/src/self-dev/shard-run.ts

@@ -1,11 +1,13 @@
-import { existsSync, mkdtempSync, readFileSync, rmSync, statSync } from 'node:fs';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { debug } from '../debug/log.js';
+import { debug, redactSecretText } from '../debug/log.js';
 import { prepareDeterministicChildEnvironment } from '../../scripts/lib/deterministic-env.js';
+import { withGateTestEnv } from '../../scripts/lib/gate-test-env.js';
 import { withBaselineWorktree } from '../self-implement/gate-baseline.js';
 import { aggregateGateTestShards, type GateShardAttempt, type GateShardAggregate } from './shard-aggregate.js';
-import { planGateTestShards, type GateTestShard } from './shard-plan.js';
+import { planFixedGateTestShards, planSelfGateSpawnSeparatedShards, type GateTestShard } from './shard-plan.js';
+import { isGateSpawnLaneFile } from './spawn-lane-files.js';
 
 export interface ShardRunResult {
   aggregate: GateShardAggregate;
@@ -13,6 +15,33 @@ export interface ShardRunResult {
   attempts: GateShardAttempt[];
   reason?: string;
   measurementFailures?: number;
+  /** Present only for opt-in `--fixed-shard-distribution` (no RSS pre-measurement). Absent = the measured planner. */
+  distribution?: 'fixed';
+  /** OP FU (MK #8178 shard-9) — raw evidence of every failed shard process (exit≠0 · signal · no JUnit). Observation only:
+   *  the aggregate never reads it. Absent = no shard process reported failure output. */
+  failureEvidence?: ShardFailureEvidence[];
+}
+
+/** What a failed shard process leaves behind so «test failure vs runner error» can be told apart after the fact. */
+export interface ShardFailureOutput {
+  durationMs: number;
+  /** Last 64KB of the child's stdout/stderr (redacted). */
+  stdoutTail: string;
+  stderrTail: string;
+}
+
+export interface ShardFailureEvidence extends ShardFailureOutput {
+  shardId: string;
+  side: 'current' | 'baseline';
+  attempt: number;
+  files: string[];
+  exitCode: number | null;
+  signal: string | null;
+}
+
+export interface ShardRunMode {
+  /** OP FU — sorted round-robin into `count` shards, zero pre-measurement runs. Default off: the measured planner. */
+  fixedDistribution?: boolean;
 }
 
 export type ShardProcess = (cwd: string, files: readonly string[]) => {
@@ -21,8 +50,54 @@ export type ShardProcess = (cwd: string, files: readonly string[]) => {
   junit?: string;
   rssMb?: number;
   seconds?: number;
+  /** Bounded, redacted process output for an abnormal exit before JUnit exists. */
+  diagnostic?: string;
+  /** Present only when the process failed (exit≠0 · signal · no JUnit) — observation only, never part of the verdict. */
+  failure?: ShardFailureOutput;
 };
 
+export const SHARD_FAILURE_TAIL_BYTES = 64 * 1024;
+
+function outputTail(bytes: Uint8Array | undefined): string {
+  if (!bytes?.length) return '';
+  const tail = bytes.length > SHARD_FAILURE_TAIL_BYTES ? bytes.subarray(bytes.length - SHARD_FAILURE_TAIL_BYTES) : bytes;
+  return redactSecretText(Buffer.from(tail).toString('utf8'));
+}
+
+/** `<shardId>.failure.json` per failed shard (shard ids are already `shard-<n>`). Top level = the latest current-side
+ *  failure (else the latest baseline one); `failures` keeps every failed side/attempt. Returns the written paths. */
+export function writeShardFailureEvidence(dir: string, evidence: readonly ShardFailureEvidence[]): string[] {
+  if (!evidence.length) return [];
+  mkdirSync(dir, { recursive: true });
+  const byShard = new Map<string, ShardFailureEvidence[]>();
+  for (const item of evidence) byShard.set(item.shardId, [...(byShard.get(item.shardId) ?? []), item]);
+  const written: string[] = [];
+  for (const [shardId, failures] of byShard) {
+    const primary = [...failures].reverse().find((item) => item.side === 'current') ?? failures[failures.length - 1]!;
+    const path = join(dir, `${shardId.replace(/[^A-Za-z0-9._-]/g, '_')}.failure.json`);
+    const { side, attempt, ...fields } = primary;
+    writeFileSync(path, `${JSON.stringify({ ...fields, side, attempt, failures }, null, 2)}\n`);
+    debug.log('self-dev.shard', 'failure-evidence', { shardId, path, failures: failures.length, exitCode: primary.exitCode, signal: primary.signal });
+    written.push(path);
+  }
+  return written;
+}
+
+const DIAGNOSTIC_STREAM_LIMIT = 240;
+
+function boundedDiagnostic(stdout: Uint8Array, stderr: Uint8Array): string | undefined {
+  const oneStream = (bytes: Uint8Array): string => {
+    const safe = redactSecretText(Buffer.from(bytes).toString('utf8')).replace(/[\r\n\t\x00-\x1f\x7f]+/g, ' ').trim();
+    if (safe.length <= DIAGNOSTIC_STREAM_LIMIT) return safe;
+    // Bun can print the cause after a long preamble; keep both ends within the same bound.
+    const head = Math.floor((DIAGNOSTIC_STREAM_LIMIT - 1) / 2);
+    return `${safe.slice(0, head)}…${safe.slice(-(DIAGNOSTIC_STREAM_LIMIT - 1 - head))}`;
+  };
+  const out = oneStream(stdout);
+  const err = oneStream(stderr);
+  return [out && `stdout: ${out}`, err && `stderr: ${err}`].filter(Boolean).join(' · ') || undefined;
+}
+
 /** Absent only when the path provably is not a file there (missing, or not a regular file); any other stat error
  *  (permissions …) is not evidence of absence, so the file stays in the baseline run (fail-closed: unmeasured). */
 const absentAtBaseline = (path: string): boolean => {
@@ -39,8 +114,17 @@ export function runShardedGateTests(
   run: ShardProcess = runBunShard,
   baselineWorktree: typeof withBaselineWorktree = withBaselineWorktree,
   budgetGiB = 8,
+  mode: ShardRunMode = {},
 ): ShardRunResult {
   if (!Number.isSafeInteger(count) || count < 1) throw new Error('invalid --shards count');
+  if (mode.fixedDistribution) {
+    // Opt-in: no per-file pre-measurement at all — the shard runs themselves (JUnit · rc · signal · baseline) decide.
+    let fixed: GateTestShard[];
+    try { fixed = planFixedGateTestShards(files, count); }
+    catch (error) { return { aggregate: { status: 'unmeasured', retryShardIds: [] }, shards: [], attempts: [], reason: String(error), distribution: 'fixed' }; }
+    debug.log('self-dev.shard', 'fixed-distribution', { shards: fixed.length, files: fixed.reduce((sum, shard) => sum + shard.files.length, 0) });
+    return { ...runPlannedShards(cwd, fixed, baseRef, run, baselineWorktree), distribution: 'fixed' };
+  }
   const rss = new Map<string, number>();
   const seconds = new Map<string, number>();
   const failedMeasurements: string[] = [];
@@ -73,11 +157,27 @@ export function runShardedGateTests(
   const measurementFailures = failedMeasurements.length || undefined;
   let shards: GateTestShard[];
   try {
-    shards = planGateTestShards(files, rss, seconds, budgetGiB, count);
+    shards = planSelfGateSpawnSeparatedShards(files, rss, seconds, budgetGiB, count);
   } catch (error) {
     return { aggregate: { status: 'unmeasured', retryShardIds: [] }, shards: [], attempts: [], reason: String(error), ...(measurementFailures ? { measurementFailures } : {}) };
   }
+  return { ...runPlannedShards(cwd, shards, baseRef, run, baselineWorktree), ...(measurementFailures ? { measurementFailures } : {}) };
+}
+
+/** Shared by the measured and the fixed planner: current + baseline per shard, one retry round, one aggregate. */
+function runPlannedShards(
+  cwd: string,
+  shards: GateTestShard[],
+  baseRef: string,
+  run: ShardProcess,
+  baselineWorktree: typeof withBaselineWorktree,
+): ShardRunResult {
   const attempts: GateShardAttempt[] = [];
+  const failureEvidence: ShardFailureEvidence[] = [];
+  const keepFailure = (shardId: string, side: ShardFailureEvidence['side'], attempt: number, files: readonly string[], result: ReturnType<ShardProcess>) => {
+    if (!result.failure) return;
+    failureEvidence.push({ shardId, side, attempt, files: [...files], exitCode: result.exitCode, signal: result.signal ?? null, ...result.failure });
+  };
   const baseline = baselineWorktree(cwd, baseRef, (dir) => {
     // LIGHT-RC-MEASURE ① — bun silently skips a path that is not in the baseline tree (exit 0), so a shard holding a
     // new test file could never yield a complete baseline JUnit. Run the baseline side on the files the base has; an
@@ -97,11 +197,14 @@ export function runShardedGateTests(
         }
         const current = runSafely(cwd, shard.files);
         const base = baselineFiles.length ? runSafely(dir, baselineFiles) : { exitCode: 0 };
+        keepFailure(shard.id, 'current', round, shard.files, current);
+        keepFailure(shard.id, 'baseline', round, baselineFiles, base);
         attempts.push({
           shardId: shard.id, attempt: round,
           currentJUnit: current.junit, baselineJUnit: base.junit,
           currentExitCode: current.exitCode, baselineExitCode: base.exitCode,
           currentSignal: current.signal, baselineSignal: base.signal,
+          currentDiagnostic: current.diagnostic, baselineDiagnostic: base.diagnostic,
           baselineFiles,
         });
       }
@@ -110,27 +213,47 @@ export function runShardedGateTests(
     }
     return aggregateGateTestShards(shards, attempts);
   });
-  if ('retryShardIds' in baseline) return { aggregate: baseline, shards, attempts, ...(measurementFailures ? { measurementFailures } : {}) };
-  return { aggregate: { status: 'unmeasured', retryShardIds: shards.map((shard) => shard.id) }, shards, attempts, reason: baseline.log, ...(measurementFailures ? { measurementFailures } : {}) };
+  const evidence = failureEvidence.length ? { failureEvidence } : {};
+  if ('retryShardIds' in baseline) return { aggregate: baseline, shards, attempts, ...evidence };
+  return { aggregate: { status: 'unmeasured', retryShardIds: shards.map((shard) => shard.id) }, shards, attempts, reason: baseline.log, ...evidence };
+}
+
+export function selfGateShardTimeoutMs(files: readonly string[]): number {
+  const spawnFiles = files.filter(isGateSpawnLaneFile);
+  if (spawnFiles.length && spawnFiles.length !== files.length) throw new Error('self gate spawn lane mixed with regular tests');
+  return spawnFiles.length ? 120_000 : 300_000;
 }
 
 export function runBunShard(cwd: string, files: readonly string[]): ReturnType<ShardProcess> {
+  return runBunShardWithSpawn(cwd, files, Bun.spawnSync);
+}
+
+/** Child launch seam for verifying the actual command and process timeout. */
+export function runBunShardWithSpawn(cwd: string, files: readonly string[], spawn: typeof Bun.spawnSync): ReturnType<ShardProcess> {
+  const timeout = selfGateShardTimeoutMs(files);
+  const spawnLane = timeout === 120_000;
   const dir = mkdtempSync(join(tmpdir(), 'elanous-shard-junit-'));
   const report = join(dir, 'result.xml');
-  const isolated = prepareDeterministicChildEnvironment('elanous-shard-test-env-');
+  const isolated = prepareDeterministicChildEnvironment('elanous-shard-test-env-', { env: withGateTestEnv(process.env) });
   try {
     const measured = files.length === 1;
-    const args = ['test', '--reporter=junit', `--reporter-outfile=${report}`, ...files];
+    const args = ['test', ...(spawnLane ? ['--timeout=120000'] : []), '--reporter=junit', `--reporter-outfile=${report}`, ...files];
     const started = performance.now();
-    const result = Bun.spawnSync(['bun', ...args], {
-      cwd, env: isolated.env, stdout: 'pipe', stderr: 'pipe', timeout: 300_000,
+    const result = spawn(['bun', ...args], {
+      cwd, env: isolated.env, stdout: 'pipe', stderr: 'pipe', timeout,
     });
+    const durationMs = performance.now() - started;
+    const junit = existsSync(report) ? readFileSync(report, 'utf8') : undefined;
+    const failed = result.exitCode !== 0 || !!result.signalCode || junit === undefined;
     return {
       exitCode: result.exitCode,
       signal: result.signalCode ? String(result.signalCode) : undefined,
-      junit: existsSync(report) ? readFileSync(report, 'utf8') : undefined,
+      junit,
+      ...(junit === undefined && (result.exitCode !== 0 || result.signalCode)
+        ? { diagnostic: boundedDiagnostic(result.stdout, result.stderr) } : {}),
       rssMb: measured ? result.resourceUsage.maxRSS / (1024 * 1024) : undefined,
-      seconds: measured ? (performance.now() - started) / 1000 : undefined,
+      seconds: measured ? durationMs / 1000 : undefined,
+      ...(failed ? { failure: { durationMs: Math.round(durationMs), stdoutTail: outputTail(result.stdout), stderrTail: outputTail(result.stderr) } } : {}),
     };
   } finally {
     isolated.cleanup();

package/src/self-dev/spawn-lane-files.ts

@@ -0,0 +1,19 @@
+/** Real child/PTY test files. This list is shared by release and self gates. */
+export const GATE_SPAWN_LANE_FILES = [
+  'scripts/lib/tui-runshell-group-e2e.test.ts',
+  'scripts/lib/tui-streaming-e2e.test.ts',
+  'src/agent-mission/doc-guided-install.test.ts',
+  'src/dashboard/first-screen-band-wiring.test.ts',
+  'src/git-fs/spawn-discipline.test.ts',
+  'src/self-implement/run-ledger.test.ts',
+  'src/video-pipeline/recipes/reframe.test.ts',
+  'test/ch5730-watch-delivery.test.ts',
+  'test/cli-dev-command.test.ts',
+  'test/preview-terminal.test.ts',
+] as const;
+
+const SPAWN_FILES: ReadonlySet<string> = new Set(GATE_SPAWN_LANE_FILES);
+
+export function isGateSpawnLaneFile(file: string): boolean {
+  return SPAWN_FILES.has(file);
+}

package/src/self-health/signatures.ts

@@ -0,0 +1,132 @@
+// ── 실패 지문 사전 (L4 자기 인지 · TUI-FAILURE-SIGNATURES) ──
+//
+// 결함 기록(`seat-state/OPC/tui-op-issues.md`)을 «데이터»로 옮긴 것이다 — 증상 → 원인 → 처방.
+// 지문 ↔ 결함 번호 ↔ 칸 대응은 PR #27498 본문 표가 정본이다(여기 복제하지 않는다).
+// TUI 턴이 오류로 끝날 때 디버그 원문(영어 덤프) 대신 «무슨 일 → 다음 행동» 한국어 한 줄을 보이고,
+// 원문은 `/detail` 쪽으로 보낸다. 설계 정본 = `RFC-tui-self-awareness-and-continuity` L4.
+//
+// ⭐ 공용 모듈이다 — 화면 경로(plain-turn 오류) 말고도 가드 문구 현지화
+//    (UX `TUI-GUARD-NOTICE`)·자기 건강 한 줄(L3 `opc-self-health`)이 이 사전을 가져다 쓴다.
+//    ⛔ 지문 문면을 호출부에 복제하지 말고 여기 한 줄을 더한다.
+// 📋 관측: 지문이 맞으면 `debug.log('tui.failure-signature', 'matched', { id, surface })` 하나.
+//    `elanous logs --category tui.failure-signature` 로 지문별 빈도를 센다.
+
+import { debug } from '../debug/log.js';
+
+export interface FailureEventInput {
+  category: string;
+  event: string;
+  data?: Record<string, unknown>;
+}
+
+export interface FailureSignature {
+  /** 안정 id — 관측 이벤트·L3 집계의 키. ⛔ 바꾸면 집계가 끊긴다. */
+  readonly id: string;
+  /** 오류 문자열·응답 문면에서 이 지문을 알아보는 패턴(하나라도 맞으면). */
+  readonly text?: readonly RegExp[];
+  /** 로그 이벤트로 알아보는 패턴. */
+  readonly event?: {
+    readonly category: string;
+    readonly event: string;
+    readonly when?: (data: Record<string, unknown>) => boolean;
+  };
+  /** 무슨 일 — 한국어 한 줄. */
+  readonly cause: string;
+  /** 다음 행동 — 한국어 한 줄. */
+  readonly next: string;
+}
+
+/** 이벤트 루프 정지를 «지문»으로 볼 문턱 — 0.25s 표본은 잦아 소음이고, 결함 #1(14s)·#14(최대 2.35s)는 이 위다. */
+export const EVENT_LOOP_STALL_SIGNATURE_MS = 2_000;
+
+// ⚠️ 순서가 뜻이다 — 앞의 것이 먼저 맞는다. 원인 지문(400)을 결과 지문(공급자 소진) 앞에 둔다:
+//    소진 문면 안에 `Codex API 400` 이 시도 이력으로 들어 있으면 처방은 400 쪽이 맞다.
+export const FAILURE_SIGNATURES: readonly FailureSignature[] = [
+  {
+    id: 'codex-400-bad-request',
+    // 모델 API 오류 머리로만 — `storage API 400 Bad Request` 같은 무관한 400 은 옛 출력 그대로 둔다.
+    text: [/\b(?:Codex|LLM) API 400\b/],
+    cause: '모델 API 가 요청을 400 으로 거절(대화 기록 어긋남 의심)',
+    next: '/session new 뒤 짧게 다시 묻기',
+  },
+  {
+    id: 'provider-fallback-exhausted',
+    // 머리(`[LLM PROVIDER …]`)만으로는 안 맞춘다 — 소진이 아닌 STOPPED·BLOCKED 는 옛 출력 그대로 둔다.
+    text: [/\[LLM PROVIDER (?:BLOCKED|STOPPED)\] fallback candidates exhausted/],
+    cause: '응답이 끊겼고 대체 공급자도 못 씀',
+    next: '잠시 뒤 다시 보내기 · 되풀이되면 eln usage',
+  },
+  {
+    id: 'tool-budget-reached',
+    text: [/Tool budget reached/],
+    cause: '이 턴의 도구 호출 상한 소진(짧은 질문은 상한이 작다)',
+    next: '«자세히 조사해» 로 다시 묻기',
+  },
+  {
+    id: 'broad-search-loop',
+    text: [/RUNTIME BLOCKED\W+repeated broad search loop/],
+    cause: '넓은 탐색이 연달아 이어져 탐색 가드가 막음',
+    next: '파일 경로를 짚어 읽게 하기',
+  },
+  {
+    id: 'synthesis-ignored',
+    text: [/\[(?:SYNTHESIS|ACTION|EXECUTION) IGNORED\]/],
+    cause: '도구만 부르는 루프를 가드가 끊음(근거 부족)',
+    next: '파일 3~5개로 좁혀 다시 묻기',
+  },
+  {
+    id: 'event-loop-stall',
+    event: {
+      category: 'tui.event-loop',
+      event: 'stall',
+      when: (data) => typeof data.lagMs === 'number' && data.lagMs >= EVENT_LOOP_STALL_SIGNATURE_MS,
+    },
+    cause: '화면 루프가 2초 넘게 멈춤(TUI 안 무거운 동기 작업)',
+    next: 'eln logs --event stall 로 직전 작업 보기',
+  },
+  {
+    id: 'stale-build',
+    event: { category: 'tui.run-state', event: 'stale' },
+    cause: '이 TUI 는 옛 판으로 도는 중(설치본이 그 뒤 갱신)',
+    next: 'TUI 다시 띄우기',
+  },
+];
+
+/** 오류 문자열에 맞는 첫 지문. 순수 — 관측을 남기지 않는다.
+ *  ⚠️ «던져진 오류·로그 이벤트»용이다 — 모델이 쓴 응답·도구 결과(인용이 섞인다)에 대면 오탐한다(PR #27498 r1~r5). */
+export function matchFailureText(text: string): FailureSignature | null {
+  if (!text) return null;
+  for (const sig of FAILURE_SIGNATURES) {
+    if (sig.text?.some((re) => re.test(text))) return sig;
+  }
+  return null;
+}
+
+/** 로그 이벤트에 맞는 첫 지문. 순수. */
+export function matchFailureEvent(input: FailureEventInput): FailureSignature | null {
+  for (const sig of FAILURE_SIGNATURES) {
+    const ev = sig.event;
+    if (!ev || ev.category !== input.category || ev.event !== input.event) continue;
+    if (ev.when && !ev.when(input.data ?? {})) continue;
+    return sig;
+  }
+  return null;
+}
+
+/** «무슨 일 → 다음 행동» 한국어 한 줄. `rawHint` 는 원문을 볼 자리(예: `/detail open`).
+ *  ⚠️ 한 화면 줄(한글은 두 칸)에 들어가게 짧게 — 140칸 TUI 에서 처방이 잘리면(…+N) 한 줄의 뜻이 없다. */
+export function formatFailureNotice(sig: FailureSignature, opts: { rawHint?: string } = {}): string {
+  const raw = opts.rawHint ? ` · 원문 ${opts.rawHint}` : '';
+  return `⚠ ${sig.cause} → ${sig.next}${raw}`;
+}
+
+/** 지문이 맞았다는 관측 한 줄 — L3 자기 건강이 이 이벤트를 센다. 관측은 화면을 막지 않는다. */
+export function recordFailureSignatureMatch(
+  sig: FailureSignature,
+  surface: string,
+  log: (category: string, event: string, data: Record<string, unknown>) => void = (c, e, d) => debug.log(c, e, d),
+): void {
+  try {
+    log('tui.failure-signature', 'matched', { id: sig.id, surface });
+  } catch { /* fail-soft — 관측이 화면을 막지 않는다 */ }
+}

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

@@ -1,6 +1,7 @@
 import { execFile as execFileCb } from 'node:child_process';
 import { promisify } from 'node:util';
 import { debug } from '../debug/log.js';
+import { runGithubRemoteCall } from '../github/remote-call.js';
 import { releaseGitDiffPaths, releasePrFilePaths } from '../self-dev/release-path-guard.js';
 
 const defaultExecFile = promisify(execFileCb);
@@ -33,6 +34,25 @@ const GH_APP_CALLERS = {
 
 export type GhAppCaller = keyof typeof GH_APP_CALLERS;
 
+/** Fixed routes keep `--body`, `-f body=…`, labels, and tokens out of both log categories. */
+const GH_APP_ROUTES: Record<GhAppCaller, string> = {
+  'post-pr-comment-history': 'repos/{owner}/{repo}/issues/:number/comments',
+  'post-pr-comment': 'pr/:number/comment',
+  'find-pr-comment': 'repos/{owner}/{repo}/issues/:number/comments',
+  'edit-pr-comment': 'repos/{owner}/{repo}/issues/comments/:id',
+  'add-pr-label-list': 'label/list',
+  'add-pr-label-create': 'label/create',
+  'add-pr-label': 'pr/:number/edit',
+  'read-pr-files': 'repos/{owner}/{repo}/pulls/:number/files',
+};
+
+function observedGhMethod(args: readonly string[]): string | undefined {
+  if (args[0] !== 'api') return undefined; // gh pr/label may choose REST or GraphQL internally
+  const at = args.indexOf('--method');
+  const value = at >= 0 ? args[at + 1] : undefined;
+  return value && /^(GET|POST|PUT|PATCH|DELETE)$/.test(value) ? value : undefined;
+}
+
 export const APP_API_RATE_LIMIT_RETRY_CAP_MS = 15 * 60_000;
 
 export class AppApiRateLimitError extends Error {
@@ -83,14 +103,32 @@ export async function waitForAppApiRateLimitReset(
 export async function runGhApp(
   caller: GhAppCaller,
   args: readonly string[],
-  opts: { cwd: string; encoding: 'utf8'; timeout: number; maxBuffer?: number; env: NodeJS.ProcessEnv },
+  opts: { cwd: string; encoding: 'utf8'; timeout: number; maxBuffer?: number; env: NodeJS.ProcessEnv; retry?: number },
 ): Promise<{ stdout: string; stderr: string }> {
+  const { retry, ...execOpts } = opts;
   let stdout = '';
   let stderr = '';
   let status: number | undefined;
   let error: unknown;
   try {
-    const result = await execFileImpl('gh', args, opts);
+    const result = await runGithubRemoteCall({
+      kind: args[0] === 'api' ? 'rest' : 'gh-command',
+      caller: GH_APP_CALLERS[caller],
+      route: GH_APP_ROUTES[caller],
+      method: observedGhMethod(args),
+      host: 'unmeasured', // gh may select the repo host even when GH_HOST is set
+      runId: opts.env.ELANOUS_RUN_ID,
+      retry,
+    }, () => execFileImpl('gh', args, execOpts), {
+      status: ({ failed, error: callError }) => {
+        if (!failed) return undefined; // gh exit 0 is not an observed HTTP 200
+        const raw = (callError as { stderr?: unknown })?.stderr;
+        const failureStderr = typeof raw === 'string' ? raw : '';
+        const header = ghHeader(failureStderr, 'HTTP') ?? ghHeader(failureStderr, 'status');
+        const code = header ? Number.parseInt(header, 10) : NaN;
+        return Number.isFinite(code) ? code : undefined;
+      },
+    });
     stdout = result.stdout;
     stderr = result.stderr ?? '';
     status = 200;
@@ -102,12 +140,14 @@ export async function runGhApp(
     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 ?? '',
-  });
+  try {
+    debug.log('github.app-api', 'call', {
+      caller: GH_APP_CALLERS[caller],
+      endpoint: GH_APP_ROUTES[caller],
+      status: status ?? 0,
+      remaining: remaining ?? '',
+    });
+  } catch { /* observation cannot replace the gh result or its original error */ }
   if (error) {
     const text = `${stderr}\n${error instanceof Error ? error.message : String(error)}`;
     if (isAppApiRateLimitFailure(status, text, remaining)) {
@@ -138,7 +178,7 @@ export async function readPrFilesWithRateLimitFallback(input: {
     `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 fromApi = async (retry: number) => releasePrFilePaths(JSON.parse((await runGhApp('read-pr-files', endpoint, { ...ghOpts, retry })).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`], {
@@ -147,7 +187,7 @@ export async function readPrFilesWithRateLimitFallback(input: {
     return releaseGitDiffPaths(stdout);
   };
   try {
-    return await fromApi();
+    return await fromApi(0);
   } catch (error) {
     if (!(error instanceof AppApiRateLimitError)) throw error;
     try {
@@ -156,7 +196,7 @@ export async function readPrFilesWithRateLimitFallback(input: {
       const waited = await waitForAppApiRateLimitReset(error.resetAtMs, input.now?.() ?? Date.now(), input.sleep);
       if (!waited) throw error;
       try {
-        return await fromApi();
+        return await fromApi(1);
       } catch (retryError) {
         if (retryError instanceof AppApiRateLimitError) throw retryError;
         throw gitError;

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

@@ -8,6 +8,7 @@
 //   셸 검사는 `zsh -n`/`bash -n`(구문만·미실행). JSON/TOML 은 인-프로세스 파싱(외부 프로세스 불필요).
 
 import { spawnSync } from 'node:child_process';
+import { SPAWN_SYNC_MAX_BUFFER } from '../util/spawn-sync-output.js';
 import { readFileSync } from 'node:fs';
 import { basename } from 'node:path';
 
@@ -32,7 +33,7 @@ export function runConfigSyntaxGate(filePath: string): ConfigGateResult {
   const isBash = /(^|\.)(bashrc|bash_profile|bash_login|profile|bash_aliases)$/.test(name) || name.endsWith('.bash') || name.endsWith('.sh');
   if (isZsh || isBash) {
     const shell = isZsh ? 'zsh' : 'bash';
-    const r = spawnSync(shell, ['-n', filePath], { encoding: 'utf8', timeout: SHELL_TIMEOUT_MS });
+    const r = spawnSync(shell, ['-n', filePath], { encoding: 'utf8', timeout: SHELL_TIMEOUT_MS, maxBuffer: SPAWN_SYNC_MAX_BUFFER });
     // 셸 미설치(status=null·ENOENT) → 검사 불가로 skip(차단 아님·HITL diff 로 검증).
     if (r.error || r.status === null) return { passed: true, checked: false, label: `${shell} -n (미설치)`, log: String(r.error?.message ?? 'shell 없음') };
     return { passed: r.status === 0, checked: true, label: `${shell} -n`, log: `${r.stdout ?? ''}${r.stderr ?? ''}`.slice(-2000) };