typeclaw 0.1.3 → 0.1.5

package/src/container/start.ts

@@ -3,7 +3,7 @@ import { existsSync } from 'node:fs'
 import { readFile, writeFile } from 'node:fs/promises'
 import { isAbsolute, join, resolve } from 'node:path'
 
-import { configSchema, expandMountPath, type Config } from '@/config/config'
+import { configSchema, expandMountPath, migrateLegacyConfigShape, type Config } from '@/config'
 import { send as sendToDaemon } from '@/hostd/client'
 import type { HttpInfoResult } from '@/hostd/protocol'
 import { ensureDaemon } from '@/hostd/spawn'
@@ -22,7 +22,7 @@ import { refreshPackageJson } from '@/init/packagejson'
 import { runBunUpdate, type UpdateRunner } from '@/init/run-bun-install'
 import { migrateKakaotalkCredentials } from '@/secrets'
 
-import { CONTAINER_PORT, findFreePort, isPortAllocatedError } from './port'
+import { CONTAINER_PORT, TUI_TOKEN_LABEL, findFreePort, isPortAllocatedError, resolveTuiToken } from './port'
 import {
   classifyRmStderr,
   cleanupRunCorpse,
@@ -57,6 +57,7 @@ export type StartPlan = {
   runArgs: string[]
   needsBuild: boolean
   hostPort: number
+  tuiToken: string | null
 }
 
 export type PlanStartOptions = {
@@ -65,6 +66,8 @@ export type PlanStartOptions = {
   imageExists: boolean
   forceBuild?: boolean
   hostdControl?: HostDaemonControl
+  publishHost?: string
+  tuiToken?: string | null
 }
 
 export type HostDaemonControl = {
@@ -127,6 +130,7 @@ export type StartResult =
       containerId: string
       built: boolean
       hostPort: number
+      tuiToken: string | null
       hostd: HostDaemonStatus
       // True when the container was already running and start() became a no-op.
       // Callers that want to distinguish "I just launched it" from "it was up
@@ -298,7 +302,17 @@ export async function start({
       : { state: 'disabled' as const }
     let hostdControl = hostd.state === 'registered' ? hostd.control : undefined
 
-    let plan = await planStart({ cwd, hostPort, imageExists: imageExisted, forceBuild, hostdControl })
+    const publishHost = await resolvePublishHost(exec)
+    const tuiToken = randomBytes(32).toString('base64url')
+    let plan = await planStart({
+      cwd,
+      hostPort,
+      imageExists: imageExisted,
+      forceBuild,
+      hostdControl,
+      publishHost,
+      tuiToken,
+    })
 
     let built = false
     if (plan.needsBuild) {
@@ -347,7 +361,15 @@ export async function start({
         hostd = await registerWithDaemon({ cwd, containerName, cliEntry, hostPort, reuseCurrentHostDaemon })
         hostdControl = hostd.state === 'registered' ? hostd.control : undefined
       }
-      plan = await planStart({ cwd, hostPort, imageExists: true, forceBuild: false, hostdControl })
+      plan = await planStart({
+        cwd,
+        hostPort,
+        imageExists: true,
+        forceBuild: false,
+        hostdControl,
+        publishHost,
+        tuiToken,
+      })
       run = await execRunWithConflictRetry(exec, plan.runArgs, cwd, containerName)
     }
 
@@ -370,6 +392,7 @@ export async function start({
       containerId,
       built,
       hostPort,
+      tuiToken,
       hostd: stripHostDaemonControl(hostd),
       alreadyRunning: false,
       autoUpgrade: upgrade,
@@ -403,6 +426,8 @@ export async function planStart({
   imageExists,
   forceBuild = false,
   hostdControl,
+  publishHost = '127.0.0.1',
+  tuiToken = null,
 }: PlanStartOptions): Promise<StartPlan> {
   const containerName = containerNameFromCwd(cwd)
   const imageTag = imageTagFromCwd(cwd)
@@ -416,7 +441,7 @@ export async function planStart({
   // the start() preflight force-removes any lingering corpse before the next
   // launch — so the only state Docker ever sees in `docker ps -a` is either
   // a running container or one the user has not started again yet.
-  const runArgs = ['run', '-d', '--name', containerName, '-p', `127.0.0.1:${hostPort}:${CONTAINER_PORT}`]
+  const runArgs = ['run', '-d', '--name', containerName, '-p', `${publishHost}:${hostPort}:${CONTAINER_PORT}`]
 
   // Network egress filter: when `typeclaw.json#network.blockInternal` is true,
   // grant the container CAP_NET_ADMIN at boot so the entrypoint shim can
@@ -424,9 +449,16 @@ export async function planStart({
   // bounding set via setpriv before exec'ing the agent — see the shim source
   // in src/init/dockerfile.ts for the full handoff. The `-e` flag is what
   // tells the shim to take the on-path; absent or set to anything other than
-  // "1", the shim is a no-op.
+  // "1", the shim is a no-op. `autoAllowResolvers` / `allow` envs are only
+  // emitted on the on-path because the shim's off-path doesn't read them;
+  // `TYPECLAW_NETWORK_ALLOW` is comma-joined to match the shim's `IFS=','`
+  // loop, and CIDR validation already happened at config parse time.
   if (cfg.network.blockInternal) {
     runArgs.push('--cap-add=NET_ADMIN', '-e', 'TYPECLAW_NETWORK_BLOCK_INTERNAL=1')
+    runArgs.push('-e', `TYPECLAW_NETWORK_AUTO_ALLOW_RESOLVERS=${cfg.network.autoAllowResolvers ? '1' : '0'}`)
+    if (cfg.network.allow.length > 0) {
+      runArgs.push('-e', `TYPECLAW_NETWORK_ALLOW=${cfg.network.allow.join(',')}`)
+    }
   }
 
   if (hostdControl) {
@@ -436,6 +468,9 @@ export async function planStart({
   for (const [key, value] of Object.entries(composeLabels(cwd, containerName))) {
     runArgs.push('--label', `${key}=${value}`)
   }
+  if (tuiToken !== null) {
+    runArgs.push('--label', `${TUI_TOKEN_LABEL}=${tuiToken}`, '-e', `TYPECLAW_TUI_TOKEN=${tuiToken}`)
+  }
 
   if (existsSync(join(cwd, ENV_FILE))) {
     runArgs.push('--env-file', join(cwd, ENV_FILE))
@@ -486,20 +521,27 @@ export async function planStart({
     runArgs,
     needsBuild: forceBuild || !imageExists,
     hostPort,
+    tuiToken,
   }
 }
 
+async function resolvePublishHost(exec: DockerExec): Promise<string> {
+  const result = await exec(['version', '--format', '{{.Server.Platform.Name}}'])
+  if (result.exitCode === 0 && result.stdout.toLowerCase().includes('docker desktop')) return '0.0.0.0'
+  return '127.0.0.1'
+}
+
 export async function refreshDockerfile(cwd: string): Promise<void> {
   const cfg = await loadTypeclawConfig(cwd)
   await writeFile(
     join(cwd, DOCKERFILE),
-    buildDockerfile(cfg.dockerfile, { baseImageVersion: resolveBaseImageVersion(cwd) }),
+    buildDockerfile(cfg.docker.file, { baseImageVersion: resolveBaseImageVersion(cwd) }),
   )
 }
 
 export async function refreshGitignore(cwd: string): Promise<void> {
   const cfg = await loadTypeclawConfig(cwd)
-  await writeFile(join(cwd, GITIGNORE_FILE), buildGitignore(cfg.gitignore))
+  await writeFile(join(cwd, GITIGNORE_FILE), buildGitignore(cfg.git.ignore))
 }
 
 // Commits TypeClaw-owned system file(s) if any are dirty in git. Skips silently
@@ -616,13 +658,15 @@ async function reportAlreadyRunning(exec: DockerExec, cwd: string, containerName
       reason: `Container ${containerName} is running but its published host port could not be resolved.`,
     }
   }
-  const plan = await planStart({ cwd, hostPort, imageExists: true, forceBuild: false })
+  const tuiToken = await resolveTuiToken({ cwd, exec })
+  const plan = await planStart({ cwd, hostPort, imageExists: true, forceBuild: false, tuiToken })
   return {
     ok: true,
     plan,
     containerId,
     built: false,
     hostPort,
+    tuiToken,
     hostd: { state: 'disabled' },
     alreadyRunning: true,
     autoUpgrade: { kind: 'skipped-already-running' },
@@ -740,7 +784,7 @@ async function loadConfigJson(cwd: string): Promise<unknown> {
   } catch {
     return {}
   }
-  return JSON.parse(raw)
+  return migrateLegacyConfigShape(JSON.parse(raw)).json
 }
 
 type PreparedHostDaemonStatus =

package/src/doctor/checks.ts

@@ -1,5 +1,5 @@
 import { existsSync, mkdirSync } from 'node:fs'
-import { readFile, writeFile } from 'node:fs/promises'
+import { readFile } from 'node:fs/promises'
 import { homedir } from 'node:os'
 import { join, relative } from 'node:path'
 
@@ -10,10 +10,13 @@ import {
   defaultDockerExec,
   imageTagFromCwd,
   inspectContainer,
+  refreshDockerfile,
+  refreshGitignore,
   resolveHostPort,
   type DockerExec,
 } from '@/container'
 import { isDaemonReachable, send } from '@/hostd'
+import { resolveBaseImageVersion } from '@/init/cli-version'
 import { buildDockerfile, DOCKERFILE } from '@/init/dockerfile'
 import { detectMissingDeps } from '@/init/ensure-deps'
 import { buildGitignore, GITIGNORE_FILE } from '@/init/gitignore'
@@ -33,7 +36,6 @@ export function buildStaticChecks(opts: { dockerExec?: DockerExec } = {}): Docto
     agentFolderDockerfileTemplate(),
     agentFolderGitignoreTemplate(),
     agentFolderNodeModules(),
-    agentFolderEnvFile(),
     agentFolderGitRepo(),
     configValid(),
     hostdHomeWritable(),
@@ -152,7 +154,7 @@ function agentFolderDockerfileTemplate(): DoctorCheck {
         fix: {
           description: 'Regenerate the Dockerfile from the typeclaw template.',
           autoFix: async () => {
-            await writeAtomic(dockerfilePath, expected)
+            await refreshDockerfile(ctx.cwd)
             return { summary: 'refreshed Dockerfile from template', changedPaths: [DOCKERFILE] }
           },
         },
@@ -181,7 +183,7 @@ function agentFolderGitignoreTemplate(): DoctorCheck {
         fix: {
           description: 'Regenerate .gitignore from the typeclaw template.',
           autoFix: async () => {
-            await writeAtomic(gitignorePath, expected)
+            await refreshGitignore(ctx.cwd)
             return { summary: 'refreshed .gitignore from template', changedPaths: [GITIGNORE_FILE] }
           },
         },
@@ -209,24 +211,6 @@ function agentFolderNodeModules(): DoctorCheck {
   }
 }
 
-function agentFolderEnvFile(): DoctorCheck {
-  return {
-    name: 'agent-folder.env-file',
-    category: 'agent-folder',
-    description: '.env file is present',
-    applies: (ctx) => ctx.hasAgentFolder,
-    async run(ctx) {
-      if (existsSync(join(ctx.cwd, '.env'))) return { status: 'ok', message: '.env present' }
-      return {
-        status: 'warning',
-        message: '.env is missing',
-        details: ['Channels and external API integrations will not have their secrets injected.'],
-        fix: { description: 'Create a .env file with the credentials your agent needs.' },
-      }
-    },
-  }
-}
-
 function agentFolderGitRepo(): DoctorCheck {
   return {
     name: 'agent-folder.git-repo',
@@ -384,7 +368,7 @@ function buildExpectedDockerfile(cwd: string): string | null {
   try {
     const cfg = loadConfigStrictForTemplate(cwd)
     if (cfg === null) return null
-    return buildDockerfile(cfg.dockerfile)
+    return buildDockerfile(cfg.dockerfile, { baseImageVersion: resolveBaseImageVersion(cwd) })
   } catch {
     return null
   }
@@ -406,7 +390,7 @@ function loadConfigStrictForTemplate(
   const result = validateConfig(cwd)
   if (!result.ok) return null
   const cfg = loadConfigSync(cwd)
-  return { dockerfile: cfg.dockerfile, gitignore: cfg.gitignore }
+  return { dockerfile: cfg.docker.file, gitignore: cfg.git.ignore }
 }
 
 async function safeRead(path: string): Promise<string | null> {
@@ -417,10 +401,6 @@ async function safeRead(path: string): Promise<string | null> {
   }
 }
 
-async function writeAtomic(path: string, content: string): Promise<void> {
-  await writeFile(path, content)
-}
-
 export function relativeToCwd(cwd: string, path: string): string {
   return relative(cwd, path) || '.'
 }

package/src/doctor/commit.ts

@@ -18,8 +18,8 @@ export async function commitAutoFixes(opts: CommitOptions): Promise<CommitOutcom
     return { kind: 'skipped', reason: 'no successful auto-fixes' }
   }
 
-  const pathsStaged = uniqueSorted(successes.flatMap((a) => a.changedPaths))
-  if (pathsStaged.length === 0) {
+  const requested = uniqueSorted(successes.flatMap((a) => a.changedPaths))
+  if (requested.length === 0) {
     return { kind: 'skipped', reason: 'auto-fixes reported no changed paths' }
   }
 
@@ -29,13 +29,23 @@ export async function commitAutoFixes(opts: CommitOptions): Promise<CommitOutcom
 
   const spawnGit = opts.spawnGit ?? defaultSpawnGit
 
+  const filter = await filterCommittable(spawnGit, opts.cwd, requested)
+  if (filter.kind === 'failed') return filter
+  const pathsStaged = filter.paths
+  if (pathsStaged.length === 0) {
+    return {
+      kind: 'skipped',
+      reason: `all changed path(s) are gitignored or untracked-and-ignored (${requested.join(', ')})`,
+    }
+  }
+
   const add = await spawnGit(['add', '--', ...pathsStaged], opts.cwd)
   if (add.exitCode !== 0) {
     return { kind: 'failed', reason: `git add failed: ${add.stderr.trim() || `exit ${add.exitCode}`}` }
   }
 
   const message = buildCommitMessage(opts.attempts)
-  const commit = await spawnGit(['commit', '-m', message], opts.cwd)
+  const commit = await spawnGit(['commit', '-m', message, '--only', '--', ...pathsStaged], opts.cwd)
   if (commit.exitCode !== 0) {
     return { kind: 'failed', reason: `git commit failed: ${commit.stderr.trim() || `exit ${commit.exitCode}`}` }
   }
@@ -45,6 +55,37 @@ export async function commitAutoFixes(opts: CommitOptions): Promise<CommitOutcom
   return { kind: 'committed', commitSha, pathsStaged }
 }
 
+// TypeClaw-owned files like `Dockerfile` live in the "truly-ignored" gitignore
+// category — they're regenerated from the CLI template on every `typeclaw
+// start`, so tracking them would produce noisy "Update Dockerfile" commits.
+// `commitSystemFile` in src/container/start.ts skips them silently because
+// `git status --porcelain -- <ignored>` returns empty. We replicate that
+// behavior here so `doctor --fix` produces the same skip semantics instead
+// of failing with `git add` hints about the ignored file.
+//
+// A non-zero git-status exit IS NOT the same signal as 'empty stdout' — the
+// former means git itself failed (broken index, malformed pathspec, etc.).
+// Surface that as { kind: 'failed' } so the user sees the real cause instead
+// of a misleading 'all paths are gitignored' message.
+async function filterCommittable(
+  spawnGit: SpawnGit,
+  cwd: string,
+  paths: string[],
+): Promise<{ kind: 'ok'; paths: string[] } | { kind: 'failed'; reason: string }> {
+  const out: string[] = []
+  for (const p of paths) {
+    const status = await spawnGit(['status', '--porcelain', '--', p], cwd)
+    if (status.exitCode !== 0) {
+      return {
+        kind: 'failed',
+        reason: `git status failed for ${p}: ${status.stderr.trim() || `exit ${status.exitCode}`}`,
+      }
+    }
+    if (status.stdout.trim().length > 0) out.push(p)
+  }
+  return { kind: 'ok', paths: out }
+}
+
 export function buildCommitMessage(attempts: FixAttempt[]): string {
   const successes = attempts.filter((a): a is Extract<FixAttempt, { ok: true }> => a.ok === true)
   const subject = `typeclaw doctor: auto-fix ${successes.length} issue${successes.length === 1 ? '' : 's'}`

package/src/doctor/plugin-bridge.ts

@@ -1,4 +1,4 @@
-import { resolveHostPort } from '@/container'
+import { resolveHostPort, resolveTuiToken } from '@/container'
 import type { ClientMessage, DoctorCheckPayload, DoctorFixPayload, ServerMessage } from '@/shared'
 
 export type PluginBridgeOptions = {
@@ -80,17 +80,26 @@ async function dial(opts: PluginBridgeOptions): Promise<DialResult> {
   if (url === undefined) {
     try {
       const port = await resolveHostPort({ cwd: opts.cwd })
-      url = `ws://localhost:${port}`
+      const token = await resolveTuiToken({ cwd: opts.cwd })
+      url = buildBridgeUrl(port, token)
     } catch (err) {
       return { kind: 'unreachable', reason: err instanceof Error ? err.message : String(err) }
     }
   }
   const ws = new WebSocket(url)
+  const displayUrl = redactUrl(url)
   try {
     await new Promise<void>((resolve, reject) => {
+      // `timer` is declared up front so `cleanup` can reference it without
+      // hitting the TDZ if the WS fires a synchronous error event during
+      // addEventListener (theoretical, but const-after-cleanup-definition
+      // would throw ReferenceError instead of being the intended no-op).
+      let timer: ReturnType<typeof setTimeout> | undefined
       const cleanup = () => {
+        if (timer !== undefined) clearTimeout(timer)
         ws.removeEventListener('open', onOpen)
         ws.removeEventListener('error', onError)
+        ws.removeEventListener('close', onClose)
       }
       const onOpen = () => {
         cleanup()
@@ -98,10 +107,28 @@ async function dial(opts: PluginBridgeOptions): Promise<DialResult> {
       }
       const onError = (err: unknown) => {
         cleanup()
-        reject(err instanceof Error ? err : new Error(`failed to connect to ${url}`))
+        reject(new Error(`failed to connect to ${displayUrl}: ${err instanceof Error ? err.message : String(err)}`))
       }
+      const onClose = () => {
+        cleanup()
+        reject(new Error(`connection to ${displayUrl} closed before opening`))
+      }
+      // Bun's WebSocket has no built-in connect timeout. Without this, a TCP
+      // handshake that completes but never produces an Upgrade response
+      // (e.g. a wedged docker/orbstack port-forward) leaves the WS stuck in
+      // CONNECTING forever — neither 'open' nor 'error' ever fires, and
+      // `typeclaw doctor` hangs. The per-request timeout downstream doesn't
+      // help because we never reach it.
+      timer = setTimeout(() => {
+        cleanup()
+        try {
+          ws.close()
+        } catch {}
+        reject(new Error(`timed out connecting to ${displayUrl} after ${timeoutMs}ms`))
+      }, timeoutMs)
       ws.addEventListener('open', onOpen, { once: true })
       ws.addEventListener('error', onError, { once: true })
+      ws.addEventListener('close', onClose, { once: true })
     })
   } catch (err) {
     return { kind: 'unreachable', reason: err instanceof Error ? err.message : String(err) }
@@ -109,6 +136,22 @@ async function dial(opts: PluginBridgeOptions): Promise<DialResult> {
   return { kind: 'ok', ws, timeoutMs }
 }
 
+function buildBridgeUrl(port: number, token: string | null): string {
+  const url = new URL(`ws://127.0.0.1:${port}`)
+  if (token !== null) url.searchParams.set('token', token)
+  return url.toString()
+}
+
+function redactUrl(url: string): string {
+  try {
+    const parsed = new URL(url)
+    if (parsed.searchParams.has('token')) parsed.searchParams.set('token', '<redacted>')
+    return parsed.toString()
+  } catch {
+    return url
+  }
+}
+
 async function withRequest<R extends { kind: string }>(
   ws: WebSocket,
   timeoutMs: number,

package/src/init/dockerfile.ts

@@ -132,6 +132,44 @@ export const NETWORK_BLOCK_IPV6_NETS = ['fc00::/7', 'fe80::/10', 'ff00::/8', '::
 // `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.
+//
+// Carve-out ordering is load-bearing. iptables OUTPUT is first-match-wins,
+// and we use -A (append). So the order written into the shim is the order
+// rules will be evaluated:
+//   1. loopback ACCEPT
+//   2. hostd port ACCEPT (narrow: tcp + single dport on the host gateway)
+//   3. resolver ACCEPT (narrow: udp/tcp dport 53 to each /etc/resolv.conf
+//      nameserver) — gated on TYPECLAW_NETWORK_AUTO_ALLOW_RESOLVERS=1
+//   4. user-supplied allowlist ACCEPT (wholesale: -d <cidr>) — driven by
+//      TYPECLAW_NETWORK_ALLOW comma-separated env
+//   5. RFC1918 + link-local + CGNAT + multicast + reserved REJECTs
+// A resolver at 10.0.0.2 hits (3) and ACCEPTs before (5) DROPs it.
+//
+// The resolver carve-out reads /etc/resolv.conf inside the container, NOT
+// on the host. Docker propagates the host's resolver into the container by
+// default (Docker Desktop and OrbStack rewrite it to the embedded DNS
+// proxy at 127.0.0.11; Docker on Linux copies the host's resolv.conf
+// verbatim unless --dns is passed). On Docker Desktop / OrbStack the
+// nameserver is loopback and the rule is a no-op (loopback is already
+// ACCEPT'd by rule 1). On native Linux + EC2/GCE/Azure VMs, the
+// nameserver is the VPC resolver inside RFC1918 — exactly the case this
+// carve-out targets.
+//
+// `awk '/^nameserver/{print $2}'` extracts only the IP, skipping
+// comments, `search`, `options`, and malformed lines. We don't validate
+// the IP further: a malformed nameserver line would have crashed glibc's
+// resolver long before the shim ran, so we trust resolv.conf's contents.
+// IPv6 nameservers (rare in practice, never the case on EC2/GCE/Azure)
+// are skipped by `grep -v ':'` to avoid feeding a v6 address to iptables.
+// `iptables -C` (check) is intentionally NOT used to dedupe — duplicate
+// ACCEPT rules are harmless (still first-match-wins), and the check
+// flag's exit code is hard to reason about under `set -e`.
+//
+// The user-supplied allowlist (TYPECLAW_NETWORK_ALLOW) is splat on
+// commas. Each entry is fed directly to iptables -d, which accepts both
+// bare IPs and CIDR notation. Validation already happened in config.ts at
+// parse time, so the shim trusts the env. Empty env → loop body never
+// runs, zero ACCEPT rules added.
 export function buildEntrypointShim(): string {
   const ipv4Rules = NETWORK_BLOCK_IPV4_NETS.map(
     (net) => `iptables -A OUTPUT -d ${net} -j REJECT --reject-with icmp-port-unreachable`,
@@ -162,6 +200,26 @@ if [ -n "\${hostd_port:-}" ]; then
     iptables -A OUTPUT -p tcp -d "$host_gw_ip" --dport "$hostd_port" -j ACCEPT
   fi
 fi
+
+# Resolver carve-out: parse /etc/resolv.conf nameservers and ACCEPT
+# udp+tcp dport 53 to each. Gated on TYPECLAW_NETWORK_AUTO_ALLOW_RESOLVERS=1.
+if [ "\${TYPECLAW_NETWORK_AUTO_ALLOW_RESOLVERS:-0}" = "1" ] && [ -r /etc/resolv.conf ]; then
+  for ns in $(awk '/^[[:space:]]*nameserver[[:space:]]+/{print $2}' /etc/resolv.conf | grep -v ':' || true); do
+    iptables -A OUTPUT -p udp -d "$ns" --dport 53 -j ACCEPT
+    iptables -A OUTPUT -p tcp -d "$ns" --dport 53 -j ACCEPT
+  done
+fi
+
+# User-supplied allowlist carve-out: comma-separated CIDRs/IPs from
+# TYPECLAW_NETWORK_ALLOW. Already validated at config-parse time.
+if [ -n "\${TYPECLAW_NETWORK_ALLOW:-}" ]; then
+  IFS=','
+  for cidr in $TYPECLAW_NETWORK_ALLOW; do
+    [ -z "$cidr" ] && continue
+    iptables -A OUTPUT -d "$cidr" -j ACCEPT
+  done
+  unset IFS
+fi
 ${ipv4Rules.join('\n')}
 
 ip6tables -A OUTPUT -o lo -j ACCEPT
@@ -326,7 +384,7 @@ ${ghKeyringLayer}# Layer 2 (changes when the package list changes): the actual a
 # 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/
+# \`docker.file\` 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.
 #
@@ -359,7 +417,7 @@ ${renderEntrypointShimLayer()}
 
 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
+# #docker.file 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 \\
@@ -374,7 +432,7 @@ RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \\
 // 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
+// docker.file.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
@@ -529,7 +587,7 @@ RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \\
 
 function renderCustomDockerfileLines(lines: string[]): string {
   if (lines.length === 0) return ''
-  return `# Custom lines from typeclaw.json#dockerfile.append.
+  return `# Custom lines from typeclaw.json#docker.file.append.
 ${lines.join('\n')}
 
 `

package/src/init/gitignore.ts

@@ -39,7 +39,7 @@ channels/
 
 function renderCustomGitignoreEntries(entries: string[]): string {
   if (entries.length === 0) return ''
-  return `# Custom entries from typeclaw.json#gitignore.append.
+  return `# Custom entries from typeclaw.json#git.ignore.append.
 ${entries.join('\n')}
 
 `