typeclaw 0.30.0 → 0.31.0

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/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

@@ -183,6 +183,18 @@ export const MAX_POLICY_DENIED_CHANNEL_SENDS_PER_TURN = 3
 // including reasoning). Deliberately NOT lowered in `providers.ts`, where
 // `maxTokens` is the model's true capability that compaction math reads.
 export const CHANNEL_MAX_OUTPUT_TOKENS = 4096
+// Raised output-token budget threaded into the ONE re-prompt that follows a
+// `stopReason:'length'` empty turn. The default 4096 backstop bounds kimi's
+// degenerate repetition loop, but it is the same ceiling a *legitimate*
+// reasoning-heavy turn hits when it spends the whole pool thinking and emits no
+// prose — re-prompting under the identical cap reproduces the truncation. A
+// `length` truncation that the byte-identical loop guard did NOT catch is
+// evidence of genuine reasoning starved for room, not a repetition loop, so the
+// retry grants 4x headroom for thinking + a reply. Bounded (not 32000) so a
+// turn that IS looping still can't burn the full pi-ai default. Consumed
+// one-shot via `LiveSession.nextPromptMaxTokens`, then reset at the next real
+// user turn so the raised budget never leaks past the turn that needed it.
+export const CHANNEL_EMPTY_TURN_RETRY_MAX_OUTPUT_TOKENS = 16384
 // Ceiling on automatic re-prompts for a turn that ended with NO user-facing
 // reply AND no attempted send — the pure "the model burned its budget thinking
 // and produced nothing" failure. The canonical trigger is Fireworks'
@@ -200,18 +212,24 @@ export const CHANNEL_MAX_OUTPUT_TOKENS = 4096
 export const MAX_EMPTY_TURN_RETRIES = 2
 // Reminder-only nudge injected before an empty-turn retry. Uses the repo's
 // SYSTEM MESSAGE framing (see composeTurnPrompt) so persona-rich models do not
-// reply to the notice itself. Neutral by design: it asks for a direct reply
-// without prescribing length or tone, matching the chosen "just retry" posture.
+// reply to the notice itself. Names the actual failure (the prior turn ran out
+// of its output budget mid-reasoning and produced no reply) and asks the model
+// to keep its thinking short and answer directly — the empty turn was budget
+// exhaustion, not a forgotten tool call, so a "reply directly" nudge alone
+// would re-loop. The matching retry re-prompt also runs with a raised budget
+// (CHANNEL_EMPTY_TURN_RETRY_MAX_OUTPUT_TOKENS) so the room actually exists.
 export const EMPTY_TURN_RETRY_NUDGE = [
   '---',
   '**[SYSTEM MESSAGE — not from a human]**',
   '',
-  'Your previous turn ended without sending any reply to the channel. This is',
+  'Your previous turn ran out of its output budget before sending a reply — it',
+  'spent the whole turn thinking and produced nothing for the channel. 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.**',
   '',
-  'Respond to the last user message now with a direct answer via your channel',
-  'reply tool. If you genuinely have nothing to say, reply with `NO_REPLY`.',
+  'Answer the last user message now: keep any reasoning brief and send a direct',
+  'reply via your channel reply tool. If you genuinely have nothing to say,',
+  'reply with `NO_REPLY`.',
   '',
   '---',
 ].join('\n')
