typeclaw 0.1.0 → 0.1.2

package/src/init/cli-version.ts

@@ -0,0 +1,81 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+// Single source of truth for "what version of typeclaw is this agent on,
+// and where does that mean we should pin the base image / write the dep
+// spec." Sync I/O at module load — relative paths are stable in both a dev
+// checkout and a real install, so the parent-walk an earlier draft used
+// was unnecessary side effect. See AGENTS.md "Rules of thumb" for the
+// install-vs-dev distinction this module encodes.
+
+export const GHCR_BASE_IMAGE_REPO = 'ghcr.io/typeclaw/typeclaw-base'
+
+const CLI_PACKAGE_JSON_PATH = join(import.meta.dir, '..', '..', 'package.json')
+
+const cliPkg = JSON.parse(readFileSync(CLI_PACKAGE_JSON_PATH, 'utf8')) as { name?: string; version?: string }
+if (cliPkg.name !== 'typeclaw' || typeof cliPkg.version !== 'string') {
+  throw new Error(`Expected typeclaw package.json at ${CLI_PACKAGE_JSON_PATH}, got name=${cliPkg.name}`)
+}
+
+export const CLI_VERSION = cliPkg.version
+
+const NODE_MODULES_SEGMENT = `${join('/', 'node_modules', '/')}`
+
+function isInstalledCli(): boolean {
+  return CLI_PACKAGE_JSON_PATH.includes(NODE_MODULES_SEGMENT)
+}
+
+// `^X.Y.Z` when the invoking CLI is itself an installed copy of typeclaw
+// (suitable for writing into a freshly-scaffolded agent's package.json),
+// `null` when the CLI is running from the source repo (caller falls back
+// to `file:` so the agent tracks the local checkout).
+export function resolveScaffoldVersion(): string | null {
+  if (!isInstalledCli()) return null
+  return `^${CLI_VERSION}`
+}
+
+// The version of typeclaw the AGENT will actually run inside the container.
+// Prefers `<agent>/node_modules/typeclaw/package.json#version` because that
+// is what the bind-mount exposes to the container at /agent/node_modules,
+// and we want the base image's CLI version to match the runtime's. Falls
+// back to parsing the agent's `dependencies.typeclaw` spec for fresh inits
+// where `bun install` hasn't run yet, and to `null` when neither maps to
+// a release version (dev mode, ranges, dist-tags, etc.).
+export function resolveBaseImageVersion(agentDir: string): string | null {
+  return readInstalledTypeclawVersion(agentDir) ?? readVersionFromDepSpec(agentDir)
+}
+
+function readInstalledTypeclawVersion(agentDir: string): string | null {
+  try {
+    const raw = readFileSync(join(agentDir, 'node_modules', 'typeclaw', 'package.json'), 'utf8')
+    const parsed = JSON.parse(raw) as { version?: string }
+    if (typeof parsed.version === 'string' && isReleaseVersion(parsed.version)) return parsed.version
+  } catch {}
+  return null
+}
+
+function readVersionFromDepSpec(agentDir: string): string | null {
+  try {
+    const raw = readFileSync(join(agentDir, 'package.json'), 'utf8')
+    const parsed = JSON.parse(raw) as { dependencies?: Record<string, string> }
+    const spec = parsed.dependencies?.typeclaw
+    if (typeof spec !== 'string') return null
+    return extractReleaseVersionFromSpec(spec)
+  } catch {
+    return null
+  }
+}
+
+// Accept only specs that name an exact release version we can map 1:1 to a
+// GHCR tag (`X.Y.Z`, `^X.Y.Z`, `~X.Y.Z`, `=X.Y.Z`). Reject ranges, `latest`,
+// `*`, dist-tags, `workspace:` / `git:` / `portal:` / `npm:` aliases. Being
+// strict here delays versioned pinning rather than silently picking the
+// wrong tag — the installed-typeclaw check above is the primary path.
+function extractReleaseVersionFromSpec(spec: string): string | null {
+  const match = spec.trim().match(/^[\^~=]?(\d+\.\d+\.\d+)$/)
+  return match ? (match[1] ?? null) : null
+}
+
+function isReleaseVersion(version: string): boolean {
+  return /^\d+\.\d+\.\d+$/.test(version)
+}

package/src/init/dockerfile.ts

@@ -1,12 +1,33 @@
 import type { DockerfileConfig, DockerfileFeatureToggle } from '@/config/config'
 
