typeclaw 0.12.0 → 0.14.0

package/src/channels/outbound-flood-filter.ts

@@ -0,0 +1,57 @@
+export type OutboundFloodCheckResult = { ok: true } | { ok: false; reason: string }
+
+const MIN_LENGTH = 40
+const MAX_RUN = 30
+const MIN_LONG_LENGTH = 80
+const MIN_UNIQUE_RATIO = 0.05
+const MAX_DOMINANCE = 0.9
+
+export function checkOutboundFlood(text: string): OutboundFloodCheckResult {
+  if (text.length < MIN_LENGTH) return { ok: true }
+
+  const graphemes = Array.from(text.normalize('NFKC'))
+  if (graphemes.length < MIN_LENGTH) return { ok: true }
+
+  const longestRun = findLongestRun(graphemes)
+  if (longestRun >= MAX_RUN) return { ok: false, reason: `repeated-char-run:${longestRun}` }
+
+  if (graphemes.length < MIN_LONG_LENGTH) return { ok: true }
+
+  const counts = countGraphemes(graphemes)
+  const uniqueRatio = counts.size / graphemes.length
+  if (uniqueRatio < MIN_UNIQUE_RATIO) return { ok: false, reason: `low-unique-ratio:${uniqueRatio.toFixed(3)}` }
+
+  const dominance = maxValue(counts) / graphemes.length
+  if (dominance > MAX_DOMINANCE) return { ok: false, reason: `char-dominance:${dominance.toFixed(2)}` }
+
+  return { ok: true }
+}
+
+function findLongestRun(graphemes: readonly string[]): number {
+  if (graphemes.length === 0) return 0
+  let longest = 1
+  let current = 1
+  for (let i = 1; i < graphemes.length; i++) {
+    if (graphemes[i] === graphemes[i - 1]) {
+      current++
+      if (current > longest) longest = current
+    } else {
+      current = 1
+    }
+  }
+  return longest
+}
+
+function countGraphemes(graphemes: readonly string[]): Map<string, number> {
+  const counts = new Map<string, number>()
+  for (const grapheme of graphemes) counts.set(grapheme, (counts.get(grapheme) ?? 0) + 1)
+  return counts
+}
+
+function maxValue(counts: Map<string, number>): number {
+  let max = 0
+  for (const value of counts.values()) {
+    if (value > max) max = value
+  }
+  return max
+}

package/src/channels/router.ts

@@ -3,7 +3,7 @@ import { basename } from 'node:path'
 import type { AssistantMessage } from '@mariozechner/pi-ai'
 import { SessionManager } from '@mariozechner/pi-coding-agent'
 
-import { createSession, type AgentSession } from '@/agent'
+import { createSession, renderTurnTimeAnchor, type AgentSession } from '@/agent'
 import { subscribeProviderErrors } from '@/agent/provider-error'
 import type { ChannelParticipant, SessionOrigin } from '@/agent/session-origin'
 import { renderSubagentCompletionReminder } from '@/agent/subagent-completion-reminder'
@@ -21,6 +21,7 @@ import {
   type MembershipResolverResult,
 } from './membership'
 import { createMembershipCache, type MembershipCache } from './membership-cache'
