@pellux/goodvibes-tui 1.27.0 → 2.0.1

package/src/runtime/session-liveness-marker.ts

@@ -1,257 +0,0 @@
-/**
- * session-liveness-marker.ts — best-effort "this session is open in another
- * terminal" signal for multi-instance safety.
- *
- * Two independent TUI instances resuming or writing recovery snapshots for
- * the SAME session can silently step on each other: one instance's periodic
- * recovery write looks, to a second instance, indistinguishable from a
- * genuine crash snapshot, and resuming a session another instance still has
- * open forks its live state without warning.
- *
- * This module writes a small marker file (session id + pid), refreshed on
- * the SAME 60s cadence as the existing recovery-file write (main.ts), so a
- * second instance can do a best-effort liveness check before either warning
- * about a stale-looking recovery snapshot or resuming a live session out
- * from under its owner.
- *
- * Every check here is best-effort by design: a missing or stale marker never
- * blocks anything — it just means "we can't tell, proceed as before". This is
- * a convenience signal, not a lock.
- *
- * Location: <homeDirectory>/.goodvibes/<surfaceRoot>/liveness/<sessionId>.json.
- * Both halves come off the caller's SessionSurface rather than being spelled
- * out here, so the markers land under the same scope as the sessions and
- * recovery snapshots they describe — mirrors the transcript-journal.ts
- * convention (homeDirectory-scoped, under the surface's own directory).
- */
-import { existsSync, mkdirSync, readFileSync, readdirSync, unlinkSync, writeFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-import type { SessionSurface } from '@/runtime/index.ts';
-
-export interface LivenessMarker {
-  readonly sessionId: string;
-  readonly pid: number;
-  readonly updatedAt: number;
-}
-
-/**
- * A marker older than this is treated as stale even if its pid happens to
- * still resolve to a running process (pid reuse after a crash) — the marker
- * is refreshed every 60s (main.ts's recovery cadence), so anything past
- * ~2.5x that cadence means the writer stopped refreshing it.
- */
-export const LIVENESS_STALE_AFTER_MS = 150_000;
-
-/** Absolute path to the directory holding every session's liveness marker. */
-export function livenessMarkerDirFor(surface: SessionSurface): string {
-  return join(surface.homeDirectory, '.goodvibes', surface.surfaceRoot, 'liveness');
-}
-
-/** Absolute path to a session's liveness marker file. */
-export function livenessMarkerPathFor(surface: SessionSurface, sessionId: string): string {
-  return join(livenessMarkerDirFor(surface), `${sessionId}.json`);
-}
-
-/** Refresh (creating if needed) the liveness marker for this session/pid. Best-effort — never throws. */
-export function writeLivenessMarker(surface: SessionSurface, sessionId: string, pid: number = process.pid): void {
-  try {
-    const path = livenessMarkerPathFor(surface, sessionId);
-    mkdirSync(dirname(path), { recursive: true });
-    const marker: LivenessMarker = { sessionId, pid, updatedAt: Date.now() };
-    writeFileSync(path, JSON.stringify(marker), { mode: 0o600 });
-  } catch {
-    // Best-effort — a missed liveness refresh never blocks anything.
-  }
-}
-
-/** Best-effort removal on exit. Never throws. */
-export function removeLivenessMarker(surface: SessionSurface, sessionId: string): void {
-  try {
-    const path = livenessMarkerPathFor(surface, sessionId);
-    if (existsSync(path)) unlinkSync(path);
-  } catch {
-    // Best-effort.
-  }
-}
-
-/** Parse one marker file by absolute path. Returns null for missing, empty, torn, or wrong-shaped content. */
-function parseMarkerFile(path: string): LivenessMarker | null {
-  try {
-    if (!existsSync(path)) return null;
-    const text = readFileSync(path, 'utf-8');
-    // A crash between create and write leaves a zero-byte file. Content, not
-    // existence, decides whether this marker says anything at all.
-    if (text.trim().length === 0) return null;
-    const parsed = JSON.parse(text) as Partial<LivenessMarker>;
-    if (typeof parsed.sessionId !== 'string' || typeof parsed.pid !== 'number' || typeof parsed.updatedAt !== 'number') return null;
-    if (!Number.isFinite(parsed.pid) || !Number.isFinite(parsed.updatedAt)) return null;
-    return { sessionId: parsed.sessionId, pid: parsed.pid, updatedAt: parsed.updatedAt };
-  } catch {
-    return null;
-  }
-}
-
-function readLivenessMarker(surface: SessionSurface, sessionId: string): LivenessMarker | null {
-  return parseMarkerFile(livenessMarkerPathFor(surface, sessionId));
-}
-
-/** Best-effort check that a pid still refers to a running process. Injectable for tests. */
-export function isPidAlive(pid: number, kill: (pid: number, signal: 0) => void = process.kill.bind(process)): boolean {
-  try {
-    kill(pid, 0);
-    return true;
-  } catch (err) {
-    // ESRCH = no such process. Any other error (e.g. EPERM — exists but this
-    // process lacks permission to signal it) is treated as "still alive" —
-    // best-effort here means erring toward not silently dropping a real warning.
-    return (err as NodeJS.ErrnoException | undefined)?.code === 'EPERM';
-  }
-}
-
-export interface SessionLivenessCheck {
-  readonly live: boolean;
-  readonly pid: number | null;
-}
-
-/**
- * Best-effort: is `sessionId` apparently open in another still-running
- * process right now? A missing, stale (older than LIVENESS_STALE_AFTER_MS),
- * or unreadable marker all resolve to `{ live: false, pid: null }` — never a
- * throw, never a block on the caller.
- */
-export function checkSessionLiveness(
-  surface: SessionSurface,
-  sessionId: string,
-  opts: { readonly now?: () => number; readonly isPidAliveFn?: typeof isPidAlive } = {},
-): SessionLivenessCheck {
-  const marker = readLivenessMarker(surface, sessionId);
-  if (!marker) return { live: false, pid: null };
-  const now = opts.now?.() ?? Date.now();
-  if (now - marker.updatedAt > LIVENESS_STALE_AFTER_MS) return { live: false, pid: null };
-  const aliveCheck = opts.isPidAliveFn ?? isPidAlive;
-  if (!aliveCheck(marker.pid)) return { live: false, pid: null };
-  return { live: true, pid: marker.pid };
-}
-
-// ─── Reaping ────────────────────────────────────────────────────────────────
-//
-// `removeLivenessMarker` only runs on a CLEAN exit (process-lifecycle.ts). A
-// SIGKILL, a panic, or a pulled power cord leaves the marker behind forever,
-// and `checkSessionLiveness` treating it as not-live does not remove the file
-// — so the liveness directory grows one file per session id ever opened. The
-// sweep below is the reclaim half of that lifecycle.
-
-/**
- * Hard ceiling on marker files kept after a sweep, oldest dropped first.
- *
- * The liveness rule below already reclaims ordinary crash residue, but it can
- * be defeated: `isPidAlive` deliberately reports EPERM (a pid this user cannot
- * signal) as alive, so on a busy host a reused pid can keep a dead session's
- * marker "live" indefinitely. This cap is the second, unconditional bound so
- * the directory can never grow without limit whatever the pid probe says.
- */
-export const LIVENESS_MARKER_MAX_FILES = 200;
-
-export interface LivenessReapResult {
-  /** Marker files examined this sweep. */
-  readonly scanned: number;
-  /** Marker files deleted this sweep. */
-  readonly reaped: number;
-}
-
-export interface LivenessReapOptions {
-  readonly now?: () => number;
-  readonly isPidAliveFn?: typeof isPidAlive;
-  /**
-   * Session ids that must never be reaped regardless of what the marker says
-   * — normally just the current session's id. Belt-and-braces: the current
-   * session refreshes its own marker every 60s, so the liveness rule already
-   * keeps it.
-   */
-  readonly keepSessionIds?: readonly string[];
-  /** Override the count cap (tests). */
-  readonly maxFiles?: number;
-}
-
-/**
- * Delete liveness markers that no longer describe a running session.
- *
- * A marker is reaped when it is either:
- *   - unreadable, empty, or not shaped like a marker (crash residue that can
- *     never resolve to a live session again — validated by parsing the
- *     content, not by the file merely existing); or
- *   - definitively not live: older than `LIVENESS_STALE_AFTER_MS` AND its pid
- *     no longer resolves to a running process.
- *
- * Both halves of that second rule are required on purpose. Deleting is
- * destructive while a liveness answer is only advisory, so a marker that is
- * stale-but-pid-alive (a wedged owner still holding the session) or
- * fresh-but-pid-dead (a process that died seconds ago, or a pid probe that
- * failed transiently) is left for a later sweep. A genuinely crashed session
- * satisfies both conditions within `LIVENESS_STALE_AFTER_MS` and is reclaimed
- * on the next sweep after that.
- *
- * Idempotent and safe to run concurrently from several processes: a marker
- * another sweeper unlinked between the directory listing and this unlink
- * (ENOENT) counts as reaped, never as an error.
- */
-export function reapStaleLivenessMarkers(surface: SessionSurface, opts: LivenessReapOptions = {}): LivenessReapResult {
-  const dir = livenessMarkerDirFor(surface);
-  let names: string[];
-  try {
-    names = readdirSync(dir).filter((name) => name.endsWith('.json'));
-  } catch {
-    // No liveness directory yet, or it is unreadable — nothing to reclaim.
-    return { scanned: 0, reaped: 0 };
-  }
-
-  const now = opts.now?.() ?? Date.now();
-  const aliveCheck = opts.isPidAliveFn ?? isPidAlive;
-  const keep = new Set(opts.keepSessionIds ?? []);
-  const maxFiles = opts.maxFiles ?? LIVENESS_MARKER_MAX_FILES;
-
-  let reaped = 0;
-  /** Survivors, so the count cap below can drop the oldest of them. */
-  const survivors: { readonly path: string; readonly updatedAt: number }[] = [];
-
-  for (const name of names) {
-    const sessionId = name.slice(0, -'.json'.length);
-    if (keep.has(sessionId)) continue;
-    const path = join(dir, name);
-    const marker = parseMarkerFile(path);
-    if (marker === null) {
-      if (unlinkIfPresent(path)) reaped++;
-      continue;
-    }
-    const stale = now - marker.updatedAt > LIVENESS_STALE_AFTER_MS;
-    if (stale && !aliveCheck(marker.pid)) {
-      if (unlinkIfPresent(path)) reaped++;
-      continue;
-    }
-    survivors.push({ path, updatedAt: marker.updatedAt });
-  }
-
-  if (survivors.length > maxFiles) {
-    survivors.sort((a, b) => a.updatedAt - b.updatedAt); // oldest first
-    for (const victim of survivors.slice(0, survivors.length - maxFiles)) {
-      if (unlinkIfPresent(victim.path)) reaped++;
-    }
-  }
-
-  return { scanned: names.length, reaped };
-}
-
-/**
- * Best-effort unlink shared by the sweep. Returns true when the file is gone
- * because of (or by the time of) this call. A concurrent sweeper winning the
- * race (ENOENT) is success, not failure; any other error leaves the file for
- * the next sweep.
- */
-function unlinkIfPresent(path: string): boolean {
-  try {
-    unlinkSync(path);
-    return true;
-  } catch (err) {
-    return (err as NodeJS.ErrnoException | undefined)?.code === 'ENOENT';
-  }
-}

package/src/runtime/session-pointer-surface.ts

@@ -1,22 +0,0 @@
-import { writeLastSessionPointer } from '@/runtime/index.ts';
-import type { SessionSurface } from '@/runtime/index.ts';
-
-/**
- * Binds the SDK's two-argument `writeLastSessionPointer(sessionId, options?)`
- * to one `SessionSurface`, returning a plain `(sessionId: string) => void`.
- *
- * Never pass the raw SDK function reference into a `(sessionId: string) =>
- * void` slot. A function with an extra optional parameter is structurally
- * assignable there, so it type-checks, but every downstream caller
- * (bootstrap-shell.ts -> bootstrap-hook-bridge.ts's resume handler) invokes
- * it with exactly one argument: `options` arrives as `undefined`, the legacy
- * compat path's `requireWorkingDirectory(undefined)` throws, and
- * `writeLastSessionPointer`'s own try/catch swallows that into a logged
- * warning. The pointer file then silently never gets written after a resume,
- * and the next launch's `--continue` / boot notice sees nothing. That was the
- * live defect at bootstrap.ts's `createBootstrapShell({ writeLastSessionPointer })`
- * call. See session-surface-pointer-journey.test.ts for the on-disk proof.
- */
-export function bindWriteLastSessionPointerToSurface(surface: SessionSurface): (sessionId: string) => void {
-  return (sessionId: string): void => writeLastSessionPointer(sessionId, { surface });
-}

package/src/runtime/session-storage-services.ts

@@ -1,41 +0,0 @@
-/**
- * session-storage-services.ts — the declare-once storage handle and the
- * session store built on it.
- *
- * Every path the app uses for session state (the sessions directory, the
- * last-session pointer, crash-recovery snapshots, the checkpoint store, the
- * transcript journal, the multi-instance liveness markers) derives from ONE
- * `SessionSurface`, built here, once, at composition time.
- *
- * The reason it is one object rather than a scope argument repeated at each
- * call site: when each site derived its own scope, they drifted. A resume
- * wrote the last-session pointer with no scope at all — into the shared,
- * unscoped `.goodvibes/` directory — while `--continue` and the boot notice
- * read a scoped path under `.goodvibes/tui/`. Nothing errored; the pointer
- * simply never existed where anyone looked. `createSessionSurface` also
- * throws synchronously on a bad scope instead of silently resolving to the
- * unscoped fallback on first use, so a mistake here fails at boot rather than
- * six months later as missing state.
- */
-import { SessionManager } from '@pellux/goodvibes-sdk/platform/sessions';
-import { createSessionSurface, type SessionSurface } from '@/runtime/index.ts';
-import { GOODVIBES_TUI_SURFACE_ROOT } from '../config/surface.ts';
-
-export interface SessionStorageServices {
-  readonly surface: SessionSurface;
-  readonly sessionManager: SessionManager;
-}
-
-export function createSessionStorageServices(input: {
-  readonly workingDirectory: string;
-  readonly homeDirectory: string;
-}): SessionStorageServices {
-  // Also performs the SDK's one-time migration of pre-surface state (pointer
-  // copy-forward, journal moves) into the scoped location.
-  const surface = createSessionSurface({
-    surfaceRoot: GOODVIBES_TUI_SURFACE_ROOT,
-    workingDirectory: input.workingDirectory,
-    homeDirectory: input.homeDirectory,
-  });
-  return { surface, sessionManager: new SessionManager(input.workingDirectory, { surface }) };
-}

package/src/runtime/surface-feature-flags.ts

@@ -1,96 +0,0 @@
-/**
- * surface-feature-flags — which platform capabilities a surface/server setup
- * needs, and how to switch them on through their real domain settings keys.
- *
- * Capabilities are configured through first-class domain settings (see
- * feature-settings.ts); enabling a surface writes keys like
- * `controlPlane.gateway` or `surfaces.slack.enabled`, never a separate
- * enablement namespace.
- */
-
-import type { ConfigManager } from '../config/index.ts';
-import { surfaceFeatureGateId } from '@/runtime/index.ts';
-import { featureEnablementWrite, getFeatureSetting, isFeatureConfigEnabled } from './feature-settings.ts';
-
-export const CONTROL_PLANE_FEATURE_FLAG = 'control-plane-gateway';
-export const ROUTE_BINDING_FEATURE_FLAG = 'route-binding';
-export const DELIVERY_ENGINE_FEATURE_FLAG = 'delivery-engine';
-export const SERVICE_MANAGEMENT_FEATURE_FLAG = 'service-management';
-
-const CORE_CHANNEL_FEATURE_FLAGS = [
-  CONTROL_PLANE_FEATURE_FLAG,
-  ROUTE_BINDING_FEATURE_FLAG,
-  DELIVERY_ENGINE_FEATURE_FLAG,
-] as const;
-
-export function getSurfaceFeatureFlag(surfaceId: string): string | null {
-  // Onboarding surface ids may be camelCase ('googleChat'); the SDK's gate
-  // map is keyed by the kebab-case ChannelSurface id ('google-chat'). Try the
-  // literal id first, then the kebab-case form, so choosing Google Chat in
-  // onboarding really flips google-chat-surface.
-  const literal = surfaceFeatureGateId(surfaceId);
-  if (literal) return literal;
-  const kebab = surfaceId.replace(/[A-Z]/g, (ch) => `-${ch.toLowerCase()}`);
-  return kebab === surfaceId ? null : surfaceFeatureGateId(kebab);
-}
-
-export function getServerSurfaceFeatureFlags(options: {
-  readonly serverBacked?: boolean;
-  readonly web?: boolean;
-  readonly externalSurfaces?: readonly string[];
-}): readonly string[] {
-  const flags = new Set<string>();
-  const hasExternalSurfaces = (options.externalSurfaces?.length ?? 0) > 0;
-
-  if (options.serverBacked || options.web || hasExternalSurfaces) {
-    flags.add(CONTROL_PLANE_FEATURE_FLAG);
-    flags.add(SERVICE_MANAGEMENT_FEATURE_FLAG);
-  }
-  if (options.web) {
-    const webFlag = getSurfaceFeatureFlag('web');
-    if (webFlag) flags.add(webFlag);
-  }
-
-  if (hasExternalSurfaces) {
-    for (const flag of CORE_CHANNEL_FEATURE_FLAGS) flags.add(flag);
-    for (const surfaceId of options.externalSurfaces ?? []) {
-      const surfaceFlag = getSurfaceFeatureFlag(surfaceId);
-      if (surfaceFlag) flags.add(surfaceFlag);
-    }
-  }
-
-  return [...flags].sort((left, right) => left.localeCompare(right));
-}
-
-/** Whether the live config has the capability on, derived from its domain settings key. */
-export function isFeatureFlagEnabled(config: Pick<ConfigManager, 'get'>, flagId: string): boolean {
-  return isFeatureConfigEnabled(config, flagId);
-}
-
-/**
- * Translate internal feature-gate ids (e.g. 'control-plane-gateway') to the
- * canonical domain settings keys the user actually sets (e.g.
- * 'controlPlane.gateway') — matching the SDK's own gate errors, which name the
- * settings key. A gate with no mapped setting falls back to its id. Deduped and
- * sorted for stable output.
- */
-export function surfaceFeatureGateSettingsKeys(flagIds: readonly string[]): string[] {
-  const keys = new Set<string>();
-  for (const flagId of flagIds) keys.add(getFeatureSetting(flagId)?.enablement.key ?? flagId);
-  return [...keys].sort((left, right) => left.localeCompare(right));
-}
-
-export function getMissingSurfaceFeatureFlags(config: Pick<ConfigManager, 'get'>, surfaceId: string): readonly string[] {
-  const required = surfaceId === 'web'
-    ? getServerSurfaceFeatureFlags({ web: true })
-    : getServerSurfaceFeatureFlags({ externalSurfaces: [surfaceId] });
-  return required.filter((flagId) => !isFeatureFlagEnabled(config, flagId));
-}
-
-/** Switch each capability on by writing its real enablement settings key. */
-export function enableFeatureFlags(config: Pick<ConfigManager, 'setDynamic'>, flagIds: readonly string[]): void {
-  for (const flagId of flagIds) {
-    const write = featureEnablementWrite(flagId, true);
-    if (write) config.setDynamic(write.key, write.value);
-  }
-}

package/src/runtime/terminal-output-guard.ts

@@ -1,235 +0,0 @@
-import { format } from 'node:util';
-import { logger } from '@pellux/goodvibes-sdk/platform/utils';
-
-type WritableStreamLike = {
-  write: {
-    (buffer: string | Uint8Array, cb?: (error?: Error | null) => void): boolean;
-    (buffer: string | Uint8Array, encoding?: BufferEncoding, cb?: (error?: Error | null) => void): boolean;
-  };
-};
-
-export type TerminalOutputInterceptSource =
-  | 'stdout'
-  | 'stderr'
-  | 'console.debug'
-  | 'console.error'
-  | 'console.info'
-  | 'console.log'
-  | 'console.warn';
-
-export type TerminalOutputIntercept = {
-  readonly source: TerminalOutputInterceptSource;
-  readonly text: string;
-  readonly preview: string;
-};
-
-export type TerminalOutputGuard = {
-  setActive(active: boolean): void;
-  allowTerminalWrite<T>(fn: () => T): T;
-  dispose(): void;
-};
-
-export type TerminalOutputGuardOptions = {
-  readonly stdout: WritableStreamLike;
-  readonly stderr?: WritableStreamLike;
-  readonly active?: boolean;
-  readonly onIntercept?: (event: TerminalOutputIntercept) => void;
-};
-
-export type TuiTerminalOutputGuardOptions = {
-  readonly stdout: WritableStreamLike;
-  readonly stderr?: WritableStreamLike;
-  readonly active?: boolean;
-  /**
-   * Called (rate-limited) after intercepts with the cumulative count of direct
-   * writes captured this session, so an honest quiet counter (e.g. /debug) can
-   * refresh. The per-write detail is already recorded to the activity log via
-   * logger.warn — this callback intentionally does NOT push transcript lines.
-   * (item 1a.)
-   */
-  readonly onCapture?: (total: number) => void;
-};
-
-const MAX_LOG_TEXT = 4_000;
-const MAX_PREVIEW_TEXT = 180;
-const ANSI_RE = /\x1b\[[0-?]*[ -/]*[@-~]/g;
-
-let currentGuard: TerminalOutputGuard | null = null;
-
-function writeCallback(args: unknown[]): ((error?: Error | null) => void) | undefined {
-  const maybeCallback = args[args.length - 1];
-  return typeof maybeCallback === 'function'
-    ? maybeCallback as (error?: Error | null) => void
-    : undefined;
-}
-
-function chunkToText(chunk: unknown): string {
-  if (typeof chunk === 'string') return chunk;
-  if (chunk instanceof Uint8Array) return Buffer.from(chunk).toString('utf8');
-  return String(chunk);
-}
-
-function normalizeText(text: string): string {
-  return text.replace(ANSI_RE, '').replace(/\r/g, '').trim();
-}
-
-function previewText(text: string): string {
-  const singleLine = normalizeText(text).replace(/\s+/g, ' ');
-  if (singleLine.length <= MAX_PREVIEW_TEXT) return singleLine;
-  return `${singleLine.slice(0, MAX_PREVIEW_TEXT - 1)}...`;
-}
-
-function truncateForLog(text: string): string {
-  if (text.length <= MAX_LOG_TEXT) return text;
-  return `${text.slice(0, MAX_LOG_TEXT)}\n[truncated ${text.length - MAX_LOG_TEXT} byte(s)]`;
-}
-
-function invokeSuppressedCallback(args: unknown[]): void {
-  const callback = writeCallback(args);
-  if (callback) {
-    queueMicrotask(() => callback(null));
-  }
-}
-
-export function allowTerminalWrite<T>(fn: () => T): T {
-  return currentGuard ? currentGuard.allowTerminalWrite(fn) : fn();
-}
-
-export function installTerminalOutputGuard(options: TerminalOutputGuardOptions): TerminalOutputGuard {
-  const stdout = options.stdout;
-  const stderr = options.stderr ?? process.stderr;
-  const originalStdoutWriteMethod = stdout.write;
-  const originalStderrWriteMethod = stderr.write;
-  const originalStdoutWrite = (...args: unknown[]): boolean =>
-    Reflect.apply(originalStdoutWriteMethod, stdout, args) as boolean;
-  const originalStderrWrite = (...args: unknown[]): boolean =>
-    Reflect.apply(originalStderrWriteMethod, stderr, args) as boolean;
-  const originalConsole = {
-    debug: console.debug.bind(console),
-    error: console.error.bind(console),
-    info: console.info.bind(console),
-    log: console.log.bind(console),
-    warn: console.warn.bind(console),
-  };
-
-  let active = options.active ?? true;
-  let disposed = false;
-  let allowDepth = 0;
-  let captureDepth = 0;
-
-  const record = (source: TerminalOutputInterceptSource, text: string): void => {
-    if (disposed || !active) return;
-    const normalized = normalizeText(text);
-    if (!normalized) return;
-    if (normalized.startsWith('[ActivityLogger]')) return;
-    if (captureDepth > 0) return;
-
-    captureDepth++;
-    try {
-      const event: TerminalOutputIntercept = {
-        source,
-        text: truncateForLog(normalized),
-        preview: previewText(normalized),
-      };
-      logger.warn('Intercepted terminal output while TUI renderer was active', {
-        source: event.source,
-        text: event.text,
-      });
-      options.onIntercept?.(event);
-    } finally {
-      captureDepth--;
-    }
-  };
-
-  const shouldPassThrough = (): boolean => !active || allowDepth > 0 || disposed;
-
-  stdout.write = ((...args: unknown[]) => {
-    if (shouldPassThrough()) {
-      return originalStdoutWrite(...args);
-    }
-    record('stdout', chunkToText(args[0]));
-    invokeSuppressedCallback(args);
-    return true;
-  }) as WritableStreamLike['write'];
-
-  stderr.write = ((...args: unknown[]) => {
-    if (shouldPassThrough()) {
-      return originalStderrWrite(...args);
-    }
-    record('stderr', chunkToText(args[0]));
-    invokeSuppressedCallback(args);
-    return true;
-  }) as WritableStreamLike['write'];
-
-  console.debug = (...args: unknown[]) => {
-    if (!active || disposed) return originalConsole.debug(...args);
-    record('console.debug', format(...args));
-  };
-  console.error = (...args: unknown[]) => {
-    if (!active || disposed) return originalConsole.error(...args);
-    record('console.error', format(...args));
-  };
-  console.info = (...args: unknown[]) => {
-    if (!active || disposed) return originalConsole.info(...args);
-    record('console.info', format(...args));
-  };
-  console.log = (...args: unknown[]) => {
-    if (!active || disposed) return originalConsole.log(...args);
-    record('console.log', format(...args));
-  };
-  console.warn = (...args: unknown[]) => {
-    if (!active || disposed) return originalConsole.warn(...args);
-    record('console.warn', format(...args));
-  };
-
-  const guard: TerminalOutputGuard = {
-    setActive(nextActive) {
-      active = nextActive;
-    },
-    allowTerminalWrite<T>(fn: () => T): T {
-      allowDepth++;
-      try {
-        return fn();
-      } finally {
-        allowDepth--;
-      }
-    },
-    dispose() {
-      if (disposed) return;
-      disposed = true;
-      stdout.write = originalStdoutWriteMethod;
-      stderr.write = originalStderrWriteMethod;
-      console.debug = originalConsole.debug;
-      console.error = originalConsole.error;
-      console.info = originalConsole.info;
-      console.log = originalConsole.log;
-      console.warn = originalConsole.warn;
-      if (currentGuard === guard) {
-        currentGuard = null;
-      }
-    },
-  };
-
-  currentGuard = guard;
-  return guard;
-}
-
-export function installTuiTerminalOutputGuard(options: TuiTerminalOutputGuardOptions): TerminalOutputGuard {
-  let totalInterceptedWrites = 0;
-  let lastNoticeAt = 0;
-  return installTerminalOutputGuard({
-    stdout: options.stdout,
-    stderr: options.stderr,
-    active: options.active,
-    onIntercept: () => {
-      // Each intercept is already logged (logger.warn in record()). Here we only
-      // maintain a cumulative counter and, rate-limited, refresh a quiet counter
-      // surface — no repeated transcript lines. (item 1a.)
-      totalInterceptedWrites++;
-      const now = Date.now();
-      if (now - lastNoticeAt < 5_000) return;
-      lastNoticeAt = now;
-      options.onCapture?.(totalInterceptedWrites);
-    },
-  });
-}