elanous 0.2.35 → 0.2.37

package/src/dashboard/synchronized-frame-output.ts

@@ -0,0 +1,74 @@
+/**
+ * TUI-FLICKER-DRAW-INTEGRATION — one synchronized-output owner per dashboard frame.
+ *
+ * A dashboard frame is not a single write: the transient-overlay cleanup, the
+ * base frame, the coordinator modal overlay, the prompt repaint and the
+ * post-frame overlay stamp are flushed one after another. Under tmux each of
+ * those flushes is presented on its own, so a tick that rewrites the frame is
+ * visible as a flicker. Wrapping the whole compose in DEC synchronized output
+ * (`CSI ? 2026 h` … `CSI ? 2026 l`) lets the terminal present the composite
+ * frame atomically.
+ *
+ * The owner is deliberately tiny and synchronous: callers open it, draw, and
+ * close it in a `finally` so a throw inside the draw still emits the ESU and
+ * the *next* frame is not swallowed by a dangling synchronized-output region.
+ *
+ * The wrap nests with the display coordinator, which opens the same region
+ * around its own flush and whose `onRender` hook is what calls `drawNow()`.
+ * `src/display/synchronized-output-region.ts` keeps that single-owner: an
+ * inner open contributes no bytes, so the coordinator's overlay + cursor stamp
+ * stays inside the one presentation instead of being pushed out by an early
+ * inner ESU.
+ */
+
+import {
+  SYNCHRONIZED_OUTPUT_BEGIN,
+  SYNCHRONIZED_OUTPUT_END,
+  openSynchronizedOutputRegion,
+  synchronizedOutputDisabledByEnv,
+} from '../display/synchronized-output-region.js';
+
+export { SYNCHRONIZED_OUTPUT_BEGIN, SYNCHRONIZED_OUTPUT_END };
+
+export interface SynchronizedFrameOutputDeps {
+  /** Sink for the control sequences — production passes `process.stdout.write`. */
+  write: (chunk: string) => void;
+  /**
+   * Whether the sink may receive DEC 2026. Defaults to `true`. Production
+   * passes `process.stdout.isTTY` so piped/captured output stays
+   * byte-identical to what it was before this seam existed.
+   */
+  supported?: boolean;
+  /** Environment escape hatch (`ELANOUS_SYNC_OUTPUT=off`). Defaults to `process.env`. */
+  env?: Record<string, string | undefined>;
+}
+
+export interface SynchronizedFrameOutput {
+  /** Closes the region. Idempotent — a second call writes nothing. */
+  close: () => void;
+}
+
+export function beginSynchronizedFrameOutput(
+  deps: SynchronizedFrameOutputDeps,
+): SynchronizedFrameOutput {
+  const region = openSynchronizedOutputRegion();
+  const enabled =
+    region.outermost && deps.supported !== false && !synchronizedOutputDisabledByEnv(deps.env);
+  let closed = false;
+  if (enabled) {
+    try {
+      deps.write(SYNCHRONIZED_OUTPUT_BEGIN);
+    } catch (err) {
+      region.close();
+      throw err;
+    }
+  }
+  return {
+    close: () => {
+      if (closed) return;
+      closed = true;
+      if (enabled) deps.write(SYNCHRONIZED_OUTPUT_END);
+      region.close();
+    },
+  };
+}

package/src/debug/batch-queue.ts

