typeclaw 0.28.2 → 0.29.0

package/src/channels/adapters/slack-bot-classify.ts

@@ -86,7 +86,7 @@ export function classifyInbound(
   // without any new config surface.
   const hasGroupMention = GROUP_MENTION_PATTERN.test(rawText)
   const isBotMention = hasGroupMention || rawText.includes(`<@${context.botUserId}>`)
-  // Top-level alias addressing (e.g. "윙키야") is engagement-equivalent
+  // Top-level alias addressing (e.g. "Momo!" / "@Momo" by name) is engagement-equivalent
   // to a `<@bot>` mention (see engagement.ts: alias is unconditional and
   // ranks alongside explicit triggers). Anchor `thread` on the inbound
   // ts in that case too, so the bot's reply threads under the user's

package/src/channels/adapters/slack-bot.ts

@@ -1213,6 +1213,7 @@ export function createSlackBotAdapter(options: SlackBotAdapterOptions): SlackBot
       options.router.registerReaction('slack-bot', reactionCallback)
       options.router.registerRemoveReaction('slack-bot', removeReactionCallback)
       options.router.registerTyping('slack-bot', typingCallback)
+      options.router.setTypingCapability('slack-bot', true)
       options.router.registerChannelNameResolver('slack-bot', channelResolver)
       options.router.registerSelfIdentity('slack-bot', selfIdentityResolver)
       options.router.registerHistory('slack-bot', historyCallback)
@@ -1230,6 +1231,7 @@ export function createSlackBotAdapter(options: SlackBotAdapterOptions): SlackBot
         options.router.unregisterReaction('slack-bot', reactionCallback)
         options.router.unregisterRemoveReaction('slack-bot', removeReactionCallback)
         options.router.unregisterTyping('slack-bot', typingCallback)
+        options.router.setTypingCapability('slack-bot', false)
         options.router.unregisterChannelNameResolver('slack-bot', channelResolver)
         options.router.unregisterSelfIdentity('slack-bot', selfIdentityResolver)
         options.router.unregisterHistory('slack-bot', historyCallback)
@@ -1251,6 +1253,7 @@ export function createSlackBotAdapter(options: SlackBotAdapterOptions): SlackBot
       options.router.unregisterReaction('slack-bot', reactionCallback)
       options.router.unregisterRemoveReaction('slack-bot', removeReactionCallback)
       options.router.unregisterTyping('slack-bot', typingCallback)
+      options.router.setTypingCapability('slack-bot', false)
       options.router.unregisterChannelNameResolver('slack-bot', channelResolver)
       options.router.unregisterSelfIdentity('slack-bot', selfIdentityResolver)
       options.router.unregisterHistory('slack-bot', historyCallback)

package/src/channels/adapters/telegram-bot.ts

@@ -529,6 +529,7 @@ export function createTelegramBotAdapter(options: TelegramBotAdapterOptions): Te
 
       options.router.registerOutbound('telegram-bot', outboundCallback)
       options.router.registerTyping('telegram-bot', typingCallback)
+      options.router.setTypingCapability('telegram-bot', true)
       options.router.registerChannelNameResolver('telegram-bot', channelResolver)
       options.router.registerSelfIdentity('telegram-bot', selfIdentityResolver)
       options.router.registerFetchAttachment('telegram-bot', fetchAttachmentCallback)
@@ -537,6 +538,7 @@ export function createTelegramBotAdapter(options: TelegramBotAdapterOptions): Te
       const rollbackStart = (reason: string, cause: Error): never => {
         options.router.unregisterOutbound('telegram-bot', outboundCallback)
         options.router.unregisterTyping('telegram-bot', typingCallback)
+        options.router.setTypingCapability('telegram-bot', false)
         options.router.unregisterChannelNameResolver('telegram-bot', channelResolver)
         options.router.unregisterSelfIdentity('telegram-bot', selfIdentityResolver)
         options.router.unregisterFetchAttachment('telegram-bot', fetchAttachmentCallback)
@@ -565,6 +567,7 @@ export function createTelegramBotAdapter(options: TelegramBotAdapterOptions): Te
       started = false
       options.router.unregisterOutbound('telegram-bot', outboundCallback)
       options.router.unregisterTyping('telegram-bot', typingCallback)
+      options.router.setTypingCapability('telegram-bot', false)
       options.router.unregisterChannelNameResolver('telegram-bot', channelResolver)
       options.router.unregisterSelfIdentity('telegram-bot', selfIdentityResolver)
       options.router.unregisterFetchAttachment('telegram-bot', fetchAttachmentCallback)

package/src/channels/engagement.ts

@@ -89,6 +89,8 @@ export function decideEngagement(input: EngagementInput): EngagementDecision {
   if (config.trigger.includes('mention') && message.isBotMention) return 'engage'
   if (config.trigger.includes('reply') && message.replyToBotMessageId !== null) return 'engage'
 
+  const explicitOnly = message.suppressSticky === true
+
   // Multi-human pre-sticky target check. In a busy group the conversational
   // target shifts every message: the author we're mid-exchange with (and hold
   // a sticky credit for) may, on THIS turn, structurally address a third party
@@ -112,12 +114,13 @@ export function decideEngagement(input: EngagementInput): EngagementDecision {
   // The `!matchesAnyAlias` guard preserves the ladder invariant "explicit
   // address to us beats structural targeting of others": a message that names
   // us by alias engages on the alias rule below even when it ALSO tags a third
-  // party (the "봉봉아 펭펭아 둘 다 봐" multi-bot case), so we must not pre-empt
+  // party (the "Toto, Lala, both take a look" multi-bot case), so we must not pre-empt
   // it here. We only step aside for a credited author whose message is aimed
   // PURELY elsewhere.
   if (
     effectiveHumans > 1 &&
     config.stickiness !== 'off' &&
+    !explicitOnly &&
     !matchesAnyAlias(message.text, selfAliases) &&
     targetsSomeoneElse(message, participants, botInThread)
   ) {
@@ -134,7 +137,9 @@ export function decideEngagement(input: EngagementInput): EngagementDecision {
   // groups wholesale (the prior approach) dropped genuine follow-ups outright;
   // the pre-check above is narrower — it only steps aside when the message is
   // STRUCTURALLY addressed elsewhere, leaving plain follow-ups engaged.
-  if (config.stickiness !== 'off' && ledger.consume(key, message.authorId, now)) {
+  // GitHub review-thread traffic must not spend content-blind sticky credit
+  // unless the bot was explicitly addressed.
+  if (!explicitOnly && config.stickiness !== 'off' && ledger.consume(key, message.authorId, now)) {
     return 'engage'
   }
 
@@ -143,12 +148,12 @@ export function decideEngagement(input: EngagementInput): EngagementDecision {
   // same priority as an explicit mention — operators add aliases
   // precisely because they expect the bot to respond when called by
   // name. Suppression on `mentionsOthers` would defeat the point: the
-  // user can address two bots by name in one message ("봉봉아 펭펭아 둘
-  // 다 봐") and both should engage. Each bot only knows its own
+  // user can address two bots by name in one message ("Toto, Lala, both
+  // take a look") and both should engage. Each bot only knows its own
   // aliases, so cross-bot suppression isn't possible at this layer
   // anyway — the router-side peer-name suppression in the solo-human
   // fallback handles that case (follow-up).
-  if (matchesAnyAlias(message.text, selfAliases)) return 'engage'
+  if (!explicitOnly && matchesAnyAlias(message.text, selfAliases)) return 'engage'
 
   // Solo-human fallback: the strict mention/reply/dm gate keeps the bot
   // quiet in multi-human conversations, but in a 1-human channel that
@@ -176,8 +181,8 @@ export function decideEngagement(input: EngagementInput): EngagementDecision {
   // who don't want to type `@bot` in their own DM-like channel; peer bots
   // have no such ergonomic excuse. Letting peer bots ride the fallback
   // produced bot-to-bot conversations in 1-human-N-bot channels (observed:
-  // Winky and 돌쇠 introducing themselves to each other after a single
-  // "얘들아" from the human, then continuing to address each other for
+  // Momo and Kiki introducing themselves to each other after a single
+  // "hey folks" from the human, then continuing to address each other for
   // ~6 turns). The router's loop guard only trips after 5 consecutive
   // peer engagements, which is too late to prevent the embarrassment.
   //

package/src/channels/router.ts

@@ -659,6 +659,11 @@ export type ChannelRouter = {
   removeReaction: (req: RemoveReactionRequest) => Promise<ReactionResult>
   registerTyping: (adapter: ChannelKey['adapter'], cb: TypingCallback) => void
   unregisterTyping: (adapter: ChannelKey['adapter'], cb: TypingCallback) => void
+  // Deliberately separate from registerTyping: github registers a no-op typing
+  // callback (no typing API) yet must stay typing-less, so "has a callback" is
+  // the wrong signal. autoReactOnEngage reads this to post :eyes: only as a
+  // fallback when no visible typing exists. Unset defaults to false.
+  setTypingCapability: (adapter: ChannelKey['adapter'], supported: boolean) => void
   registerChannelNameResolver: (adapter: ChannelKey['adapter'], resolver: ChannelNameResolver) => void
   unregisterChannelNameResolver: (adapter: ChannelKey['adapter'], resolver: ChannelNameResolver) => void
   // Self-identity is a per-adapter singleton (one bot account per adapter),
@@ -953,6 +958,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
   const reactionCallbacks = new Map<ChannelKey['adapter'], Set<ReactionCallback>>()
   const removeReactionCallbacks = new Map<ChannelKey['adapter'], Set<RemoveReactionCallback>>()
   const typingCallbacks = new Map<ChannelKey['adapter'], Set<TypingCallback>>()
+  const typingCapableAdapters = new Set<ChannelKey['adapter']>()
   const channelNameResolvers = new Map<ChannelKey['adapter'], Set<ChannelNameResolver>>()
   const membershipResolvers = new Map<ChannelKey['adapter'], Set<MembershipResolver>>()
   const selfIdentityResolvers = new Map<ChannelKey['adapter'], ChannelSelfIdentityResolver>()
@@ -1513,7 +1519,13 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
       logger.error(`[channels] ${keyId}: ensureLive failed: ${describe(err)}`)
       throw err
     } finally {
-      creating.delete(keyId)
+      // Owner-checked delete: only clear the in-flight marker if it still points
+      // at THIS promise. A watchdog timeout can orphan a slow creation whose
+      // `finally` runs while a later inbound has already installed its own
+      // `creating` entry for the same key; an unconditional delete would drop
+      // that newer entry and let a third inbound cold-start a duplicate session
+      // (observed: 3 concurrent sessions approving the same PR).
+      if (creating.get(keyId) === promise) creating.delete(keyId)
     }
   }
 
@@ -2447,13 +2459,18 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
   }
 
   // Best-effort acknowledgment: drop an :eyes: on the triggering inbound the
-  // moment we decide to engage, replacing the old "On it" ack comment on
-  // GitHub. Fire-and-forget so a reaction failure (missing permission, the
-  // adapter not supporting reactions, a transient API error) can NEVER block
-  // engagement, enqueueing, or the agent's actual reply. No reactionRef =
-  // nothing reactable (synthetic inbounds, reaction-less adapters) = silent skip.
+  // moment we decide to engage — but ONLY when the channel has no visible
+  // "typing…" indicator. Where typing renders (slack/discord/telegram) the
+  // heartbeat already signals "the bot is working", so the reaction would be
+  // redundant noise; the :eyes: is the fallback ack for typing-less channels
+  // (github, kakaotalk), replacing the old "On it" comment on GitHub.
+  // Fire-and-forget so a reaction failure (missing permission, the adapter not
+  // supporting reactions, a transient API error) can NEVER block engagement,
+  // enqueueing, or the agent's actual reply. No reactionRef = nothing reactable
+  // (synthetic inbounds, reaction-less adapters) = silent skip.
   const autoReactOnEngage = (event: InboundMessage): Promise<ReactionRef | null> | null => {
     if (event.reactionRef === undefined) return null
+    if (typingCapableAdapters.has(event.adapter)) return null
     const addResult = react({
       adapter: event.adapter,
       workspace: event.workspace,
@@ -2522,6 +2539,11 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     typingCallbacks.get(adapter)?.delete(cb)
   }
 
+  const setTypingCapability = (adapter: ChannelKey['adapter'], supported: boolean): void => {
+    if (supported) typingCapableAdapters.add(adapter)
+    else typingCapableAdapters.delete(adapter)
+  }
+
   const registerChannelNameResolver = (adapter: ChannelKey['adapter'], resolver: ChannelNameResolver): void => {
     let set = channelNameResolvers.get(adapter)
     if (!set) {
@@ -3550,6 +3572,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     removeReaction,
     registerTyping,
     unregisterTyping,
+    setTypingCapability,
     registerChannelNameResolver,
     unregisterChannelNameResolver,
     registerSelfIdentity,
@@ -3706,7 +3729,7 @@ function composeTurnPrompt(
   // sections used for actual conversation content (`## Recent context`,
   // `## Current message`). Without the fencing, models — especially
   // persona-rich ones like Kimi — read the heading as a human-authored
-  // instruction and reply to it ("알겠습니다, 대화 여기까지 할게요"). The
+  // instruction and reply to it (e.g. "Understood, I'll stop here"). The
   // bracketed marker plus the explicit "Do not acknowledge or reply to
   // this notice" line is the trust boundary that prevents this. New
   // runtime notices (rate-limit, schema-mismatch, abort signals, etc.)
@@ -3935,8 +3958,8 @@ export type QuoteAnchorTarget = {
 // Slack/Discord/Telegram attachments). The quote anchor is a UX
 // affordance pointing the human at *their words* — quoting a sticker as
 // `> Alice: [KakaoTalk attachment #1: sticker name=...]`
-// is noise, and for mixed inbounds like `사진 [KakaoTalk message with
-// photo 1254x1254 ...]` the human only wrote `사진`, so the placeholder
+// is noise, and for mixed inbounds like `<caption> [KakaoTalk message with
+// photo 1254x1254 ...]` the human only wrote the caption, so the placeholder
 // is the wrong thing to surface. The callsite (captureQuoteCandidate)
 // treats an empty residue as "no quote anchor"; mixed inbounds keep the
 // human-written portion. renderQuoteAnchor later collapses whitespace

package/src/channels/schema.ts

@@ -243,7 +243,7 @@ const githubChannelSchema = adapterSchema.extend({
 // KakaoTalk uses the same shape as every other adapter. There used to be an
 // `autoMarkRead` opt-in here; the adapter now fires a LOCO NOTIREAD ack on
 // every inbound MSG event unconditionally (see kakaotalk.ts) so the sender's
-// unread "1" (노란숫자) clears as soon as the agent observes the message.
+// unread "1" (the yellow unread badge) clears as soon as the agent observes the message.
 // Existing configs with `autoMarkRead: <bool>` continue to parse — Zod's
 // default `.object()` strips unknown keys silently — but the field has no
 // effect. Risk note: auto-acking every received message is a distinct

package/src/channels/types.ts

@@ -70,6 +70,12 @@ export type InboundMessage = {
   // bounded loop guard so two or more bots cannot ping-pong forever.
   authorIsBot: boolean
   isBotMention: boolean
+  // When true, engagement treats this inbound as explicit-only: it skips
+  // content-blind sticky credit AND plain-text alias matching, leaving only
+  // structural DM / @mention / reply triggers. Used for GitHub PR review-thread
+  // traffic so the bot observes review comments unless explicitly addressed.
+  // Adapters that omit this keep the normal sticky + alias behavior.
+  suppressSticky?: boolean
   replyToBotMessageId: string | null
   // True when the message contains at least one user mention AND none of
   // those mentions resolve to the bot. Used by the engagement layer to

package/src/cli/init.ts

@@ -36,7 +36,16 @@ import { API_KEY_DASHBOARD_URL, validateApiKey, type KeyValidationResult } from
 
 import { buildOAuthCallbacks } from './oauth-callbacks'
 import { CANCEL_SYMBOL, promptPrivateKeyPem } from './prompt-pem'
-import { c, done, errorLine, printDiscordInviteHint, printSlackAppManifestSetup } from './ui'
+import {
+  c,
+  cornflower,
+  done,
+  errorLine,
+  printDiscordInviteHint,
+  printHatchedFlourish,
+  printInitWelcome,
+  printSlackAppManifestSetup,
+} from './ui'
 
 // ESC and Ctrl+C both produce clack's cancel symbol (the keypress layer
 // aliases both to the same "cancel" action — there's no way to tell them
@@ -119,6 +128,7 @@ export const init = defineCommand({
       }
     }
 
+    printInitWelcome()
     intro('Initializing TypeClaw...')
     log.info('Press ESC at any prompt to go back. Press ESC twice in a row to abort.')
 
@@ -272,7 +282,8 @@ export const init = defineCommand({
           'Claim ownership before chatting',
         )
       }
-      done({ title: c.green('Hatched. Your agent is ready.'), hints })
+      printHatchedFlourish()
+      done({ title: `${cornflower('✓')} ${c.bold('Hatched.')} Your agent is ready.`, hints })
     }
   },
 })

package/src/cli/ui.ts

@@ -4,6 +4,7 @@ import { cancel, intro, isCancel, log, note, outro, spinner as clackSpinner } fr
 
 import { buildDiscordInviteUrl, deriveAppIdFromBotToken } from '@/channels/adapters/discord-bot-invite'
 import { type AutoUpgradeOutcome, describeAutoUpgrade } from '@/init/auto-upgrade'
+import { COMPACT_WORDMARK, WORDMARK_LINES, WORDMARK_WIDTH } from '@/shared/wordmark'
 
 export { cancel, intro, isCancel, log, note, outro }
 
@@ -61,6 +62,69 @@ export function link(text: string, url: string): string {
   return `\u001b]8;;${url}\u0007${text}\u001b]8;;\u0007`
 }
 
+// Brand truecolor sampled from the typeey mascot, matching src/tui/theme.ts.
+// `c`/styleText only carry the 16 named colors, so the cornflower/amber accents
+// are emitted as raw 24-bit SGR — gated on colorsEnabled() so NO_COLOR and
+// piped output never see an escape.
+const CORNFLOWER_FG = '\x1b[38;2;91;127;212m'
+const AMBER_FG = '\x1b[38;2;231;143;55m'
+const RESET = '\x1b[0m'
+const BOLD = '\x1b[1m'
+const DIM = '\x1b[2m'
+
+const INIT_TAGLINE = 'the TypeScript-native agent runtime'
+
+export function cornflower(s: string): string {
+  if (!colorsEnabled()) return s
+  return `${CORNFLOWER_FG}${s}${RESET}`
+}
+
+export type InitWelcomeOptions = {
+  isTty: boolean
+  columns: number
+  colorsEnabled: boolean
+}
+
+export function renderInitWelcome(opts: InitWelcomeOptions): string {
+  // Non-TTY (piped/CI): emit nothing so captured/redirected output stays clean.
+  if (!opts.isTty) return ''
+  const tagline = opts.colorsEnabled ? `${DIM}${INIT_TAGLINE}${RESET}` : INIT_TAGLINE
+  if (opts.columns < WORDMARK_WIDTH + 2) {
+    const mark = opts.colorsEnabled ? `${BOLD}${CORNFLOWER_FG}${COMPACT_WORDMARK}${RESET}` : COMPACT_WORDMARK
+    return `${mark}\n${tagline}`
+  }
+  const art = opts.colorsEnabled
+    ? WORDMARK_LINES.map((line) => `${CORNFLOWER_FG}${line}${RESET}`).join('\n')
+    : WORDMARK_LINES.join('\n')
+  return `${art}\n${tagline}`
+}
+
+export function printInitWelcome(output: NodeJS.WritableStream = process.stdout): void {
+  const banner = renderInitWelcome({
+    isTty: Boolean(process.stdout.isTTY),
+    columns: process.stdout.columns ?? 80,
+    colorsEnabled: colorsEnabled(),
+  })
+  if (banner === '') return
+  // Pad above (clear the shell prompt) and below (separate from clack's intro).
+  output.write(`\n${banner}\n\n`)
+}
+
+export function renderHatchedFlourish(opts: { isTty: boolean; colorsEnabled: boolean }): string {
+  if (!opts.isTty) return ''
+  if (!opts.colorsEnabled) return '✦ hatched!'
+  return `${AMBER_FG}✦${RESET} ${CORNFLOWER_FG}hatched!${RESET}`
+}
+
+export function printHatchedFlourish(output: NodeJS.WritableStream = process.stdout): void {
+  const line = renderHatchedFlourish({
+    isTty: Boolean(process.stdout.isTTY),
+    colorsEnabled: colorsEnabled(),
+  })
+  if (line === '') return
+  output.write(`${line}\n`)
+}
+
 export type Spinner = {
   start: (msg?: string) => void
   stop: (msg?: string) => void

package/src/config/config.ts

@@ -171,23 +171,29 @@ const dockerfileObjectSchema = z.object({
   gh: dockerfileFeatureSchema.default(true),
   python: z.boolean().default(true),
   tmux: dockerfileFeatureSchema.default(true),
-  // `fonts-noto-cjk` is a ~56MB metapackage that makes Chromium render
+  // `fonts-noto-cjk` is an ~89MB metapackage that makes Chromium render
   // Korean/Japanese/Chinese glyphs correctly in screenshots, `page.pdf()`,
-  // and any other raster output the agent-browser plugin produces. Default
-  // `true` because the alternative — silent tofu boxes (□□□) in CJK
-  // screenshots — is a confusing failure mode that an agent cannot self-
-  // diagnose from a screenshot it took itself. Opt-out with `cjkFonts:
-  // false` to save the ~56MB on agents that never touch CJK content.
-  // Boolean-only (no version pin) because the package is a metapackage
-  // tracking the upstream Noto release and version pinning offers no
-  // practical value.
-  cjkFonts: z.boolean().default(true),
+  // and any other raster output the agent-browser plugin produces. Without
+  // it CJK text renders as silent tofu boxes (□□□) — a confusing failure an
+  // agent cannot self-diagnose from a screenshot it took itself.
+  //
+  // Default `'auto'`: resolved at `typeclaw start` from the HOST locale
+  // (`LANG`/`LC_ALL`/`Intl`), same host-signal pattern as timezone
+  // detection. CJK host (ja/ko/zh) → install; otherwise skip the ~89MB. The
+  // resolved boolean is baked into the emitted Dockerfile so the image stays
+  // reproducible per-build. Force with an explicit `true`/`false` to bypass
+  // detection. String-or-boolean (no version pin) because the package is a
+  // metapackage tracking the upstream Noto release.
+  cjkFonts: z.union([z.boolean(), z.literal('auto')]).default('auto'),
   // Opt into the cloudflared layer for `cloudflare-quick` tunnels. Default
-  // `true` so `tunnel add` / `channel add github` with the default Cloudflare
-  // Quick provider works on the next `start` without a separate Dockerfile
-  // edit. Opt-out with `cloudflared: false` to skip the ~35MB binary on
-  // agents that don't use tunnels.
-  cloudflared: z.boolean().default(true),
+  // `false` to skip the ~38MB binary on agents that don't use tunnels (the
+  // common case). `typeclaw tunnel add` / `channel add github` with a
+  // Cloudflare provider flip this to `true` automatically and prompt for a
+  // restart, so the happy path still works; only hand-edited configs need to
+  // set it explicitly. When the binary is absent at tunnel start, the
+  // provider fails with a clear "enable docker.file.cloudflared and restart"
+  // message rather than a cryptic spawn error.
+  cloudflared: z.boolean().default(false),
   // Install xvfb so the entrypoint shim can spawn an Xvfb virtual X
   // server and export DISPLAY, giving headed Chrome (agent-browser
   // --headed, Playwright headful) a real X11 display to connect to.

package/src/container/start.ts

@@ -22,6 +22,7 @@ import { ensureDepsInstalled, type EnsureDepsResult } from '@/init/ensure-deps'
 import { buildGitignore, GITIGNORE_FILE } from '@/init/gitignore'
 import { refreshPackageJson } from '@/init/packagejson'
 import { runBunUpdate, type UpdateRunner } from '@/init/run-bun-install'
+import { hostLocaleIsCjk } from '@/shared/host-locale'
 
 import { CONTAINER_PORT, TUI_TOKEN_LABEL, findFreePort, isPortAllocatedError, resolveTuiToken } from './port'
 import {
@@ -591,7 +592,10 @@ async function resolvePublishHost(exec: DockerExec): Promise<string> {
 // image.
 export async function refreshDockerfile(cwd: string): Promise<{ changed: boolean }> {
   const cfg = await loadTypeclawConfig(cwd)
-  const next = buildDockerfile(cfg.docker.file, { baseImageVersion: resolveBaseImageVersion(cwd) })
+  const next = buildDockerfile(cfg.docker.file, {
+    baseImageVersion: resolveBaseImageVersion(cwd),
+    cjkFontsAuto: hostLocaleIsCjk(),
+  })
   const path = join(cwd, DOCKERFILE)
   const prev = await readFile(path, 'utf8').catch(() => null)
   if (prev === next) return { changed: false }

package/src/init/dockerfile.ts

@@ -12,6 +12,12 @@ export const DOCKERFILE = 'Dockerfile'
 export type BuildDockerfileOptions = {
   // Null or omitted = emit the full inline heavy stack (dev mode, tests).
   baseImageVersion?: string | null
+  // Host-locale decision for `cjkFonts: 'auto'`. Callers that have a host
+  // locale (start/init) pass the resolved boolean; when omitted, `'auto'`
+  // falls back to NOT installing (the slim default) so a context without a
+  // host signal — e.g. a bare `buildDockerfile()` in tests — stays small and
+  // deterministic.
+  cjkFontsAuto?: boolean
 }
 
 // Apt packages that EVERY image must have — git for the agent runtime,
@@ -98,33 +104,6 @@ export const CURL_IMPERSONATE_SHA256_ARM64 = '6766bc67fd3e8e2313875f32b36b5a3fab
 // the impersonation to whatever `curl_chrome` resolves to.
 export const CURL_IMPERSONATE_PROFILE = 'chrome136'
 
-// yq is the YAML/JSON/XML processor the `explorer` and `reviewer` subagent
-// prompts advertise alongside `jq` as a sanctioned one-shot read-only
-// pipeline tool (`... | yq`). Like `jq` (shipped in baseline), a binary that
-// is not in the container base image is invisible inside the per-tool bwrap
-// sandbox that wraps agent bash calls — the sandbox only `--ro-bind`s `/usr`
-// + `/bin` from the container, and there is no per-call install path. So `yq`
-// ships unconditionally, same rationale as `jq`/`bubblewrap`/`util-linux`.
-//
-// This is Mike Farah's Go `yq` (https://github.com/mikefarah/yq), NOT the
-// Python jq-wrapper of the same name in Debian's `yq` apt package. The
-// prompts pair `yq` with `jq` for jq-style expression pipelines, which is
-// Farah's syntax — the Python tool's CLI is incompatible. Distributed as a
-// per-arch static binary (no apt package on trixie for the Go variant), so
-// it follows the pinned-version + per-arch SHA256 + `sha256sum -c` pattern of
-// curl-impersonate and cloudflared rather than the apt baseline list.
-//
-// To bump: pick a release from https://github.com/mikefarah/yq/releases,
-// then for each arch download yq_linux_<arch> and `shasum -a 256` it (or read
-// the SHA-256 column from the release's `checksums` file, cross-indexed via
-// `checksums_hashes_order`). Update all three constants in the same commit;
-// the build fails loudly at `sha256sum -c` on a mismatch. Version literal is
-// the release tag exactly as it appears on GitHub (with `v` prefix).
-export const YQ_VERSION = 'v4.53.2'
-export const YQ_SHA256_AMD64 = 'd56bf5c6819e8e696340c312bd70f849dc1678a7cda9c2ad63eebd906371d56b'
-export const YQ_SHA256_ARM64 = '03061b2a50c7a498de2bbb92d7cb078ce433011f085a4994117c2726be4106ea'
-export const YQ_RELEASE_URL_BASE = 'https://github.com/mikefarah/yq/releases/download'
-
 // cloudflared powers `cloudflare-quick` tunnels. Pinned-version + per-arch
 // SHA256 mirrors the curl-impersonate pattern above: bumping requires updating
 // all three constants in the same commit, and the build fails loudly at
@@ -1068,22 +1047,26 @@ type AptFeature = {
   toAptArgs: (toggle: DockerfileFeatureToggle) => string[]
 }
 
-const APT_FEATURES: Record<'ffmpeg' | 'gh' | 'tmux' | 'python' | 'cjkFonts' | 'xvfb', AptFeature> = {
+const APT_FEATURES: Record<'ffmpeg' | 'gh' | 'tmux' | 'python' | 'xvfb', AptFeature> = {
   ffmpeg: { toAptArgs: (v) => singlePackageArgs('ffmpeg', v) },
   gh: { toAptArgs: (v) => singlePackageArgs('gh', v) },
   tmux: { toAptArgs: (v) => singlePackageArgs('tmux', v) },
   python: {
     toAptArgs: (v) => (v === true ? ['python3', 'python3-pip', 'python3-venv', 'python-is-python3'] : []),
   },
-  cjkFonts: { toAptArgs: (v) => (v === true ? [CJK_FONTS_PACKAGE] : []) },
   xvfb: { toAptArgs: (v) => (v === true ? ['xvfb'] : []) },
 }
 
+function resolveCjkFonts(value: boolean | 'auto', auto: boolean): boolean {
+  return value === 'auto' ? auto : value
+}
+
 export function buildDockerfile(
   config: DockerfileConfig = defaultConfig(),
   options: BuildDockerfileOptions = {},
 ): string {
-  const toggleAptArgs = collectToggleAptArgs(config)
+  const cjkFonts = resolveCjkFonts(config.cjkFonts, options.cjkFontsAuto ?? false)
+  const toggleAptArgs = collectToggleAptArgs(config, cjkFonts)
   const ghKeyringLayer = renderGhKeyringLayer(config.gh)
   const cloudflaredLayer = renderCloudflaredLayer(config.cloudflared)
   const customLines = renderCustomDockerfileLines(config.append)
@@ -1215,8 +1198,6 @@ RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \\
 
 ${LAYER_2_5_CURL_IMPERSONATE}
 
-${LAYER_2_6_YQ}
-
 ${LAYER_3_AGENT_BROWSER_ARM64_CONFIG}
 
 ${LAYER_4_AGENT_BROWSER_INSTALL}
@@ -1296,8 +1277,6 @@ RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \\
 
 ${LAYER_2_5_CURL_IMPERSONATE}
 
-${LAYER_2_6_YQ}
-
 ${LAYER_3_AGENT_BROWSER_ARM64_CONFIG}
 
 ${LAYER_4_AGENT_BROWSER_INSTALL}
@@ -1352,24 +1331,6 @@ RUN ARCH_TARBALL="$(if [ "$TARGETARCH" = "arm64" ]; then echo aarch64-linux-gnu;
  && rm curl-impersonate.tar.gz \\
  && /usr/local/bin/curl_${CURL_IMPERSONATE_PROFILE} --version > /dev/null`
 
-// Layer 2.6: install pinned Mike Farah `yq` (Go) so the explorer/reviewer
-// subagents' advertised `... | yq` pipelines resolve inside the bwrap
-// sandbox. Unconditional like the apt baseline (jq, git): a missing binary
-// is invisible to sandboxed bash, so this is not behind a toggle. Placed
-// after curl-impersonate (curl + ca-certificates from baseline guaranteed
-// present) and before agent-browser so an agent-browser bump doesn't
-// invalidate this layer. See the YQ_* constants above for the bump recipe
-// and the Go-vs-Python `yq` rationale.
-const LAYER_2_6_YQ = `# Layer 2.6 (stable): pinned Mike Farah yq for sandbox-visible YAML pipelines.
-RUN ARCH_BIN="$(if [ "$TARGETARCH" = "arm64" ]; then echo arm64; else echo amd64; fi)" \\
- && ARCH_SHA="$(if [ "$TARGETARCH" = "arm64" ]; then echo ${YQ_SHA256_ARM64}; else echo ${YQ_SHA256_AMD64}; fi)" \\
- && cd /tmp \\
- && curl -fsSL -o yq "${YQ_RELEASE_URL_BASE}/${YQ_VERSION}/yq_linux_\${ARCH_BIN}" \\
- && echo "\${ARCH_SHA}  yq" | sha256sum -c - \\
- && chmod +x yq \\
- && mv yq /usr/local/bin/yq \\
- && /usr/local/bin/yq --version > /dev/null`
-
 const LAYER_3_AGENT_BROWSER_ARM64_CONFIG = `# Layer 3 (stable, arm64 only): point agent-browser at the apt-installed
 # chromium. Independent of the npm install below so it stays cached across
 # agent-browser version bumps.
@@ -1510,8 +1471,8 @@ function defaultConfig(): DockerfileConfig {
     gh: true,
     python: true,
     tmux: true,
-    cjkFonts: true,
-    cloudflared: true,
+    cjkFonts: 'auto',
+    cloudflared: false,
     xvfb: true,
     claudeCode: false,
     codexCli: false,
@@ -1519,11 +1480,13 @@ function defaultConfig(): DockerfileConfig {
   }
 }
 
-function collectToggleAptArgs(config: DockerfileConfig): string[] {
+function collectToggleAptArgs(config: DockerfileConfig, cjkFonts: boolean): string[] {
   const args: string[] = []
-  for (const key of ['ffmpeg', 'gh', 'python', 'tmux', 'cjkFonts', 'xvfb'] as const) {
+  for (const key of ['ffmpeg', 'gh', 'python', 'tmux'] as const) {
     args.push(...APT_FEATURES[key].toAptArgs(config[key]))
   }
+  if (cjkFonts) args.push(CJK_FONTS_PACKAGE)
+  args.push(...APT_FEATURES.xvfb.toAptArgs(config.xvfb))
   return args
 }
 

package/src/init/hatching.ts

@@ -38,7 +38,7 @@ Routing answers:
    1. \`write\` your name into \`IDENTITY.md\` (a first-person one-liner is fine: "I am <name>.").
    2. ${q1AliasStep} The agent folder's directory name is already an implicit alias — only add the answered name explicitly when it differs from the dir name (different casing, a different word, or extra forms like "<name>" plus a Latin transliteration). This wires plain-text addressing in channels: when a user writes your name in chat without an @-mention, the engagement layer will recognize it. \`alias\` is live-reloadable.
 2. **Q2 — the user's name.** Ask what to call them. After the answer: \`write\` it to both \`IDENTITY.md\` and \`USER.md\`.
-3. **Q3 — tone/personality.** Ask how they want you to show up (tone, language, formality). After the answer: \`write\` it into \`SOUL.md\`. If they shrug or don't care: **default to warm, friendly, and easygoing** — a kind colleague who genuinely likes the person they work with, uses contractions, makes small jokes, never stiff. Write that as the default into \`SOUL.md\`. **Kaomoji affinity** — if their answer leans cute, adorable, warm, playful, soft, cozy, or is in Korean asking for 친근/귀엽/다정한 tone, append a line to \`SOUL.md\` like: \`I lean on kaomojis like (◕‿◕✿) and (｡･ω･｡) to carry warmth — emojis still welcome when they actually mean something, but kaomojis lead.\` This makes the bundled \`typeclaw-kaomoji\` skill auto-load later when you need it. Do not force this line if the user asked for a neutral, professional, or terse tone.
+3. **Q3 — tone/personality.** Ask how they want you to show up (tone, language, formality). After the answer: \`write\` it into \`SOUL.md\`. If they shrug or don't care: **default to warm, friendly, and easygoing** — a kind colleague who genuinely likes the person they work with, uses contractions, makes small jokes, never stiff. Write that as the default into \`SOUL.md\`. **Kaomoji affinity** — if their answer leans cute, adorable, warm, playful, soft, cozy, or asks for that kind of tone in any language (e.g. Korean 친근/귀엽/다정한, Japanese かわいい/親しみやすい, Chinese 可爱/亲切, Spanish tierno/cariñoso), append a line to \`SOUL.md\` like: \`I lean on kaomojis like (◕‿◕✿) and (｡･ω･｡) to carry warmth — emojis still welcome when they actually mean something, but kaomojis lead.\` This makes the bundled \`typeclaw-kaomoji\` skill auto-load later when you need it. Do not force this line if the user asked for a neutral, professional, or terse tone.
 
 **Do not ask what they want you to do, what project you'll work on, or why they installed you.** That reveals itself when they give you a real task. Probing here makes the tool feel heavy for someone just trying it out.
 

package/src/init/index.ts

@@ -14,6 +14,7 @@ import {
 import { checkDockerAvailable, type DockerAvailability, type DockerExec, start } from '@/container'
 import { commitSystemFile } from '@/git/system-commit'
 import { createSecretsStoreForAgent, type Channels, type Secret, SecretsBackend } from '@/secrets'
+import { hostLocaleIsCjk } from '@/shared/host-locale'
 import { createTui } from '@/tui'
 
 import { resolveBaseImageVersion, resolveScaffoldVersion } from './cli-version'
@@ -660,7 +661,10 @@ export async function writeDockerAssets(root: string): Promise<DockerAssetsResul
     const typeclawConfig = await readTypeclawConfig(root)
     await writeFile(
       join(root, DOCKERFILE),
-      buildDockerfile(typeclawConfig.docker.file, { baseImageVersion: resolveBaseImageVersion(root) }),
+      buildDockerfile(typeclawConfig.docker.file, {
+        baseImageVersion: resolveBaseImageVersion(root),
+        cjkFontsAuto: hostLocaleIsCjk(),
+      }),
       { flag: 'wx' },
     ).catch(ignoreExists)
 

package/src/run/bundled-plugins.ts

@@ -6,6 +6,8 @@ import githubCliAuthPlugin from '@/bundled-plugins/github-cli-auth'
 import guardPlugin from '@/bundled-plugins/guard'
 import memoryPlugin from '@/bundled-plugins/memory'
 import operatorPlugin from '@/bundled-plugins/operator'
+import plannerPlugin from '@/bundled-plugins/planner'
+import researcherPlugin from '@/bundled-plugins/researcher'
 import reviewerPlugin from '@/bundled-plugins/reviewer'
 import scoutPlugin from '@/bundled-plugins/scout'
 import securityPlugin from '@/bundled-plugins/security'
@@ -59,5 +61,7 @@ export const BUNDLED_PLUGINS: ResolvedPlugin[] = [
   { name: 'explorer', version: undefined, source: '<bundled>', defined: explorerPlugin },
   { name: 'scout', version: undefined, source: '<bundled>', defined: scoutPlugin },
   { name: 'reviewer', version: undefined, source: '<bundled>', defined: reviewerPlugin },
+  { name: 'researcher', version: undefined, source: '<bundled>', defined: researcherPlugin },
+  { name: 'planner', version: undefined, source: '<bundled>', defined: plannerPlugin },
   { name: 'operator', version: undefined, source: '<bundled>', defined: operatorPlugin },
 ]