typeclaw 0.1.3 → 0.1.5

package/README.md

@@ -43,7 +43,7 @@ The bundled `memory` plugin turns lived experience into reusable knowledge. No m
 
 1. **Observe.** After every idle turn, a `memory-logger` subagent reads the transcript and appends notable fragments to `memory/yyyy-MM-dd.md`. Cheap, frequent, lossy by design.
 2. **Dream.** On a cron schedule (default 4am), a `dreaming` subagent consolidates daily streams into `MEMORY.md`, and — when it spots a procedure worth remembering — writes it as **muscle memory**: a new skill at `memory/skills/<name>/SKILL.md`.
-3. **Apply.** Tomorrow's prompt sees the updated `MEMORY.md`. Muscle-memory skills sit alongside bundled and user-installed ones, loaded on demand. Every dream is `git commit -m Dream`'d, so growth is auditable.
+3. **Apply.** Tomorrow's prompt sees the updated `MEMORY.md`. Muscle-memory skills sit alongside bundled and user-installed ones, loaded on demand. Every dream is committed with a one-line summary — e.g. `dream: 3 fragments + new skill 'pr-review' 🔮` — so growth is auditable.
 
 See [`src/bundled-plugins/memory/README.md`](./src/bundled-plugins/memory/README.md) for the full contract.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typeclaw",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "homepage": "https://github.com/typeclaw/typeclaw#readme",
   "bugs": {
     "url": "https://github.com/typeclaw/typeclaw/issues"

package/src/bundled-plugins/memory/README.md

@@ -27,14 +27,14 @@ All fields are **restart-required** — the plugin reads them once at boot.
 
 ## What it contributes
 
-| Kind     | Name                       | Notes                                                                                                                                                                                                                                                                             |
-| -------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Subagent | `memory-logger`            | Reads a parent transcript past a watermark and appends fragments to `memory/<today>.md`. Coalesced per `agentDir`; the plugin chains spawn calls onto a per-agent Promise so two concurrent channel sessions never race on the same daily stream file.                            |
-| Subagent | `dreaming`                 | Reads `MEMORY.md` plus undreamed daily-stream tails, rewrites `MEMORY.md`, optionally writes muscle-memory skills under `memory/skills/<name>/SKILL.md`, advances the per-day watermark, and `git commit -m Dream` the result. Coalesced per `agentDir`.                          |
-| Cron job | `__plugin_memory_dreaming` | `kind: 'prompt'`, `subagent: 'dreaming'`, scheduled per `memory.dreaming.schedule`.                                                                                                                                                                                               |
-| Hook     | `session.prompt`           | Appends the rendered memory section (`# Memory`, `MEMORY.md`, undreamed stream tails) to `event.prompt`.                                                                                                                                                                          |
-| Hook     | `session.idle`             | Per-session debouncer with size-based ceiling. Resets a `setTimeout(idleMs)` on every event; on fire, calls `ctx.spawnSubagent('memory-logger', ...)`. Also `fs.stat`s the transcript on every event and spawns immediately when growth since the last run reaches `bufferBytes`. |
-| Hook     | `session.end`              | Cancels the debounce timer and immediately spawns `memory-logger` (so the final transcript is captured even when the user disconnects right away).                                                                                                                                |
+| Kind     | Name                       | Notes                                                                                                                                                                                                                                                                                                                                                |
+| -------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Subagent | `memory-logger`            | Reads a parent transcript past a watermark and appends fragments to `memory/<today>.md`. Coalesced per `agentDir`; the plugin chains spawn calls onto a per-agent Promise so two concurrent channel sessions never race on the same daily stream file.                                                                                               |
+| Subagent | `dreaming`                 | Reads `MEMORY.md` plus undreamed daily-stream tails, rewrites `MEMORY.md`, optionally writes muscle-memory skills under `memory/skills/<name>/SKILL.md`, advances the per-day watermark, and commits the result with a summary message (`dream: <summary> <emoji>`, e.g. `dream: 3 fragments + new skill 'pr-review' 🔮`). Coalesced per `agentDir`. |
+| Cron job | `__plugin_memory_dreaming` | `kind: 'prompt'`, `subagent: 'dreaming'`, scheduled per `memory.dreaming.schedule`.                                                                                                                                                                                                                                                                  |
+| Hook     | `session.prompt`           | Appends the rendered memory section (`# Memory`, `MEMORY.md`, undreamed stream tails) to `event.prompt`.                                                                                                                                                                                                                                             |
+| Hook     | `session.idle`             | Per-session debouncer with size-based ceiling. Resets a `setTimeout(idleMs)` on every event; on fire, calls `ctx.spawnSubagent('memory-logger', ...)`. Also `fs.stat`s the transcript on every event and spawns immediately when growth since the last run reaches `bufferBytes`.                                                                    |
+| Hook     | `session.end`              | Cancels the debounce timer and immediately spawns `memory-logger` (so the final transcript is captured even when the user disconnects right away).                                                                                                                                                                                                   |
 
 ## Files on disk
 

package/src/bundled-plugins/memory/dreaming.ts

@@ -183,8 +183,10 @@ export async function commitMemorySnapshot(cwd: string): Promise<void> {
     return
   }
 
+  const message = await buildCommitMessage(bun, cwd, staged)
+
   const commit = bun.spawn({
-    cmd: ['git', 'commit', '-m', 'Dream', '--only', '--', ...staged],
+    cmd: ['git', 'commit', '-m', message, '--only', '--', ...staged],
     cwd,
     stdout: 'pipe',
     stderr: 'pipe',
@@ -194,6 +196,120 @@ export async function commitMemorySnapshot(cwd: string): Promise<void> {
   await applySkipWorktree(bun, cwd)
 }
 
+// Pool of emojis sampled into every dream commit. The pool is small and
+// thematically coherent (sleep + cognition) so `git log --oneline` reads like a
+// dream journal. Exported for tests.
+export const DREAM_EMOJI_POOL = ['💤', '🌙', '⭐', '🛌', '😴', '🧠', '💭', '🔮'] as const
+export type DreamEmoji = (typeof DREAM_EMOJI_POOL)[number]
+
+// Random pick is deliberate (not seeded). Independent draw per commit gives the
+// log surface maximum visual variety; correctness does not depend on the
+// emoji.
+function pickDreamEmoji(): DreamEmoji {
+  const i = Math.floor(Math.random() * DREAM_EMOJI_POOL.length)
+  return DREAM_EMOJI_POOL[i] ?? DREAM_EMOJI_POOL[0]
+}
+
+// Build `dream: <summary> <emoji>` from what is actually staged in the
+// snapshot. The summary is derived from the staged diff (ground truth of what
+// is being committed), not from the handler's intent — so a partial commit
+// reports honestly.
+//
+// Classification:
+//   - `N fragments` when daily-stream files (memory/yyyy-MM-dd.md) added lines
+//   - `+ new skill 'x'` / `+ N new skills` when memory/skills/<name>/SKILL.md
+//     paths are newly added in this commit (status A, not M)
+//   - `MEMORY.md only` when only MEMORY.md changed
+//   - `watermarks only` as the fallback (e.g. only .dreaming-state.json moved)
+export async function buildCommitMessage(
+  bun: { spawn: typeof Bun.spawn },
+  cwd: string,
+  staged: string[],
+  emojiPicker: () => DreamEmoji = pickDreamEmoji,
+): Promise<string> {
+  const summary = await buildDreamSummary(bun, cwd, staged)
+  return `dream: ${summary} ${emojiPicker()}`
+}
+
+const STREAM_FILE_RELATIVE = /^memory\/\d{4}-\d{2}-\d{2}\.md$/
+const SKILL_FILE_RELATIVE = /^memory\/skills\/([^/]+)\/SKILL\.md$/
+
+async function buildDreamSummary(bun: { spawn: typeof Bun.spawn }, cwd: string, staged: string[]): Promise<string> {
+  // numstat: `<added>\t<deleted>\t<path>` per line. Use NUL-terminated so paths
+  // with whitespace round-trip; -z switches the record separator to NUL.
+  const numstat = bun.spawn({
+    cmd: ['git', 'diff', '--cached', '--numstat', '-z', '--', ...staged],
+    cwd,
+    stdout: 'pipe',
+    stderr: 'pipe',
+  })
+  const raw = await new Response(numstat.stdout).text()
+  if ((await numstat.exited) !== 0) return 'snapshot'
+
+  let fragmentLines = 0
+  let touchedMemoryMd = false
+  for (const record of raw.split('\0')) {
+    if (record.length === 0) continue
+    // Each record is `<added>\t<deleted>\t<path>`; binary files report `-`
+    // instead of integers — treat those as 0 since memory artifacts are text.
+    const [addedStr = '', , path = ''] = record.split('\t')
+    const added = Number.parseInt(addedStr, 10)
+    if (!Number.isFinite(added)) continue
+    if (path === 'MEMORY.md') {
+      touchedMemoryMd = true
+    } else if (STREAM_FILE_RELATIVE.test(path)) {
+      fragmentLines += added
+    }
+  }
+
+  // Newly-added muscle-memory skills (status A). Refinements (status M) are
+  // not announced — they ride under the fragment count.
+  const newSkills = await listNewlyAddedSkills(bun, cwd, staged)
+
+  const parts: string[] = []
+  if (fragmentLines > 0) {
+    parts.push(`${fragmentLines} fragment${fragmentLines === 1 ? '' : 's'}`)
+  } else if (touchedMemoryMd && newSkills.length === 0) {
+    parts.push('MEMORY.md only')
+  }
+  if (newSkills.length === 1) {
+    parts.push(`new skill '${newSkills[0]}'`)
+  } else if (newSkills.length > 1) {
+    parts.push(`${newSkills.length} new skills`)
+  }
+
+  if (parts.length === 0) return 'watermarks only'
+  return parts.join(' + ')
+}
+
+async function listNewlyAddedSkills(
+  bun: { spawn: typeof Bun.spawn },
+  cwd: string,
+  staged: string[],
+): Promise<string[]> {
+  const proc = bun.spawn({
+    cmd: ['git', 'diff', '--cached', '--name-status', '-z', '--', ...staged],
+    cwd,
+    stdout: 'pipe',
+    stderr: 'pipe',
+  })
+  const raw = await new Response(proc.stdout).text()
+  if ((await proc.exited) !== 0) return []
+
+  // `--name-status -z` interleaves status and path as separate NUL records:
+  // `A\0path\0M\0other\0...`. Pair them up.
+  const tokens = raw.split('\0').filter((t) => t.length > 0)
+  const names: string[] = []
+  for (let i = 0; i + 1 < tokens.length; i += 2) {
+    const status = tokens[i] ?? ''
+    const path = tokens[i + 1] ?? ''
+    if (status !== 'A') continue
+    const match = SKILL_FILE_RELATIVE.exec(path)
+    if (match) names.push(match[1] ?? '')
+  }
+  return names.filter((n) => n.length > 0)
+}
+
 async function listTrackedSnapshotFiles(bun: { spawn: typeof Bun.spawn }, cwd: string): Promise<string[]> {
   const ls = bun.spawn({
     cmd: ['git', 'ls-files', '-z', '--', ...SNAPSHOT_PATHS],

package/src/cli/init.ts

@@ -13,6 +13,7 @@ import {
   findAgentDir,
   isDirectoryNonEmpty,
   isHatched,
+  readExistingProviderApiKey,
   runInit,
   type InitStep,
   type InitStepEvent,
@@ -64,10 +65,11 @@ export const init = defineCommand({
     const selectedModel = await pickModel()
     const provider = KNOWN_PROVIDERS[selectedModel.providerId]
 
-    const llmAuth = await collectLLMAuth(provider)
+    const existingApiKey = await readExistingProviderApiKey(cwd, selectedModel.providerId)
+    const llmAuth = await collectLLMAuth(provider, existingApiKey)
 
     const channelChoice = await select({
-      message: 'Pick a channel to wire (you can add more later by editing typeclaw.json + .env)',
+      message: 'Pick a channel to wire (you can add more later by editing typeclaw.json + secrets.json)',
       options: [
         { value: 'slack', label: 'Slack' },
         { value: 'discord', label: 'Discord' },
@@ -435,21 +437,36 @@ function reportHatching(event: Extract<InitStepEvent, { step: 'hatching' }>): vo
 }
 
 // Resolves how the user wants to authenticate to the chosen provider:
-// - api-key only (e.g. Fireworks): prompt for the key, write to .env.
+// - api-key only (e.g. Fireworks): prompt for the key, write to secrets.json.
 // - oauth only (e.g. openai-codex): run the browser flow inline, write
 //   secrets.json. No API key prompt at all.
 // - both supported (no providers ship this today, but Anthropic will when
 //   wired): ask "API key or OAuth?" first, then dispatch to the chosen path.
-async function collectLLMAuth(provider: (typeof KNOWN_PROVIDERS)[KnownProviderId]): Promise<LLMAuth> {
+async function collectLLMAuth(
+  provider: (typeof KNOWN_PROVIDERS)[KnownProviderId],
+  existingApiKey: string | null,
+): Promise<LLMAuth> {
   const supportsApiKey = providerSupportsApiKey(provider)
   const supportsOAuth = providerSupportsOAuth(provider)
 
+  const existingKeyDecision = await decideExistingApiKeyReuse(provider, existingApiKey, (message) =>
+    confirm({ message, initialValue: true }),
+  )
+  if (existingKeyDecision === 'cancel') {
+    cancel('Aborted.')
+    process.exit(0)
+  }
+  if (existingKeyDecision === 'reuse' && existingApiKey !== null) {
+    log.info(`Using existing ${provider.name} API key from secrets.json.`)
+    return { kind: 'api-key', apiKey: existingApiKey }
+  }
+
   let method: 'api-key' | 'oauth'
   if (supportsApiKey && supportsOAuth) {
     const choice = await select<'api-key' | 'oauth'>({
       message: `How do you want to authenticate to ${provider.name}?`,
       options: [
-        { value: 'api-key', label: 'API key', hint: `saved to .env as ${provider.apiKeyEnv}` },
+        { value: 'api-key', label: 'API key', hint: 'saved to secrets.json' },
         { value: 'oauth', label: 'OAuth (browser login)', hint: 'saved to secrets.json' },
       ],
       initialValue: 'api-key',
@@ -467,7 +484,7 @@ async function collectLLMAuth(provider: (typeof KNOWN_PROVIDERS)[KnownProviderId
 
   if (method === 'api-key') {
     const apiKey = await password({
-      message: `Put your ${provider.name} API key (will be saved to .env as ${provider.apiKeyEnv})`,
+      message: `Put your ${provider.name} API key (will be saved to secrets.json)`,
       validate: (value) => (value && value.length > 0 ? undefined : 'API key is required'),
     })
     if (isCancel(apiKey)) {
@@ -480,6 +497,18 @@ async function collectLLMAuth(provider: (typeof KNOWN_PROVIDERS)[KnownProviderId
   return { kind: 'oauth', runLogin: makeOAuthLoginRunner(buildOAuthCallbacks(provider.name)) }
 }
 
+export async function decideExistingApiKeyReuse(
+  provider: (typeof KNOWN_PROVIDERS)[KnownProviderId],
+  existingApiKey: string | null,
+  askReuse: (message: string) => Promise<unknown>,
+): Promise<'reuse' | 'prompt' | 'cancel'> {
+  if (!providerSupportsApiKey(provider) || existingApiKey === null) return 'prompt'
+
+  const reuse = await askReuse(`Reuse existing ${provider.name} API key from secrets.json?`)
+  if (isCancel(reuse)) return 'cancel'
+  return reuse === true ? 'reuse' : 'prompt'
+}
+
 // Wraps the OAuth lifecycle into the same clack idiom the rest of the wizard
 // uses: a spinner over the "waiting for login" period, with onAuth printing
 // the URL the user needs to open and onPrompt falling back to a `text`

package/src/cli/reload.ts

@@ -1,6 +1,6 @@
 import { defineCommand } from 'citty'
 
-import { resolveHostPort } from '@/container'
+import { resolveHostPort, resolveTuiToken } from '@/container'
 import { findAgentDir } from '@/init'
 import { requestReload, type ReloadResult } from '@/reload'
 
@@ -15,7 +15,7 @@ export const reload = defineCommand({
     url: {
       type: 'string',
       description:
-        "agent websocket url (defaults to ws://localhost:<host port> discovered from the running container's published port)",
+        "agent websocket url (defaults to ws://127.0.0.1:<host port> discovered from the running container's published port)",
     },
     timeout: {
       type: 'string',
@@ -64,5 +64,8 @@ export const reload = defineCommand({
 async function defaultUrl(): Promise<string> {
   const cwd = findAgentDir(process.cwd()) ?? process.cwd()
   const port = await resolveHostPort({ cwd })
-  return `ws://localhost:${port}`
+  const token = await resolveTuiToken({ cwd })
+  const url = new URL(`ws://127.0.0.1:${port}`)
+  if (token !== null) url.searchParams.set('token', token)
+  return url.toString()
 }

package/src/cli/tui.ts

@@ -1,6 +1,6 @@
 import { defineCommand } from 'citty'
 
-import { resolveHostPort } from '@/container'
+import { resolveHostPort, resolveTuiToken } from '@/container'
 import { findAgentDir } from '@/init'
 import { createTui } from '@/tui'
 
@@ -18,7 +18,7 @@ export const tui = defineCommand({
     url: {
       type: 'string',
       description:
-        "agent websocket url (defaults to ws://localhost:<host port> discovered from the running container's published port)",
+        "agent websocket url (defaults to ws://127.0.0.1:<host port> discovered from the running container's published port)",
     },
   },
   async run({ args }) {
@@ -31,5 +31,8 @@ export const tui = defineCommand({
 async function defaultUrl(): Promise<string> {
   const cwd = findAgentDir(process.cwd()) ?? process.cwd()
   const port = await resolveHostPort({ cwd })
-  return `ws://localhost:${port}`
+  const token = await resolveTuiToken({ cwd })
+  const url = new URL(`ws://127.0.0.1:${port}`)
+  if (token !== null) url.searchParams.set('token', token)
+  return url.toString()
 }

package/src/config/config.ts

@@ -1,4 +1,4 @@
-import { accessSync, constants as fsConstants, readFileSync, statSync } from 'node:fs'
+import { accessSync, constants as fsConstants, readFileSync, statSync, writeFileSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { isAbsolute, join, resolve } from 'node:path'
 
@@ -75,7 +75,7 @@ const dockerfileFeatureSchema = z.union([
 ])
 
 // `default(() => ({}))` paired with field-level defaults is the idiom that
-// makes both `dockerfile: {}` and an omitted `dockerfile` key resolve to the
+// makes both `docker.file: {}` and an omitted `docker.file` key resolve to the
 // SAME fully-populated object. A plain `.default({})` would short-circuit the
 // inner field defaults when the key is omitted, leaving downstream code with
 // `{ append: undefined, tmux: undefined, ... }` and a `lines.length` crash.
@@ -92,17 +92,61 @@ export const dockerfileSchema = dockerfileObjectSchema.default(() => dockerfileO
 export type DockerfileConfig = z.infer<typeof dockerfileSchema>
 export type DockerfileFeatureToggle = z.infer<typeof dockerfileFeatureSchema>
 
+// The `docker` namespace nests Docker-related blocks under one top-level key
+// so future extensions (e.g. `docker.compose`, `docker.buildArgs`) have a home
+// without polluting the root. Today the only inhabitant is `docker.file`,
+// which holds the same shape that used to live at top-level `dockerfile`.
+// One-time migration (see `migrateLegacyConfigShape`) rewrites the old
+// top-level key into the new path on first load.
+export const dockerSchema = z
+  .object({
+    file: dockerfileSchema,
+  })
+  .default(() => ({ file: dockerfileObjectSchema.parse({}) }))
+
+export type DockerConfig = z.infer<typeof dockerSchema>
+
 const gitignoreLineSchema = z.string().refine((line) => !/[\r\n]/.test(line), {
-  message: 'gitignore.append entries must be single gitignore lines; split multiline patterns into array entries',
+  message: 'git.ignore.append entries must be single gitignore lines; split multiline patterns into array entries',
+})
+
+const gitignoreObjectSchema = z.object({
+  append: z.array(gitignoreLineSchema).default([]),
 })
 
-export const gitignoreSchema = z
+export const gitignoreSchema = gitignoreObjectSchema.default(() => gitignoreObjectSchema.parse({}))
+
+export type GitignoreConfig = z.infer<typeof gitignoreSchema>
+
+// Same rationale as `dockerSchema`: a `git` namespace today carries `git.ignore`
+// and leaves room for future siblings (e.g. `git.attributes`). The one-time
+// migration also handles the rename of legacy top-level `gitignore`.
+export const gitSchema = z
   .object({
-    append: z.array(gitignoreLineSchema).default([]),
+    ignore: gitignoreSchema,
   })
-  .default({ append: [] })
+  .default(() => ({ ignore: gitignoreObjectSchema.parse({}) }))
 
-export type GitignoreConfig = z.infer<typeof gitignoreSchema>
+export type GitConfig = z.infer<typeof gitSchema>
+
+const IPV4_CIDR_PATTERN = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})(?:\/(\d{1,2}))?$/
+
+const ipv4CidrSchema = z.string().refine(
+  (value) => {
+    const match = IPV4_CIDR_PATTERN.exec(value)
+    if (!match) return false
+    const octets = [match[1], match[2], match[3], match[4]].map(Number)
+    if (octets.some((n) => !Number.isInteger(n) || n < 0 || n > 255)) return false
+    if (match[5] !== undefined) {
+      const prefix = Number(match[5])
+      if (!Number.isInteger(prefix) || prefix < 0 || prefix > 32) return false
+    }
+    return true
+  },
+  {
+    message: 'network.allow entries must be IPv4 addresses or CIDR ranges (e.g. "10.0.0.0/16", "10.0.0.2")',
+  },
+)
 
 // `blockInternal` is the kill-switch for the container-stage egress filter
 // installed by Dockerfile entrypoint shim: when true, the container is granted
@@ -124,11 +168,38 @@ export type GitignoreConfig = z.infer<typeof gitignoreSchema>
 // field is discoverable in fresh `typeclaw.json` files. Loopback traffic
 // (`-o lo`) is always allowed by the shim, so `bun run dev` and local APIs
 // on `localhost` / `127.0.0.1` are unaffected.
+//
+// `autoAllowResolvers` (default `true`) makes the shim narrowly carve out
+// the container's DNS resolvers — every `nameserver` line in
+// `/etc/resolv.conf` gets a `udp/tcp --dport 53` ACCEPT inserted BEFORE the
+// REJECT rules. This fixes the canonical EC2/GCE/Azure footgun: cloud VPC
+// resolvers live inside RFC1918 (e.g. AWS VPC DNS at `10.0.0.2`), so
+// `blockInternal: true` would otherwise kill every DNS lookup the agent
+// makes. The carve-out is scoped to port 53 only — a compromised agent
+// cannot reach the resolver host on any other port. On a laptop where
+// `/etc/resolv.conf` points at a public resolver (1.1.1.1, 8.8.8.8), the
+// generated ACCEPT rules are no-ops because public IPs are not in the
+// block list to begin with. Opt-out (`false`) is for users who explicitly
+// configure DNS via `.env` (e.g. `DOCKER_DNS=1.1.1.1`) and want a fully
+// closed filter.
+//
+// `allow` is the power-user escape hatch: an explicit list of IPv4 CIDRs
+// or bare IPv4 addresses that punch through the block list wholesale (all
+// ports, all protocols). Use case: VPC-private services the agent must
+// reach by IP — internal APIs, RDS endpoints, VPC interface endpoints for
+// S3/Bedrock. Each entry inserts an unscoped `iptables -A OUTPUT -d <cidr>
+// -j ACCEPT` before the REJECT rules. IPv4 only: the carve-out is for
+// destinations the operator names explicitly, and every cloud VPC we
+// support is IPv4-routable. Validation at parse time rejects non-CIDR
+// strings, IPv6 forms, and out-of-range octets so a typo in
+// `typeclaw.json` surfaces immediately instead of at container boot.
 export const networkSchema = z
   .object({
     blockInternal: z.boolean().default(true),
+    autoAllowResolvers: z.boolean().default(true),
+    allow: z.array(ipv4CidrSchema).default([]),
   })
-  .default({ blockInternal: true })
+  .default({ blockInternal: true, autoAllowResolvers: true, allow: [] })
 
 export type NetworkConfig = z.infer<typeof networkSchema>
 
@@ -152,8 +223,8 @@ export const configSchema = z
     channels: channelsSchema,
     portForward: portForwardSchema,
     network: networkSchema,
-    dockerfile: dockerfileSchema,
-    gitignore: gitignoreSchema,
+    docker: dockerSchema,
+    git: gitSchema,
   })
   .catchall(z.unknown())
 
@@ -243,8 +314,8 @@ export const FIELD_EFFECTS: Record<string, FieldEffect> = {
   channels: 'applied',
   portForward: 'restart-required',
   network: 'restart-required',
-  dockerfile: 'restart-required',
-  gitignore: 'restart-required',
+  'docker.file': 'restart-required',
+  'git.ignore': 'restart-required',
 }
 
 // Stable JSON for value comparison. Fields are small JSON-shaped objects, so
@@ -307,8 +378,8 @@ export function extractPluginConfigs(raw: unknown): Record<string, unknown> {
     'channels',
     'portForward',
     'network',
-    'dockerfile',
-    'gitignore',
+    'docker',
+    'git',
   ])
   const result: Record<string, unknown> = {}
   for (const [key, value] of Object.entries(raw as Record<string, unknown>)) {
@@ -330,7 +401,8 @@ export function loadPluginConfigsSync(cwd: string): Record<string, unknown> {
   } catch {
     return {}
   }
-  return extractPluginConfigs(json)
+  const migrated = migrateLegacyConfigShape(json)
+  return extractPluginConfigs(migrated.json)
 }
 
 export function loadConfigSync(cwd: string): Config {
@@ -349,13 +421,81 @@ export function loadConfigSync(cwd: string): Config {
     throw new Error(`${CONFIG_FILE} is not valid JSON: ${detail}`)
   }
 
-  const result = configSchema.safeParse(json)
+  const migrated = migrateLegacyConfigShape(json)
+  if (migrated.changed) {
+    persistMigratedConfig(cwd, migrated.json)
+  }
+
+  const result = configSchema.safeParse(migrated.json)
   if (!result.success) {
     throw new Error(`${CONFIG_FILE} is invalid: ${formatZodError(result.error)}`)
   }
   return result.data
 }
 
+// One-shot rename of legacy top-level `dockerfile` / `gitignore` keys into the
+// nested `docker.file` / `git.ignore` shape introduced for namespace
+// extensibility (`docker.compose`, `git.attributes`, etc. land here later
+// without a second migration). Called from every entry point that reads
+// `typeclaw.json` so the rest of the pipeline only ever sees the new shape.
+//
+// Precedence when both legacy and new keys coexist: the new shape wins and
+// the legacy key is dropped silently. Two ways this happens in practice:
+//   1. User hand-edited the new shape after auto-migration but forgot to
+//      delete the legacy key.
+//   2. Two `typeclaw start` invocations raced on a stale checkout.
+// Either way, the new shape is the source of truth — losing the legacy
+// duplicate is the right call because it would otherwise be shadowed at
+// parse time anyway (`configSchema` has no `dockerfile`/`gitignore` keys).
+export function migrateLegacyConfigShape(json: unknown): { json: unknown; changed: boolean } {
+  if (typeof json !== 'object' || json === null || Array.isArray(json)) {
+    return { json, changed: false }
+  }
+
+  const obj = json as Record<string, unknown>
+  const hasLegacyDockerfile = 'dockerfile' in obj
+  const hasLegacyGitignore = 'gitignore' in obj
+  if (!hasLegacyDockerfile && !hasLegacyGitignore) {
+    return { json, changed: false }
+  }
+
+  const next: Record<string, unknown> = { ...obj }
+  if (hasLegacyDockerfile) {
+    const legacy = next.dockerfile
+    delete next.dockerfile
+    if (!('docker' in next)) {
+      next.docker = { file: legacy }
+    } else if (isPlainObject(next.docker) && !('file' in next.docker)) {
+      next.docker = { ...next.docker, file: legacy }
+    }
+  }
+  if (hasLegacyGitignore) {
+    const legacy = next.gitignore
+    delete next.gitignore
+    if (!('git' in next)) {
+      next.git = { ignore: legacy }
+    } else if (isPlainObject(next.git) && !('ignore' in next.git)) {
+      next.git = { ...next.git, ignore: legacy }
+    }
+  }
+  return { json: next, changed: true }
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function persistMigratedConfig(cwd: string, json: unknown): void {
+  try {
+    writeFileSync(join(cwd, CONFIG_FILE), `${JSON.stringify(json, null, 2)}\n`)
+  } catch {
+    // Best-effort write-back: the migration is also applied in-memory on every
+    // load, so a read-only filesystem (e.g. snapshotted CI checkout) just
+    // means the rewrite retries next start. Surfacing the error would brick
+    // load paths the user didn't ask to mutate.
+  }
+}
+
 export type ValidateConfigResult = { ok: true } | { ok: false; reason: string }
 
 // Missing file → ok (matches `loadMounts` in src/container/up.ts; `isInitialized`
@@ -384,7 +524,12 @@ export function validateConfig(cwd: string): ValidateConfigResult {
     return { ok: false, reason: `${CONFIG_FILE} is not valid JSON: ${detail}` }
   }
 
-  const result = configSchema.safeParse(json)
+  const migrated = migrateLegacyConfigShape(json)
+  if (migrated.changed) {
+    persistMigratedConfig(cwd, migrated.json)
+  }
+
+  const result = configSchema.safeParse(migrated.json)
   if (!result.success) {
     return { ok: false, reason: `${CONFIG_FILE} is invalid: ${formatZodError(result.error)}` }
   }

package/src/config/index.ts

@@ -1,13 +1,17 @@
 export {
   config,
   configSchema,
+  dockerSchema,
+  dockerfileSchema,
   expandMountPath,
   extractPluginConfigs,
   getConfig,
+  gitSchema,
+  gitignoreSchema,
   loadConfigSync,
   loadPluginConfigsSync,
+  migrateLegacyConfigShape,
   mountSchema,
-  dockerfileSchema,
   portForwardSchema,
   reloadConfig,
   resolveModel,
@@ -16,7 +20,10 @@ export {
   type Config,
   type ConfigChange,
   type ConfigReloadDiff,
+  type DockerConfig,
   type DockerfileConfig,
+  type GitConfig,
+  type GitignoreConfig,
   type Mount,
   type PortForward,
   type ValidateConfigResult,

package/src/container/index.ts

@@ -1,5 +1,5 @@
 export { logs, planLogs, type LogsPlan, type LogsResult } from './logs'
-export { CONTAINER_PORT, findFreePort, resolveHostPort } from './port'
+export { CONTAINER_PORT, TUI_TOKEN_LABEL, findFreePort, resolveHostPort, resolveTuiToken } from './port'
 export { planShell, shell, type ShellPlan, type ShellResult } from './shell'
 export { status, type ContainerStatus, type StatusOptions } from './status'
 export {
@@ -17,6 +17,8 @@ export {
 } from './shared'
 export {
   planStart,
+  refreshDockerfile,
+  refreshGitignore,
   start,
   type HostDaemonStatus,
   type PlanStartOptions,

package/src/container/port.ts

@@ -13,6 +13,7 @@ import { containerNameFromCwd, defaultDockerExec, type DockerExec } from './shar
 // works: containers started before this change used `-p 8973:8973`, and after
 // the upgrade `docker port <name> 8973/tcp` still resolves correctly.
 export const CONTAINER_PORT = 8973
+export const TUI_TOKEN_LABEL = 'dev.typeclaw.tui-token'
 
 // Asks the kernel for a free TCP port. When `preferred` is supplied, tries
 // that port first; if it's already bound, falls back to a kernel-assigned
@@ -102,6 +103,15 @@ export async function resolveHostPort(options: ResolveHostPortOptions): Promise<
   return loadConfigSync(options.cwd).port
 }
 
+export async function resolveTuiToken(options: { cwd: string; exec?: DockerExec }): Promise<string | null> {
+  const exec = options.exec ?? defaultDockerExec
+  const containerName = containerNameFromCwd(options.cwd)
+  const result = await exec(['inspect', '--format', `{{ index .Config.Labels "${TUI_TOKEN_LABEL}" }}`, containerName])
+  if (result.exitCode !== 0) return null
+  const token = result.stdout.trim()
+  return token.length > 0 && token !== '<no value>' ? token : null
+}
+
 async function queryDockerHostPort(exec: DockerExec, containerName: string): Promise<number | null> {
   const result = await exec(['port', containerName, `${CONTAINER_PORT}/tcp`])
   if (result.exitCode !== 0) return null