typeclaw 0.37.2 → 0.37.4

package/src/init/run-bun-install.ts

@@ -1,5 +1,7 @@
 export type InstallResult = { ok: true } | { ok: false; reason: string }
 
+const INSTALL_TIMEOUT_MS = 300_000
+
 export type InstallRunnerOptions = {
   // Append `--force` to the bun install argv to bypass the cache for
   // `file:` / `link:` deps. Bun treats name+version of a `file:` dep as a
@@ -7,6 +9,8 @@ export type InstallRunnerOptions = {
   // locally-linked typeclaw never propagate into <agent>/node_modules until
   // either the typeclaw version is bumped or the install is forced.
   force?: boolean
+  timeoutMs?: number
+  spawn?: typeof Bun.spawn
 }
 
 // Signature for the function `runInit` uses to materialize the agent folder's
@@ -19,31 +23,29 @@ export async function runBunInstall(cwd: string, opts?: InstallRunnerOptions): P
   const bun = (globalThis as { Bun?: { spawn: typeof Bun.spawn } }).Bun
   if (!bun) return { ok: false, reason: 'bun runtime not available' }
   try {
-    const proc = bun.spawn({
-      // `--linker=hoisted` sidesteps a deadlock in Bun 1.3.x's isolated linker
-      // (the default since 1.3.0). When any single package fetch fails — 401,
-      // SHA-512 mismatch, transient registry 5xx, the kind of flake that's
-      // routine on GitHub Actions shared-IP runners — the isolated linker
-      // hangs the process indefinitely instead of erroring out
-      // (oven-sh/bun#26341, oven-sh/bun#29646). `bun install` runs here over
-      // ~500 transitive packages with no lockfile, so the odds of triggering
-      // the bug are non-trivial. Hoisted is the fallback strategy bun shipped
-      // before 1.3 — slightly slower for huge monorepos, indistinguishable
-      // for an agent folder, and not affected by the bug.
-      //
-      // `--force` is conditional: it bypasses the package cache so file:/link:
-      // deps re-copy their current on-disk source into node_modules. Bun's
-      // file-dep cache is keyed on name+version, so without --force, edits to
-      // a `file:..` typeclaw never reach the container after the first install.
+    // `--linker=hoisted` sidesteps a deadlock in Bun 1.3.x's isolated linker
+    // (the default since 1.3.0). When any single package fetch fails — 401,
+    // SHA-512 mismatch, transient registry 5xx, the kind of flake that's
+    // routine on GitHub Actions shared-IP runners — the isolated linker
+    // hangs the process indefinitely instead of erroring out
+    // (oven-sh/bun#26341, oven-sh/bun#29646). `bun install` runs here over
+    // ~500 transitive packages with no lockfile, so the odds of triggering
+    // the bug are non-trivial. Hoisted is the fallback strategy bun shipped
+    // before 1.3 — slightly slower for huge monorepos, indistinguishable
+    // for an agent folder, and not affected by the bug.
+    //
+    // `--force` is conditional: it bypasses the package cache so file:/link:
+    // deps re-copy their current on-disk source into node_modules. Bun's
+    // file-dep cache is keyed on name+version, so without --force, edits to
+    // a `file:..` typeclaw never reach the container after the first install.
+    return await runTimedBunProcess({
       cmd: opts?.force ? ['bun', 'install', '--linker=hoisted', '--force'] : ['bun', 'install', '--linker=hoisted'],
       cwd,
-      stdout: 'pipe',
-      stderr: 'pipe',
+      timeoutMs: opts?.timeoutMs ?? INSTALL_TIMEOUT_MS,
+      spawn: opts?.spawn ?? bun.spawn,
+      timeoutReason: (seconds) => `bun install timed out after ${seconds}s`,
+      failureReason: (code, stderr) => `bun install exited with code ${code}: ${stderr.trim() || 'no stderr'}`,
     })
-    const code = await proc.exited
-    if (code === 0) return { ok: true }
-    const stderr = await new Response(proc.stderr).text()
-    return { ok: false, reason: `bun install exited with code ${code}: ${stderr.trim() || 'no stderr'}` }
   } catch (error) {
     return { ok: false, reason: error instanceof Error ? error.message : String(error) }
   }
@@ -55,30 +57,62 @@ export async function runBunInstall(cwd: string, opts?: InstallRunnerOptions): P
 // install` would no-op when the existing lockfile entry already satisfies
 // an in-range spec — which is the exact regression auto-upgrade exists to
 // prevent).
-export type UpdateRunner = (cwd: string, pkg: string) => Promise<InstallResult>
+export type UpdateRunnerOptions = Pick<InstallRunnerOptions, 'timeoutMs' | 'spawn'>
 
-export async function runBunUpdate(cwd: string, pkg: string): Promise<InstallResult> {
+export type UpdateRunner = (cwd: string, pkg: string, opts?: UpdateRunnerOptions) => Promise<InstallResult>
+
+export async function runBunUpdate(cwd: string, pkg: string, opts?: UpdateRunnerOptions): Promise<InstallResult> {
   const bun = (globalThis as { Bun?: { spawn: typeof Bun.spawn } }).Bun
   if (!bun) return { ok: false, reason: 'bun runtime not available' }
   try {
-    const proc = bun.spawn({
-      // `bun update <pkg> --latest` re-resolves <pkg> against the registry,
-      // capped by the spec in package.json. For a caret/tilde range this
-      // pulls the highest in-range version (the case `bun install` won't
-      // upgrade because the lockfile already satisfies the spec). For an
-      // exact pin it's effectively a force re-fetch of that exact version.
-      // `--linker=hoisted` for the same Bun 1.3.x deadlock reason as
-      // runBunInstall above.
+    // `bun update <pkg> --latest` re-resolves <pkg> against the registry,
+    // capped by the spec in package.json. For a caret/tilde range this
+    // pulls the highest in-range version (the case `bun install` won't
+    // upgrade because the lockfile already satisfies the spec). For an
+    // exact pin it's effectively a force re-fetch of that exact version.
+    // `--linker=hoisted` for the same Bun 1.3.x deadlock reason as
+    // runBunInstall above.
+    return await runTimedBunProcess({
       cmd: ['bun', 'update', pkg, '--latest', '--linker=hoisted'],
       cwd,
-      stdout: 'pipe',
-      stderr: 'pipe',
+      timeoutMs: opts?.timeoutMs ?? INSTALL_TIMEOUT_MS,
+      spawn: opts?.spawn ?? bun.spawn,
+      timeoutReason: (seconds) => `bun update ${pkg} timed out after ${seconds}s`,
+      failureReason: (code, stderr) => `bun update ${pkg} exited with code ${code}: ${stderr.trim() || 'no stderr'}`,
     })
+  } catch (error) {
+    return { ok: false, reason: error instanceof Error ? error.message : String(error) }
+  }
+}
+
+async function runTimedBunProcess({
+  cmd,
+  cwd,
+  timeoutMs,
+  spawn,
+  timeoutReason,
+  failureReason,
+}: {
+  cmd: string[]
+  cwd: string
+  timeoutMs: number
+  spawn: typeof Bun.spawn
+  timeoutReason: (seconds: number) => string
+  failureReason: (code: number, stderr: string) => string
+}): Promise<InstallResult> {
+  const proc = spawn({ cmd, cwd, stdout: 'pipe', stderr: 'pipe' })
+  let timedOut = false
+  const timeout = setTimeout(() => {
+    timedOut = true
+    proc.kill('SIGKILL')
+  }, timeoutMs)
+  try {
     const code = await proc.exited
+    if (timedOut) return { ok: false, reason: timeoutReason(timeoutMs / 1000) }
     if (code === 0) return { ok: true }
     const stderr = await new Response(proc.stderr).text()
-    return { ok: false, reason: `bun update ${pkg} exited with code ${code}: ${stderr.trim() || 'no stderr'}` }
-  } catch (error) {
-    return { ok: false, reason: error instanceof Error ? error.message : String(error) }
+    return { ok: false, reason: failureReason(code, stderr) }
+  } finally {
+    clearTimeout(timeout)
   }
 }

package/src/inspect/transcript-view.ts

@@ -10,6 +10,7 @@ import {
 } from '@mariozechner/pi-tui'
 
 import { formatToolEnd, formatToolStart, formatUserPromptHistory } from '@/tui/format'
+import { armTerminalGuard } from '@/tui/terminal-guard'
 import { colors, markdownTheme } from '@/tui/theme'
 
 import { streamSessionEvents, type LiveSourceFactory, type StreamPhase } from './index'
@@ -46,6 +47,9 @@ export function createTranscriptView(opts: TranscriptViewOptions) {
     tui.addChild(new Text(header(opts.summary), 0, 0))
     tui.addChild(status)
     tui.start()
+    // Restores the terminal on an abnormal exit (SSH SIGHUP, kill, crash) that
+    // never reaches tui.stop(), so the shell isn't left in Kitty kbd mode.
+    const guard = armTerminalGuard()
     tui.requestRender()
 
     // The status line is pinned last (no editor to pin, unlike createTui). Each
@@ -71,12 +75,21 @@ export function createTranscriptView(opts: TranscriptViewOptions) {
     const outcome = new Promise<TranscriptViewOutcome>((resolve) => {
       settle = resolve
     })
+    // drainInput() before stop() swallows late Kitty key-release bytes so they
+    // don't leak to the shell over a slow SSH link; disarm() drops the abnormal-
+    // exit guard now that a clean teardown ran.
     const finish = (reason: TranscriptViewOutcome['reason']): void => {
       if (settle === null) return
       const fn = settle
       settle = null
-      tui.stop()
-      fn({ reason })
+      void terminal
+        .drainInput()
+        .catch(() => {})
+        .then(() => {
+          tui.stop()
+          guard.disarm()
+          fn({ reason })
+        })
     }
 
     tui.addInputListener((data) => {

package/src/portbroker/hostd-client.ts

@@ -30,7 +30,8 @@ export type BrokerOptions = {
   // and reports the reason so hostd can GC the stale registration.
   onFatalAuthFailure?: (reason: string) => void
   onLog?: (msg: string) => void
-  connectWs?: (url: string) => Promise<WsClient>
+  connectWs?: (url: string, timeoutMs: number) => Promise<WsClient>
+  connectTimeoutMs?: number
   listenHost?: ListenHostFn
   reconnectDelaysMs?: number[]
   hostBindAddr?: string
@@ -71,6 +72,7 @@ export type Broker = {
 
 const DEFAULT_RECONNECT_DELAYS = [1_000, 2_000, 4_000, 10_000]
 const DEFAULT_HOST_BIND = '127.0.0.1'
+const DEFAULT_CONNECT_TIMEOUT_MS = 15_000
 
 // broker-hello-nack reasons emitted by container-server.ts when authentication
 // fails. These are immutable for a broker instance's lifetime, so reconnecting
@@ -82,6 +84,7 @@ export function createBroker(opts: BrokerOptions): Broker {
   const reconnectDelays = opts.reconnectDelaysMs ?? DEFAULT_RECONNECT_DELAYS
   const hostBind = opts.hostBindAddr ?? DEFAULT_HOST_BIND
   const connectWs = opts.connectWs ?? defaultConnectWs
+  const connectTimeoutMs = opts.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS
   const listenHost = opts.listenHost ?? defaultListenHost
 
   type ForwarderState = {
@@ -437,7 +440,7 @@ export function createBroker(opts: BrokerOptions): Broker {
     const url = `ws://127.0.0.1:${hostPort}/portbroker`
     let client: WsClient
     try {
-      client = await connectWs(url)
+      client = await connectWs(url, connectTimeoutMs)
     } catch (err) {
       log(`ws connect ${url}: ${err instanceof Error ? err.message : String(err)}`)
       scheduleReconnect()
@@ -504,12 +507,31 @@ export function createBroker(opts: BrokerOptions): Broker {
   }
 }
 
-async function defaultConnectWs(url: string): Promise<WsClient> {
+async function defaultConnectWs(url: string, timeoutMs = DEFAULT_CONNECT_TIMEOUT_MS): Promise<WsClient> {
   return new Promise((resolve, reject) => {
     const ws = new WebSocket(url)
-    let resolved = false
+    let settled = false
     const messageCbs: Array<(msg: ContainerToHostd) => void> = []
     const closeCbs: Array<() => void> = []
+    let connectTimeout: ReturnType<typeof setTimeout> | null = null
+    const clearConnectTimeout = (): void => {
+      if (connectTimeout !== null) {
+        clearTimeout(connectTimeout)
+        connectTimeout = null
+      }
+    }
+    const failConnect = (err: Error): void => {
+      if (settled) return
+      settled = true
+      clearConnectTimeout()
+      reject(err)
+    }
+    connectTimeout = setTimeout(() => {
+      failConnect(new Error(`ws connect timeout after ${timeoutMs}ms to ${url}`))
+      try {
+        ws.close()
+      } catch {}
+    }, timeoutMs)
     const client: WsClient = {
       send: (msg) => {
         try {
@@ -529,7 +551,9 @@ async function defaultConnectWs(url: string): Promise<WsClient> {
       },
     }
     ws.onopen = (): void => {
-      resolved = true
+      if (settled) return
+      settled = true
+      clearConnectTimeout()
       resolve(client)
     }
     ws.onmessage = (ev: MessageEvent): void => {
@@ -542,9 +566,11 @@ async function defaultConnectWs(url: string): Promise<WsClient> {
       for (const cb of messageCbs) cb(msg)
     }
     ws.onerror = (): void => {
-      if (!resolved) reject(new Error(`ws error connecting to ${url}`))
+      failConnect(new Error(`ws error connecting to ${url}`))
     }
     ws.onclose = (): void => {
+      if (!settled) failConnect(new Error(`ws closed connecting to ${url}`))
+      else clearConnectTimeout()
       for (const cb of closeCbs) cb()
     }
   })

package/src/shared/index.ts

@@ -27,3 +27,7 @@ export {
 } from './protocol'
 
 export { formatLocalDate, formatLocalDateTime, formatLocalWeekday, resolveLocalTimezoneName } from './local-time'
+
+export { detectWsl, isWindowsDriveMount, type WslInfo, type WslVersion } from './wsl'
+
+export { isMacOS, isWindows } from './platform'

package/src/shared/platform.ts

@@ -0,0 +1,11 @@
+// Centralized seam so host-stage macOS/Linux/Windows branches stay greppable as
+// native-Windows support lands; the default arg lets tests pass a platform
+// without mutating the read-only `process.platform`.
+
+export function isWindows(platform: NodeJS.Platform = process.platform): boolean {
+  return platform === 'win32'
+}
+
+export function isMacOS(platform: NodeJS.Platform = process.platform): boolean {
+  return platform === 'darwin'
+}

package/src/shared/wsl.ts

@@ -0,0 +1,139 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { release } from 'node:os'
+
+// Detection of WSL (Windows Subsystem for Linux) and Windows-drive mounts.
+//
+// Why this matters for typeclaw: inside WSL the kernel is real Linux, so the
+// host stage runs unchanged — EXCEPT when files live on a Windows-drive mount
+// (DrvFs on WSL1, 9p on WSL2, e.g. `/mnt/c/...`). On those mounts POSIX
+// permissions are NOT enforced: `chmod 0o600` silently succeeds but leaves the
+// file world-readable. typeclaw stores encryption keys and API tokens with
+// mode 0600 (src/secrets/*, src/hostd/paths.ts), so a secrets file on `/mnt/c`
+// loses its confidentiality guarantee. The doctor surfaces this as a warning.
+
+export type WslVersion = 1 | 2
+
+export type WslInfo = {
+  isWsl: boolean
+  // null when not WSL, or WSL but the version can't be determined (e.g. a
+  // custom kernel detected only via the binfmt/`/run/WSL` artifacts).
+  version: WslVersion | null
+}
+
+// Injectable so the pure detection logic is unit-testable without a real
+// `/proc` or `/etc/wsl.conf`; production uses the real-filesystem defaults.
+export type WslProbes = {
+  platform: NodeJS.Platform
+  kernelRelease: () => string
+  readFile: (path: string) => string | null
+  fileExists: (path: string) => boolean
+  env: NodeJS.ProcessEnv
+}
+
+function safeReadFile(path: string): string | null {
+  try {
+    return readFileSync(path, 'utf8')
+  } catch {
+    return null
+  }
+}
+
+const defaultProbes: WslProbes = {
+  platform: process.platform,
+  kernelRelease: release,
+  readFile: safeReadFile,
+  fileExists: existsSync,
+  env: process.env,
+}
+
+// Mirrors the is-wsl@3 cascade: os.release() → /proc/version → WSL runtime
+// artifacts. Matching is case-insensitive because WSL1 stamps `Microsoft`
+// (capital M) and WSL2 stamps `microsoft` (lowercase) into the kernel strings.
+// A user-compiled WSL2 kernel can omit the string entirely, which is why the
+// binfmt/`/run/WSL` artifacts are the final fallback.
+export function detectWslWith(probes: WslProbes): WslInfo {
+  if (probes.platform !== 'linux') return { isWsl: false, version: null }
+
+  const kernelRelease = probes.kernelRelease().toLowerCase()
+  const procVersion = (probes.readFile('/proc/version') ?? '').toLowerCase()
+
+  const kernelSaysMicrosoft = kernelRelease.includes('microsoft')
+  const procSaysMicrosoft = procVersion.includes('microsoft')
+  const hasArtifacts = probes.fileExists('/proc/sys/fs/binfmt_misc/WSLInterop') || probes.fileExists('/run/WSL')
+
+  if (!kernelSaysMicrosoft && !procSaysMicrosoft && !hasArtifacts) {
+    return { isWsl: false, version: null }
+  }
+
+  return { isWsl: true, version: resolveWslVersion({ kernelRelease, procVersion, env: probes.env }) }
+}
+
+// WSL_INTEROP is present only under WSL2 (Microsoft's own recommendation in
+// microsoft/WSL#4555). It can be stripped by `sudo`, so the kernel-string
+// heuristics back it up: WSL2 kernels are `*-microsoft-standard*` / contain
+// `wsl2`; WSL1 kernels are the older `*-Microsoft` form without "standard".
+function resolveWslVersion(args: {
+  kernelRelease: string
+  procVersion: string
+  env: NodeJS.ProcessEnv
+}): WslVersion | null {
+  if (args.env.WSL_INTEROP !== undefined && args.env.WSL_INTEROP !== '') return 2
+
+  const haystack = `${args.kernelRelease} ${args.procVersion}`
+  if (haystack.includes('wsl2') || haystack.includes('microsoft-standard')) return 2
+
+  // Older WSL1 kernels say `microsoft` but never `standard`/`wsl2`. If we only
+  // know it's WSL from the kernel/proc string (not the artifacts), call it v1.
+  if (args.kernelRelease.includes('microsoft') || args.procVersion.includes('microsoft')) return 1
+
+  return null
+}
+
+export function detectWsl(): WslInfo {
+  return detectWslWith(defaultProbes)
+}
+
+// The WSL automount root defaults to `/mnt/` but can be remapped via
+// `/etc/wsl.conf` ([automount] root = ...). Returns the configured root with a
+// guaranteed trailing slash, or `/mnt/` when unset/unreadable.
+export function readAutomountRootWith(probes: Pick<WslProbes, 'readFile'>): string {
+  const conf = probes.readFile('/etc/wsl.conf')
+  const parsed = conf === null ? null : parseAutomountRoot(conf)
+  const root = parsed ?? '/mnt/'
+  return root.endsWith('/') ? root : `${root}/`
+}
+
+function parseAutomountRoot(content: string): string | null {
+  let inAutomountSection = false
+  for (const rawLine of content.split('\n')) {
+    const line = rawLine.trim()
+    if (line.length === 0 || line.startsWith('#') || line.startsWith(';')) continue
+    const section = /^\[(?<name>[^\]]+)\]$/.exec(line)
+    if (section) {
+      inAutomountSection = section.groups?.name?.trim().toLowerCase() === 'automount'
+      continue
+    }
+    if (!inAutomountSection) continue
+    const match = /^root\s*=\s*(?<value>"[^"]*"|'[^']*'|[^#;]*)/.exec(line)
+    const raw = match?.groups?.value
+    if (raw === undefined) continue
+    const value = raw.trim().replace(/^["']|["']$/g, '')
+    if (value.length > 0) return value
+  }
+  return null
+}
+
+// True when `path` lives under the WSL Windows-drive automount (e.g.
+// `/mnt/c/...`), where Unix permissions are not enforced. The drive component
+// must be a single ASCII letter so `/mnt/wsl/...` (WSLg, not a Windows drive)
+// is correctly excluded.
+export function isWindowsDriveMountWith(path: string, probes: Pick<WslProbes, 'readFile'>): boolean {
+  const root = readAutomountRootWith(probes)
+  if (!path.startsWith(root)) return false
+  const rest = path.slice(root.length)
+  return /^[A-Za-z](?:\/|$)/.test(rest)
+}
+
+export function isWindowsDriveMount(path: string): boolean {
+  return isWindowsDriveMountWith(path, defaultProbes)
+}

package/src/tui/index.ts

@@ -23,6 +23,7 @@ import {
   formatUserPromptHistory,
   withTimestamp,
 } from './format'
+import { armTerminalGuard } from './terminal-guard'
 import { colors, editorTheme, markdownTheme } from './theme'
 
 export type ClientFactory = (url: string) => Promise<Client>
@@ -103,6 +104,10 @@ export function createTui({
     const status = new Text(colors.dim(`connecting to ${displayUrl}...`), 0, 0)
     tui.addChild(status)
     tui.start()
+    // Armed once the terminal is in raw mode + Kitty kbd protocol: restores the
+    // terminal on an abnormal exit (SSH SIGHUP, kill, crash) that never reaches
+    // tui.stop(), so the shell isn't left echoing Kitty key-release events.
+    const guard = armTerminalGuard()
     tui.requestRender()
 
     // Pre-handshake failures resolve 'connectFailed' (not throw): the standalone
@@ -113,6 +118,7 @@ export function createTui({
       status.setText(colors.red(`connection error: ${err instanceof Error ? err.message : String(err)}`))
       tui.requestRender()
       tui.stop()
+      guard.disarm()
       exit(1)
       return null
     })
@@ -124,6 +130,7 @@ export function createTui({
       tui.requestRender()
       client.close()
       tui.stop()
+      guard.disarm()
       exit(1)
       return null
     })
@@ -418,21 +425,32 @@ export function createTui({
     // Settle BEFORE closing the client: client.close() fires onClose, which
     // settles 'lostConnection'. settle() is idempotent, so the first call wins —
     // settling the deliberate outcome first keeps the later onClose a no-op.
-    const teardown = (): void => {
-      stopAllLoaders()
-      tui.stop()
-      client.close()
+    // drainInput() runs before stop() so late Kitty key-release bytes (the keys
+    // that triggered the exit) are swallowed instead of leaking to the shell
+    // over a slow SSH link. The promise is memoized so repeated callers (a
+    // fire-and-forget detach/exit plus the end-of-run await) share ONE teardown
+    // and the end-of-run await truly blocks until draining finishes — otherwise
+    // the next clack picker could start reading stdin mid-drain.
+    let teardownPromise: Promise<void> | null = null
+    const teardown = (): Promise<void> => {
+      teardownPromise ??= (async () => {
+        stopAllLoaders()
+        await terminal.drainInput().catch(() => {})
+        tui.stop()
+        client.close()
+        guard.disarm()
+      })()
+      return teardownPromise
     }
 
     const exitWith = (code: number): void => {
       settle({ reason: 'exit', exitCode: code })
-      teardown()
-      exit(code)
+      void teardown().finally(() => exit(code))
     }
 
     const detach = (): void => {
       settle({ reason: 'detach' })
-      teardown()
+      void teardown()
     }
 
     // Ctrl+C exits the client. In raw mode the kernel does NOT generate SIGINT,
@@ -490,7 +508,7 @@ export function createTui({
     }
 
     const result = await outcome
-    tui.stop()
+    await teardown()
     return result
   }
 

package/src/tui/terminal-guard.ts

@@ -0,0 +1,139 @@
+import { writeSync } from 'node:fs'
+
+// Mirrors pi-tui ProcessTerminal.stop()'s resets so an abnormal exit (SSH
+// SIGHUP, a frozen TUI the user kills, a crash, or a Bun process.exit() that
+// drops pi-tui's buffered stop() writes) can't leave the parent shell with the
+// Kitty keyboard protocol still on. While on, the terminal emits CSI-u
+// key-RELEASE events (`;1:3u`) for every keystroke, corrupting the shell. Order
+// matches stop(): pop Kitty kbd protocol, disable xterm modifyOtherKeys, disable
+// bracketed paste, end synchronized output, show cursor.
+export const RESTORE_SEQUENCE = '\x1b[<u\x1b[>4;0m\x1b[?2004l\x1b[?2026l\x1b[?25h'
+
+const STDOUT_FD = 1
+
+const SCOPED_SIGNALS = ['SIGINT', 'SIGTERM', 'SIGHUP'] as const
+export type ScopedSignal = (typeof SCOPED_SIGNALS)[number]
+
+const SIGNAL_EXIT_CODE: Record<ScopedSignal, number> = {
+  SIGINT: 130,
+  SIGTERM: 143,
+  SIGHUP: 129,
+}
+
+export type TerminalGuardDeps = {
+  isTty: boolean
+  writeStdout: (seq: string) => void
+  setRawMode: (mode: boolean) => void
+  on: (event: string, handler: (...args: unknown[]) => void) => void
+  off: (event: string, handler: (...args: unknown[]) => void) => void
+  killSelf: (signal: ScopedSignal) => void
+  exit: (code: number) => void
+}
+
+export type TerminalGuard = {
+  arm: () => void
+  disarm: () => void
+}
+
+export function createTerminalGuard(deps: TerminalGuardDeps): TerminalGuard {
+  let armed = 0
+  let exitInstalled = false
+  let signalHandlers: Map<ScopedSignal, (...args: unknown[]) => void> | null = null
+
+  const restore = (): void => {
+    if (!deps.isTty) return
+    deps.writeStdout(RESTORE_SEQUENCE)
+    deps.setRawMode(false)
+  }
+
+  const onExit = (): void => {
+    restore()
+  }
+
+  const installSignalHandlers = (): void => {
+    if (signalHandlers !== null) return
+    const handlers = new Map<ScopedSignal, (...args: unknown[]) => void>()
+    for (const sig of SCOPED_SIGNALS) {
+      const handler = (): void => {
+        // Restore the terminal, then let the signal terminate with default
+        // semantics. Remove our handlers first so the re-raised signal isn't
+        // swallowed by this same handler; fall back to an explicit exit if the
+        // re-raise somehow doesn't terminate.
+        removeSignalHandlers()
+        restore()
+        deps.killSelf(sig)
+        deps.exit(SIGNAL_EXIT_CODE[sig])
+      }
+      deps.on(sig, handler)
+      handlers.set(sig, handler)
+    }
+    signalHandlers = handlers
+  }
+
+  const removeSignalHandlers = (): void => {
+    if (signalHandlers === null) return
+    for (const [sig, handler] of signalHandlers) deps.off(sig, handler)
+    signalHandlers = null
+  }
+
+  return {
+    arm: () => {
+      // A non-TTY process (piped/redirected, or the test runner) has no terminal
+      // state to protect, so the guard stays fully inert — it never touches the
+      // real process signal/exit handlers.
+      if (!deps.isTty) return
+      armed += 1
+      if (!exitInstalled) {
+        deps.on('exit', onExit)
+        exitInstalled = true
+      }
+      installSignalHandlers()
+    },
+    disarm: () => {
+      if (!deps.isTty) return
+      if (armed > 0) armed -= 1
+      if (armed === 0) removeSignalHandlers()
+    },
+  }
+}
+
+let defaultGuard: TerminalGuard | null = null
+
+function getDefaultGuard(): TerminalGuard {
+  defaultGuard ??= createTerminalGuard({
+    isTty: Boolean(process.stdout.isTTY),
+    writeStdout: (seq) => {
+      try {
+        writeSync(STDOUT_FD, seq)
+      } catch {
+        /* fd closed mid-teardown */
+      }
+    },
+    setRawMode: (mode) => {
+      try {
+        process.stdin.setRawMode?.(mode)
+      } catch {
+        /* terminal already torn down */
+      }
+    },
+    on: (event, handler) => {
+      process.on(event as NodeJS.Signals, handler)
+    },
+    off: (event, handler) => {
+      process.off(event as NodeJS.Signals, handler)
+    },
+    killSelf: (signal) => {
+      process.kill(process.pid, signal)
+    },
+    exit: (code) => {
+      process.exit(code)
+    },
+  })
+  return defaultGuard
+}
+
+export function armTerminalGuard(): TerminalGuard {
+  const guard = getDefaultGuard()
+  guard.arm()
+  return guard
+}