typeclaw 0.29.0 → 0.30.1

package/src/channels/adapters/github/inbound.ts

@@ -9,6 +9,7 @@ import { removeRequestedReviewer } from './decoy-reviewer'
 import type { DeliveryDedup } from './dedup'
 import { isGithubEventAllowed } from './event-allowlist'
 import { encodeGithubReactionRef, type GithubReactionTarget } from './reactions'
+import { fetchSelfReviewBlocking } from './review-state'
 import { listUnresolvedSelfReviewThreads } from './review-thread-resolver'
 
 export type GithubInboundLogger = { info: (m: string) => void; warn: (m: string) => void; error: (m: string) => void }
@@ -83,14 +84,16 @@ export function createGithubWebhookHandler(options: GithubWebhookHandlerOptions)
     }
 
     // A push to an open PR (`synchronize`) is not a message to react to — it is
-    // a trigger to re-check whether the new commits addressed the bot's own
-    // still-open review threads. The check needs a GraphQL round-trip, so it
-    // runs OFF the ACK path (like the decoy-reviewer drop) and only wakes a
-    // session when there is at least one such thread. Returning here also keeps
+    // a trigger to re-evaluate the bot's own outstanding review obligations on
+    // this PR: unresolved review threads it authored AND a sticky
+    // CHANGES_REQUESTED block (which leaves no threads when filed as a top-level
+    // verdict — the black hole this path closes). Both need an API round-trip,
+    // so it runs OFF the ACK path (like the decoy-reviewer drop) and only wakes a
+    // session when an obligation is outstanding. Returning here also keeps
     // synchronize out of the generic awareness-only fallthrough below.
     if (event === 'pull_request' && action === 'synchronize') {
       if (delivery !== '') options.dedup.add(delivery)
-      scheduleReviewThreadRecheck({ payload, selfLogin, options })
+      scheduleReviewFollowup({ payload, selfLogin, options })
       return ok()
     }
 
@@ -187,7 +190,7 @@ function defaultScheduleBackgroundTask(task: () => Promise<void>): void {
   void task().catch(() => {})
 }
 