+import { checkOutboundFlood } from './outbound-flood-filter'
 import { updateParticipants } from './participants'
 import {
   channelsSessionsPath,
@@ -40,6 +41,7 @@ import type {
   FetchHistoryArgs,
   FetchHistoryResult,
   HistoryCallback,
+  InboundAttachment,
   InboundMessage,
   OutboundCallback,
   OutboundMessage,
@@ -106,6 +108,7 @@ export const SEND_RATE_WINDOW_MS = 5_000
 // send still emits a structured log line regardless of rate — this
 // constant only controls when the warning marker appears.
 export const SEND_RATE_WARN_THRESHOLD = 3
+export const OUTBOUND_FLOOD_ERROR = 'outbound message denied: content looks like a repeated-character flood'
 
 /**
  * Maximum age of the last engaged inbound before the next inbound triggers a fresh session.
@@ -216,6 +219,7 @@ export type ConfigForAdapter = (adapter: ChannelKey['adapter']) => ChannelAdapte
 
 type QueuedInbound = {
   text: string
+  attachments?: readonly InboundAttachment[]
   authorId: string
   authorName: string
   authorIsBot: boolean
@@ -234,6 +238,7 @@ type QueuedInbound = {
 
 type ObservedInbound = {
   text: string
+  attachments?: readonly InboundAttachment[]
   authorId: string
   authorName: string
   authorIsBot: boolean
@@ -447,6 +452,8 @@ export type ChannelRouter = {
   registerFetchAttachment: (adapter: ChannelKey['adapter'], cb: FetchAttachmentCallback) => void
   unregisterFetchAttachment: (adapter: ChannelKey['adapter'], cb: FetchAttachmentCallback) => void
   fetchAttachment: (adapter: ChannelKey['adapter'], args: FetchAttachmentArgs) => Promise<FetchAttachmentResult>
+  lookupInboundAttachment: (args: ChannelKey & { id: number }) => InboundAttachment | null
+  listInboundAttachmentIds: (args: ChannelKey) => readonly number[]
   // Execute a command by name against an existing live session, bypassing
   // the inbound classifier, engagement gate, debounce, and prompt queue.
   // Used by adapters that receive commands through a native surface
@@ -491,13 +498,15 @@ export type ChannelRouter = {
   // turn cannot drop a future legitimate reply.
   //
   // Returns:
-  //   - 'recorded'      — the live session was found and the skip was stamped
-  //   - 'send-already-happened' — a tool-source channel send already landed
-  //                       in this turn; the skip is refused (symmetric with
-  //                       the send-after-skip lock in `send()`) so the model
-  //                       cannot land a reply AND claim silence. The flag is
-  //                       NOT stamped, so the turn proceeds as a normal
-  //                       reply turn.
+  //   - 'recorded'      — silence-first: no send had landed this turn, so the
+  //                       skip was stamped and later tool-source sends are
+  //                       locked out via the send-after-skip guard in `send()`
+  //   - 'recorded-after-send' — reply-first: a tool-source channel send already
+  //                       landed this turn and the agent is now going quiet for
+  //                       the rest of it (the normal ack-then-wait pattern). The
+  //                       delivered reply stands; this skip posts nothing and is
+  //                       a terminal no-op. NOT stamped as a skipped turn (a
+  //                       reply already landed), and logged inline by the impl.
   //   - 'no-live-session' — no matching channel session (e.g. tool fired
   //                         outside a channel origin); the tool should
   //                         still log the reason but cannot suppress.
@@ -506,7 +515,7 @@ export type ChannelRouter = {
     reason: string
   }) =>
     | { kind: 'recorded'; keyId: string }
-    | { kind: 'send-already-happened'; keyId: string }
+    | { kind: 'recorded-after-send'; keyId: string }
     | { kind: 'no-live-session' }
   stop: () => Promise<void>
   liveCount: () => number
@@ -1635,6 +1644,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
   const observe = (live: LiveSession, event: InboundMessage): void => {
     live.contextBuffer.push({
       text: event.text,
+      ...(event.attachments !== undefined && event.attachments.length > 0 ? { attachments: event.attachments } : {}),
       authorId: event.authorId,
       authorName: event.authorName,
       authorIsBot: event.authorIsBot,
@@ -1650,6 +1660,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
   const enqueue = (live: LiveSession, event: InboundMessage): void => {
     live.promptQueue.push({
       text: event.text,
+      ...(event.attachments !== undefined && event.attachments.length > 0 ? { attachments: event.attachments } : {}),
       authorId: event.authorId,
       authorName: event.authorName,
       authorIsBot: event.authorIsBot,
@@ -1798,6 +1809,39 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     return lastError
   }
 
+  const lookupInboundAttachment = (args: ChannelKey & { id: number }): InboundAttachment | null => {
+    const live = liveSessions.get(channelKeyId(args))
+    if (live === undefined) return null
+    // Walk newest → oldest so that when an id collides across messages
+    // (e.g. two photos in the same session each labelled `#1`) the agent's
+    // `attachment_id: 1` always resolves to the CURRENT inbound's
+    // attachment. promptQueue holds the about-to-be-delivered turn and
+    // is therefore the freshest; within each list, append-order maps to
+    // wall-clock order, so iterating in reverse gives recency.
+    const haystacks: ReadonlyArray<ReadonlyArray<{ attachments?: readonly InboundAttachment[] }>> = [
+      live.promptQueue,
+      live.contextBuffer,
+    ]
+    for (const haystack of haystacks) {
+      for (let i = haystack.length - 1; i >= 0; i--) {
+        const item = haystack[i]
+        const found = item?.attachments?.find((attachment) => attachment.id === args.id)
+        if (found !== undefined) return found
+      }
+    }
+    return null
+  }
+
+  const listInboundAttachmentIds = (args: ChannelKey): readonly number[] => {
+    const live = liveSessions.get(channelKeyId(args))
+    if (live === undefined) return []
+    const ids = new Set<number>()
+    for (const item of [...live.promptQueue, ...live.contextBuffer]) {
+      for (const attachment of item.attachments ?? []) ids.add(attachment.id)
+    }
+    return Array.from(ids).sort((a, b) => a - b)
+  }
+
   const send = async (msg: OutboundMessage, opts?: SendOptions): Promise<SendResult> => {
     const source: SendSource = opts?.source ?? 'tool'
     const callbacks = outboundCallbacks.get(msg.adapter)
@@ -1805,6 +1849,12 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
       return { ok: false, error: `no adapter registered for "${msg.adapter}"`, code: 'no-adapter' }
     }
 
+    const authoredText = normalizeSendText(msg.text)
+    if (authoredText !== undefined) {
+      const flood = checkOutboundFlood(authoredText)
+      if (!flood.ok) return { ok: false, error: OUTBOUND_FLOOD_ERROR, code: 'outbound-flood' }
+    }
+
     const keyId = channelKeyId({
       adapter: msg.adapter,
       workspace: msg.workspace,
@@ -1982,6 +2032,11 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
       return
     }
 
+    if (isLikelyPlainTextChannelToolCall(assistantText)) {
+      logger.warn(`[channels] ${live.keyId}: suppressed plain_text_channel_tool_call text_len=${assistantText.length}`)
+      return
+    }
+
     // `source` distinguishes the two recovery shapes for log triage:
     //   - 'leaf': the assistant message IS the leaf (existing behavior; model
     //     ended its turn with text but forgot to call channel_reply).
@@ -2201,13 +2256,22 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     reason: string
   }):
     | { kind: 'recorded'; keyId: string }
-    | { kind: 'send-already-happened'; keyId: string }
+    | { kind: 'recorded-after-send'; keyId: string }
     | { kind: 'no-live-session' } => {
     for (const live of liveSessions.values()) {
       if (live.destroyed) continue
       if (live.sessionId !== args.parentSessionId) continue
       if (live.successfulChannelSends > live.successfulSendsAtTurnStart) {
-        return { kind: 'send-already-happened', keyId: live.keyId }
+        // Reply-first skip ("acked, now going quiet"): accept as a terminal
+        // no-op, never stamp `skippedTurn`. The delivered reply stands and must
+        // not be suppressed, so stamping (which `validateChannelTurn` reads to
+        // drop the turn) would be wrong; the send-after-skip lock only needs to
+        // arm on the silence-first path. Rejecting this instead deadlocks the
+        // agentic loop: denied a clean silent exit the model re-sends, gets
+        // re-denied, and repeats until the per-turn send cap trips. Logged here
+        // since `validateChannelTurn` won't see a `skippedTurn` for it.
+        logger.info(`[channels] ${live.keyId} skip_after_send reason=${JSON.stringify(args.reason)}`)
+        return { kind: 'recorded-after-send', keyId: live.keyId }
       }
       live.skippedTurn = { turnSeq: live.turnSeq, reason: args.reason }
       return { kind: 'recorded', keyId: live.keyId }
@@ -2234,6 +2298,8 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     registerFetchAttachment,
     unregisterFetchAttachment,
     fetchAttachment,
+    lookupInboundAttachment,
+    listInboundAttachmentIds,
     executeCommand,
     getSelfAliases: computeSelfAliases,
     injectSubagentCompletionReminder,
@@ -2306,12 +2372,13 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
 function composeTurnPrompt(
   observed: readonly ObservedInbound[],
   batch: readonly QueuedInbound[],
-  state: { adapter?: AdapterId; loopGuardActive: boolean; systemReminders?: readonly string[] } = {
+  state: { adapter?: AdapterId; loopGuardActive: boolean; systemReminders?: readonly string[]; now?: Date } = {
     loopGuardActive: false,
   },
 ): string {
   const adapter = state.adapter ?? 'discord-bot'
   const parts: string[] = []
+  parts.push(renderTurnTimeAnchor(state.now), '')
   // System reminders (subagent-completion wakeups today) lead the turn body
   // because they are typically what triggered the drain — when the prompt
   // queue is empty and the only thing in this iteration is a reminder, the
@@ -2503,18 +2570,20 @@ export type QuoteAnchorCandidate = {
   hadInterveningObserved: boolean
 }
 
-// Strips `[<Adapter> message with ...]` placeholders that adapter
+// Strips both current `[<Adapter> attachment #N: ...]` and legacy
+// `[<Adapter> message with ...]` placeholders that adapter
 // classifiers synthesize for non-text inbounds (KakaoTalk stickers,
 // Slack/Discord/Telegram attachments). The quote anchor is a UX
 // affordance pointing the human at *their words* — quoting a sticker as
-// `> Alice: [KakaoTalk message with sticker (sticker_ani) pack=... path=...]`
+// `> 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 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
 // so residual double-spaces from mid-string strips are harmless.
-const CHANNEL_MEDIA_PLACEHOLDER_RE = /\[(?:KakaoTalk|Slack|Discord|Telegram) message with [^\]]*\]/g
+const CHANNEL_MEDIA_PLACEHOLDER_RE =
+  /\[(?:KakaoTalk|Slack|Discord|Telegram) (?:message with|attachment #\d+:) [^\]]*\]/g
 
 export function stripChannelMediaPlaceholders(text: string): string {
   return text
@@ -2944,6 +3013,36 @@ export function isLikelyKimiChannelToolLeak(text: string): boolean {
   return KIMI_CHANNEL_TOOL_ID_RE.test(text)
 }
 
+// Detects the *plain-text* shape of a leaked channel-tool invocation — the
+// model serialized the tool call as ordinary prose instead of producing a
+// real tool call. Observed against Kimi-family deployments on KakaoTalk:
+// the entire assistant message body is literally
+//
+//   channel_reply({"text":"<the user-facing greeting the bot meant to send>"})
+//
+// with no Kimi delimiter tokens (`<|tool_call_begin|>` etc.), so
+// `isLikelyKimiChannelToolLeak` cannot catch it. Without a guard the
+// recovery path in `validateChannelTurn` posts this raw function-call
+// serialization straight to the channel, which is exactly what
+// users see in the reported screenshots.
+//
+// Structural-only detection (NOT a substring search): the trimmed text must
+// *start* with `channel_reply(` or `channel_send(`, and that opening paren
+// must enclose at least one `"` (the JSON argument). This deliberately
+// matches the leak shape while letting prose that merely *mentions* the
+// tool name (e.g. "I would normally call channel_reply here but...") reach
+// the user — that false-positive class is already locked in by the
+// `still recovers legit prose that happens to mention "channel_reply"` test.
+//
+// The trailing close paren is NOT required: the model sometimes truncates
+// mid-serialization, and a half-leaked `channel_reply({"text":"..."` is
+// just as user-hostile as the full shape.
+const PLAIN_TEXT_CHANNEL_TOOL_CALL_RE = /^channel_(?:reply|send)\s*\(\s*[^)]*"/
+
+export function isLikelyPlainTextChannelToolCall(text: string): boolean {
+  return PLAIN_TEXT_CHANNEL_TOOL_CALL_RE.test(text.trim())
+}
+
 function describe(err: unknown): string {
   return err instanceof Error ? err.message : String(err)
 }

package/src/channels/types.ts

@@ -7,12 +7,56 @@ export type ChannelKey = {
   thread: string | null
 }
 
+// Inbound (non-text) media that the user attached to a channel message.
+// The classifier produces these alongside `InboundMessage.text`; the router
+// stores them and lets channel tools look them up by `id` so the agent can
+// fetch / view a specific attachment without ever seeing the underlying
+// platform-side `ref` (URL, file id, CDN key) in its prompt context.
+//
+// Design contract:
+// - `id` is a 1-based index that is stable WITHIN A SINGLE inbound message
+//   and assigned by the adapter classifier. It is NOT globally unique —
+//   different inbounds re-use small ids (1, 2, ...). The router's lookup
+//   scopes the search to one (adapter,workspace,chat,thread) session and
+//   returns the MOST RECENT match across that session's promptQueue +
+//   contextBuffer, so within a single turn the agent always resolves
+//   `attachment_id: 1` to the attachment on the current inbound — earlier
+//   uses of id 1 from buffered context cannot intercept the lookup.
+// - `ref` is the opaque platform handle that the adapter's
+//   FetchAttachmentCallback knows how to download (Slack file id, Discord
+//   CDN URL, KakaoCDN URL, Telegram file_id). It is INTENTIONALLY not
+//   rendered into the user-visible prompt text — keeping it out of the
+//   LLM's context prevents the dialect-confusion bug where the agent
+//   pastes a malformed ref (e.g. a KakaoCDN bare key) into a tool.
+// - The kind labels (photo/video/...) are coarse on purpose: they exist
+//   for the prompt placeholder ("an image arrived") and for tool routing,
+//   not for platform-specific behavior.
+export type InboundAttachment = {
+  id: number
+  kind: 'photo' | 'video' | 'audio' | 'file' | 'sticker' | 'multiphoto' | 'embed'
+  ref: string
+  // Optional metadata that the adapter classifier may surface for the
+  // placeholder rendering. Every field MUST be safe to print into a prompt
+  // (no credentials, no long opaque tokens). If a piece of metadata would
+  // leak fetchable state, leave it off and rely on `ref` instead.
+  mimetype?: string
+  filename?: string
+  width?: number
+  height?: number
+  sizeBytes?: number
+}
+
 export type InboundMessage = {
   adapter: AdapterId
   workspace: string
   chat: string
   thread: string | null
   text: string
+  // Non-text attachments the user sent on this inbound. Empty / omitted
+  // when the message is text-only. The router carries these through to
+  // the live session's promptQueue/contextBuffer so channel tools can
+  // resolve `attachment_id` → ref without the agent ever seeing the ref.
+  attachments?: readonly InboundAttachment[]
   externalMessageId: string
   authorId: string
   authorName: string
@@ -84,7 +128,13 @@ export type OutboundMessage = {
   attachments?: OutboundAttachment[]
 }
 
-export type SendErrorCode = 'duplicate' | 'turn-cap' | 'no-adapter' | 'callback-rejected' | 'skip-locked'
+export type SendErrorCode =
+  | 'duplicate'
+  | 'turn-cap'
+  | 'outbound-flood'
+  | 'no-adapter'
+  | 'callback-rejected'
+  | 'skip-locked'
 
 export type SendResult = { ok: true } | { ok: false; error: string; code?: SendErrorCode }
 
@@ -124,6 +174,7 @@ export type ChannelHistoryMessage = {
   authorId: string
   authorName: string
   text: string
+  attachments?: readonly InboundAttachment[]
   ts: number
   isBot: boolean
   replyToBotMessageId: string | null

package/src/cli/builtins.ts

@@ -21,6 +21,7 @@ export const BUILTIN_COMMAND_NAMES = [
   'role',
   'provider',
   'model',
+  'mount',
   'doctor',
   'usage',
   'update',

package/src/cli/index.ts

@@ -31,6 +31,7 @@ const main = defineCommand({
     role: () => import('./role').then((m) => m.roleCommand),
     provider: () => import('./provider').then((m) => m.providerCommand),
     model: () => import('./model').then((m) => m.modelCommand),
+    mount: () => import('./mount').then((m) => m.mountCommand),
     doctor: () => import('./doctor').then((m) => m.doctorCommand),
     usage: () => import('./usage').then((m) => m.usageCommand),
     update: () => import('./update').then((m) => m.updateCommand),

package/src/cli/mount.ts

@@ -0,0 +1,157 @@
+import { defineCommand } from 'citty'
+
+import { addMount, listMounts, removeMount, type MountListEntry } from '@/config/mounts-mutation'
+import { findAgentDir, isInitialized } from '@/init'
+
+import { c, errorLine, successLine } from './ui'
+
+const listSub = defineCommand({
+  meta: {
+    name: 'list',
+    description: 'list host directories mounted into the agent container',
+  },
+  args: {
+    json: {
+      type: 'boolean',
+      description: 'emit mounts as JSON',
+      default: false,
+    },
+  },
+  async run({ args }) {
+    const cwd = ensureAgentDir()
+    const mounts = listMounts(cwd)
+    if (args.json) {
+      process.stdout.write(`${JSON.stringify({ mounts }, null, 2)}\n`)
+      return
+    }
+    process.stdout.write(`${formatMountList(mounts)}\n`)
+  },
+})
+
+const addSub = defineCommand({
+  meta: {
+    name: 'add',
+    description: 'add a host directory mount to typeclaw.json',
+  },
+  args: {
+    name: {
+      type: 'positional',
+      description: 'mount name; appears inside the container at /agent/mounts/<name>',
+      required: true,
+    },
+    path: {
+      type: 'positional',
+      description: 'host directory path to expose inside the container',
+      required: true,
+    },
+    'read-only': {
+      type: 'boolean',
+      description: 'mount read-only inside the container',
+      default: false,
+    },
+    description: {
+      type: 'string',
+      description: 'optional human-readable note stored in typeclaw.json',
+      required: false,
+    },
+  },
+  async run({ args }) {
+    const cwd = ensureAgentDir()
+    const result = addMount(cwd, args.name, args.path, {
+      readOnly: args['read-only'] === true,
+      ...(args.description !== undefined ? { description: args.description } : {}),
+    })
+    if (!result.ok) {
+      console.error(errorLine(result.reason))
+      process.exit(1)
+    }
+    process.stdout.write(`${successLine(`Added mount "${result.entry.name}".`)}\n`)
+    process.stdout.write(`${formatMountEntry(result.entry)}\n`)
+    process.stdout.write(`${c.dim('Apply change:')} ${c.cyan('typeclaw restart')}\n`)
+  },
+})
+
+const removeSub = defineCommand({
+  meta: {
+    name: 'remove',
+    description: 'remove a host directory mount from typeclaw.json',
+  },
+  args: {
+    name: {
+      type: 'positional',
+      description: 'mount name to remove',
+      required: true,
+    },
+  },
+  async run({ args }) {
+    const cwd = ensureAgentDir()
+    const result = removeMount(cwd, args.name)
+    if (!result.ok) {
+      console.error(errorLine(result.reason))
+      process.exit(1)
+    }
+    process.stdout.write(`${successLine(`Removed mount "${result.removed.name}".`)}\n`)
+    process.stdout.write(`${c.dim('Apply change:')} ${c.cyan('typeclaw restart')}\n`)
+  },
+})
+
+export const mountCommand = defineCommand({
+  meta: {
+    name: 'mount',
+    description: 'manage host directories mounted into the agent container',
+  },
+  subCommands: {
+    list: listSub,
+    add: addSub,
+    remove: removeSub,
+  },
+})
+
+export function formatMountList(mounts: readonly MountListEntry[]): string {
+  if (mounts.length === 0) return c.dim('No mounts configured.')
+
+  const nameWidth = Math.max(4, ...mounts.map((m) => m.name.length))
+  const modeWidth = 'MODE'.length
+  const statusWidth = Math.max(6, ...mounts.map((m) => m.status.length))
+  const lines: string[] = []
+  lines.push(
+    c.dim(
+      `${'NAME'.padEnd(nameWidth)}  ${'MODE'.padEnd(modeWidth)}  ${'STATUS'.padEnd(statusWidth)}  HOST PATH -> CONTAINER PATH`,
+    ),
+  )
+  for (const mount of mounts) {
+    const mode = mount.readOnly ? 'ro' : 'rw'
+    const statusText = mount.status.padEnd(statusWidth)
+    const status = mount.status === 'ok' ? c.green(statusText) : c.red(statusText)
+    lines.push(
+      `${mount.name.padEnd(nameWidth)}  ${mode.padEnd(modeWidth)}  ${status}  ${mount.resolvedPath} -> ${mount.targetPath}`,
+    )
+    if (mount.description !== undefined) {
+      lines.push(`${' '.repeat(nameWidth + modeWidth + statusWidth + 6)}${c.dim(mount.description)}`)
+    }
+    if (mount.statusReason !== undefined) {
+      lines.push(`${' '.repeat(nameWidth + modeWidth + statusWidth + 6)}${c.yellow(mount.statusReason)}`)
+    }
+  }
+  return lines.join('\n')
+}
+
+function formatMountEntry(mount: MountListEntry): string {
+  const mode = mount.readOnly ? 'read-only' : 'read-write'
+  const details = [
+    `${c.dim('host:')} ${mount.resolvedPath}`,
+    `${c.dim('container:')} ${mount.targetPath}`,
+    `${c.dim('mode:')} ${mode}`,
+  ]
+  if (mount.description !== undefined) details.push(`${c.dim('description:')} ${mount.description}`)
+  return details.join('\n')
+}
+
+function ensureAgentDir(): string {
+  const cwd = findAgentDir(process.cwd()) ?? process.cwd()
+  if (!isInitialized(cwd)) {
+    console.error(errorLine('TypeClaw config file not found. Run `typeclaw init` first, or cd into an agent folder.'))
+    process.exit(1)
+  }
+  return cwd
+}

package/src/cli/update.ts

@@ -9,7 +9,7 @@ const MANAGERS = ['auto', 'bun', 'npm', 'pnpm', 'yarn'] as const
 export const updateCommand = defineCommand({
   meta: {
     name: 'update',
-    description: 'update the globally installed typeclaw CLI',
+    description: 'update the installed typeclaw CLI (auto-detects global vs local)',
   },
   args: {
     manager: {
@@ -42,8 +42,9 @@ export const updateCommand = defineCommand({
       return
     }
 
-    process.stdout.write(`${c.cyan('Updating TypeClaw with:')} ${rendered}\n`)
-    const exitCode = await runUpdateCommand(plan.command)
+    const scopeLabel = plan.scope === 'global' ? 'global' : `local (${plan.cwd ?? '.'})`
+    process.stdout.write(`${c.cyan(`Updating TypeClaw [${scopeLabel}] with:`)} ${rendered}\n`)
+    const exitCode = await runUpdateCommand(plan.command, plan.cwd)
     if (exitCode !== 0) {
       console.error(errorLine(`Update command exited with code ${exitCode}.`))
       process.exit(exitCode)
@@ -58,7 +59,7 @@ function parseManager(value: string | undefined): UpdateManagerSelection | null
   return (MANAGERS as readonly string[]).includes(value) ? (value as UpdateManagerSelection) : null
 }
 
-async function runUpdateCommand(command: string[]): Promise<number> {
+async function runUpdateCommand(command: string[], cwd: string | undefined): Promise<number> {
   const bun = (globalThis as { Bun?: { spawn: typeof Bun.spawn } }).Bun
   if (!bun) {
     console.error(errorLine('bun runtime not available'))
@@ -67,6 +68,7 @@ async function runUpdateCommand(command: string[]): Promise<number> {
   try {
     const proc = bun.spawn({
       cmd: command,
+      cwd,
       stdin: 'inherit',
       stdout: 'inherit',
       stderr: 'inherit',