typeclaw 0.28.2 → 0.30.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/github-review-claim.ts

@@ -53,6 +53,12 @@ const WARN_POSITIVE_CLOSEOUT: readonly RegExp[] = [
   /\bshould be (fine|good)\b/,
   /\blooks resolved\b/,
   /\bseems resolved\b/,
+  // The canonical PR #672 close-out: "that addresses the concern", "addressed
+  // your feedback". On a PR the bot still blocks, this READS as a verdict and
+  // strands the block, so it escalates through the re-review guard. Demoted to
+  // ignore by the negation/future markers below ("haven't addressed", "to
+  // address").
+  /\baddress(es|ed)\b[^.!?]*\b(concern|feedback|review|comment|issue|point)/,
 ]
 
 // Negative warn phrases re-assert a block ("not done yet") instead of closing it
@@ -65,11 +71,17 @@ const WARN: readonly RegExp[] = [...WARN_POSITIVE_CLOSEOUT, ...WARN_NEGATIVE]
 // ignore. Blocking "I haven't approved" / "I'll approve" / "approved it earlier"
 // (answering a question) is the worst false-positive class, so it is checked first.
 const DEMOTE_TO_IGNORE: readonly RegExp[] = [
-  /\b(haven'?t|have not|did ?n'?t|did not|not yet|never)\b[^.!?]*\b(approv|request|resolv|block)/,
-  /\b(can'?t|cannot|won'?t|will not|wouldn'?t)\b[^.!?]*\b(approv|request|resolv|block)/,
-  /\bnot (approved|resolved|blocked|requesting)\b/,
+  /\b(haven'?t|have not|did ?n'?t|did not|not yet|never)\b[^.!?]*\b(approv|request|resolv|block|address)/,
+  /\b(can'?t|cannot|won'?t|will not|wouldn'?t)\b[^.!?]*\b(approv|request|resolv|block|address)/,
+  /\bnot (approved|resolved|blocked|requesting|addressed)\b/,
   /\b(not|no longer|hardly|barely)\b[^.!?]*\b(lgtm|looks good|looks fine|seems fine|should be (fine|good)|looks resolved|seems resolved)\b/,
   /\b(i'?ll|i will|going to|gonna|about to|planning to)\b[^.!?]*\b(approv|review|request|resolv)/,
+  // "address" demotion is restricted to explicit future/obligation forms only.
+  // A standalone `to` marker (e.g. "...to address my feedback") would match
+  // hard-claim prose like "Approved — thanks for updating the docs to address
+  // my feedback" and demote it to ignore BEFORE the BLOCK_APPROVE check, hiding
+  // a real verdict (the recovery path would then post it unguarded — PR #675).
+  /\b(i'?ll|i will|going to|gonna|about to|planning to|need(s)? to|have to|want(s)? to|trying to)\b[^.!?]*\baddress/,
   /\b(approved|resolved|requested changes)\b[^.!?]*\b(earlier|already|yesterday|before|last (review|time)|previously)\b/,
   /\b(pre|self|co|re|un|non|ai|admin|user|machine|auto) approved\b/,
 ]

package/src/channels/router.ts

@@ -32,6 +32,8 @@ import {
   StickyLedger,
   type EngagementDecision,
 } from './engagement'
+import { checkFalseReceipt } from './github-false-receipt'
+import { evaluateRereviewGuard } from './github-rereview-guard'
 import { resetReviewTurn } from './github-review-turn-ledger'
 import {
   MEMBERSHIP_COLD_FETCH_TIMEOUT_MS,
@@ -659,6 +661,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 +960,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 +1521,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 +2461,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 +2541,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) {
@@ -3103,6 +3127,25 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     //     the model's pre-tool commentary is the only user-facing text we have.
     //     Recovering it means the user gets *something* — strictly better than
     //     the historical silent drop.
+    // Egress-level GitHub review guards. The false-receipt and re-review
+    // stranding guards live inside the channel_reply / channel_send tool
+    // handlers, but recovery surfaces trailing assistant prose through a
+    // `source:'system'` send that never touches those handlers. A model that
+    // ends its turn with a close-out ack ("that addresses the concern") instead
+    // of calling a channel tool would otherwise post a verdict-shaped comment
+    // while still holding its own CHANGES_REQUESTED — stranding the PR (PR #672).
+    // Re-run the guards here and SUPPRESS on block: recovery cannot land the
+    // missing formal review on the model's behalf, and posting the unguarded ack
+    // is worse than dropping it — the next inbound re-prompts the model, which
+    // can then land the verdict properly.
+    const recoveryBlock = await evaluateRecoveryReviewGuards(live, assistantText)
+    if (recoveryBlock !== null) {
+      logger.warn(
+        `[channels] ${live.keyId}: suppressed recovery (github review guard) reason=${JSON.stringify(recoveryBlock)} text_len=${assistantText.length}`,
+      )
+      return
+    }
+
     logger.warn(
       `[channels] ${live.keyId}: recovering assistant_text_without_channel_tool source=${source} text_len=${assistantText.length}`,
     )
@@ -3121,6 +3164,38 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     }
   }
 
+  // Returns a block reason when the recovered text would be denied by a github
+  // review guard, or null when it is safe to surface. Non-github channels and
+  // non-PR chats short-circuit inside each guard (adapter / `pr:\d+` checks), so
+  // this is a no-op for everything except GitHub PR sessions.
+  const evaluateRecoveryReviewGuards = async (live: LiveSession, text: string): Promise<string | null> => {
+    const falseReceipt = checkFalseReceipt({
+      sessionId: live.sessionId,
+      adapter: live.key.adapter,
+      workspace: live.key.workspace,
+      chat: live.key.chat,
+      thread: live.key.thread,
+      text,
+      isContinue: false,
+      resolveReviewThread: false,
+    })
+    if (falseReceipt.kind === 'block') return falseReceipt.reason
+
+    const rereview = await evaluateRereviewGuard({
+      adapter: live.key.adapter,
+      workspace: live.key.workspace,
+      chat: live.key.chat,
+      thread: live.key.thread,
+      text,
+      wantsResolve: false,
+      isContinue: false,
+      getReviewState: (req) => getReviewState(req),
+    })
+    if (rereview.block) return rereview.reason
+
+    return null
+  }
+
   const getConsecutiveSendCount = (target: {
     adapter: ChannelKey['adapter']
     workspace: string
@@ -3550,6 +3625,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     removeReaction,
     registerTyping,
     unregisterTyping,
+    setTypingCapability,
     registerChannelNameResolver,
     unregisterChannelNameResolver,
     registerSelfIdentity,
@@ -3706,7 +3782,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 +4011,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 }