-function scheduleReviewThreadRecheck(input: {
+function scheduleReviewFollowup(input: {
   payload: Record<string, unknown>
   selfLogin: string | null
   options: GithubWebhookHandlerOptions
@@ -203,13 +206,27 @@ function scheduleReviewThreadRecheck(input: {
   if (repository === null || pullNumber === null) return
   const headSha = readString(readRecord(pr?.head), 'sha')
 
+  // Same webhook head SHA can arrive on several deliveries (a multi-commit push
+  // emits one synchronize per ref update). Dedup the follow-up on the head SHA
+  // so a single push wakes at most one re-review, distinct from the per-delivery
+  // dedup above. When headSha is absent we cannot dedup, so we skip the followup
+  // rather than risk a re-review storm.
+  if (headSha === null) {
+    options.logger.warn(`[github] synchronize for ${repository.owner}/${repository.name}#${pullNumber} has no head sha`)
+    return
+  }
+  const followupKey = `synchronize-followup:${repository.owner}/${repository.name}#${pullNumber}:${headSha}`
+  if (options.dedup.has(followupKey)) return
+  options.dedup.add(followupKey)
+
+  const reviewOn = options.reviewOn?.() ?? 'review_requested'
   const fetchImpl = options.fetchImpl ?? fetch
   const schedule = options.scheduleBackgroundTask ?? defaultScheduleBackgroundTask
   const target = `${repository.owner}/${repository.name}#${pullNumber}`
   schedule(async () => {
     try {
       const token = await authToken({ repoSlug: `${repository.owner}/${repository.name}` })
-      const result = await listUnresolvedSelfReviewThreads({
+      const threads = await listUnresolvedSelfReviewThreads({
         token,
         selfLogin,
         owner: repository.owner,
@@ -217,46 +234,63 @@ function scheduleReviewThreadRecheck(input: {
         prNumber: pullNumber,
         fetchImpl,
       })
-      if (!result.ok) {
-        options.logger.warn(`[github] review-thread recheck failed for ${target}: ${result.error}`)
+      if (!threads.ok) {
+        options.logger.warn(`[github] review-thread recheck failed for ${target}: ${threads.error}`)
         return
       }
-      if (result.threads.length === 0) return
+
+      // A held CHANGES_REQUESTED is the bot's own obligation regardless of how
+      // reviews are triggered, so re-evaluate it on push unless review is off.
+      let selfBlocking = false
+      if (reviewOn !== 'off') {
+        const blocking = await fetchSelfReviewBlocking({
+          token,
+          selfLogin,
+          owner: repository.owner,
+          repo: repository.name,
+          prNumber: pullNumber,
+          fetchImpl,
+        })
+        if (blocking.ok) selfBlocking = blocking.selfBlocking
+        else options.logger.warn(`[github] review-state recheck failed for ${target}: ${blocking.error}`)
+      }
+
+      const rootCommentIds = threads.threads.map((t) => t.rootCommentId)
+      if (rootCommentIds.length === 0 && !selfBlocking) return
       options.route(
-        buildRecheckInbound({
-          repository,
-          pullNumber,
-          headSha,
-          rootCommentIds: result.threads.map((t) => t.rootCommentId),
-          title: readString(pr, 'title'),
-        }),
+        withApprovalPolicy(
+          buildReviewFollowupInbound({
+            repository,
+            pullNumber,
+            headSha,
+            rootCommentIds,
+            selfBlocking,
+            title: readString(pr, 'title'),
+          }),
+          options.allowApprove?.() ?? true,
+        ),
       )
     } catch (err) {
       options.logger.warn(
-        `[github] review-thread recheck failed for ${target}: ${err instanceof Error ? err.message : String(err)}`,
+        `[github] review followup failed for ${target}: ${err instanceof Error ? err.message : String(err)}`,
       )
     }
   })
 }
 
-function buildRecheckInbound(input: {
+function buildReviewFollowupInbound(input: {
   repository: { owner: string; name: string }
   pullNumber: number
-  headSha: string | null
+  headSha: string
   rootCommentIds: readonly number[]
+  selfBlocking: boolean
   title: string | null
 }): InboundMessage {
-  const { repository, pullNumber, headSha, rootCommentIds, title } = input
+  const { repository, pullNumber, headSha, rootCommentIds, selfBlocking, title } = input
   const titleSegment = title !== null && title.trim() !== '' ? `: "${title}"` : ''
-  const shaSegment = headSha !== null ? ` (now at ${headSha.slice(0, 7)})` : ''
-  const idList = rootCommentIds.join(', ')
   const text =
-    `PR #${pullNumber}${titleSegment} received new commits${shaSegment}. ` +
-    `You have ${rootCommentIds.length} unresolved review thread(s) you authored on this PR ` +
-    `(root comment id(s): ${idList}). For each, check whether the new commits addressed your ` +
-    `concern. If addressed, reply on that thread via channel_send with a short acknowledgement ` +
-    `and resolve_review_thread: true (the thread id is the root comment id). If not addressed, ` +
-    `leave it open. If none are addressed, end your turn without replying.`
+    `PR #${pullNumber}${titleSegment} received new commits (now at ${headSha.slice(0, 7)}). ` +
+    followupInstruction(rootCommentIds, selfBlocking)
 
   return {
     adapter: 'github',
@@ -264,7 +298,7 @@ function buildRecheckInbound(input: {
     chat: `pr:${pullNumber}`,
     thread: null,
     text,
-    externalMessageId: `pr-${pullNumber}-recheck-${headSha ?? 'unknown'}`,
+    externalMessageId: `pr-${pullNumber}-recheck-${headSha}`,
     authorId: 'github-system',
     authorName: 'github',
     authorIsBot: false,
@@ -277,6 +311,30 @@ function buildRecheckInbound(input: {
   }
 }
 
+function followupInstruction(rootCommentIds: readonly number[], selfBlocking: boolean): string {
+  const threadPart =
+    rootCommentIds.length > 0
+      ? `You have ${rootCommentIds.length} unresolved review thread(s) you authored on this PR ` +
+        `(root comment id(s): ${rootCommentIds.join(', ')}). For each, check whether the new commits ` +
+        `addressed your concern. If addressed, reply on that thread via channel_send with a short ` +
+        `acknowledgement and resolve_review_thread: true (the thread id is the root comment id); ` +
+        `if not, leave it open. `
+      : ''
+  // A held CHANGES_REQUESTED never clears itself: GitHub keeps the block until a
+  // fresh APPROVE/COMMENT/dismiss, so a blocking follow-up must always end with a
+  // submitted verdict — the "end without replying" escape hatch is reserved for
+  // the thread-only path, where leaving every thread open is a valid no-op.
+  const blockingPart = selfBlocking
+    ? `Your latest review on this PR is still CHANGES_REQUESTED, which keeps the PR blocked until you ` +
+      `submit a fresh review. Re-review the current head against the concerns from that blocking review ` +
+      `and always end with a new verdict: if the commits resolve your concerns, submit an APPROVE ` +
+      `(or COMMENT if approval is disabled) to clear the block; if concerns remain, submit a new ` +
+      `CHANGES_REQUESTED explaining what is still blocking. `
+    : ''
+  const tail = selfBlocking ? '' : 'If none are addressed, end your turn without replying.'
+  return `${threadPart}${blockingPart}${tail}`
+}
+
 export async function verifySignature(body: string, secret: string, sigHeader: string): Promise<boolean> {
   const expected = `sha256=${createHmac('sha256', secret).update(body).digest('hex')}`
   const a = Buffer.from(expected)

package/src/channels/adapters/github/review-state.ts

@@ -48,6 +48,33 @@ export function createGithubReviewStateResolver(deps: {
   }
 }
 
+export type SelfReviewBlockingResult =
+  | { ok: true; selfBlocking: boolean }
+  | { ok: false; error: string; code: 'not-found' | 'permission-denied' | 'transient' }
+
+// Last DECISIVE self review == CHANGES_REQUESTED? (COMMENTED/PENDING ignored, as
+// in createGithubReviewStateResolver.) Standalone so the synchronize follow-up
+// skips the reviewDecision round-trip the stranding guard needs but this doesn't.
+export async function fetchSelfReviewBlocking(deps: {
+  token: string
+  selfLogin: string
+  owner: string
+  repo: string
+  prNumber: number
+  fetchImpl?: typeof fetch
+}): Promise<SelfReviewBlockingResult> {
+  const fetchImpl = deps.fetchImpl ?? fetch
+  const reviews = await fetchSelfReviews(
+    fetchImpl,
+    deps.token,
+    { owner: deps.owner, repo: deps.repo, prNumber: deps.prNumber },
+    deps.selfLogin,
+  )
+  if (!reviews.ok) return { ok: false, error: reviews.error, code: reviews.code }
+  const lastDecisive = reviews.states.filter(isDecisive).at(-1) ?? null
+  return { ok: true, selfBlocking: lastDecisive === 'CHANGES_REQUESTED' }
+}
+
 type Target = { owner: string; repo: string; prNumber: number }
 
 function parseTarget(workspace: string, chat: string): Target | null {

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

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

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

@@ -3,9 +3,34 @@ export type OutboundFloodCheckResult = { ok: true } | { ok: false; reason: strin
 const MIN_LENGTH = 40
 const MAX_RUN = 30
 const MIN_LONG_LENGTH = 80
-const MIN_UNIQUE_RATIO = 0.05
 const MAX_DOMINANCE = 0.9
 
+// Contiguous-span detector for multi-character floods ("lollol...", "ababab...",
+// repeated emoji pairs) — including a flood body buried inside otherwise-varied
+// text, which a whole-message periodicity test misses. Strict equality (no
+// mismatch budget) and a large span floor keep it clear of incidental prose
+// repetition ("---", "....", "hahaha", code indentation, table separators).
+const MAX_REPEATING_PERIOD = 32
+// Span floor is deliberately a flood boundary, not a "never-deny" guarantee: it
+// catches obvious short-period floods like "ab".repeat(300) (600 chars) and
+// "lol".repeat(300) (900). Hundreds of byte-identical rows or box-art lines also
+// trip it — that output is information-poor and flood-like, and raising the floor
+// to clear it would let those real floods through. Tables/diagrams with varying
+// cells break periodicity and pass.
+const MIN_PERIODIC_SPAN = 384
+const MIN_PERIODIC_REPETITIONS = 24
+
+// Narrow last resort: structured text (code, tables, logs) is often lower-
+// entropy than prose, so this only fires on a tiny alphabet at real length.
+const MIN_ENTROPY_LENGTH = 200
+const MAX_TINY_ALPHABET_SIZE = 4
+const VERY_LOW_ENTROPY_BITS = 1.25
+
+// Replaces the old `uniqueRatio = distinctChars / length` gate, which was
+// length-coupled: natural language draws from a fixed alphabet, so any reply
+// past ~(alphabet/0.05) chars failed it regardless of variety — a 2.9KB
+// markdown report was silently dropped. Every check below is bounded-run or
+// length-independent, so length alone never makes a reply look like a flood.
 export function checkOutboundFlood(text: string): OutboundFloodCheckResult {
   if (text.length < MIN_LENGTH) return { ok: true }
 
@@ -18,12 +43,18 @@ export function checkOutboundFlood(text: string): OutboundFloodCheckResult {
   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)}` }
 
+  const span = findLongestPeriodicSpan(graphemes)
+  if (span !== undefined) return { ok: false, reason: `repeated-pattern-span:${span.period}:${span.spanLength}` }
+
+  if (graphemes.length >= MIN_ENTROPY_LENGTH && counts.size <= MAX_TINY_ALPHABET_SIZE) {
+    const entropy = shannonEntropyBitsPerGrapheme(counts, graphemes.length)
+    if (entropy < VERY_LOW_ENTROPY_BITS) return { ok: false, reason: `low-entropy:${entropy.toFixed(2)}` }
+  }
+
   return { ok: true }
 }
 
@@ -42,6 +73,42 @@ function findLongestRun(graphemes: readonly string[]): number {
   return longest
 }
 
+// Longest contiguous span (in graphemes) that is exactly periodic at some
+// period 2..32, or undefined when no span clears the flood floor. Period 1 is
+// left to the run check above. A span must reach MIN_PERIODIC_SPAN graphemes
+// AND repeat its unit MIN_PERIODIC_REPETITIONS times — the larger bound wins,
+// so a 32-period unit needs 768 graphemes, not three echoes of a 32-char line.
+function findLongestPeriodicSpan(graphemes: readonly string[]): { period: number; spanLength: number } | undefined {
+  const maxPeriod = Math.min(MAX_REPEATING_PERIOD, Math.floor(graphemes.length / MIN_PERIODIC_REPETITIONS))
+  let best: { period: number; spanLength: number } | undefined
+  for (let period = 2; period <= maxPeriod; period++) {
+    let matches = 0
+    let longestForPeriod = 0
+    for (let i = period; i < graphemes.length; i++) {
+      if (graphemes[i] === graphemes[i - period]) {
+        matches++
+        const spanLength = matches + period
+        if (spanLength > longestForPeriod) longestForPeriod = spanLength
+      } else {
+        matches = 0
+      }
+    }
+    const requiredSpan = Math.max(MIN_PERIODIC_SPAN, period * MIN_PERIODIC_REPETITIONS)
+    if (longestForPeriod < requiredSpan) continue
+    if (best === undefined || longestForPeriod > best.spanLength) best = { period, spanLength: longestForPeriod }
+  }
+  return best
+}
+
+function shannonEntropyBitsPerGrapheme(counts: Map<string, number>, length: number): number {
+  let entropy = 0
+  for (const count of counts.values()) {
+    const probability = count / length
+    entropy -= probability * Math.log2(probability)
+  }
+  return entropy
+}
+
 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)

package/src/channels/router.ts

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

package/src/compose/discover.ts

@@ -1,6 +1,7 @@
 import { readdirSync } from 'node:fs'
 import { join, resolve } from 'node:path'
 
+import { loadConfigSyncOrDefaults } from '@/config'
 import { containerNameFromCwd } from '@/container'
 import { isInitialized } from '@/init'
 
@@ -17,7 +18,9 @@ export type AgentEntry = {
 //
 // Underscore-prefixed names are also skipped so operators can park a disabled
 // or in-progress agent next to live ones (e.g. `_archived-coder/`) without
-// compose touching it.
+// compose touching it. Agents with `compose.exclude: true` in typeclaw.json
+// are skipped too — the in-config opt-out for operators who don't want to rename
+// the folder.
 //
 // Returns an empty array when rootCwd doesn't exist or is empty — discovery is
 // not the place to fail; the caller decides what to do with zero agents.
@@ -40,6 +43,7 @@ export function discoverAgents(rootCwd: string): AgentEntry[] {
     if (entry.name.startsWith('_')) continue
     const cwd = join(root, entry.name)
     if (!isInitialized(cwd)) continue
+    if (loadConfigSyncOrDefaults(cwd).compose.exclude) continue
     agents.push({ name: entry.name, cwd, containerName: containerNameFromCwd(cwd) })
   }
 

package/src/config/config.ts

@@ -338,6 +338,39 @@ 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.
+export const sandboxSchema = z
+  .object({
+    realProc: z.boolean().default(false),
+  })
+  .default({ realProc: false })
+
+export type SandboxConfig = z.infer<typeof sandboxSchema>
+
+// Host-stage `typeclaw compose` knobs. `exclude: true` skips this agent during
+// compose discovery (same effect as parking it under an `_`-prefixed dir, but
+// without renaming the folder). The container never reads this block — it's a
+// pure compose CLI hint, so omitting it keeps the agent in every compose
+// operation. Namespaced under `compose` so future compose-only settings have a
+// home without crowding the top level.
+export const composeSchema = z
+  .object({
+    exclude: z.boolean().default(false),
+  })
+  .default({ exclude: false })
+
+export type ComposeConfig = z.infer<typeof composeSchema>
+
 // Reverse-proxy tunnels expose a container-private port to the public internet
 // via a managed subprocess (cloudflared) or a user-supplied external URL.
 // See AGENTS.md `## Tunnels`. Keeping the enum scoped to what's implemented
@@ -490,9 +523,11 @@ export const configSchema = z
     // time. Defaults to `[]`. Hatching appends the agent's chosen name
     // here, so a freshly-hatched bot already has its identity wired up.
     alias: z.array(z.string().trim().min(1)).default([]),
+    compose: composeSchema,
     channels: channelsSchema,
     portForward: portForwardSchema,
     network: networkSchema,
+    sandbox: sandboxSchema,
     docker: dockerSchema,
     git: gitSchema,
     roles: rolesConfigSchema.optional(),
@@ -632,9 +667,11 @@ export const FIELD_EFFECTS: Record<string, FieldEffect> = {
   mcpServers: 'restart-required',
   plugins: 'restart-required',
   alias: 'applied',
+  compose: 'ignored',
   channels: 'applied',
   portForward: 'restart-required',
   network: 'restart-required',
+  sandbox: 'restart-required',
   tunnels: 'restart-required',
   'docker.file': 'restart-required',
   'git.ignore': 'restart-required',
@@ -723,6 +760,7 @@ export function extractPluginConfigs(raw: unknown): Record<string, unknown> {
     'mounts',
     'plugins',
     'alias',
+    'compose',
     'channels',
     'portForward',
     'network',

package/src/container/start.ts

@@ -514,6 +514,20 @@ 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
+  // `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.
+  if (cfg.sandbox.realProc) {
+    runArgs.push('--cap-add=SYS_ADMIN')
+  }
+
   if (hostdControl) {
     runArgs.push('--add-host', HOST_GATEWAY_ALIAS)
   }

package/src/migrations/index.ts

@@ -0,0 +1,35 @@
+import { MIGRATION_ID, migrateSecretsV1ToV2, type SecretsMigrationResult } from './secrets-v1-to-v2'
+
+export { MIGRATION_ID, migrateSecretsV1ToV2, type SecretsMigrationResult }
+
+export type Migration = {
+  id: string
+  run: (agentDir: string) => SecretsMigrationResult
+}
+
+export type MigrationOutcome = { id: string; changed: boolean; summary: string; error?: string }
+
+const MIGRATIONS: readonly Migration[] = [{ id: MIGRATION_ID, run: migrateSecretsV1ToV2 }]
+
+// Each migration is isolated: a throw is captured per-migration so one folder's
+// unsafe state (e.g. both auth.json and a non-empty secrets.json) is reported
+// loudly without aborting boot or blocking later migrations. Returns one
+// outcome per registered migration so the caller can log what happened.
+export function runStartupMigrations(
+  agentDir: string,
+  log: (message: string) => void = (m) => console.warn(m),
+): MigrationOutcome[] {
+  const outcomes: MigrationOutcome[] = []
+  for (const migration of MIGRATIONS) {
+    try {
+      const result = migration.run(agentDir)
+      if (result.changed) log(`migration ${migration.id}: ${result.summary}`)
+      outcomes.push({ id: migration.id, changed: result.changed, summary: result.summary })
+    } catch (err) {
+      const error = err instanceof Error ? err.message : String(err)
+      log(`migration ${migration.id} failed: ${error}`)
+      outcomes.push({ id: migration.id, changed: false, summary: 'failed', error })
+    }
+  }
+  return outcomes
+}