typeclaw 0.28.1 → 0.29.0

package/src/channels/github-rereview-guard.ts

@@ -1,4 +1,4 @@
-import { classifyReviewClaim } from './github-review-claim'
+import { classifyReviewClaim, isPositiveWarnCloseout } from './github-review-claim'
 import type { ReviewStateResult } from './types'
 
 // The re-review stranding guard. A bot that resolves a review thread (or posts a
@@ -17,6 +17,10 @@ export type RereviewGuardInput = {
   thread: string | null
   text: string | undefined
   wantsResolve: boolean
+  // A mid-turn status reply (continue:true) is not the turn's receipt, so it
+  // suppresses the warn-tier escalation below — but never the explicit resolve,
+  // which is a real mutation. Mirrors the false-receipt guard's continue rule.
+  isContinue: boolean
   getReviewState: (req: { adapter: 'github'; workspace: string; chat: string }) => Promise<ReviewStateResult>
   workspace: string
 }
@@ -32,14 +36,19 @@ export async function evaluateRereviewGuard(input: RereviewGuardInput): Promise<
   // a close-out ack in it ("Verified — that closes it") strands the block just
   // as a thread reply would. Only the resolve ACTION needs a thread; the
   // text-claim path fires regardless (caught by isCloseoutAttempt below).
-  if (!isCloseoutAttempt(input.wantsResolve, input.thread, input.text)) return ALLOW
+  if (!isCloseoutAttempt(input)) return ALLOW
 
   const state = await input.getReviewState({ adapter: 'github', workspace: input.workspace, chat: input.chat })
 
   // Fail closed: an unverifiable review state is treated as a live block, so the
   // bot never strands a re-review on a transient API failure.
   if (!state.ok) return { block: true, reason: unverifiableReason(state.error) }
-  if (!state.selfBlocking) return ALLOW
+  if (!state.selfBlocking) {
+    if (state.reviewDecision === 'REVIEW_REQUIRED' && isPositiveWarnCloseout(input.text ?? '')) {
+      return { block: true, reason: INITIAL_REVIEW_REQUIRED }
+    }
+    return ALLOW
+  }
 
   return { block: true, reason: state.approve ? STICKY_BLOCK_APPROVE_ENABLED : STICKY_BLOCK_APPROVE_DISABLED }
 }
@@ -47,11 +56,20 @@ export async function evaluateRereviewGuard(input: RereviewGuardInput): Promise<
 // Trigger when the model asks to resolve a thread (only meaningful with a
 // thread), OR when its reply reads as a close-out/verdict claim — the latter
 // strands the block whether or not it sits in a thread, so it fires for any PR
