typeclaw 0.4.0 → 0.5.1

package/src/init/dockerfile.ts

@@ -27,6 +27,12 @@ export type BuildDockerfileOptions = {
 // `util-linux` carries `setpriv`, which the shim uses to drop CAP_NET_ADMIN
 // from the bounding set before exec'ing the agent. Listed first in the
 // apt-get install line so the package set is self-documenting at a glance.
+//
+// xvfb is intentionally NOT in baseline — it's a toggle (`xvfb: true` by
+// default, opt-out via `docker.file.xvfb: false`) because the shim
+// self-heals: it spawns Xvfb (and exports DISPLAY) if the binary is on
+// PATH, and execs the agent directly otherwise. See APT_FEATURES.xvfb
+// below and `buildEntrypointShim`.
 const BASELINE_APT_PACKAGES = ['git', 'ca-certificates', 'curl', 'gnupg', 'iptables', 'util-linux'] as const
 
 // curl-impersonate is the only currently-working way to query DuckDuckGo from
@@ -219,7 +225,96 @@ export function buildEntrypointShim(): string {
 # Source: src/init/dockerfile.ts \`buildEntrypointShim()\`.
 set -eu
 
+# start_xvfb launches Xvfb in the background under a stripped capability
+# bounding set so headed Chrome (agent-browser --headed, Playwright
+# headful) has a real X11 display to connect to. Headless containers
+# have no display server; Chrome --headless / --headless=new is
+# fingerprinted by modern bot detection (Akamai / Cloudflare BM)
+# regardless of UA spoof, so real headed Chrome under a virtual
+# framebuffer is the only path to a passing sensor score from a
+# server-side container.
+#
+# Two correctness invariants this function enforces:
+#
+# 1. Xvfb never holds CAP_NET_ADMIN. The shim runs as PID 1 with the
+#    container's full capability set (including NET_ADMIN when
+#    network.blockInternal=true). If we backgrounded Xvfb naked, it
+#    would inherit NET_ADMIN and keep it for the container's lifetime
+#    — defeating the capability-drop contract that setpriv applies to
+#    the agent process. Routing Xvfb through the same setpriv invocation
+#    we use for the agent strips NET_ADMIN before Xvfb's first exec.
+#    On the off-path (blockInternal=false) the bounding-set drop is a
+#    no-op (NET_ADMIN was never granted), but the call is harmless.
+#
+# 2. Xvfb startup failure is loud, not silent. \`Xvfb ... >/dev/null &\`
+#    under \`set -e\` does not fail the script if Xvfb exits immediately
+#    (missing library, port conflict, malformed args). Without the
+#    explicit liveness probe below, the shim would then export DISPLAY
+#    and exec bun, agent-browser launches would die with "cannot open
+#    display", and the operator would chase a phantom bug. We capture
+#    $! and \`kill -0\` it on every poll iteration so an early exit
+#    becomes a clear stderr line and a non-zero shim exit.
+#
+# We DO NOT use \`xvfb-run\`. xvfb-run hangs forever when it runs as
+# PID 1 inside a container: its SIGUSR1-based ready handshake races
+# and stalls because PID 1 ignores signals without explicit handlers,
+# so the \`trap : USR1 ; wait || :\` dance never wakes up. Observed in
+# practice: container alive, Xvfb running, PID 1 stuck in
+# \`rt_sigsuspend\`, no agent process ever spawns, \`docker logs\` empty.
+# Documented industry workarounds are tini-as-PID-1 or direct Xvfb
+# spawn; we pick the latter (no new dep).
+#
+# Xvfb args:
+#   :99                     fixed display number. Filesystem
+#                           (/tmp/.X11-unix/X99) and abstract
+#                           (\\0/tmp/.X11-unix/X99) sockets are both
+#                           network-namespace-scoped, so :99 is safe
+#                           across all Compose'd containers.
+#   -screen 0 1920x1080x24  desktop viewport agent-browser advertises;
+#                           mismatched geometry is itself a fingerprint
+#                           signal.
+#   -ac                     disable host-based X access control so
+#                           Chrome connects without XAUTHORITY plumbing.
+#   +extension RANDR        expose the RandR extension; Chrome queries
+#                           it for screen geometry, and without it
+#                           \`screen.*\` values come back inconsistent.
+#   -nolisten tcp           refuse TCP connections (Unix socket only).
+#                           Defense-in-depth — we are in a netns with
+#                           no inbound exposure anyway.
+start_xvfb() {
+  if ! command -v Xvfb >/dev/null 2>&1; then
+    return 0
+  fi
+  setpriv --bounding-set -net_admin --inh-caps -net_admin --ambient-caps -net_admin \\
+    -- Xvfb :99 -screen 0 1920x1080x24 -ac +extension RANDR -nolisten tcp \\
+    >/dev/null 2>&1 &
+  xvfb_pid=$!
+  export DISPLAY=:99
+  # Poll the socket every 10ms up to ~3s. Xvfb cold start is typically
+  # ~20-50ms on a modern host; 3s covers slow Docker Desktop VMs,
+  # Rosetta/QEMU emulation, and loaded CI runners. We also \`kill -0\`
+  # the pid each iteration so an Xvfb that died immediately surfaces
+  # as a clear error instead of a 3-second hang followed by silent
+  # "cannot open display" downstream.
+  i=0
+  while [ $i -lt 300 ]; do
+    if [ -S /tmp/.X11-unix/X99 ]; then
+      unset i xvfb_pid
+      return 0
+    fi
+    if ! kill -0 "$xvfb_pid" 2>/dev/null; then
+      echo "typeclaw-entrypoint: Xvfb exited immediately; cannot start headed display (docker.file.xvfb=true)" >&2
+      exit 1
+    fi
+    sleep 0.01
+    i=$((i + 1))
+  done
+  echo "typeclaw-entrypoint: Xvfb did not create /tmp/.X11-unix/X99 within 3s; refusing to continue (docker.file.xvfb=true)" >&2
+  exit 1
+}
+
 if [ "\${TYPECLAW_NETWORK_BLOCK_INTERNAL:-0}" != "1" ]; then
+  start_xvfb
   exec bun run typeclaw "$@"
 fi
 
@@ -264,6 +359,7 @@ ip6tables -A OUTPUT -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT
 ip6tables -A OUTPUT -o lo -j ACCEPT
 ${ipv6Rules.join('\n')}
 
+start_xvfb
 exec setpriv --bounding-set -net_admin --inh-caps -net_admin --ambient-caps -net_admin -- bun run typeclaw "$@"
 `
 }
@@ -337,7 +433,7 @@ type AptFeature = {
   toAptArgs: (toggle: DockerfileFeatureToggle) => string[]
 }
 
-const APT_FEATURES: Record<'ffmpeg' | 'gh' | 'tmux' | 'python' | 'cjkFonts', AptFeature> = {
+const APT_FEATURES: Record<'ffmpeg' | 'gh' | 'tmux' | 'python' | 'cjkFonts' | 'xvfb', AptFeature> = {
   ffmpeg: { toAptArgs: (v) => singlePackageArgs('ffmpeg', v) },
   gh: { toAptArgs: (v) => singlePackageArgs('gh', v) },
   tmux: { toAptArgs: (v) => singlePackageArgs('tmux', v) },
@@ -345,6 +441,7 @@ const APT_FEATURES: Record<'ffmpeg' | 'gh' | 'tmux' | 'python' | 'cjkFonts', Apt
     toAptArgs: (v) => (v === true ? ['python3', 'python3-pip', 'python3-venv', 'python-is-python3'] : []),
   },
   cjkFonts: { toAptArgs: (v) => (v === true ? [CJK_FONTS_PACKAGE] : []) },
+  xvfb: { toAptArgs: (v) => (v === true ? ['xvfb'] : []) },
 }
 
 export function buildDockerfile(
@@ -464,6 +561,8 @@ ${LAYER_3_AGENT_BROWSER_ARM64_CONFIG}
 
 ${LAYER_4_AGENT_BROWSER_INSTALL}
 
+${LAYER_4_5_AGENT_BROWSER_HEADED_WRAPPER}
+
 ${LAYER_5_CHROME_FOR_TESTING}
 
 ${cloudflaredLayer}${renderEntrypointShimLayer()}
@@ -541,6 +640,8 @@ ${LAYER_3_AGENT_BROWSER_ARM64_CONFIG}
 
 ${LAYER_4_AGENT_BROWSER_INSTALL}
 
+${LAYER_4_5_AGENT_BROWSER_HEADED_WRAPPER}
+
 ${LAYER_5_CHROME_FOR_TESTING}
 
 ${renderEntrypointShimLayer()}
@@ -602,6 +703,114 @@ const LAYER_4_AGENT_BROWSER_INSTALL = `# Layer 4 (volatile): install agent-brows
 RUN --mount=type=cache,target=/root/.bun/install/cache,sharing=locked \\
     bun install -g agent-browser`
 
+// Layer 4.5: shim the agent-browser binary with a wrapper that calls
+// \`agent-browser close\` before \`open\`/\`goto\`/\`navigate\` when headed
+// mode is requested. Works around vercel-labs/agent-browser issue #1083
+// ("headed silently ignored on existing session"): when a daemon is
+// already running with a headless browser, subsequent commands with
+// --headed / AGENT_BROWSER_HEADED reuse the existing headless browser
+// regardless of the requested mode. Three upstream fix PRs (#660, #370,
+// #387) have been open and unmerged for months as of 2026-05, so we
+// patch this locally rather than block on upstream.
+//
+// Allowlist, not denylist. The wrapper only pre-closes on the three
+// commands that explicitly start a new browsing session (\`open\`,
+// \`goto\`, \`navigate\`). Every other agent-browser subcommand — \`click\`,
+// \`snapshot\`, \`chat\`, \`connect\`, \`batch\`, \`tab\`, \`record\`, \`trace\`,
+// \`stream\`, \`cookies\`, \`network\`, ... — passes through untouched.
+// Rationale: those subcommands may operate on the live browser/page
+// state (cookies, in-progress recording, attached external CDP, etc.),
+// and a pre-close from us would silently destroy it. The user-reported
+// scenario for #1083 (\"\`agent-browser open <url> --headed\` after a
+// previous headless invocation\") is fully covered because the
+// follow-up commands inherit the now-headed browser the \`open\`
+// pre-close forced. An earlier draft used a deny-list approach that
+// pre-closed on every non-skip subcommand under headed env; oracle
+// self-review flagged the state-destruction risk for stateful commands,
+// and the allowlist fix is the resulting narrower contract.
+//
+// Truthy contract mirrors upstream's \`env_var_is_truthy\`
+// (cli/src/flags.rs:183): any non-empty value EXCEPT case-insensitive
+// "0" / "false" / "no" counts as truthy. So
+// \`AGENT_BROWSER_HEADED=yes\`, \`=y\`, \`=on\`, \`=anything-non-falsy\` all
+// trigger the workaround — matching what upstream's CLI parser would
+// see — instead of the original narrower 1|true match that left the
+// bug present for legitimate truthy values.
+//
+// Re-entrancy is defended at two layers. (1) The pre-close path is
+// \`open\`/\`goto\`/\`navigate\` only, and the close subcommand isn't in the
+// allowlist, so the pre-close never recurses through the wrapper into
+// another pre-close. (2) \`_TYPECLAW_AGENT_BROWSER_HEADED_HANDLED=1\` is
+// set on the env passed to both the pre-close and the final exec; if a
+// future subcommand we don't recognize shells out to \`agent-browser\` as
+// a subprocess while headed env is still set, the child sees the guard
+// and bypasses straight to .real without recursing.
+const LAYER_4_5_AGENT_BROWSER_HEADED_WRAPPER = `# Layer 4.5 (cheap): wrap agent-browser to work around upstream issue
+# #1083 (--headed / AGENT_BROWSER_HEADED ignored on existing session).
+# See src/init/dockerfile.ts for the full rationale.
+RUN mv /usr/local/bin/agent-browser /usr/local/bin/agent-browser.real \\
+ && cat > /usr/local/bin/agent-browser <<'TYPECLAW_AGENT_BROWSER_WRAPPER_EOF' \\
+ && chmod +x /usr/local/bin/agent-browser
+#!/bin/sh
+# typeclaw wrapper for agent-browser — see src/init/dockerfile.ts.
+set -e
+real="\${TYPECLAW_AGENT_BROWSER_REAL:-/usr/local/bin/agent-browser.real}"
+# Re-entrancy guard: if the wrapper invoked us, skip straight to the real
+# binary. Prevents infinite recursion if a subcommand shells out to
+# agent-browser while AGENT_BROWSER_HEADED is still set.
+if [ "\${_TYPECLAW_AGENT_BROWSER_HEADED_HANDLED:-}" = "1" ]; then
+  exec "$real" "$@"
+fi
+# Pre-close is only needed when the caller is requesting headed mode.
+# Match upstream's env_var_is_truthy contract (cli/src/flags.rs:183):
+# truthy = any non-empty value except case-insensitive "0", "false", "no".
+# Argv triggers: bare --headed, --headed=true, --headed=1. (A bare
+# --headed followed by a separate "false" argument is upstream-supported
+# to FORCE headless; the wrapper still pre-closes on the --headed match
+# and the real binary launches headless — wasted close, correct end
+# state. The narrower argv match keeps the wrapper from triggering on
+# unrelated --headed-prefixed flags that may exist in future upstream
+# versions.)
+headed=0
+val=\${AGENT_BROWSER_HEADED:-}
+lower=$(printf '%s' "$val" | tr '[:upper:]' '[:lower:]')
+case "$lower" in
+  ''|'0'|'false'|'no') ;;
+  *) headed=1 ;;
+esac
+for arg in "$@"; do
+  case "$arg" in
+    --headed|--headed=true|--headed=1) headed=1; break ;;
+  esac
+done
+if [ "$headed" != "1" ]; then
+  exec "$real" "$@"
+fi
+# Allowlist of commands where pre-close is safe and necessary. Only
+# user-visible "start a new browsing session" verbs go here. Everything
+# else (click, snapshot, chat, connect, batch, tab, record, trace,
+# stream, cookies, ...) may depend on live browser/page state and must
+# not be pre-closed by us.
+first=""
+for arg in "$@"; do
+  case "$arg" in
+    -*) continue ;;
+    *) first="$arg"; break ;;
+  esac
+done
+case "$first" in
+  open|goto|navigate) ;;
+  *) exec "$real" "$@" ;;
+esac
+# Best-effort pre-close. If the daemon is already gone, the real binary
+# prints "No active sessions" and exits 0 — safe to call unconditionally.
+# We discard its output so it never pollutes the caller's stdout/stderr,
+# and we tolerate failures (network blip, stale socket) by falling
+# through to the real command anyway.
+_TYPECLAW_AGENT_BROWSER_HEADED_HANDLED=1 "$real" close >/dev/null 2>&1 || true
+exec env _TYPECLAW_AGENT_BROWSER_HEADED_HANDLED=1 "$real" "$@"
+TYPECLAW_AGENT_BROWSER_WRAPPER_EOF`
+
 // Layer 5: download the pinned Chrome for Testing build into
 // ~/.agent-browser/browsers/. NO cache mount on that path because the
 // runtime needs the binary in the image. System shared libraries are
@@ -616,12 +825,21 @@ RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \\
     fi`
 
 function defaultConfig(): DockerfileConfig {
-  return { ffmpeg: false, gh: true, python: true, tmux: true, cjkFonts: true, cloudflared: true, append: [] }
+  return {
+    ffmpeg: false,
+    gh: true,
+    python: true,
+    tmux: true,
+    cjkFonts: true,
+    cloudflared: true,
+    xvfb: true,
+    append: [],
+  }
 }
 
 function collectToggleAptArgs(config: DockerfileConfig): string[] {
   const args: string[] = []
-  for (const key of ['ffmpeg', 'gh', 'python', 'tmux', 'cjkFonts'] as const) {
+  for (const key of ['ffmpeg', 'gh', 'python', 'tmux', 'cjkFonts', 'xvfb'] as const) {
     args.push(...APT_FEATURES[key].toAptArgs(config[key]))
   }
   return args

package/src/init/hatching.ts

@@ -45,9 +45,9 @@ Do these in order. Do **not** ask further questions.
 2. Write one short paragraph in \`MEMORY.md\` marking this moment: the date, how you came to be, what you and the user agreed on.
 3. Configure local git identity with \`bash\`: \`git config user.name "<your name>"\` and \`git config user.email "<reasonable placeholder>@typeclaw.local"\` (unless the user provided an email).
 4. Stage and commit **only the files you authored** with commit message \`Hatched 🐣\`. This is the hatching-specific commit message — it overrides the normal version-control style guidance for this one commit.
-5. Send **one final short message** — two sentences at most — telling the user hatching is complete and they can \`/quit\` the TUI. Do not ask further questions. Do not offer more work. The container keeps running once they quit; keeping the TUI open here wastes time.
+5. Send **one final short message** — two sentences at most — telling the user hatching is complete and they can leave the TUI with \`/quit\` (or Ctrl+C). Do not ask further questions. Do not offer more work. The container keeps running once they quit; keeping the TUI open here wastes time.
 
-After that final message, stop. If the user keeps talking, answer briefly and remind them they can \`/quit\` whenever they are ready.
+After that final message, stop. If the user keeps talking, answer briefly and remind them they can \`/quit\` (or Ctrl+C) whenever they are ready.
 
 This is the only time you will receive these instructions. After the \`Hatched 🐣\` commit, your identity takes over and you run as yourself.`
 

package/src/init/index.ts

@@ -37,6 +37,14 @@ const CONFIG_FILE = 'typeclaw.json'
 const CRON_FILE = 'cron.json'
 const PACKAGE_FILE = 'package.json'
 
+// Seeded into `typeclaw.json#roles.member.match[]` whenever a chat adapter
+// (slack-bot, discord-bot, telegram-bot, kakaotalk) is wired. The "*" rule
+// matches every channel session on every platform, so the built-in `member`
+// role (which already carries `channel.respond`) covers any inbound the
+// router sees. Without this, freshly-hatched agents silently drop every
+// chat message — see scaffold() and ensureDefaultChatMemberMatch() below.
+const DEFAULT_CHAT_MEMBER_MATCH_RULE = '*'
+
 const MARKDOWN_FILES = ['AGENTS.md', 'IDENTITY.md', 'SOUL.md', 'USER.md'] as const
 
 // `packages/` is a bun workspace root (see `workspaces` in buildPackageJson).
@@ -121,7 +129,18 @@ export type KakaotalkAuthRunner = (options: { cwd: string }) => Promise<Kakaotal
 // API-key provider". Optional model defaults to DEFAULT_MODEL_REF, which is
 // an OpenAI api-key provider — so test fixtures that omit both fields keep
 // working under the api-key path.
-export type LLMAuth = { kind: 'api-key'; apiKey: string } | { kind: 'oauth'; runLogin: OAuthLoginRunner }
+//
+// `oauth-completed` is the CLI wizard's signal that the browser login already
+// happened up-front (right after the user picked the auth method) and the
+// resulting credentials are already in `secrets.json`. `runInit` then skips
+// the `oauth-login` step but still treats this as an OAuth provider (no API
+// key written, etc.). The wizard runs OAuth eagerly so the browser opens the
+// moment the user picks "OAuth (browser login)" instead of waiting until the
+// end of the wizard — see `collectWizardInputs` in `src/cli/init.ts`.
+export type LLMAuth =
+  | { kind: 'api-key'; apiKey: string }
+  | { kind: 'oauth'; runLogin: OAuthLoginRunner }
+  | { kind: 'oauth-completed' }
 
 export type InitOptions = {
   cwd: string
@@ -223,8 +242,8 @@ export async function runInit({
   // Same trap as kakaotalk-auth: scaffold-then-fail-auth would leave
   // typeclaw.json without working credentials and the runtime would silently
   // refuse to boot. The login itself doesn't need the agent folder to exist
-  // — pi-ai's OAuth helper just needs a writable path for secrets.json, which
-  // we create on demand inside scaffold().
+  // — pi-ai's OAuth helper just needs a writable path for secrets.json, and
+  // the `mkdir` below creates it on demand before the login runs.
   if (resolvedAuth.kind === 'oauth') {
     emit({ step: 'oauth-login', phase: 'start' })
     await mkdir(cwd, { recursive: true })
@@ -532,6 +551,11 @@ export async function scaffold(root: string, options: ScaffoldOptions = {}): Pro
   if (options.withTelegram) channels['telegram-bot'] = {}
   if (options.withKakaotalk) channels.kakaotalk = {}
   if (Object.keys(channels).length > 0) config.channels = channels
+  // See DEFAULT_CHAT_MEMBER_MATCH_RULE for why this is here. GitHub is wired
+  // separately (writeGithubChannelForInit) and seeds per-repo member.match
+  // entries instead of the wildcard, so a github-only init stays scoped to
+  // the repos the operator opted in to.
+  if (Object.keys(channels).length > 0) config.roles = { member: { match: [DEFAULT_CHAT_MEMBER_MATCH_RULE] } }
   await writeFile(join(root, CONFIG_FILE), `${JSON.stringify(config, null, 2)}\n`)
 
   const cron = {
@@ -954,6 +978,8 @@ export async function runAddChannel(options: AddChannelOptions): Promise<void> {
   if (options.channel === 'github') {
     await appendGithubMatchRules(options.cwd, options.repos)
     await maybeInstallGithubWebhooks(options, emit)
+  } else {
+    await ensureDefaultChatMemberMatch(options.cwd)
   }
 
   // Commit the typeclaw.json change so the agent folder isn't silently
@@ -1198,6 +1224,24 @@ async function appendGithubMatchRules(cwd: string, repos: readonly string[]): Pr
   await writeFile(path, `${JSON.stringify(parsed, null, 2)}\n`)
 }
 
+// Chat-adapter counterpart of appendGithubMatchRules. See
+// DEFAULT_CHAT_MEMBER_MATCH_RULE for the rationale. Set-union semantics: re-
+// running `typeclaw channel add` for additional chat adapters is a no-op on
+// the match list, and any pre-existing rules the operator hand-authored
+// (e.g. owner-claim's per-author entry on `owner`) are left intact.
+async function ensureDefaultChatMemberMatch(cwd: string): Promise<void> {
+  const path = join(cwd, CONFIG_FILE)
+  const parsed = JSON.parse(await readFile(path, 'utf8')) as Record<string, unknown>
+  const roles = isObjectRecord(parsed.roles) ? { ...parsed.roles } : {}
+  const member = isObjectRecord(roles.member) ? { ...roles.member } : {}
+  const existing = Array.isArray(member.match) ? member.match.filter((v): v is string => typeof v === 'string') : []
+  if (existing.includes(DEFAULT_CHAT_MEMBER_MATCH_RULE)) return
+  member.match = [...existing, DEFAULT_CHAT_MEMBER_MATCH_RULE]
+  roles.member = member
+  parsed.roles = roles
+  await writeFile(path, `${JSON.stringify(parsed, null, 2)}\n`)
+}
+
 // Writes per-adapter field values into `secrets.json#channels.<adapter>`.
 // Refuses to overwrite existing fields: if the user already has e.g.
 // `botToken` recorded (from a prior `channel add` whose follow-up steps

package/src/init/oauth-login.ts

@@ -14,16 +14,29 @@ export type OAuthLoginResult = { ok: true } | { ok: false; reason: string }
 export type OAuthLoginRunner = (options: { cwd: string; model: KnownModelRef }) => Promise<OAuthLoginResult>
 
 // Wrap pi-ai's OAuth callbacks so the CLI doesn't have to know about the
-// upstream callback shape. The CLI only sees three lifecycle events:
+// upstream callback shape. The CLI sees four lifecycle events:
 // (1) onAuth(url) — print the URL the user must visit
 // (2) onProgress(message) — show waiting/finalizing status
 // (3) onPrompt(prompt) — ask the user for a manual code if the browser flow
-//     can't reach the local callback server. Most users won't see this; it
-//     fires when they paste the post-redirect URL by hand.
+//     can't reach the local callback server. Fires only after the local
+//     server gave up (bind error -> waitForCode resolves null).
+// (4) onManualCodeInput() — concurrent paste input that RACES the local
+//     callback server. Required for cross-device flows: pi-ai's openai-codex
+//     OAuth hardcodes redirect_uri=http://localhost:1455/auth/callback, which
+//     resolves to the *browser's* machine. When the user runs `typeclaw init`
+//     over SSH or on a remote dev box and completes login on a different
+//     laptop, the browser callback never reaches the CLI's local server and
+//     waitForCode() hangs forever — so onPrompt would never fire either.
+//     onManualCodeInput is the upstream-supported escape hatch: it shows a
+//     paste field IMMEDIATELY alongside the URL, and whichever path lands a
+//     code first wins. parseAuthorizationInput on the upstream side accepts
+//     the full redirect URL, the bare `code=...&state=...` query string, or
+//     just the code value.
 export type OAuthCallbacks = {
   onAuth: (url: string, instructions?: string) => void
   onProgress?: (message: string) => void
   onPrompt: (message: string, placeholder?: string) => Promise<string | null>
+  onManualCodeInput?: () => Promise<string>
 }
 
 // Default runner: real OAuth flow against pi-ai. Tests inject a stub to skip
@@ -50,6 +63,7 @@ export function makeOAuthLoginRunner(callbacks: OAuthCallbacks): OAuthLoginRunne
           }
           return value
         },
+        onManualCodeInput: callbacks.onManualCodeInput,
       })
       return { ok: true }
     } catch (error) {

package/src/permissions/builtins.ts

@@ -25,6 +25,21 @@ export type BuiltinRoleSpec = {
   readonly permissions: readonly string[]
 }
 
+// Owner carries low + medium tier strings explicitly AND the wildcard
+// sentinel. The sentinel expands to plugin-contributed `security.bypass.*`
+// strings minus the security plugin's `ownerWildcardExclusions` (today:
+// `security.bypass.high` plus high-tier per-guard strings). Net effect:
+// owner auto-bypasses every low- and medium-tier guard, and high-tier
+// guards require per-call ack from owner too (the audience-leak rule —
+// owner-in-public-channel must not silently post credentials).
+//
+// Trusted carries only `security.bypass.low`. Trusted does NOT carry the
+// pre-PR per-guard grants (`bypassSecretExfilBash`, `bypassGitExfil`):
+// those guards are medium/high under the audience-leak axis and per-guard
+// grants would re-introduce exactly the bypass holes the tier system
+// exists to prevent. Operators who want the pre-PR ergonomics can add the
+// per-guard strings explicitly to `roles.trusted.permissions[]` in
+// typeclaw.json — that path stays alive forever.
 export const BUILTIN_ROLES: Readonly<Record<BuiltinRoleName, BuiltinRoleSpec>> = {
   owner: {
     match: [{ kind: 'tui' }],
@@ -32,17 +47,14 @@ export const BUILTIN_ROLES: Readonly<Record<BuiltinRoleName, BuiltinRoleSpec>> =
       CORE_PERMISSIONS.channelRespond,
       CORE_PERMISSIONS.cronSchedule,
       CORE_PERMISSIONS.cronModify,
+      'security.bypass.low',
+      'security.bypass.medium',
       OWNER_SECURITY_WILDCARD,
     ],
   },
   trusted: {
     match: [],
-    permissions: [
-      CORE_PERMISSIONS.channelRespond,
-      CORE_PERMISSIONS.cronSchedule,
-      'security.bypass.secretExfilBash',
-      'security.bypass.gitExfil',
-    ],
+    permissions: [CORE_PERMISSIONS.channelRespond, CORE_PERMISSIONS.cronSchedule, 'security.bypass.low'],
   },
   member: {
     match: [],
@@ -54,11 +66,21 @@ export const BUILTIN_ROLES: Readonly<Record<BuiltinRoleName, BuiltinRoleSpec>> =
   },
 }
 
+// Expands the owner wildcard sentinel against plugin-contributed
+// `security.bypass.*` strings. `wildcardExclusions` is an optional set of
+// permission strings the sentinel must NOT expand to — used by the
+// bundled security plugin to exclude `security.bypass.high` AND the
+// per-guard strings for high-tier guards, so the wildcard does not
+// auto-grant audience-leak bypass to owner. Explicit operator grants of
+// those strings in `roles.owner.permissions[]` still take effect (they
+// flow through the non-sentinel branch).
 export function expandOwnerWildcard(
   ownerPermissions: readonly string[],
   pluginContributed: readonly string[],
+  wildcardExclusions: readonly string[] = [],
 ): readonly string[] {
-  const bypass = pluginContributed.filter((p) => p.startsWith('security.bypass.'))
+  const excludeSet = new Set(wildcardExclusions)
+  const bypass = pluginContributed.filter((p) => p.startsWith('security.bypass.') && !excludeSet.has(p))
   const out: string[] = []
   for (const p of ownerPermissions) {
     if (p === OWNER_SECURITY_WILDCARD) {

package/src/permissions/permissions.ts

@@ -38,6 +38,12 @@ type ResolvedRole = {
 export type CreatePermissionServiceOptions = {
   roles?: RolesConfig
   pluginPermissions?: readonly string[]
+  // Permission strings that the owner wildcard sentinel must NOT
+  // auto-expand to. Today populated from the bundled security plugin's
+  // high-tier list so audience-leak guards do not get auto-granted to
+  // owner. Generic by design — any future plugin could contribute
+  // exclusions through the plugin manager. See expandOwnerWildcard.
+  ownerWildcardExclusions?: readonly string[]
 }
 
 // Returns warnings for user-declared `permissions[]` strings that aren't
@@ -97,7 +103,8 @@ function levenshtein(a: string, b: string): number {
 
 export function createPermissionService(opts: CreatePermissionServiceOptions = {}): PermissionService {
   const pluginPermissions = opts.pluginPermissions ?? []
-  let resolved = buildRoleTable(opts.roles ?? {}, pluginPermissions)
+  const ownerWildcardExclusions = opts.ownerWildcardExclusions ?? []
+  let resolved = buildRoleTable(opts.roles ?? {}, pluginPermissions, ownerWildcardExclusions)
   let byName = new Map(resolved.map((r) => [r.name, r]))
 
   function resolveRole(origin: SessionOrigin | undefined): string {
@@ -139,36 +146,46 @@ export function createPermissionService(opts: CreatePermissionServiceOptions = {
       return { role: name, permissions: role?.permissions ?? [] }
     },
     replaceRoles(roles) {
-      resolved = buildRoleTable(roles ?? {}, pluginPermissions)
+      resolved = buildRoleTable(roles ?? {}, pluginPermissions, ownerWildcardExclusions)
       byName = new Map(resolved.map((r) => [r.name, r]))
     },
   }
 }
 
-function buildRoleTable(roles: RolesConfig, pluginPermissions: readonly string[]): ResolvedRole[] {
+function buildRoleTable(
+  roles: RolesConfig,
+  pluginPermissions: readonly string[],
+  ownerWildcardExclusions: readonly string[],
+): ResolvedRole[] {
   const out: ResolvedRole[] = []
   const seen = new Set<string>()
 
   for (const name of Object.keys(roles)) {
     if (seen.has(name)) continue
     seen.add(name)
-    out.push(resolveOne(name, roles[name], pluginPermissions))
+    out.push(resolveOne(name, roles[name], pluginPermissions, ownerWildcardExclusions))
   }
 
   for (const name of BUILTIN_ROLE_NAMES) {
     if (seen.has(name)) continue
-    out.push(resolveOne(name, undefined, pluginPermissions))
+    out.push(resolveOne(name, undefined, pluginPermissions, ownerWildcardExclusions))
   }
 
   return out
 }
 
-function resolveOne(name: string, user: RoleConfig | undefined, pluginPermissions: readonly string[]): ResolvedRole {
+function resolveOne(
+  name: string,
+  user: RoleConfig | undefined,
+  pluginPermissions: readonly string[],
+  ownerWildcardExclusions: readonly string[],
+): ResolvedRole {
   if (isBuiltinRoleName(name)) {
     const builtin = BUILTIN_ROLES[name]
     const match = [...builtin.match, ...(user?.match ?? [])]
     const rawPerms = user?.permissions !== undefined ? user.permissions : [...builtin.permissions]
-    const permissions = name === 'owner' ? expandOwnerWildcard(rawPerms, pluginPermissions) : rawPerms
+    const permissions =
+      name === 'owner' ? expandOwnerWildcard(rawPerms, pluginPermissions, ownerWildcardExclusions) : rawPerms
     return { name, match, permissions }
   }
   return {

package/src/plugin/define.ts

@@ -18,11 +18,13 @@ type DefinePluginSpec<S extends z.ZodType<unknown> | undefined> =
     ? {
         configSchema: S
         permissions?: readonly string[]
+        ownerWildcardExclusions?: readonly string[]
         commands?: Record<string, PluginCommand>
         plugin: (ctx: PluginContext<T>) => Promise<PluginExports>
       }
     : {
         permissions?: readonly string[]
+        ownerWildcardExclusions?: readonly string[]
         commands?: Record<string, PluginCommand>
         plugin: (ctx: PluginContext<unknown>) => Promise<PluginExports>
       }

package/src/plugin/manager.ts

@@ -56,9 +56,11 @@ export async function loadPlugins(opts: LoadPluginsOptions): Promise<LoadPlugins
   ]
 
   const declaredPermissions = collectDeclaredPermissions(allPlugins)
+  const ownerWildcardExclusions = collectOwnerWildcardExclusions(allPlugins)
   const permissions = createPermissionService({
     ...(opts.roles !== undefined ? { roles: opts.roles } : {}),
     pluginPermissions: declaredPermissions,
+    ownerWildcardExclusions,
   })
 
   // Non-fatal: surface user-declared `permissions[]` strings that aren't in
@@ -158,6 +160,18 @@ function collectDeclaredPermissions(
   return out
 }
 
+function collectOwnerWildcardExclusions(
+  plugins: readonly { entry: string; resolved: ResolvedPlugin }[],
+): readonly string[] {
+  const out: string[] = []
+  for (const { resolved } of plugins) {
+    for (const perm of resolved.defined.ownerWildcardExclusions ?? []) {
+      if (!out.includes(perm)) out.push(perm)
+    }
+  }
+  return out
+}
+
 export function summarizeLoaded(loaded: LoadPluginsResult['loadedPlugins'], registry: PluginRegistry): string {
   const head = loaded.map((p) => (p.version !== undefined ? `${p.name} v${p.version}` : p.name)).join(', ')
   const counts = [

package/src/plugin/types.ts

@@ -318,6 +318,12 @@ export type PluginFixResult = {
 export type DefinedPlugin<TConfig = never> = {
   readonly configSchema?: z.ZodType<TConfig>
   readonly permissions?: readonly string[]
+  // Permission strings the owner wildcard sentinel MUST NOT auto-expand
+  // to. Used by the bundled security plugin to keep audience-leak
+  // (high-tier) bypasses off the owner role unless an operator grants
+  // them explicitly in roles.owner.permissions[]. Generic by design so
+  // any future plugin can carve specific permissions out of the wildcard.
+  readonly ownerWildcardExclusions?: readonly string[]
   // Declared by-value (not built inside the factory) so the host-stage CLI
   // can dispatch commands without booting plugin runtime state.
   readonly commands?: Record<string, PluginCommand>

package/src/run/index.ts

@@ -314,7 +314,7 @@ export async function startAgent({
       }
       await job.handler(ctx)
     },
-    createSessionForCron: async (job) => {
+    createSessionForCron: async (job, refOverride) => {
       const snap = pluginRuntime.get()
       const sessionManager = SessionManager.create(cwd, sessionFactory.sessionDir())
       const sessionId = sessionManager.getSessionId()
@@ -336,6 +336,7 @@ export async function startAgent({
         channelRouter: channelManager.router,
         origin: cronOrigin,
         permissions: pluginsLoaded.permissions,
+        ...(refOverride !== undefined ? { refOverride } : {}),
         ...(snap.hasAnyPluginContent
           ? {
               plugins: {