typeclaw 0.30.0 → 0.30.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typeclaw",
-  "version": "0.30.0",
+  "version": "0.30.1",
   "homepage": "https://github.com/typeclaw/typeclaw#readme",
   "bugs": {
     "url": "https://github.com/typeclaw/typeclaw/issues"

package/scripts/verify-realproc-sandbox.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+# Manual acceptance check for the sandbox.realProc strategy (src/sandbox/build.ts).
+# Not a unit test: it needs a Linux container with CAP_SYS_ADMIN, which the macOS
+# dev host and standard CI runners cannot provide, so it lives here as an
+# operator-runnable script instead of a skipIf-everywhere test.
+#
+# Proves two properties of the two-phase `unshare --mount-proc -- bwrap` sandbox:
+#   1. An external package runner (bunx) runs to completion (no Bun "NotDir").
+#   2. A secret in a sibling process's environment NEVER appears in any
+#      /proc/*/environ the sandbox can read (PID-namespace scoping holds).
+#
+# Usage: scripts/verify-realproc-sandbox.sh [image]
+#   image defaults to ghcr.io/typeclaw/typeclaw-base:<version-from-package.json>
+set -euo pipefail
+
+IMAGE="${1:-}"
+if [ -z "$IMAGE" ]; then
+  version="$(node -p "require('./package.json').version" 2>/dev/null || echo latest)"
+  IMAGE="ghcr.io/typeclaw/typeclaw-base:${version}"
+fi
+
+secret="TYPECLAW_REALPROC_LEAK_CANARY_$$"
+
+inner='
+echo "=== bunx via real-proc sandbox ==="
+bunx cowsay "real-proc ok" 2>&1 | tail -6
+echo "bunx exit=$?"
+echo "=== visible pids (sandbox should NOT see the canary holder) ==="
+ls /proc | grep -E "^[0-9]+$" | tr "\n" " "; echo
+echo "=== leak scan ==="
+found=0
+for f in /proc/[0-9]*/environ; do
+  if tr "\0" "\n" < "$f" 2>/dev/null | grep -q "CANARY_TOKEN"; then
+    echo "LEAK:$f"; found=1
+  fi
+done
+if [ $found -eq 0 ]; then echo "NO_LEAK_CONFIRMED"; else echo "LEAK_DETECTED"; exit 1; fi
+'
+inner="${inner//CANARY_TOKEN/$secret}"
+
+# The real-proc argv shape mirrors buildArgv() in src/sandbox/build.ts. Keep in
+# sync if that helper changes.
+runner="
+${secret}_holder() { :; }
+env CANARY=${secret} sleep 120 &
+unshare --pid --fork --mount --mount-proc -- \
+  bwrap --unshare-user --unshare-ipc --unshare-uts --unshare-cgroup \
+        --new-session --die-with-parent --clearenv \
+        --setenv PATH /usr/local/bin:/usr/bin:/bin --setenv HOME /tmp --setenv LANG C.UTF-8 \
+        --ro-bind /usr /usr --ro-bind /etc /etc --dev /dev --tmpfs /tmp \
+        --ro-bind-try /bin /bin --ro-bind-try /sbin /sbin --ro-bind-try /lib /lib --ro-bind-try /lib64 /lib64 \
+        --ro-bind /proc /proc \
+        bash -c '$inner'
+"
+
+echo "Image: $IMAGE"
+docker run --rm --security-opt seccomp=unconfined --cap-add SYS_ADMIN \
+  -e "CANARY=${secret}" "$IMAGE" bash -c "$runner"

package/src/agent/plugin-tools.ts

@@ -23,6 +23,7 @@ import {
   checkNonWorkspaceWriteGuard,
   checkSkillAuthoringGuard,
 } from '@/bundled-plugins/guard/policy'
+import { config } from '@/config/config'
 import type { PermissionService } from '@/permissions/permissions'
 import type {
   BuiltinToolRef,
@@ -582,6 +583,17 @@ async function applyBashSandbox(
   // bwrap does --clearenv, so the overlay must be re-introduced via env.set or
   // it would never reach the sandboxed process (the non-sandboxed spawnHook
   // path does not run when the command is rewritten to a bwrap invocation).
+  // 'real-proc' gives a sandboxed JS package runner a working /proc/self/{fd,
+  // maps} so `bunx`/`bun add`/`bun run <pkg>` stop aborting with Bun's NotDir.
+  // Opt-in (default 'tmpfs') because it makes start.ts grant the container
+  // CAP_SYS_ADMIN at boot. Read from the boot-time `config` snapshot, NOT live
+  // getConfig(): sandbox.realProc is restart-required, and the strategy MUST
+  // track the boot-time capability. A `typeclaw reload` that flips realProc to
+  // true would otherwise make this emit `unshare --mount-proc` in a container
+  // booted WITHOUT CAP_SYS_ADMIN, so the mount fails instead of the old tmpfs
+  // strategy holding until restart. `config` never changes on reload.
+  // procSelfExe is only consumed by the 'tmpfs' branch.
+  const realProc = config.sandbox.realProc
   const { commandString } = buildSandboxedCommand(command, {
     mounts: [
       { type: 'ro-bind', source: agentDir, dest: agentDir },
@@ -592,6 +604,7 @@ async function applyBashSandbox(
     protected: protectedZones,
     network: 'inherit',
     cwd: agentDir,
+    proc: realProc ? 'real-proc' : 'tmpfs',
     procSelfExe: resolveProcSelfExe(),
     ...(envOverlay !== undefined ? { env: { set: envOverlay } } : {}),
   })

package/src/agent/system-prompt.ts

@@ -93,7 +93,7 @@ Delegate focused work to subagents via \`spawn_subagent\`, \`subagent_output\`,
 
 There are three delegation modes. Pick deliberately.
 
-**Mode A — Research fan-out.** Need information and the search is broad? Fire 2-5 subagents (usually \`explorer\`/\`scout\`) in parallel with \`run_in_background: true\`, then end your response. A \`<system-reminder>\` lands per completion; call \`subagent_output\` once per task_id to collect (it never blocks) and answer. Match the worker to the depth: a fast or narrow web lookup goes to \`scout\`; a fuzzy question that needs decomposition, many sources, cross-validation, and a synthesized verdict goes to \`researcher\` (don't do that grind inline with \`web_search\` yourself).
+**Mode A — Research fan-out.** Need information and the search is broad? Fire 2-5 subagents (usually \`explorer\`/\`scout\`) in parallel with \`run_in_background: true\`, then end your response. A \`<system-reminder>\` lands per completion; call \`subagent_output\` once per task_id to collect (it never blocks) and answer. Match the worker to the depth: a fast or narrow web lookup goes to \`scout\`; a fuzzy question that needs decomposition, many sources, cross-validation, and a synthesized verdict goes to \`researcher\` (don't do that grind inline with \`web_search\` yourself). When the user *explicitly* says "research"/"investigate" (or equivalent), you MUST spawn \`researcher\` — answering from training memory or a single inline \`web_search\` does not satisfy the request, even if you think you know the answer. (Fanning out \`scout\`/\`explorer\` underneath is fine, but it does not replace \`researcher\`.)
 
 **Mode B — Delegate-and-converse.** Asked to DO something long-running (>~30s: installs, builds, \`docker\`, scrapes, long test suites, multi-host loops, any noisy "fetch N and synthesize" chain)? Don't run it inline — blocking your own \`bash\` freezes the conversation and stalls the channel typing heartbeat (\`MAX_TYPING_HEARTBEAT_MS\`). Spawn one subagent (\`operator\` for side effects, \`scout\` for a quick web lookup, \`researcher\` for a deep multi-source "fetch N and synthesize" investigation, \`planner\` when a multi-step goal needs a sequenced, risk-aware plan before anyone acts) with \`run_in_background: true\`, acknowledge, and KEEP TALKING. Single fast calls (\`git status\`, one known-endpoint \`curl\`) stay inline. When the completion reminder lands, weave the result in; in a channel session, the completion \`<system-reminder>\` is NOT a user message but plain text is still invisible — Surface the result via \`channel_reply\` (or \`channel_send\`). If you already posted the substantive answer in the spawn turn, prefer \`skip_response({ reason: "result confirms prior reply" })\` over going silent.
 

package/src/bundled-plugins/github-cli-auth/approve-idempotency.ts

@@ -1,13 +1,17 @@
 import type { ReviewVerdict } from '@/channels/github-review-turn-ledger'
 
+// `NONE` covers "never reviewed" and "last decisive review was DISMISSED" — both
+// mean a fresh verdict is legitimate (not a duplicate).
+export type EffectiveVerdict = 'APPROVED' | 'CHANGES_REQUESTED' | 'NONE'
+
 export type EffectiveApprovalResolver = (target: {
   workspace: string
   prNumber: number
-}) => Promise<{ ok: true; alreadyApproved: boolean } | { ok: false }>
+}) => Promise<{ ok: true; effective: EffectiveVerdict } | { ok: false }>
 
 export type ApproveBlock = { block: true; reason: string }
 
-export type ApproveIdempotencyGuard = {
+export type ReviewVerdictGuard = {
   guard: (args: {
     callId: string
     workspace: string
@@ -17,78 +21,135 @@ export type ApproveIdempotencyGuard = {
   release: (args: { callId: string; succeeded: boolean }) => void
 }
 
-const DUPLICATE_REASON =
-  'This bot has already approved this pull request. A second APPROVE would post a redundant review. ' +
-  'If you intended to change your verdict, request changes or dismiss the prior review instead of re-approving.'
+// Back-compat alias: the guard now covers REQUEST_CHANGES too, not just APPROVE.
+export type ApproveIdempotencyGuard = ReviewVerdictGuard
+
+function duplicateReason(verdict: ReviewVerdict): string {
+  if (verdict === 'APPROVE') {
+    return (
+      'This bot already holds a standing APPROVED review on this pull request. A second APPROVE would ' +
+      'post a redundant review. If you intended to change your verdict, request changes or dismiss the ' +
+      'prior review instead of re-approving.'
+    )
+  }
+  return (
+    'This bot already holds a standing CHANGES_REQUESTED review on this pull request. A second ' +
+    'REQUEST_CHANGES would post a redundant blocking review. The prior review is still live — push a fix ' +
+    'and APPROVE, or reply in the existing thread, instead of re-requesting changes.'
+  )
+}
+
+const CONCURRENT_REASON =
+  'Another session in this agent is already submitting a formal review verdict for this pull request. ' +
+  'Only one verdict may land per PR — do not submit a second review; the in-flight one will post.'
+
+// The standing verdict a fresh attempt would duplicate. APPROVE duplicates a
+// standing APPROVED; REQUEST_CHANGES duplicates a standing CHANGES_REQUESTED.
+function duplicatesStanding(verdict: ReviewVerdict, effective: EffectiveVerdict): boolean {
+  return verdict === 'APPROVE' ? effective === 'APPROVED' : effective === 'CHANGES_REQUESTED'
+}
+
+// How long a reservation may sit before it is treated as abandoned. A normal
+// `gh` review submit completes in seconds; this only guards against a tool.after
+// that never fires (crash mid-command), so it must outlast a slow command yet
+// never strand a PR for long.
+const LEASE_TTL_MS = 5 * 60_000
+
+type Reservation = { key: string; token: number; createdAt: number }
 
-// Makes formal `gh ... event=APPROVE` idempotent per PR across turns, sessions,
-// and restarts. Two layers, each with a single job:
+// MODULE-LEVEL singletons, shared by every plugin instance in this process. The
+// github-cli-auth plugin's `plugin: async (ctx) => ...` factory may run once per
+// session, giving each its own closure — but all of those closures import THIS
+// module, so they coordinate through one Map. A closure-local Set (the prior
+// design) could not see a concurrent session's in-flight verdict, which is how
+// three sessions each landed an APPROVE on the same PR within ten seconds.
+const inFlightByPr = new Map<string, Reservation>()
+const reservationByCall = new Map<string, Reservation>()
+let tokenSeq = 0
+
+// Makes a formal `gh ... event=APPROVE|REQUEST_CHANGES` idempotent per PR across
+// turns, sessions, and (in-process) concurrent fan-out. Two layers:
+//
+//   1. A process-wide in-flight lease keyed by `workspace#prNumber`, held from
+//      tool.before through tool.after. While one verdict is mid-flight, every
+//      other session's verdict for the same PR is blocked — even though GitHub
+//      has not yet recorded the in-flight review. This is the layer the old
+//      closure-local Set could not provide: separate plugin instances meant
+//      separate Sets, so concurrent sessions never saw each other.
 //
-//   1. An in-process set of *in-flight* reservations (`pendingApprovals`) that
-//      blocks a second APPROVE while a first is still mid-flight in the same
-//      container — the concurrent-double-approve case the remote read can't see
-//      yet (GitHub hasn't recorded the in-flight review).
-//   2. The authoritative GitHub effective-state read, the SOLE source of truth
-//      for "the bot already holds a standing APPROVED review." It understands
-//      supersession: a later CHANGES_REQUESTED / DISMISSED demotes an earlier
-//      APPROVED, so the bot may legitimately re-approve.
+//   2. The authoritative GitHub effective-state read, consulted AFTER the lease
+//      is acquired. It catches the cross-restart case (lease lost) and tracks
+//      supersession: a later CHANGES_REQUESTED/DISMISSED demotes an earlier
+//      APPROVED, so a genuine re-verdict is allowed. Reads fail OPEN — a
+//      transient error must never strand a genuine first verdict; the lease
+//      still covers the concurrent case while the command runs.
 //
-// The set is strictly an in-flight lock — never a persistent "already approved"
-// memory. A completed APPROVE drops its reservation in release(), so the next
-// APPROVE re-consults GitHub instead of being shadowed by a stale local entry.
-// That separation fixes the strand bug: once a standing approval is superseded
-// (PR back to CHANGES_REQUESTED), a stale local lock must not keep blocking a
-// genuine re-approve — only the remote read decides, and it now reports
-// alreadyApproved=false. Reads fail OPEN: a transient GitHub error must never
-// permanently strand a first approval; the in-flight reservation still covers
-// the concurrent case.
+// The lease is released only in release() (tool.after) or on a terminal block,
+// never after the remote read — releasing early reopens the TOCTOU the lease
+// exists to close. Release is keyed by a per-call token so a late/stale
+// tool.after for a superseded reservation cannot drop a newer session's lease.
 export function createApproveIdempotencyGuard(deps: {
   resolveEffectiveApproval: EffectiveApprovalResolver
-}): ApproveIdempotencyGuard {
-  const pendingApprovals = new Set<string>()
-  const reservedByCall = new Map<string, string>()
+  now?: () => number
+}): ReviewVerdictGuard {
+  const now = deps.now ?? Date.now
 
   return {
     async guard(args): Promise<ApproveBlock | null> {
-      if (args.verdict !== 'APPROVE') return null
+      if (args.verdict !== 'APPROVE' && args.verdict !== 'REQUEST_CHANGES') return null
       const key = prKey(args.workspace, args.prNumber)
 
-      // Reserve BEFORE the await so two calls racing into guard() for the same
-      // PR cannot both observe an empty set: the loser sees the winner's
-      // in-flight reservation and is blocked. The reservation is provisional
-      // and is always cleared on a terminal path (block below or release()).
-      if (pendingApprovals.has(key)) return { block: true, reason: DUPLICATE_REASON }
-      pendingApprovals.add(key)
-      reservedByCall.set(args.callId, key)
+      // Reserve BEFORE the await so two calls racing into guard() for the same PR
+      // cannot both observe an empty map: the loser sees the winner's in-flight
+      // lease and is blocked. An expired lease (tool.after never fired) is
+      // reclaimable so a crash cannot permanently strand the PR.
+      const held = inFlightByPr.get(key)
+      if (held !== undefined && now() - held.createdAt < LEASE_TTL_MS) {
+        return { block: true, reason: CONCURRENT_REASON }
+      }
+      const reservation: Reservation = { key, token: ++tokenSeq, createdAt: now() }
+      inFlightByPr.set(key, reservation)
+      reservationByCall.set(args.callId, reservation)
 
       const remote = await deps.resolveEffectiveApproval({ workspace: args.workspace, prNumber: args.prNumber })
-      if (remote.ok && remote.alreadyApproved) {
-        // Standing approval upstream. Block, and release the in-flight lock now:
-        // a blocked command never reaches tool.after, so release() won't run for
-        // this callId. Leaving the key set would resurrect the strand bug — the
-        // GitHub read is authoritative for the standing-approval case, not a
-        // lingering local entry.
-        reservedByCall.delete(args.callId)
-        pendingApprovals.delete(key)
-        return { block: true, reason: DUPLICATE_REASON }
+      if (remote.ok && duplicatesStanding(args.verdict, remote.effective)) {
+        // Standing verdict upstream already matches. Block, and release the lease
+        // now: a blocked command never reaches tool.after, so release() won't run
+        // for this callId. Leaving the lease set would resurrect the strand bug —
+        // the GitHub read is authoritative for the standing case.
+        releaseReservation(args.callId, reservation)
+        return { block: true, reason: duplicateReason(args.verdict) }
       }
 
       return null
     },
 
     release(args): void {
-      const key = reservedByCall.get(args.callId)
-      if (key === undefined) return
-      reservedByCall.delete(args.callId)
-      // Always drop the in-flight lock, success or fail. On success the standing
-      // approval now lives on GitHub, so future APPROVEs are caught by the remote
-      // read (which tracks supersession); the local lock must not outlive the
-      // in-flight window and shadow that read.
-      pendingApprovals.delete(key)
+      const reservation = reservationByCall.get(args.callId)
+      if (reservation === undefined) return
+      releaseReservation(args.callId, reservation)
     },
   }
 }
 
+// Drop the lease only if THIS reservation still owns the key. A stale tool.after
+// for a reservation that was already superseded (e.g. reclaimed after TTL by a
+// newer session) must not yank the live session's lease.
+function releaseReservation(callId: string, reservation: Reservation): void {
+  reservationByCall.delete(callId)
+  const current = inFlightByPr.get(reservation.key)
+  if (current !== undefined && current.token === reservation.token) {
+    inFlightByPr.delete(reservation.key)
+  }
+}
+
 function prKey(workspace: string, prNumber: number): string {
   return `${workspace}#${prNumber}`
 }
+
+// Test-only: clear the process-wide lease state between cases.
+export function __resetReviewVerdictGuardForTest(): void {
+  inFlightByPr.clear()
+  reservationByCall.clear()
+  tokenSeq = 0
+}

package/src/bundled-plugins/github-cli-auth/effective-approval.ts

@@ -1,13 +1,12 @@
 import { GITHUB_API_BASE, githubJsonHeaders } from '@/channels/adapters/github/auth-pat'
 
-import type { EffectiveApprovalResolver } from './approve-idempotency'
-
-// Resolves whether THIS bot already has a standing APPROVED review on a PR, used
-// by the approve-idempotency guard to stop a second formal APPROVE after a
-// restart (the in-process pending set covers the same-container case but is lost
-// when the container bounces). Every failure returns { ok: false } so the guard
-// fails open — a transient read error must never permanently block a genuine
-// first approval.
+import type { EffectiveApprovalResolver, EffectiveVerdict } from './approve-idempotency'
+
+// Resolves THIS bot's standing decisive review on a PR, used by the review
+// verdict guard to stop a second formal verdict after a restart (the in-process
+// lease covers the same-container case but is lost when the container bounces).
+// Every failure returns { ok: false } so the guard fails open — a transient read
+// error must never permanently block a genuine first verdict.
 export function createGithubEffectiveApprovalResolver(deps: {
   resolveToken: (workspace: string) => Promise<string | null>
   fetchImpl?: typeof fetch
@@ -27,10 +26,16 @@ export function createGithubEffectiveApprovalResolver(deps: {
     if (reviews === null) return { ok: false }
 
     const lastDecisive = reviews.filter((r) => isSelf(r.login, r.isBot, self) && isDecisive(r.state)).at(-1)
-    return { ok: true, alreadyApproved: lastDecisive?.state === 'APPROVED' }
+    return { ok: true, effective: toEffective(lastDecisive?.state) }
   }
 }
 
+function toEffective(state: string | undefined): EffectiveVerdict {
+  if (state === 'APPROVED') return 'APPROVED'
+  if (state === 'CHANGES_REQUESTED') return 'CHANGES_REQUESTED'
+  return 'NONE'
+}
+
 // A bot's effective review is its LATEST decisive one. COMMENTED/PENDING are
 // non-deciding noise that must not clear an earlier APPROVED/CHANGES_REQUESTED;
 // a later CHANGES_REQUESTED or DISMISSED supersedes an earlier APPROVED. The

package/src/bundled-plugins/github-cli-auth/index.ts

@@ -11,7 +11,7 @@ import { classifyGhToken } from './token-class'
 export default definePlugin({
   plugin: async (ctx) => {
     const resolveTokenForRepo = ctx.github.resolveTokenForRepo
-    const approveGuard = createApproveIdempotencyGuard({
+    const verdictGuard = createApproveIdempotencyGuard({
       resolveEffectiveApproval: createGithubEffectiveApprovalResolver({
         resolveToken: async (workspace) => {
           const result = await resolveTokenForRepo(workspace)
@@ -28,7 +28,7 @@ export default definePlugin({
 
           const review = await noteReviewCommand({ callId: event.callId, command })
           if (review.detected !== null) {
-            const block = await approveGuard.guard({
+            const block = await verdictGuard.guard({
               callId: event.callId,
               workspace: review.detected.workspace,
               prNumber: review.detected.prNumber,
@@ -70,7 +70,7 @@ export default definePlugin({
             callId: event.callId,
             result: event.result,
           })
-          approveGuard.release({ callId: event.callId, succeeded: committed })
+          verdictGuard.release({ callId: event.callId, succeeded: committed })
         },
       },
     }

package/src/channels/adapters/discord-bot-format.ts

@@ -0,0 +1,191 @@
+// Discord renders no GitHub-flavored Markdown tables — a `| a | b |` block
+// shows up as literal pipes and dashes, so an agent reply that leans on a table
+// (very common) becomes unreadable. Discord DOES preserve whitespace verbatim
+// inside inline code spans, so we re-emit each table row as a single
+// backtick-wrapped line with columns padded to a fixed width. Columns line up
+// because every row is the same monospaced inline-code span. The header row is
+// additionally wrapped in `**...**` so it reads as a bold caption above the body.
+//
+// This is a line-walker, not a Markdown parser: it only touches blocks that
+// match the pipe-table shape (a `|`-bearing line followed by a `|---|` alignment
+// row) and leaves every other byte — prose, code fences, lists — untouched.
+
+const TABLE_SEP_RE = /^\s*\|?\s*:?-{3,}:?\s*(\|\s*:?-{3,}:?\s*)+\|?\s*$/
+const FENCE_RE = /^(\s*)(```+|~~~+)(.*)$/
+
+export function convertDiscordTables(input: string): string {
+  if (input === '') return ''
+  if (!input.includes('|')) return input
+
+  const lines = input.split('\n')
+  const out: string[] = []
+  let i = 0
+  let openFence: string | null = null
+
+  while (i < lines.length) {
+    const line = lines[i]!
+
+    // A code fence (``` / ~~~) suspends table detection until it closes — a
+    // table-shaped block inside a fence is literal text, not a table. The close
+    // must use the same fence char and be at least as long as the opener, per
+    // CommonMark.
+    const fence = FENCE_RE.exec(line)
+    if (fence !== null) {
+      const marker = fence[2]!
+      if (openFence === null) {
+        openFence = marker
+      } else if (marker[0] === openFence[0] && marker.length >= openFence.length) {
+        openFence = null
+      }
+      out.push(line)
+      i++
+      continue
+    }
+    if (openFence !== null) {
+      out.push(line)
+      i++
+      continue
+    }
+
+    // A table needs a `|`-bearing header line immediately followed by the
+    // alignment row; same disambiguation rule chunkMarkdown uses so a stray
+    // leading `|` in prose is not mistaken for a table.
+    if (line.includes('|') && i + 1 < lines.length && TABLE_SEP_RE.test(lines[i + 1]!)) {
+      const start = i
+      i += 2
+      while (i < lines.length && lines[i]!.includes('|') && lines[i]!.trim() !== '') {
+        i++
+      }
+      const tableLines = lines.slice(start, i)
+      out.push(renderTable(tableLines))
+      continue
+    }
+    out.push(line)
+    i++
+  }
+
+  return out.join('\n')
+}
+
+function renderTable(tableLines: string[]): string {
+  const headerCells = splitRow(tableLines[0]!)
+  const bodyRows = tableLines.slice(2).map(splitRow)
+  const widths = computeWidths([headerCells, ...bodyRows])
+
+  const header = wrapCode(padRow(headerCells, widths))
+  const renderedRows = [`**${header}**`, ...bodyRows.map((cells) => wrapCode(padRow(cells, widths)))]
+  return renderedRows.join('\n')
+}
+
+function splitRow(row: string): string[] {
+  // Trim one optional leading/trailing pipe, then split on the rest. A trailing
+  // backslash before a pipe escapes it, but GFM table escaping is rare in agent
+  // output — we keep it simple and split on bare pipes.
+  let trimmed = row.trim()
+  if (trimmed.startsWith('|')) trimmed = trimmed.slice(1)
+  if (trimmed.endsWith('|')) trimmed = trimmed.slice(0, -1)
+  return trimmed.split('|').map((cell) => cell.trim())
+}
+
+function computeWidths(rows: string[][]): number[] {
+  const widths: number[] = []
+  for (const row of rows) {
+    for (let c = 0; c < row.length; c++) {
+      const cellWidth = displayWidth(row[c]!)
+      if (widths[c] === undefined || cellWidth > widths[c]!) {
+        widths[c] = cellWidth
+      }
+    }
+  }
+  return widths
+}
+
+function padRow(cells: string[], widths: number[]): string {
+  const padded = widths.map((width, c) => padToWidth(cells[c] ?? '', width))
+  // Two spaces between columns keeps them visually distinct inside the
+  // monospaced span without a vertical-bar separator.
+  return padded.join('  ')
+}
+
+function padToWidth(cell: string, width: number): string {
+  const pad = width - displayWidth(cell)
+  return pad > 0 ? cell + ' '.repeat(pad) : cell
+}
+
+// Discord's monospaced inline-code font renders CJK ideographs, full-width
+// punctuation, and most emoji at two columns, while combining/zero-width marks
+// take none. `String.prototype.padEnd` counts UTF-16 code units, so padding by
+// `.length` leaves wide-character tables visually ragged. We iterate by code
+// point and sum per-glyph column widths so every cell pads to the same VISUAL
+// width. The ranges below are the standard East-Asian-Wide / Wide blocks plus
+// the common emoji planes; this is the same wcwidth approximation editors use.
+export function displayWidth(text: string): number {
+  let width = 0
+  for (const ch of text) {
+    width += charWidth(ch.codePointAt(0)!)
+  }
+  return width
+}
+
+function charWidth(cp: number): number {
+  if (isZeroWidth(cp)) return 0
+  if (isWide(cp)) return 2
+  return 1
+}
+
+function isZeroWidth(cp: number): boolean {
+  return (
+    cp === 0x200b || // zero-width space
+    (cp >= 0x0300 && cp <= 0x036f) || // combining diacritical marks
+    (cp >= 0x200c && cp <= 0x200f) || // ZWNJ/ZWJ/directional marks
+    (cp >= 0xfe00 && cp <= 0xfe0f) // variation selectors
+  )
+}
+
+function isWide(cp: number): boolean {
+  return (
+    (cp >= 0x1100 && cp <= 0x115f) || // Hangul Jamo
+    (cp >= 0x2e80 && cp <= 0x303e) || // CJK radicals, Kangxi
+    (cp >= 0x3041 && cp <= 0x33ff) || // Hiragana, Katakana, CJK symbols
+    (cp >= 0x3400 && cp <= 0x4dbf) || // CJK Ext A
+    (cp >= 0x4e00 && cp <= 0x9fff) || // CJK Unified Ideographs
+    (cp >= 0xa000 && cp <= 0xa4cf) || // Yi
+    (cp >= 0xac00 && cp <= 0xd7a3) || // Hangul Syllables
+    (cp >= 0xf900 && cp <= 0xfaff) || // CJK Compatibility Ideographs
+    (cp >= 0xfe30 && cp <= 0xfe4f) || // CJK Compatibility Forms
+    (cp >= 0xff00 && cp <= 0xff60) || // Fullwidth Forms
+    (cp >= 0xffe0 && cp <= 0xffe6) || // Fullwidth signs
+    (cp >= 0x2600 && cp <= 0x26ff) || // Miscellaneous Symbols (☀ ♻ ⚠ …)
+    (cp >= 0x2700 && cp <= 0x27bf) || // Dingbats (✅ ✔ ✨ ➡ …)
+    (cp >= 0x2b00 && cp <= 0x2bff) || // Misc Symbols and Arrows (⭐ …)
+    (cp >= 0x1f300 && cp <= 0x1faff) || // emoji, symbols, pictographs
+    (cp >= 0x20000 && cp <= 0x3fffd) // CJK Ext B+ (supplementary ideographic)
+  )
+}
+
+// CommonMark inline code: the delimiter must be a backtick run LONGER than any
+// run inside the content, otherwise an embedded `` ` `` (e.g. a cell holding
+// `bun test`) closes the span early and corrupts the row. When the content
+// begins or ends with a backtick, one space of padding is inserted on each side
+// so the delimiter is not adjacent to a content backtick; CommonMark strips that
+// single padding space on render, leaving our column widths intact.
+function wrapCode(text: string): string {
+  const fence = '`'.repeat(longestBacktickRun(text) + 1)
+  const needsPad = text.startsWith('`') || text.endsWith('`')
+  const pad = needsPad ? ' ' : ''
+  return `${fence}${pad}${text}${pad}${fence}`
+}
+
+function longestBacktickRun(text: string): number {
+  let longest = 0
+  let run = 0
+  for (const ch of text) {
+    if (ch === '`') {
+      run++
+      if (run > longest) longest = run
+    } else {
+      run = 0
+    }
+  }
+  return longest
+}

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

@@ -39,6 +39,7 @@ import {
   type InboundDropReason,
   renderPlaceholder,
 } from './discord-bot-classify'
+import { convertDiscordTables } from './discord-bot-format'
 import { createDiscordReactionCallback, createDiscordRemoveReactionCallback } from './discord-bot-reactions'
 import { enrichDiscordMessageReferences } from './discord-bot-reference'
 import {
@@ -647,7 +648,7 @@ export function createOutboundCallback(deps: {
     if (msg.adapter !== 'discord-bot') {
       return { ok: false, error: `unknown adapter: ${msg.adapter}` }
     }
-    const text = msg.text ?? ''
+    const text = convertDiscordTables(msg.text ?? '')
     const attachments = msg.attachments ?? []
     if (text === '' && attachments.length === 0) {
       return { ok: false, error: 'message has neither text nor attachments' }

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/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/sandbox/build.ts

@@ -36,14 +36,35 @@ export function buildSandboxedCommand(command: string, policy: SandboxPolicy = {
 
 function buildArgv(command: string, policy: SandboxPolicy): string[] {
   const bwrap = policy.bwrapPath ?? 'bwrap'
-  const argv: string[] = [bwrap, '--unshare-all']
-
-  if (policy.network === 'inherit') {
-    // --unshare-all already unshared the net namespace; --share-net rejoins
-    // the outer container's network. Other namespaces (user/pid/mount/ipc/
-    // uts/cgroup) stay unshared. Default ('none' / undefined) leaves the net
-    // namespace isolated — prompt-injected bash cannot exfiltrate over the
-    // network without the consumer explicitly opting in.
+  const procStrategy = policy.proc ?? 'tmpfs'
+  const realProc = procStrategy === 'real-proc'
+
+  // 'real-proc' splits PID-namespace ownership from bwrap. `unshare --pid
+  // --fork --mount --mount-proc` (util-linux, baseline) creates the new PID +
+  // mount namespaces as REAL root and mounts a fresh procfs scoped to that PID
+  // namespace — which OrbStack permits only with CAP_SYS_ADMIN and NOT from
+  // bwrap's user namespace (bwrap's --proc is blocked there). bwrap then runs
+  // INSIDE that namespace and must NOT re-unshare pid (it would create a second
+  // PID ns with no matching procfs and reintroduce the ENOTDIR crash), so we
+  // unshare each namespace EXCEPT pid explicitly instead of --unshare-all. The
+  // freshly mounted /proc contains only the sandbox subtree, so --ro-bind /proc
+  // (below) binds that scoped procfs, never the agent runtime's /proc/N/environ.
+  const argv: string[] = realProc
+    ? ['unshare', '--pid', '--fork', '--mount', '--mount-proc', '--', bwrap]
+    : [bwrap, '--unshare-all']
+  if (realProc) {
+    argv.push('--unshare-user', '--unshare-ipc', '--unshare-uts', '--unshare-cgroup')
+  }
+
+  if (policy.network !== 'inherit') {
+    // Default ('none' / undefined) isolates the net namespace — prompt-injected
+    // bash cannot exfiltrate over the network unless the consumer opts in.
+    // --unshare-all already covers this in the non-real-proc path; under
+    // real-proc the explicit unshares above omit net, so add it here.
+    if (realProc) argv.push('--unshare-net')
+  } else if (!realProc) {
+    // --unshare-all unshared the net namespace; --share-net rejoins the outer
+    // container's network. Under real-proc we simply never add --unshare-net.
     argv.push('--share-net')
   }
 
@@ -97,7 +118,15 @@ function buildArgv(command: string, policy: SandboxPolicy): string[] {
     '/lib64',
   )
 
-  if ((policy.proc ?? 'tmpfs') === 'tmpfs') {
+  if (realProc) {
+    // The outer `unshare --mount-proc` already mounted a fresh procfs scoped to
+    // the new PID namespace. --ro-bind /proc /proc binds THAT procfs (not the
+    // outer container's), so the child gets real /proc/self/{fd,maps} and the
+    // agent runtime's pids — and their /proc/N/environ secrets — are simply
+    // absent from this namespace. No /proc/self/exe symlink is needed: a real
+    // /proc/self/exe already resolves correctly.
+    argv.push('--ro-bind', '/proc', '/proc')
+  } else if (procStrategy === 'tmpfs') {
     // --tmpfs /proc, never --proc /proc (OrbStack's kernel blocks
     // mount("proc",...) from user namespaces) and never --dev-bind /proc /proc
     // (leaks the outer container's /proc/N/environ — including
@@ -111,6 +140,9 @@ function buildArgv(command: string, policy: SandboxPolicy): string[] {
     // /proc/self/exe. --symlink (not --ro-bind /proc/self/exe): /proc/self at
     // setup time is bwrap's pid, so a bind would capture bwrap's own binary.
     // Must come AFTER --tmpfs /proc (last-op-wins) or the tmpfs erases it.
+    // This restores only the runner's SELF-location; a spawned child still
+    // reads /proc/self/fd + /proc/self/maps, which the empty tmpfs lacks, so
+    // external-package execution requires the 'real-proc' strategy above.
     if (policy.procSelfExe !== undefined) {
       argv.push('--ro-bind', policy.procSelfExe, policy.procSelfExe)
       argv.push('--symlink', policy.procSelfExe, '/proc/self/exe')

package/src/sandbox/policy.ts

@@ -6,7 +6,15 @@ export type SandboxMount =
 
 export type SandboxNetwork = 'none' | 'inherit'
 
-export type SandboxProcStrategy = 'tmpfs' | 'none'
+// 'tmpfs' (default): empty /proc + a single /proc/self/exe symlink. Works on
+// every host but gives no /proc/self/{fd,maps}, so a JS package runner's CHILD
+// (the spawned bin) crashes with ENOTDIR reading /proc/self/fd. 'none': no
+// /proc at all. 'real-proc': mount a fresh procfs scoped to a NEW pid namespace
+// so the child gets a real /proc/self/{fd,maps} WITHOUT seeing the agent
+// runtime's pids (no /proc/<agent>/environ leak). 'real-proc' requires the
+// outer container to hold CAP_SYS_ADMIN (mount(2) of proc); start.ts only grants
+// it when the operator opts in via typeclaw.json#sandbox.realProc.
+export type SandboxProcStrategy = 'tmpfs' | 'none' | 'real-proc'
 
 export type SandboxEnvPolicy = {
   set?: Record<string, string>

package/typeclaw.schema.json

@@ -190,6 +190,18 @@
         "minLength": 1
       }
     },
+    "compose": {
+      "default": {
+        "exclude": false
+      },
+      "type": "object",
+      "properties": {
+        "exclude": {
+          "default": false,
+          "type": "boolean"
+        }
+      }
+    },
     "channels": {
       "default": {},
       "type": "object",
@@ -1114,6 +1126,18 @@
         }
       }
     },
+    "sandbox": {
+      "default": {
+        "realProc": false
+      },
+      "type": "object",
+      "properties": {
+        "realProc": {
+          "default": false,
+          "type": "boolean"
+        }
+      }
+    },
     "docker": {
       "default": {
         "file": {