typeclaw 0.37.3 → 0.37.4

package/src/cli/init.ts

@@ -39,6 +39,7 @@ import {
   hasExistingOAuthCredentials,
   isDirectoryNonEmpty,
   isHatched,
+  isInitialized,
   readExistingProviderApiKey,
   runInit,
   type GithubInitCredentials,
@@ -139,18 +140,22 @@ export const init = defineCommand({
     if (existingAgent !== null && existingAgent !== cwd) {
       console.error(
         errorLine(
-          `Refusing to init: a TypeClaw agent already exists at ${existingAgent}. Nested agents are not supported.`,
+          `Refusing to init: a TypeClaw agent already exists at ${existingAgent}. Nested agents are not supported. Run init from a directory that is not inside an existing agent.`,
         ),
       )
       process.exit(1)
     }
 
     if (await isHatched(cwd)) {
-      console.error(errorLine(`TypeClaw has already hatched in ${cwd}.`))
+      console.error(
+        errorLine(
+          `TypeClaw has already hatched in ${cwd}. Use \`typeclaw tui\` to attach or \`typeclaw start\` to run it; init in a different directory to create another agent.`,
+        ),
+      )
       process.exit(1)
     }
 
-    if (isDirectoryNonEmpty(cwd)) {
+    if (shouldConfirmNonEmptyDirectory(cwd)) {
       const proceed = await confirm({
         message: `You're at ${cwd}. The directory is not empty. Do you want to proceed?`,
         initialValue: false,
@@ -192,7 +197,7 @@ export const init = defineCommand({
             [
               'OAuth credentials were saved to `secrets.json` before you aborted.',
               'Re-run `typeclaw init` here to pick up where you left off (the credentials',
-              'will be reused), or delete `secrets.json` if you want a clean restart.',
+              'will be reused), or run `typeclaw init --reset` to start fresh.',
             ].join('\n'),
             'Saved OAuth credentials',
           )
@@ -288,6 +293,14 @@ export const init = defineCommand({
       })
     } catch (error) {
       console.error(errorLine(error instanceof Error ? error.message : String(error)))
+      note(
+        [
+          'Your answers are saved.',
+          'Re-run `typeclaw init` here to resume, or `typeclaw init --reset` to start fresh.',
+          'Run `typeclaw doctor` to diagnose host/Docker issues.',
+        ].join('\n'),
+        'init failed',
+      )
       process.exit(1)
     }
 
@@ -296,6 +309,19 @@ export const init = defineCommand({
       process.exit(1)
     }
 
+    if (!hatchingOk) {
+      note(
+        [
+          'The container was built but the agent did not come up.',
+          'Check logs: `typeclaw logs`',
+          'Diagnose: `typeclaw doctor`',
+          'Retry once fixed: `typeclaw start` (your setup is saved).',
+        ].join('\n'),
+        'Hatching failed',
+      )
+      process.exit(1)
+    }
+
     if (githubCredentials?.tunnelProvider === 'none') {
       log.warn(
         'Webhook delivery is disabled until you add a `tunnels[]` entry or set `channels.github.webhookUrl` manually.',
@@ -335,6 +361,10 @@ export const init = defineCommand({
   },
 })
 
+export function shouldConfirmNonEmptyDirectory(cwd: string): boolean {
+  return isDirectoryNonEmpty(cwd) && !isInitialized(cwd)
+}
+
 interface WizardState {
   catalog?: { options: ModelOption[]; source: 'models.dev' | 'curated'; warning?: string }
   vendorId?: KnownProviderVendorId
@@ -1750,20 +1780,24 @@ function reportProgress(
         s.stop(event.result.ok ? 'Logged in.' : `OAuth login failed: ${event.result.reason}`)
         break
       case 'install':
-        s.stop(event.result.ok ? 'Dependencies installed.' : `Skipped bun install: ${event.result.reason}`)
+        if (event.result.ok) {
+          s.stop('Dependencies installed.')
+        } else {
+          s.error(`Dependency install failed: ${event.result.reason}`)
+        }
         break
       case 'dockerfile':
         if (event.result.ok) {
           s.stop(event.result.devMode ? 'Dockerfile written (dev mode).' : 'Dockerfile written.')
         } else {
-          s.stop(`Skipped Dockerfile: ${event.result.reason}`)
+          s.error(`Dockerfile generation failed: ${event.result.reason}`)
         }
         break
       case 'git':
         if (event.result.ok) {
           s.stop(event.result.skipped ? 'Git repository already exists.' : 'Git repository initialized.')
         } else {
-          s.stop(`Skipped git init: ${event.result.reason}`)
+          s.error(`git init failed — continuing without a repo: ${event.result.reason}`)
         }
         break
     }

package/src/cli/qr.ts

@@ -6,6 +6,8 @@ import { promisify } from 'node:util'
 
 import QRCode from 'qrcode'
 
+import { isMacOS, isWindows } from '@/shared'
+
 const execFileAsync = promisify(execFile)
 
 // The upstream LINE SDK's QR login hands back a raw auth URL
@@ -108,12 +110,11 @@ async function writeQRHtmlFile(
 }
 
 async function openInBrowser(filePath: string): Promise<void> {
-  const platform = process.platform
-  if (platform === 'darwin') {
+  if (isMacOS()) {
     await execFileAsync('open', [filePath])
     return
   }
-  if (platform === 'win32') {
+  if (isWindows()) {
     await execFileAsync('cmd', ['/c', 'start', '', filePath])
     return
   }

package/src/cli/ui.ts

@@ -14,14 +14,18 @@ type ClackInput = Pick<NodeJS.ReadStream, 'isTTY' | 'setRawMode' | 'resume'>
 // Bun's readline keypress wiring only transitions stdin into flowing raw mode
 // reliably once the stream has already been resumed; on a never-resumed stdin
 // the picker renders but arrow keys echo as raw `^[[B` and never advance it.
-// Local terminals dodge this because stdin was already flowing. So before every
-// picker: clear any stale raw mode for a clean baseline, then resume the stream.
-// Never pause() here — a previously-paused process.stdin does not reliably
-// re-flow under Bun, which is the same failure this resume() is fixing.
+// Local terminals dodge this because stdin was already flowing. Worse, after a
+// pi-tui viewer (ProcessTerminal.stop() calls process.stdin.pause()), a plain
+// resume() does NOT re-flow stdin under Bun, so the next picker is dead over
+// SSH. Toggling raw mode on->off forces the TTY read back into flowing mode;
+// the trailing resume() + non-raw state is the baseline clack expects.
+// Never pause() here — a paused process.stdin does not reliably re-flow.
 export function prepareStdinForClack(input: ClackInput = process.stdin): void {
   if (!input.isTTY) return
+  input.resume()
   if (typeof input.setRawMode === 'function') {
     try {
+      input.setRawMode(true)
       input.setRawMode(false)
     } catch {
       /* terminal already torn down */

package/src/doctor/checks.ts

@@ -15,11 +15,12 @@ import {
   resolveHostPort,
   type DockerExec,
 } from '@/container'
-import { isDaemonReachable, send } from '@/hostd'
+import { homeRoot, isDaemonReachable, send } from '@/hostd'
 import { resolveBaseImageVersion } from '@/init/cli-version'
 import { buildDockerfile, DOCKERFILE } from '@/init/dockerfile'
 import { detectMissingDeps } from '@/init/ensure-deps'
 import { buildGitignore, GITIGNORE_FILE } from '@/init/gitignore'
+import { detectWsl, isWindows, isWindowsDriveMount, type WslInfo } from '@/shared'
 
 import { buildChannelChecks } from './channel-checks'
 import type { DoctorCheck } from './types'
@@ -37,8 +38,11 @@ export function buildStaticChecks(opts: { dockerExec?: DockerExec } = {}): Docto
     agentFolderGitRepo(),
     configValid(),
     hostdHomeWritable(),
+    wslDriveMount(),
+    windowsSecretPerms(),
     hostdReachable(),
     hostdRegistration(),
+    windowsBindMount(),
     containerState(dockerExec),
     containerHostPort(),
     ...buildChannelChecks(),
@@ -237,6 +241,142 @@ function hostdHomeWritable(): DoctorCheck {
   }
 }
 
+export type WslDriveMountDeps = {
+  detect: () => WslInfo
+  isWindowsDriveMount: (path: string) => boolean
+  typeclawHome: () => string
+}
+
+// Under WSL, files on a Windows-drive mount (/mnt/c/...) don't enforce Unix
+// permissions, so the 0600 chmod that protects secrets.json and the encryption
+// keys is silently ignored — they become readable by every local user. Warn
+// when either the agent folder or ~/.typeclaw lives on such a mount.
+export function wslDriveMount(deps: Partial<WslDriveMountDeps> = {}): DoctorCheck {
+  const detect = deps.detect ?? detectWsl
+  const onWindowsDrive = deps.isWindowsDriveMount ?? isWindowsDriveMount
+  const typeclawHome = deps.typeclawHome ?? homeRoot
+
+  return {
+    name: 'hostd.wsl-drive-mount',
+    category: 'hostd',
+    description: 'agent state is not on a Windows-drive mount under WSL',
+    async run(ctx) {
+      if (!detect().isWsl) return { status: 'ok', message: 'not running under WSL' }
+
+      const offenders: string[] = []
+      if (ctx.hasAgentFolder && onWindowsDrive(ctx.cwd)) offenders.push(`agent folder: ${ctx.cwd}`)
+      const home = typeclawHome()
+      if (onWindowsDrive(home)) offenders.push(`hostd home: ${home}`)
+
+      if (offenders.length === 0) {
+        return { status: 'ok', message: 'agent state is on the Linux filesystem' }
+      }
+
+      return {
+        status: 'warning',
+        message: 'agent state is on a Windows-drive mount; file permissions are not enforced',
+        details: [
+          ...offenders,
+          'chmod is a no-op on /mnt/<drive> (DrvFs/9p), so secrets.json and encryption keys become world-readable.',
+        ],
+        fix: {
+          description:
+            'Move the agent folder to the WSL Linux filesystem (e.g. ~/my-agent) and, if needed, set TYPECLAW_HOME to a Linux path.',
+        },
+      }
+    },
+  }
+}
+
+export type WindowsSecretPermsDeps = {
+  isWindows: () => boolean
+  typeclawHome: () => string
+}
+
+// On native Windows the 0600/0700 modes typeclaw sets on secrets.json and the
+// encryption keys are no-ops — NTFS uses ACLs, not Unix modes — so their
+// confidentiality rests on the inherited %USERPROFILE% ACLs rather than the
+// hardening typeclaw enforces on POSIX. Surface that as a warning.
+export function windowsSecretPerms(deps: Partial<WindowsSecretPermsDeps> = {}): DoctorCheck {
+  const onWindows = deps.isWindows ?? isWindows
+  const typeclawHome = deps.typeclawHome ?? homeRoot
+
+  return {
+    name: 'hostd.windows-secret-perms',
+    category: 'hostd',
+    description: 'secrets rely on enforced file permissions (native Windows)',
+    async run(ctx) {
+      if (!onWindows()) return { status: 'ok', message: 'not running on native Windows' }
+
+      const details = [`hostd home: ${typeclawHome()}`]
+      if (ctx.hasAgentFolder) details.push(`agent folder: ${ctx.cwd}`)
+      details.push(
+        'NTFS ignores the 0600/0700 chmod typeclaw applies to secrets.json and encryption keys; their confidentiality relies on the inherited %USERPROFILE% ACLs instead.',
+      )
+
+      return {
+        status: 'warning',
+        message: 'native Windows does not enforce the file modes that protect agent secrets',
+        details,
+        fix: {
+          description:
+            'Keep the agent folder and ~/.typeclaw under your user profile, where default ACLs restrict access to your account; avoid a shared or everyone-readable location.',
+        },
+      }
+    },
+  }
+}
+
+export type WindowsBindMountDeps = {
+  isWindows: () => boolean
+}
+
+// Docker Desktop bind-mounts the agent folder into its Linux VM, and a few host
+// locations don't survive that translation: UNC/network paths (\\server\share)
+// aren't shareable, OneDrive-virtualized folders fail on placeholder files, and
+// paths near the legacy MAX_PATH (260) limit break mid-build. Flag them so
+// `typeclaw start` fails loudly here instead of cryptically at mount time.
+export function windowsBindMount(deps: Partial<WindowsBindMountDeps> = {}): DoctorCheck {
+  const onWindows = deps.isWindows ?? isWindows
+
+  return {
+    name: 'container.windows-bind-mount',
+    category: 'container',
+    description: 'agent folder is bind-mountable by Docker Desktop (native Windows)',
+    applies: (ctx) => ctx.hasAgentFolder,
+    async run(ctx) {
+      if (!onWindows()) return { status: 'ok', message: 'not running on native Windows' }
+
+      const issues = detectWindowsBindMountIssues(ctx.cwd)
+      if (issues.length === 0) return { status: 'ok', message: 'agent folder path is bind-mountable' }
+
+      return {
+        status: 'warning',
+        message: 'agent folder may not bind-mount cleanly under Docker Desktop',
+        details: issues,
+        fix: {
+          description:
+            'Use a local, short, non-OneDrive path under your user profile (e.g. C:\\agents\\my-agent), then re-run typeclaw start.',
+        },
+      }
+    },
+  }
+}
+
+export function detectWindowsBindMountIssues(path: string): string[] {
+  const issues: string[] = []
+  if (path.startsWith('\\\\')) {
+    issues.push(`UNC/network path is not shareable with Docker Desktop: ${path}`)
+  }
+  if (path.split(/[\\/]/).some((seg) => /^onedrive(?: -.*)?$/i.test(seg))) {
+    issues.push(`path is under OneDrive, where virtualized files can break bind mounts: ${path}`)
+  }
+  if (path.length > 260) {
+    issues.push(`path length ${path.length} exceeds the legacy Windows MAX_PATH (260) limit`)
+  }
+  return issues
+}
+
 function hostdReachable(): DoctorCheck {
   return {
     name: 'hostd.reachable',
@@ -362,9 +502,12 @@ function loadConfigStrictForTemplate(
   return { dockerfile: cfg.docker.file, gitignore: cfg.git.ignore }
 }
 
+// Normalizes CRLF to LF: the managed templates are emitted with `\n`, but a
+// checkout under Git for Windows (core.autocrlf=true) rewrites them to `\r\n`,
+// which would make the byte-exact template comparison report a false divergence.
 async function safeRead(path: string): Promise<string | null> {
   try {
-    return await readFile(path, 'utf8')
+    return (await readFile(path, 'utf8')).replace(/\r\n/g, '\n')
   } catch {
     return null
   }

package/src/hostd/tailscale.ts

@@ -1,4 +1,5 @@
 import { getBun } from '@/container/shared'
+import { isMacOS, isWindows } from '@/shared'
 
 export type TailscaleExecResult = { exitCode: number; stdout: string; stderr: string }
 export type TailscaleExec = (args: string[]) => Promise<TailscaleExecResult>
@@ -33,6 +34,7 @@ type TailscaleStatus = {
 }
 
 const MACOS_APP_CLI = '/Applications/Tailscale.app/Contents/MacOS/Tailscale'
+const WINDOWS_CLI = 'C:\\Program Files\\Tailscale\\tailscale.exe'
 
 export function createTailscaleServeManager(opts: TailscaleServeManagerOptions): TailscaleServeManager {
   const exec = opts.exec ?? defaultTailscaleExec
@@ -129,8 +131,17 @@ async function checkRunning(exec: TailscaleExec): Promise<{ ok: true } | { ok: f
   return { ok: true }
 }
 
+// `tailscale` on PATH is tried first everywhere; the platform-specific absolute
+// path is a fallback for GUI installs that leave the CLI off PATH (the macOS app
+// bundle, the Windows default install dir).
+export function tailscaleCandidates(platform: NodeJS.Platform = process.platform): string[] {
+  if (isMacOS(platform)) return ['tailscale', MACOS_APP_CLI]
+  if (isWindows(platform)) return ['tailscale', WINDOWS_CLI]
+  return ['tailscale']
+}
+
 export const defaultTailscaleExec: TailscaleExec = async (args) => {
-  const candidates = process.platform === 'darwin' ? ['tailscale', MACOS_APP_CLI] : ['tailscale']
+  const candidates = tailscaleCandidates()
   let lastError = 'tailscale command not found'
 
   for (const candidate of candidates) {

package/src/init/index.ts

@@ -20,7 +20,14 @@ import {
   type KnownProviderId,
   type ModelRef,
 } from '@/config/providers'
-import { checkDockerAvailable, type DockerAvailability, type DockerExec, start } from '@/container'
+import {
+  checkDockerAvailable,
+  type DockerAvailability,
+  type DockerExec,
+  start,
+  type StartResult,
+  stop,
+} from '@/container'
 import { commitSystemFile } from '@/git/system-commit'
 import { createSecretsStoreForAgent, type Channels, type Secret, SecretsBackend } from '@/secrets'
 import { hostLocaleIsCjk } from '@/shared/host-locale'
@@ -376,10 +383,12 @@ export async function runInit({
   emit({ step: 'install', phase: 'start' })
   const install = await installRunner(cwd)
   emit({ step: 'install', phase: 'done', result: install })
+  if (!install.ok) throw new Error(`Dependency install failed: ${install.reason}`)
 
   emit({ step: 'dockerfile', phase: 'start' })
   const docker = await writeDockerAssets(cwd)
   emit({ step: 'dockerfile', phase: 'done', result: docker })
+  if (!docker.ok) throw new Error(`Dockerfile generation failed: ${docker.reason}`)
 
   emit({ step: 'git', phase: 'start' })
   const git = await initGitRepo(cwd)
@@ -417,6 +426,7 @@ export async function defaultRunHatching({
   tui: tuiFactory = createTui,
   waitForAgent: waitForAgentFn = waitForAgent,
   runClaim = defaultRunClaim,
+  stopContainer = stop,
 }: {
   cwd: string
   port: number
@@ -426,14 +436,17 @@ export async function defaultRunHatching({
   tui?: typeof createTui
   waitForAgent?: typeof waitForAgent
   runClaim?: ClaimRunner
+  stopContainer?: typeof stop
 }): Promise<HatchingResult> {
+  let launch: Extract<StartResult, { ok: true }> | null = null
   try {
-    const launch = await startContainer({
+    const startResult = await startContainer({
       cwd,
       preferredHostPort: port,
       ...(cliEntry !== undefined ? { cliEntry } : {}),
     })
-    if (!launch.ok) return { ok: false, reason: launch.reason }
+    if (!startResult.ok) return { ok: false, reason: startResult.reason }
+    launch = startResult
 
     // start() may have allocated a different host port (the preferred one was
     // bound). Use the actually-published port for the TUI handshake instead of
@@ -455,6 +468,9 @@ export async function defaultRunHatching({
     await tui.run()
     return { ok: true }
   } catch (error) {
+    if (launch !== null && !launch.alreadyRunning) {
+      await stopContainer({ cwd }).catch(() => {})
+    }
     return { ok: false, reason: error instanceof Error ? error.message : String(error) }
   }
 }
@@ -709,7 +725,7 @@ export async function initGitRepo(cwd: string): Promise<GitInitResult> {
   const bun = (globalThis as { Bun?: { spawn: typeof Bun.spawn } }).Bun
   if (!bun) return { ok: false, reason: 'bun runtime not available' }
 
-  if (existsSync(join(cwd, '.git'))) return { ok: true, skipped: true }
+  const hasGit = existsSync(join(cwd, '.git'))
 
   // Author the initial commit as TypeClaw itself. The agent is still unnamed
   // (IDENTITY.md is empty and hatching hasn't run), so the agent identity will
@@ -724,10 +740,21 @@ export async function initGitRepo(cwd: string): Promise<GitInitResult> {
   }
 
   try {
-    const init = bun.spawn({ cmd: ['git', 'init', '-b', 'main'], cwd, env, stdout: 'pipe', stderr: 'pipe' })
-    if ((await init.exited) !== 0) {
-      const stderr = await new Response(init.stderr).text()
-      return { ok: false, reason: `git init failed: ${stderr.trim() || 'no stderr'}` }
+    if (hasGit) {
+      const head = bun.spawn({
+        cmd: ['git', 'rev-parse', '--verify', 'HEAD'],
+        cwd,
+        env,
+        stdout: 'pipe',
+        stderr: 'pipe',
+      })
+      if ((await head.exited) === 0) return { ok: true, skipped: true }
+    } else {
+      const init = bun.spawn({ cmd: ['git', 'init', '-b', 'main'], cwd, env, stdout: 'pipe', stderr: 'pipe' })
+      if ((await init.exited) !== 0) {
+        const stderr = await new Response(init.stderr).text()
+        return { ok: false, reason: `git init failed: ${stderr.trim() || 'no stderr'}` }
+      }
     }
 
     const add = bun.spawn({ cmd: ['git', 'add', '.'], cwd, env, stdout: 'pipe', stderr: 'pipe' })

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)
   }
 }