typeclaw 0.1.5 → 0.1.6

package/src/container/start.ts

@@ -3,7 +3,8 @@ import { existsSync } from 'node:fs'
 import { readFile, writeFile } from 'node:fs/promises'
 import { isAbsolute, join, resolve } from 'node:path'
 
-import { configSchema, expandMountPath, migrateLegacyConfigShape, type Config } from '@/config'
+import { expandMountPath, loadConfigSync, type Config } from '@/config'
+import { commitSystemFile as commitSystemFileShared } from '@/git/system-commit'
 import { send as sendToDaemon } from '@/hostd/client'
 import type { HttpInfoResult } from '@/hostd/protocol'
 import { ensureDaemon } from '@/hostd/spawn'
@@ -30,7 +31,6 @@ import {
   defaultDockerExec,
   type DockerExec,
   type DockerExecResult,
-  getBun,
   imageTagFromCwd,
   isContainerNameConflict,
   sanitizeDockerStderr,
@@ -41,7 +41,6 @@ import { buildCrashReason, createVerifyRunning, type VerifyRunningFn } from './v
 const PACKAGE_FILE = 'package.json'
 const BUN_LOCK_FILE = 'bun.lock'
 const DEPENDENCY_FILES = [PACKAGE_FILE, BUN_LOCK_FILE] as const
-const CONFIG_FILE = 'typeclaw.json'
 const ENV_FILE = '.env'
 const COMPOSE_PROJECT = 'typeclaw'
 const CONTAINER_HOSTD_HOST = 'host.docker.internal'
@@ -179,6 +178,14 @@ export async function start({
     // one-shot and idempotent — once `workspaces` is set, refreshPackageJson
     // is a no-op, so users who never edit their agent folder pay zero cost on
     // subsequent starts and users who customized `workspaces` are not clobbered.
+    //
+    // typeclaw.json migration is NOT triggered explicitly here — it follows
+    // the disk rewrite via persistMigratedConfig (src/config/config.ts), so
+    // every entry point that reads typeclaw.json (host CLI, hostd daemon,
+    // container runtime) also produces the commit. start() therefore only
+    // needs to orchestrate the .gitignore / package.json side; the
+    // refreshGitignore call below reads typeclaw.json and will incidentally
+    // trigger the migration commit if the file was legacy.
     await refreshGitignore(cwd)
     const pkgRefresh = await refreshPackageJson(cwd)
     await commitSystemFile(cwd, GITIGNORE_FILE, 'Update .gitignore')
@@ -237,7 +244,7 @@ export async function start({
     // line resolves against the agent's installed node_modules/typeclaw —
     // ensures the base image's CLI version matches the runtime the
     // container will actually load.
-    await refreshDockerfile(cwd)
+    const dockerfileRefresh = await refreshDockerfile(cwd)
     await migrateKakaotalkCredentials(cwd)
 
     if (state.exists) {
@@ -308,7 +315,7 @@ export async function start({
       cwd,
       hostPort,
       imageExists: imageExisted,
-      forceBuild,
+      forceBuild: forceBuild || dockerfileRefresh.changed,
       hostdControl,
       publishHost,
       tuiToken,
@@ -531,12 +538,20 @@ async function resolvePublishHost(exec: DockerExec): Promise<string> {
   return '127.0.0.1'
 }
 
-export async function refreshDockerfile(cwd: string): Promise<void> {
+// The `changed` return drives auto-rebuild in start() so users don't need to
+// pass `--build` after a CLI upgrade or after editing `typeclaw.json#docker.*`.
+// Comparing rendered contents (rather than tracking a separate state file) is
+// the cheapest correct signal: the build context for `docker build` is the
+// Dockerfile itself, so equal contents definitionally produce an equivalent
+// image.
+export async function refreshDockerfile(cwd: string): Promise<{ changed: boolean }> {
   const cfg = await loadTypeclawConfig(cwd)
-  await writeFile(
-    join(cwd, DOCKERFILE),
-    buildDockerfile(cfg.docker.file, { baseImageVersion: resolveBaseImageVersion(cwd) }),
-  )
+  const next = buildDockerfile(cfg.docker.file, { baseImageVersion: resolveBaseImageVersion(cwd) })
+  const path = join(cwd, DOCKERFILE)
+  const prev = await readFile(path, 'utf8').catch(() => null)
+  if (prev === next) return { changed: false }
+  await writeFile(path, next)
+  return { changed: true }
 }
 
 export async function refreshGitignore(cwd: string): Promise<void> {
@@ -544,43 +559,13 @@ export async function refreshGitignore(cwd: string): Promise<void> {
   await writeFile(join(cwd, GITIGNORE_FILE), buildGitignore(cfg.git.ignore))
 }
 
-// Commits TypeClaw-owned system file(s) if any are dirty in git. Skips silently
-// when the agent folder is not a git repo, when bun is unavailable, or when
-// every named file is clean (no changes since last commit). Uses the user's
-// global git config for authorship — TypeClaw does not impersonate the user
-// here. Accepts a single file or an array; the array form produces a single
-// atomic commit covering all listed paths, used for migrations that touch
-// multiple files together (e.g. enabling bun workspaces writes both
-// package.json and packages/.gitkeep in one commit).
-export async function commitSystemFile(cwd: string, file: string | readonly string[], message: string): Promise<void> {
-  const files = typeof file === 'string' ? [file] : file
-  if (files.length === 0) return
-
-  const bun = getBun()
-  if (!bun) return
-  if (!existsSync(join(cwd, '.git'))) return
-
-  const status = bun.spawn({
-    cmd: ['git', 'status', '--porcelain', '--', ...files],
-    cwd,
-    stdout: 'pipe',
-    stderr: 'pipe',
-  })
-  if ((await status.exited) !== 0) return
-  const dirty = (await new Response(status.stdout).text()).trim().length > 0
-  if (!dirty) return
-
-  const add = bun.spawn({ cmd: ['git', 'add', '--', ...files], cwd, stdout: 'pipe', stderr: 'pipe' })
-  if ((await add.exited) !== 0) return
-
-  const commit = bun.spawn({
-    cmd: ['git', 'commit', '-m', message, '--only', '--', ...files],
-    cwd,
-    stdout: 'pipe',
-    stderr: 'pipe',
-  })
-  await commit.exited
-}
+// Re-exported from src/git/system-commit.ts so existing call sites
+// (refreshGitignore wiring, doctor/commit.ts comment references, test
+// imports) keep working under the original name. New code should import
+// directly from @/git/system-commit instead. The sync sibling lives
+// alongside in that module and is used by persistMigratedConfig to pair
+// the migration write with a commit on every read path, not only here.
+export const commitSystemFile = commitSystemFileShared
 
 async function imageExists(exec: DockerExec, tag: string): Promise<boolean> {
   const result = await exec(['image', 'inspect', tag])
@@ -730,7 +715,13 @@ async function detectDevSource(cwd: string): Promise<string | null> {
 // invalid mount entry — must surface so the user sees they configured a mount
 // that won't be applied.
 async function loadTypeclawConfig(cwd: string): Promise<Config> {
-  return configSchema.parse(await loadConfigJson(cwd))
+  // Goes through the shared loadConfigSync so the legacy-shape migration
+  // (and its paired git commit via persistMigratedConfig) follows every
+  // start() read path — refreshGitignore, the docker run argv builder, and
+  // the daemon-register payload all eventually land here. The function is
+  // declared async only to preserve the existing await sites; the work is
+  // synchronous under the hood.
+  return loadConfigSync(cwd)
 }
 
 async function registerWithDaemon({
@@ -777,16 +768,6 @@ async function useCurrentHostDaemon(): Promise<{ ok: true; httpPort: number } |
   return { ok: true, httpPort: result.port }
 }
 
-async function loadConfigJson(cwd: string): Promise<unknown> {
-  let raw: string
-  try {
-    raw = await readFile(join(cwd, CONFIG_FILE), 'utf8')
-  } catch {
-    return {}
-  }
-  return migrateLegacyConfigShape(JSON.parse(raw)).json
-}
-
 type PreparedHostDaemonStatus =
   | { state: 'registered'; control: HostDaemonControl }
   | { state: 'unavailable'; reason: string }

package/src/cron/consumer.ts

@@ -100,8 +100,24 @@ async function runPrompt(
   stream: Stream,
 ): Promise<void> {
   if (job.subagent !== undefined) {
+    // Propagate the cron job's role and origin into the spawned subagent.
+    // Without this, every cron-triggered subagent (e.g. memory dreaming)
+    // resolves to `guest` because the new-session consumer reads provenance
+    // off the stream target rather than rebuilding it. Encode the parent
+    // origin as JSON since StreamTarget is a flat-string shape.
+    const parentOrigin: SessionOrigin = {
+      kind: 'cron',
+      jobId: job.id,
+      jobKind: 'prompt',
+      ...(job.scheduledByRole !== undefined ? { scheduledByRole: job.scheduledByRole } : {}),
+    }
     stream.publish({
-      target: { kind: 'new-session', subagent: job.subagent },
+      target: {
+        kind: 'new-session',
+        subagent: job.subagent,
+        ...(job.scheduledByRole !== undefined ? { spawnedByRole: job.scheduledByRole } : {}),
+        spawnedByOriginJson: JSON.stringify(parentOrigin),
+      },
       payload: job.payload,
     })
     return
@@ -131,11 +147,15 @@ async function runPrompt(
         sessionId: session.sessionId,
         parentTranscriptPath: session.getTranscriptPath?.(),
         idleMs: 0,
+        ...(session.origin !== undefined ? { origin: session.origin } : {}),
       })
     }
   } finally {
     if (session.hooks && session.sessionId !== undefined) {
-      await session.hooks.runSessionEnd({ sessionId: session.sessionId })
+      await session.hooks.runSessionEnd({
+        sessionId: session.sessionId,
+        ...(session.origin !== undefined ? { origin: session.origin } : {}),
+      })
     }
     session.dispose?.()
   }

package/src/cron/index.ts

@@ -1,10 +1,17 @@
 import { existsSync } from 'node:fs'
-import { readFile } from 'node:fs/promises'
+import { readFile, writeFile } from 'node:fs/promises'
 import { join } from 'node:path'
 
 import type { SubagentRegistry } from '@/agent/subagents'
+import { commitSystemFile } from '@/git/system-commit'
 
-import { type CronFile, parseCronFile } from './schema'
+import {
+  buildCronMigrationCommitMessage,
+  type CronFile,
+  type CronMigrationStep,
+  migrateLegacyCronShape,
+  parseCronFile,
+} from './schema'
 
 export { createCronReloadable, type CreateCronReloadableOptions } from './reloadable'
 export {
@@ -15,7 +22,18 @@ export {
   type CronSession,
 } from './consumer'
 export { createScheduler, type JobDiff, type Scheduler, type SchedulerLogger } from './scheduler'
-export { cronFileSchema, cronJobSchema, type CronFile, type CronJob, type ExecJob, type PromptJob } from './schema'
+export {
+  buildCronMigrationCommitMessage,
+  cronFileSchema,
+  cronJobSchema,
+  type CronFile,
+  type CronJob,
+  type CronMigrationResult,
+  type CronMigrationStep,
+  type ExecJob,
+  migrateLegacyCronShape,
+  type PromptJob,
+} from './schema'
 
 const CRON_FILE = 'cron.json'
 
@@ -43,12 +61,35 @@ export async function loadCron(agentDir: string, options: LoadCronOptions = {}):
     return { ok: false, reason: `cron.json is not valid JSON: ${errorMessage(err)}` }
   }
 
-  const result = parseCronFile(parsed, options.subagents !== undefined ? { subagents: options.subagents } : {})
+  const migrated = migrateLegacyCronShape(parsed)
+  if (migrated.changed) {
+    await persistMigratedCron(path, migrated.json, agentDir, migrated.applied)
+  }
+
+  const result = parseCronFile(migrated.json, options.subagents !== undefined ? { subagents: options.subagents } : {})
   if (!result.ok) return { ok: false, reason: result.reason }
 
   return { ok: true, file: result.file }
 }
 
+async function persistMigratedCron(
+  path: string,
+  json: unknown,
+  agentDir: string,
+  applied: readonly CronMigrationStep[],
+): Promise<void> {
+  try {
+    await writeFile(path, `${JSON.stringify(json, null, 2)}\n`)
+  } catch {
+    return
+  }
+
+  const message = buildCronMigrationCommitMessage(applied)
+  if (message !== null) {
+    await commitSystemFile(agentDir, CRON_FILE, message)
+  }
+}
+
 function errorMessage(err: unknown): string {
   return err instanceof Error ? err.message : String(err)
 }

package/src/cron/schema.ts

@@ -11,6 +11,16 @@ const baseJob = z.object({
   schedule: z.string().min(1),
   enabled: z.boolean().default(true),
   timezone: z.string().optional(),
+  scheduledByRole: z.string().optional(),
+  // Audit snapshot of the SessionOrigin that scheduled this job. Persisted
+  // as opaque z.unknown() because SessionOrigin is recursive (a cron origin
+  // can contain a subagent origin can contain another cron origin, etc.)
+  // and we do not want to mirror that union in the cron schema. The cron
+  // consumer reads this back as-is and stamps it into the firing session's
+  // origin without further validation -- if it's malformed, role
+  // resolution falls back to `guest` via the same path that handles
+  // missing fields.
+  scheduledByOrigin: z.unknown().optional(),
 })
 
 const promptJob = baseJob.extend({
@@ -46,6 +56,93 @@ export type ParseCronOptions = {
   subagents?: SubagentRegistry
 }
 
+// One-shot rewrite for cron.json files that predate PR #171, when
+// `scheduledByRole` became mandatory on every job. The schema gate
+// (`parseCronFile`) rejects legacy entries with a precise remediation
+// message, but rejecting on every container boot is a stuck state for
+// the user — the agent crashes in a tight restart loop with no path
+// forward except hand-editing cron.json.
+//
+// The migration stamps `scheduledByRole: 'owner'` on every job that's
+// missing it. `owner` is the right default for two reasons:
+//   1. Before #171 there was no role concept; every cron job ran with
+//      the same (effectively-owner) privileges the agent had.
+//   2. The schema gate's own error message tells users to add
+//      `"scheduledByRole": "owner"` for manually-authored entries —
+//      we just do it for them.
+//
+// Mirrors `migrateLegacyConfigShape` in src/config/config.ts: pure
+// function, returns the rewritten JSON plus an `applied` array so
+// callers can build a meaningful commit message. Returns `changed:
+// false` on canonical input so the persist + commit path stays
+// untouched on the happy path.
+export type CronMigrationStep = { kind: 'stamp-scheduled-by-role-owner'; jobIds: string[] }
+
+export type CronMigrationResult = { json: unknown; changed: boolean; applied: CronMigrationStep[] }
+
+export function migrateLegacyCronShape(json: unknown): CronMigrationResult {
+  if (typeof json !== 'object' || json === null || Array.isArray(json)) {
+    return { json, changed: false, applied: [] }
+  }
+
+  const obj = json as Record<string, unknown>
+  const jobs = obj.jobs
+  if (!Array.isArray(jobs)) {
+    return { json, changed: false, applied: [] }
+  }
+
+  const stampedIds: string[] = []
+  const nextJobs = jobs.map((job) => {
+    if (typeof job !== 'object' || job === null || Array.isArray(job)) return job
+    const record = job as Record<string, unknown>
+    if ('scheduledByRole' in record) return job
+    const id = typeof record.id === 'string' ? record.id : '<unknown>'
+    stampedIds.push(id)
+    return { ...record, scheduledByRole: 'owner' }
+  })
+
+  if (stampedIds.length === 0) {
+    return { json, changed: false, applied: [] }
+  }
+
+  return {
+    json: { ...obj, jobs: nextJobs },
+    changed: true,
+    applied: [{ kind: 'stamp-scheduled-by-role-owner', jobIds: stampedIds }],
+  }
+}
+
+// Builds a one-line git commit subject (plus enumerating body) for a
+// cron.json migration. Returns null when no steps were applied — callers
+// should not commit in that case. Mirrors `buildConfigMigrationCommitMessage`
+// in src/config/config.ts.
+export function buildCronMigrationCommitMessage(applied: readonly CronMigrationStep[]): string | null {
+  const first = applied[0]
+  if (first === undefined) return null
+
+  const subject =
+    applied.length === 1
+      ? `cron.json: ${shortCronStepLabel(first)}`
+      : `cron.json: migrate legacy shape (${applied.length} steps)`
+
+  const bodyLines: string[] = applied.map((step) => `- ${describeCronStep(step)}`)
+  return `${subject}\n\n${bodyLines.join('\n')}\n`
+}
+
+function shortCronStepLabel(step: CronMigrationStep): string {
+  switch (step.kind) {
+    case 'stamp-scheduled-by-role-owner':
+      return `stamp scheduledByRole: "owner" on ${step.jobIds.length} legacy job${step.jobIds.length === 1 ? '' : 's'}`
+  }
+}
+
+function describeCronStep(step: CronMigrationStep): string {
+  switch (step.kind) {
+    case 'stamp-scheduled-by-role-owner':
+      return `stamp scheduledByRole: "owner" on jobs without provenance (PR #171 backfill): ${step.jobIds.join(', ')}`
+  }
+}
+
 export function parseCronFile(raw: unknown, options: ParseCronOptions = {}): ParseCronResult {
   const parsed = cronFileSchema.safeParse(raw)
   if (!parsed.success) {
@@ -73,6 +170,13 @@ export function parseCronFile(raw: unknown, options: ParseCronOptions = {}): Par
       return { ok: false, reason: `job ${job.id}: invalid schedule "${job.schedule}": ${message}` }
     }
 
+    if (job.scheduledByRole === undefined) {
+      return {
+        ok: false,
+        reason: `job ${job.id}: missing 'scheduledByRole'. Add "scheduledByRole": "owner" if you authored this entry manually.`,
+      }
+    }
+
     if (job.kind === 'prompt' && job.subagent !== undefined && options.subagents !== undefined) {
       const subagent = options.subagents[job.subagent]
       if (!subagent) {

package/src/doctor/checks.ts

@@ -23,8 +23,6 @@ import { buildGitignore, GITIGNORE_FILE } from '@/init/gitignore'
 
 import type { DoctorCheck } from './types'
 
-const REQUIRED_DIRS = ['workspace', 'sessions', '.agents/skills', 'mounts', 'packages'] as const
-
 export function buildStaticChecks(opts: { dockerExec?: DockerExec } = {}): DoctorCheck[] {
   const dockerExec = opts.dockerExec ?? defaultDockerExec
 
@@ -32,12 +30,12 @@ export function buildStaticChecks(opts: { dockerExec?: DockerExec } = {}): Docto
     dockerDaemon(dockerExec),
     bunRuntime(),
     agentFolderInitialized(),
-    agentFolderRequiredDirs(),
     agentFolderDockerfileTemplate(),
     agentFolderGitignoreTemplate(),
     agentFolderNodeModules(),
     agentFolderGitRepo(),
     configValid(),
+    configBundledProfiles(),
     hostdHomeWritable(),
     hostdReachable(),
     hostdRegistration(),
@@ -103,36 +101,6 @@ function agentFolderInitialized(): DoctorCheck {
   }
 }
 
-function agentFolderRequiredDirs(): DoctorCheck {
-  return {
-    name: 'agent-folder.required-dirs',
-    category: 'agent-folder',
-    description: 'required agent directories exist',
-    applies: (ctx) => ctx.hasAgentFolder,
-    async run(ctx) {
-      const missing = REQUIRED_DIRS.filter((d) => !existsSync(join(ctx.cwd, d)))
-      if (missing.length === 0) return { status: 'ok', message: 'all required directories present' }
-      return {
-        status: 'warning',
-        message: `${missing.length} required ${missing.length === 1 ? 'directory' : 'directories'} missing`,
-        details: missing.map((d) => `missing: ${d}/`),
-        fix: {
-          description: `Create the missing directories (${missing.map((d) => `${d}/`).join(', ')}).`,
-          autoFix: async () => {
-            for (const d of missing) {
-              mkdirSync(join(ctx.cwd, d), { recursive: true })
-            }
-            return {
-              summary: `created ${missing.map((d) => `${d}/`).join(', ')}`,
-              changedPaths: missing.map((d) => `${d}/`),
-            }
-          },
-        },
-      }
-    },
-  }
-}
-
 function agentFolderDockerfileTemplate(): DoctorCheck {
   return {
     name: 'agent-folder.dockerfile-managed',
@@ -247,6 +215,55 @@ function configValid(): DoctorCheck {
   }
 }
 
+// Warns (not errors) when a model profile that a bundled subagent prefers is
+// absent from `models`. Bundled subagents fall back to `default` silently
+// today, but the operator likely declared a `fast`/`deep`/`vision` model in
+// the design discussion's tier scheme expecting the bundled subagents to
+// pick them up. This check surfaces the gap once at `typeclaw doctor` time
+// instead of leaving it buried in container logs (where the rate-limited
+// fallback warning lives).
+//
+// We deliberately limit this to known bundled profiles (memory-logger=fast,
+// dreaming=deep, multimodal-looker=vision). Plugin-contributed subagents
+// would require loading the plugin registry — a heavyweight async path
+// that doesn't belong in doctor's static check surface.
+const BUNDLED_PROFILES: ReadonlyArray<{ profile: string; subagent: string }> = [
+  { profile: 'fast', subagent: 'memory-logger' },
+  { profile: 'deep', subagent: 'dreaming' },
+  { profile: 'vision', subagent: 'multimodal-looker (via look_at tool)' },
+]
+
+function configBundledProfiles(): DoctorCheck {
+  return {
+    name: 'config.bundled-profiles',
+    category: 'config',
+    description: 'bundled subagent profiles (`fast`, `deep`, `vision`) declared in models',
+    applies: (ctx) => ctx.hasAgentFolder,
+    async run(ctx) {
+      const validation = validateConfig(ctx.cwd)
+      if (!validation.ok) {
+        return { status: 'ok', message: 'skipped (config.valid will report the underlying error)' }
+      }
+      const config = loadConfigSync(ctx.cwd)
+      const declared = new Set(Object.keys(config.models))
+      const missing = BUNDLED_PROFILES.filter((p) => !declared.has(p.profile))
+      if (missing.length === 0) {
+        return { status: 'ok', message: 'all bundled subagent profiles declared' }
+      }
+      return {
+        status: 'warning',
+        message: `${missing.length} bundled profile(s) missing; will fall back to \`default\``,
+        details: missing.map(
+          (m) => `${m.profile}: used by ${m.subagent}; declare \`models.${m.profile}\` in typeclaw.json to override`,
+        ),
+        fix: {
+          description: 'Add the missing profile(s) under `models` in typeclaw.json. See the typeclaw-config skill.',
+        },
+      }
+    },
+  }
+}
+
 function hostdHomeWritable(): DoctorCheck {
   return {
     name: 'hostd.home-writable',

package/src/git/system-commit.ts

@@ -0,0 +1,103 @@
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+// Commits TypeClaw-owned tracked files (.gitignore, package.json,
+// typeclaw.json) if any are dirty in git. Skips silently when the agent
+// folder is not a git repo, when Bun is unavailable, or when every named
+// file is clean. Uses the user's global git config for authorship —
+// TypeClaw does not impersonate the user here.
+//
+// Accepts a single file or an array; the array form produces a single
+// atomic commit covering all listed paths (used for migrations that touch
+// multiple files together, e.g. enabling bun workspaces writes both
+// package.json and packages/.gitkeep in one commit).
+//
+// Lives under src/git/ rather than src/container/ because both the
+// host-stage launcher (typeclaw start) and src/config/config.ts (called
+// from every entry point that reads typeclaw.json, host AND container)
+// need to commit migration artifacts. Putting it in src/container/ would
+// pull container-level imports into the config module and create a
+// circular dependency at the package boundary.
+export async function commitSystemFile(cwd: string, file: string | readonly string[], message: string): Promise<void> {
+  const files = typeof file === 'string' ? [file] : file
+  if (files.length === 0) return
+
+  const bun = getBunAsync()
+  if (!bun) return
+  if (!existsSync(join(cwd, '.git'))) return
+
+  const status = bun.spawn({
+    cmd: ['git', 'status', '--porcelain', '--', ...files],
+    cwd,
+    stdout: 'pipe',
+    stderr: 'pipe',
+  })
+  if ((await status.exited) !== 0) return
+  const dirty = (await new Response(status.stdout).text()).trim().length > 0
+  if (!dirty) return
+
+  const add = bun.spawn({ cmd: ['git', 'add', '--', ...files], cwd, stdout: 'pipe', stderr: 'pipe' })
+  if ((await add.exited) !== 0) return
+
+  const commit = bun.spawn({
+    cmd: ['git', 'commit', '-m', message, '--only', '--', ...files],
+    cwd,
+    stdout: 'pipe',
+    stderr: 'pipe',
+  })
+  await commit.exited
+}
+
+// Synchronous variant for callers that already hold a synchronous codepath
+// — specifically `persistMigratedConfig` in src/config/config.ts. The
+// migration write is itself synchronous (writeFileSync) and the call sites
+// (loadConfigSync, validateConfig, loadPluginConfigsSync) are sync, so we
+// cannot await an async commit without forcing them all to become async,
+// which would ripple into hundreds of call sites across the codebase.
+//
+// The commit overhead (~10-50ms) is paid exactly once per agent folder
+// per legacy form: after the first call rewrites the file to canonical
+// shape, subsequent migrateLegacyConfigShape calls return changed=false
+// and this codepath is unreachable. On canonical folders (the common
+// case) this function is never called at all.
+//
+// Same skip semantics as the async variant — no-op when the folder is not
+// a git repo, when Bun is unavailable, or when the file is clean.
+export function commitSystemFileSync(cwd: string, file: string | readonly string[], message: string): void {
+  const files = typeof file === 'string' ? [file] : file
+  if (files.length === 0) return
+
+  const bun = getBunSync()
+  if (!bun) return
+  if (!existsSync(join(cwd, '.git'))) return
+
+  const status = bun.spawnSync({
+    cmd: ['git', 'status', '--porcelain', '--', ...files],
+    cwd,
+    stdout: 'pipe',
+    stderr: 'pipe',
+  })
+  if (status.exitCode !== 0) return
+  if (new TextDecoder().decode(status.stdout).trim().length === 0) return
+
+  const add = bun.spawnSync({ cmd: ['git', 'add', '--', ...files], cwd, stdout: 'pipe', stderr: 'pipe' })
+  if (add.exitCode !== 0) return
+
+  bun.spawnSync({
+    cmd: ['git', 'commit', '-m', message, '--only', '--', ...files],
+    cwd,
+    stdout: 'pipe',
+    stderr: 'pipe',
+  })
+}
+
+// Bun-availability shims kept tight to the two functions so the module
+// has no module-level side effects (matters for the sync codepath, which
+// is called during typeclaw.json reads on hot import).
+function getBunAsync(): { spawn: typeof Bun.spawn } | undefined {
+  return (globalThis as { Bun?: { spawn: typeof Bun.spawn } }).Bun
+}
+
+function getBunSync(): { spawnSync: typeof Bun.spawnSync } | undefined {
+  return (globalThis as { Bun?: { spawnSync: typeof Bun.spawnSync } }).Bun
+}