typeclaw 0.1.0

package/src/hostd/version.ts

@@ -0,0 +1,115 @@
+import { createHash } from 'node:crypto'
+import { readdir, readFile } from 'node:fs/promises'
+import { dirname, join, resolve, sep } from 'node:path'
+
+// Identifies the typeclaw source the daemon was loaded from. Computed by
+// hashing the bytes of every .ts file under `src/` (excluding tests).
+//
+// Why: the host daemon (`typeclaw _hostd`) is the only long-lived host-stage
+// process. Bun reads source files once at process start; subsequent edits on
+// disk do not propagate. A short-lived CLI invocation (`typeclaw start`) sees
+// the new code immediately, but if it reuses an existing daemon, the daemon
+// keeps serving old in-memory daemon logic indefinitely. The
+// observable effect is that bug fixes "don't apply" until the user manually
+// kills `_hostd` — which is invisible footgun territory.
+//
+// This module produces a deterministic fingerprint of the source the running
+// daemon represents, so the CLI can detect drift over the control socket and
+// transparently respawn. Two implementation guarantees matter:
+//
+// 1. Determinism. The same source tree must always produce the same hash
+//    across processes/machines. We sort entries by path and hash bytes only,
+//    not metadata (mtime/size/inode), so a clean checkout of HEAD always
+//    matches.
+// 2. Right scope. Hash only files the daemon actually loads. Test files and
+//    non-typescript assets are out — changes to them must not trigger a
+//    daemon respawn. The current scheme covers all of `src/**/*.ts` because
+//    the daemon's behavior depends on transitive imports (e.g. the supervisor
+//    callback in `src/cli/hostd.ts` reaches into `src/container/` and
+//    `src/config/`). Over-respawning on `src/agent/` changes is acceptable
+//    cost: a daemon spawn is < 100ms.
+
+export type SourceVersion = string
+
+export type ComputeOptions = {
+  // Absolute path to the project's `src/` directory. The hash covers every
+  // *.ts file rooted here, recursively.
+  srcRoot: string
+  // Test seam. Tests inject an in-memory file map to keep the unit tests
+  // hermetic; production reads the real filesystem.
+  fs?: VersionFs
+}
+
+export type VersionFs = {
+  readdir: (path: string) => Promise<Array<{ name: string; isDirectory: boolean }>>
+  readFile: (path: string) => Promise<Buffer>
+}
+
+const realFs: VersionFs = {
+  readdir: async (path) => {
+    const entries = await readdir(path, { withFileTypes: true })
+    return entries.map((e) => ({ name: e.name, isDirectory: e.isDirectory() }))
+  },
+  readFile: (path) => readFile(path),
+}
+
+export async function computeSourceVersion(opts: ComputeOptions): Promise<SourceVersion> {
+  const fs = opts.fs ?? realFs
+  const root = resolve(opts.srcRoot)
+  const files = await collectSourceFiles(root, root, fs)
+  files.sort()
+
+  const hash = createHash('sha256')
+  for (const rel of files) {
+    const abs = join(root, rel)
+    const bytes = await fs.readFile(abs)
+    // Path separator is normalized so a hash computed on macOS matches one
+    // computed on Linux for the same checkout. Tree fingerprints should not
+    // depend on the host OS's path conventions.
+    const normalizedRel = rel.split(sep).join('/')
+    hash.update(`${normalizedRel}\u0000`)
+    hash.update(bytes)
+    hash.update('\u0000')
+  }
+  return hash.digest('hex').slice(0, 32)
+}
+
+async function collectSourceFiles(root: string, dir: string, fs: VersionFs): Promise<string[]> {
+  const out: string[] = []
+  const entries = await fs.readdir(dir)
+  for (const entry of entries) {
+    if (entry.isDirectory) {
+      const sub = await collectSourceFiles(root, join(dir, entry.name), fs)
+      out.push(...sub)
+      continue
+    }
+    if (!entry.name.endsWith('.ts')) continue
+    if (entry.name.endsWith('.test.ts')) continue
+    const absPath = join(dir, entry.name)
+    const relPath = absPath.slice(root.length + 1)
+    out.push(relPath)
+  }
+  return out
+}
+
+// Resolves the project's `src/` directory from a CLI entry path
+// (typically `process.argv[1]`, which points at `src/cli/index.ts` in dev
+// stage or a bundled JS entry in published builds). Returns `null` if no
+// `src/` ancestor is found, in which case versioning falls back to a
+// constant — disabling drift detection rather than crashing.
+export function resolveSrcRoot(cliEntry: string): string | null {
+  let current = resolve(cliEntry)
+  while (true) {
+    const parent = dirname(current)
+    if (parent === current) return null
+    if (parent.endsWith(`${sep}src`) || parent === 'src') return parent
+    current = parent
+  }
+}
+
+// Sentinel used when the source root cannot be resolved (e.g. published
+// bundle that lives outside a `src/` tree). Both daemon and CLI compute the
+// same fallback, so they will appear in-sync and skip the respawn path. This
+// preserves correctness for non-dev installs at the cost of disabling drift
+// detection there.
+export const UNVERSIONED_SENTINEL: SourceVersion = 'unversioned'

