feat(ink): auto compat mode for legacy pre-ConPTY Windows consoles (#1299)

* feat: 老旧 Windows 控制台（pre-ConPTY）自动兼容模式

Windows 10 build < 17763（1709/LTSC 等无 ConPTY 的内网机器）上，
老 conhost 的 VT 解析器对增量渲染的行尾 pending-wrap 语义处理有误，
真实光标与虚拟光标漂移，花屏残渣持续累积，直到一次全量重绘才消除。
该问题影响此类机器上的所有终端（VS Code/mintty 走 winpty 抓取的
是同一份损坏的 conhost buffer）。

- 新增 legacyConsole.ts：按 os.release() build 号自动检测，
  CLAUDE_CODE_LEGACY_CONSOLE=1/0 可强制开/关
- log-update.ts：命中时每约 1 秒用一次全量重绘替换增量 diff，
  屏幕持续自愈；非老控制台环境完全不走此路径
- 6 个单元测试（检测逻辑 + 环境变量覆盖 + 缓存行为）

* docs: CLAUDE.md 补充老控制台兼容模式说明，修正版本号描述

* feat: 老控制台兼容模式支持强度调节

真机（1709/build 16299）第一轮验证反馈周期性自愈可能不足，
增加两个调节旋钮：

- CLAUDE_CODE_LEGACY_CONSOLE=2（或 always）：每帧全量重绘，
  用于增量 diff 立即花屏、1 秒自愈不够的机器
- CLAUDE_CODE_LEGACY_CONSOLE_RESET_MS：周期模式的重绘间隔，
  钳制在 [100, 10000]，默认 1000 不变

默认行为不变（自动检测 → periodic 1s）。新增 9 个单元测试
（模式解析、间隔钳制、空串回退、缓存行为）。

* fix: 老控制台花屏根因修复——渲染宽度收窄 1 列绕开 pending-wrap

真机（1709/build 16299）第二轮反馈：周期性全量重绘在跑（可见闪烁）
但花屏范围随重绘扩大。定位到真正根因：老 conhost 对 pending-wrap
的处理是「写满最后一列立即换行」（现代终端为挂起等待），任何顶满
行宽的输出（分隔线、满行文本）都会把真实光标多推一行——增量 diff
和全量重绘同样受害，且每次重绘还把缓冲区多滚几行，旧帧残渣上移，
表现为「越闪越花」。

修复：legacy 模式下 effectiveColumns() 把渲染宽度收窄 1 列
（下限 20），任何一行都不再触碰最后一列，pending-wrap 缺陷路径
从源头绕开；周期重绘保留作为兜底自愈。非 legacy 环境行为完全不变。

新增 effectiveColumns 单元测试；ink.tsx 三处宽度读取统一走该函数。

Author: Jade-beads

CLAUDE.md

@@ -87,7 +87,7 @@ bun run docs:dev
 - **Lint/Format**: Biome (`biome.json`)。覆盖 `src/`、`scripts/`、`packages/` 全项目（含 `packages/@ant/`）。`bun run lint` / `bun run lint:fix` / `bun run format` / `bun run check` / `bun run check:fix`。42 条规则因 decompiled 代码被关闭，仅保留 `recommended` 基线。
 - **Pre-commit**: husky + lint-staged。提交时自动对暂存文件执行 `biome check --fix`（TS/JS）和 `biome format --write`（JSON）。
 - **CI Lint**: `ci.yml` 在依赖安装后、类型检查前执行 `bunx biome ci .`，lint 或格式化不达标则 CI 失败。
-- **Defines**: 集中管理在 `scripts/defines.ts`。当前版本 `2.2.1`。
+- **Defines**: 集中管理在 `scripts/defines.ts`。版本号从 `package.json` 读取（不再硬编码）。
 - **CI**: GitHub Actions — `ci.yml`（lint + 构建 + 测试）、`release-rcs.yml`（RCS 发布）、`update-contributors.yml`（自动更新贡献者）。
 
 ### Entry & Bootstrap
@@ -141,6 +141,7 @@ bun run docs:dev
 
 - **`src/ink.ts`** — Ink render wrapper with ThemeProvider injection.
 - **`packages/@ant/ink/`** — Custom Ink framework（forked/internal），包含 components、core、hooks、keybindings、theme、utils。注意：不是 `src/ink/`。
+- **老控制台兼容模式** — `packages/@ant/ink/src/core/legacyConsole.ts`：检测 Windows build < 17763（无 ConPTY 的老系统，如 1709/LTSC 内网机器）时自动启用；`log-update.ts` 的渲染循环每约 1 秒（`LEGACY_CONSOLE_RESET_MS`）用一次全量重绘替换增量 diff，自愈老 conhost 的光标漂移花屏。`CLAUDE_CODE_LEGACY_CONSOLE=1`/`=0` 可强制开/关。其他环境完全不走此路径。
 - **`src/components/`** — 149 个组件目录/文件，渲染于终端 Ink 环境中。关键组件：
   - `App.tsx` — Root provider (AppState, Stats, FpsMetrics)
   - `Messages.tsx` / `MessageRow.tsx` — Conversation message rendering

packages/@ant/ink/src/core/__tests__/legacyConsole.test.ts

@@ -0,0 +1,157 @@
+import { afterEach, describe, expect, test } from 'bun:test'
+import {
+  effectiveColumns,
+  isLegacyWindowsBuild,
+  isLegacyWindowsConsole,
+  legacyConsoleMode,
+  legacyConsoleResetMs,
+  parseLegacyConsoleMode,
+  parseLegacyConsoleResetMs,
+  resetLegacyConsoleCacheForTesting,
+} from '../legacyConsole.js'
+
+const savedOverride = process.env.CLAUDE_CODE_LEGACY_CONSOLE
+const savedResetMs = process.env.CLAUDE_CODE_LEGACY_CONSOLE_RESET_MS
+
+function restoreEnv(name: string, value: string | undefined): void {
+  if (value === undefined) {
+    delete process.env[name]
+  } else {
+    process.env[name] = value
+  }
+}
+
+describe('isLegacyWindowsBuild', () => {
+  test('build below 17763 (pre-ConPTY) is legacy', () => {
+    expect(isLegacyWindowsBuild('10.0.16299')).toBe(true)
+    expect(isLegacyWindowsBuild('10.0.14393')).toBe(true)
+  })
+
+  test('build 17763 and newer are not legacy', () => {
+    expect(isLegacyWindowsBuild('10.0.17763')).toBe(false)
+    expect(isLegacyWindowsBuild('10.0.19045')).toBe(false)
+    expect(isLegacyWindowsBuild('10.0.22631')).toBe(false)
+  })
+
+  test('unparseable release strings are not legacy', () => {
+    expect(isLegacyWindowsBuild('')).toBe(false)
+    expect(isLegacyWindowsBuild('6.1')).toBe(false)
+    expect(isLegacyWindowsBuild('10.0.abc')).toBe(false)
+  })
+})
+
+describe('parseLegacyConsoleMode', () => {
+  test('0 forces off even when auto-detected', () => {
+    expect(parseLegacyConsoleMode('0', true)).toBe('off')
+  })
+
+  test('1 forces periodic even without auto-detection', () => {
+    expect(parseLegacyConsoleMode('1', false)).toBe('periodic')
+  })
+
+  test('2 and always select every-frame mode', () => {
+    expect(parseLegacyConsoleMode('2', false)).toBe('always')
+    expect(parseLegacyConsoleMode('always', false)).toBe('always')
+  })
+
+  test('no override follows auto-detection', () => {
+    expect(parseLegacyConsoleMode(undefined, true)).toBe('periodic')
+    expect(parseLegacyConsoleMode(undefined, false)).toBe('off')
+  })
+
+  test('unknown override values follow auto-detection', () => {
+    expect(parseLegacyConsoleMode('yes', true)).toBe('periodic')
+    expect(parseLegacyConsoleMode('yes', false)).toBe('off')
+  })
+})
+
+describe('parseLegacyConsoleResetMs', () => {
+  test('defaults to 1000 for missing or garbage values', () => {
+    expect(parseLegacyConsoleResetMs(undefined)).toBe(1000)
+    expect(parseLegacyConsoleResetMs('')).toBe(1000)
+    expect(parseLegacyConsoleResetMs('abc')).toBe(1000)
+  })
+
+  test('clamps to [100, 10000] and floors', () => {
+    expect(parseLegacyConsoleResetMs('50')).toBe(100)
+    expect(parseLegacyConsoleResetMs('250.9')).toBe(250)
+    expect(parseLegacyConsoleResetMs('99999')).toBe(10000)
+  })
+})
+
+describe('effectiveColumns', () => {
+  afterEach(() => {
+    restoreEnv('CLAUDE_CODE_LEGACY_CONSOLE', savedOverride)
+    resetLegacyConsoleCacheForTesting()
+  })
+
+  test('passes width through when legacy mode is off', () => {
+    process.env.CLAUDE_CODE_LEGACY_CONSOLE = '0'
+    resetLegacyConsoleCacheForTesting()
+    expect(effectiveColumns(120)).toBe(120)
+    expect(effectiveColumns(undefined)).toBe(80)
+    expect(effectiveColumns(0)).toBe(80)
+  })
+
+  test('narrows by one column on legacy consoles (with floor)', () => {
+    process.env.CLAUDE_CODE_LEGACY_CONSOLE = '1'
+    resetLegacyConsoleCacheForTesting()
+    expect(effectiveColumns(120)).toBe(119)
+    expect(effectiveColumns(undefined)).toBe(79)
+    expect(effectiveColumns(21)).toBe(20)
+    expect(effectiveColumns(5)).toBe(20)
+  })
+})
+
+describe('legacyConsoleMode / isLegacyWindowsConsole / legacyConsoleResetMs', () => {
+  afterEach(() => {
+    restoreEnv('CLAUDE_CODE_LEGACY_CONSOLE', savedOverride)
+    restoreEnv('CLAUDE_CODE_LEGACY_CONSOLE_RESET_MS', savedResetMs)
+    resetLegacyConsoleCacheForTesting()
+  })
+
+  test('CLAUDE_CODE_LEGACY_CONSOLE=1 forces legacy mode on', () => {
+    process.env.CLAUDE_CODE_LEGACY_CONSOLE = '1'
+    resetLegacyConsoleCacheForTesting()
+    expect(isLegacyWindowsConsole()).toBe(true)
+    expect(legacyConsoleMode()).toBe('periodic')
+  })
+
+  test('CLAUDE_CODE_LEGACY_CONSOLE=0 forces legacy mode off', () => {
+    process.env.CLAUDE_CODE_LEGACY_CONSOLE = '0'
+    resetLegacyConsoleCacheForTesting()
+    expect(isLegacyWindowsConsole()).toBe(false)
+    expect(legacyConsoleMode()).toBe('off')
+  })
+
+  test('CLAUDE_CODE_LEGACY_CONSOLE=2 selects every-frame mode', () => {
+    process.env.CLAUDE_CODE_LEGACY_CONSOLE = '2'
+    resetLegacyConsoleCacheForTesting()
+    expect(isLegacyWindowsConsole()).toBe(true)
+    expect(legacyConsoleMode()).toBe('always')
+  })
+
+  test('reset interval is read from env with clamping', () => {
+    process.env.CLAUDE_CODE_LEGACY_CONSOLE_RESET_MS = '250'
+    resetLegacyConsoleCacheForTesting()
+    expect(legacyConsoleResetMs()).toBe(250)
+    process.env.CLAUDE_CODE_LEGACY_CONSOLE_RESET_MS = '1'
+    resetLegacyConsoleCacheForTesting()
+    expect(legacyConsoleResetMs()).toBe(100)
+  })
+
+  test('caches the computed values until reset', () => {
+    process.env.CLAUDE_CODE_LEGACY_CONSOLE = '1'
+    process.env.CLAUDE_CODE_LEGACY_CONSOLE_RESET_MS = '500'
+    resetLegacyConsoleCacheForTesting()
+    expect(isLegacyWindowsConsole()).toBe(true)
+    expect(legacyConsoleResetMs()).toBe(500)
+    process.env.CLAUDE_CODE_LEGACY_CONSOLE = '0'
+    process.env.CLAUDE_CODE_LEGACY_CONSOLE_RESET_MS = '9000'
+    expect(isLegacyWindowsConsole()).toBe(true)
+    expect(legacyConsoleResetMs()).toBe(500)
+    resetLegacyConsoleCacheForTesting()
+    expect(isLegacyWindowsConsole()).toBe(false)
+    expect(legacyConsoleResetMs()).toBe(9000)
+  })
+})

packages/@ant/ink/src/core/ink.tsx

@@ -93,6 +93,7 @@ import {
   wrapForMultiplexer,
 } from './termio/osc.js';
 import { TerminalWriteProvider } from '../hooks/useTerminalNotification.js';
+import { effectiveColumns } from './legacyConsole.js';
 
 // Alt-screen: renderer.ts sets cursor.visible = !isTTY || screen.height===0,
 // which is always false in alt-screen (TTY + content fills screen).
@@ -247,7 +248,7 @@ export default class Ink {
       stderr: options.stderr,
     };
 
-    this.terminalColumns = options.stdout.columns || 80;
+    this.terminalColumns = effectiveColumns(options.stdout.columns);
     this.terminalRows = options.stdout.rows || 24;
     this.altScreenParkPatch = makeAltScreenParkPatch(this.terminalRows);
     this.stylePool = new StylePool();
@@ -396,7 +397,7 @@ export default class Ink {
   // blank→paint flicker). useVirtualScroll's height scaling already bounds
   // the per-resize cost; synchronous handling keeps dimensions consistent.
   private handleResize = () => {
-    const cols = this.options.stdout.columns || 80;
+    const cols = effectiveColumns(this.options.stdout.columns);
     const rows = this.options.stdout.rows || 24;
     // Terminals often emit 2+ resize events for one user action (window
     // settling). Same-dimension events are no-ops; skip to avoid redundant
@@ -522,7 +523,7 @@ export default class Ink {
     this.options.onBeforeRender?.();
 
     const renderStart = performance.now();
-    const terminalWidth = this.options.stdout.columns || 80;
+    const terminalWidth = effectiveColumns(this.options.stdout.columns);
     const terminalRows = this.options.stdout.rows || 24;
 
     const frame = this.renderer({

packages/@ant/ink/src/core/legacyConsole.ts

@@ -0,0 +1,98 @@
+import { release } from 'node:os'
+
+/**
+ * Legacy Windows console detection (pre-ConPTY).
+ *
+ * ConPTY shipped in Windows 10 1809 (build 17763). On older builds the
+ * conhost VT parser predates it and mis-handles incremental TUI updates
+ * (pending-wrap semantics at the last column drift the real cursor away
+ * from the virtual one), so residue accumulates until a full repaint.
+ * Every terminal on such a machine is affected — VS Code and mintty fall
+ * back to winpty, which scrapes the same corrupted conhost buffer.
+ *
+ * Overrides:
+ *   CLAUDE_CODE_LEGACY_CONSOLE=0        force off
+ *   CLAUDE_CODE_LEGACY_CONSOLE=1        force on (periodic full repaint)
+ *   CLAUDE_CODE_LEGACY_CONSOLE=2|always full repaint on EVERY frame — for
+ *     machines where each incremental diff corrupts immediately and the
+ *     periodic self-heal is not enough. Maximum flicker, maximum
+ *     correctness.
+ *   CLAUDE_CODE_LEGACY_CONSOLE_RESET_MS=<ms>
+ *     periodic repaint interval, clamped to [100, 10000]. Default 1000.
+ */
+
+export type LegacyConsoleMode = 'off' | 'periodic' | 'always'
+
+/** Pure build-number check, exported for tests. */
+export function isLegacyWindowsBuild(releaseString: string): boolean {
+  const build = Number(releaseString.split('.')[2])
+  return Number.isFinite(build) && build < 17763
+}
+
+/** Pure override/auto-detect resolution, exported for tests. */
+export function parseLegacyConsoleMode(
+  override: string | undefined,
+  autoDetected: boolean,
+): LegacyConsoleMode {
+  if (override === '0') return 'off'
+  if (override === '2' || override === 'always') return 'always'
+  if (override === '1') return 'periodic'
+  return autoDetected ? 'periodic' : 'off'
+}
+
+/** Pure interval parser with clamping, exported for tests. */
+export function parseLegacyConsoleResetMs(raw: string | undefined): number {
+  // Number('') === 0, so an empty env var must be treated as unset.
+  if (raw === undefined || raw.trim() === '') return 1000
+  const parsed = Number(raw)
+  if (!Number.isFinite(parsed)) return 1000
+  return Math.min(10_000, Math.max(100, Math.floor(parsed)))
+}
+
+let cachedMode: LegacyConsoleMode | undefined
+let cachedResetMs: number | undefined
+
+export function legacyConsoleMode(): LegacyConsoleMode {
+  if (cachedMode === undefined) {
+    cachedMode = parseLegacyConsoleMode(
+      process.env.CLAUDE_CODE_LEGACY_CONSOLE,
+      process.platform === 'win32' && isLegacyWindowsBuild(release()),
+    )
+  }
+  return cachedMode
+}
+
+export function isLegacyWindowsConsole(): boolean {
+  return legacyConsoleMode() !== 'off'
+}
+
+export function legacyConsoleResetMs(): number {
+  if (cachedResetMs === undefined) {
+    cachedResetMs = parseLegacyConsoleResetMs(
+      process.env.CLAUDE_CODE_LEGACY_CONSOLE_RESET_MS,
+    )
+  }
+  return cachedResetMs
+}
+
+/**
+ * Effective render width for the terminal.
+ *
+ * Legacy conhost mis-handles pending-wrap: writing the last column wraps
+ * immediately (modern terminals defer the wrap), so every full-width line
+ * pushes the real cursor one row past where the renderer believes it is —
+ * both incremental diffs AND full repaints drift, and each full repaint
+ * scrolls extra lines into view (the "garbage grows with every flash"
+ * failure mode). Rendering one column narrower means no line ever touches
+ * the last column, so the buggy code path never fires.
+ */
+export function effectiveColumns(columns: number | undefined): number {
+  const cols = columns || 80
+  if (!isLegacyWindowsConsole()) return cols
+  return Math.max(20, cols - 1)
+}
+
+export function resetLegacyConsoleCacheForTesting(): void {
+  cachedMode = undefined
+  cachedResetMs = undefined
+}

packages/@ant/ink/src/core/log-update.ts

@@ -28,6 +28,11 @@ import {
   setScrollRegion,
 } from './termio/csi.js'
 import { LINK_END, link as oscLink } from './termio/osc.js'
+import {
+  isLegacyWindowsConsole,
+  legacyConsoleMode,
+  legacyConsoleResetMs,
+} from './legacyConsole.js'
 
 type State = {
   previousOutput: string
@@ -43,6 +48,8 @@ const NEWLINE = { type: 'stdout', content: '\n' } as const
 
 export class LogUpdate {
   private state: State
+  // Timestamp of the last legacy-console full reset (see render()).
+  private lastLegacyReset = 0
 
   constructor(private readonly options: Options) {
     this.state = {
@@ -147,6 +154,23 @@ export class LogUpdate {
       return fullResetSequence_CAUSES_FLICKER(next, 'resize', stylePool)
     }
 
+    // Legacy Windows console (pre-ConPTY, build < 17763): the old conhost
+    // VT parser drifts on incremental cursor diffs (pending-wrap semantics
+    // at the last column), so residue accumulates until a full repaint.
+    // Replace the diff with a full reset — every frame in 'always' mode
+    // (machines where each diff corrupts immediately), otherwise on a
+    // configurable interval so the screen self-heals. Gated off everywhere
+    // else; see legacyConsole.ts.
+    if (isLegacyWindowsConsole()) {
+      if (
+        legacyConsoleMode() === 'always' ||
+        startTime - this.lastLegacyReset >= legacyConsoleResetMs()
+      ) {
+        this.lastLegacyReset = startTime
+        return fullResetSequence_CAUSES_FLICKER(next, 'clear', stylePool)
+      }
+    }
+
     // DECSTBM scroll optimization: when a ScrollBox's scrollTop changed,
     // shift content with a hardware scroll (CSI top;bot r + CSI n S/T)
     // instead of rewriting the whole scroll region. The shiftRows on