+import { GHCR_BASE_IMAGE_REPO } from './cli-version'
+
 export const DOCKERFILE = 'Dockerfile'
 
+export type BuildDockerfileOptions = {
+  // Null or omitted = emit the full inline heavy stack (dev mode, tests).
+  baseImageVersion?: string | null
+}
+
 // 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
+// (e.g. the gh keyring) depend on. `iptables` and `util-linux` back the
+// network egress entrypoint shim, installed unconditionally so that flipping
+// `typeclaw.json#network.blockInternal` is a runtime toggle (re-run
+// `typeclaw restart`) and not an image rebuild.
+//
+// On Debian trixie the single `iptables` package ships both the IPv4 nft
+// frontend (`iptables-nft`, available as `iptables` through
+// update-alternatives) and the IPv6 nft frontend (`ip6tables-nft`, available
+// as `ip6tables`). The standalone `iptables-nft`/`ip6tables-nft` package
+// names do NOT exist on trixie — `apt install iptables-nft` fails with
+// "Unable to locate package". The shim invokes `iptables` and `ip6tables`
+// which alternatives resolves to the nft variants.
+//
+// `util-linux` carries `setpriv`, which the shim uses to drop CAP_NET_ADMIN
+// from the bounding set before exec'ing the agent. 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', 'iptables', 'util-linux'] 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
@@ -35,6 +56,132 @@ export const CURL_IMPERSONATE_SHA256_ARM64 = '6766bc67fd3e8e2313875f32b36b5a3fab
 // the impersonation to whatever `curl_chrome` resolves to.
 export const CURL_IMPERSONATE_PROFILE = 'chrome136'
 