@@ -0,0 +1,119 @@
+// TUI-TYPING-LAG — bounded-chunk drain queue for the log plane.
+//
+// A worker that floods the log (streaming chunks, subagent output) used to hand
+// the main thread one synchronous drain of the whole burst (e.g. StoreSink's
+// detached flush inserting thousands of sqlite rows in one macrotask), so a key
+// typed meanwhile waited for the entire drain (0.25–2.4s stalls). This queue
+// drains at most `batchSize` items per scheduled tick and schedules the remainder
+// as a NEW tick, so the event loop gets back to I/O (stdin) between chunks.
+//
+// Zero imports on purpose: the log sinks under
+// src/mss/logging import it without creating a cycle.
+
+/** Scheduler seam — production uses setImmediate / setTimeout(unref); stages inject a fake clock. */
+export interface DebugBatchScheduler {
+  schedule(run: () => void, delayMs: number): unknown;
+  cancel(handle: unknown): void;
+}
+
+export const defaultDebugBatchScheduler: DebugBatchScheduler = {
+  schedule(run, delayMs) {
+    if (delayMs <= 0) return { immediate: setImmediate(run) };
+    const timer = setTimeout(run, delayMs);
+    (timer as unknown as { unref?: () => void }).unref?.();
+    return { timeout: timer };
+  },
+  cancel(handle) {
+    const h = handle as { immediate?: ReturnType<typeof setImmediate>; timeout?: ReturnType<typeof setTimeout> } | null;
+    if (!h) return;
+    if (h.immediate !== undefined) clearImmediate(h.immediate);
+    if (h.timeout !== undefined) clearTimeout(h.timeout);
+  },
+};
+
+export interface DebugLogBatchQueueOptions<T> {
+  /** Max items handed to `drain` per scheduled tick. `Infinity` = whole queue in one tick. */
+  batchSize: number;
+  /** Delay before each scheduled tick (0 = next loop iteration). */
+  flushDelayMs?: number;
+  scheduler?: DebugBatchScheduler;
+  /** Return `false` to stop chunking (e.g. the store is contended) — the remainder stays queued, unscheduled. */
+  drain: (items: T[]) => void | boolean;
+}
+
+export class DebugLogBatchQueue<T> {
+  private items: T[] = [];
+  private handle: unknown = null;
+  private hasHandle = false;
+  private flushCount = 0;
+  private readonly batchSize: number;
+  private readonly flushDelayMs: number;
+  private readonly scheduler: DebugBatchScheduler;
+  private readonly drainFn: (items: T[]) => void | boolean;
+
+  constructor(opts: DebugLogBatchQueueOptions<T>) {
+    this.batchSize = opts.batchSize > 0 ? opts.batchSize : 1;
+    this.flushDelayMs = Math.max(0, opts.flushDelayMs ?? 0);
+    this.scheduler = opts.scheduler ?? defaultDebugBatchScheduler;
+    this.drainFn = opts.drain;
+  }
+
+  get pending(): number { return this.items.length; }
+  get flushes(): number { return this.flushCount; }
+  get scheduled(): boolean { return this.hasHandle; }
+
+  /** Enqueue without draining — the caller decides when to `schedule()`. */
+  push(item: T): void { this.items.push(item); }
+
+  /** Arm one drain tick (idempotent while a tick is in flight). */
+  schedule(): void {
+    if (this.hasHandle || this.items.length === 0) return;
+    this.hasHandle = true;
+    this.handle = this.scheduler.schedule(() => this.tick(), this.flushDelayMs);
+  }
+
+  /** Drop up to `count` oldest items; returns how many were dropped. */
+  dropOldest(count: number): number {
+    if (count <= 0) return 0;
+    const dropped = Math.min(count, this.items.length);
+    this.items.splice(0, dropped);
+    return dropped;
+  }
+
+  /** Synchronous full drain (exit / explicit flush) — one `drain` call, pending tick cancelled. */
+  flushAll(): void {
+    this.cancelTick();
+    if (this.items.length === 0) return;
+    const all = this.items;
+    this.items = [];
+    this.flushCount += 1;
+    this.drainFn(all);
+  }
+
+  /** Disarm the pending tick (items stay queued) — e.g. the store is contended. */
+  cancelScheduled(): void { this.cancelTick(); }
+
+  private cancelTick(): void {
+    if (!this.hasHandle) return;
+    this.scheduler.cancel(this.handle);
+    this.handle = null;
+    this.hasHandle = false;
+  }
+
+  private tick(): void {
+    this.handle = null;
+    this.hasHandle = false;
+    if (this.items.length === 0) return;
+    const chunk = Number.isFinite(this.batchSize)
+      ? this.items.splice(0, this.batchSize)
+      : this.items.splice(0, this.items.length);
+    this.flushCount += 1;
+    let keepGoing = true;
+    try {
+      keepGoing = this.drainFn(chunk) !== false;
+    } finally {
+      // The remainder is a separate tick so stdin can be served between chunks.
+      if (keepGoing) this.schedule();
+    }
+  }
+}