package/src/init/dockerfile.ts

@@ -0,0 +1,327 @@
+import type { DockerfileConfig, DockerfileFeatureToggle } from '@/config/config'
+
+export const DOCKERFILE = 'Dockerfile'
+
+// Apt packages that EVERY image must have — git for the agent runtime,
+// curl/ca-certificates/gnupg for HTTPS and key fetches that downstream layers
+// (e.g. the gh keyring) depend on. Listed first in the apt-get install line so
+// the package set is self-documenting at a glance.
+const BASELINE_APT_PACKAGES = ['git', 'ca-certificates', 'curl', 'gnupg'] as const
+
+// curl-impersonate is the only currently-working way to query DuckDuckGo from
+// a non-browser client on residential IPs in 2026. DDG fingerprints incoming
+// requests at the TLS handshake (JA3/JA4) and HTTP/2 SETTINGS-frame layer
+// before any HTTP headers are read; Bun's native fetch cannot match Chrome's
+// fingerprint (upstream Bun issue #11368, open) so requests get gated behind
+// 202 anomaly-modal responses, escalating to interactive duck-picker
+// challenges. See `src/agent/tools/ddg.ts` for the runtime invocation.
+//
+// Pinned to lexiforest's actively-maintained fork (Chrome 136+ profiles in
+// v1.5.6, May 2026), NOT the original `lwthiker/curl-impersonate` whose last
+// release v0.6.1 (March 2024) carries Chrome ≤116 profiles — two years stale
+// and useless against current DDG fingerprinting. Bumping: replace the
+// version + sha256 constants below and run `typeclaw start --build` in any
+// agent folder per the AGENTS.md "owns the Dockerfile" rule. Verify the new
+// release ships the wrapper named in CURL_IMPERSONATE_PROFILE; lexiforest
+// regenerates the bundled wrappers on Chrome major bumps and occasionally
+// drops older ones.
+export const CURL_IMPERSONATE_VERSION = 'v1.5.6'
+export const CURL_IMPERSONATE_SHA256_AMD64 = 'b60344f63b9ed8806f0e9f7fd357d9f6c9a82aca279ed1e9e257d544885dcbde'
+export const CURL_IMPERSONATE_SHA256_ARM64 = '6766bc67fd3e8e2313875f32b36b5a3fab02beffe77e5f1cf7fc5da99731d403'
+// Wrapper symlink shipped in the v1.5.6 tarball. The tarball lays out
+// curl_chrome136 → curl_chrome alongside the canonical `curl-impersonate`
+// binary; we invoke the version-pinned wrapper so a future release that
+// drops chrome136 fails loudly at search time instead of silently regressing
+// the impersonation to whatever `curl_chrome` resolves to.
+export const CURL_IMPERSONATE_PROFILE = 'chrome136'
+
+// Shared-library runtime deps Chrome for Testing needs to launch on amd64
+// Debian trixie (base of `oven/bun:1-slim`). `agent-browser install
+// --with-deps` (v0.27.0) is supposed to install these but silently no-ops:
+// its hardcoded list omits `libglib2.0-0t64`, so Chrome dies on launch
+// with `libglib-2.0.so.0: cannot open shared object file` even though the
+// binary download and `--with-deps` both exit 0. We install the full
+// Playwright-tested chromium dep set here in Layer 2 so the bug doesn't
+// recur if upstream omits another package; Layer 5 still calls
+// `--with-deps` as a no-op-on-cache-hit backstop for future deps.
+//
+// Package list mirrors Playwright's `debian13-x64` chromium deps in
+// nativeDeps.ts (https://github.com/microsoft/playwright). t64-suffixed
+// names are the trixie-renamed variants from the 64-bit time_t ABI
+// transition; SONAMEs (libglib-2.0.so.0 etc.) are unchanged. Packages
+// without t64 here have no t64 sibling on trixie — verified against
+// packages.debian.org/trixie. Fonts are intentionally omitted: the
+// reported failure is launch-time linker errors, not rendering glyphs;
+// font packages (esp. fonts-noto-cjk) cost ~50MB+ for no launch impact.
+export const CHROME_RUNTIME_APT_PACKAGES_AMD64 = [
+  'libasound2t64',
+  'libatk-bridge2.0-0t64',
+  'libatk1.0-0t64',
+  'libatspi2.0-0t64',
+  'libcairo2',
+  'libcups2t64',
+  'libdbus-1-3',
+  'libdrm2',
+  'libgbm1',
+  'libglib2.0-0t64',
+  'libnspr4',
+  'libnss3',
+  'libpango-1.0-0',
+  'libx11-6',
+  'libxcb1',
+  'libxcomposite1',
+  'libxdamage1',
+  'libxext6',
+  'libxfixes3',
+  'libxkbcommon0',
+  'libxrandr2',
+] as const
+
+type AptFeature = {
+  toAptArgs: (toggle: DockerfileFeatureToggle) => string[]
+}
+
+const APT_FEATURES: Record<'ffmpeg' | 'gh' | 'tmux' | 'python', AptFeature> = {
+  ffmpeg: { toAptArgs: (v) => singlePackageArgs('ffmpeg', v) },
+  gh: { toAptArgs: (v) => singlePackageArgs('gh', v) },
+  tmux: { toAptArgs: (v) => singlePackageArgs('tmux', v) },
+  python: {
+    toAptArgs: (v) => (v === true ? ['python3', 'python3-pip', 'python3-venv', 'python-is-python3'] : []),
+  },
+}
+
+export function buildDockerfile(config: DockerfileConfig = defaultConfig()): string {
+  const aptArgs = collectAptArgs(config)
+  const ghKeyringLayer = renderGhKeyringLayer(config.gh)
+  const customLines = renderCustomDockerfileLines(config.append)
+
+  return `${BUILDKIT_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.
+
+${FROM_AND_WORKDIR}
+
+# Layers are ordered most-stable first to maximize Docker layer cache hits on
+# rebuilds. Anything that pulls from npm (volatile) sits below anything that
+# pulls from apt (stable, version-pinned by the base image's debian release),
+# and the heavy Chrome-for-Testing download on amd64 is isolated in its own
+# final layer so unrelated changes do not invalidate it.
+
+${LAYER_0_APT_KEEP_CACHE}
+
+${ghKeyringLayer}# Layer 2 (changes when the package list changes): the actual apt install.
+# Cache mounts make a re-install nearly free when this layer is invalidated:
+# .deb files come straight from the host's BuildKit cache instead of being
+# refetched from Debian/GitHub mirrors. Package set is composed from the
+# \`dockerfile\` config block in typeclaw.json — toggles for tmux/python/gh/
+# ffmpeg fan out into the args below. Baseline (git/ca-certificates/curl/
+# gnupg) is always installed because downstream layers depend on it.
+#
+# 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 \\
+ && apt-get install -y --no-install-recommends \\
+      ${aptArgs.join(' ')} \\
+ && if [ "$TARGETARCH" = "arm64" ]; then \\
+      apt-get install -y --no-install-recommends chromium; \\
+    else \\
+      apt-get install -y --no-install-recommends \\
+        ${CHROME_RUNTIME_APT_PACKAGES_AMD64.join(' ')}; \\
+    fi
+
+${LAYER_2_5_CURL_IMPERSONATE}
+
+${LAYER_3_AGENT_BROWSER_ARM64_CONFIG}
+
+${LAYER_4_AGENT_BROWSER_INSTALL}
+
+${LAYER_5_CHROME_FOR_TESTING}
+
+# The agent folder (including node_modules) is bind-mounted at runtime by
+# \`typeclaw start\`, so we do not COPY or install here. This keeps the image
+# tiny and lets edits on the host take effect without rebuilds.
+
+ENV NODE_ENV=production
+
+# Pin agent-messenger's config dir into the agent's workspace/ so KakaoTalk
+# (and any future agent-messenger-backed channel) reads/writes credentials
+# inside the bind-mounted agent folder. Without this, the SDK would default
+# to /root/.config/agent-messenger inside the container, which doesn't
+# survive container restarts and isn't visible from the host. The agent
+# folder's bind-mount maps /agent → host's agent dir, so the credentials
+# end up at <agentDir>/workspace/.agent-messenger/ on the host.
+ENV AGENT_MESSENGER_CONFIG_DIR=/agent/workspace/.agent-messenger
+
+${customLines}ENTRYPOINT ["bun", "run", "typeclaw"]
+CMD ["run"]
+`
+}
+
+// Recipe for the prebuilt typeclaw-base image published to
+// ghcr.io/typeclaw/typeclaw-base by .github/workflows/base-image.yml. Built
+// from the same constants and layer templates as buildDockerfile() so the
+// two cannot drift — the published image is a function of this source, not
+// a checked-in Dockerfile that needs hand-syncing. The base intentionally
+// stops before the per-agent layers (gh keyring, apt feature toggles,
+// dockerfile.append, ENV, ENTRYPOINT) so users can still toggle them via
+// typeclaw.json without forcing a base-image rebuild.
+//
+// Layer 2's apt-get install line installs only the baseline packages, NOT
+// the gh/python/tmux/ffmpeg toggles — those layer onto the base in the
+// per-agent Dockerfile.
+export function buildBaseDockerfile(): string {
+  return `${BUILDKIT_HEADER}
+# AUTOGENERATED by scripts/emit-base-dockerfile.ts from src/init/dockerfile.ts.
+# Do not edit by hand — your changes will be lost on the next CI run.
+
+${FROM_AND_WORKDIR}
+
+${LAYER_0_APT_KEEP_CACHE}
+
+# Layer 2 (baseline only): apt baseline + Chrome runtime libs. Toggle-driven
+# 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 \\
+ && apt-get install -y --no-install-recommends \\
+      ${BASELINE_APT_PACKAGES.join(' ')} \\
+ && if [ "$TARGETARCH" = "arm64" ]; then \\
+      apt-get install -y --no-install-recommends chromium; \\
+    else \\
+      apt-get install -y --no-install-recommends \\
+        ${CHROME_RUNTIME_APT_PACKAGES_AMD64.join(' ')}; \\
+    fi
+
+${LAYER_2_5_CURL_IMPERSONATE}
+
+${LAYER_3_AGENT_BROWSER_ARM64_CONFIG}
+
+${LAYER_4_AGENT_BROWSER_INSTALL}
+
+${LAYER_5_CHROME_FOR_TESTING}
+`
+}
+
+// Shared layer templates. Both buildDockerfile() (per-agent) and
+// buildBaseDockerfile() (prebuilt base image) compose from these so the
+// two outputs cannot drift on Chrome runtime libs, curl-impersonate
+// version, or the agent-browser install path.
+
+const BUILDKIT_HEADER = `# syntax=docker/dockerfile:1.7`
+
+const FROM_AND_WORKDIR = `FROM oven/bun:1-slim
+
+WORKDIR /agent
+
+ARG TARGETARCH`
+
+// Layer 0: defeat Debian's apt auto-clean so \`--mount=type=cache\` below
+// actually retains downloaded .debs across builds. The default
+// /etc/apt/apt.conf.d/docker-clean (inherited from debian:slim) deletes
+// /var/cache/apt/archives at the end of every apt invocation, which would
+// nullify our cache mount. Also pre-create the keyring dir so the gh repo
+// layer in the per-agent Dockerfile is one cheap cp/echo with no mkdir.
+const LAYER_0_APT_KEEP_CACHE = `# Layer 0 (rarely changes): defeat Debian's apt auto-clean so cache mounts
+# below actually retain downloaded .debs across builds.
+RUN rm -f /etc/apt/apt.conf.d/docker-clean \\
+ && echo 'Binary::apt::APT::Keep-Downloaded-Packages "true";' > /etc/apt/apt.conf.d/keep-cache \\
+ && mkdir -p -m 755 /etc/apt/keyrings`
+
+// Layer 2.5: install pinned curl-impersonate (lexiforest fork) for the
+// websearch tool's DDG scraper. Required to evade DDG's TLS/HTTP2
+// fingerprinting on residential IPs — see src/agent/tools/ddg.ts for the
+// full rationale. Placed after Layer 2 so curl + ca-certificates + tar
+// (already in baseline) are present, and before agent-browser so a version
+// bump there doesn't invalidate this layer.
+const LAYER_2_5_CURL_IMPERSONATE = `# Layer 2.5 (stable): pinned curl-impersonate (lexiforest fork) for DDG.
+RUN ARCH_TARBALL="$(if [ "$TARGETARCH" = "arm64" ]; then echo aarch64-linux-gnu; else echo x86_64-linux-gnu; fi)" \\
+ && ARCH_SHA="$(if [ "$TARGETARCH" = "arm64" ]; then echo ${CURL_IMPERSONATE_SHA256_ARM64}; else echo ${CURL_IMPERSONATE_SHA256_AMD64}; fi)" \\
+ && cd /tmp \\
+ && curl -fsSL -o curl-impersonate.tar.gz \\
+      "https://github.com/lexiforest/curl-impersonate/releases/download/${CURL_IMPERSONATE_VERSION}/curl-impersonate-${CURL_IMPERSONATE_VERSION}.\${ARCH_TARBALL}.tar.gz" \\
+ && echo "\${ARCH_SHA}  curl-impersonate.tar.gz" | sha256sum -c - \\
+ && tar -xzf curl-impersonate.tar.gz -C /usr/local/bin/ \\
+ && rm curl-impersonate.tar.gz \\
+ && /usr/local/bin/curl_${CURL_IMPERSONATE_PROFILE} --version > /dev/null`
+
+const LAYER_3_AGENT_BROWSER_ARM64_CONFIG = `# Layer 3 (stable, arm64 only): point agent-browser at the apt-installed
+# chromium. Independent of the npm install below so it stays cached across
+# agent-browser version bumps.
+RUN if [ "$TARGETARCH" = "arm64" ]; then \\
+      mkdir -p /root/.agent-browser \\
+   && 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
+# runtime bind-mount over /agent/node_modules.
+RUN --mount=type=cache,target=/root/.bun/install/cache,sharing=locked \\
+    bun install -g agent-browser`
+
+// Layer 5: download the pinned Chrome for Testing build into
+// ~/.agent-browser/browsers/. NO cache mount on that path because the
+// runtime needs the binary in the image. System shared libraries are
+// 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 \\
+      agent-browser install --with-deps; \\
+    fi`
+
+function defaultConfig(): DockerfileConfig {
+  return { ffmpeg: false, gh: true, python: true, tmux: true, append: [] }
+}
+
+function collectAptArgs(config: DockerfileConfig): string[] {
+  const args: string[] = [...BASELINE_APT_PACKAGES]
+  for (const key of ['ffmpeg', 'gh', 'python', 'tmux'] as const) {
+    args.push(...APT_FEATURES[key].toAptArgs(config[key]))
+  }
+  return args
+}
+
+function singlePackageArgs(name: string, toggle: DockerfileFeatureToggle): string[] {
+  if (toggle === false) return []
+  if (toggle === true) return [name]
+  return [`${name}=${toggle}`]
+}
+
+// The gh keyring bootstrap is a separate layer so editing the package list
+// (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 {
+  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 \\
+ && 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 \\
+ && chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg \\
+ && echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" \\
+      > /etc/apt/sources.list.d/github-cli.list
+
+`
+}
+
+function renderCustomDockerfileLines(lines: string[]): string {
+  if (lines.length === 0) return ''
+  return `# Custom lines from typeclaw.json#dockerfile.append.
+${lines.join('\n')}
+
+`
+}

