elanous 0.2.29 → 0.2.32

package/src/dashboard/slash-runtime/help-from-registry.ts

@@ -16,7 +16,8 @@ const ESSENTIAL_KEYS = [
   ['Home / End', 'Move to start / end of line'],
   ['Ctrl+A / E', 'Move to start / end of line'],
   ['PgUp / PgDn', 'Scroll chat log'],
-  ['Ctrl+↑', 'Recall a queued line (Enter while answering queues it)'],
+  // 10-14 — 줄 수는 그대로(행 예산) · 큐는 다음 도구 경계에 들어가고, 빈 Enter 가 «지금 밀어 넣기»다.
+  ['Ctrl+↑', 'Recall all queued lines (Enter while answering queues · empty Enter pushes now)'],
 ] as const;
 
 function fitLine(text: string, width: number): string {

package/src/dashboard/slash-runtime/index.ts

@@ -13,3 +13,16 @@ export {
   type SkillToolSlashExecutor,
   type SkillToolSlashResult,
 } from './dashboard-handlers.js';
+// TUI-SLASH-SPLIT-MISSION(D4b) — 새 집 src/tui/slash/mission.ts 의 공개 심볼을 옛 입구에서도 낸다(re-export shim · RFC A5).
+export {
+  handleMissionSlash,
+  registerMissionSlash,
+  type MissionSlashContext,
+} from '../../tui/slash/mission.js';
+// TUI-SLASH-SPLIT-TERM(D4b) — 새 집 src/tui/slash/term.ts 의 공개 심볼을 옛 입구에서도 낸다(re-export shim · RFC A5).
+export {
+  handleTermSlash,
+  registerTermSlash,
+  type TermSlashContext,
+  type TermSlashHost,
+} from '../../tui/slash/term.js';

package/src/dashboard/turn-busy-teardown.ts

@@ -0,0 +1,50 @@
+// ── 턴 busy 표지 마감 (TUI-STALE-BUSY-MARKER · 0.2.31 · tui-op-issues #36·#37·#45·#54·#55·#58) ──
+//
+// S: 턴이 시작되면 `streamingInFlight = true` ⊕ `reportTuiTurn('busy')` 가 켜지고, 마감 closure 가
+//    끄기 전까지 외부 입력 대기열(`isTurnActive`)·`eln pty state` 는 «바쁨»으로 본다.
+// C: 마감 closure 안의 한 단계가 던지면(10-14 «✘ 실패 line.startsWith») 끄는 줄에 못 닿아 70분+ busy 가 남았다.
+//    #27721 이 settle 단계 하나를 try/finally 로 감쌌지만, 그 «앞» 단계(키 리스너 떼기 · ESC 게이트 정리)는
+//    여전히 맨몸이었다 — 거기서 던지면 키 층은 유휴(리스너 떨어짐)·턴 층은 busy 인 이원 판정이 그대로 재현된다.
+//    그리고 실패는 `dashboard.turn settle-failed` 한 곳에서만 보였다(#58 — 턴 본문 실패는 tui 범주 0).
+// A: 마감 단계마다 이 함수로 격리해 «다음 단계 ⊕ idle 전이»가 반드시 돌게 하고,
+//    던진 것은 한 범주 `tui.turn turn-threw {error, phase}` 로 남긴다.
+
+import { debug, redactSecretText } from '../debug/log.js';
+
+/** 4번째 인자로 `{ level: 'warn' }` 를 받는다 — 주입 기록기도 warn 수준을 그대로 넘겨야 한다(#58). */
+export type TurnThrewLog = (
+  category: string,
+  event: string,
+  payload: Record<string, unknown>,
+  opts?: { level?: 'warn' },
+) => void;
+
+const ERROR_HEAD_CHARS = 200;
+
+const warnLog: TurnThrewLog = (category, event, payload, opts) => debug.log(category, event, payload, opts);
+
+/** 턴 경로에서 던진 것을 한 범주로 남긴다(warn — #58 «warn/error 0» 의 몫). 관측 실패가 턴 마감을 막지 않는다. */
+export function logTurnThrew(phase: string, err: unknown, log: TurnThrewLog = warnLog): void {
+  try {
+    const message = err instanceof Error ? err.message : String(err);
+    const stackHead = err instanceof Error
+      ? err.stack?.split('\n').slice(1, 3).map((line) => line.trim()).join(' | ')
+      : undefined;
+    log('tui.turn', 'turn-threw', {
+      error: redactSecretText(message).slice(0, ERROR_HEAD_CHARS),
+      phase,
+      ...(stackHead ? { stackHead: redactSecretText(stackHead) } : {}),
+    }, { level: 'warn' });
+  } catch { /* fail-soft — 관측이 마감을 막지 않는다 */ }
+}
+
+/** 턴 마감의 한 단계 — 던져도 삼키고 `turn-threw` 로 남긴다. 다음 단계·idle 전이는 계속 돈다. */
+export function runTurnTeardownStep(phase: string, step: () => void, log?: TurnThrewLog): boolean {
+  try {
+    step();
+    return true;
+  } catch (err) {
+    logTurnThrew(phase, err, log);
+    return false;
+  }
+}

package/src/dashboard/turn-preamble.ts

@@ -39,6 +39,8 @@ import {
 } from '../agent/task-notification.js';
 import type { getUserConfig } from '../user-config.js';
 import { isNativeStructureEnabledForProvider, resolveActiveProvider } from '../user-config.js';
+import { measureInputLagTurnStart } from '../tui/input-lag-probe.js';
+import { effectiveInstanceRoot, prodInstanceRoot } from '../instance/resolve.js';
 
 type UserConfig = ReturnType<typeof getUserConfig>;
 
@@ -61,8 +63,6 @@ export interface DashboardTurnPreambleContext {
   modelFamily?: ModelFamily;
   /** Current request session ID. It is injected only while this preamble is built for the turn. */
   sessionId?: string;
-  /** Catalog richness for non-dashboard callers; the essential dashboard passes false. */
-  rich?: boolean;
   /** Active tool names for session-specific guidance (Wave 3,
    *  2026-05-04). When provided, the universal preamble emits per-tool
    *  one-liner directives (e.g. AskUserQuestion → use for tool-deny
@@ -85,40 +85,108 @@ export function buildControllerSystemMessage(controller: string, channels?: stri
   };
 }
 
+/** How old a git snapshot the TUI preamble may serve while it rebuilds in the background.
+ *  Edits (post-Edit force refresh) and HEAD moves invalidate it earlier; the dashboard's
+ *  5s git tick keeps it younger than this so an idle-then-type turn still hits. */
+const DASHBOARD_GIT_SNAPSHOT_STALE_MS = 60_000;
+
+/** TUI-TYPING-LAG-OBS 시험 seam — 이 ms 만큼 turn-preamble 을 «동기로» 막아 타이핑 지연을 일으킨다.
+ *  운영 기본 0. 켜는 길 둘: ux-sim·단위 시험은 `setPreambleSyncBlockMsForTesting` · 격리 TUI 는
+ *  env `ELANOUS_TEST_PREAMBLE_SYNC_BLOCK_MS`(⛔ test 우주에서만 읽는다 — 운영 우주에선 무시).
+ *  test 우주 = 이 프로세스의 실효 뿌리가 운영 집이 아닌 것. `--test` 플래그만 보면 pty-drive 가
+ *  `--test` 를 `--config-dir <격리 뿌리>` 로 바꿔 띄운 시험 자식에서 seam 이 안 켜진다. */
+export const PREAMBLE_SYNC_BLOCK_ENV = 'ELANOUS_TEST_PREAMBLE_SYNC_BLOCK_MS';
+let preambleSyncBlockOverrideMs: number | null = null;
+
+export function setPreambleSyncBlockMsForTesting(ms: number | null): void {
+  preambleSyncBlockOverrideMs = ms;
+}
+
+export function preambleSyncBlockMs(
+  env: NodeJS.ProcessEnv = process.env,
+  instanceRoot: () => string = effectiveInstanceRoot,
+): number {
+  if (preambleSyncBlockOverrideMs !== null) return Math.max(0, preambleSyncBlockOverrideMs);
+  const raw = env[PREAMBLE_SYNC_BLOCK_ENV];
+  if (!raw || instanceRoot() === prodInstanceRoot()) return 0;
+  const ms = Number(raw);
+  return Number.isFinite(ms) && ms > 0 ? ms : 0;
+}
+
+/** 일부러 이벤트 루프를 동기로 막는다(시험 seam). 시계를 돌며 도는 바쁜 루프 대신 `Atomics.wait` —
+ *  CPU 를 태우지 않고, 시험이 시계를 가짜로 바꿔도 끝난다. */
+function blockPreambleSync(ms: number): void {
+  if (ms <= 0) return;
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
 export function buildDashboardTurnPreamble(
   ctx: DashboardTurnPreambleContext,
 ): LLMMessage[] {
+  return measureInputLagTurnStart(() => {
+    blockPreambleSync(preambleSyncBlockMs());
+    return buildDashboardTurnPreambleUnmeasured(ctx);
+  });
+}
+
+/** TURN-START-BLOCK-REST 1단계 — 빌더마다 걸린 ms(0.1ms 반올림)를 `chat.turn-preamble built` 의
+ *  `builderMs` 칸에 싣는다. 시계는 빌더마다 앞뒤 한 번씩이고, `built` 이벤트가 안 나가는
+ *  (`debug.enabled` 꺼짐) 턴에서는 재지 않는다. 이 함수의 빌더는 전부 동기라 잰 ms 가 곧
+ *  이벤트 루프를 막은 시간이다(`builderMsKind: 'sync'`). */
+type BuilderMs = Record<string, number>;
+
+function timed<T>(ms: BuilderMs | null, name: string, fn: () => T): T {
+  if (ms === null) return fn();
+  const t0 = performance.now();
+  try {
+    return fn();
+  } finally {
+    ms[name] = Math.round((performance.now() - t0) * 10) / 10;
+  }
+}
+
+function buildDashboardTurnPreambleUnmeasured(
+  ctx: DashboardTurnPreambleContext,
+): LLMMessage[] {
+  const builderMs: BuilderMs | null = debug.enabled ? {} : null;
+  const startedAt = builderMs === null ? 0 : performance.now();
   // Universal preamble — surface-agnostic anchor (AGENTS.md +
   // CLAUDE.md). Spread first so the project context lands BEFORE any
   // surface-specific guidance, mirroring Claude Code's Phase 0
   // ordering. Returns [] when neither anchor file exists, so the
   // spread is a no-op outside actual project repos (tests etc.).
-  const universalPreamble = buildUniversalPreamble({
+  const universalPreamble = timed(builderMs, 'universal', () => buildUniversalPreamble({
     cwd: ctx.cwd,
     ...(ctx.modelFamily !== undefined ? { modelFamily: ctx.modelFamily } : {}),
     ...(ctx.enabledTools !== undefined ? { enabledTools: ctx.enabledTools } : {}),
-  });
+  }));
   // 🪪 L1 — 자리 부트 카드(세션마다 한 번 만든 스냅샷). 정체성(앵커) 바로 뒤. 자리가 아니면 [].
-  const seatBootSystemMsgs = ctx.seatBoot
-    ? buildSeatBootSystemMessages(
+  const seatBoot = ctx.seatBoot;
+  const seatBootSystemMsgs = seatBoot
+    ? timed(builderMs, 'seatBoot', () => buildSeatBootSystemMessages(
       { cwd: ctx.cwd, ...(ctx.sessionId !== undefined ? { sessionId: ctx.sessionId } : {}) },
-      ctx.seatBoot === true ? {} : ctx.seatBoot,
-    )
+      seatBoot === true ? {} : seatBoot,
+    ))
     : [];
-  const planModeSystemMsgs = buildPlanModeSystemMessages();
-  const askSystemMsgs = buildExecutionAskSystemMessages() as LLMMessage[];
-  const approvalSystemMsgs = buildApprovalPolicySystemMessages() as LLMMessage[];
-  const sandboxSystemMsgs = buildSandboxEscalationSystemMessages() as LLMMessage[];
+  const planModeSystemMsgs = timed(builderMs, 'planMode', () => buildPlanModeSystemMessages());
+  const askSystemMsgs = timed(builderMs, 'ask', () => buildExecutionAskSystemMessages() as LLMMessage[]);
+  const approvalSystemMsgs = timed(builderMs, 'approval', () => buildApprovalPolicySystemMessages() as LLMMessage[]);
+  const sandboxSystemMsgs = timed(builderMs, 'sandbox', () => buildSandboxEscalationSystemMessages() as LLMMessage[]);
   // Session-scoped (built once, rebuilt on change) — see turn-session-layers.ts.
   const sessionKey = ctx.sessionId ?? 'tui';
-  const memorySystemMsgs = ctx.memory === false
+  const memory = ctx.memory;
+  const memorySystemMsgs = memory === false
     ? []
-    : sessionMemoryLayer({ sessionKey, cwd: ctx.cwd, ...(ctx.memory ?? {}) });
-  const gitSnapshotSystemMsgs = buildSessionRuntimeSystemMessages({
+    : timed(builderMs, 'memory', () => sessionMemoryLayer({ sessionKey, cwd: ctx.cwd, ...(memory ?? {}) }));
+  // TUI-TYPING-LAG — the snapshot is built twice per turn (dashboard ⊕ ACP) with 5+ git
+  // subprocesses each; a recent one is served and rebuilt off the event loop instead.
+  const gitSnapshotSystemMsgs = timed(builderMs, 'gitSnapshot', () => buildSessionRuntimeSystemMessages({
     cwd: ctx.cwd,
-  });
-  const surfaceSystemMsgs = ctx.turnProfile
-    ? buildSessionRuntimeTurnSystemMessages(ctx.turnProfile, ctx.userText)
+    gitSnapshotStaleMs: DASHBOARD_GIT_SNAPSHOT_STALE_MS,
+  }));
+  const turnProfile = ctx.turnProfile;
+  const surfaceSystemMsgs = turnProfile
+    ? timed(builderMs, 'surface', () => buildSessionRuntimeTurnSystemMessages(turnProfile, ctx.userText))
     : ([] as LLMMessage[]);
   // ⭐⭐ `tools.nativeStructure` 는 «어느 provider 에 켤지»를 목록으로 고를 수 있다(2026-08-18).
   //   ⛔ 목록이 없으면 종전대로 «전 provider» — 기존 설정을 쓰는 사람의 값이 안 바뀐다.
@@ -134,43 +202,46 @@ export function buildDashboardTurnPreamble(
     && isNativeStructureEnabledForProvider(nativeStructureConfig, resolveActiveProvider(ctx.userConfig));
   let nativeTools: NativeToolCatalogEntry[] | undefined;
   if (nativeStructureEnabled) {
-    // eslint-disable-next-line @typescript-eslint/no-var-requires
-    const { findNativeTool } = require('../native-tool-catalog.js') as typeof import('../native-tool-catalog.js');
-    nativeTools = [...new Map((ctx.enabledTools ?? [])
-      .map(findNativeTool)
-      .filter((tool): tool is NativeToolCatalogEntry => tool !== undefined)
-      .map(tool => [tool.id, tool])).values()];
+    nativeTools = timed(builderMs, 'nativeTools', () => {
+      // eslint-disable-next-line @typescript-eslint/no-var-requires
+      const { findNativeTool } = require('../native-tool-catalog.js') as typeof import('../native-tool-catalog.js');
+      return [...new Map((ctx.enabledTools ?? [])
+        .map(findNativeTool)
+        .filter((tool): tool is NativeToolCatalogEntry => tool !== undefined)
+        .map(tool => [tool.id, tool])).values()];
+    });
   }
-  const implDisciplineSystemMsgs = buildImplDisciplineSystemMessages({
+  const implDisciplineSystemMsgs = timed(builderMs, 'implDiscipline', () => buildImplDisciplineSystemMessages({
     text: ctx.userText,
   }, {
     nativeStructureEnabled,
     ...(nativeTools !== undefined ? { enabledTools: nativeTools } : {}),
-  }) as LLMMessage[];
-  const concisenessSystemMsgs = buildConcisenessSystemMessages(
+  }) as LLMMessage[]);
+  const concisenessSystemMsgs = timed(builderMs, 'conciseness', () => buildConcisenessSystemMessages(
     ctx.userConfig.chat.conciseness,
-  ) as LLMMessage[];
+  ) as LLMMessage[]);
   // ★ elanous 자기접근 규율 + 자기인지 ambient(P3 · 2026-07-13) — 텔레그램/디스코드
   //   (makeElanousAgentRunTurn)와 단일 출처(agent/self-ambient.ts). TUI 채팅에서도 미션
   //   진단("P2 왜 실패?")·자율 시스템 관측·회상이 규율+ambient+툴(self-ops family) 3박자로
   //   성립한다. fail-soft: ambient 조회 실패가 턴을 막지 않는다.
   let selfOpsSystemMsgs: LLMMessage[] = [];
   try {
-    selfOpsSystemMsgs = [
+    selfOpsSystemMsgs = timed(builderMs, 'selfOps', () => [
       elanousSelfAccessPrompt(ctx.sessionId),
       ...sessionSelfAmbientParts(sessionKey),
       investigationRecallAmbient(ctx.userText),
       localRefGroundingAmbient(ctx.userText),
     ]
       .filter(Boolean)
-      .map((content): LLMMessage => ({ role: 'system', content }));
+      .map((content): LLMMessage => ({ role: 'system', content })));
   } catch { /* fail-soft */ }
   const controlEnv = ctx.controlEnv ?? {
     controller: process.env.ELANOUS_CONTROLLER,
     channels: process.env.ELANOUS_CONTROL_CHANNELS,
   };
-  const controllerSystemMsgs = controlEnv.controller
-    ? [buildControllerSystemMessage(controlEnv.controller, controlEnv.channels)]
+  const controller = controlEnv.controller;
+  const controllerSystemMsgs = controller
+    ? timed(builderMs, 'controller', () => [buildControllerSystemMessage(controller, controlEnv.channels)])
     : [];
   const preamble = [
     ...universalPreamble,
@@ -196,24 +267,25 @@ export function buildDashboardTurnPreamble(
   // or (c) the model is simply ignoring what we sent.
   let taskNotificationCount = 0;
   try {
-    const pendingNotifications = globalTaskNotificationQueue.drain();
-    taskNotificationCount = pendingNotifications.length;
-    const taskNotificationsXml = renderTaskNotificationsXml(pendingNotifications);
-    if (taskNotificationsXml) {
-      preamble.push({ role: 'user', content: taskNotificationsXml });
-    }
+    timed(builderMs, 'taskNotifications', () => {
+      const pendingNotifications = globalTaskNotificationQueue.drain();
+      taskNotificationCount = pendingNotifications.length;
+      const taskNotificationsXml = renderTaskNotificationsXml(pendingNotifications);
+      if (taskNotificationsXml) {
+        preamble.push({ role: 'user', content: taskNotificationsXml });
+      }
+    });
   } catch {
     // Fail-soft: a task-notification delivery failure must not block the turn.
   }
 
-  if (debug.enabled) {
+  if (debug.enabled && builderMs !== null) {
     const total = preamble.reduce((sum, m) => {
       const c = m.content;
       return sum + (typeof c === 'string' ? c.length : JSON.stringify(c).length);
     }, 0);
     debug.log('chat.turn-preamble', 'built', {
       hasTurnProfile: ctx.turnProfile != null,
-      rich: ctx.rich === true,
       builderCounts: {
         universal: universalPreamble.length,
         seatBoot: seatBootSystemMsgs.length,
@@ -229,6 +301,10 @@ export function buildDashboardTurnPreamble(
         implDiscipline: implDisciplineSystemMsgs.length,
         conciseness: concisenessSystemMsgs.length,
       },
+      // 실린 빌더만 키가 있다(seatBoot·memory·surface·nativeTools·controller 는 조건부로 안 불린다).
+      builderMs,
+      builderMsKind: 'sync',
+      builderTotalMs: Math.round((performance.now() - startedAt) * 10) / 10,
       totalMessageCount: preamble.length,
       taskNotificationCount,
       totalChars: total,

package/src/dashboard/turn-session-layers.ts

@@ -16,7 +16,7 @@ import { join } from 'node:path';
 import type { LLMMessage } from '../llm.js';
 import { debug } from '../debug/log.js';
 import { buildMemoryInjection, memoryRoot, type MemoryEntry } from '../memory.js';
-import { elanousSelfAmbientParts } from '../agent/self-ambient.js';
+import { cachedSelfAmbientBaseParts } from '../agent/self-ambient-cache.js';
 
 /** Token budget for the TUI memory layer — the same default chat.ts gives buildMemoryInjection. */
 export const TUI_MEMORY_BUDGET_TOKENS = 1500;
@@ -157,7 +157,9 @@ export function sessionSelfAmbientParts(sessionKey: string, opts: SessionSelfAmb
     return cached.parts;
   }
   try {
-    const parts = (opts.build ?? (() => elanousSelfAmbientParts()))();
+    // TUI-TYPING-LAG — the stores are scanned by a worker (self-ambient-cache.ts); expiry here must
+    // not bring a synchronous `ps`/crontab/sqlite scan back onto the TUI turn path.
+    const parts = (opts.build ?? (() => cachedSelfAmbientBaseParts()))();
     const hash = contentHash(parts.join('\0'));
     if (cached && cached.hash === hash) {
       remember(ambientCache, sessionKey, { ...cached, at: now });

package/src/dashboard/turn-start-segments.ts

@@ -0,0 +1,222 @@
+// TURN-START-BLOCK-REST 2단계 — 턴 시작 덩어리 관측(`tui.turn-start segments`).
+//
+// 1단계(#28821)가 turn-preamble 빌더 전체 ≤10ms 인데 같은 창의 `tui.input-lag turn-start` loopDelayMs.max 는
+// 21~112ms 임을 보였다 — 막는 것은 preamble «밖»이다. 이 모듈은 턴 시작(대시보드 턴 본문 첫 콜백)에 트레이스를
+// 열고, 실제 호출 순서를 따라 심은 경계(`markTurnStartSegment`)마다 시계를 «한 번» 읽어 앞 경계와의 ms 를
+// 덩어리로 쌓는다. 첫 스트림 요청 경계(`endTurnStartSegments`)에서 닫고, 박동 두 번 간격 뒤 같은 창의 루프
+// 지연과 함께 debug.log('tui.turn-start', 'segments', …) 한 줄을 남긴다. 기존 `tui.input-lag` 줄은 창·칸 그대로다.
+//
+// - 턴 키: 경계는 트레이스를 연 «그 턴»의 키(ACP sessionId)를 같이 준다. 키가 다른 경계(다른 세션의 턴 ·
+//   서브 에이전트)는 문자열 비교 한 번으로 버린다 — 시계를 안 읽고 덩어리도 안 섞는다. 한 번에 열린 트레이스는
+//   하나(TUI 는 한 번에 한 턴)이고, 다른 키로 새로 열면 앞 것은 `superseded` 로 닫는다.
+// - 박동: 덩어리 안에서 박동이 돌았으면(`yielded`) 루프가 돌았다 = 순수 동기 아님. 박동 없이 이어진 덩어리 합의
+//   최대(`syncBlockMaxMs`)가 박동 하나가 본 막힘의 추정이다(오차 ≤ 박동 간격). 박동은 input-lag 프로브의 것을
+//   읽는다(`InputLagBeatView` — 새 타이머 0).
+// - debug 가 꺼진 턴은 트레이스를 안 연다 — 그 턴의 경계는 null 검사 한 번이고 시계를 안 읽는다.
+// - 줄을 내는 시점은 기존 turn-start 와 같은 «박동 두 번 간격» 타이머다(두 줄의 창이 같은 규칙으로 닫힌다).
+//   실제 박동 두 번을 센 뒤 내보내는 전환은 TURN-START-BLOCK-REST 3단계 앞 조각.
+// - 결선(대시보드·ACP·코어 턴·LLM 경계 한 줄씩)은 후속 PR — 이 모듈은 등록이 없으면 아무 일도 안 한다.
+
+import type { InputLagBeatView, LoopDelayMs } from '../tui/input-lag-probe.js';
+
+export const TURN_START_CATEGORY = 'tui.turn-start';
+export const TURN_START_SEGMENTS_EVENT = 'segments';
+/** 첫 스트림 요청 경계가 끝내 안 오면(원격 데몬 세션 · 중단 · 실패) 이만큼 뒤 쌓인 덩어리로 닫는다. */
+export const TURN_START_TRACE_CAP_MS = 15_000;
+
+export interface TurnStartSegments {
+  /** 덩어리 이름 → ms(0.1ms 반올림 · 앞 경계부터 이 경계까지의 벽시계). 같은 이름이 또 오면 `#2`… */
+  segmentsMs: Record<string, number>;
+  /** 경계가 온 순서. */
+  order: string[];
+  /** 그 덩어리 안에서 박동이 돌았다 — 루프가 돌았으니(await·I/O) 벽시계 ms 가 곧 막힘은 아니다. */
+  yielded: string[];
+  /** 덩어리 합(공개된 segmentsMs 값의 합 · 0.1ms). */
+  totalMs: number;
+  /** 트레이스 시작 → 닫힘. stream-open 이면 totalMs 와 같고, cap·superseded 면 마지막 경계 뒤 기다린 시간까지 든다
+   *  (debug 가 꺼진 새 턴이 닫으면 시계를 안 읽으므로 마지막 경계까지). */
+  closedAfterMs: number;
+  /** 트레이스를 열 때 마지막 박동부터 흐른 ms — 열기 «전» 동기 일이 이미 루프를 막고 있었으면 크다(평상시 ≤ 박동 간격). */
+  preTraceMs: number;
+  /** 박동 없이 이어진 덩어리 합의 최대 — 루프를 한 번에 막은 동기 덩어리의 추정(박동이 돈 덩어리는 마지막 박동 뒤
+   *  꼬리만 · 첫 덩어리까지 박동이 안 돌았으면 `preTrace` 를 머리로 포함). */
+  syncBlockMaxMs: number;
+  /** 그 최대 동기 덩어리를 이룬 덩어리 이름(순서대로). ⚠️ 첫 이름이 `yielded` 에 든 덩어리면 그 덩어리는 «마지막 박동 뒤
+   *  꼬리만» syncBlockMaxMs 에 들었다 — 그 덩어리 segmentsMs 전체가 동기 블록이라는 뜻이 아니다. */
+  syncBlockSegments: string[];
+  /** 트레이스 시작 → 닫힘 ⊕ 박동 두 번 간격 창의 루프 지연. */
+  loopDelayMs: LoopDelayMs;
+  endedBy: 'stream-open' | 'cap' | 'superseded';
+  /** 트레이스 키(ACP sessionId). */
+  key: string;
+  turnId?: string;
+  busy: boolean;
+}
+
+interface TimerLike { unref?: () => void }
+
+export interface TurnStartSegmentsOptions {
+  beats: InputLagBeatView;
+  log: (category: string, event: string, data: TurnStartSegments) => void;
+  isBusy: () => boolean;
+  /** 트레이스를 열지 — 대시보드는 `debug.enabled` 를 준다. 없으면 연다. */
+  isEnabled?: () => boolean;
+  now?: () => number;
+  setTimeoutFn?: (fn: () => void, ms: number) => TimerLike;
+  clearTimeoutFn?: (timer: TimerLike) => void;
+}
+
+export interface TurnStartSegmentsRecorder {
+  /** 키 `key` 의 턴 시작 트레이스를 연다(열린 것이 있으면 `superseded` 로 닫고). */
+  begin(key: string, turnId?: string): void;
+  /** 키가 같은 열린 트레이스에 덩어리 경계 하나 — 시계 한 번. 아니면 null 검사·비교뿐. */
+  mark(key: string, name: string): void;
+  /** 첫 스트림 요청 경계 — 마지막 덩어리를 찍고 닫는다(줄은 박동 두 번 간격 뒤). */
+  end(key: string, name: string): void;
+  dispose(): void;
+}
+
+const round1 = (ms: number): number => Math.round(Math.max(0, ms) * 10) / 10;
+
+interface Trace {
+  key: string;
+  turnId: string | undefined;
+  startAt: number;
+  lastAt: number;
+  preTraceMs: number;
+  /** 공개 덩어리(반올림 값)의 누적 합 — totalMs 가 segmentsMs 의 합과 어긋나지 않게. */
+  sumMs: number;
+  segmentsMs: Record<string, number>;
+  order: string[];
+  yielded: string[];
+  blockMs: number;
+  blockSegments: string[];
+  maxBlockMs: number;
+  maxBlockSegments: string[];
+  capTimer: TimerLike | null;
+}
+
+export function createTurnStartSegments(opts: TurnStartSegmentsOptions): TurnStartSegmentsRecorder {
+  const now = opts.now ?? (() => performance.now());
+  const isEnabled = opts.isEnabled ?? (() => true);
+  const setTimeoutFn = opts.setTimeoutFn ?? ((fn, ms) => setTimeout(fn, ms));
+  const clearTimeoutFn = opts.clearTimeoutFn ?? ((t) => clearTimeout(t as ReturnType<typeof setTimeout>));
+  const beats = opts.beats;
+  let trace: Trace | null = null;
+  let disposed = false;
+
+  const markAt = (tr: Trace, name: string): void => {
+    const t = now();
+    let key = name;
+    for (let n = 2; key in tr.segmentsMs; n++) key = `${name}#${n}`;
+    const ms = round1(t - tr.lastAt);
+    tr.segmentsMs[key] = ms;
+    tr.sumMs += ms;
+    tr.order.push(key);
+    // 앞 경계 뒤에 박동이 돌았으면 루프가 돌았다 — 동기 덩어리는 마지막 박동 «뒤» 꼬리부터 다시 센다.
+    const lastBeatAt = beats.lastBeatAt();
+    if (lastBeatAt > tr.lastAt) {
+      tr.yielded.push(key);
+      tr.blockMs = t - lastBeatAt;
+      tr.blockSegments = [key];
+    } else {
+      tr.blockMs += t - tr.lastAt;
+      tr.blockSegments.push(key);
+    }
+    if (tr.blockMs >= tr.maxBlockMs) {
+      tr.maxBlockMs = tr.blockMs;
+      tr.maxBlockSegments = tr.blockSegments.slice();
+    }
+    tr.lastAt = t;
+  };
+
+  const close = (tr: Trace, endedBy: TurnStartSegments['endedBy'], closedAt: number): void => {
+    if (trace === tr) trace = null;
+    // 닫힌 트레이스를 상한 타이머가 붙잡지 않게 푼다.
+    if (tr.capTimer !== null) { clearTimeoutFn(tr.capTimer); tr.capTimer = null; }
+    const emit = (): void => {
+      if (disposed) return;
+      opts.log(TURN_START_CATEGORY, TURN_START_SEGMENTS_EVENT, {
+        segmentsMs: tr.segmentsMs,
+        order: tr.order,
+        yielded: tr.yielded,
+        totalMs: Math.round(tr.sumMs * 10) / 10,
+        closedAfterMs: round1(closedAt - tr.startAt),
+        preTraceMs: round1(tr.preTraceMs),
+        syncBlockMaxMs: round1(tr.maxBlockMs),
+        syncBlockSegments: tr.maxBlockSegments,
+        loopDelayMs: beats.loopDelaySince(tr.startAt),
+        endedBy,
+        key: tr.key,
+        ...(tr.turnId !== undefined ? { turnId: tr.turnId } : {}),
+        busy: opts.isBusy(),
+      });
+    };
+    // 방금 끝난 동기 막힘은 루프가 풀린 «뒤» 박동에 찍힌다 — 첫 스트림 요청이면 박동 두 번 간격 기다렸다 읽는다.
+    if (endedBy === 'stream-open') setTimeoutFn(emit, beats.heartbeatMs * 2).unref?.();
+    else emit();
+  };
+
+  return {
+    begin(key: string, turnId?: string): void {
+      if (disposed) return;
+      const open = trace;
+      if (!isEnabled()) {
+        // debug 가 꺼진 턴은 시계를 안 읽는다 — 열려 있던 트레이스는 마지막 경계 시각으로 닫는다.
+        if (open !== null) close(open, 'superseded', open.lastAt);
+        return;
+      }
+      const t = now();
+      if (open !== null) close(open, 'superseded', t);
+      // 열기 전 마지막 박동 뒤 흐른 시간 — 열기 전 동기 일이 같은 막힘의 머리다(시계는 이 한 번).
+      const preTraceMs = Math.max(0, t - beats.lastBeatAt());
+      const tr: Trace = {
+        key, turnId, startAt: t, lastAt: t, preTraceMs, sumMs: 0,
+        segmentsMs: {}, order: [], yielded: [],
+        blockMs: preTraceMs, blockSegments: ['preTrace'], maxBlockMs: preTraceMs, maxBlockSegments: ['preTrace'],
+        capTimer: null,
+      };
+      trace = tr;
+      tr.capTimer = setTimeoutFn(() => { tr.capTimer = null; if (trace === tr) close(tr, 'cap', now()); }, TURN_START_TRACE_CAP_MS);
+      tr.capTimer.unref?.();
+    },
+    mark(key: string, name: string): void {
+      const tr = trace;
+      if (tr !== null && tr.key === key) markAt(tr, name);
+    },
+    end(key: string, name: string): void {
+      const tr = trace;
+      if (tr === null || tr.key !== key) return;
+      markAt(tr, name);
+      close(tr, 'stream-open', tr.lastAt);
+    },
+    dispose(): void {
+      if (disposed) return;
+      disposed = true;
+      if (trace !== null && trace.capTimer !== null) { clearTimeoutFn(trace.capTimer); trace.capTimer = null; }
+      trace = null;
+    },
+  };
+}
+
+// ── 등록 자리 — 대시보드가 하나 등록하고, 경계(대시보드·ACP·코어 턴·LLM)는 부르기만 한다. ──
+let active: TurnStartSegmentsRecorder | null = null;
+
+export function setTurnStartSegments(recorder: TurnStartSegmentsRecorder | null): void {
+  active = recorder;
+}
+
+/** 키 `key`(ACP sessionId) 의 턴 시작 트레이스를 연다 — 대시보드 턴 본문의 첫 콜백. */
+export function beginTurnStartSegments(key: string, turnId?: string): void {
+  active?.begin(key, turnId);
+}
+
+/** 턴 시작 덩어리 경계 — 등록·트레이스가 없거나 키가 다르면 null 검사·비교뿐(시계를 안 읽는다). */
+export function markTurnStartSegment(key: string | undefined, name: string): void {
+  if (key !== undefined) active?.mark(key, name);
+}
+
+/** 첫 스트림 요청 경계 — 같은 키의 트레이스를 닫는다. */
+export function endTurnStartSegments(key: string | undefined, name: string): void {
+  if (key !== undefined) active?.end(key, name);
+}