package/src/debug/tui-log-tag.ts

@@ -0,0 +1,67 @@
+// TUI-LOG-SESSION-TAG (0.2.36 · 10-23) — tell TUIs apart in one logs.db.
+//
+// Several TUIs (classic `elanous` / `--legacy` and `--tui next`) on one host write to the same logs.db
+// with surface `tui`. Their rows had no pid and usually no session_id (the dashboard does not set the
+// ambient session), so the 10-23 n8n SIGTTIN incident could not tell which TUI's `tui.event-loop stall`
+// was which. This wraps the TUI's logs.db sink and stamps every plain-object payload with:
+//   tuiPid      — the TUI process id
+//   tuiName     — the `--name` launch alias (when given)
+//   tuiSession  — the chat session the TUI currently owns (getTuiOwnedSession, when known)
+// Caller-supplied fields win; primitive / non-plain payloads are left untouched; an absent payload becomes
+// the tag object. No schema change — the tag rides in the existing `data` column.
+//
+// Query: `elanous logs --surface tui --grep '"tuiName":"n8n"'` · `--grep '"tuiPid":20960'`
+//        or `--json | jq 'select((.data|fromjson? // {}).tuiName == "n8n")'`.
+
+import type { LogSink } from '../mss/logging/sink.js';
+import type { LogRecord } from '../mss/logging/record.js';
+
+export interface TuiLogTag {
+  pid: number;
+  name?: string;
+  /** Current owned chat session id, or null. Called per record — keep it cheap. */
+  session?: () => string | null | undefined;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (value === null || typeof value !== 'object') return false;
+  const p = Object.getPrototypeOf(value);
+  return p === Object.prototype || p === null;
+}
+
+/** Pure — returns the record with the tag applied (a new object when changed). */
+export function tagTuiRecord(rec: LogRecord, tag: TuiLogTag): LogRecord {
+  let session: string | null | undefined;
+  try { session = tag.session?.(); } catch { session = undefined; }
+  const add: Record<string, unknown> = { tuiPid: tag.pid };
+  const name = tag.name?.trim();
+  if (name) add.tuiName = name;
+  if (session) add.tuiSession = session;
+  if (rec.data === undefined) return { ...rec, data: add };
+  if (!isPlainObject(rec.data)) return rec;
+  const data = rec.data;
+  const missing = Object.entries(add).filter(([k]) => !Object.hasOwn(data, k));
+  if (missing.length === 0) return rec;
+  return { ...rec, data: { ...data, ...Object.fromEntries(missing) } };
+}
+
+// Process-wide tag state — the TUI's self-report fills it (`--name` at launch, the owned session on every
+// claim) so the sink wrapper needs no import of the TUI modules (no cycle · no hub edit).
+let processName: string | undefined;
+let processSession: string | null = null;
+export function setTuiLogName(name: string | undefined): void { processName = name?.trim() || undefined; }
+export function setTuiLogSession(id: string | null): void { processSession = id || null; }
+/** The tag for this process: pid ⊕ the state above. */
+export function processTuiLogTag(): TuiLogTag {
+  return { pid: process.pid, get name() { return processName; }, session: () => processSession };
+}
+
+/** Wraps a sink so every record it receives is tagged. */
+export function withTuiLogTag(inner: LogSink, tag: TuiLogTag): LogSink {
+  return {
+    name: inner.name,
+    emit(rec: LogRecord): void { inner.emit(tagTuiRecord(rec, tag)); },
+    ...(inner.flush ? { flush: () => inner.flush?.() } : {}),
+    ...(inner.clear ? { clear: () => inner.clear?.() } : {}),
+  };
+}