@@ -532,6 +550,13 @@ type LiveSession = {
   // increments it before injecting EMPTY_TURN_RETRY_NUDGE and reads it to decide
   // retry-vs-fallback. See the candidate===null branch.
   emptyTurnRetries: number
+  // One-shot output-token budget for the NEXT `session.prompt()` only.
+  // `installChannelOutputCap` reads and clears it per stream call, so it
+  // overrides the default backstop for exactly one re-prompt. Set by the
+  // empty-turn length-retry branch to CHANNEL_EMPTY_TURN_RETRY_MAX_OUTPUT_TOKENS
+  // and reset to undefined at each fresh user turn so the raised budget cannot
+  // leak past the turn that needed it.
+  nextPromptMaxTokens: number | undefined
   // Stamped by `markTurnSkipped` (called from the `skip_response` tool)
   // with the current `turnSeq`. Read at the top of `validateChannelTurn`:
   // if it matches the just-completed turn, recovery is skipped entirely
@@ -1417,6 +1442,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         inFlightToolSends: new Map(),
         policyDeniedToolSendsThisTurn: new Map(),
         emptyTurnRetries: 0,
+        nextPromptMaxTokens: undefined,
         skippedTurn: null,
         skipLockedSendTurn: null,
         pendingQuoteCandidate: null,
@@ -1704,14 +1730,22 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
   // Override pi-ai's hidden `Math.min(model.maxTokens, 32000)` output cap for
   // channel sessions by threading an explicit `maxTokens` into every stream
   // call. See CHANNEL_MAX_OUTPUT_TOKENS for why. Composes the existing streamFn
-  // (pi's default `streamSimple` unless a proxy was installed) and only fills
-  // `maxTokens` when the caller left it unset, so an explicit per-call value
-  // still wins.
+  // (pi's default `streamSimple` unless a proxy was installed). Precedence:
+  // an explicit per-call `maxTokens` always wins; otherwise a one-shot
+  // `live.nextPromptMaxTokens` (set by the empty-turn length-retry) is consumed
+  // and cleared so the raised budget applies to exactly one stream call;
+  // otherwise the default backstop.
   const installChannelOutputCap = (live: LiveSession): void => {
     const { agent } = live.session
     const inner = agent.streamFn
-    agent.streamFn = (model, context, options) =>
-      inner(model, context, { ...options, maxTokens: options?.maxTokens ?? CHANNEL_MAX_OUTPUT_TOKENS })
+    agent.streamFn = (model, context, options) => {
+      let maxTokens = options?.maxTokens
+      if (maxTokens === undefined && live.nextPromptMaxTokens !== undefined) {
+        maxTokens = live.nextPromptMaxTokens
+        live.nextPromptMaxTokens = undefined
+      }
+      return inner(model, context, { ...options, maxTokens: maxTokens ?? CHANNEL_MAX_OUTPUT_TOKENS })
+    }
   }
 
   const startTypingHeartbeat = (live: LiveSession): void => {
@@ -1904,10 +1938,13 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
           live.lastSentText.clear()
           live.pendingQuoteCandidate = captureQuoteCandidate(live.key.adapter, batch, observed)
           // A real user batch starts a fresh logical turn → restore the full
-          // empty-turn retry budget. Reset here (batch.length > 0) and NOT in
-          // the per-prompt block below, so the reminder-only iterations the
-          // retry itself queues do not refill the budget and loop forever.
+          // empty-turn retry budget and drop any raised output-token budget left
+          // over from a prior turn's length-retry. Reset here (batch.length > 0)
+          // and NOT in the per-prompt block below, so the reminder-only
+          // iterations the retry itself queues do not refill the budget and loop
+          // forever (and the raised cap stays scoped to the turn that set it).
           live.emptyTurnRetries = 0
+          live.nextPromptMaxTokens = undefined
         } else if (live.lastTurnAuthorId !== null) {
           live.currentTurnEngageReactions = []
           // Reminder-only turn (batch.length === 0, reminders.length > 0):
@@ -3037,8 +3074,18 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
       }
       if (!attemptedSendThisTurn && live.emptyTurnRetries < MAX_EMPTY_TURN_RETRIES) {
         live.emptyTurnRetries++
+        // Raise the re-prompt's budget ONLY for a `length` truncation: that is
+        // the budget-exhaustion case (reasoning ate the whole pool before any
+        // prose), so the retry needs room to finish thinking AND reply. `error`
+        // and `aborted` are not budget exhaustion — an upstream failure or the
+        // terminal-reply abort — so they retry under the default backstop.
+        // Consumed one-shot by installChannelOutputCap on the next prompt().
+        if (assistantLeafStopReason(live.session) === 'length') {
+          live.nextPromptMaxTokens = CHANNEL_EMPTY_TURN_RETRY_MAX_OUTPUT_TOKENS
+        }
         logger.warn(
-          `[channels] ${live.keyId} empty_turn_retry attempt=${live.emptyTurnRetries}/${MAX_EMPTY_TURN_RETRIES}`,
+          `[channels] ${live.keyId} empty_turn_retry attempt=${live.emptyTurnRetries}/${MAX_EMPTY_TURN_RETRIES} ` +
+            `max_tokens=${live.nextPromptMaxTokens ?? CHANNEL_MAX_OUTPUT_TOKENS}`,
         )
         live.pendingSystemReminders.push(EMPTY_TURN_RETRY_NUDGE)
         return
@@ -4355,18 +4402,25 @@ function recoverableAssistantText(
   return null
 }
 
-// True only when the leaf is an assistant message that was CUT OFF mid-output:
-// `length` (hit the token cap — the canonical kimi reasoning-loop), `error`, or
-// `aborted`. This is the precise signature of "the model was producing but got
-// truncated", as distinct from a turn that produced no assistant message at all
-// (leaf undefined / a non-assistant entry), which is a benign empty/cold turn —
-// NOT something to re-prompt. The empty-turn retry guard keys off this so it
-// fires for real degenerations and stays silent for cold sessions.
-function assistantLeafTruncated(session: AgentSession): boolean {
+// The truncation stop reason when the leaf is an assistant message that was CUT
+// OFF mid-output — `length` (hit the token cap, the canonical kimi reasoning-
+// loop), `error`, or `aborted` — else undefined. This is the precise signature
+// of "the model was producing but got truncated", as distinct from a turn that
+// produced no assistant message at all (leaf undefined / a non-assistant
+// entry), which is a benign empty/cold turn. Callers that only need the boolean
+// use `assistantLeafTruncated`; the retry guard reads the reason itself because
+// the raised reasoning budget is justified ONLY for `length` (budget
+// exhaustion), not for `error`/`aborted`.
+function assistantLeafStopReason(session: AgentSession): 'length' | 'error' | 'aborted' | undefined {
   const leaf = session.sessionManager.getLeafEntry()
-  if (!leaf || leaf.type !== 'message' || leaf.message.role !== 'assistant') return false
+  if (!leaf || leaf.type !== 'message' || leaf.message.role !== 'assistant') return undefined
   const stop = leaf.message.stopReason
-  return stop === 'length' || stop === 'error' || stop === 'aborted'
+  if (stop === 'length' || stop === 'error' || stop === 'aborted') return stop
+  return undefined
+}
+
+function assistantLeafTruncated(session: AgentSession): boolean {
+  return assistantLeafStopReason(session) !== undefined
 }
 
 function visibleAssistantText(message: AssistantMessage): 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)
   }