-// chat. Plain discussion replies (ignore/warn) do not fire.
-function isCloseoutAttempt(wantsResolve: boolean, thread: string | null, text: string | undefined): boolean {
-  if (wantsResolve && thread !== null) return true
-  const claim = classifyReviewClaim(text ?? '')
-  return claim === 'block-resolve' || claim === 'block-approve'
+// chat. Unlike the pure false-receipt classifier, this guard has the objective
+// review state available, so an approval-shaped warn reply ("looks good"/"lgtm")
+// is escalated to a closeout too: it only blocks when the bot actually holds a
+// live CHANGES_REQUESTED, so casual approval-shaped chatter on an unblocked PR
+// still posts. Only POSITIVE warn phrases escalate — negative ones ("needs
+// changes", "still needs work") re-assert a block rather than strand it, so they
+// stay non-firing. `continue:true` exempts the warn escalation (mid-turn
+// planning, not the receipt), but never the explicit resolve action. Plain
+// `ignore` text never fires.
+function isCloseoutAttempt(input: RereviewGuardInput): boolean {
+  if (input.wantsResolve && input.thread !== null) return true
+  const claim = classifyReviewClaim(input.text ?? '')
+  if (claim === 'block-resolve' || claim === 'block-approve') return true
+  return !input.isContinue && isPositiveWarnCloseout(input.text ?? '')
 }
 
 function unverifiableReason(error: string): string {
@@ -74,3 +92,9 @@ const STICKY_BLOCK_APPROVE_DISABLED =
   'dismiss your prior review via ' +
   '`gh api -X PUT /repos/<owner>/<repo>/pulls/<N>/reviews/<review_id>/dismissals -f message="..." -f event=DISMISS` ' +
   'if the blockers are fixed (or submit REQUEST_CHANGES if not), THEN resolve the thread / reply.'
+
+const INITIAL_REVIEW_REQUIRED =
+  'This PR still requires a formal GitHub review. A flat `LGTM` / `looks good` PR comment does not create ' +
+  'review state, so it leaves the PR awaiting review. Submit the reviewer verdict via ' +
+  '`gh api -X POST /repos/<owner>/<repo>/pulls/<N>/reviews` with event `APPROVE` when approval is enabled, ' +
+  'or event `COMMENT` when approval is disabled, then narrate only if needed.'

package/src/channels/github-review-claim.ts

@@ -41,19 +41,26 @@ const BLOCK_RESOLVE: readonly RegExp[] = [
   /\b(thanks,?|fixed,?) (looks )?resolved\b/,
 ]
 
-// Casual phrasing that might be chatter, not a formal close-out: allow + nudge.
-const WARN: readonly RegExp[] = [
+// Approval/resolve-shaped warn phrases: casual chatter that, on a PR the bot is
+// still blocking, READS as a close-out and so can strand the block. Split out so
+// the re-review guard can escalate only these — never the negative warn phrases
+// below, which re-assert a block rather than strand it.
+const WARN_POSITIVE_CLOSEOUT: readonly RegExp[] = [
   /\blgtm\b/,
   /\blooks good\b/,
   /\blooks fine\b/,
   /\bseems fine\b/,
   /\bshould be (fine|good)\b/,
-  /\bneeds changes\b/,
-  /\bstill needs work\b/,
   /\blooks resolved\b/,
   /\bseems resolved\b/,
 ]
 
+// Negative warn phrases re-assert a block ("not done yet") instead of closing it
+// out, so they are NOT close-out attempts — the re-review guard must ignore them.
+const WARN_NEGATIVE: readonly RegExp[] = [/\bneeds changes\b/, /\bstill needs work\b/]
+
+const WARN: readonly RegExp[] = [...WARN_POSITIVE_CLOSEOUT, ...WARN_NEGATIVE]
+
 // Negation / future-intent / past-reference markers DEMOTE a positive match to
 // 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.
@@ -61,15 +68,40 @@ 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(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)/,
   /\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/,
 ]
 
+const QUESTION_CONTEXT =
+  /(?:^|\b)(who|what|when|where|why|how|was|were|is|are|did|do|does|has|have|can|could|would|should)\b[^.!?]*\?/
+
 export function classifyReviewClaim(rawText: string): ReviewClaim {
-  const text = normalize(rawText)
-  if (text === '') return 'ignore'
+  const segments = claimSegments(rawText)
+  if (segments.length === 0) return 'ignore'
+
+  const claims = segments.map(classifySegment)
+
+  if (claims.includes('block-approve')) return 'block-approve'
+  if (claims.includes('block-request-changes')) return 'block-request-changes'
+  if (claims.includes('block-resolve')) return 'block-resolve'
+  if (claims.includes('warn')) return 'warn'
+  return 'ignore'
+}
 
+// True only for warn-tier replies whose phrasing reads as an approval/resolve
+// close-out (e.g. "looks good", "lgtm"), excluding negative warn phrases like
+// "needs changes" that re-assert a block. The re-review guard uses this to
+// escalate just the stranding-shaped warns, not the whole warn bucket.
+export function isPositiveWarnCloseout(rawText: string): boolean {
+  if (classifyReviewClaim(rawText) !== 'warn') return false
+  return claimSegments(rawText).some((segment) => WARN_POSITIVE_CLOSEOUT.some((re) => re.test(segment)))
+}
+
+function classifySegment(text: string): ReviewClaim {
   if (DEMOTE_TO_IGNORE.some((re) => re.test(text))) return 'ignore'
+  if (QUESTION_CONTEXT.test(text)) return 'ignore'
 
   // Block-tier wins over warn-tier: an unambiguous "approved" in a casual message
   // is still a formal claim.
@@ -80,6 +112,21 @@ export function classifyReviewClaim(rawText: string): ReviewClaim {
   return 'ignore'
 }
 
+function claimSegments(text: string): string[] {
+  return redactQuotedAndCode(text)
+    .split(/(?<=[.!?])\s+|\n+/)
+    .map(normalize)
+    .filter((segment) => segment !== '')
+}
+
+function redactQuotedAndCode(text: string): string {
+  return text
+    .replace(/```[\s\S]*?```/g, ' ')
+    .replace(/`[^`\n]*`/g, ' ')
+    .replace(/"[^"\n]*"|“[^”\n]*”|‘[^’\n]*’/g, ' ')
+    .replace(/^\s*>.*$/gm, ' ')
+}
+
 // Strips markdown/emoji noise so "**Approved!**" and "approved" classify alike,
 // keeping apostrophes + sentence punctuation that the negation regexes rely on.
 function normalize(text: string): string {

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>()
@@ -1422,8 +1428,20 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         unsubTypingActivity: null,
         unsubTodoOutcome: null,
       }
+      // Tracks the `turnSeq` a provider-error notice was last POSTED for, so the
+      // channel surfaces at most one notice per turn. The upstream SDK retries
+      // internally, and each retry emits its own `message_end` with
+      // `stopReason: 'error'` — without this gate a single failing turn posts N
+      // identical "⚠️ upstream provider failed" notices (one per retry). Logs
+      // still record every attempt; only the user-facing notice is deduped.
+      let lastProviderErrorNoticeTurn: number | undefined
       live.unsubProviderErrors = subscribeProviderErrors(created.session, (err) => {
         logger.error(`[channels] ${live.keyId}: LLM call failed: ${err.message}`)
+        // Suppress duplicate notices for the SAME turn (retry storm). Set the
+        // marker BEFORE the async send so a synchronous burst of retry events
+        // can't each slip past the check and enqueue their own notice.
+        if (lastProviderErrorNoticeTurn === live.turnSeq) return
+        lastProviderErrorNoticeTurn = live.turnSeq
         // A provider soft-error (rate/usage limit, billing, malformed response)
         // ends the turn with no assistant text, so the human otherwise sees
         // silence. Surface the REDACTED `safeMessage` (never the raw provider
@@ -1501,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)
     }
   }
 
@@ -2435,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,
@@ -2510,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) {
@@ -3538,6 +3572,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     removeReaction,
     registerTyping,
     unregisterTyping,
+    setTypingCapability,
     registerChannelNameResolver,
     unregisterChannelNameResolver,
     registerSelfIdentity,
@@ -3694,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.)
@@ -3923,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

@@ -192,8 +192,9 @@ export const SEEDED_GITHUB_EVENT_ALLOWLISTS: readonly (readonly string[])[] = [
 // prefix is implied by this field living under the review config); `off` is the
 // disable sentinel, matching the `engagement.stickiness: 'off'` convention:
 //   - 'review_requested' — review only when the bot is requested (default)
-//   - 'opened'           — review every non-draft PR as soon as it opens; draft
-//                          PRs are skipped until an explicit review_requested
+//   - 'opened'           — review every non-draft PR as soon as it opens; a draft
+//                          PR wakes no session and is reviewed once it turns ready
+//                          (ready_for_review) or the bot is explicitly requested
 //   - 'off'              — disable code review entirely
 export const GITHUB_REVIEW_ON_VALUES = ['review_requested', 'opened', 'off'] as const
 
@@ -242,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
@@ -395,19 +401,24 @@ export type ReviewStateRequest = {
   chat: string
 }
 
-// `selfBlocking` is the answer the guard acts on: true means the bot's latest
-// effective formal review is its own CHANGES_REQUESTED (COMMENTED reviews are
-// ignored — they never clear the sticky block, GitHub's own rule). `approve`
-// mirrors `channels.github.review.approve` so the guard's denial text can tell
-// the model whether to land a fresh APPROVE or to DISMISS its prior review.
+// `selfBlocking` is the answer the guard acts on for re-reviews: true means the
+// bot's latest effective formal review is its own CHANGES_REQUESTED (COMMENTED
+// reviews are ignored — they never clear the sticky block, GitHub's own rule).
+// `reviewDecision` is GitHub's aggregate PR review status when GraphQL can
+// provide it; REVIEW_REQUIRED means an approval-shaped flat comment would still
+// leave the PR awaiting a formal review. `approve` mirrors
+// `channels.github.review.approve` so the guard's denial text can tell the model
+// whether to land a fresh APPROVE or to DISMISS its prior review.
 //
 // On `ok: false` the caller MUST fail closed: an unverifiable review state is
 // treated like a live block, so the bot never claims close-out when the runtime
 // could not confirm the platform-side verdict.
 export type ReviewStateResult =
-  | { ok: true; selfBlocking: boolean; approve: boolean }
+  | { ok: true; selfBlocking: boolean; approve: boolean; reviewDecision?: GithubReviewDecision }
   | { ok: false; error: string; code?: 'unsupported' | 'not-found' | 'permission-denied' | 'transient' }
 
+export type GithubReviewDecision = 'APPROVED' | 'CHANGES_REQUESTED' | 'REVIEW_REQUIRED'
+
 // Registered per-adapter on the ChannelRouter, last-write-wins like the
 // review-thread resolver. Adapters that never register one make `getReviewState`
 // answer `unsupported`.

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 }