package/src/display/agent-surface.ts

@@ -447,7 +447,14 @@ function recentToolTrail(task: AgentTask, limit: number, cache: ScanCache): Agen
   return trail;
 }
 
+/** Tool calls the child made: the live counter (bumped as each call starts) or the
+ *  tool_use blocks in its history, whichever is larger — history lags until a tool
+ *  loop completes and stays short when the run is aborted or errors. */
 function countToolUses(task: AgentTask, cache: ScanCache): number {
+  return Math.max(task.toolCallCount ?? 0, countHistoryToolUses(task, cache));
+}
+
+function countHistoryToolUses(task: AgentTask, cache: ScanCache): number {
   const len = task.messages?.length ?? 0;
   if (len === 0) return 0;
   const cached = cache.count.get(task.id);

package/src/display/coordinator.ts

@@ -22,6 +22,10 @@ import { TIER_ORDER, tierRank, tiersCompatible } from './types.js';
 import { resolveKeyAlias } from '../input-core/key-alias-table.js';
 import type { DisplayEventBus } from './events.js';
 import { paintCursor, type CursorState } from './cursor-state.js';
+import {
+  openSynchronizedOutputRegion,
+  synchronizedOutputDisabledByEnv,
+} from './synchronized-output-region.js';
 import { deriveCursor, type CursorDecision } from './cursor-owner.js';
 import {
   createVirtualCursorRegistry,
@@ -261,7 +265,6 @@ export class DisplayCoordinator {
    *  even when its bytes are unchanged, because the base rows under it
    *  were just repainted. Replaces the old forceNext follow-up. */
   private overlayRowsInvalidated = false;
-
   private surfaces = new Map<SurfaceId, DisplaySurface>();
   private focusNodes = new Map<SurfaceId, FocusNode>();
   private keyBindings = new Map<string, DisplayKeyBinding>();
@@ -288,6 +291,7 @@ export class DisplayCoordinator {
   private dirty = new Set<SurfaceId | 'all' | 'status' | 'dock'>();
   private forceNext = false;
   private scheduled: Timer | null = null;
+  private scheduleGeneration = 0;
   // P2.2.b — cursor state. Last-writer-wins. cursorVersion bumps on
   // every setCursor; lastEmittedCursorVersion tracks what's been
   // written so flushCursor only emits on change.
@@ -966,6 +970,36 @@ export class DisplayCoordinator {
     }, 'dashboard');
   }
 
+  /** Mark a render dirty and flush it before returning. Used when a host
+   *  already owns a synchronized output batch around the render. */
+  requestRenderNow(opts?: { region?: SurfaceId | 'all'; force?: boolean }): void {
+    this.markDirty(opts?.region ?? 'all');
+    if (opts?.force) this.forceNext = true;
+    this.scheduleGeneration += 1;
+    this.scheduled = null;
+    this.flush();
+  }
+
+  /** Run synchronous terminal writes inside DECSET 2026 when enabled.
+   *  Coordinator flushes, the dashboard draw seam, and host paint batches
+   *  share the same re-entrant region instead of emitting nested markers. */
+  withSynchronizedOutput<T>(paint: () => T): T {
+    const syncRegion = openSynchronizedOutputRegion();
+    const syncOutput = syncRegion.outermost && this.syncOutputEnabled;
+    try {
+      if (syncOutput) {
+        this.writeOverlay?.('\x1b[?2026h');
+      }
+      return paint();
+    } finally {
+      try {
+        if (syncOutput) this.writeOverlay?.('\x1b[?2026l');
+      } finally {
+        syncRegion.close();
+      }
+    }
+  }
+
   handle(owner: SurfaceOwner): DisplayHandle {
     return {
       owner,
@@ -2629,10 +2663,16 @@ export class DisplayCoordinator {
 
   private requestFrame(): void {
     if (this.scheduled !== null) return;
-    this.scheduled = this.scheduleFn(() => {
+    const generation = ++this.scheduleGeneration;
+    const marker = {} as Timer;
+    let scheduled: Timer | undefined;
+    this.scheduled = marker;
+    scheduled = this.scheduleFn(() => {
+      if (generation !== this.scheduleGeneration || (this.scheduled !== marker && this.scheduled !== scheduled)) return;
       this.scheduled = null;
       this.flush();
     }, this.frameMs);
+    if (this.scheduled === marker) this.scheduled = scheduled;
   }
 
   private flush(): void {
@@ -2661,9 +2701,7 @@ export class DisplayCoordinator {
     // `ELANOUS_SYNC_OUTPUT=off` for buggy terminals (none observed in
     // practice, 2026-04-21). Pattern matches Textual (synchronized
     // output since v0.47) + Ratatui backend buffer-swap semantics.
-    const syncOutput = this.syncOutputEnabled;
-    if (syncOutput) this.writeOverlay?.('\x1b[?2026h');
-    try {
+    this.withSynchronizedOutput(() => {
       // H1.6 · W2 shadow flush. Fires rc.on('before-flush') +
       // rc.on('after-flush') synchronously. Subscriber paints (if any
       // are wired in Phase γ) land INSIDE the DECSET 2026 atomic-frame
@@ -2696,11 +2734,7 @@ export class DisplayCoordinator {
       // so the prior cursor position may have been overwritten. Always
       // re-assert. The bypass-batch path calls flushCursor(false).
       this.flushCursor(true);
-    } finally {
-      // Always close the sync block — a throw inside render hooks
-      // must not leave the terminal stuck in "buffering" mode.
-      if (syncOutput) this.writeOverlay?.('\x1b[?2026l');
-    }
+    });
     this.eventBus?.emit({ type: 'render:after', request, snapshot });
     this.pendingWidgetPatches = [];
     this.pendingLogLines = [];
@@ -2713,8 +2747,7 @@ export class DisplayCoordinator {
    *  not a TTY (unit-test + CI environment) so overlay assertions
    *  don't have to strip the ?2026h / ?2026l pair. */
   private get syncOutputEnabled(): boolean {
-    const v = (process.env.ELANOUS_SYNC_OUTPUT ?? 'on').toLowerCase();
-    if (v === 'off' || v === '0' || v === 'false') return false;
+    if (synchronizedOutputDisabledByEnv()) return false;
     // Non-TTY environments (tests, piped output) gain nothing from
     // atomic frame wrapping and the sequences would pollute assertions.
     if (typeof process !== 'undefined' && process.stdout && process.stdout.isTTY !== true) {

package/src/display/resize-listener.ts

@@ -5,10 +5,9 @@
 // resize produced a stale paint (old input prompt row + ghost tab
 // bar) until the next keystroke triggered a redraw.
 //
-// Strategy: on every stdout resize event, (1) push a forced dashboard
-// redraw and (2) invoke the prompt's repaint hook so input-mode
-// overlays catch up too. Both calls are wrapped in try/catch so a
-// transient paint error doesn't kill the listener.
+// Strategy: debounce resize bursts for one frame (16ms), then paint the
+// dashboard, prompt, and overlays synchronously inside one atomic output
+// block. Transient paint errors do not kill the listener.
 //
 // (3) TUI-PICKER-RESIZE-SHRINK (#76 · 2026-10-17) — then ask the
 // coordinator for one FORCED frame. Steps (1)+(2) bypass the
@@ -28,6 +27,8 @@
 
 import { debug } from '../debug/log.js';
 
+const RESIZE_DEBOUNCE_MS = 16;
+
 export interface ResizeListenerDeps {
   draw: (opts?: { force?: boolean }) => void;
   promptCtl: { repaint: () => void };
@@ -35,6 +36,9 @@ export interface ResizeListenerDeps {
    *  re-emitted on top of the chrome the prompt repaint just wrote.
    *  Optional: hosts without a coordinator keep the legacy two-step. */
   requestOverlayFrame?: () => void;
+  /** Run the whole resize repaint batch inside the host's atomic output
+   *  block. Nested coordinator frames must share this outer block. */
+  withSynchronizedOutput?: (paint: () => void) => void;
 }
 
 /** Registers the resize listener and returns a dispose fn that
@@ -42,26 +46,43 @@ export interface ResizeListenerDeps {
  *  fresh listener; the caller is responsible for disposing previous
  *  installations. */
 export function installResizeListener(deps: ResizeListenerDeps): () => void {
-  const handler = (): void => {
-    try { deps.draw({ force: true }); } catch { /* swallow — paint errors shouldn't break resize */ }
-    try { deps.promptCtl.repaint(); } catch { /* swallow */ }
-    let overlayFrame: 'requested' | 'absent' | 'failed' = 'absent';
-    if (deps.requestOverlayFrame) {
-      try {
-        deps.requestOverlayFrame();
-        overlayFrame = 'requested';
-      } catch {
-        overlayFrame = 'failed';
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let disposed = false;
+  const repaint = (): void => {
+    timer = undefined;
+    if (disposed) return;
+    const paint = (): void => {
+      try { deps.draw({ force: true }); } catch { /* swallow — paint errors shouldn't break resize */ }
+      try { deps.promptCtl.repaint(); } catch { /* swallow */ }
+      let overlayFrame: 'requested' | 'absent' | 'failed' = 'absent';
+      if (deps.requestOverlayFrame) {
+        try {
+          deps.requestOverlayFrame();
+          overlayFrame = 'requested';
+        } catch {
+          overlayFrame = 'failed';
+        }
       }
-    }
-    debug.log('display.resize', 'repaint', {
-      cols: process.stdout.columns ?? null,
-      rows: process.stdout.rows ?? null,
-      overlayFrame,
-    });
+      debug.log('display.resize', 'repaint', {
+        cols: process.stdout.columns ?? null,
+        rows: process.stdout.rows ?? null,
+        overlayFrame,
+      });
+    };
+    try {
+      if (deps.withSynchronizedOutput) deps.withSynchronizedOutput(paint);
+      else paint();
+    } catch { /* resize painting must not detach the listener */ }
+  };
+  const handler = (): void => {
+    if (timer !== undefined) clearTimeout(timer);
+    timer = setTimeout(repaint, RESIZE_DEBOUNCE_MS);
   };
   process.stdout.on('resize', handler);
   return (): void => {
+    disposed = true;
+    if (timer !== undefined) clearTimeout(timer);
+    timer = undefined;
     process.stdout.removeListener('resize', handler);
   };
 }

package/src/display/synchronized-output-region.ts

@@ -0,0 +1,60 @@
+/**
+ * DECSET 2026 (synchronized output) region registry.
+ *
+ * Two owners wrap their writes in `CSI ? 2026 h` … `CSI ? 2026 l`: the
+ * display coordinator (`flush()`) and the dashboard draw seam
+ * (`src/dashboard/synchronized-frame-output.ts`). They nest — the
+ * coordinator opens a region and its `onRender` hook runs `drawNow()`,
+ * which wants the same wrap for the frame + prompt repaint. A second pair
+ * emitted inside the outer one is not harmless: the inner ESU flushes the
+ * terminal early, so everything the coordinator writes afterwards (modal
+ * overlay, cursor) lands in a separate presentation — exactly the flicker
+ * the wrap exists to prevent.
+ *
+ * The registry makes the wrap re-entrant: whoever opens first owns the
+ * byte pair; nested openers contribute no bytes and never close the outer
+ * region. Every opener must close its handle (idempotent) so the depth
+ * stays balanced even when a draw throws.
+ */
+
+export const SYNCHRONIZED_OUTPUT_BEGIN = '\x1b[?2026h';
+export const SYNCHRONIZED_OUTPUT_END = '\x1b[?2026l';
+
+export interface SynchronizedOutputRegion {
+  /** true when this region owns the emitted BSU/ESU pair. */
+  readonly outermost: boolean;
+  /** Idempotent — closes this region exactly once. */
+  close(): void;
+}
+
+let openDepth = 0;
+
+/** True while any owner holds a synchronized-output region open. */
+export function isSynchronizedOutputRegionOpen(): boolean {
+  return openDepth > 0;
+}
+
+/**
+ * `ELANOUS_SYNC_OUTPUT=off|0|false` escape hatch for terminals that
+ * mishandle DEC 2026. Anything else (including unset) keeps the wrap on.
+ */
+export function synchronizedOutputDisabledByEnv(
+  env: Record<string, string | undefined> = process.env,
+): boolean {
+  const value = (env.ELANOUS_SYNC_OUTPUT ?? 'on').toLowerCase();
+  return value === 'off' || value === '0' || value === 'false';
+}
+
+export function openSynchronizedOutputRegion(): SynchronizedOutputRegion {
+  const outermost = openDepth === 0;
+  openDepth += 1;
+  let closed = false;
+  return {
+    outermost,
+    close(): void {
+      if (closed) return;
+      closed = true;
+      if (openDepth > 0) openDepth -= 1;
+    },
+  };
+}

package/src/domains/standalone-log-sink.ts

@@ -10,20 +10,33 @@
 /**
  * 독립 프로세스에서 logs.db 싱크를 등록한다. 반환된 off 는 process 'exit' 에 자동 배선된다.
  * @param surface  이 프로세스가 남기는 로그의 surface 라벨(예: 'scheduler'·'autopilot').
+ * @param opts.wrapSink  logs.db 싱크를 감싼다(예: TUI 는 pid·`--name`·세션을 data 에 찍는다 — debug/tui-log-tag.ts).
  */
-export async function registerStandaloneLogSink(surface: string): Promise<boolean> {
+export async function registerStandaloneLogSink(
+  surface: string,
+  opts: { wrapSink?: (sink: import('../mss/logging/sink.js').LogSink) => import('../mss/logging/sink.js').LogSink } = {},
+): Promise<boolean> {
   try {
     const [storeMod, dbgMod, cfgMod] = await Promise.all([
       import('../mss/logging/log-store.js'),
       import('../debug/log.js'),
       import('../user-config.js'),
     ]);
+    // TUI-LOG-SESSION-TAG — 한 logs.db 를 여러 TUI(클래식·next)가 쓴다: 행마다 pid·`--name`·소유 세션을 data 에 찍는다.
+    if (surface === 'tui' && !opts.wrapSink) {
+      const tagMod = await import('../debug/tui-log-tag.js');
+      const tag = tagMod.processTuiLogTag();
+      opts = { ...opts, wrapSink: (s) => tagMod.withTuiLogTag(s, tag) };
+    }
     const logsCfg = cfgMod.getUserConfig().logs;
     storeMod.setLogInstanceName(logsCfg.instanceName);
+    // TUI-TYPING-LAG — TUI 는 워커 로그 폭주를 덩어리로 나눠 넣는다(키가 drain 전체를 기다리지 않게).
+    const drainChunkSize = storeMod.logStoreDrainChunkForSurface(surface);
     const offStore = storeMod.registerLogStoreSink(
-      (s) => dbgMod.debug.registerSink(s),
+      (s) => dbgMod.debug.registerSink(opts.wrapSink ? opts.wrapSink(s) : s),
       surface,
       logsCfg.retention,
+      drainChunkSize !== undefined ? { drainChunkSize } : {},
     );
     if (!offStore) return false;
     process.on('exit', offStore);