typeclaw 0.1.4 → 0.1.6

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'
 
@@ -6,6 +6,8 @@ import type { Model } from '@mariozechner/pi-ai'
 import { z } from 'zod'
 
 import { channelsSchema } from '@/channels/schema'
+import { commitSystemFileSync } from '@/git/system-commit'
+import { rolesConfigSchema } from '@/permissions/schema'
 
 import {
   DEFAULT_MODEL_REF,
@@ -75,7 +77,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 +94,42 @@ 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}))?$/
 
@@ -178,11 +205,41 @@ export const networkSchema = z
 
 export type NetworkConfig = z.infer<typeof networkSchema>
 
+// `models` is a map from profile name to a single curated model ref. The
+// `default` profile is mandatory; every other profile is optional and falls
+// back to `default` at resolution time (see `resolveProfile`).
+//
+// Profile names are open strings; the runtime recognizes a handful of
+// well-known names by convention (`default`, `fast`, `deep`, `vision`) but
+// any string is valid. Subagents may declare a static profile preference;
+// callers may override per-spawn. Unknown profile names resolve to `default`
+// with a one-time warning at session construction.
+//
+// The pre-multi-model schema had a single `model: KnownModelRef` at the top
+// level. `migrateLegacyConfigShape` rewrites that to `models: { default: ... }`
+// on first load (and writes the result back to disk + commits via
+// `persistMigratedConfig`), so every downstream consumer sees the new shape.
+export const modelsSchema = z
+  .record(z.string().min(1), z.enum(knownModelRefs))
+  .refine((m) => 'default' in m, { message: 'models.default is required' })
+
+// Zod's `z.record(..., refine)` doesn't refine the inferred type — the inferred
+// shape is `Record<string, KnownModelRef>` where every access is `T | undefined`.
+// The runtime guarantee (the `refine` above) is that `default` is present, so
+// we narrow the type here. Every consumer (auth.ts, agent/index.ts,
+// resolveProfile) reads `models.default` on the hot path; without this
+// narrowing they all have to assert or `?? throw`, which is noise around an
+// invariant the schema already enforces.
+export type Models = Record<string, KnownModelRef> & { default: KnownModelRef }
+
 export const configSchema = z
   .object({
     $schema: z.string().optional(),
     port: z.number().int().min(1).max(65535).default(DEFAULT_PORT),
-    model: z.enum(knownModelRefs).default(DEFAULT_MODEL_REF),
+    // `default(() => ...)` ensures every parsed config has at least
+    // `models.default`. Direct `.default({ default: ... })` would short-circuit
+    // the refinement, so we lean on the lazy thunk form.
+    models: modelsSchema.default(() => ({ default: DEFAULT_MODEL_REF })) as unknown as z.ZodType<Models>,
     // Defaults to `[]` so the field can be omitted from `typeclaw.json` (no
     // host paths exposed) without failing the whole config load. `typeclaw
     // init` omits this field so users don't see noise for the empty case.
@@ -198,8 +255,9 @@ export const configSchema = z
     channels: channelsSchema,
     portForward: portForwardSchema,
     network: networkSchema,
-    dockerfile: dockerfileSchema,
-    gitignore: gitignoreSchema,
+    docker: dockerSchema,
+    git: gitSchema,
+    roles: rolesConfigSchema.optional(),
   })
   .catchall(z.unknown())
 
@@ -213,6 +271,28 @@ export function resolveModel(ref: KnownModelRef): Model<'openai-completions'> |
   return KNOWN_PROVIDERS[providerId].models[modelId as never]
 }
 
