typeclaw 0.37.3 → 0.37.5

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/kakaotalk-auth.ts

@@ -1,4 +1,4 @@
-import { join, resolve } from 'node:path'
+import { join, posix, resolve } from 'node:path'
 
 import { loginFlow as upstreamLoginFlow } from 'agent-messenger/kakaotalk'
 
@@ -34,7 +34,7 @@ export type LoginFlowOptions = Parameters<LoginFlowFn>[0]
 export type LoginFlowResult = Awaited<ReturnType<LoginFlowFn>>
 
 export function kakaotalkConfigDir(agentDir: string): string {
-  return join(agentDir, 'workspace', '.agent-messenger')
+  return posix.join(agentDir, 'workspace', '.agent-messenger')
 }
 
 export function kakaotalkSecretsPath(agentDir: string): string {

package/src/init/packagejson.ts

@@ -1,6 +1,6 @@
 import { existsSync } from 'node:fs'
 import { mkdir, readFile, writeFile } from 'node:fs/promises'
-import { join } from 'node:path'
+import { join, posix } from 'node:path'
 
 import { GITKEEP_FILE, PACKAGES_DIR } from './paths'
 
@@ -33,7 +33,7 @@ export async function refreshPackageJson(cwd: string): Promise<PackageJsonRefres
     if (updated) changed.push(PACKAGE_FILE)
   }
 
-  const gitkeepRel = join(PACKAGES_DIR, GITKEEP_FILE)
+  const gitkeepRel = posix.join(PACKAGES_DIR, GITKEEP_FILE)
   const gitkeepPath = join(cwd, gitkeepRel)
   if (!existsSync(gitkeepPath)) {
     await mkdir(join(cwd, PACKAGES_DIR), { recursive: true })

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/plugin/loader.ts

@@ -61,8 +61,7 @@ async function loadLocal(entry: string, agentDir: string): Promise<ResolvedPlugi
   if (!existsSync(resolved)) {
     throw new PluginNotFoundError(entry, `plugin path does not exist: ${entry} (resolved to ${resolved})`)
   }
-  const url = pathToFileURL(resolved).href
-  const mod = (await import(url)) as { default?: unknown }
+  const mod = (await import(toModuleSpecifier(resolved))) as { default?: unknown }
   const defined = expectDefined(mod, entry)
   const name = basename(resolved).replace(/\.(ts|tsx|js|mjs|cjs)$/i, '')
   return { name, version: undefined, source: entry, defined }
@@ -108,10 +107,10 @@ async function loadNpm(entry: string, agentDir: string): Promise<ResolvedPlugin>
   // located on disk; the else branch lets Bun's resolver read `exports` maps.
   let importTarget: string
   if (entryPath !== null) {
-    importTarget = pathToFileURL(entryPath).href
+    importTarget = toModuleSpecifier(entryPath)
   } else {
     try {
-      importTarget = Bun.resolveSync(packageName, agentDir)
+      importTarget = toModuleSpecifier(Bun.resolveSync(packageName, agentDir))
     } catch (err) {
       throw new PluginNotFoundError(entry, `cannot resolve plugin "${entry}": ${describeError(err)}`, { cause: err })
     }
@@ -151,6 +150,10 @@ function describeError(err: unknown): string {
   return err instanceof Error ? err.message : String(err)
 }
 
+function toModuleSpecifier(target: string): string {
+  return isAbsolute(target) ? pathToFileURL(target).href : target
+}
+
 function findPackageJson(entry: string, agentDir: string): string | null {
   const PACKAGE_JSON = 'package.json'
   let cur = agentDir

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/sandbox/session-tmp.ts

@@ -1,5 +1,10 @@
 import { mkdir } from 'node:fs/promises'
-import { isAbsolute, join, relative, resolve } from 'node:path'
+import { posix } from 'node:path'
+
+// Container-only code over the POSIX `/tmp`; pinned to `path.posix` so the test
+// suite produces the same backing paths on a win32 runner (default `node:path`
+// would yield `\tmp\…` and diverge from the Linux runtime).
+const { isAbsolute, join, relative, resolve } = posix
 
 // Per-session scratch lives on the REAL container /tmp, namespaced by session id.
 // It sits OUTSIDE the agent folder on purpose: the agent folder's `sessions/` is

package/src/secrets/export-claude-credentials-file.ts

@@ -9,7 +9,7 @@ import {
   writeFileSync,
 } from 'node:fs'
 import { homedir } from 'node:os'
-import { dirname, isAbsolute, join, resolve } from 'node:path'
+import { dirname, isAbsolute, join, posix, resolve } from 'node:path'
 
 import { decodeClaudeAccessTokenExpiryMs, emitClaudeCredentialsJson } from './claude-credentials-json'
 import type { ProviderCredential, Providers } from './schema'
@@ -19,7 +19,7 @@ const FILE_MODE = 0o600
 const DIR_MODE = 0o700
 export const CLAUDE_CREDENTIALS_FILE_NAME = '.credentials.json'
 export const CLAUDE_DEFAULT_CONFIG_DIR_NAME = '.claude'
-export const CLAUDE_CREDENTIALS_RELATIVE_PATH = join(CLAUDE_DEFAULT_CONFIG_DIR_NAME, CLAUDE_CREDENTIALS_FILE_NAME)
+export const CLAUDE_CREDENTIALS_RELATIVE_PATH = posix.join(CLAUDE_DEFAULT_CONFIG_DIR_NAME, CLAUDE_CREDENTIALS_FILE_NAME)
 
 export type ExportClaudeCredentialsFileResult =
   | { action: 'skipped'; reason: SkipReason }

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