package/src/init/ensure-deps.ts

@@ -0,0 +1,152 @@
+import { existsSync, realpathSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { dirname, join, parse as parsePath } from 'node:path'
+
+import { runBunInstall } from './run-bun-install'
+
+const PACKAGE_FILE = 'package.json'
+const NODE_MODULES = 'node_modules'
+
+export type EnsureDepsResult =
+  | { ok: true; installed: boolean }
+  | { ok: false; reason: string; missing?: readonly string[] }
+
+export type EnsureDepsOptions = {
+  cwd: string
+  install?: (cwd: string) => Promise<{ ok: true } | { ok: false; reason: string }>
+  detect?: (cwd: string) => Promise<readonly string[]>
+}
+
+export async function ensureDepsInstalled(options: EnsureDepsOptions): Promise<EnsureDepsResult> {
+  const { cwd } = options
+  const install = options.install ?? runBunInstall
+  const detect = options.detect ?? detectMissingDeps
+
+  const missing = await detect(cwd)
+  if (missing.length === 0) return { ok: true, installed: false }
+
+  const result = await install(cwd)
+  if (!result.ok) return { ok: false, reason: result.reason, missing }
+
+  // Re-probe: `bun install` returns 0 even when a file:-linked dep's own
+  // package.json is unreachable (it silently no-ops on the target). Without
+  // this check, we'd proceed to `docker run` with a known-broken
+  // node_modules/ and the agent would crash with a confusing in-container
+  // `Cannot find package 'x'`.
+  const stillMissing = await detect(cwd)
+  if (stillMissing.length > 0) {
+    return {
+      ok: false,
+      reason: `bun install completed but these deps are still missing from ${cwd}/node_modules/: ${stillMissing.join(', ')}`,
+      missing: stillMissing,
+    }
+  }
+  return { ok: true, installed: true }
+}
+
+// Walks the agent's package.json plus one level of transitive deps. The
+// canonical failure we guard against: typeclaw is installed, but its own
+// deps (e.g. agent-messenger, zod) aren't reachable from the agent folder
+// after a CLI upgrade added them. Direct deps alone wouldn't catch that —
+// typeclaw IS present, but its dependencies field has grown. Deeper drift
+// (dep-of-dep-of-dep missing) is rare and surfaces during `bun install`.
+//
+// Root deps are checked against <cwd>/node_modules/<dep> ONLY (no walk-up):
+// the agent folder is what gets bind-mounted into the container, so a dep
+// satisfied by some ancestor host folder's node_modules would be invisible
+// inside the container. Walking the host filesystem upward here would
+// silently pass the gate and let `docker run` crash later with "Cannot find
+// package", which is the exact failure mode this whole module was added to
+// prevent.
+//
+// Transitive deps are different: they MUST be resolved via Node's algorithm
+// from the parent package's realpath, not lexical-joined against <cwd>.
+// Bun's isolated linker (used for new workspace projects with
+// `configVersion = 1`, which is TypeClaw's scaffold) symlinks
+// node_modules/<dep> into node_modules/.bun/<dep>@<ver>/node_modules/<dep>/
+// and stores that package's own deps as siblings inside the same nested
+// node_modules. A lexical probe at <cwd>/node_modules/<transitive> finds
+// nothing even though the dep is correctly installed and reachable from
+// the parent — that was the original false-positive that aborted
+// `typeclaw start`.
+export async function detectMissingDeps(cwd: string): Promise<readonly string[]> {
+  const rootDeps = await readDeclaredDeps(join(cwd, PACKAGE_FILE))
+  if (rootDeps.length === 0) return []
+
+  const missing = new Set<string>()
+  const installedRootDirs = new Map<string, string>()
+  for (const dep of rootDeps) {
+    const dir = resolveDirectDep(cwd, dep)
+    if (dir === null) {
+      missing.add(dep)
+    } else {
+      installedRootDirs.set(dep, dir)
+    }
+  }
+
+  for (const [dep, parentDir] of installedRootDirs) {
+    if (missing.has(dep)) continue
+    const transitive = await readDeclaredDeps(join(parentDir, PACKAGE_FILE))
+    for (const t of transitive) {
+      if (!resolveTransitiveDep(parentDir, t)) {
+        missing.add(t)
+      }
+    }
+  }
+
+  return [...missing].sort()
+}
+
+async function readDeclaredDeps(packageJsonPath: string): Promise<readonly string[]> {
+  if (!existsSync(packageJsonPath)) return []
+  let raw: string
+  try {
+    raw = await readFile(packageJsonPath, 'utf8')
+  } catch {
+    return []
+  }
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    return []
+  }
+  if (parsed === null || typeof parsed !== 'object') return []
+  const deps = (parsed as { dependencies?: unknown }).dependencies
+  if (deps === null || typeof deps !== 'object') return []
+  return Object.keys(deps as Record<string, unknown>)
+}
+
+function resolveDirectDep(cwd: string, depName: string): string | null {
+  const candidate = join(cwd, NODE_MODULES, depName)
+  if (!existsSync(join(candidate, PACKAGE_FILE))) return null
+  try {
+    return realpathSync(candidate)
+  } catch {
+    return null
+  }
+}
+
+function resolveTransitiveDep(fromDir: string, depName: string): string | null {
+  let dir: string
+  try {
+    dir = realpathSync(fromDir)
+  } catch {
+    return null
+  }
+  const fsRoot = parsePath(dir).root
+  while (true) {
+    const candidate = join(dir, NODE_MODULES, depName)
+    if (existsSync(join(candidate, PACKAGE_FILE))) {
+      try {
+        return realpathSync(candidate)
+      } catch {
+        return null
+      }
+    }
+    if (dir === fsRoot) return null
+    const parent = dirname(dir)
+    if (parent === dir) return null
+    dir = parent
+  }
+}