+// Resolves a profile name (e.g. `fast`, `deep`, `vision`) to a concrete model
+// ref. Unknown profiles fall back to `default` so callers can pass through
+// arbitrary subagent-declared or user-overridden strings without crashing.
+// Returns the resolved ref plus whether it came from the requested profile or
+// from the `default` fallback, so the caller can warn once per session
+// instead of every prompt.
+export type ResolvedProfile = {
+  ref: KnownModelRef
+  profile: string
+  fellBackToDefault: boolean
+}
+
+export function resolveProfile(models: Models, name: string | undefined): ResolvedProfile {
+  const requested = name ?? 'default'
+  const ref = models[requested]
+  if (ref !== undefined) {
+    return { ref, profile: requested, fellBackToDefault: false }
+  }
+  const fallback = models.default
+  return { ref: fallback, profile: 'default', fellBackToDefault: true }
+}
+
 // Resolves a mount's `path` field to an absolute host path, mirroring shell
 // expansion rules: `~`/`~/...` → home dir, relative → resolved against `cwd`,
 // absolute → unchanged. Single source of truth so validation and Docker arg
@@ -281,7 +361,7 @@ export type FieldEffect = 'applied' | 'restart-required' | 'ignored'
 
 export const FIELD_EFFECTS: Record<string, FieldEffect> = {
   $schema: 'ignored',
-  model: 'applied',
+  models: 'applied',
   port: 'restart-required',
   mounts: 'restart-required',
   plugins: 'restart-required',
@@ -289,8 +369,18 @@ 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',
+  // Split: `match` lists are reload-safe (typeclaw role claim, hand-edits
+  // adding/removing match rules apply without a container restart);
+  // `permissions` lists are restart-required (changing what a role can DO
+  // is a bigger deal than changing WHO fills it, and several consumers —
+  // plugin contexts, the security plugin guards — capture the permissions
+  // contract at boot). The diff machinery in diffConfig() understands
+  // `roles.match` and `roles.permissions` as virtual paths and compares
+  // the corresponding projections of the whole `roles` block.
+  'roles.match': 'applied',
+  'roles.permissions': 'restart-required',
 }
 
 // Stable JSON for value comparison. Fields are small JSON-shaped objects, so
