typeclaw 0.32.0 → 0.32.1

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

@@ -16,7 +16,6 @@ export type SlackMessagePointer = {
 export async function enrichSlackReferenceContext(args: {
   text: string
   channelId: string
-  threadTs?: string
   messageTs: string
   attachments?: readonly unknown[]
   fetchMessage: SlackReferenceFetch
@@ -25,17 +24,17 @@ export async function enrichSlackReferenceContext(args: {
   const sources: QuoteAnchorSource[] = []
   let kind: InboundReferenceContext['kind'] = 'link'
 
-  if (args.threadTs !== undefined && args.threadTs !== args.messageTs) {
-    const parent = await fetchSafely(args.fetchMessage, { channelId: args.channelId, messageTs: args.threadTs })
-    if (parent !== null) {
-      sources.push(toSource(parent))
-      kind = 'reply'
-    }
-  }
-
+  // Slack `thread_ts` is thread MEMBERSHIP, not a "reply-to this message"
+  // signal: every message in a thread carries the same root ts, so deriving
+  // reply context from it attached the thread root as a quote anchor on every
+  // in-thread message — repeated once per buffered message in a turn, and
+  // re-attached on every turn for the life of the thread. Only explicit
+  // message shares and archive links below carry a genuine referenced-message
+  // signal. If Slack ever exposes a distinct referenced-message id, add a new
+  // path for it rather than reusing `thread_ts`.
   for (const source of extractSlackShareSources(args.attachments ?? [])) {
     sources.push(source)
-    if (kind !== 'reply') kind = 'quote'
+    kind = 'quote'
   }
 
   const links = extractSlackMessageLinks(args.text).slice(0, args.linkLimit ?? 3)

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

@@ -32,7 +32,7 @@ import type {
 } from '@/channels/types'
 import { chunkMarkdown } from '@/markdown'
 
-import { createSlackAuthorResolver } from './slack-bot-author-resolver'
+import { createSlackAuthorResolver, type SlackAuthorResolver } from './slack-bot-author-resolver'
 import { createSlackChannelResolver } from './slack-bot-channel-resolver'
 import {
   classifyInbound,
@@ -650,9 +650,10 @@ export function createSlackHistoryCallback(deps: {
   token: string
   logger: SlackBotAdapterLogger
   botUserIdRef: () => string | null
+  authorResolver?: SlackAuthorResolver
   fetchImpl?: typeof fetch
 }): HistoryCallback {
-  const { token, logger, botUserIdRef } = deps
+  const { token, logger, botUserIdRef, authorResolver } = deps
   const fetchFn = deps.fetchImpl ?? fetch
   return async (args: FetchHistoryArgs): Promise<FetchHistoryResult> => {
     const limit = clampLimit(args.limit, SLACK_HISTORY_LIMIT_MAX)
@@ -687,6 +688,20 @@ export function createSlackHistoryCallback(deps: {
     const botUserId = botUserIdRef()
     const rawMessages = raw.messages ?? []
     const mapped = rawMessages.map((m) => mapSlackMessage(m, botUserId))
+    // History payloads carry no profile, so mapSlackMessage echoes the raw
+    // id into authorName; resolve it here so prompts show display names.
+    // Only msg.user authors are resolvable — bot_id-only messages have no
+    // users.info entry. The resolver caches/coalesces, so repeated authors
+    // cost one lookup each.
+    if (authorResolver !== undefined) {
+      await Promise.all(
+        mapped.map(async (message, index) => {
+          const userId = rawMessages[index]?.user
+          if (userId === undefined || userId === '') return
+          message.authorName = await authorResolver.resolve(userId)
+        }),
+      )
+    }
     // Slack's `conversations.history` returns newest-first; `replies`
     // returns oldest-first. Normalize to oldest-first so the agent always
     // reads chronological order regardless of scope.
@@ -905,7 +920,11 @@ export function createFetchAttachmentCallback(deps: {
   }
 }
 
-function createSlackReferenceFetch(deps: { token: string; fetchImpl: typeof fetch }) {
+export function createSlackReferenceFetch(deps: {
+  token: string
+  fetchImpl: typeof fetch
+  authorResolver?: SlackAuthorResolver
+}) {
   return async (channelId: string, messageTs: string) => {
     const url = new URL('https://slack.com/api/conversations.replies')
     url.searchParams.set('channel', channelId)
@@ -918,10 +937,13 @@ function createSlackReferenceFetch(deps: { token: string; fetchImpl: typeof fetc
     const messages = arrayField(body, 'messages')
     const first = recordValue(messages[0])
     if (first === null) return null
-    const authorId = stringField(first, 'user') ?? stringField(first, 'bot_id')
+    const userId = stringField(first, 'user')
+    const authorId = userId ?? stringField(first, 'bot_id')
     const text = stringField(first, 'text')
     if (authorId === null || text === null) return null
-    return { authorId, authorName: authorId, text }
+    const authorName =
+      userId !== null && deps.authorResolver !== undefined ? await deps.authorResolver.resolve(userId) : authorId
+    return { authorId, authorName, text }
   }
 }
 
@@ -981,6 +1003,7 @@ export function createSlackBotAdapter(options: SlackBotAdapterOptions): SlackBot
     token: options.token,
     logger,
     botUserIdRef: () => botUserId,
+    authorResolver,
   })
 
   const membershipResolver = createSlackMembershipResolver({
@@ -1105,10 +1128,9 @@ export function createSlackBotAdapter(options: SlackBotAdapterOptions): SlackBot
       const referenceResult = await enrichSlackReferenceContext({
         text: verdict.payload.text,
         channelId: event.channel,
-        ...(event.thread_ts !== undefined ? { threadTs: event.thread_ts } : {}),
         messageTs: event.ts,
         ...(slackAttachments !== undefined ? { attachments: slackAttachments } : {}),
-        fetchMessage: createSlackReferenceFetch({ token: options.token, fetchImpl }),
+        fetchMessage: createSlackReferenceFetch({ token: options.token, fetchImpl, authorResolver }),
       })
       const enriched = {
         ...verdict.payload,

package/src/channels/router.ts

@@ -297,6 +297,8 @@ export class StaleLiveSessionError extends Error {
 export const RESOLVE_CHANNEL_NAMES_TIMEOUT_MS = 5_000
 export const FETCH_HISTORY_TIMEOUT_MS = 5_000
 
+export const HISTORY_ATTACHMENT_LIMIT = 50
+
 // Watchdog over the whole session.idle hook chain. The drain loop awaits
 // `fireSessionIdle` between turns; a single hung plugin handler (e.g. a
 // memory-logger awaiting a network call that never resolves) wedges the
@@ -418,6 +420,8 @@ type ObservedInbound = {
   source: 'prefetch' | 'observed'
 }
 
+type TimedAttachment = { ts: number; attachment: InboundAttachment }
+
 type LiveSession = {
   key: ChannelKey
   keyId: string
@@ -439,6 +443,17 @@ type LiveSession = {
   // and cleared when the turn ends, is what the lookup reads so a freshly-
   // arrived attachment stays resolvable for the whole turn it belongs to.
   currentTurnAttachments: readonly InboundAttachment[]
+  // Refs from an explicit channel_history look-back. A prior-turn attachment is
+  // replayed to the model as a text placeholder but its ref is gone from every
+  // turn-scoped queue above, so look_at/fetch can't resolve it; stashing the
+  // fetched refs here makes the same `attachment_id: N` resolvable. MUST be
+  // searched LAST so a live `#1` still wins over a historical `#1` (the
+  // newest-first collision rule lookupInboundAttachment documents). Bounded,
+  // never persisted, never exposes the ref to the model. historyTimedAttachments
+  // is the ts-tagged source of truth (ordered oldest→newest, deduped by id);
+  // historyAttachments is its flat projection consumed by the lookup helpers.
+  historyTimedAttachments: readonly TimedAttachment[]
+  historyAttachments: InboundAttachment[]
   draining: boolean
   debounceTimer: ReturnType<typeof setTimeout> | null
   typingTimer: ReturnType<typeof setInterval> | null
@@ -724,6 +739,10 @@ export type ChannelRouter = {
   getReviewState: (req: ReviewStateRequest) => Promise<ReviewStateResult>
   lookupInboundAttachment: (args: ChannelKey & { id: number }) => InboundAttachment | null
   listInboundAttachmentIds: (args: ChannelKey) => readonly number[]
+  // Stash refs from a channel_history fetch so prior-turn attachments stay
+  // resolvable by their placeholder id. Called by the channel_history tool
+  // after a successful fetch; no-op when the session is not live.
+  registerHistoryAttachments: (key: ChannelKey, messages: readonly ChannelHistoryMessage[]) => void
   // 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
@@ -1407,6 +1426,8 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         pendingSystemReminders: [],
         contextBuffer: [],
         currentTurnAttachments: [],
+        historyTimedAttachments: [],
+        historyAttachments: [],
         draining: false,
         debounceTimer: null,
         typingTimer: null,
@@ -2778,7 +2799,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         if (hit !== undefined) return hit
       }
     }
-    return null
+    return findAttachmentById(live.historyAttachments, args.id)
   }
 
   const listInboundAttachmentIds = (args: ChannelKey): readonly number[] => {
@@ -2789,9 +2810,36 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     for (const item of [...live.promptQueue, ...live.contextBuffer]) {
       for (const attachment of item.attachments ?? []) ids.add(attachment.id)
     }
+    for (const attachment of live.historyAttachments) ids.add(attachment.id)
     return Array.from(ids).sort((a, b) => a - b)
   }
 
+  const registerHistoryAttachments = (key: ChannelKey, messages: readonly ChannelHistoryMessage[]): void => {
+    const live = liveSessions.get(channelKeyId(key))
+    if (live === undefined) return
+    const incoming: TimedAttachment[] = messages.flatMap((message) =>
+      (message.attachments ?? []).map((attachment) => ({ ts: message.ts, attachment })),
+    )
+    if (incoming.length === 0) return
+    // Order by message freshness, NOT append order: channel_history pages
+    // OLDER messages via nextCursor, so a later call can deliver an OLDER ref.
+    // findAttachmentById searches end-first, so the list MUST end with the
+    // freshest ref or an older paged `#1` would shadow a newer one. Dedupe by
+    // id keeping the freshest ts (a re-fetch of the same message is a no-op,
+    // not a duplicate), sort ascending by ts, then keep the freshest LIMIT so
+    // eviction drops the OLDEST refs, never newer ones.
+    const byId = new Map<number, TimedAttachment>()
+    for (const entry of [...live.historyTimedAttachments, ...incoming]) {
+      const existing = byId.get(entry.attachment.id)
+      if (existing === undefined || entry.ts >= existing.ts) byId.set(entry.attachment.id, entry)
+    }
+    const sorted = Array.from(byId.values()).sort((a, b) => a.ts - b.ts)
+    const kept =
+      sorted.length > HISTORY_ATTACHMENT_LIMIT ? sorted.slice(sorted.length - HISTORY_ATTACHMENT_LIMIT) : sorted
+    live.historyTimedAttachments = kept
+    live.historyAttachments = kept.map((entry) => entry.attachment)
+  }
+
   const send = async (msg: OutboundMessage, opts?: SendOptions): Promise<SendResult> => {
     const source: SendSource = opts?.source ?? 'tool'
     const callbacks = outboundCallbacks.get(msg.adapter)
@@ -3043,13 +3091,18 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     const candidate = recoverableAssistantText(live.session)
     if (candidate === null) {
       // No recoverable assistant prose: the turn ended with no usable reply.
-      // Two distinct shapes, handled differently (Option B):
+      // Three distinct shapes, handled differently:
       //
-      //   1. The model THRASHED the send path this turn — it tried to send but
-      //      every attempt was denied (skip-locked, or policy-denied/duplicate/
-      //      cap, tracked on skipLockedSendTurn / policyDeniedToolSendsThisTurn).
-      //      Re-prompting would just re-thrash, so skip retry and post the
-      //      user-facing fallback once.
+      //   1a. SKIP-LOCKED thrash — the model called `skip_response` (committed to
+      //       silence) then tried to send; every attempt was denied skip-locked
+      //       (skipLockedSendTurn === turnSeq). Honor the silence decision: stay
+      //       silent, no fallback. Handled first, below.
+      //
+      //   1b. The model THRASHED the send path WITHOUT a skip commitment — denials
+      //       tracked on policyDeniedToolSendsThisTurn (duplicate/cap). In practice
+      //       these only accumulate after a real send landed, so the early return
+      //       above usually fires first; if one ever reaches here, re-prompting
+      //       would just re-thrash, so skip retry and post the fallback once.
       //
       //   2. The PURE reasoning-loop — no send was ever attempted; the model
       //      burned its budget thinking and produced nothing (the canonical
@@ -3061,8 +3114,25 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
       // The legitimate empty-state case (a TUI-only check before any user
       // prompt, no inbound this turn) is excluded: no batch means no real turn
       // to retry or apologize for — keep the historical silent bail there.
-      const attemptedSendThisTurn =
-        live.skipLockedSendTurn === live.turnSeq || live.policyDeniedToolSendsThisTurn.size > 0
+      const skipLockedThisTurn = live.skipLockedSendTurn === live.turnSeq
+      const attemptedSendThisTurn = skipLockedThisTurn || live.policyDeniedToolSendsThisTurn.size > 0
+
+      // Skip-locked thrash honors the skip with SILENCE, not the fallback. The
+      // model called `skip_response` (committed to silence) then tried to send;
+      // the send was denied skip-locked and a retry loop aborts the run, leaving
+      // an `aborted` leaf whose reply text was a denied tool ARG — never
+      // recoverable prose. EMPTY_TURN_FALLBACK_TEXT would be a false alarm here:
+      // it reads as a system failure when the real state is the model's own
+      // silence decision contradicted by a late reply. The pure turn-cap/duplicate
+      // thrash below (no `skip_response`) never committed to silence, so it still
+      // gets the fallback. Distinct log line keeps production signal.
+      if (skipLockedThisTurn) {
+        logger.warn(
+          `[channels] ${live.keyId} skip_locked_send_thrash_suppressed ` +
+            `denied_targets=${live.policyDeniedToolSendsThisTurn.size}`,
+        )
+        return
+      }
 
       // Only a TRUNCATED assistant leaf (length/error/aborted) from a real
       // conversational turn is a degeneration worth retrying. A cold/empty turn
@@ -3693,6 +3763,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     getReviewState,
     lookupInboundAttachment,
     listInboundAttachmentIds,
+    registerHistoryAttachments,
     executeCommand,
     getSelfAliases: computeSelfAliases,
     injectSubagentCompletionReminder,
@@ -3907,19 +3978,16 @@ function composeTurnPrompt(
     }
     parts.push('')
   }
-  // Only emit the `## Current message(s)` header when there is at least one
-  // queued inbound to live under it. A reminder-only wakeup (subagent
-  // completion firing while the prompt queue is empty) used to print the
-  // header with zero lines underneath; persona-rich models read the empty
-  // header as "there must be a current message addressed to me" and
-  // hallucinated content to reply to. The header is now batch-gated; the
-  // reminder block above and any observed context still render normally.
+  // Emit the `## Current message(s)` header whenever the batch is non-empty.
+  // It is batch-gated (a reminder-only wakeup with an empty promptQueue must
+  // not print a header with zero lines under it — persona-rich models read
+  // the dangling header as a message they're failing to see and hallucinate a
+  // reply). It must NOT also be gated on observed context: a turn carrying
+  // only the current message then rendered the batch line bare, or flush under
+  // the `## Recent context (not addressed to you …)` header — mislabeling the
+  // one line the model is supposed to answer as context it should ignore.
   if (batch.length > 0) {
-    if (observed.length > 0) {
-      parts.push(
-        batch.length === 1 ? '## Current message (addressed to you)' : '## Current messages (addressed to you)',
-      )
-    }
+    parts.push(batch.length === 1 ? '## Current message (addressed to you)' : '## Current messages (addressed to you)')
     for (const b of batch) {
       parts.push(formatInboundPromptLines(b, adapter))
     }

package/src/cli/index.ts

@@ -3,8 +3,10 @@
 import { defineCommand, runMain } from 'citty'
 
 import { CLI_VERSION } from '../init/cli-version'
+import { findAgentDir } from '../init/find-agent-dir'
+import { runStartupMigrations } from '../migrations'
 import { BUILTIN_COMMAND_NAMES } from './builtins'
-import { dispatchPluginCommand, type PluginCommandDispatchOutcome } from './plugin-commands-dispatch'
+import type { PluginCommandDispatchOutcome } from './plugin-commands-dispatch'
 
 const main = defineCommand({
   meta: {
@@ -40,12 +42,44 @@ const main = defineCommand({
   },
 })
 
-await runWithPluginDispatch()
+// #673's v1->v2 secrets migration was wired only into the container-stage boot
+// path (src/run/index.ts), so host CLI commands that read secrets.json directly
+// (model/provider list -> tryReadProvidersSync -> v2-only parser) still hard-fail
+// on a never-booted v1 folder. Run it once per host invocation here — at the
+// dispatch boundary, NOT in the parse path, which would recreate the read-time
+// shim #638 deliberately removed.
+let hostStartupMigrationsDone = false
+
+// `run` is the container stage and owns its own migration. Bare flag
+// invocations (`--help`, `-h`, `--version`, `-v`, no command) are
+// informational, exit before reading secrets, and must NOT rewrite secrets.json
+// or emit migration warnings — so only a real subcommand triggers the migration.
+function shouldRunHostStartupMigrations(commandName: string | undefined): boolean {
+  if (commandName === undefined || commandName === 'run') return false
+  return !commandName.startsWith('-')
+}
+
+function runHostStartupMigrationsOnce(commandName: string | undefined): void {
+  if (hostStartupMigrationsDone) return
+  hostStartupMigrationsDone = true
+  if (!shouldRunHostStartupMigrations(commandName)) return
+  const agentDir = findAgentDir(process.cwd())
+  if (agentDir === null) return
+  try {
+    runStartupMigrations(agentDir)
+  } catch (err) {
+    // runStartupMigrations isolates per-migration throws; this guards only the
+    // unexpected so a migration error can never block the host command itself.
+    console.warn(`[migration] host startup migration error: ${err instanceof Error ? err.message : String(err)}`)
+  }
+}
 
 async function runWithPluginDispatch(): Promise<void> {
   const argv = process.argv.slice(2)
   const first = argv[0]
 
+  runHostStartupMigrationsOnce(first)
+
   if (first === '--help' || first === '-h') {
     // citty calls process.exit() after rendering help, so anything we print
     // AFTER `runMain(main)` is never reached. Print the plugin commands
@@ -64,6 +98,10 @@ async function runWithPluginDispatch(): Promise<void> {
     !first.startsWith('-') &&
     !BUILTIN_COMMAND_NAMES.includes(first as (typeof BUILTIN_COMMAND_NAMES)[number])
   ) {
+    // Lazy: the dispatch chain statically pulls in @/config, @/plugin, zod, and
+    // @/container (~190ms). Only plugin (non-builtin) commands need it, so we
+    // defer the import to keep builtin commands and bare flags fast.
+    const { dispatchPluginCommand } = await import('./plugin-commands-dispatch')
     const outcome = await dispatchPluginCommand({ name: first, rawArgs: argv.slice(1), cwd: process.cwd() })
     if (outcome.kind === 'dispatched') {
       process.exit(outcome.exitCode)
@@ -78,3 +116,5 @@ async function runWithPluginDispatch(): Promise<void> {
 }
 
 export type { PluginCommandDispatchOutcome }
+
+await runWithPluginDispatch()

package/src/cli/inspect.ts

@@ -299,9 +299,12 @@ async function clackSelectSession(
 }
 
 function itemLabel(item: ViewerItem): string {
+  // clack's select already draws a radio dot (●/○) per option; a leading status
+  // dot here doubled it into a confusing "● ○". Keep rows glyph-free; the live
+  // row uses ▸ (not a dot) to stay distinct from the radio cursor.
   if (item.kind === 'logs') return `${c.dim('▤')} container logs`
-  if (item.kind === 'tui') return `${c.green('●')} ${c.bold('live TUI')}  ${sessionRowLabel(item.summary)}`
-  return `${c.dim('○')} ${sessionRowLabel(item.summary)}`
+  if (item.kind === 'tui') return `${c.green('▸')} ${c.bold('live TUI')}  ${sessionRowLabel(item.summary)}`
+  return sessionRowLabel(item.summary)
 }
 
 function itemHint(item: ViewerItem): { hint: string } {

package/src/config/config.ts

@@ -338,17 +338,29 @@ export const networkSchema = z
 
 export type NetworkConfig = z.infer<typeof networkSchema>
 
-// `realProc` opts the per-tool bwrap sandbox into the 'real-proc' strategy
-// (src/sandbox/build.ts): a fresh procfs scoped to a new PID namespace so
-// external-package runners (`bunx`, `bun add <pkg>`, `bun run <pkg-bin>`) get a
-// working /proc/self/{fd,maps} and stop aborting with Bun's "NotDir". Default
-// `false` keeps the universally-portable '--tmpfs /proc' profile, under which
-// sandboxed external-package execution is unsupported by design. Turning it on
-// makes `typeclaw start` grant the container CAP_SYS_ADMIN (required to mount
-// proc for the new PID namespace), which is a deliberate posture change on the
-// single-tenant outer boundary — see docs/internals/sandbox.mdx. PID isolation
-// and the /proc/N/environ leak guard are both preserved; the trade is the
-// CAP_SYS_ADMIN grant, not sandbox strength.
+// `realProc` opts the per-tool bwrap sandbox (src/sandbox/build.ts) into the
+// stricter 'real-proc' /proc strategy: a fresh procfs scoped to a NEW PID
+// namespace via `unshare --pid --fork --mount --mount-proc`. It adds full PID
+// isolation (the agent runtime's pids are absent from the sandbox namespace),
+// but needs CAP_SYS_ADMIN to mount proc — so `typeclaw start` grants the
+// container `--cap-add=SYS_ADMIN` only when this is set.
+//
+// Default `false`, because external-package execution (`bunx agent-*`, `bun add
+// <pkg>`, `bun run <pkg-bin>` — the core subagent workflow) no longer needs it:
+// the default 'proc-bind' strategy `--ro-bind`s the container's already-real
+// procfs into the sandbox with NO CAP_SYS_ADMIN, giving the runner's child a
+// working /proc/self/{fd,maps} so it stops aborting with Bun's "NotDir". The
+// agent runtime's /proc/N/environ (FIREWORKS_API_KEY) stays unreadable because
+// bwrap's --unshare-user puts the sandbox in a child user namespace the kernel
+// won't let read a parent-userns process's environ — verified at runtime by a
+// probe before the strategy is selected (src/sandbox/availability.ts). Avoiding
+// the broad CAP_SYS_ADMIN grant by default is a smaller blast radius than the
+// non-secret PID metadata 'proc-bind' exposes — see docs/internals/sandbox.mdx.
+//
+// Set `true` only to add the PID-isolation posture on a host where the proc
+// mount actually works (bare-metal Linux, Docker Desktop — NOT OrbStack, which
+// rejects the mount even with the cap; there the runtime falls back to
+// 'proc-bind' regardless). The cost is the CAP_SYS_ADMIN grant on the container.
 export const sandboxSchema = z
   .object({
     realProc: z.boolean().default(false),

package/src/container/start.ts

@@ -514,16 +514,21 @@ export async function planStart({
     }
   }
 
-  // sandbox.realProc opts the per-tool bwrap sandbox into the 'real-proc'
-  // strategy (src/sandbox/build.ts), which prefixes the sandbox with
+  // sandbox.realProc (default FALSE) opts into the per-tool bwrap sandbox's
+  // 'real-proc' strategy (src/sandbox/build.ts), which prefixes the sandbox with
   // `unshare --pid --fork --mount --mount-proc`. Mounting a fresh procfs for the
   // new PID namespace needs real CAP_SYS_ADMIN — seccomp=unconfined alone is not
   // enough (it only unblocks the unshare/clone SYSCALLS; the kernel still
-  // rejects mount(2) of proc without the capability). This is the deliberate
-  // posture change documented in docs/internals/sandbox.mdx: the default keeps
-  // the narrower seccomp-only profile, and the operator grants the broad
-  // "new root" capability ONLY by opting into real-proc. Placed before the
-  // image tag (like --cap-add=NET_ADMIN) so docker applies it at run time.
+  // rejects mount(2) of proc without the capability). So the grant is gated on
+  // the flag and is OFF by default: external-package execution (`bunx agent-*`)
+  // no longer needs it — the default 'proc-bind' strategy gives the runner real
+  // /proc without any outer capability (see docs/internals/sandbox.mdx). Setting
+  // realProc:true adds the stricter PID-isolation posture at the cost of this
+  // broad "new root" grant. The container-side strategy resolution still probes
+  // whether the mount actually works (canMountRealProc) and falls back to
+  // proc-bind on runtimes where the cap is a no-op (e.g. OrbStack), so this grant
+  // is necessary-but-not-sufficient by design. Placed before the image tag (like
+  // --cap-add=NET_ADMIN) so docker applies it at run time.
   if (cfg.sandbox.realProc) {
     runArgs.push('--cap-add=SYS_ADMIN')
   }

package/src/init/find-agent-dir.ts

@@ -0,0 +1,44 @@
+import { existsSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+
+// Dependency-free agent-folder resolution. Kept out of `src/init/index.ts` so
+// the host CLI entry (`src/cli/index.ts`) can locate the agent folder at the
+// dispatch boundary WITHOUT pulling in the heavy init barrel (which statically
+// imports @/config, @/config/providers, @/container, @/secrets, @/tui — a
+// ~190ms module graph). This module MUST NOT import from the init barrel,
+// config, container, or plugin modules; keep the dependency direction one-way.
+
+export const CONFIG_FILE = 'typeclaw.json'
+
+export function isInitialized(dir: string): boolean {
+  return existsSync(join(dir, CONFIG_FILE))
+}
+
+// Walks upward from `start` looking for the agent folder (the dir containing
+// typeclaw.json). Returns the found dir, or null if nothing is found before
+// the walk hits a stop boundary.
+//
+// Stop boundaries (whichever comes first, checked at every level):
+//   1. The current dir contains typeclaw.json — return it.
+//   2. The current dir contains .git — return null. A .git boundary marks a
+//      project root; refusing to cross it prevents accidentally picking up an
+//      unrelated parent project, and matches how typeclaw itself initializes
+//      one .git per agent folder.
+//   3. We've reached the filesystem root — return null.
+//
+// The `.git` check fires AFTER the typeclaw.json check at the same level so
+// that walking up from a subdir of the agent (e.g. `<agent>/workspace/`) still
+// resolves to the agent root, even though the agent root itself contains both
+// typeclaw.json and .git.
+export function findAgentDir(start: string): string | null {
+  let dir = resolve(start)
+  const root = resolve(dir, '/')
+  while (true) {
+    if (existsSync(join(dir, CONFIG_FILE))) return dir
+    if (existsSync(join(dir, '.git'))) return null
+    if (dir === root) return null
+    const parent = dirname(dir)
+    if (parent === dir) return null
+    dir = parent
+  }
+}

package/src/init/index.ts

@@ -19,6 +19,7 @@ import { createTui } from '@/tui'
 
 import { resolveBaseImageVersion, resolveScaffoldVersion } from './cli-version'
 import { buildDockerfile, DOCKERFILE } from './dockerfile'
+import { CONFIG_FILE, findAgentDir, isInitialized } from './find-agent-dir'
 import { installGithubWebhooksEagerly, type EagerGithubWebhookInstallResult } from './github-webhook-install'
 import { buildGitignore, GITIGNORE_FILE } from './gitignore'
 import { buildHatchingPrompt } from './hatching'
@@ -35,7 +36,8 @@ export { GITKEEP_FILE, PACKAGES_DIR, PUBLIC_DIR } from './paths'
 
 export { appendOrReplaceEnvKey, hasEnvKey, readEnvFile } from './env-file'
 
-const CONFIG_FILE = 'typeclaw.json'
+export { CONFIG_FILE, findAgentDir, isInitialized }
+
 const CRON_FILE = 'cron.json'
 const PACKAGE_FILE = 'package.json'
 
@@ -491,39 +493,6 @@ export function isDirectoryNonEmpty(dir: string): boolean {
   }
 }
 
-export function isInitialized(dir: string): boolean {
-  return existsSync(join(dir, CONFIG_FILE))
-}
-
-// Walks upward from `start` looking for the agent folder (the dir containing
-// typeclaw.json). Returns the found dir, or null if nothing is found before
-// the walk hits a stop boundary.
-//
-// Stop boundaries (whichever comes first, checked at every level):
-//   1. The current dir contains typeclaw.json — return it.
-//   2. The current dir contains .git — return null. A .git boundary marks a
-//      project root; refusing to cross it prevents accidentally picking up an
-//      unrelated parent project, and matches how typeclaw itself initializes
-//      one .git per agent folder.
-//   3. We've reached the filesystem root — return null.
-//
-// The `.git` check fires AFTER the typeclaw.json check at the same level so
-// that walking up from a subdir of the agent (e.g. `<agent>/workspace/`) still
-// resolves to the agent root, even though the agent root itself contains both
-// typeclaw.json and .git.
-export function findAgentDir(start: string): string | null {
-  let dir = resolve(start)
-  const root = resolve(dir, '/')
-  while (true) {
-    if (existsSync(join(dir, CONFIG_FILE))) return dir
-    if (existsSync(join(dir, '.git'))) return null
-    if (dir === root) return null
-    const parent = dirname(dir)
-    if (parent === dir) return null
-    dir = parent
-  }
-}
-
 const HATCHED_COMMIT_SUBJECT = 'Hatched 🐣'
 
 export async function isHatched(dir: string): Promise<boolean> {