elanous 0.2.31 → 0.2.32

package/src/task-orchestrator/surfaces/pod-warm-worker-runtime.ts

@@ -2,9 +2,11 @@
 import { spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
-import { join, resolve, sep } from 'node:path';
+import { basename, dirname, join, parse, relative, resolve, sep } from 'node:path';
 import { warmReferenceFromJobArtifacts } from '../../../scripts/release-loop/gate-warm-artifacts.js';
 import { stateDirSourceForChild } from '../../agent/identity-env.js';
+import { debug } from '../../debug/log.js';
+import { decidePodReuseCleanup } from './pod-reuse-cleanup.js';
 import type { WarmWorkerCommand, WarmWorkerFileResult, WarmWorkerReply } from './pod-warm-worker-protocol.js';
 
 const token = (s: unknown): s is string => typeof s === 'string' && /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(s);
@@ -22,6 +24,76 @@ const withoutGitEnvironment = (): NodeJS.ProcessEnv => {
   return env;
 };
 
+function resolveThroughExistingAncestor(path: string): string | null {
+  let ancestor = resolve(path);
+  const suffix: string[] = [];
+  for (;;) {
+    try { return join(realpathSync(ancestor), ...suffix); }
+    catch {
+      const parent = dirname(ancestor);
+      if (parent === ancestor) return null;
+      suffix.unshift(basename(ancestor));
+      ancestor = parent;
+    }
+  }
+}
+
+function hasCheckoutLocalSymlink(repoDir: string, path: string): boolean {
+  if (path.split(sep).includes('..')) return true;
+  const absolute = resolve(path);
+  let current = parse(absolute).root;
+  for (const part of absolute.slice(current.length).split(sep).filter(Boolean)) {
+    current = join(current, part);
+    try {
+      if (!lstatSync(current).isSymbolicLink()) continue;
+      const physicalParent = resolveThroughExistingAncestor(dirname(current));
+      if (!physicalParent) continue;
+      const physicalLink = join(physicalParent, basename(current));
+      if (physicalLink === repoDir || physicalLink.startsWith(`${repoDir}${sep}`)) return true;
+    } catch { return false; }
+  }
+  return false;
+}
+
+function runtimeDirectoryExclusions(repoDir: string, repoLexicalDir: string, directories: readonly { name: string; path: string }[]) {
+  const additionalCleanExclusions: Array<{ name: string; pattern: string }> = [];
+  const statusExclusions = new Set<string>();
+  for (const directory of directories) {
+    const lexical = resolve(directory.path);
+    if (hasCheckoutLocalSymlink(repoDir, directory.path)) return null;
+    const candidates = new Set([lexical]);
+    const resolvedThroughAncestor = resolveThroughExistingAncestor(directory.path);
+    if (resolvedThroughAncestor) candidates.add(resolvedThroughAncestor);
+    for (const candidate of candidates) {
+      const root = candidate.startsWith(`${repoDir}${sep}`) ? repoDir
+        : candidate.startsWith(`${repoLexicalDir}${sep}`) ? repoLexicalDir : null;
+      if (candidate === repoDir || candidate === repoLexicalDir) return null;
+      if (!root) continue;
+      const path = relative(root, candidate).split(sep).join('/');
+      if (!path || path === '..' || path.startsWith('../')) return null;
+      const escaped = path.replace(/[\\*?\[\]]/g, '\\$&');
+      const pattern = `/${escaped}/`;
+      if (!additionalCleanExclusions.some(item => item.pattern === pattern)) {
+        additionalCleanExclusions.push({ name: directory.name, pattern });
+      }
+      statusExclusions.add(path);
+    }
+  }
+  return { additionalCleanExclusions, statusExclusions: [...statusExclusions] };
+}
+
+function remainingGitStatusPaths(statusPorcelainZ: string): string[] {
+  const records = statusPorcelainZ.split('\0').filter(Boolean);
+  const paths: string[] = [];
+  for (let i = 0; i < records.length; i++) {
+    const record = records[i]!;
+    if (!/^[ MADRCU?!][ MADRCU?!] /.test(record)) continue;
+    paths.push(record.slice(3));
+    if (/[RC]/.test(record.slice(0, 2))) i++;
+  }
+  return paths;
+}
+
 export interface WarmWorkerRunFile {
   file: string;
   cutSha: string;
@@ -33,6 +105,7 @@ export interface WarmWorkerRunFile {
   deadlineAt: number;
 }
 export type WarmWorkerFileRunner = (request: WarmWorkerRunFile) => Promise<number>;
+type WarmWorkerGitResult = { status: number | null; stdout?: string | null };
 
 /** Recheck the source bytes before every request, not only at Pod init. */
 export function warmWorkerSourceMatches(repoDir: string, cutSha: string, lockHash: string): boolean {
@@ -71,12 +144,13 @@ export class WarmWorkerRuntime {
     artifactsRoot: string;
     workerId: string;
     runFile: WarmWorkerFileRunner;
+    runGit?: (args: readonly string[]) => WarmWorkerGitResult;
     removeScratch?: (path: string) => void;
     now?: () => number;
   }) {}
 
   handle(command: WarmWorkerCommand): Promise<WarmWorkerOutcome> {
-    const next = this.tail.then(() => this.execute(command)).catch((): WarmWorkerOutcome => {
+    const next = this.tail.then(() => this.execute(command)).catch((error): WarmWorkerOutcome => {
       this.quarantined = true;
       return { reply: null, quarantineWorker: true, reason: 'execution-error' };
     });
@@ -131,6 +205,18 @@ export class WarmWorkerRuntime {
     if (!artifactsDir.startsWith(`${artifactsRoot}${sep}`) || existsSync(artifactsDir)) {
       return { reply: null, quarantineWorker: false, reason: 'invalid-command' };
     }
+    const runtimeExclusions = runtimeDirectoryExclusions(repo, resolve(this.options.repoDir), [
+      { name: 'worker scratch directory', path: this.options.scratchDir },
+      { name: 'worker artifacts directory', path: artifactsRoot },
+    ]);
+    if (!runtimeExclusions) {
+      this.quarantined = true;
+      try { debug.log('pod.reuse', 'clean-failed', {
+        runId: command.runId, attemptId: command.attemptId, workerId: command.workerId,
+        reason: 'unsafe-runtime-directory', remainingPaths: [],
+      }, { level: 'warn' }); } catch { /* observation cannot revive an unsafe worker */ }
+      return { reply: null, quarantineWorker: true, reason: 'cleanup-failed', artifactsDir };
+    }
     mkdirSync(this.options.scratchDir, { recursive: true });
     mkdirSync(artifactsRoot, { recursive: true });
     mkdirSync(artifactsDir, { recursive: true, mode: 0o700 });
@@ -180,6 +266,74 @@ export class WarmWorkerRuntime {
       if (reason !== 'complete') break;
     }
     if (now() >= command.deadlineAt) reason = 'execution-error';
+    const sourceMatchedBeforeCleanup = warmWorkerSourceMatches(repo, command.cutSha, command.key.lockHash);
+    // A worker accepts another request only after restoring the pinned source and removing prior-request artifacts.
+    const cleanupPlan = decidePodReuseCleanup({
+      base: command.cutSha,
+      resetExitCode: 0,
+      cleanExitCode: 0,
+      statusExitCode: 0,
+      statusPorcelain: '',
+      ...runtimeExclusions,
+    });
+    const git = (args: readonly string[]): WarmWorkerGitResult => {
+      try {
+        return this.options.runGit?.(args) ?? spawnSync('git', [...args], {
+          cwd: repo, encoding: 'utf8', env: withoutGitEnvironment(), maxBuffer: 16 * 1024 * 1024,
+        });
+      } catch {
+        return { status: null, stdout: null };
+      }
+    };
+    const rootMatches = () => {
+      const top = git(['rev-parse', '--show-toplevel']);
+      if (top.status !== 0 || !top.stdout?.trim()) return false;
+      try { return realpathSync(top.stdout.trim()) === repo; } catch { return false; }
+    };
+    const discard = (reason: string, remainingPaths: readonly string[] = []): WarmWorkerOutcome => {
+      this.quarantined = true;
+      try { debug.log('pod.reuse', 'clean-failed', {
+        runId: command.runId,
+        attemptId: command.attemptId,
+        workerId: command.workerId,
+        reason,
+        remainingPaths: remainingPaths.slice(0, 5),
+      }, { level: 'warn' }); } catch { /* observation cannot revive an unsafe worker */ }
+      return { reply: null, quarantineWorker: true, reason: 'cleanup-failed', artifactsDir };
+    };
+    if (!rootMatches()) return discard('checkout-root-mismatch');
+    const reset = git(cleanupPlan.resetArgs);
+    if (reset.status !== 0) {
+      const failed = decidePodReuseCleanup({ base: command.cutSha, resetExitCode: reset.status,
+        cleanExitCode: null, statusExitCode: null, statusPorcelain: '', ...runtimeExclusions });
+      return discard(failed.reason ?? 'reset-failed');
+    }
+    if (!rootMatches()) return discard('checkout-root-mismatch');
+    const clean = git(cleanupPlan.cleanArgs);
+    if (clean.status !== 0) {
+      const failed = decidePodReuseCleanup({ base: command.cutSha, resetExitCode: 0,
+        cleanExitCode: clean.status, statusExitCode: null, statusPorcelain: '', ...runtimeExclusions });
+      return discard(failed.reason ?? 'clean-failed');
+    }
+    if (!rootMatches()) return discard('checkout-root-mismatch');
+    const status = git(cleanupPlan.statusArgs);
+    if (status.status === 0 && typeof status.stdout !== 'string') return discard('status-output-missing');
+    const cleanup = decidePodReuseCleanup({
+      base: command.cutSha,
+      resetExitCode: reset.status,
+      cleanExitCode: clean.status,
+      statusExitCode: status.status,
+      statusPorcelain: status.stdout ?? '',
+      remainingPaths: remainingGitStatusPaths(status.stdout ?? ''),
+      ...runtimeExclusions,
+    });
+    if (cleanup.outcome === 'discard') {
+      return discard(cleanup.reason ?? 'unknown', cleanup.remainingPaths);
+    }
+    if (!sourceMatchedBeforeCleanup) {
+      this.quarantined = true;
+      return { reply: null, quarantineWorker: true, reason: 'quarantined', artifactsDir };
+    }
     if (reason !== 'complete') this.quarantined = true;
     if (reason !== 'complete' || files.length !== command.files.length) return { reply: null, quarantineWorker: true, reason, artifactsDir };
     if (!warmWorkerSourceMatches(repo, command.cutSha, command.key.lockHash)) {

package/src/task-orchestrator/surfaces/self-implement-pod.ts

@@ -43,8 +43,9 @@ export const POD_LOGS_KEEP_BYTES = 4_500_000;
  *  POD-NORESULT ⓑ (10-07 · 28 failed rc=2 Jobs read back): every child printed its result line, but one
  *  (si-task-71f68d57f6b7, image 0.2.15) had stderr lines (`[graph] collect fail`) after it, so the old
  *  «last line only» check skipped the flatten and the host kept `ok:false` with no stage or PR number.
- *  Scan back to the newest child result line instead; still append exactly one line. */
-const POD_RESULT_FLATTEN = `bun -e 'const fs=require("fs");const p="/tmp/si.out";const lines=fs.readFileSync(p,"utf8").trimEnd().split("\\n");for(let i=lines.length-1;i>=0;i--){const l=lines[i].trim();if(!l.startsWith("{"))continue;let o;try{o=JSON.parse(l)}catch{continue}if(!o||o.kind!=="self")continue;if(o.result&&typeof o.result==="object"&&!Array.isArray(o.result))fs.appendFileSync(p,"\\n"+JSON.stringify({...o.result,...(typeof o.ok==="boolean"?{ok:o.ok}:{})})+"\\n");break}'`;
+ *  Scan back to a terminal child result; an interim JSON row or successful row on rc≠0 cannot hide a later failure.
+ *  Keep this shell command on one physical line: Job command extraction consumes it as one line. */
+export const POD_RESULT_FLATTEN = `ELANOUS_CHILD_RC="$rc" bun -e ' const fs=require("fs"); const p="/tmp/si.out"; const lines=fs.readFileSync(p,"utf8").trimEnd().split("\\n"); const failed=Number(process.env.ELANOUS_CHILD_RC)!==0; let terminal=null; let appendTerminal=false; let successIndex=-1; for(let i=lines.length-1;i>=0;i--){ const l=lines[i].trim(); if(!l.startsWith("{"))continue; let o; try{o=JSON.parse(l)}catch{continue} if(!o||typeof o!=="object"||Array.isArray(o))continue; const nested=o.kind==="self"&&o.result&&typeof o.result==="object"&&!Array.isArray(o.result); const flat=nested ? {...o.result,...(typeof o.ok==="boolean"?{ok:o.ok}:{})} : o.kind===undefined?o:null; if(!flat||typeof flat.ok!=="boolean"||typeof flat.stage!=="string"||!flat.stage||flat.stage==="running")continue; if(failed&&flat.ok===true){successIndex=i;break;} terminal=flat; appendTerminal=i!==lines.length-1||flat!==o; break; } let reason=""; let reasonIndex=-1; if(failed){ for(let i=successIndex>=0?successIndex+1:0;i<lines.length;i++){ const l=lines[i].trim(); if(/골 완료 경계 누락|self-implement PR guard 실패|draft PR 생성 실패/u.test(l)){ reason=l;reasonIndex=i; }else if(/^(Error:|❌)/u.test(l)&&(!reason||lines.slice(reasonIndex+1,i).some(x=>x.trim().startsWith("[retry]")||x.trim().startsWith("재시도:")))){ reason=l;reasonIndex=i; } } } if(terminal){ if(appendTerminal)fs.appendFileSync(p,"\\n"+JSON.stringify(terminal)+"\\n"); }else if(failed){ if(reason)fs.appendFileSync(p,"\\n"+JSON.stringify({stage:reason.includes("골 완료 경계 누락")?"preflight-blocked":"error",ok:false,error:lines.slice(reasonIndex).join("\\n").trim().slice(0,4000)})+"\\n"); else if(successIndex>=0)fs.appendFileSync(p,"\\n"+JSON.stringify({stage:"error",ok:false,error:"child exited rc="+process.env.ELANOUS_CHILD_RC+" after a success result without a terminal failure result"})+"\\n"); }'`;
 
 export const POD_JOB_DEADLINE_SECONDS = 10_800;
 
@@ -240,11 +241,11 @@ export interface PodSpawnOptions {
   memoryAdvice?: () => PodMemoryAdvice;
 }
 
-export function defaultKubectl(args: readonly string[], input?: string): { status: number | null; stdout: string; stderr: string } {
+export function defaultKubectl(args: readonly string[], input?: string, timeoutMs = 120_000): { status: number | null; stdout: string; stderr: string } {
   // 셸 프록시가 kubectl 의 로컬 API 요청을 가로챈다(2026-09-25 실측) — 자식 env 에서 뺀다.
   const env = { ...process.env };
   for (const k of ['HTTPS_PROXY', 'https_proxy', 'HTTP_PROXY', 'http_proxy', 'ALL_PROXY', 'all_proxy']) delete env[k];
-  const r = spawnSync('kubectl', [...args], { encoding: 'utf8', input, env, timeout: 120_000, maxBuffer: LEASE_KUBECTL_MAX_BUFFER });
+  const r = spawnSync('kubectl', [...args], { encoding: 'utf8', input, env, timeout: timeoutMs, maxBuffer: LEASE_KUBECTL_MAX_BUFFER });
   const error = (r.error as NodeJS.ErrnoException | undefined)?.code === 'ENOBUFS'
     ? `kubectl 출력 너무 큼 (ENOBUFS; maxBuffer=${LEASE_KUBECTL_MAX_BUFFER} bytes)`
     : r.error ? String(r.error) : '';
@@ -1080,7 +1081,7 @@ export function podJobManifest(o: { name: string; namespace: string; image: stri
       ? `echo "ELANOUS_AUTHOR_ON_POD started host=$(hostname) at=$(date -u +%Y-%m-%dT%H:%M:%SZ)"; author_t0=$(date +%s); ${o.authorGrade === 'lite' || o.authorGrade === 'full' ? `ELANOUS_AUTHOR_GRADE=${o.authorGrade} ` : ''}elanous harness say --substrate local --json${quotedAsk}${quotedChildLlm} -- "$(cat /creds/feature)" > /tmp/si.out 2>&1 & si_pid=$!; wait "$si_pid"; rc=$?; ${RUN_END}; echo "ELANOUS_AUTHOR_ON_POD finished host=$(hostname) rc=$rc seconds=$(( $(date +%s) - author_t0 ))"; ${POD_RESULT_FLATTEN}`
       : goalPath
       ? `elanous harness ask ${goalPath} --json${quotedAsk}${quotedChildLlm} > /tmp/si.out 2>&1 & si_pid=$!; wait "$si_pid"; rc=$?; ${RUN_END}; ${POD_RESULT_FLATTEN}`
-      : `export ${OLD_DOOR_STAMP_ENV}=self-implement; elanous self implement "$(cat /creds/feature)" --json ${quoted} > /tmp/si.out 2>&1 & si_pid=$!; wait "$si_pid"; rc=$?; ${RUN_END}`,
+      : `export ${OLD_DOOR_STAMP_ENV}=self-implement; elanous self implement "$(cat /creds/feature)" --json ${quoted} > /tmp/si.out 2>&1 & si_pid=$!; wait "$si_pid"; rc=$?; ${RUN_END}; ${POD_RESULT_FLATTEN}`,
     'cat /tmp/si.out',
     '[ -f scripts/usage-rollup.ts ] && bun scripts/usage-rollup.ts --since 12h || echo "ELANOUS_USAGE_ROLLUP {\"measured\":false,\"reason\":\"no rollup script\"}"',
     // A long run's log export can pass the 5MB artifact limit; skipping it whole left no window into why a
@@ -1174,6 +1175,7 @@ if [ "$found" -eq 0 ]; then echo ELANOUS_RUN_LEDGER_NONE; fi`,
               ...(o.runId ? [{ name: 'ELANOUS_RUN_ID', value: o.runId }] : []),
               ...(o.parentRunId ? [{ name: 'ELANOUS_PARENT_RUN_ID', value: o.parentRunId }] : []),
               ...(o.workIdentity?.taskCard ? [{ name: 'ELANOUS_TASK_CARD_ID', value: o.workIdentity.taskCard }] : []),
+              ...(o.workIdentity?.slotId ? [{ name: 'ELANOUS_POD_SLOT_ID', value: o.workIdentity.slotId }] : []),
               { name: 'ELANOUS_SUBSTRATE', value: 'pod' },
               ...Object.entries(controlInboxEnv(POD_CONTROL_INBOX_DIR)).map(([name, value]) => ({ name, value })),
               // ⭐ 런 출처(🅣 RFC run-origin §A3 · #20457/#20468 칸 이름) — Pod 는 자기 elanous_id 를 쓰지 않고 «띄운 감독기»의 hostId 를 물려받는다.

package/src/tui/chat/execution-badge.ts

@@ -12,7 +12,7 @@
 // completion-line presentation. dashboard/execution-badge.ts is now a
 // re-export shim for backward compat until callers migrate.
 
-import { currentRouteDecision } from '../../llm/route-decision.js';
+import { currentRouteDecision, routeFallbackLabel } from '../../llm/route-decision.js';
 import { getUserConfig } from '../../user-config.js';
 import { effectiveReasoningLevel, modelSupportsReasoning } from '../../llm.js';
 import { executionBadge } from '../../telegram-exec-footer.js';
@@ -24,6 +24,10 @@ import { executionBadge } from '../../telegram-exec-footer.js';
  *  execution footer uses, so both surfaces report the same truth. */
 export function resolveDashboardExecutionBadge(): string | undefined {
   const cfg = getUserConfig();
+  // 폴백(TUI-MODEL-BADGE-ACTUAL · 10-16) — 턴이 고른 모델과 «실제로 응답한» 모델이 다르면 «sol → grok».
+  //   생각 깊이는 결정 쪽 값이라 넘어간 공급자엔 맞지 않는다 → 폴백 배지엔 안 붙인다.
+  const fallback = routeFallbackLabel('dashboard');
+  if (fallback) return executionBadge({ model: fallback });
   const decision = currentRouteDecision('dashboard');
   const model = decision?.model || cfg.llm.model;
   if (!model) return undefined;

package/src/tui/input-lag-probe.ts

@@ -0,0 +1,230 @@
+// TUI-TYPING-LAG-OBS — 타이핑 지연을 «재는» 관측(#28063 이 «실물 불가» 로 착지한 빈칸).
+//
+// 계약(UX SCENARIO-MOCK-RIG 와 합의 · ⛔ 이름·칸을 바꾸지 않는다):
+//   debug.log('tui.input-lag', 'measured', {
+//     phase: 'keystroke' | 'turn-start', keyToPaintMs?, loopDelayMs: { p99, max }, turnId?, busy, sampled })
+//
+// - keystroke: stdin 키 수신 → 그 뒤 첫 화면 칠(render · typeahead echo) 의 write 호출까지.
+//   이벤트 루프가 막힌 동안 온 키는 막힘이 풀린 뒤에야 'data' 로 배달되므로, 배달 시각만 보면
+//   막힌 시간이 빠진다. ⇒ 20ms 심장박동으로 «배달 전 기다린 시간» 을 추정해 더한다(상한 추정 ·
+//   오차 ≤ 심장박동 간격). 기본 표본 = 10키 중 1(`sampled: 0.1`) · 50ms 이상은 항상 남긴다.
+// - turn-start: turn-preamble 을 감싼 창(시작 → 끝 + 박동 두 번)의 루프 지연(`sampled: 1`) · busy 는 창 끝 값.
+// - loopDelayMs: 그 창의 루프 지연 p99/max(ms) — 같은 20ms 심장박동의 드리프트 표본(최근 ~20초 고리).
+//   ⚠️ perf_hooks.monitorEventLoopDelay 를 «안» 쓴다: Bun 1.4.2 에서 동작은 하지만 인스턴스들이
+//   «히스토그램 하나를 공유» 하고 한 인스턴스의 disable() 이 전부를 멈춘다(node-c 실측 · 라이브에서
+//   turn-start 창을 닫은 뒤 keystroke 창이 {p99:0,max:0} 만 찍었다). 창이 겹치는 이 프로브엔 못 쓴다.
+//
+// 키 경로 비용: 키 청크마다 시각 호출 1회 ⊕ 비교 몇 개 · 할당 0(대기 중 키는 숫자 둘로 쥔다).
+// 화면 칠마다: 대기 키가 없으면 비교 1회. 로그 객체는 «남길 때만» 만든다.
+// 프로브가 등록되지 않으면(대시보드 밖 · 시험) 모든 훅은 null 검사 한 번으로 끝난다.
+
+export const INPUT_LAG_CATEGORY = 'tui.input-lag';
+export const INPUT_LAG_EVENT = 'measured';
+/** 표본 비율의 분모 — 측정한 키 N개 중 1개를 남긴다. */
+export const INPUT_LAG_SAMPLE_EVERY = 10;
+/** 이 ms 이상 걸린 키는 표본과 무관하게 항상 남긴다. */
+export const INPUT_LAG_ALWAYS_MS = 50;
+const HEARTBEAT_MS = 20;
+/** 루프가 «안 막힌 채» 이만큼 지나도 칠이 없으면 그 키는 칠을 안 낳은 키(무시 키 등)로 보고 놓는다 —
+ *  안 그러면 한참 뒤 다른 칠이 그 키에 붙어 수 분짜리 가짜 지연이 찍힌다(라이브 실측 150,963ms). */
+export const INPUT_LAG_ABANDON_MS = 1000;
+/** 루프 지연 표본 고리 크기 — 20ms 박동이면 ~20초. */
+const LOOP_RING = 1024;
+
+export interface LoopDelayMs { p99: number; max: number }
+
+export interface InputLagMeasured {
+  phase: 'keystroke' | 'turn-start';
+  keyToPaintMs?: number;
+  loopDelayMs: LoopDelayMs;
+  turnId?: string;
+  busy: boolean;
+  sampled: number;
+}
+
+interface TimerLike { unref?: () => void }
+
+export interface InputLagProbeOptions {
+  log: (category: string, event: string, data: InputLagMeasured) => void;
+  isBusy: () => boolean;
+  now?: () => number;
+  sampleEvery?: number;
+  alwaysMs?: number;
+  heartbeatMs?: number;
+  setIntervalFn?: (fn: () => void, ms: number) => TimerLike;
+  clearIntervalFn?: (timer: TimerLike) => void;
+  setTimeoutFn?: (fn: () => void, ms: number) => TimerLike;
+}
+
+export interface InputLagProbe {
+  /** 키 `count` 개가 한 번에 도착했다(한 stdin 청크가 여러 키를 낳을 수 있다). */
+  noteKey(count?: number): void;
+  notePaint(): void;
+  measureTurnStart<T>(fn: () => T, turnId?: string): T;
+  /** 같은 심장박동을 다른 관측(턴 시작 덩어리 · `dashboard/turn-start-segments.ts`)이 읽는 창 — 시계·할당 0. */
+  beats: InputLagBeatView;
+  dispose(): void;
+}
+
+export interface InputLagBeatView {
+  heartbeatMs: number;
+  /** 마지막 박동 시각(같은 `now` 시계). */
+  lastBeatAt(): number;
+  /** `since` 뒤 박동들의 루프 지연 p99/max — 남길 때만 부른다. */
+  loopDelaySince(since: number): LoopDelayMs;
+}
+
+const round1 = (ms: number): number => Math.round(Math.max(0, ms) * 10) / 10;
+
+/** 드리프트 표본 고리에서 `since` «뒤»(초과) 표본의 p99/max. 남길 때만 부른다(그때만 할당). */
+function readLoopDelay(drift: Float64Array, at: Float64Array, count: number, head: number, since: number): LoopDelayMs {
+  const picked: number[] = [];
+  for (let i = 0; i < count; i++) {
+    const idx = (head - 1 - i + LOOP_RING) % LOOP_RING;
+    if (at[idx]! <= since) break;
+    picked.push(drift[idx]!);
+  }
+  if (picked.length === 0) return { p99: 0, max: 0 };
+  picked.sort((x, y) => x - y);
+  return {
+    // 최근순위(nearest-rank) p99 — 짧은 창([0, 300])에서도 큰 막힘을 내림으로 잃지 않는다.
+    p99: round1(picked[Math.max(0, Math.ceil(picked.length * 0.99) - 1)]!),
+    max: round1(picked[picked.length - 1]!),
+  };
+}
+
+export function createInputLagProbe(opts: InputLagProbeOptions): InputLagProbe {
+  const now = opts.now ?? (() => performance.now());
+  const sampleEvery = Math.max(1, Math.floor(opts.sampleEvery ?? INPUT_LAG_SAMPLE_EVERY));
+  const alwaysMs = opts.alwaysMs ?? INPUT_LAG_ALWAYS_MS;
+  const heartbeatMs = opts.heartbeatMs ?? HEARTBEAT_MS;
+  const setIntervalFn = opts.setIntervalFn ?? ((fn, ms) => setInterval(fn, ms));
+  const clearIntervalFn = opts.clearIntervalFn ?? ((t) => clearInterval(t as ReturnType<typeof setInterval>));
+  const setTimeoutFn = opts.setTimeoutFn ?? ((fn, ms) => setTimeout(fn, ms));
+
+  // 칠을 기다리는 첫 키(뒤따르는 키는 같은 칠을 기다리므로 첫 키가 최악값이다).
+  let pendingAt = -1;
+  let pendingWaitMs = 0;
+  // 심장박동 — 마지막 박동 시각 ⊕ 방금 끝난 막힘(같은 루프 회전에서 키가 배달되면 그만큼 기다렸다).
+  let lastBeatAt = now();
+  let stallMs = 0;
+  let stallEndedAt = -Infinity;
+  const ringDrift = new Float64Array(LOOP_RING);
+  const ringAt = new Float64Array(LOOP_RING);
+  let ringHead = 0;
+  let ringCount = 0;
+  let keyWindowStart = lastBeatAt;
+  const loopDelaySince = (since: number): LoopDelayMs => readLoopDelay(ringDrift, ringAt, ringCount, ringHead, since);
+  const beat = setIntervalFn(() => {
+    const t = now();
+    const drift = t - lastBeatAt - heartbeatMs;
+    ringDrift[ringHead] = Math.max(0, drift);
+    ringAt[ringHead] = t;
+    ringHead = (ringHead + 1) % LOOP_RING;
+    if (ringCount < LOOP_RING) ringCount += 1;
+    if (drift > heartbeatMs) { stallMs = drift; stallEndedAt = t; }
+    lastBeatAt = t;
+    if (pendingAt >= 0 && t - Math.max(pendingAt, stallEndedAt) > INPUT_LAG_ABANDON_MS) pendingAt = -1;
+  }, heartbeatMs);
+  beat.unref?.();
+
+  // 표본 줄 사이에 들어온 실제 키 수(측정 횟수가 아니다) — 표본 줄을 남기면 sampleEvery 의 나머지를 이월한다.
+  let keysSinceLine = 0;
+  let disposed = false;
+
+  return {
+    noteKey(count = 1): void {
+      if (disposed) return;
+      keysSinceLine += count;
+      if (pendingAt >= 0) return;
+      const t = now();
+      // 박동이 밀려 있으면 루프가 아직 막혀 있었다. 마지막 박동이 막힘을 끝낸 박동이면(그 뒤 평상 박동이
+      // 아직 없으면) 막힘 동안 쌓인 키가 이제 배달되는 중이다 — 막힘 ⊕ 그 뒤 흐른 시간(상한 추정).
+      const overdue = t - lastBeatAt - heartbeatMs;
+      const justStalled = stallEndedAt === lastBeatAt ? stallMs + (t - stallEndedAt) : 0;
+      pendingAt = t;
+      pendingWaitMs = Math.max(0, overdue, justStalled);
+    },
+    notePaint(): void {
+      if (pendingAt < 0) return;
+      const keyToPaintMs = now() - pendingAt + pendingWaitMs;
+      pendingAt = -1;
+      // 50ms↑ 강제 줄은 표본을 소비하지 않는다(표본이 때가 됐어도 다음 칠로 넘긴다) ·
+      // 표본 줄은 넘친 키를 다음 표본으로 이월한다.
+      const forced = keyToPaintMs >= alwaysMs;
+      if (!forced) {
+        if (keysSinceLine < sampleEvery) return;
+        keysSinceLine %= sampleEvery;
+      }
+      const t = now();
+      const loopDelayMs = loopDelaySince(keyWindowStart);
+      keyWindowStart = t;
+      opts.log(INPUT_LAG_CATEGORY, INPUT_LAG_EVENT, {
+        phase: 'keystroke',
+        keyToPaintMs: round1(keyToPaintMs),
+        loopDelayMs,
+        busy: opts.isBusy(),
+        sampled: 1 / sampleEvery,
+      });
+    },
+    measureTurnStart<T>(fn: () => T, turnId?: string): T {
+      if (disposed) return fn();
+      const windowStart = now();
+      const finish = (): void => {
+        // busy 는 창이 닫히는 «지금» 잡는다 — 박동 두 번 뒤 읽으면 그 사이 바뀐 상태가 창에 붙는다.
+        const busy = opts.isBusy();
+        // 동기 막힘은 루프가 풀린 «뒤» 첫 박동에 찍힌다 — 박동 두 번만큼 기다렸다 읽는다.
+        const timer = setTimeoutFn(() => {
+          if (disposed) return;
+          const loopDelayMs = loopDelaySince(windowStart);
+          opts.log(INPUT_LAG_CATEGORY, INPUT_LAG_EVENT, {
+            phase: 'turn-start',
+            loopDelayMs,
+            ...(turnId !== undefined ? { turnId } : {}),
+            busy,
+            sampled: 1,
+          });
+        }, heartbeatMs * 2);
+        timer.unref?.();
+      };
+      try {
+        return fn();
+      } finally {
+        finish();
+      }
+    },
+    beats: {
+      heartbeatMs,
+      lastBeatAt: () => lastBeatAt,
+      loopDelaySince,
+    },
+    dispose(): void {
+      if (disposed) return;
+      disposed = true;
+      pendingAt = -1;
+      clearIntervalFn(beat);
+    },
+  };
+}
+
+// ── 등록 자리 — 대시보드가 하나 등록하고, 저수준 훅(tui.ts · chat · turn-preamble)은 부르기만 한다. ──
+let activeProbe: InputLagProbe | null = null;
+
+export function setInputLagProbe(probe: InputLagProbe | null): void {
+  activeProbe = probe;
+}
+
+/** stdin(또는 주입) 키 `count` 개 수신 — 키 경로 훅. 등록이 없으면 null 검사 한 번. */
+export function noteInputLagKey(count = 1): void {
+  activeProbe?.noteKey(count);
+}
+
+/** 화면 칠(write 호출) 직후 — 칠 경로 훅. */
+export function noteInputLagPaint(): void {
+  activeProbe?.notePaint();
+}
+
+/** turn-preamble 창을 잰다. 등록이 없으면 fn 만 부른다. */
+export function measureInputLagTurnStart<T>(fn: () => T, turnId?: string): T {
+  return activeProbe ? activeProbe.measureTurnStart(fn, turnId) : fn();
+}

package/src/tui.ts

@@ -5,6 +5,7 @@
 import chalk from 'chalk';
 import { StringDecoder } from 'node:string_decoder';
 import { perf } from './perf-counters.js';
+import { noteInputLagKey, noteInputLagPaint } from './tui/input-lag-probe.js';
 import { debug } from './debug/log.js';
 
 // ── ANSI escape sequences ──
@@ -911,6 +912,7 @@ export function readKey(source: KeyTraceSource = 'main'): Promise<Key> {
       // split across chunk boundaries need a pending buffer that belongs
       // to this stream alone.
       const keys = _stdinParser.push(data);
+      if (keys.length > 0) noteInputLagKey(keys.length);
 
       // 2026-04-30 — also drain `_keyQueue` here so an `injectKey`
       // call that happened while `readKey` was already awaiting on
@@ -963,6 +965,7 @@ export function readKey(source: KeyTraceSource = 'main'): Promise<Key> {
  *  §8.6 — "(A) auto-Enter via injectKey" approach. */
 export function injectKey(key: Key): boolean {
   if (!_raw) return false;
+  noteInputLagKey();
   _keyQueue.push(key);
   _injectedKeys.add(key);
   // Wake any in-flight readKey awaiting on stdin by emitting an empty
@@ -1109,6 +1112,7 @@ export function render(lines: string[], opts: RenderOptions = {}): void {
   }
   perf.recordStdoutWrite(buf.length, true);
   perf.markDrawEnd();
+  noteInputLagPaint();
 
   _lastFrameLines = lines.slice(0, lineCount);
   _lastFrameRows = rows;