Sync public snapshot from freebuff-private

github-actions[bot] · github-actions[bot] · commit 7f9bb4e107e2 · 2026-07-03T22:08:15.000Z
Source: CodebuffAI/freebuff-private@f16ff43dd50b978b8ea0798aecd070718176cd02
diff --git a/bun.lock b/bun.lock
diff --git a/cli/release-staging/index.js b/cli/release-staging/index.js
@@ -26,6 +26,8 @@ const SAFE_TERMINAL_RESET_SEQUENCES =
   '\x1b[?1006l' + // Disable SGR extended mouse mode
   '\x1b[?1004l' + // Disable focus reporting
   '\x1b[?2004l' + // Disable bracketed paste mode
+  '\x1b[<u' + // Pop kitty keyboard protocol flags
+  '\x1b[>4;0m' + // Reset modifyOtherKeys
   '\x1b[?25h' // Show cursor
 
 const FULL_TERMINAL_RESET_SEQUENCES =
diff --git a/cli/release/index.js b/cli/release/index.js
@@ -26,6 +26,8 @@ const SAFE_TERMINAL_RESET_SEQUENCES =
   '\x1b[?1006l' + // Disable SGR extended mouse mode
   '\x1b[?1004l' + // Disable focus reporting
   '\x1b[?2004l' + // Disable bracketed paste mode
+  '\x1b[<u' + // Pop kitty keyboard protocol flags
+  '\x1b[>4;0m' + // Reset modifyOtherKeys
   '\x1b[?25h' // Show cursor
 
 const FULL_TERMINAL_RESET_SEQUENCES =