+export const TYPECLAW_ENTRYPOINT_PATH = '/usr/local/bin/typeclaw-entrypoint'
+
+// IPv4 networks the container is forbidden to egress to when
+// `network.blockInternal` is true. Loopback (127/8) is NOT here — loopback
+// traffic uses the `lo` interface, which the shim's first ACCEPT rule
+// short-circuits. The agent inside the container needs loopback to dogfood
+// its own `bun run dev` server. RFC1918 (10/8, 172.16/12, 192.168/16) covers
+// router admin panels and home/office LANs. 169.254/16 covers cloud
+// metadata (169.254.169.254 IMDS, 169.254.170.2 ECS task role) and Windows
+// APIPA. 100.64/10 is CGNAT. 224/4 multicast and 240/4 reserved are belt-
+// and-suspenders against creative exfil targets. host.docker.internal (in
+// 172.16/12 on Docker Desktop/Linux) is re-allowed by the shim at runtime
+// via getent so the agent's `restart` tool can still reach hostd.
+export const NETWORK_BLOCK_IPV4_NETS = [
+  '10.0.0.0/8',
+  '172.16.0.0/12',
+  '192.168.0.0/16',
+  '169.254.0.0/16',
+  '100.64.0.0/10',
+  '224.0.0.0/4',
+  '240.0.0.0/4',
+] as const
+
+// IPv6 mirrors of the IPv4 block list. fc00::/7 is unique-local (the IPv6
+// equivalent of RFC1918), fe80::/10 is link-local (incl. SLAAC + IPv6 cloud
+// metadata in fd00:ec2::/64 which fits inside fc00::/7), ff00::/8 is
+// multicast, ::ffff:0:0/96 is IPv4-mapped IPv6 (an attacker could otherwise
+// reach 192.168.x.x via [::ffff:192.168.0.1]).
+export const NETWORK_BLOCK_IPV6_NETS = ['fc00::/7', 'fe80::/10', 'ff00::/8', '::ffff:0:0/96'] as const
+
+// Renders the shell script that runs as PID 1 inside the container. Two
+// modes, picked at boot time from `$TYPECLAW_NETWORK_BLOCK_INTERNAL`:
+//
+//   off (default, blockInternal=false or env unset): no rules installed,
+//   no setpriv. Just exec `bun run typeclaw "$@"`. Identical observable
+//   behavior to the pre-feature container.
+//
+//   on (blockInternal=true): walks IPv4 + IPv6 block lists and installs
+//   REJECT rules in the OUTPUT chain. Loopback (`-o lo`) is ACCEPT'd first
+//   so dev-server dogfooding still works. The hostd HTTP control port on
+//   `host.docker.internal` is re-allowed at runtime — narrowly, single
+//   TCP destport, only when hostd is configured — so the agent's `restart`
+//   tool can still reach the daemon. The shim then drops CAP_NET_ADMIN
+//   from the bounding set AND from the inheritable + ambient sets via
+//   setpriv before exec'ing the agent. Bounding set is the hard ceiling
+//   enforced by execve; inheritable + ambient are cleared defensively to
+//   match setpriv(1)'s explicit warning about not dropping the bounding
+//   set alone.
+//
+// Carve-out is intentionally narrow: ACCEPT only `tcp --dport <hostd-port>`
+// to the host gateway, never the gateway IP wholesale. Without the dport
+// scope, a compromised agent could reach any host service via
+// `host.docker.internal:22` (SSH), `:53` (DNS), `:5432` (postgres), etc.
+// The gateway IP itself sits inside `172.16.0.0/12`, which the IPv4 reject
+// rules below DROP — the narrow ACCEPT here is the only path through.
+// When hostd is not configured (`TYPECLAW_HOSTD_URL` unset or unparseable),
+// nothing is ACCEPT'd: the agent loses self-restart capability but the
+// rest of the egress filter still works.
+//
+// IPv4-only carve-out uses `getent ahostsv4` to force the resolver into
+// the A-record path. Without this, `getent hosts` would return whichever
+// family the resolver prefers, and on systems that prefer AAAA we'd feed
+// a v6 address to `iptables` and crash under `set -e`. host.docker.internal
+// resolves to a bridge gateway that is IPv4-only on every Docker runtime
+// we support (Docker Desktop, OrbStack, Docker on Linux with the
+// `--add-host host.docker.internal:host-gateway` flag typeclaw injects).
+//
+// REJECT (not DROP) so the agent fails fast with an ICMP unreachable
+// instead of hanging on a 30-second connect timeout — much friendlier
+// debug UX and identical security posture.
+//
+// `set -eu` propagates rule-install failures up to PID 1 exit, which kills
+// the container. Failing closed is the right thing: an unenforced
+// blockInternal=true is worse than blockInternal=false.
+export function buildEntrypointShim(): string {
+  const ipv4Rules = NETWORK_BLOCK_IPV4_NETS.map(
+    (net) => `iptables -A OUTPUT -d ${net} -j REJECT --reject-with icmp-port-unreachable`,
+  )
+  const ipv6Rules = NETWORK_BLOCK_IPV6_NETS.map(
+    (net) => `ip6tables -A OUTPUT -d ${net} -j REJECT --reject-with icmp6-port-unreachable`,
+  )
+  return `#!/bin/sh
+# AUTOGENERATED by typeclaw — do not edit.
+# Source: src/init/dockerfile.ts \`buildEntrypointShim()\`.
+set -eu
+
+if [ "\${TYPECLAW_NETWORK_BLOCK_INTERNAL:-0}" != "1" ]; then
+  exec bun run typeclaw "$@"
+fi
+
+iptables -A OUTPUT -o lo -j ACCEPT
+
+# Hostd HTTP control carve-out: narrow ACCEPT, scoped to one TCP port on
+# the host gateway. Skipped silently when hostd is not configured.
+hostd_port=""
+if [ -n "\${TYPECLAW_HOSTD_URL:-}" ]; then
+  hostd_port="$(printf '%s' "$TYPECLAW_HOSTD_URL" | sed -n 's#^https\\{0,1\\}://[^/:]\\{1,\\}:\\([0-9]\\{1,5\\}\\).*#\\1#p')"
+fi
+if [ -n "\${hostd_port:-}" ]; then
+  host_gw_ip="$(getent ahostsv4 host.docker.internal 2>/dev/null | awk '{print $1; exit}')"
+  if [ -n "\${host_gw_ip:-}" ]; then
+    iptables -A OUTPUT -p tcp -d "$host_gw_ip" --dport "$hostd_port" -j ACCEPT
+  fi
+fi
+${ipv4Rules.join('\n')}
+
+ip6tables -A OUTPUT -o lo -j ACCEPT
+${ipv6Rules.join('\n')}
+
+exec setpriv --bounding-set -net_admin --inh-caps -net_admin --ambient-caps -net_admin -- bun run typeclaw "$@"
+`
+}
+
+// Layer 6: install the network-egress entrypoint shim. Content is base64-
+// encoded inline so the Dockerfile is fully self-contained — no second file
+// in the build context, no COPY, no chicken-and-egg between init and start.
+// Layer placement is intentionally late: shim source changes invalidate
+// only this small layer (~1KB image impact), keeping Chrome and apt cached.
+function renderEntrypointShimLayer(): string {
+  const encoded = Buffer.from(buildEntrypointShim(), 'utf8').toString('base64')
+  return `# Layer 6 (small, changes with the egress shim): install /usr/local/bin/typeclaw-entrypoint.
+# The shim is a no-op unless \`network.blockInternal\` is true at runtime.
+RUN echo "${encoded}" | base64 -d > ${TYPECLAW_ENTRYPOINT_PATH} \\
+ && chmod +x ${TYPECLAW_ENTRYPOINT_PATH}`
+}
+
 // 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:
@@ -90,10 +237,19 @@ const APT_FEATURES: Record<'ffmpeg' | 'gh' | 'tmux' | 'python', AptFeature> = {
   },
 }
 
-export function buildDockerfile(config: DockerfileConfig = defaultConfig()): string {
-  const aptArgs = collectAptArgs(config)
+export function buildDockerfile(
+  config: DockerfileConfig = defaultConfig(),
+  options: BuildDockerfileOptions = {},
+): string {
+  const toggleAptArgs = collectToggleAptArgs(config)
   const ghKeyringLayer = renderGhKeyringLayer(config.gh)
   const customLines = renderCustomDockerfileLines(config.append)
+  const baseImageVersion = options.baseImageVersion ?? null
+
+  const fromAndHeavyLayers =
+    baseImageVersion !== null
+      ? renderVersionedHead(baseImageVersion, ghKeyringLayer, toggleAptArgs)
+      : renderInlineHead(ghKeyringLayer, toggleAptArgs)
 
   return `${BUILDKIT_HEADER}
 # AUTOGENERATED by typeclaw — do not edit.
@@ -101,7 +257,51 @@ export function buildDockerfile(config: DockerfileConfig = defaultConfig()): str
 # 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}
+${fromAndHeavyLayers}
+# 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 ["${TYPECLAW_ENTRYPOINT_PATH}"]
+CMD ["run"]
+`
+}
+
+// FROMs the prebuilt typeclaw-base image at the pinned version. Heavy
+// layers (apt baseline, Chrome runtime libs, curl-impersonate, agent-browser,
+// Chrome for Testing) are already in that image, so the per-agent head only
+// re-runs the toggle apt install and (optionally) the gh keyring bootstrap.
+// When no toggle adds packages, the head is empty after the FROM/WORKDIR/ARG
+// trio — rebuild cost ≈ zero for users who don't change typeclaw.json#dockerfile.
+function renderVersionedHead(baseImageVersion: string, ghKeyringLayer: string, toggleAptArgs: string[]): string {
+  const toggleAptLayer = toggleAptArgs.length === 0 ? '' : `${renderToggleAptInstallLayer(toggleAptArgs)}\n\n`
+  return `FROM ${GHCR_BASE_IMAGE_REPO}:${baseImageVersion}
+
+WORKDIR /agent
+
+ARG TARGETARCH
+
+${ghKeyringLayer}${toggleAptLayer}`
+}
+
+// FROMs oven/bun:1-slim and rebuilds the full heavy stack inline. Used by
+// dev-mode runs (typeclaw installed via file: / link: spec) where the
+// matching :version GHCR tag does not yet exist, and by the test suite to
+// keep coverage of the full-stack layers independent of GHCR availability.
+function renderInlineHead(ghKeyringLayer: string, toggleAptArgs: string[]): string {
+  const baselineAndToggleArgs = [...BASELINE_APT_PACKAGES, ...toggleAptArgs]
+  return `${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
@@ -125,7 +325,7 @@ 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(' ')} \\
+      ${baselineAndToggleArgs.join(' ')} \\
  && if [ "$TARGETARCH" = "arm64" ]; then \\
       apt-get install -y --no-install-recommends chromium; \\
     else \\
@@ -141,26 +341,22 @@ ${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
+${renderEntrypointShimLayer()}
 
-${customLines}ENTRYPOINT ["bun", "run", "typeclaw"]
-CMD ["run"]
 `
 }
 
+function renderToggleAptInstallLayer(toggleAptArgs: string[]): string {
+  return `# Layer 1 (toggle apt install): packages requested via typeclaw.json
+# #dockerfile toggles. Baseline + Chrome runtime libs are already in the
+# base image; this layer only adds gh/tmux/python/ffmpeg 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 \\
+ && apt-get install -y --no-install-recommends \\
+      ${toggleAptArgs.join(' ')}`
+}
+
 // 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
@@ -205,6 +401,8 @@ ${LAYER_3_AGENT_BROWSER_ARM64_CONFIG}
 ${LAYER_4_AGENT_BROWSER_INSTALL}
 
 ${LAYER_5_CHROME_FOR_TESTING}
+
+${renderEntrypointShimLayer()}
 `
 }
 
@@ -280,8 +478,8 @@ function defaultConfig(): DockerfileConfig {
   return { ffmpeg: false, gh: true, python: true, tmux: true, append: [] }
 }
 
-function collectAptArgs(config: DockerfileConfig): string[] {
-  const args: string[] = [...BASELINE_APT_PACKAGES]
+function collectToggleAptArgs(config: DockerfileConfig): string[] {
+  const args: string[] = []
   for (const key of ['ffmpeg', 'gh', 'python', 'tmux'] as const) {
     args.push(...APT_FEATURES[key].toAptArgs(config[key]))
   }

package/src/init/ensure-deps.ts

@@ -2,7 +2,7 @@ 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'
+import { type InstallRunner, runBunInstall } from './run-bun-install'
 
 const PACKAGE_FILE = 'package.json'
 const NODE_MODULES = 'node_modules'
@@ -13,7 +13,7 @@ export type EnsureDepsResult =
 
 export type EnsureDepsOptions = {
   cwd: string
-  install?: (cwd: string) => Promise<{ ok: true } | { ok: false; reason: string }>
+  install?: InstallRunner
   detect?: (cwd: string) => Promise<readonly string[]>
 }
 

package/src/init/index.ts

@@ -8,14 +8,15 @@ import { DEFAULT_MODEL_REF, KNOWN_PROVIDERS, providerForModelRef, type KnownMode
 import { checkDockerAvailable, type DockerAvailability, type DockerExec, start } from '@/container'
 import { createTui } from '@/tui'
 
+import { resolveBaseImageVersion, resolveScaffoldVersion } from './cli-version'
 import { buildDockerfile, DOCKERFILE } from './dockerfile'
 import { buildGitignore, GITIGNORE_FILE } from './gitignore'
 import { HATCHING_PROMPT } from './hatching'
 import type { OAuthLoginRunner, OAuthLoginResult } from './oauth-login'
 import { GITKEEP_FILE, PACKAGES_DIR } from './paths'
-import { runBunInstall, type InstallResult } from './run-bun-install'
+import { type InstallResult, type InstallRunner, runBunInstall } from './run-bun-install'
 
-export { runBunInstall, type InstallResult } from './run-bun-install'
+export { type InstallResult, type InstallRunner, runBunInstall } from './run-bun-install'
 
 export { GITKEEP_FILE, PACKAGES_DIR } from './paths'
 
@@ -101,6 +102,7 @@ export type InitOptions = {
   runKakaotalkAuth?: KakaotalkAuthRunner
   onProgress?: (event: InitStepEvent) => void
   runHatching?: HatchRunner
+  runBunInstall?: InstallRunner
   dockerExec?: DockerExec
 }
 
@@ -121,6 +123,7 @@ export async function runInit({
   runKakaotalkAuth,
   onProgress,
   runHatching = defaultRunHatching,
+  runBunInstall: installRunner = runBunInstall,
   dockerExec,
 }: InitOptions): Promise<void> {
   const emit = onProgress ?? (() => {})
@@ -202,7 +205,7 @@ export async function runInit({
   }
 
   emit({ step: 'install', phase: 'start' })
-  const install = await runBunInstall(cwd)
+  const install = await installRunner(cwd)
   emit({ step: 'install', phase: 'done', result: install })
 
   emit({ step: 'dockerfile', phase: 'start' })
@@ -385,24 +388,29 @@ export async function scaffold(root: string, options: ScaffoldOptions = {}): Pro
 const AGENT_BROWSER_VERSION = '^0.26.0'
 
 function buildPackageJson(root: string, name: string): Record<string, unknown> {
-  const typeclawRoot = findTypeclawRoot()
-  // FIXME: temporary dev-stage wiring. Switch to a published version range
-  // (e.g. "typeclaw": "^x.y.z") once typeclaw is released. The `file:` spec is
-  // computed relative to the agent root because `file:` resolves relative to
-  // the consuming package.
-  const fileSpec = typeclawRoot ? `file:${toFileSpec(relative(root, typeclawRoot))}` : 'file:../typeclaw'
   return {
     name,
     private: true,
     type: 'module',
     workspaces: [`${PACKAGES_DIR}/*`],
     dependencies: {
-      typeclaw: fileSpec,
+      typeclaw: resolveTypeclawSpec(root),
       'agent-browser': AGENT_BROWSER_VERSION,
     },
   }
 }
 
+// Prefer the registry-style range (`^X.Y.Z`) when typeclaw is itself an
+// installed package — that's what lets `bun install` in the agent resolve
+// typeclaw from npm. Fall back to `file:` against the local checkout for
+// dev contributors running `bun run src/cli/index.ts init` from the repo.
+function resolveTypeclawSpec(agentRoot: string): string {
+  const scaffoldVersion = resolveScaffoldVersion()
+  if (scaffoldVersion !== null) return scaffoldVersion
+  const typeclawRoot = findTypeclawRoot()
+  return typeclawRoot ? `file:${toFileSpec(relative(agentRoot, typeclawRoot))}` : 'file:../typeclaw'
+}
+
 function toFileSpec(rel: string): string {
   if (rel === '') return '.'
   // bun/npm accept POSIX-style paths in file: specifiers; normalize separators.
@@ -432,9 +440,11 @@ export async function writeDockerAssets(root: string): Promise<DockerAssetsResul
     const devMode = typeclawSpec.startsWith('file:')
 
     const typeclawConfig = await readTypeclawConfig(root)
-    await writeFile(join(root, DOCKERFILE), buildDockerfile(typeclawConfig.dockerfile), { flag: 'wx' }).catch(
-      ignoreExists,
-    )
+    await writeFile(
+      join(root, DOCKERFILE),
+      buildDockerfile(typeclawConfig.dockerfile, { baseImageVersion: resolveBaseImageVersion(root) }),
+      { flag: 'wx' },
+    ).catch(ignoreExists)
 
     return { ok: true, devMode }
   } catch (error) {

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

@@ -1,11 +1,27 @@
 export type InstallResult = { ok: true } | { ok: false; reason: string }
 
+// Signature for the function `runInit` uses to materialize the agent folder's
+// dependencies. Exposed as a named type so callers (and tests) can pass their
+// own stub without re-declaring the shape, mirroring `HatchRunner` and
+// `KakaotalkAuthRunner` in `./index.ts`.
+export type InstallRunner = (cwd: string) => Promise<InstallResult>
+
 export async function runBunInstall(cwd: string): 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({
-      cmd: ['bun', '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.
+      cmd: ['bun', 'install', '--linker=hoisted'],
       cwd,
       stdout: 'pipe',
       stderr: 'pipe',

package/src/plugin/hooks.ts

@@ -6,6 +6,8 @@ import type {
   SessionIdleEvent,
   SessionPromptEvent,
   SessionStartEvent,
+  SessionTurnEndEvent,
+  SessionTurnStartEvent,
   ToolAfterEvent,
   ToolBeforeEvent,
   ToolBeforeResult,
@@ -43,6 +45,8 @@ export type HookBus = {
   runSessionEnd: (event: SessionEndEvent) => Promise<void>
   runSessionIdle: (event: SessionIdleEvent) => Promise<void>
   runSessionPrompt: (event: SessionPromptEvent) => Promise<void>
+  runSessionTurnStart: (event: SessionTurnStartEvent) => Promise<void>
+  runSessionTurnEnd: (event: SessionTurnEndEvent) => Promise<void>
   runToolBefore: (event: ToolBeforeEvent) => Promise<{ block: true; reason: string } | undefined>
   runToolAfter: (event: ToolAfterEvent) => Promise<void>
   count: (name: keyof Hooks) => number
@@ -62,6 +66,8 @@ type Registries = {
   'session.end': RegisteredHook<'session.end'>[]
   'session.idle': RegisteredHook<'session.idle'>[]
   'session.prompt': RegisteredHook<'session.prompt'>[]
+  'session.turn.start': RegisteredHook<'session.turn.start'>[]
+  'session.turn.end': RegisteredHook<'session.turn.end'>[]
   'tool.before': RegisteredHook<'tool.before'>[]
   'tool.after': RegisteredHook<'tool.after'>[]
 }
@@ -74,6 +80,8 @@ export function createHookBus(options: CreateHookBusOptions = {}): HookBus {
     'session.end': [],
     'session.idle': [],
     'session.prompt': [],
+    'session.turn.start': [],
+    'session.turn.end': [],
     'tool.before': [],
     'tool.after': [],
   }
@@ -89,6 +97,8 @@ export function createHookBus(options: CreateHookBusOptions = {}): HookBus {
       if (hooks['session.end']) r['session.end'].push({ ...base, handler: hooks['session.end'] })
       if (hooks['session.idle']) r['session.idle'].push({ ...base, handler: hooks['session.idle'] })
       if (hooks['session.prompt']) r['session.prompt'].push({ ...base, handler: hooks['session.prompt'] })
+      if (hooks['session.turn.start']) r['session.turn.start'].push({ ...base, handler: hooks['session.turn.start'] })
+      if (hooks['session.turn.end']) r['session.turn.end'].push({ ...base, handler: hooks['session.turn.end'] })
       if (hooks['tool.before']) r['tool.before'].push({ ...base, handler: hooks['tool.before'] })
       if (hooks['tool.after']) r['tool.after'].push({ ...base, handler: hooks['tool.after'] })
     },
@@ -98,6 +108,8 @@ export function createHookBus(options: CreateHookBusOptions = {}): HookBus {
       r['session.end'] = r['session.end'].filter((h) => h.pluginName !== pluginName)
       r['session.idle'] = r['session.idle'].filter((h) => h.pluginName !== pluginName)
       r['session.prompt'] = r['session.prompt'].filter((h) => h.pluginName !== pluginName)
+      r['session.turn.start'] = r['session.turn.start'].filter((h) => h.pluginName !== pluginName)
+      r['session.turn.end'] = r['session.turn.end'].filter((h) => h.pluginName !== pluginName)
       r['tool.before'] = r['tool.before'].filter((h) => h.pluginName !== pluginName)
       r['tool.after'] = r['tool.after'].filter((h) => h.pluginName !== pluginName)
     },
@@ -150,6 +162,26 @@ export function createHookBus(options: CreateHookBusOptions = {}): HookBus {
       }
     },
 
+    async runSessionTurnStart(event) {
+      for (const reg of r['session.turn.start']) {
+        try {
+          await reg.handler(event, ctx(reg))
+        } catch (err) {
+          reportHookError(reg, 'session.turn.start', err)
+        }
+      }
+    },
+
+    async runSessionTurnEnd(event) {
+      for (const reg of r['session.turn.end']) {
+        try {
+          await reg.handler(event, ctx(reg))
+        } catch (err) {
+          reportHookError(reg, 'session.turn.end', err)
+        }
+      }
+    },
+
     // First plugin to return `{ block: true, reason }` short-circuits. Earlier
     // plugins' arg mutations remain visible to later plugins via the shared
     // event.args object.

package/src/plugin/index.ts

@@ -18,10 +18,16 @@ export type {
   HookContext,
   HookName,
   Hooks,
+  PluginCheckResult,
+  PluginCheckStatus,
   PluginContext,
   PluginCronJob,
+  PluginDoctorCheck,
+  PluginDoctorContext,
   PluginExecCronJob,
   PluginExports,
+  PluginFixResult,
+  PluginFixSuggestion,
   PluginLogger,
   PluginPromptCronJob,
   PluginSkill,
@@ -55,6 +61,7 @@ export {
   buildPluginCronGlobalId,
   type PluginRegistry,
   type RegisteredCronJob,
+  type RegisteredDoctorCheck,
   type RegisteredSubagent,
   type RegisteredTool,
   type RegisteredSkillEntry,

package/src/plugin/manager.ts

@@ -93,6 +93,7 @@ export async function loadPlugins(opts: LoadPluginsOptions): Promise<LoadPlugins
         registry,
         hooks,
         agentDir: opts.agentDir,
+        pluginConfig: validatedConfig,
       })
     } catch (err) {
       discardRegistrationsBy(resolved.name, registry, hooks)
@@ -123,6 +124,7 @@ export function summarizeLoaded(loaded: LoadPluginsResult['loadedPlugins'], regi
     `${registry.cronJobs.length} cron job(s)`,
     `${registry.skills.length} skill(s)`,
     `${registry.skillsDirs.length} skills dir(s)`,
+    `${registry.doctorChecks.length} doctor check(s)`,
   ].join(', ')
   return `${loaded.length} plugin(s): ${head} [${counts}]`
 }