typeclaw 0.36.7 → 0.37.0

package/src/init/checkpoint.ts

@@ -0,0 +1,201 @@
+import { mkdir, readFile, rename, unlink, writeFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+
+import {
+  KNOWN_PROVIDERS,
+  listKnownModelRefs,
+  listKnownProviderVendorIds,
+  providerIdsForVendor,
+  type KnownProviderId,
+  type KnownProviderVendorId,
+  type ModelRef,
+} from '@/config/providers'
+
+// In-folder scratch for an in-progress `typeclaw init`, co-located with the
+// agent it describes. Lives under the agent's `.typeclaw/` (the same gitignored
+// local-scratch dir as the persistent-$HOME overlay), so it self-cleans when
+// the half-init folder is deleted, survives a folder rename mid-init, and is
+// inspectable right next to the thing being resumed. Gitignored via
+// `TRULY_IGNORED_PATTERNS`; never committed.
+export const INIT_CHECKPOINT_PATH = join('.typeclaw', 'init-progress.json')
+
+export const WIZARD_CHECKPOINT_VERSION = 1
+
+export type WizardChannelChoice = 'slack' | 'discord' | 'telegram' | 'kakaotalk' | 'github' | 'none'
+
+export type AuthMethod = 'api-key' | 'oauth'
+
+// Only stable selection IDs — never `llmAuth`, tokens, OAuth data, channel
+// secrets, the volatile models.dev catalog, or full `ModelOption` objects. The
+// projection in `checkpointFromSelections` is the single seam that enforces
+// this, so a secret can never leak into host state by accident.
+export interface WizardAnswerCheckpointV1 {
+  version: typeof WIZARD_CHECKPOINT_VERSION
+  cwd: string
+  updatedAt: string
+  vendorId?: KnownProviderVendorId
+  providerId?: KnownProviderId
+  modelRef?: ModelRef | string
+  authMethod?: AuthMethod
+  visionVendorId?: KnownProviderVendorId
+  visionProviderId?: KnownProviderId
+  visionModelRef?: ModelRef | string
+  visionAuthMethod?: AuthMethod
+  channelChoice?: WizardChannelChoice
+}
+
+export interface WizardCheckpointStore {
+  load(cwd: string): Promise<WizardAnswerCheckpointV1 | undefined>
+  save(cwd: string, checkpoint: WizardAnswerCheckpointV1): Promise<void>
+  clear(cwd: string): Promise<void>
+}
+
+// Selections the wizard already holds, projected to the persisted shape. Keep
+// this the ONLY place that reads `WizardState` so secret fields are physically
+// unable to reach the checkpoint file.
+export interface WizardCheckpointSelections {
+  cwd: string
+  vendorId?: KnownProviderVendorId
+  providerId?: KnownProviderId
+  modelRef?: ModelRef | string
+  authMethod?: AuthMethod
+  visionVendorId?: KnownProviderVendorId
+  visionProviderId?: KnownProviderId
+  visionModelRef?: ModelRef | string
+  visionAuthMethod?: AuthMethod
+  channelChoice?: WizardChannelChoice
+}
+
+export function checkpointFromSelections(selections: WizardCheckpointSelections): WizardAnswerCheckpointV1 {
+  return {
+    version: WIZARD_CHECKPOINT_VERSION,
+    cwd: selections.cwd,
+    updatedAt: new Date().toISOString(),
+    ...(selections.vendorId !== undefined ? { vendorId: selections.vendorId } : {}),
+    ...(selections.providerId !== undefined ? { providerId: selections.providerId } : {}),
+    ...(selections.modelRef !== undefined ? { modelRef: selections.modelRef } : {}),
+    ...(selections.authMethod !== undefined ? { authMethod: selections.authMethod } : {}),
+    ...(selections.visionVendorId !== undefined ? { visionVendorId: selections.visionVendorId } : {}),
+    ...(selections.visionProviderId !== undefined ? { visionProviderId: selections.visionProviderId } : {}),
+    ...(selections.visionModelRef !== undefined ? { visionModelRef: selections.visionModelRef } : {}),
+    ...(selections.visionAuthMethod !== undefined ? { visionAuthMethod: selections.visionAuthMethod } : {}),
+    ...(selections.channelChoice !== undefined ? { channelChoice: selections.channelChoice } : {}),
+  }
+}
+
+// Drop any saved field that no longer references a real vendor/provider/model.
+// Stale values cascade downward: an unknown provider invalidates its model and
+// auth-method too, since those were chosen for a provider that no longer
+// exists. Returns a sanitized copy; never throws on drift.
+export function sanitizeCheckpointAgainstCatalog(
+  checkpoint: WizardAnswerCheckpointV1,
+  validModelRefs: ReadonlySet<string> = new Set(listKnownModelRefs()),
+): WizardAnswerCheckpointV1 {
+  const sanitized: WizardAnswerCheckpointV1 = {
+    version: WIZARD_CHECKPOINT_VERSION,
+    cwd: checkpoint.cwd,
+    updatedAt: checkpoint.updatedAt,
+  }
+
+  const vendor = pruneVendor(checkpoint.vendorId)
+  const provider = pruneProvider(vendor, checkpoint.providerId)
+  if (vendor !== undefined) sanitized.vendorId = vendor
+  if (provider !== undefined) {
+    sanitized.providerId = provider
+    if (checkpoint.modelRef !== undefined && validModelRefs.has(checkpoint.modelRef)) {
+      sanitized.modelRef = checkpoint.modelRef
+    }
+    if (checkpoint.authMethod !== undefined) sanitized.authMethod = checkpoint.authMethod
+  }
+
+  const visionVendor = pruneVendor(checkpoint.visionVendorId)
+  const visionProvider = pruneProvider(visionVendor, checkpoint.visionProviderId)
+  if (visionVendor !== undefined) sanitized.visionVendorId = visionVendor
+  if (visionProvider !== undefined) {
+    sanitized.visionProviderId = visionProvider
+    if (checkpoint.visionModelRef !== undefined && validModelRefs.has(checkpoint.visionModelRef)) {
+      sanitized.visionModelRef = checkpoint.visionModelRef
+    }
+    if (checkpoint.visionAuthMethod !== undefined) sanitized.visionAuthMethod = checkpoint.visionAuthMethod
+  }
+
+  if (checkpoint.channelChoice !== undefined) sanitized.channelChoice = checkpoint.channelChoice
+
+  return sanitized
+}
+
+function pruneVendor(vendorId: KnownProviderVendorId | undefined): KnownProviderVendorId | undefined {
+  if (vendorId === undefined) return undefined
+  return listKnownProviderVendorIds().includes(vendorId) ? vendorId : undefined
+}
+
+function pruneProvider(
+  vendorId: KnownProviderVendorId | undefined,
+  providerId: KnownProviderId | undefined,
+): KnownProviderId | undefined {
+  if (vendorId === undefined || providerId === undefined) return undefined
+  if (!(providerId in KNOWN_PROVIDERS)) return undefined
+  return providerIdsForVendor(vendorId).includes(providerId) ? providerId : undefined
+}
+
+function checkpointFilePath(cwd: string): string {
+  return join(cwd, INIT_CHECKPOINT_PATH)
+}
+
+export function createLocalWizardCheckpointStore(): WizardCheckpointStore {
+  return {
+    async load(cwd) {
+      const path = checkpointFilePath(cwd)
+      let parsed: unknown
+      try {
+        parsed = JSON.parse(await readFile(path, 'utf8'))
+      } catch {
+        return undefined
+      }
+      if (!isValidCheckpoint(parsed)) return undefined
+      return parsed
+    },
+
+    // Atomic write: temp + rename within the agent's .typeclaw/ so a crash
+    // mid-write never leaves a half-written file that `load` would misparse and
+    // discard.
+    async save(cwd, checkpoint) {
+      const final = checkpointFilePath(cwd)
+      const tmp = `${final}.${process.pid}.tmp`
+      await mkdir(dirname(final), { recursive: true })
+      await writeFile(tmp, JSON.stringify(checkpoint), { mode: 0o600 })
+      await rename(tmp, final)
+    },
+
+    async clear(cwd) {
+      try {
+        await unlink(checkpointFilePath(cwd))
+      } catch {}
+    },
+  }
+}
+
+function isValidCheckpoint(value: unknown): value is WizardAnswerCheckpointV1 {
+  if (typeof value !== 'object' || value === null) return false
+  const v = value as Record<string, unknown>
+  if (v.version !== WIZARD_CHECKPOINT_VERSION) return false
+  if (typeof v.cwd !== 'string') return false
+  if (typeof v.updatedAt !== 'string') return false
+  // Every optional selection field must be a string when present. Membership
+  // (is this a real provider/model?) is the sanitizer's job, but a non-string
+  // here is structurally corrupt and would later index KNOWN_PROVIDERS or join
+  // into prompt text with a wrong shape — reject it at load.
+  return OPTIONAL_STRING_FIELDS.every((field) => v[field] === undefined || typeof v[field] === 'string')
+}
+
+const OPTIONAL_STRING_FIELDS = [
+  'vendorId',
+  'providerId',
+  'modelRef',
+  'authMethod',
+  'visionVendorId',
+  'visionProviderId',
+  'visionModelRef',
+  'visionAuthMethod',
+  'channelChoice',
+] as const satisfies ReadonlyArray<keyof WizardAnswerCheckpointV1>

package/src/init/dockerfile.ts

@@ -18,6 +18,10 @@ export type BuildDockerfileOptions = {
   // host signal — e.g. a bare `buildDockerfile()` in tests — stays small and
   // deterministic.
   cjkFontsAuto?: boolean
+  // Emit a BuildKit Dockerfile (default) or strip BuildKit-only directives for
+  // hosts without buildx. `start` sets this to false when buildx is absent so
+  // the legacy `docker build` can still build the agent image.
+  buildKit?: boolean
 }
 
 // Apt packages that EVERY image must have — git for the agent runtime,
@@ -75,6 +79,7 @@ const BASELINE_APT_PACKAGES = [
   'util-linux',
   'bubblewrap',
   'jq',
+  'libgomp1',
 ] as const
 
 // curl-impersonate is the only currently-working way to query DuckDuckGo from
@@ -293,9 +298,20 @@ set -eu
 #    (missing library, port conflict, malformed args). Without the
 #    explicit liveness probe below, the shim would then export DISPLAY
 #    and exec bun, agent-browser launches would die with "cannot open
-#    display", and the operator would chase a phantom bug. We capture
-#    $! and \`kill -0\` it on every poll iteration so an early exit
-#    becomes a clear stderr line and a non-zero shim exit.
+#    display", and the operator would chase a phantom bug. A monitor
+#    subshell owns Xvfb, \`wait\`s for it, and drops a status file the
+#    instant it exits; the poll loop checks that file (before the socket
+#    check) so an early exit becomes a clear stderr line and a non-zero
+#    shim exit.
+#
+#    We do NOT probe liveness with \`kill -0 "\$xvfb_pid"\`. A backgrounded
+#    child that exits before the shell \`wait\`s for it becomes a zombie,
+#    and \`kill -0\` returns success on a zombie PID (it still exists in
+#    the process table). Under load the shell reaps the zombie lazily, so
+#    \`kill -0\` reported the dead Xvfb as alive for up to the full 3s
+#    window — the loop then timed out and printed the misleading "did not
+#    create socket within 3s" diagnostic instead of "exited immediately".
+#    The status-file handshake sidesteps zombie semantics entirely.
 #
 # We DO NOT use \`xvfb-run\`. xvfb-run hangs forever when it runs as
 # PID 1 inside a container: its SIGUSR1-based ready handshake races
@@ -451,30 +467,45 @@ start_xvfb() {
   if ! command -v Xvfb >/dev/null 2>&1; then
     return 0
   fi
-  setpriv --bounding-set -net_admin --inh-caps -net_admin --ambient-caps -net_admin \\
-    -- Xvfb :99 -screen 0 1920x1080x24 -ac +extension RANDR -nolisten tcp \\
-    >/dev/null 2>&1 &
+  # A monitor subshell owns Xvfb and \`wait\`s for it (the bare command
+  # blocks until exit), then writes Xvfb's exit code to a status file.
+  # The poll loop below reads that file instead of probing \`kill -0\` —
+  # see invariant 2 above for why zombie semantics make \`kill -0\`
+  # unreliable. \`set +e\` inside the subshell keeps the outer \`set -e\`
+  # from killing the monitor before it records a non-zero Xvfb exit.
+  xvfb_status="/tmp/typeclaw-xvfb-status.$$"
+  rm -f "$xvfb_status"
+  (
+    set +e
+    setpriv --bounding-set -net_admin --inh-caps -net_admin --ambient-caps -net_admin \\
+      -- Xvfb :99 -screen 0 1920x1080x24 -ac +extension RANDR -nolisten tcp \\
+      >/dev/null 2>&1
+    printf '%s\\n' "$?" > "$xvfb_status"
+  ) &
   xvfb_pid=$!
   export DISPLAY=:99
-  # Poll the socket every 10ms up to ~3s. Xvfb cold start is typically
-  # ~20-50ms on a modern host; 3s covers slow Docker Desktop VMs,
-  # Rosetta/QEMU emulation, and loaded CI runners. We also \`kill -0\`
-  # the pid each iteration so an Xvfb that died immediately surfaces
-  # as a clear error instead of a 3-second hang followed by silent
-  # "cannot open display" downstream.
+  # Poll every 10ms up to ~3s. Xvfb cold start is typically ~20-50ms on
+  # a modern host; 3s covers slow Docker Desktop VMs, Rosetta/QEMU
+  # emulation, and loaded CI runners. The status-file check comes FIRST
+  # so an Xvfb that creates the socket and then immediately dies is still
+  # treated as a startup failure.
   i=0
   while [ $i -lt 300 ]; do
-    if [ -S /tmp/.X11-unix/X99 ]; then
-      unset i xvfb_pid
-      return 0
-    fi
-    if ! kill -0 "$xvfb_pid" 2>/dev/null; then
+    if [ -f "$xvfb_status" ]; then
+      wait "$xvfb_pid" 2>/dev/null || true
+      rm -f "$xvfb_status"
       echo "typeclaw-entrypoint: Xvfb exited immediately; cannot start headed display (docker.file.xvfb=true)" >&2
       exit 1
     fi
+    if [ -S /tmp/.X11-unix/X99 ]; then
+      rm -f "$xvfb_status"
+      unset i xvfb_pid xvfb_status
+      return 0
+    fi
     sleep 0.01
     i=$((i + 1))
   done
+  rm -f "$xvfb_status"
   echo "typeclaw-entrypoint: Xvfb did not create /tmp/.X11-unix/X99 within 3s; refusing to continue (docker.file.xvfb=true)" >&2
   exit 1
 }
@@ -547,6 +578,72 @@ RUN echo "${encoded}" | base64 -d > ${TYPECLAW_ENTRYPOINT_PATH} \\
  && chmod +x ${TYPECLAW_ENTRYPOINT_PATH}`
 }
 
+// Layer 7: install @huggingface/transformers with its linux-native binaries.
+//
+// The host node_modules is bind-mounted over /agent at runtime carrying
+// whatever binaries the host (typically macOS) resolved, so this layer seeds
+// LINUX binaries into an image path that survives the bind mount and still
+// wins Node/Bun resolution. Two native-dep mechanisms, fixed differently:
+//
+//   1. onnxruntime-node ships its addon via a POSTINSTALL that materializes the
+//      binary inside the package dir, so a plain `bun add` covers it.
+//   2. sharp resolves its native code from SEPARATE `@img/sharp-*` optional
+//      PACKAGES, not a postinstall addon. sharp is a MANDATORY dep of
+//      transformers, loaded eagerly because the package main chains
+//      transformers.js -> utils/image.js (top-level `import sharp`) even though
+//      typeclaw only does text feature-extraction. `bun add
+//      @huggingface/transformers` alone does NOT pull the linux `@img/*` when
+//      the bind-mounted host tree already satisfies sharp with the macOS ones —
+//      so `sharp.js` throws at import ("Could not load the sharp module using
+//      the linux-<arch> runtime") and the container exits at startup. We
+//      install the arch-matched linux platform packages EXPLICITLY to fix it.
+//
+// CRITICAL — install location. `typeclaw start` bind-mounts the host agent
+// folder over /agent at runtime (`-v <cwd>:/agent`), so anything written under
+// /agent/node_modules at BUILD time is MASKED at runtime and can never win.
+// The prior fix ran this `bun add` under `WORKDIR /agent`, populating
+// /agent/node_modules — invisible behind the bind mount, so the sharp crash
+// persisted. We install from `WORKDIR /` instead: the linux packages land in
+// the IMAGE's /node_modules, which is NOT masked by the /agent mount. Node/Bun
+// resolution for `require('@img/sharp-linux-<arch>')` ascends from
+// /agent/node_modules/sharp up the directory chain and finds /node_modules,
+// so the linux binary resolves. WORKDIR is restored to /agent afterwards so
+// later layers and the runtime CWD are unchanged.
+//
+// EXACT transformers version this image installs. Must stay in lockstep with
+// `@huggingface/transformers` in the repo package.json (a guard test in
+// dockerfile.test.ts asserts the two agree). The pin is EXACT — not a caret —
+// because this layer's `bun add` runs at `WORKDIR /` with NO project lockfile,
+// so the repo `bun.lock` does NOT constrain it. A bare `@huggingface/
+// transformers` (no version) would resolve npm `latest` at BUILD time: the day
+// a newer transformers ships, the container would install it while the
+// sharp/libvips pins below stay fixed, and the mismatched sharp platform
+// packages crash at container import ("Could not load the sharp module using
+// the linux-<arch> runtime"). Pinning the version closes that drift.
+export const TRANSFORMERS_VERSION = '4.2.0'
+
+// sharp + libvips versions are pinned to what @huggingface/transformers@4.2.0
+// resolves. A future transformers bump that moves sharp must bump
+// TRANSFORMERS_VERSION, `sharp@`, `@img/sharp-linux-*`, and
+// `@img/sharp-libvips-linux-*` together — mismatched sharp/libvips platform
+// packages are a known failure mode. `$TARGETARCH` is `arm64` or `amd64`; an
+// empty value (bare `docker build` without buildx) falls back to x64 for
+// determinism.
+const LAYER_TRANSFORMERS_INSTALL = `# Layer 7: install @huggingface/transformers with its linux-native binaries.
+# Installs the linux onnxruntime-node addon AND sharp's linux platform packages
+# (@img/sharp-linux-*) into the image's /node_modules so they survive the
+# runtime /agent bind mount and still win Node/Bun resolution from
+# /agent/node_modules/sharp. The transformers version is pinned EXACT (this
+# bun add has no lockfile) — see src/init/dockerfile.ts for the rationale.
+WORKDIR /
+RUN SHARP_ARCH="$(if [ "\${TARGETARCH:-amd64}" = "arm64" ]; then echo arm64; else echo x64; fi)" \\
+ && bun add \\
+      @huggingface/transformers@${TRANSFORMERS_VERSION} \\
+      sharp@0.34.5 \\
+      "@img/sharp-linux-\${SHARP_ARCH}@0.34.5" \\
+      "@img/sharp-libvips-linux-\${SHARP_ARCH}@1.2.4"
+WORKDIR /agent`
+
 // Claude Code's official installer is `curl | bash`, not apt — can't live
 // in APT_FEATURES. Layer placed after the toggle apt install (so curl + ca-
 // certificates from the baseline are guaranteed present) and before the
@@ -1033,7 +1130,7 @@ const TYPECLAW_CX_GLOBAL_HOOKS = JSON.stringify({
   },
 })
 