diff --git a/cli/src/__tests__/helpers/terminal-watchdog-fixture.ts b/cli/src/__tests__/helpers/terminal-watchdog-fixture.ts
@@ -0,0 +1,31 @@
+/**
+ * Fixture process for terminal-watchdog.test.ts.
+ *
+ * Usage: bun terminal-watchdog-fixture.ts <mode> <ttyPath>
+ * - mode "hang":  start the watchdog and stay alive until killed by the test.
+ * - mode "clean": start the watchdog, then stop it and exit (clean shutdown).
+ *
+ * Prints "ready" once the watchdog is armed so the test knows when to kill.
+ */
+import {
+  startTerminalWatchdog,
+  stopTerminalWatchdog,
+} from '../../utils/terminal-watchdog'
+
+const [mode, ttyPath] = process.argv.slice(2)
+
+if (!mode || !ttyPath) {
+  console.error('usage: terminal-watchdog-fixture.ts <hang|clean> <ttyPath>')
+  process.exit(2)
+}
+
+startTerminalWatchdog({ ttyPath })
+
+if (mode === 'clean') {
+  stopTerminalWatchdog()
+  console.log('ready')
+  process.exit(0)
+}
+
+console.log('ready')
+setInterval(() => {}, 1_000)
diff --git a/cli/src/__tests__/terminal-reset-sequences.test.ts b/cli/src/__tests__/terminal-reset-sequences.test.ts
@@ -0,0 +1,40 @@
+import { readFileSync } from 'fs'
+import { join } from 'path'
+
+import { describe, expect, test } from 'bun:test'
+
+import { TERMINAL_RESET_SEQUENCES } from '../utils/terminal-reset-sequences'
+
+/**
+ * The npm wrapper release scripts are standalone published JS that can't
+ * import the TS constant, so each carries its own copy of the reset
+ * sequences (split into EXIT_ALTERNATE_SCREEN_SEQUENCE +
+ * SAFE_TERMINAL_RESET_SEQUENCES). This guard turns silent drift into a test
+ * failure: every sequence in the TS constant must appear as a source
+ * literal in every wrapper.
+ */
+const REPO_ROOT = join(import.meta.dir, '..', '..', '..')
+
+const WRAPPER_PATHS = [
+  'cli/release/index.js',
+  'cli/release-staging/index.js',
+  'freebuff/cli/release/index.js',
+]
+
+/** Split the runtime constant into per-sequence source literals ('\x1b…'). */
+function sequenceSourceLiterals(): string[] {
+  return TERMINAL_RESET_SEQUENCES.split('\x1b')
+    .filter(Boolean)
+    .map((rest) => `'\\x1b${rest}'`)
+}
+
+describe('terminal reset sequence copies stay in sync', () => {
+  for (const wrapperPath of WRAPPER_PATHS) {
+    test(wrapperPath, () => {
+      const source = readFileSync(join(REPO_ROOT, wrapperPath), 'utf8')
+      for (const literal of sequenceSourceLiterals()) {
+        expect(source).toContain(literal)
+      }
+    })
+  }
+})
diff --git a/cli/src/__tests__/terminal-watchdog.test.ts b/cli/src/__tests__/terminal-watchdog.test.ts
@@ -0,0 +1,88 @@
+import { spawn } from 'child_process'
+import { mkdtempSync, readFileSync, rmSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+
+import { afterAll, describe, expect, test } from 'bun:test'
+
+import { TERMINAL_RESET_SEQUENCES } from '../utils/terminal-reset-sequences'
+
+import type { ChildProcess } from 'child_process'
+
+const FIXTURE = join(import.meta.dir, 'helpers', 'terminal-watchdog-fixture.ts')
+
+const tempDir = mkdtempSync(join(tmpdir(), 'terminal-watchdog-'))
+
+afterAll(() => {
+  rmSync(tempDir, { recursive: true, force: true })
+})
+
+function spawnFixture(mode: 'hang' | 'clean', ttyPath: string): ChildProcess {
+  return spawn(process.execPath, [FIXTURE, mode, ttyPath], {
+    stdio: ['ignore', 'pipe', 'inherit'],
+  })
+}
+
+/** Resolve once the fixture prints "ready" (watchdog armed). */
+function waitForReady(child: ChildProcess): Promise<void> {
+  return new Promise((resolve, reject) => {
+    let out = ''
+    child.stdout!.on('data', (chunk: Buffer) => {
+      out += chunk.toString()
+      if (out.includes('ready')) resolve()
+    })
+    child.on('exit', () => resolve()) // "clean" mode exits immediately
+    child.on('error', reject)
+  })
+}
+
+function waitForExit(child: ChildProcess): Promise<void> {
+  return new Promise((resolve) => {
+    if (child.exitCode !== null || child.signalCode !== null) return resolve()
+    child.on('exit', () => resolve())
+  })
+}
+
+function readTty(ttyPath: string): string {
+  try {
+    return readFileSync(ttyPath, 'utf8')
+  } catch {
+    return ''
+  }
+}
+
+async function pollForContent(ttyPath: string, timeoutMs: number): Promise<string> {
+  const deadline = Date.now() + timeoutMs
+  while (Date.now() < deadline) {
+    const content = readTty(ttyPath)
+    if (content) return content
+    await new Promise((r) => setTimeout(r, 50))
+  }
+  return readTty(ttyPath)
+}
+
+// The watchdog is POSIX-only (sh + /dev/tty); on Windows the npm wrapper is
+// the safety net instead.
+describe.skipIf(process.platform === 'win32')('terminal watchdog', () => {
+  test('writes reset sequences to the tty when the process dies uncleanly', async () => {
+    const ttyPath = join(tempDir, 'unclean.out')
+    const child = spawnFixture('hang', ttyPath)
+    await waitForReady(child)
+
+    child.kill('SIGKILL')
+    await waitForExit(child)
+
+    const written = await pollForContent(ttyPath, 5_000)
+    expect(written).toBe(TERMINAL_RESET_SEQUENCES)
+  }, 15_000)
+
+  test('stays silent when the process shuts down cleanly', async () => {
+    const ttyPath = join(tempDir, 'clean.out')
+    const child = spawnFixture('clean', ttyPath)
+    await waitForExit(child)
+
+    // Give a killed-too-late watchdog time to (incorrectly) fire.
+    await new Promise((r) => setTimeout(r, 500))
+    expect(readTty(ttyPath)).toBe('')
+  }, 15_000)
+})
diff --git a/cli/src/index.tsx b/cli/src/index.tsx
@@ -40,7 +40,9 @@ import { clearLogFile, logger } from './utils/logger'
 import { shouldShowProjectPicker } from './utils/project-picker'
 import { saveRecentProject } from './utils/recent-projects'
 import { startEngagementTracking } from './utils/engagement'
-import { installProcessCleanupHandlers, TERMINAL_RESET_SEQUENCES } from './utils/renderer-cleanup'
+import { installProcessCleanupHandlers } from './utils/renderer-cleanup'
+import { TERMINAL_RESET_SEQUENCES } from './utils/terminal-reset-sequences'
+import { startTerminalWatchdog, stopTerminalWatchdog } from './utils/terminal-watchdog'
 import { initializeSkillRegistry } from './utils/skill-registry'
 import { detectTerminalTheme } from './utils/terminal-color-detection'
 import { setOscDetectedTheme } from './utils/theme-system'
@@ -345,6 +347,7 @@ async function main(): Promise<void> {
   // If the renderer crashes during init, these ensure the error is visible
   // by exiting the alternate screen buffer before printing the error.
   const earlyFatalHandler = (error: unknown) => {
+    stopTerminalWatchdog() // we reset the terminal ourselves below
     try {
       if (process.stdin.isTTY && process.stdin.setRawMode) {
         process.stdin.setRawMode(false)
@@ -369,6 +372,13 @@ async function main(): Promise<void> {
   process.on('uncaughtException', earlyFatalHandler)
   process.on('unhandledRejection', earlyFatalHandler)
 
+  // Last line of defense for uncatchable deaths (SIGKILL, native crashes,
+  // kill sweeps that also take out the npm wrapper): a detached sh process
+  // that resets the terminal when this process disappears. Started before the
+  // renderer begins enabling terminal modes; the clean-shutdown path
+  // (renderer-cleanup) disarms it.
+  startTerminalWatchdog()
+
   const renderer = await createCliRenderer({
     backgroundColor: 'transparent',
     exitOnCtrlC: false,
diff --git a/cli/src/utils/renderer-cleanup.ts b/cli/src/utils/renderer-cleanup.ts
@@ -1,5 +1,7 @@
 import { resetTerminalTitle } from './terminal-title'
 import { flushLiveChatState } from './run-state-storage'
+import { TERMINAL_RESET_SEQUENCES } from './terminal-reset-sequences'
+import { stopTerminalWatchdog } from './terminal-watchdog'
 
 import type { CliRenderer } from '@opentui/core'
 
@@ -8,30 +10,6 @@ let renderer: CliRenderer | null = null
 let handlersInstalled = false
 let terminalStateReset = false
 
-/**
- * Terminal escape sequences to reset terminal state.
- * These are written directly to stdout to ensure they're sent even if the renderer is in a bad state.
- *
- * Sequences:
- * - \x1b[?1049l: Exit alternate screen buffer (restores main screen)
- * - \x1b[?1000l: Disable X10 mouse mode
- * - \x1b[?1002l: Disable button event mouse mode
- * - \x1b[?1003l: Disable any-event mouse mode (all motion tracking)
- * - \x1b[?1006l: Disable SGR extended mouse mode
- * - \x1b[?1004l: Disable focus reporting
- * - \x1b[?2004l: Disable bracketed paste mode
- * - \x1b[?25h: Show cursor (safety measure)
- */
-export const TERMINAL_RESET_SEQUENCES =
-  '\x1b[?1049l' + // Exit alternate screen buffer
-  '\x1b[?1000l' + // Disable X10 mouse mode
-  '\x1b[?1002l' + // Disable button event mouse mode
-  '\x1b[?1003l' + // Disable any-event mouse mode (all motion)
-  '\x1b[?1006l' + // Disable SGR extended mouse mode
-  '\x1b[?1004l' + // Disable focus reporting
-  '\x1b[?2004l' + // Disable bracketed paste mode
-  '\x1b[?25h' // Show cursor
-
 /**
  * Reset terminal state by writing escape sequences directly to stdout.
  * This is called BEFORE renderer.destroy() to ensure sequences are sent
@@ -69,6 +47,10 @@ function resetTerminalState(): void {
  * This resets terminal state to prevent garbled output after exit.
  */
 function cleanup(): void {
+  // We're on the clean-shutdown path, so the watchdog must not fire — kill it
+  // before anything else (synchronous, so no race with our own exit).
+  stopTerminalWatchdog()
+
   // Persist any in-flight chat state first (synchronous, best-effort) so
   // closing the terminal or killing the process mid-run doesn't lose the turn.
   flushLiveChatState()
diff --git a/cli/src/utils/terminal-reset-sequences.ts b/cli/src/utils/terminal-reset-sequences.ts
@@ -0,0 +1,34 @@
+/**
+ * Terminal escape sequences to reset terminal state.
+ * Shared by the in-process cleanup handlers (renderer-cleanup.ts) and the
+ * sacrificial watchdog process (terminal-watchdog.ts).
+ *
+ * Keep this list in sync with the modes OpenTUI enables (see the enable
+ * sequences in @opentui/core's native lib) and with
+ * SAFE_TERMINAL_RESET_SEQUENCES in the npm wrapper release scripts
+ * (cli/release/index.js, cli/release-staging/index.js,
+ * freebuff/cli/release/index.js).
+ *
+ * Sequences:
+ * - \x1b[?1049l: Exit alternate screen buffer (restores main screen)
+ * - \x1b[?1000l: Disable X10 mouse mode
+ * - \x1b[?1002l: Disable button event mouse mode
+ * - \x1b[?1003l: Disable any-event mouse mode (all motion tracking)
+ * - \x1b[?1006l: Disable SGR extended mouse mode
+ * - \x1b[?1004l: Disable focus reporting
+ * - \x1b[?2004l: Disable bracketed paste mode
+ * - \x1b[<u:     Pop the kitty keyboard protocol flags OpenTUI pushes
+ * - \x1b[>4;0m:  Reset xterm modifyOtherKeys (OpenTUI sets [>4;1m)
+ * - \x1b[?25h:   Show cursor (safety measure)
+ */
+export const TERMINAL_RESET_SEQUENCES =
+  '\x1b[?1049l' + // Exit alternate screen buffer
+  '\x1b[?1000l' + // Disable X10 mouse mode
+  '\x1b[?1002l' + // Disable button event mouse mode
+  '\x1b[?1003l' + // Disable any-event mouse mode (all motion)
+  '\x1b[?1006l' + // Disable SGR extended mouse mode
+  '\x1b[?1004l' + // Disable focus reporting
+  '\x1b[?2004l' + // Disable bracketed paste mode
+  '\x1b[<u' + // Pop kitty keyboard protocol flags
+  '\x1b[>4;0m' + // Reset modifyOtherKeys
+  '\x1b[?25h' // Show cursor
diff --git a/cli/src/utils/terminal-watchdog.ts b/cli/src/utils/terminal-watchdog.ts
diff --git a/freebuff/cli/release/index.js b/freebuff/cli/release/index.js