@@ -329,6 +419,8 @@ function diffConfig(before: Config, after: Config): ConfigReloadDiff {
 }
 
 function readPath(obj: unknown, path: string): unknown {
+  if (path === 'roles.match') return projectRoles(obj, 'match')
+  if (path === 'roles.permissions') return projectRoles(obj, 'permissions')
   let cur: unknown = obj
   for (const part of path.split('.')) {
     if (cur === null || cur === undefined) return undefined
@@ -337,6 +429,19 @@ function readPath(obj: unknown, path: string): unknown {
   return cur
 }
 
+function projectRoles(obj: unknown, field: 'match' | 'permissions'): unknown {
+  if (typeof obj !== 'object' || obj === null) return undefined
+  const roles = (obj as Record<string, unknown>).roles
+  if (typeof roles !== 'object' || roles === null) return undefined
+  const projection: Record<string, unknown> = {}
+  for (const [roleName, roleVal] of Object.entries(roles as Record<string, unknown>)) {
+    if (typeof roleVal !== 'object' || roleVal === null) continue
+    const val = (roleVal as Record<string, unknown>)[field]
+    if (val !== undefined) projection[roleName] = val
+  }
+  return projection
+}
+
 // Plugin configs live at the top level of typeclaw.json keyed by plugin name
 // (e.g. "standup-log": { ... }). They are preserved by configSchema.catchall(z.unknown())
 // because the schema does not predeclare these keys. This helper returns the
@@ -347,14 +452,17 @@ export function extractPluginConfigs(raw: unknown): Record<string, unknown> {
   const known = new Set([
     '$schema',
     'port',
-    'model',
+    'models',
     'mounts',
     'plugins',
+    'alias',
     'channels',
     'portForward',
     'network',
-    'dockerfile',
-    'gitignore',
+    'docker',
+    'git',
+    'roles',
+    'permissions',
   ])
   const result: Record<string, unknown> = {}
   for (const [key, value] of Object.entries(raw as Record<string, unknown>)) {
@@ -376,7 +484,11 @@ export function loadPluginConfigsSync(cwd: string): Record<string, unknown> {
   } catch {
     return {}
   }
-  return extractPluginConfigs(json)
+  const migrated = migrateLegacyConfigShape(json)
+  if (migrated.changed) {
+    persistMigratedConfig(cwd, migrated.json, migrated.applied)
+  }
+  return extractPluginConfigs(migrated.json)
 }
 
 export function loadConfigSync(cwd: string): Config {
@@ -395,13 +507,368 @@ 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, migrated.applied)
+  }
+
+  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).
+//
+// The returned `applied` array names each migration step that fired, so
+// callers in `typeclaw start` can build a meaningful git commit message
+// instead of a generic "migrate legacy shape" subject. `changed` is the
+// boolean equivalent of `applied.length > 0` and is preserved for back-compat
+// with the many call sites that only care whether ANY rewrite happened.
+export type MigrationStep =
+  | { kind: 'dockerfile-to-docker-file' }
+  | { kind: 'gitignore-to-git-ignore' }
+  | { kind: 'channels-allow-to-roles-member-match'; rules: string[]; dropped: string[] }
+  | { kind: 'strip-permissions-gate-channel-respond' }
+  | { kind: 'model-to-models'; ref: string }
+  | { kind: 'drop-stale-model'; ref: string }
+
+export type MigrationResult = { json: unknown; changed: boolean; applied: MigrationStep[] }
+
+export function migrateLegacyConfigShape(json: unknown): MigrationResult {
+  if (typeof json !== 'object' || json === null || Array.isArray(json)) {
+    return { json, changed: false, applied: [] }
+  }
+
+  const obj = json as Record<string, unknown>
+  const hasLegacyDockerfile = 'dockerfile' in obj
+  const hasLegacyGitignore = 'gitignore' in obj
+  const channelsAllowMigration = collectChannelsAllowMigration(obj)
+  const hasLegacyGateChannelRespond = isPlainObject(obj.permissions) && 'gateChannelRespond' in obj.permissions
+  // The pre-multi-model schema had a top-level `model: KnownModelRef` and no
+  // `models` key. Detecting the legacy shape requires both: `model` present
+  // AND `models` absent. If both coexist (user hand-edited after auto-migrate
+  // but didn't delete the legacy key), `models` wins and `model` is dropped
+  // silently — same precedence rule as the dockerfile/gitignore migrations.
+  const hasLegacyModel = 'model' in obj && !('models' in obj) && typeof obj.model === 'string'
+  const hasStaleModelAlongsideModels = 'model' in obj && 'models' in obj
+  if (
+    !hasLegacyDockerfile &&
+    !hasLegacyGitignore &&
+    !channelsAllowMigration.found &&
+    !hasLegacyGateChannelRespond &&
+    !hasLegacyModel &&
+    !hasStaleModelAlongsideModels
+  ) {
+    return { json, changed: false, applied: [] }
+  }
+
+  const applied: MigrationStep[] = []
+  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 }
+    }
+    applied.push({ kind: 'dockerfile-to-docker-file' })
+  }
+  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 }
+    }
+    applied.push({ kind: 'gitignore-to-git-ignore' })
+  }
+  if (channelsAllowMigration.found) {
+    applyChannelsAllowMigration(next, channelsAllowMigration)
+    applied.push({
+      kind: 'channels-allow-to-roles-member-match',
+      rules: channelsAllowMigration.rules,
+      dropped: channelsAllowMigration.warnings,
+    })
+  }
+  if (hasLegacyGateChannelRespond) {
+    const perms = { ...(next.permissions as Record<string, unknown>) }
+    delete perms.gateChannelRespond
+    if (Object.keys(perms).length === 0) {
+      delete next.permissions
+    } else {
+      next.permissions = perms
+    }
+    applied.push({ kind: 'strip-permissions-gate-channel-respond' })
+  }
+  if (hasLegacyModel) {
+    const ref = next.model as string
+    delete next.model
+    next.models = { default: ref }
+    applied.push({ kind: 'model-to-models', ref })
+  } else if (hasStaleModelAlongsideModels) {
+    // `models` wins (per the same precedence rule as dockerfile/gitignore), but
+    // the drop is still a tracked migration step so the disk rewrite gets a
+    // commit instead of silently dirtying the worktree. Without this, the
+    // file would be rewritten by persistMigratedConfig and no commit would
+    // fire (buildConfigMigrationCommitMessage returns null for empty applied
+    // lists), contradicting the invariant in persistMigratedConfig's comment.
+    const ref = typeof next.model === 'string' ? next.model : ''
+    delete next.model
+    applied.push({ kind: 'drop-stale-model', ref })
+  }
+  return { json: next, changed: true, applied }
+}
+
+// Builds a meaningful one-line git commit subject for a typeclaw.json
+// migration. Single-step migrations get a specific subject; multi-step ones
+// fall back to a stable summary subject with the count. The body (after the
+// blank line) enumerates each step so `git log -p typeclaw.json` is an
+// auditable trail of what legacy shapes the agent has graduated from.
+//
+// Returns null when no steps were applied — callers should not commit in
+// that case. Keeping the null branch here (vs an empty string) makes the
+// "nothing happened" case impossible to misuse at the call site.
+export function buildConfigMigrationCommitMessage(applied: readonly MigrationStep[]): string | null {
+  const first = applied[0]
+  if (first === undefined) return null
+
+  const subject =
+    applied.length === 1
+      ? `typeclaw.json: ${shortStepLabel(first)}`
+      : `typeclaw.json: migrate legacy shape (${applied.length} steps)`
+
+  const bodyLines: string[] = applied.map((step) => `- ${describeStep(step)}`)
+
+  // Surface dropped rules in the commit body so a user inspecting `git log -p`
+  // sees exactly which legacy entries had to be hand-re-added (the lossy
+  // `channel:<id>` case). Without this, the silent-drop is invisible after
+  // the fact.
+  for (const step of applied) {
+    if (step.kind === 'channels-allow-to-roles-member-match' && step.dropped.length > 0) {
+      for (const warning of step.dropped) {
+        bodyLines.push(`  warning: ${warning}`)
+      }
+    }
+  }
+
+  return `${subject}\n\n${bodyLines.join('\n')}\n`
+}
+
+function shortStepLabel(step: MigrationStep): string {
+  switch (step.kind) {
+    case 'dockerfile-to-docker-file':
+      return 'lift dockerfile → docker.file'
+    case 'gitignore-to-git-ignore':
+      return 'lift gitignore → git.ignore'
+    case 'channels-allow-to-roles-member-match':
+      return 'lift channels.<adapter>.allow[] → roles.member.match[]'
+    case 'strip-permissions-gate-channel-respond':
+      return 'drop permissions.gateChannelRespond'
+    case 'model-to-models':
+      return 'lift model → models.default'
+    case 'drop-stale-model':
+      return 'drop stale legacy model alongside models'
+  }
+}
+
+function describeStep(step: MigrationStep): string {
+  switch (step.kind) {
+    case 'dockerfile-to-docker-file':
+      return 'lift top-level dockerfile into docker.file'
+    case 'gitignore-to-git-ignore':
+      return 'lift top-level gitignore into git.ignore'
+    case 'channels-allow-to-roles-member-match': {
+      if (step.rules.length === 0) {
+        return 'strip channels.<adapter>.allow[] (no translatable rules)'
+      }
+      return `lift channels.<adapter>.allow[] → roles.member.match[]: ${step.rules.join(', ')}`
+    }
+    case 'strip-permissions-gate-channel-respond':
+      return 'drop permissions.gateChannelRespond (removed key)'
+    case 'model-to-models':
+      return `lift top-level model into models.default: ${step.ref}`
+    case 'drop-stale-model':
+      return step.ref !== ''
+        ? `drop stale top-level model (${step.ref}) — models block takes precedence`
+        : 'drop stale top-level model — models block takes precedence'
+  }
+}
+
+// Channels.<adapter>.allow[] → roles.member.match[] migration.
+//
+// Phase 3 removes the per-adapter allow-list and unifies wake-up gating
+// through `roles.member.match[]` + the `channel.respond` permission. This
+// helper translates legacy `allow` entries into canonical match-rule DSL
+// strings and appends them (deduplicated, preserving declaration order)
+// to `roles.member.match[]`. The `allow` field is then stripped from each
+// adapter block; the block survives — only the field is gone.
+//
+// `channel:<id>` rules cannot round-trip (the DSL forbids
+// wildcard-workspace + specific-chat) and are dropped with a warning. All
+// other shapes translate losslessly per the table in match-rule.ts.
+type ChannelsAllowMigration = {
+  found: boolean
+  rules: string[]
+  warnings: string[]
+}
+
+function collectChannelsAllowMigration(obj: Record<string, unknown>): ChannelsAllowMigration {
+  const out: ChannelsAllowMigration = { found: false, rules: [], warnings: [] }
+  const channels = obj.channels
+  if (!isPlainObject(channels)) return out
+  for (const [adapter, value] of Object.entries(channels)) {
+    if (!isPlainObject(value)) continue
+    if (!('allow' in value)) continue
+    out.found = true
+    const allow = value.allow
+    if (!Array.isArray(allow)) continue
+    for (const entry of allow) {
+      if (typeof entry !== 'string') continue
+      const translated = translateLegacyAllowRule(entry)
+      if (translated.kind === 'rule') {
+        out.rules.push(translated.value)
+      } else {
+        out.warnings.push(`channels.${adapter}.allow[]: dropped '${entry}' (${translated.reason})`)
+      }
+    }
+  }
+  return out
+}
+
+function applyChannelsAllowMigration(next: Record<string, unknown>, migration: ChannelsAllowMigration): void {
+  const channels = next.channels
+  if (isPlainObject(channels)) {
+    const updated: Record<string, unknown> = {}
+    for (const [adapter, value] of Object.entries(channels)) {
+      if (isPlainObject(value) && 'allow' in value) {
+        const { allow: _allow, ...rest } = value
+        updated[adapter] = rest
+      } else {
+        updated[adapter] = value
+      }
+    }
+    next.channels = updated
+  }
+
+  if (migration.rules.length === 0) {
+    for (const warning of migration.warnings) {
+      console.warn(`[config] ${warning}`)
+    }
+    return
+  }
+
+  const roles = isPlainObject(next.roles) ? { ...next.roles } : {}
+  const member = isPlainObject(roles.member) ? { ...roles.member } : {}
+  const existingMatch = Array.isArray(member.match)
+    ? (member.match as unknown[]).filter((m) => typeof m === 'string')
+    : []
+  const seen = new Set<string>(existingMatch as string[])
+  const merged = [...(existingMatch as string[])]
+  for (const rule of migration.rules) {
+    if (!seen.has(rule)) {
+      seen.add(rule)
+      merged.push(rule)
+    }
+  }
+  member.match = merged
+  roles.member = member
+  next.roles = roles
+
+  console.warn(`[config] migrated channels.<adapter>.allow[] -> roles.member.match[]: ${migration.rules.join(', ')}`)
+  for (const warning of migration.warnings) {
+    console.warn(`[config] ${warning}`)
+  }
+}
+
+type TranslatedRule = { kind: 'rule'; value: string } | { kind: 'drop'; reason: string }
+
+function translateLegacyAllowRule(rule: string): TranslatedRule {
+  // Already canonical / cross-platform.
+  if (rule === '*') return { kind: 'rule', value: '*' }
+  if (rule.startsWith('kakao:')) return { kind: 'rule', value: rule }
+
+  // Discord: guild → discord, dm → discord:dm.
+  if (rule === 'guild:*') return { kind: 'rule', value: 'discord:*' }
+  if (rule.startsWith('guild:')) return { kind: 'rule', value: `discord:${rule.slice('guild:'.length)}` }
+  if (rule === 'dm:*') return { kind: 'rule', value: 'discord:dm/*' }
+  if (rule.startsWith('dm:')) return { kind: 'rule', value: `discord:dm/${rule.slice('dm:'.length)}` }
+
+  // Slack: team → slack, im → slack:dm.
+  if (rule === 'team:*') return { kind: 'rule', value: 'slack:*' }
+  if (rule.startsWith('team:')) return { kind: 'rule', value: `slack:${rule.slice('team:'.length)}` }
+  if (rule === 'im:*') return { kind: 'rule', value: 'slack:dm/*' }
+  if (rule.startsWith('im:')) return { kind: 'rule', value: `slack:dm/${rule.slice('im:'.length)}` }
+
+  // Telegram: tg → telegram.
+  if (rule === 'tg:*') return { kind: 'rule', value: 'telegram:*' }
+  if (rule.startsWith('tg:')) return { kind: 'rule', value: `telegram:${rule.slice('tg:'.length)}` }
+
+  // `channel:<id>` had no workspace; canonical DSL rejects wildcard
+  // workspace + specific chat. Drop with a warning so the operator knows
+  // to re-add the rule explicitly with a workspace coordinate.
+  if (rule.startsWith('channel:')) {
+    return {
+      kind: 'drop',
+      reason:
+        'channel:<id> rules require an explicit workspace under the new DSL; re-add as discord:<guild>/<id> or slack:<team>/<id>',
+    }
+  }
+
+  return { kind: 'drop', reason: `unrecognized legacy allow shape '${rule}'` }
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function persistMigratedConfig(cwd: string, json: unknown, applied: readonly MigrationStep[]): 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. Bail before the commit step
+    // too — without the write there's nothing to commit.
+    return
+  }
+
+  // Pair the disk rewrite with a git commit so the agent folder is never
+  // silently dirty after a legacy-shape migration. typeclaw.json is in
+  // git's "tracked" category (unlike Dockerfile, which is regenerated on
+  // every start and intentionally gitignored), so an uncommitted rewrite
+  // gets mixed into unrelated commits the moment any other tool touches
+  // the repo. commitSystemFileSync no-ops on non-git folders, missing
+  // Bun, and clean files, so canonical-shape reads pay zero cost.
+  //
+  // Called from every entry point that reads typeclaw.json (host CLI,
+  // hostd daemon, container runtime) so the commit follows the rewrite
+  // wherever it happens — not only from `typeclaw start`. The earlier
+  // design that committed only in start() missed the long-running hostd
+  // daemon, doctor, tui, reload, and compose paths.
+  const message = buildConfigMigrationCommitMessage(applied)
+  if (message !== null) {
+    commitSystemFileSync(cwd, CONFIG_FILE, message)
+  }
+}
+
 export type ValidateConfigResult = { ok: true } | { ok: false; reason: string }
 
 // Missing file → ok (matches `loadMounts` in src/container/up.ts; `isInitialized`
@@ -430,7 +897,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, migrated.applied)
+  }
+
+  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,24 +1,38 @@
 export {
+  buildConfigMigrationCommitMessage,
   config,
   configSchema,
+  dockerSchema,
+  dockerfileSchema,
   expandMountPath,
   extractPluginConfigs,
   getConfig,
+  gitSchema,
+  gitignoreSchema,
   loadConfigSync,
   loadPluginConfigsSync,
+  migrateLegacyConfigShape,
+  modelsSchema,
   mountSchema,
-  dockerfileSchema,
   portForwardSchema,
   reloadConfig,
   resolveModel,
+  resolveProfile,
   validateConfig,
   validateMount,
   type Config,
   type ConfigChange,
   type ConfigReloadDiff,
+  type DockerConfig,
   type DockerfileConfig,
+  type GitConfig,
+  type GitignoreConfig,
+  type MigrationResult,
+  type MigrationStep,
+  type Models,
   type Mount,
   type PortForward,
+  type ResolvedProfile,
   type ValidateConfigResult,
 } from './config'
 export { type KnownModelRef, type KnownProviderId } from './providers'