-function renderCodexCliInstallLayer(enabled: boolean): string {
+function renderCodexCliInstallLayer(enabled: boolean, buildKit: boolean): string {
   if (!enabled) return ''
   return `# Layer 5.7 (toggle): install OpenAI's Codex CLI. Opt-in via
 # typeclaw.json#docker.file.codexCli. The skill \`typeclaw-codex-cli\`
@@ -1043,8 +1140,7 @@ function renderCodexCliInstallLayer(enabled: boolean): string {
 # are pre-written at build time so the operator subagent never has to
 # construct that JSON itself — same load-bearing reason as the Claude
 # Code layer above.
-RUN --mount=type=cache,target=/root/.bun/install/cache,sharing=locked \\
-    bun install -g @openai/codex \\
+RUN ${bunCacheMount(buildKit)}bun install -g @openai/codex \\
  && codex --version > /dev/null \\
  && cat > ${TYPECLAW_CX_SESSION_START_HOOK_PATH} <<'TYPECLAW_CX_SESSION_START_HOOK_EOF'
 ${TYPECLAW_CX_SESSION_START_HOOK_SCRIPT}TYPECLAW_CX_SESSION_START_HOOK_EOF
@@ -1129,15 +1225,19 @@ export function buildDockerfile(
   config: DockerfileConfig = defaultConfig(),
   options: BuildDockerfileOptions = {},
 ): string {
+  // buildKit is the default; `start` passes false on hosts without buildx so the
+  // generated Dockerfile omits the `# syntax=` pragma and every cache mount —
+  // the legacy builder accepts the result as-is, no text post-processing needed.
+  const buildKit = options.buildKit !== false
   const cjkFonts = resolveCjkFonts(config.cjkFonts, options.cjkFontsAuto ?? false)
   const toggleAptArgs = collectToggleAptArgs(config, cjkFonts)
-  const ghKeyringLayer = renderGhKeyringLayer(config.gh)
+  const ghKeyringLayer = renderGhKeyringLayer(config.gh, buildKit)
   const cloudflaredLayer = renderCloudflaredLayer(config.cloudflared)
   const customLines = renderCustomDockerfileLines(config.append)
   const baseImageVersion = options.baseImageVersion ?? null
 
   const claudeCodeLayer = renderClaudeCodeInstallLayer(config.claudeCode)
-  const codexCliLayer = renderCodexCliInstallLayer(config.codexCli)
+  const codexCliLayer = renderCodexCliInstallLayer(config.codexCli, buildKit)
   const fromAndHeavyLayers =
     baseImageVersion !== null
       ? renderVersionedHead(
@@ -1147,11 +1247,12 @@ export function buildDockerfile(
           cloudflaredLayer,
           claudeCodeLayer,
           codexCliLayer,
+          buildKit,
         )
-      : renderInlineHead(ghKeyringLayer, toggleAptArgs, cloudflaredLayer, claudeCodeLayer, codexCliLayer)
+      : renderInlineHead(ghKeyringLayer, toggleAptArgs, cloudflaredLayer, claudeCodeLayer, codexCliLayer, buildKit)
 
-  return `${BUILDKIT_HEADER}
-# AUTOGENERATED by typeclaw — do not edit.
+  const header = buildKit ? `${BUILDKIT_HEADER}\n` : ''
+  return `${header}# AUTOGENERATED by typeclaw — do not edit.
 # This file is rewritten on every \`typeclaw start\` from src/init/dockerfile.ts
 # in the typeclaw repo. Local edits will be overwritten (and committed away if
 # the working tree is dirty). To change the template, edit dockerfile.ts there.
@@ -1197,8 +1298,9 @@ function renderVersionedHead(
   cloudflaredLayer: string,
   claudeCodeLayer: string,
   codexCliLayer: string,
+  buildKit: boolean,
 ): string {
-  const toggleAptLayer = toggleAptArgs.length === 0 ? '' : `${renderToggleAptInstallLayer(toggleAptArgs)}\n\n`
+  const toggleAptLayer = toggleAptArgs.length === 0 ? '' : `${renderToggleAptInstallLayer(toggleAptArgs, buildKit)}\n\n`
   const cloudflaredBlock = cloudflaredLayer === '' ? '' : `${cloudflaredLayer}\n\n`
   const claudeCodeBlock = claudeCodeLayer === '' ? '' : `${claudeCodeLayer}\n\n`
   const codexCliBlock = codexCliLayer === '' ? '' : `${codexCliLayer}\n\n`
@@ -1210,6 +1312,8 @@ ARG TARGETARCH
 
 ${ghKeyringLayer}${toggleAptLayer}${cloudflaredBlock}${claudeCodeBlock}${codexCliBlock}${renderEntrypointShimLayer()}
 
+${LAYER_TRANSFORMERS_INSTALL}
+
 `
 }
 
@@ -1223,6 +1327,7 @@ function renderInlineHead(
   cloudflaredLayer: string,
   claudeCodeLayer: string,
   codexCliLayer: string,
+  buildKit: boolean,
 ): string {
   const baselineAndToggleArgs = [...BASELINE_APT_PACKAGES, ...toggleAptArgs]
   const cloudflaredBlock = cloudflaredLayer === '' ? '' : `${cloudflaredLayer}\n\n`
@@ -1248,9 +1353,7 @@ ${ghKeyringLayer}# Layer 2 (changes when the package list changes): the actual a
 #
 # No \`rm -rf /var/lib/apt/lists/*\` because the lists live on a cache mount
 # that is excluded from the image layer by definition.
-RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \\
-    --mount=type=cache,target=/var/lib/apt/lists,sharing=locked \\
-    apt-get update \\
+RUN ${aptCacheMount(buildKit)}apt-get update \\
  && apt-get install -y --no-install-recommends \\
       ${baselineAndToggleArgs.join(' ')} \\
  && if [ "$TARGETARCH" = "arm64" ]; then \\
@@ -1264,14 +1367,16 @@ ${LAYER_2_5_CURL_IMPERSONATE}
 
 ${LAYER_3_AGENT_BROWSER_ARM64_CONFIG}
 
-${LAYER_4_AGENT_BROWSER_INSTALL}
+${renderAgentBrowserInstallLayer(buildKit)}
 
 ${LAYER_4_5_AGENT_BROWSER_HEADED_WRAPPER}
 
-${LAYER_5_CHROME_FOR_TESTING}
+${renderChromeForTestingLayer(buildKit)}
 
 ${cloudflaredBlock}${claudeCodeBlock}${codexCliBlock}${renderEntrypointShimLayer()}
 
+${LAYER_TRANSFORMERS_INSTALL}
+
 `
 }
 
@@ -1291,13 +1396,11 @@ RUN ARCH_BIN="$(if [ "$TARGETARCH" = "arm64" ]; then echo arm64; else echo amd64
 `
 }
 
-function renderToggleAptInstallLayer(toggleAptArgs: string[]): string {
+function renderToggleAptInstallLayer(toggleAptArgs: string[], buildKit: boolean): string {
   return `# Layer 1 (toggle apt install): packages requested via typeclaw.json
 # #docker.file toggles. Baseline + Chrome runtime libs are already in the
 # base image; this layer only adds gh/tmux/python/ffmpeg/cjkFonts if enabled.
-RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \\
-    --mount=type=cache,target=/var/lib/apt/lists,sharing=locked \\
-    apt-get update \\
+RUN ${aptCacheMount(buildKit)}apt-get update \\
  && apt-get install -y --no-install-recommends \\
       ${toggleAptArgs.join(' ')}`
 }
@@ -1327,9 +1430,7 @@ ${LAYER_0_APT_KEEP_CACHE}
 # packages (gh/python/tmux/ffmpeg) are intentionally NOT installed here —
 # they layer onto the base in the per-agent Dockerfile so users can opt in/
 # out via typeclaw.json without forcing a base-image rebuild.
-RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \\
-    --mount=type=cache,target=/var/lib/apt/lists,sharing=locked \\
-    apt-get update \\
+RUN ${aptCacheMount(true)}apt-get update \\
  && apt-get install -y --no-install-recommends \\
       ${BASELINE_APT_PACKAGES.join(' ')} \\
  && if [ "$TARGETARCH" = "arm64" ]; then \\
@@ -1343,13 +1444,15 @@ ${LAYER_2_5_CURL_IMPERSONATE}
 
 ${LAYER_3_AGENT_BROWSER_ARM64_CONFIG}
 
-${LAYER_4_AGENT_BROWSER_INSTALL}
+${renderAgentBrowserInstallLayer(true)}
 
 ${LAYER_4_5_AGENT_BROWSER_HEADED_WRAPPER}
 
-${LAYER_5_CHROME_FOR_TESTING}
+${renderChromeForTestingLayer(true)}
 
 ${renderEntrypointShimLayer()}
+
+${LAYER_TRANSFORMERS_INSTALL}
 `
 }
 
@@ -1360,6 +1463,19 @@ ${renderEntrypointShimLayer()}
 
 const BUILDKIT_HEADER = `# syntax=docker/dockerfile:1.7`
 
+// Cache-mount prefixes spliced between `RUN ` and the command. BuildKit honors
+// `--mount=type=cache` (apt .debs / bun packages reused across builds); the
+// legacy builder (hosts without buildx) has no equivalent, so legacy mode emits
+// an empty prefix — same image, just no cross-build cache. Generating the two
+// modes structurally is why typeclaw needs no Dockerfile text post-processing.
+const APT_CACHE_MOUNT =
+  '--mount=type=cache,target=/var/cache/apt,sharing=locked \\\n' +
+  '    --mount=type=cache,target=/var/lib/apt/lists,sharing=locked \\\n    '
+const BUN_CACHE_MOUNT = '--mount=type=cache,target=/root/.bun/install/cache,sharing=locked \\\n    '
+
+const aptCacheMount = (buildKit: boolean): string => (buildKit ? APT_CACHE_MOUNT : '')
+const bunCacheMount = (buildKit: boolean): string => (buildKit ? BUN_CACHE_MOUNT : '')
+
 const FROM_AND_WORKDIR = `FROM oven/bun:1-slim
 
 WORKDIR /agent
@@ -1403,10 +1519,10 @@ RUN if [ "$TARGETARCH" = "arm64" ]; then \\
    && printf '%s\\n' '{"executablePath":"/usr/bin/chromium"}' > /root/.agent-browser/config.json; \\
     fi`
 
-const LAYER_4_AGENT_BROWSER_INSTALL = `# Layer 4 (volatile): install agent-browser globally so it survives the
+const renderAgentBrowserInstallLayer = (buildKit: boolean): string =>
+  `# Layer 4 (volatile): install agent-browser globally so it survives the
 # runtime bind-mount over /agent/node_modules.
-RUN --mount=type=cache,target=/root/.bun/install/cache,sharing=locked \\
-    bun install -g agent-browser`
+RUN ${bunCacheMount(buildKit)}bun install -g agent-browser@^0.27.0`
 
 // Layer 4.5: shim the agent-browser binary with a wrapper that calls
 // \`agent-browser close\` before \`open\`/\`goto\`/\`navigate\` when headed
@@ -1522,10 +1638,9 @@ TYPECLAW_AGENT_BROWSER_WRAPPER_EOF`
 // already installed in Layer 2; --with-deps is a defense-in-depth backstop
 // so a future agent-browser bump that adds new deps installs them
 // automatically (near-no-op when Layer 2 already covers them).
-const LAYER_5_CHROME_FOR_TESTING = `# Layer 5 (heavy, amd64 only): Chrome for Testing download.
-RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \\
-    --mount=type=cache,target=/var/lib/apt/lists,sharing=locked \\
-    if [ "$TARGETARCH" != "arm64" ]; then \\
+const renderChromeForTestingLayer = (buildKit: boolean): string =>
+  `# Layer 5 (heavy, amd64 only): Chrome for Testing download.
+RUN ${aptCacheMount(buildKit)}if [ "$TARGETARCH" != "arm64" ]; then \\
       agent-browser install --with-deps; \\
     fi`
 
@@ -1564,16 +1679,14 @@ function singlePackageArgs(name: string, toggle: DockerfileFeatureToggle): strin
 // (the most frequent change) does not re-fetch the GPG key over the network.
 // When `gh` is disabled, omit the layer entirely — both to skip the network
 // roundtrip on cold builds and to keep the package source registry clean.
-function renderGhKeyringLayer(toggle: DockerfileFeatureToggle): string {
+function renderGhKeyringLayer(toggle: DockerfileFeatureToggle, buildKit: boolean): string {
   if (toggle === false) return ''
   return `# Layer 1 (rarely changes): register the GitHub CLI apt repository and trust
 # its keyring. Split from the package install below so editing the package
 # list (the most frequent change to this Dockerfile) does NOT re-fetch the
 # GPG key over the network. The cache mount on /var/cache/apt covers the
 # tiny gnupg/curl install we need to bootstrap the key fetch.
-RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \\
-    --mount=type=cache,target=/var/lib/apt/lists,sharing=locked \\
-    apt-get update \\
+RUN ${aptCacheMount(buildKit)}apt-get update \\
  && apt-get install -y --no-install-recommends curl ca-certificates gnupg \\
  && curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg \\
       | gpg --dearmor -o /etc/apt/keyrings/githubcli-archive-keyring.gpg \\

package/src/init/gitignore.ts

@@ -9,7 +9,7 @@ export const TRULY_IGNORED_PATTERNS = [
   '.env.local',
   'secrets.json',
   'auth.json',
-  '.typeclaw/home/',
+  '.typeclaw/',
   'node_modules/',
   'packages/*/node_modules/',
   'workspace/',
@@ -40,12 +40,12 @@ export function buildGitignore(config: GitignoreConfig = { append: [] }): string
 # as a safety net so an agent folder cloned from a pre-rename machine never
 # stages credentials by accident.
 #
-# .typeclaw/home/ is the persistent-$HOME overlay populated by the
-# entrypoint shim's \`link_persistent_home_files\` (see
-# src/init/dockerfile.ts). It mirrors selected files from the container's
-# $HOME (e.g. ~/.codex/auth.json) into the bind-mounted agent folder so
-# tool credentials survive container restarts. Always credentials; never
-# commit.
+# .typeclaw/ is the agent's local-scratch dir. It holds the persistent-$HOME
+# overlay (.typeclaw/home/, populated by the entrypoint shim's
+# \`link_persistent_home_files\` — see src/init/dockerfile.ts, mirrors container
+# $HOME files like ~/.codex/auth.json so tool credentials survive restarts) and
+# the in-progress init checkpoint (.typeclaw/init-progress.json, non-secret
+# wizard selections for resume). Local-only; never commit.
 ${TRULY_IGNORED_PATTERNS.join('\n')}
 
 # System-managed: gitignored by default so the agent never stages them by hand,