package/src/init/gitignore.ts

@@ -0,0 +1,46 @@
+import type { GitignoreConfig } from '@/config/config'
+
+export const GITIGNORE_FILE = '.gitignore'
+
+export function buildGitignore(config: GitignoreConfig = { append: [] }): string {
+  const customEntries = renderCustomGitignoreEntries(config.append)
+
+  return `${customEntries}# Truly ignored: secrets, runtime junk, the agent's free-write zone, and
+# regenerated-on-every-start system files. Never enter git history.
+#
+# Dockerfile is rewritten from the typeclaw CLI template on every \`typeclaw
+# start\` (see src/init/dockerfile.ts), so tracking it would only produce
+# noisy "Update Dockerfile" commits whenever the template changes. Treat it
+# like node_modules/ — reproducible from source, not part of agent state.
+#
+# auth.json is the pre-rename name for secrets.json; kept here permanently
+# as a safety net so an agent folder cloned from a pre-rename machine never
+# stages credentials by accident, even if its agent boot hasn't yet run the
+# auth.json -> secrets.json migration.
+.env
+.env.local
+secrets.json
+auth.json
+node_modules/
+packages/*/node_modules/
+workspace/
+mounts/
+Dockerfile
+.DS_Store
+
+# System-managed: gitignored by default so the agent never stages them by hand,
+# but TypeClaw force-commits them on its own schedule (sessions/ via auto-backup,
+# memory/ via the dreaming subagent). Treat them as runtime-owned, not agent-owned.
+sessions/
+memory/
+channels/
+`
+}
+
+function renderCustomGitignoreEntries(entries: string[]): string {
+  if (entries.length === 0) return ''
+  return `# Custom entries from typeclaw.json#gitignore.append.
+${entries.join('\n')}
+
+`
+}