typeclaw 0.37.3 → 0.37.5

package/src/channels/router.ts

@@ -24,6 +24,7 @@ import type { HookBus } from '@/plugin'
 import { extractClaimCode } from '@/role-claim'
 import type { Stream } from '@/stream'
 
+import { extractMentionedUserIds } from './adapters/mention-hints'
 import { formatChannelCommandHelp } from './commands'
 import { detectContinuationWillingness } from './continuation-willingness'
 import {
@@ -97,6 +98,11 @@ export const MAX_DEBOUNCE_MS = 4000
 export const HOT_THRESHOLD_MS = 3000
 export const MAX_CONSECUTIVE_ABORTS = 3
 export const CONTEXT_BUFFER_SIZE = 20
+// Observed ("Recent context") messages are awareness-only and replayed in full
+// on every turn (uncached), so one long paste would otherwise re-bloat every
+// subsequent turn until it ages out. Cap each observed message's text; the
+// addressed current message is never capped (it's the actual request).
+export const OBSERVED_MESSAGE_MAX_CHARS = 800
 // Discord's typing indicator expires after ~10s; an 8s heartbeat keeps it
 // continuously visible while we debounce + generate without spamming the API.
 export const TYPING_HEARTBEAT_MS = 8000
@@ -106,13 +112,18 @@ export const TYPING_HEARTBEAT_MS = 8000
 // turns a temporary status into a permanent-looking artifact.
 //
 // The cap is measured from `live.typingStartedAt`, which is refreshed by
-// two signals of life (see `bumpTypingActivity`):
+// these signals of life (see `bumpTypingActivity`):
 //   1. Each new `drain()` iteration (a new turn is starting).
 //   2. Each `tool_execution_end` from the agent session (a tool just
 //      completed — the prompt is progressing, not stuck).
-// A 2-minute bash command that emits no intermediate events still trips
-// the cap, but a chatty agent running long tools stays under it
-// indefinitely. The cap exists to catch *silence*, not duration.
+//   3. Each streaming token (`message_update` carrying a `text_delta` or
+//      `thinking_delta`) — the model is actively generating, even on a
+//      pure-text reply that calls no tools.
+// Signal 3 is what keeps a long conversational reply (no tool calls, just
+// minutes of streamed text or extended thinking) under the cap: without it,
+// such a turn emits no `tool_execution_end` and the indicator was paused
+// mid-generation. A genuinely stuck model call — no tokens, no tools — still
+// trips the cap. The cap exists to catch *silence*, not duration.
 export const MAX_TYPING_HEARTBEAT_MS = 2 * 60 * 1000
 
 // Idle GC: a LiveSession whose `lastInboundAt` is older than
@@ -255,6 +266,28 @@ export const EMPTY_TURN_RETRY_NUDGE = [
 // drop so the human is never left staring at dead air after a degenerate turn.
 export const EMPTY_TURN_FALLBACK_TEXT =
   "⚠️ I got stuck putting together a reply and couldn't finish. Could you rephrase or try again?"
+// Distinct from EMPTY_TURN_RETRY_NUDGE: that one diagnoses budget exhaustion
+// ("ran out of output budget"), which is FALSE for a clean `stop` with empty
+// text. This nudge names the real failure — a turn that ended sending nothing
+// to a message addressed to the agent in a one-on-one conversation — and steers
+// the model to either answer or record the silence explicitly (skip_response /
+// NO_REPLY) rather than ending empty again.
+export const COLD_START_REPLY_NUDGE = [
+  '---',
+  '**[SYSTEM MESSAGE — not from a human]**',
+  '',
+  'Your previous turn ended without sending anything, but the last message was',
+  'addressed to you in a direct, one-on-one conversation — ending silent there',
+  'reads as ignoring the person. This is an automated signal from the channel',
+  'router, not a message from anyone in the chat. **Do not acknowledge or reply',
+  'to this notice itself.**',
+  '',
+  'Answer the last user message now via your channel reply tool. If you truly',
+  'have nothing to add, call `skip_response({ reason })` (preferred) or end with',
+  'exactly `NO_REPLY` so the silence is recorded — do not just end empty.',
+  '',
+  '---',
+].join('\n')
 // At most one continuation nudge per logical turn. Stricter than the empty-turn
 // retry budget (2) because the turn ALREADY delivered a user-facing reply — this
 // is a one-shot correction offer, not recovery from no output.
@@ -767,6 +800,20 @@ type LiveSession = {
   // decision used, so the prompt nudge and sticky suppression agree on
   // "is this a multi-human group". Read by composeTurnPrompt().
   multiHumanGroup: boolean
+  // True when this live session was born from a cold-start (no persisted
+  // session existed — first contact or a stale-rollover after long idle), as
+  // opposed to rehydrating an existing session. Combined with `turnSeq === 0`
+  // it pinpoints the very first prompt of a freshly woken session.
+  createdFromColdStart: boolean
+  // Set in route() when the FIRST turn of a cold-start session engages via the
+  // solo-human "answer everything" fallback (not an explicit mention/reply/DM,
+  // not a multi-human group). Read by validateChannelTurn: a BARE-EMPTY stop on
+  // such a turn is a model whiff on a direct one-on-one question, not deliberate
+  // silence, so it earns an empty-turn retry instead of a silent no_reply.
+  // Recomputed on every engage, so it self-clears once turnSeq leaves the first
+  // turn; explicit NO_REPLY / skip_response and any turn that already sent stay
+  // on the historical silent path.
+  coldStartSoloFallbackTurnActive: boolean
   membershipFetch: Promise<MembershipCount | null> | null
   // Provider soft-error (`stopReason: 'error'`) captured during the current
   // turn, deferred to turn-end. Upstream surfaces transient errors (e.g.
@@ -1668,6 +1715,8 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         consecutiveEngagedPeerBotTurns: 0,
         loopGuardActive: false,
         multiHumanGroup: false,
+        createdFromColdStart: isColdStart,
+        coldStartSoloFallbackTurnActive: false,
         membershipFetch,
         pendingProviderError: null,
         destroyed: false,
@@ -1883,8 +1932,15 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
 
   const subscribeTypingActivity = (session: AgentSession, live: LiveSession): (() => void) => {
     return session.subscribe((event) => {
-      if (event.type !== 'tool_execution_end') return
-      bumpTypingActivity(live)
+      if (event.type === 'tool_execution_end') {
+        bumpTypingActivity(live)
+        return
+      }
+      if (event.type !== 'message_update') return
+      const streamed = event.assistantMessageEvent.type
+      if (streamed === 'text_delta' || streamed === 'thinking_delta') {
+        bumpTypingActivity(live)
+      }
     })
   }
 
@@ -2552,7 +2608,8 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
 
     const membership = await membershipForEngagement(live)
 
-    live.multiHumanGroup = isMultiHumanGroup(event.isDm, countEffectiveHumans(live.participants, membership, now()))
+    const effectiveHumans = countEffectiveHumans(live.participants, membership, now())
+    live.multiHumanGroup = isMultiHumanGroup(event.isDm, effectiveHumans)
 
     const decision: EngagementDecision = decideEngagement({
       message: event,
@@ -2578,6 +2635,22 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
 
     publishInbound(event, 'engage', live.sessionId)
 
+    // Arm cold-start bare-empty recovery only for the exact incident shape: the
+    // FIRST prompt (`turnSeq === 0`) of a freshly cold-started session that
+    // engaged via the solo-human answer-everything fallback — a lone human, no
+    // explicit mention/reply/DM, not a multi-human group. Recomputed on every
+    // engage so it self-clears once the first turn advances `turnSeq`; explicit
+    // address (mention/reply/DM) keeps the historical silent-on-empty path.
+    live.coldStartSoloFallbackTurnActive =
+      live.createdFromColdStart &&
+      live.turnSeq === 0 &&
+      effectiveHumans <= 1 &&
+      !event.authorIsBot &&
+      !event.isDm &&
+      !event.isBotMention &&
+      event.replyToBotMessageId === null &&
+      !live.multiHumanGroup
+
     const engageReaction = autoReactOnEngage(event)
 
     updateLoopGuard(live, event)
@@ -3315,11 +3388,21 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
       const disengagedThisTurn = live.disengagedTurn !== null && live.disengagedTurn === live.turnSeq
       const adapterConfig = options.configForAdapter(msg.adapter)
       if (adapterConfig && !disengagedThisTurn) {
-        const targetIds = Array.from(
-          live.currentTurnAuthorIds.size > 0 ? live.currentTurnAuthorIds : live.lastTurnAuthorIds,
-        )
-        if (targetIds.length > 0) {
-          grantStickyForReplyTargets(stickyLedger, keyId, targetIds, adapterConfig.engagement, now())
+        const targets = new Set(live.currentTurnAuthorIds.size > 0 ? live.currentTurnAuthorIds : live.lastTurnAuthorIds)
+        // A user the agent addresses by @-mention is a reply target too: their
+        // next message answers us without re-mentioning the bot. Granting them
+        // sticky closes the gap where the agent asks "<@U123> can you confirm?"
+        // and that user's plain reply was observed until they re-pinged.
+        // Self-mentions (e.g. a quoted inbound) are excluded — we credit the
+        // OTHERS we addressed, not ourselves.
+        if (text !== undefined) {
+          const selfId = resolveSelfIdentity(live.key)?.id
+          for (const id of extractMentionedUserIds(msg.adapter, text)) {
+            if (id !== selfId) targets.add(id)
+          }
+        }
+        if (targets.size > 0) {
+          grantStickyForReplyTargets(stickyLedger, keyId, Array.from(targets), adapterConfig.engagement, now())
         }
       }
       const turnCount = live.consecutiveSends.get(sendKey) ?? 0
@@ -3592,6 +3675,36 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     let assistantText = candidateText
 
     if (endsWithNoReplySignal(assistantText)) {
+      // A BARE-EMPTY stop (no visible text, not an explicit NO_REPLY token) on
+      // the armed cold-start solo-human fallback turn is the production "dropped
+      // the owner's first question" shape — a model whiff on a direct one-on-one
+      // question, not a deliberate decline. Give it the bounded empty-turn retry
+      // with a dedicated nudge; on exhaustion post the visible fallback so the
+      // human is never stranded on silence. Gated hard so deliberate silence
+      // still stays silent: explicit NO_REPLY (non-empty trim), any turn that
+      // already sent (successfulChannelSends moved), a queued fresh inbound (the
+      // next drain answers it), and every turn outside the armed cold-start solo
+      // path all fall through to the historical no_reply below.
+      if (
+        assistantText.trim() === '' &&
+        source === 'leaf' &&
+        live.coldStartSoloFallbackTurnActive &&
+        live.currentTurnAuthorId !== null &&
+        live.successfulChannelSends === successfulSendsBeforePrompt &&
+        live.promptQueue.length === 0
+      ) {
+        if (live.emptyTurnRetries < MAX_EMPTY_TURN_RETRIES) {
+          live.emptyTurnRetries++
+          logger.warn(
+            `[channels] ${live.keyId} empty_turn_retry attempt=${live.emptyTurnRetries}/${MAX_EMPTY_TURN_RETRIES} ` +
+              `cause=cold_start_solo_bare_empty`,
+          )
+          live.pendingSystemReminders.push(COLD_START_REPLY_NUDGE)
+          return
+        }
+        await postEmptyTurnFallback('cold_start_solo_bare_empty_retries_exhausted')
+        return
+      }
       const leakedReasoning = !isNoReplySignal(assistantText)
       logger.info(`[channels] ${live.keyId} no_reply${leakedReasoning ? ' (with_leaked_reasoning)' : ''}`)
       return
@@ -4462,7 +4575,7 @@ function composeTurnPrompt(
   if (observed.length > 0) {
     parts.push('## Recent context (not addressed to you, for awareness only)')
     for (const o of observed) {
-      parts.push(formatInboundPromptLines(o, adapter))
+      parts.push(formatInboundPromptLines(o, adapter, OBSERVED_MESSAGE_MAX_CHARS))
     }
     parts.push('')
   }
@@ -4521,10 +4634,22 @@ function formatAuthorLine(
   authorName: string,
   authorIsBot: boolean,
   text: string,
+  maxChars?: number,
 ): string {
   const tag = authorIsBot ? ' [bot]' : ''
   const stamp = ts > 0 ? `[${new Date(ts).toISOString()}] ` : ''
-  return `${stamp}${formatAuthorReference(adapter, authorId, authorName)} (${authorName})${tag}: ${text}`
+  return `${stamp}${formatAuthorReference(adapter, authorId, authorName)} (${authorName})${tag}: ${capObservedText(text, maxChars)}`
+}
+
+// Cap by whole code points so truncation never splits a surrogate pair (emoji,
+// astral-plane chars) into a dangling half. `text.length` (UTF-16 code units) is
+// a cheap upper bound on the code-point count, so a string already within the
+// cap skips the array build.
+function capObservedText(text: string, maxChars: number | undefined): string {
+  if (maxChars === undefined || text.length <= maxChars) return text
+  const points = Array.from(text)
+  if (points.length <= maxChars) return text
+  return `${points.slice(0, maxChars).join('')} […truncated]`
 }
 
 function formatInboundPromptLines(
@@ -4537,10 +4662,19 @@ function formatInboundPromptLines(
     referenceContext?: InboundReferenceContext
   },
   adapter: AdapterId,
+  maxTextChars?: number,
 ): string {
   const lines = inbound.referenceContext?.sources.map(renderQuoteAnchor) ?? []
   lines.push(
-    formatAuthorLine(inbound.ts, adapter, inbound.authorId, inbound.authorName, inbound.authorIsBot, inbound.text),
+    formatAuthorLine(
+      inbound.ts,
+      adapter,
+      inbound.authorId,
+      inbound.authorName,
+      inbound.authorIsBot,
+      inbound.text,
+      maxTextChars,
+    ),
   )
   return lines.join('\n')
 }

package/src/cli/dreams.ts

@@ -1,9 +1,9 @@
 import { defineCommand } from 'citty'
 
 import { type DreamEntry, renderListRow, runDreams, type ViewAction } from '@/dreams'
-import { findAgentDir } from '@/init'
 
 import { createEscController } from './inspect-controller'
+import { requireAgentDir } from './require-agent-dir'
 import { c, cancel, errorLine, isCancel, prepareStdinForClack } from './ui'
 
 const ESC_DEBOUNCE_MS = 50
@@ -31,7 +31,7 @@ export const dreamsCommand = defineCommand({
     },
   },
   async run({ args }) {
-    const cwd = findAgentDir(process.cwd()) ?? process.cwd()
+    const cwd = requireAgentDir()
     const color = useColor()
     const limit = parseLimit(args.limit)
     const interactive = isInteractive() && args.json !== true

package/src/cli/init.ts

@@ -39,6 +39,7 @@ import {
   hasExistingOAuthCredentials,
   isDirectoryNonEmpty,
   isHatched,
+  isInitialized,
   readExistingProviderApiKey,
   runInit,
   type GithubInitCredentials,
@@ -139,18 +140,22 @@ export const init = defineCommand({
     if (existingAgent !== null && existingAgent !== cwd) {
       console.error(
         errorLine(
-          `Refusing to init: a TypeClaw agent already exists at ${existingAgent}. Nested agents are not supported.`,
+          `Refusing to init: a TypeClaw agent already exists at ${existingAgent}. Nested agents are not supported. Run init from a directory that is not inside an existing agent.`,
         ),
       )
       process.exit(1)
     }
 
     if (await isHatched(cwd)) {
-      console.error(errorLine(`TypeClaw has already hatched in ${cwd}.`))
+      console.error(
+        errorLine(
+          `TypeClaw has already hatched in ${cwd}. Use \`typeclaw tui\` to attach or \`typeclaw start\` to run it; init in a different directory to create another agent.`,
+        ),
+      )
       process.exit(1)
     }
 
-    if (isDirectoryNonEmpty(cwd)) {
+    if (shouldConfirmNonEmptyDirectory(cwd)) {
       const proceed = await confirm({
         message: `You're at ${cwd}. The directory is not empty. Do you want to proceed?`,
         initialValue: false,
@@ -192,7 +197,7 @@ export const init = defineCommand({
             [
               'OAuth credentials were saved to `secrets.json` before you aborted.',
               'Re-run `typeclaw init` here to pick up where you left off (the credentials',
-              'will be reused), or delete `secrets.json` if you want a clean restart.',
+              'will be reused), or run `typeclaw init --reset` to start fresh.',
             ].join('\n'),
             'Saved OAuth credentials',
           )
@@ -288,6 +293,14 @@ export const init = defineCommand({
       })
     } catch (error) {
       console.error(errorLine(error instanceof Error ? error.message : String(error)))
+      note(
+        [
+          'Your answers are saved.',
+          'Re-run `typeclaw init` here to resume, or `typeclaw init --reset` to start fresh.',
+          'Run `typeclaw doctor` to diagnose host/Docker issues.',
+        ].join('\n'),
+        'init failed',
+      )
       process.exit(1)
     }
 
@@ -296,6 +309,19 @@ export const init = defineCommand({
       process.exit(1)
     }
 
+    if (!hatchingOk) {
+      note(
+        [
+          'The container was built but the agent did not come up.',
+          'Check logs: `typeclaw logs`',
+          'Diagnose: `typeclaw doctor`',
+          'Retry once fixed: `typeclaw start` (your setup is saved).',
+        ].join('\n'),
+        'Hatching failed',
+      )
+      process.exit(1)
+    }
+
     if (githubCredentials?.tunnelProvider === 'none') {
       log.warn(
         'Webhook delivery is disabled until you add a `tunnels[]` entry or set `channels.github.webhookUrl` manually.',
@@ -335,6 +361,10 @@ export const init = defineCommand({
   },
 })
 
+export function shouldConfirmNonEmptyDirectory(cwd: string): boolean {
+  return isDirectoryNonEmpty(cwd) && !isInitialized(cwd)
+}
+
 interface WizardState {
   catalog?: { options: ModelOption[]; source: 'models.dev' | 'curated'; warning?: string }
   vendorId?: KnownProviderVendorId
@@ -1750,20 +1780,24 @@ function reportProgress(
         s.stop(event.result.ok ? 'Logged in.' : `OAuth login failed: ${event.result.reason}`)
         break
       case 'install':
-        s.stop(event.result.ok ? 'Dependencies installed.' : `Skipped bun install: ${event.result.reason}`)
+        if (event.result.ok) {
+          s.stop('Dependencies installed.')
+        } else {
+          s.error(`Dependency install failed: ${event.result.reason}`)
+        }
         break
       case 'dockerfile':
         if (event.result.ok) {
           s.stop(event.result.devMode ? 'Dockerfile written (dev mode).' : 'Dockerfile written.')
         } else {
-          s.stop(`Skipped Dockerfile: ${event.result.reason}`)
+          s.error(`Dockerfile generation failed: ${event.result.reason}`)
         }
         break
       case 'git':
         if (event.result.ok) {
           s.stop(event.result.skipped ? 'Git repository already exists.' : 'Git repository initialized.')
         } else {
-          s.stop(`Skipped git init: ${event.result.reason}`)
+          s.error(`git init failed — continuing without a repo: ${event.result.reason}`)
         }
         break
     }

package/src/cli/inspect.ts

@@ -1,7 +1,6 @@
 import { defineCommand } from 'citty'
 
 import { requireContainerRunning, resolveHostPort, resolveTuiToken } from '@/container'
-import { findAgentDir } from '@/init'
 import {
   fetchLiveSessions,
   listViewerItems,
@@ -20,6 +19,7 @@ import {
 import { originLabel, shortSessionId } from '@/inspect/label'
 
 import { createTailScope } from './inspect-controller'
+import { requireAgentDir } from './require-agent-dir'
 import { cancel, c, errorLine, isCancel, prepareStdinForClack } from './ui'
 
 const ESC_DEBOUNCE_MS = 50
@@ -51,7 +51,7 @@ export const inspectCommand = defineCommand({
     },
   },
   async run({ args }) {
-    const cwd = findAgentDir(process.cwd()) ?? process.cwd()
+    const cwd = requireAgentDir()
     const color = useColor()
     const sessionArg = typeof args.session === 'string' ? args.session : undefined
     const filterArg = typeof args.filter === 'string' ? args.filter : undefined

package/src/cli/logs.ts

@@ -1,9 +1,9 @@
 import { defineCommand } from 'citty'
 
 import { logs, parseTailValue } from '@/container'
-import { findAgentDir } from '@/init'
 
 import { runInspectViewer } from './inspect'
+import { requireAgentDir } from './require-agent-dir'
 import { c, errorLine } from './ui'
 
 export const logsCommand = defineCommand({
@@ -30,7 +30,7 @@ export const logsCommand = defineCommand({
     },
   },
   async run({ args }) {
-    const cwd = findAgentDir(process.cwd()) ?? process.cwd()
+    const cwd = requireAgentDir()
 
     let tail: string | undefined
     if (args.tail !== undefined) {

package/src/cli/qr.ts

@@ -6,6 +6,8 @@ import { promisify } from 'node:util'
 
 import QRCode from 'qrcode'
 
+import { isMacOS, isWindows } from '@/shared'
+
 const execFileAsync = promisify(execFile)
 
 // The upstream LINE SDK's QR login hands back a raw auth URL
@@ -108,12 +110,11 @@ async function writeQRHtmlFile(
 }
 
 async function openInBrowser(filePath: string): Promise<void> {
-  const platform = process.platform
-  if (platform === 'darwin') {
+  if (isMacOS()) {
     await execFileAsync('open', [filePath])
     return
   }
-  if (platform === 'win32') {
+  if (isWindows()) {
     await execFileAsync('cmd', ['/c', 'start', '', filePath])
     return
   }

package/src/cli/require-agent-dir.ts

@@ -0,0 +1,31 @@
+import { findAgentDir, isInitialized } from '@/init'
+
+import { errorLine } from './ui'
+
+export type RequiredAgentDir = { ok: true; cwd: string } | { ok: false; message: string }
+
+const NOT_AN_AGENT_FOLDER = 'TypeClaw config file not found. Run `typeclaw init` first, or cd into an agent folder.'
+
+// Operational host-stage commands (inspect, tui, logs, stop, shell, dreams) act
+// on a specific agent's container or on-disk state, so they must run from inside
+// an agent folder. The `findAgentDir(...) ?? startDir` fallback every caller used
+// silently degraded these commands into an agent-less view — e.g. `inspect` would
+// warn "container not running" and then offer only the container-logs row — instead
+// of failing. Resolving to a fail result keeps the existence check explicit.
+//
+// Diagnostic commands (status, doctor, role list) deliberately tolerate a missing
+// agent folder and must NOT use this gate.
+export function resolveRequiredAgentDir(startDir: string): RequiredAgentDir {
+  const cwd = findAgentDir(startDir) ?? startDir
+  if (!isInitialized(cwd)) return { ok: false, message: NOT_AN_AGENT_FOLDER }
+  return { ok: true, cwd }
+}
+
+export function requireAgentDir(startDir: string = process.cwd()): string {
+  const result = resolveRequiredAgentDir(startDir)
+  if (!result.ok) {
+    console.error(errorLine(result.message))
+    process.exit(1)
+  }
+  return result.cwd
+}

package/src/cli/shell.ts

@@ -1,8 +1,8 @@
 import { defineCommand } from 'citty'
 
 import { shell } from '@/container'
-import { findAgentDir } from '@/init'
 
+import { requireAgentDir } from './require-agent-dir'
 import { c, errorLine } from './ui'
 
 export const shellCommand = defineCommand({
@@ -18,7 +18,7 @@ export const shellCommand = defineCommand({
     },
   },
   async run({ args }) {
-    const cwd = findAgentDir(process.cwd()) ?? process.cwd()
+    const cwd = requireAgentDir()
 
     console.log(c.cyan(`Attaching ${args.shell} inside the container...`))
 

package/src/cli/stop.ts

@@ -1,8 +1,8 @@
 import { defineCommand } from 'citty'
 
 import { stop } from '@/container'
-import { findAgentDir } from '@/init'
 
+import { requireAgentDir } from './require-agent-dir'
 import { c, spinner } from './ui'
 
 export const stopCommand = defineCommand({
@@ -11,7 +11,7 @@ export const stopCommand = defineCommand({
     description: 'stop the agent container (host stage)',
   },
   async run() {
-    const cwd = findAgentDir(process.cwd()) ?? process.cwd()
+    const cwd = requireAgentDir()
 
     const s = spinner()
     s.start('Stopping container...')

package/src/cli/tui.ts

@@ -1,12 +1,12 @@
 import { defineCommand } from 'citty'
 
 import { requireContainerRunning, resolveHostPort, resolveTuiToken } from '@/container'
-import { findAgentDir } from '@/init'
 import { CLI_VERSION } from '@/init/cli-version'
 import { runTuiViewer } from '@/inspect'
 import { formatVersionMismatchWarning } from '@/tui'
 
 import { runInspectViewer } from './inspect'
+import { requireAgentDir } from './require-agent-dir'
 import { errorLine } from './ui'
 
 export const tui = defineCommand({
@@ -27,9 +27,22 @@ export const tui = defineCommand({
     },
   },
   async run({ args }) {
-    const cwd = findAgentDir(process.cwd()) ?? process.cwd()
-    const resolveUrl: () => Promise<string> =
-      args.url !== undefined ? async () => args.url as string : () => defaultUrl(cwd)
+    // An explicit --url targets an agent over the wire and needs no local agent
+    // folder — only the default-URL discovery and the esc-detach picker read
+    // local state. Require an agent folder only when --url is absent, mirroring
+    // how reload/cron/role claim gate their default-target path, not the whole
+    // command.
+    const explicitUrl = typeof args.url === 'string' ? args.url : undefined
+    let cwd: string | undefined
+    let resolveUrl: () => Promise<string>
+    if (explicitUrl === undefined) {
+      const agentDir = requireAgentDir()
+      cwd = agentDir
+      resolveUrl = () => defaultUrl(agentDir)
+    } else {
+      cwd = undefined
+      resolveUrl = async () => explicitUrl
+    }
 
     const result = await runTuiViewer({
       resolveUrl,
@@ -45,8 +58,9 @@ export const tui = defineCommand({
     // can pick another session or the container logs — `tui` is just a deep-link
     // into the session viewer, pre-opened on the live session. allowWritable
     // is false because detaching ended the live session, so no row may be
-    // offered as a writable "live TUI" anymore.
-    if (result.ok && result.escToPicker === true) {
+    // offered as a writable "live TUI" anymore. A --url-only run has no local
+    // agent folder to browse, so it exits instead of opening the local picker.
+    if (result.ok && result.escToPicker === true && cwd !== undefined) {
       const viewerExit = await runInspectViewer({ cwd, allowWritable: false })
       process.exit(viewerExit)
       return

package/src/cli/ui.ts

@@ -14,14 +14,18 @@ type ClackInput = Pick<NodeJS.ReadStream, 'isTTY' | 'setRawMode' | 'resume'>
 // Bun's readline keypress wiring only transitions stdin into flowing raw mode
 // reliably once the stream has already been resumed; on a never-resumed stdin
 // the picker renders but arrow keys echo as raw `^[[B` and never advance it.
-// Local terminals dodge this because stdin was already flowing. So before every
-// picker: clear any stale raw mode for a clean baseline, then resume the stream.
-// Never pause() here — a previously-paused process.stdin does not reliably
-// re-flow under Bun, which is the same failure this resume() is fixing.
+// Local terminals dodge this because stdin was already flowing. Worse, after a
+// pi-tui viewer (ProcessTerminal.stop() calls process.stdin.pause()), a plain
+// resume() does NOT re-flow stdin under Bun, so the next picker is dead over
+// SSH. Toggling raw mode on->off forces the TTY read back into flowing mode;
+// the trailing resume() + non-raw state is the baseline clack expects.
+// Never pause() here — a paused process.stdin does not reliably re-flow.
 export function prepareStdinForClack(input: ClackInput = process.stdin): void {
   if (!input.isTTY) return
+  input.resume()
   if (typeof input.setRawMode === 'function') {
     try {
+      input.setRawMode(true)
       input.setRawMode(false)
     } catch {
       /* terminal already torn down */

package/src/container/shared.ts

@@ -1,3 +1,4 @@
+import { createHash } from 'node:crypto'
 import { basename, resolve } from 'node:path'
 
 export type DockerExecResult = { exitCode: number; stdout: string; stderr: string }
@@ -249,8 +250,25 @@ export function imageTagFromCwd(cwd: string): string {
 }
 
 // Docker container names must match [a-zA-Z0-9][a-zA-Z0-9_.-]*.
+//
+// Non-ASCII names (Korean/CJK/Cyrillic/accented Latin — the common Windows case
+// where the profile folder is a localized display name, e.g. C:\Users\사용자\봇)
+// have every out-of-charset character collapsed to a dash, so distinct folders
+// reduce to the SAME string: '봇' and '집' both → 'tc--'. The container name keys
+// hostd registration and the secrets key path, so that collision is silent
+// host-side state clobbering, not cosmetics. For any name carrying a non-ASCII
+// char we append a deterministic hash of the original (cf. makeUntitledSlug in
+// the memory plugin) to keep distinct folders distinct; surviving ASCII stays a
+// readable prefix. ASCII-only names take the original branch — never renamed.
 function sanitizeContainerName(name: string): string {
   const cleaned = name.replace(/[^a-zA-Z0-9_.-]/g, '-')
+  if (/[^\u0000-\u007f]/.test(name)) {
+    const hash = createHash('sha256').update(name).digest('hex').slice(0, 8)
+    const remnant = cleaned.replace(/-+/g, '-').replace(/^-+|-+$/g, '')
+    if (remnant === '') return `tc-${hash}`
+    const base = /^[a-zA-Z0-9]/.test(remnant) ? remnant : `tc-${remnant}`
+    return `${base}-${hash}`
+  }
   if (cleaned === '' || !/^[a-zA-Z0-9]/.test(cleaned)) {
     return `tc-${cleaned || 'agent'}`
   }

package/src/container/start.ts

@@ -671,7 +671,7 @@ export async function planStart({
   // so mounting an empty cache would only invite a confusing local_files_only
   // miss if something inside the container reached for the model anyway.
   if (agentUsesVector(cwd)) {
-    runArgs.push('-v', `${homeRoot()}/models:/opt/models:ro`)
+    runArgs.push('-v', `${join(homeRoot(), 'models')}:/opt/models:ro`)
     runArgs.push('-e', 'TYPECLAW_MODEL_CACHE=/opt/models')
   }