typeclaw 0.15.1 → 0.16.0

package/src/bundled-plugins/security/policies/private-surface-read.ts

@@ -0,0 +1,215 @@
+import { realpathSync } from 'node:fs'
+import path from 'node:path'
+
+import type { HiddenPaths } from '@/sandbox'
+
+import type { SecurityBlock } from '../policy'
+
+export const GUARD_PRIVATE_SURFACE_READ = 'privateSurfaceRead'
+
+// bash is excluded: its access to hidden paths is contained by the bwrap
+// sandbox (applyBashSandbox), not by blocking the call. Every OTHER tool is
+// scanned, so a new file-reading tool — bundled or third-party — is covered
+// the day it ships without a whitelist edit. websearch/webfetch take URLs, not
+// local paths, and the path-plausibility filter keeps their args from matching.
+const UNSCANNED_TOOLS = new Set(['bash'])
+
+// The bash sandbox hides the role's private surface — the working DIRECTORIES
+// (workspace/, memory/, sessions/) and the secret FILES (.env, secrets.json) —
+// via bwrap masks, but every non-bash tool runs in the main process, outside
+// any sandbox. find_entry, look_at, and the channel attachment tools all read
+// files by a caller-supplied path, so without a guard a restricted role could
+// read back through them exactly what bash masking denies. This guard mirrors
+// the WHOLE deny-list (dirs + files) onto all of them, honouring the PR's
+// "two enforcement points, one deny-list" invariant.
+//
+// It covers the full deny-list rather than delegating secret files to the
+// secretExfilRead guard: that guard only inspects read/grep/find/ls (not
+// edit/write/look_at/channel_send) and is acknowledgement-bypassable, so
+// delegating would leave .env/secrets.json reachable through the uncovered
+// tools — exactly the gap the bash masks close. secretExfilRead remains as
+// independent defense in depth for the four tools it does cover.
+//
+// Posture is FAIL-CLOSED for restricted roles: it does not whitelist a known
+// set of tools (that fails open the moment a new reader is added). It scans
+// every arg of every non-bash tool — recursively, since paths hide in nested
+// shapes like look_at's images[].path and channel_send's attachments[].path —
+// and blocks any string that resolves to (a secret file) or under (a hidden
+// directory) the deny-list.
+export function checkPrivateSurfaceReadGuard(options: {
+  tool: string
+  args: Record<string, unknown>
+  agentDir: string
+  hidden: HiddenPaths
+}): SecurityBlock | undefined {
+  const { tool, args, agentDir, hidden } = options
+  if (UNSCANNED_TOOLS.has(tool)) return undefined
+  const deniedDirs = hidden.dirs
+  const deniedFiles = hidden.files
+  if (deniedDirs.length === 0 && deniedFiles.length === 0) return undefined
+
+  for (const candidate of collectPathCandidates(args, tool)) {
+    const hit = matchHidden(candidate, agentDir, deniedDirs, deniedFiles)
+    if (hit !== undefined) {
+      return {
+        block: true,
+        reason: [
+          `Guard \`${GUARD_PRIVATE_SURFACE_READ}\` blocked ${tool}: argument \`${candidate}\` resolves to ${hit}, which is hidden from the current role.`,
+          'The bash sandbox masks the same path; reaching it through another tool is the same disclosure.',
+        ].join(' '),
+      }
+    }
+  }
+  return undefined
+}
+
+// Field names whose values are ALWAYS free text (prose/queries/ids), NEVER a
+// filesystem path, for EVERY tool. Scanning them caused false positives: a
+// guest's `channel_reply({ text: "the memory leak" })` or `websearch({ query:
+// "workspace setup" })` resolve to a bare hidden-dir name and were wrongly
+// blocked. This is a DENYLIST OF KEY NAMES, not a tool whitelist: an unknown
+// field on an unknown tool is still scanned (fail-closed for new path-bearing
+// readers); we only skip values whose KEY is universally free text. `command`
+// is here because bash (its only user) is already exempt via UNSCANNED_TOOLS.
+//
+// `glob` and `pattern` are deliberately ABSENT — they are tool-dependent (a
+// glob/path-filter in grep/find, a regex only in grep) and handled by
+// FREE_TEXT_KEYS_BY_TOOL below.
+const NON_PATH_KEYS = new Set([
+  'text',
+  'query',
+  'prompt',
+  'selector',
+  'url',
+  'message',
+  'body',
+  'content',
+  'command',
+  'reason',
+  'subject',
+  'description',
+  'title',
+  'name',
+  // edit tool: replacement text is free-form and may quote a hidden path.
+  'oldText',
+  'newText',
+  // memory append tool: fragment topic is free text.
+  'topic',
+  // channel_send/channel_reply attachments[].filename and
+  // channel_fetch_attachment.filename: display-only metadata (defaults to the
+  // basename of the real `path`), never the file location the guard cares
+  // about — `attachments[].path` carries that and is NOT exempted.
+  'filename',
+])
+
+// Keys that are free text in SPECIFIC tools but path-bearing in others, so a
+// global denylist would either over-block or open a bypass. Scoped per tool:
+//   - grep.pattern  : a regex/search string (e.g. "sessions"), NOT a path.
+// Notably NOT listed (and therefore SCANNED):
+//   - grep.glob / find.pattern : both are glob path-filters resolved RELATIVE
+//     to the search root, so `grep({ path: '.', glob: 'workspace/**' })` and
+//     `find({ path: '.', pattern: 'workspace/**' })` reach a hidden subtree.
+//     Exempting them let the only hidden-identifying arg through (the bypass a
+//     review caught). They have no false-positive risk: path.resolve treats
+//     glob metacharacters as literal, so `*.ts` -> `/agent/*.ts` (passes) while
+//     `workspace/**` -> `/agent/workspace/**` (correctly blocked).
+// Fail-closed: only the listed tool's listed key is exempted; an unknown tool
+// (or grep gaining a new key) scans everything.
+const FREE_TEXT_KEYS_BY_TOOL: Record<string, ReadonlySet<string>> = {
+  grep: new Set(['pattern']),
+}
+
+// Recursively collects strings that could be paths, skipping values under a
+// universally-free-text key or a tool-scoped free-text key. matchHidden then
+// realpath-resolves each candidate and fires only on one landing inside a
+// hidden directory. Fail-closed by design: a bare path-bearing value equal to a
+// hidden dir name (e.g. `path: "memory"`) is still blocked. `underExempt`
+// propagates so nested values under an exempt key (e.g. a structured pattern)
+// stay exempt; top-level strings and array elements carry no key and are always
+// scanned (so attachments[].path is collected).
+function collectPathCandidates(value: unknown, tool: string): string[] {
+  const out: string[] = []
+  walk(value, out, tool, false)
+  return out
+}
+
+function walk(value: unknown, out: string[], tool: string, underExempt: boolean): void {
+  if (typeof value === 'string') {
+    if (underExempt) return
+    out.push(value)
+    return
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) walk(item, out, tool, underExempt)
+    return
+  }
+  if (value !== null && typeof value === 'object') {
+    const toolFreeText = FREE_TEXT_KEYS_BY_TOOL[tool]
+    for (const [key, item] of Object.entries(value)) {
+      const keyIsExempt = NON_PATH_KEYS.has(key) || (toolFreeText?.has(key) ?? false)
+      walk(item, out, tool, underExempt || keyIsExempt)
+    }
+  }
+}
+
+// Resolving both sides against agentDir defeats traversal (workspace/../workspace/x),
+// relative forms (./workspace), and absolute restatements. Secret files match on
+// exact equality; hidden directories match the dir itself or anything under it,
+// using a trailing slash so `workspace` does not also match a sibling
+// `workspace-notes`.
+//
+// Symlink defense: lexical path.resolve is NOT enough. A restricted role can
+// plant `public/leak -> ../.env` (or `-> ../memory`) via sandboxed bash, then
+// read it back through a non-bash tool whose path lexically lands in the
+// guest-visible `public/`. So we resolve the candidate's REAL path
+// (realpathRealIntendedPath follows symlinks on every existing path component)
+// before matching. Both sides are realpath'd because agentDir itself may sit
+// under a symlink (e.g. /tmp -> /private/tmp on macOS); comparing a real
+// candidate against a lexical deny-list would never match.
+function matchHidden(
+  candidate: string,
+  agentDir: string,
+  deniedDirs: string[],
+  deniedFiles: string[],
+): string | undefined {
+  const resolved = realpathRealIntendedPath(path.resolve(agentDir, candidate))
+  for (const file of deniedFiles) {
+    if (resolved === realpathRealIntendedPath(file)) return file
+  }
+  for (const dir of deniedDirs) {
+    const realDir = realpathRealIntendedPath(dir)
+    if (resolved === realDir || resolved.startsWith(`${realDir}/`)) return dir
+  }
+  return undefined
+}
+
+// Resolves symlinks on the longest existing prefix of an absolute path, then
+// re-appends the non-existent tail. A bare realpathSync throws on a path that
+// does not exist yet (a write target, or a read of a not-yet-created file), so
+// we walk up to the nearest existing ancestor, realpath THAT (collapsing any
+// symlinked component including a planted symlink), and rejoin the remainder.
+// This catches `public/leak/x` where `public/leak` is a symlink into a hidden
+// dir even though `public/leak/x` itself does not exist. Sync (realpathSync)
+// keeps the guard synchronous so the security tool.before check array stays
+// non-async; the cost is one syscall per existing component, negligible at the
+// tool-call boundary. Sync mirror of resolveRealIntendedPath in the guard
+// plugin's non-workspace-write policy.
+function realpathRealIntendedPath(absolutePath: string): string {
+  const pending: string[] = []
+  let current = absolutePath
+  while (true) {
+    try {
+      return path.join(realpathSync.native(current), ...pending.reverse())
+    } catch (err) {
+      if (!isNotFoundError(err)) throw err
+    }
+    const parent = path.dirname(current)
+    if (parent === current) return absolutePath
+    pending.push(path.basename(current))
+    current = parent
+  }
+}
+
+function isNotFoundError(err: unknown): boolean {
+  return err instanceof Error && 'code' in err && err.code === 'ENOENT'
+}

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

@@ -13,6 +13,9 @@ export type GithubWebhookHandlerOptions = {
   allowlist: () => readonly string[]
   selfId: () => string | null
   selfLogin: () => string | null
+  // Defaults to 'pat' when omitted. Only 'app' promotes an opened PR to a
+  // review request; see classifyOpenedAsReview for why.
+  authType?: () => 'pat' | 'app'
   route: (message: InboundMessage) => void
   logger: GithubInboundLogger
   // Optional: resolves whether the bot is a member of the given team. When
@@ -56,6 +59,7 @@ export function createGithubWebhookHandler(options: GithubWebhookHandlerOptions)
     const teamIsBotMember = await resolveTeamMembership(event, payload, options)
     const classified = classifyGithubInbound(event, payload, selfLogin, {
       teamIsBotMember,
+      authType: options.authType?.() ?? 'pat',
     })
     if (classified === null) return ok()
 
@@ -77,7 +81,7 @@ export function classifyGithubInbound(
   event: string,
   payload: Record<string, unknown>,
   selfLogin: string | null,
-  options?: { teamIsBotMember?: boolean },
+  options?: { teamIsBotMember?: boolean; authType?: 'pat' | 'app' },
 ): InboundMessage | null {
   const repository = readRepository(payload)
   if (repository === null) return null
@@ -177,6 +181,14 @@ export function classifyGithubInbound(
         teamIsBotMember: options?.teamIsBotMember,
       })
     }
+    // A GitHub App cannot be added to a PR's requested_reviewers, so it never
+    // receives a review_requested event targeting itself. The opened event is
+    // the only signal it can act on, so in App mode an opened PR is promoted to
+    // a review request. A PAT-backed bot is a real user that can be requested,
+    // so it waits for the explicit request instead of reviewing every PR.
+    if (action === 'opened' && options?.authType === 'app') {
+      return classifyOpenedAsReview({ payload, pr, number, base, selfLogin })
+    }
     return buildInbound(
       { ...base, chat: `pr:${number}`, thread: null },
       pr.body,
@@ -291,6 +303,47 @@ function classifyReviewRequest(input: ReviewRequestInput): InboundMessage | null
   }
 }
 
+type OpenedAsReviewInput = {
+  payload: Record<string, unknown>
+  pr: Record<string, unknown>
+  number: number
+  base: Pick<InboundMessage, 'adapter' | 'workspace' | 'isDm' | 'mentionsOthers' | 'replyToOtherMessageId'>
+  selfLogin: string | null
+}
+
+function classifyOpenedAsReview(input: OpenedAsReviewInput): InboundMessage | null {
+  const { payload, pr, number, base, selfLogin } = input
+  if (selfLogin === null) return null
+  const sender = readUser(payload.sender)
+  if (sender === null) return null
+  if (sender.login === selfLogin) return null
+
+  const title = readString(pr, 'title') ?? `#${number}`
+  const head = readString(readRecord(pr.head), 'ref')
+  const baseRef = readString(readRecord(pr.base), 'ref')
+  const branchSegment = head !== null && baseRef !== null ? ` Branch: ${head} → ${baseRef}.` : ''
+  const text =
+    `@${sender.login} requested your review on PR #${number}: "${title}".${branchSegment}` +
+    ' Please review the changes line-by-line and post your feedback.'
+
+  const updatedAt = readString(pr, 'updated_at') ?? ''
+  const prId = readNumber(pr, 'id') ?? number
+
+  return {
+    ...base,
+    chat: `pr:${number}`,
+    thread: null,
+    text,
+    externalMessageId: `pr-${prId}-opened-${updatedAt}`,
+    authorId: String(sender.id),
+    authorName: sender.login,
+    authorIsBot: sender.type === 'Bot',
+    isBotMention: true,
+    replyToBotMessageId: null,
+    ts: updatedAt !== '' ? Date.parse(updatedAt) || 0 : 0,
+  }
+}
+
 export type GithubReviewerTeam = { slug: string; id: number; org: string | null }
 
 export function readReviewerTeam(value: unknown): GithubReviewerTeam | null {

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

@@ -128,6 +128,7 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
     allowlist: () => options.configRef().eventAllowlist,
     selfId: () => selfId,
     selfLogin: () => selfLogin,
+    authType: () => options.secrets.auth.type,
     isBotInTeam,
     logger,
     route: (message) => {

package/src/channels/router.ts

@@ -3,7 +3,7 @@ import { basename } from 'node:path'
 import type { AssistantMessage } from '@mariozechner/pi-ai'
 import { SessionManager } from '@mariozechner/pi-coding-agent'
 
-import { createSession, renderTurnTimeAnchor, type AgentSession } from '@/agent'
+import { createSession, renderTurnRoleAnchor, renderTurnTimeAnchor, type AgentSession } from '@/agent'
 import { subscribeProviderErrors } from '@/agent/provider-error'
 import type { ChannelParticipant, SessionOrigin } from '@/agent/session-origin'
 import { renderSubagentCompletionReminder } from '@/agent/subagent-completion-reminder'
@@ -1248,16 +1248,22 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
   // tools and `channel_send` must keep the follow-up so genuine multi-step turns
   // continue. A prior non-typeclaw `afterToolCall` (none today) would be
   // composed, not clobbered.
+  //
+  // `channel_reply({ continue: true })` is the explicit opt-out: a mid-turn
+  // status reply ("working on it…") that the model follows with more work this
+  // turn. The tool surfaces that intent as `details.continue === true`, and we
+  // keep the follow-up so the turn proceeds. The kimi 32k loop only recurs when
+  // the model genuinely has nothing left to say after a reply, which `continue`
+  // asserts is not the case; Layer 2's maxTokens cap still bounds any misuse.
   const installChannelReplyTerminalHook = (live: LiveSession): void => {
     const { agent } = live.session
     const prior = agent.afterToolCall
     agent.afterToolCall = async (context, signal) => {
       const result = prior ? await prior(context, signal) : undefined
-      const succeeded =
-        context.toolCall.name === 'channel_reply' &&
-        !context.isError &&
-        (context.result.details as { ok?: unknown } | undefined)?.ok === true
-      if (succeeded && agent.signal?.aborted !== true) {
+      const details = context.result.details as { ok?: unknown; continue?: unknown } | undefined
+      const succeeded = context.toolCall.name === 'channel_reply' && !context.isError && details?.ok === true
+      const keepTurnAlive = details?.continue === true
+      if (succeeded && !keepTurnAlive && agent.signal?.aborted !== true) {
         logger.info(`[channels] ${live.keyId} terminal_after_channel_reply`)
         agent.abort()
       }
@@ -1421,11 +1427,6 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         const batch = live.promptQueue.splice(0, live.promptQueue.length)
         const observed = live.contextBuffer.splice(0, live.contextBuffer.length)
         const reminders = live.pendingSystemReminders.splice(0, live.pendingSystemReminders.length)
-        const text = composeTurnPrompt(observed, batch, {
-          adapter: live.key.adapter,
-          loopGuardActive: live.loopGuardActive,
-          systemReminders: reminders,
-        })
 
         if (batch.length > 0) {
           live.currentTurnAuthorId = batch[batch.length - 1]!.authorId
@@ -1451,12 +1452,21 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         }
 
         // Update the live origin holder so this turn's tool.before events
-        // carry the current actor's id. The DefaultResourceLoader still
-        // renders the session-creation origin into the system prompt (v0.2
-        // work to regenerate that per-turn); but permission gating off
-        // `lastInboundAuthorId` happens in the tool layer and now sees the
+        // carry the current actor's id, and resolve the live role from it for
+        // the per-turn <your-role> anchor below. Done BEFORE composeTurnPrompt
+        // so the anchor reflects the speaker of THIS turn, not the session-
+        // creation snapshot the system prompt still renders. Permission gating
+        // off `lastInboundAuthorId` happens in the tool layer and sees the same
         // live value.
         live.originRef.current = buildLiveOrigin(live)
+        const liveRole = permissions.describe(live.originRef.current).role
+
+        const text = composeTurnPrompt(observed, batch, {
+          adapter: live.key.adapter,
+          loopGuardActive: live.loopGuardActive,
+          systemReminders: reminders,
+          role: liveRole,
+        })
 
         // Bracketing logs around the LLM call so a hung prompt() is
         // diagnosable from logs alone (we see prompting without prompted).
@@ -2193,9 +2203,14 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
       return
     }
 
-    // `source` distinguishes the two recovery shapes for log triage:
-    //   - 'leaf': the assistant message IS the leaf (existing behavior; model
-    //     ended its turn with text but forgot to call channel_reply).
+    // `source` distinguishes the three recovery shapes for log triage:
+    //   - 'leaf': the assistant message IS the leaf with stopReason 'stop'
+    //     (existing behavior; model ended its turn with text but forgot to
+    //     call channel_reply).
+    //   - 'mid-turn': the assistant message IS the leaf with stopReason
+    //     'toolUse'; the model narrated a reply, committed to a tool plan, and
+    //     the turn ended before a follow-up that would have called a channel
+    //     tool was persisted. The narration is the only user-facing text.
     //   - 'pre-tool': the leaf is a toolResult (or other non-assistant entry)
     //     and the assistant message lives upstream in the branch. This is the
     //     Kimi-on-Fireworks `kimi-k2p6-turbo` failure mode where the post-tool
@@ -2528,13 +2543,21 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
 function composeTurnPrompt(
   observed: readonly ObservedInbound[],
   batch: readonly QueuedInbound[],
-  state: { adapter?: AdapterId; loopGuardActive: boolean; systemReminders?: readonly string[]; now?: Date } = {
+  state: {
+    adapter?: AdapterId
+    loopGuardActive: boolean
+    systemReminders?: readonly string[]
+    now?: Date
+    role?: string
+  } = {
     loopGuardActive: false,
   },
 ): string {
   const adapter = state.adapter ?? 'discord-bot'
   const parts: string[] = []
   parts.push(renderTurnTimeAnchor(state.now), '')
+  const roleAnchor = state.role !== undefined ? renderTurnRoleAnchor(state.role) : undefined
+  if (roleAnchor !== undefined) parts.push(roleAnchor, '')
   // System reminders (subagent-completion wakeups today) lead the turn body
   // because they are typically what triggered the drain — when the prompt
   // queue is empty and the only thing in this iteration is a reminder, the
@@ -2995,7 +3018,7 @@ async function raceWithTimeout<T>(work: Promise<T>, ms: number, label: string):
 // assistant message — i.e., text the user should see but didn't, because the
 // model failed to call `channel_reply`/`channel_send` before its turn ended.
 //
-// Two recovery shapes:
+// Three recovery shapes:
 //
 //   - source: 'leaf'
 //     The leaf entry IS an assistant message with `stopReason === 'stop'`.
@@ -3003,6 +3026,20 @@ async function raceWithTimeout<T>(work: Promise<T>, ms: number, label: string):
 //     tool. Pre-existing behavior; this is what the historical
 //     `latestAssistantText` covered.
 //
+//   - source: 'mid-turn'
+//     The leaf IS an assistant message with `stopReason === 'toolUse'` that
+//     carries visible text. The model narrated a user-facing reply ("on it,
+//     bumping to 16x now") AND committed to a tool plan in the same message,
+//     but the turn ended before any follow-up assistant message that would
+//     have called `channel_reply` was persisted — the upstream pi-agent-core
+//     loop's post-tool follow-up never landed, or the run was aborted
+//     mid-loop. The model treated its visible prose as ambient narration; in
+//     a channel session that prose is dead text. Recovers it so the user gets
+//     the reply the model thought it had already given. Observed against
+//     Fireworks' `kimi-k2p6-turbo` on KakaoTalk: the agent posted speed-change
+//     status as narration, kept taking screenshots, and the user saw nothing.
+//     This is the leaf-is-assistant twin of the 'pre-tool' shape below.
+//
 //   - source: 'pre-tool'
 //     The leaf is a `toolResult` and the immediately-prior assistant message
 //     has `stopReason === 'toolUse'` (it called the tool that produced this
@@ -3014,22 +3051,34 @@ async function raceWithTimeout<T>(work: Promise<T>, ms: number, label: string):
 //
 // Returns null when no recovery is appropriate:
 //   - No leaf, no messages in branch, branch is malformed
-//   - Leaf is an assistant with non-'stop' stopReason (e.g. mid-stream error)
+//   - Leaf is an assistant with `stopReason` of 'length' / 'error' / 'aborted'
 //     and is NOT preceded by a toolResult pattern — we don't recover partial
 //     errored output because it's typically a truncation, not a deliberate
-//     reply
+//     reply. Only 'stop' (turn-complete) and 'toolUse' (committed to a tool
+//     plan, prose stranded) signal text the model meant for the user.
 //   - Leaf is a user/system message (model hasn't responded yet)
 //
 // `visibleAssistantText` returning '' (empty string) is a valid recovery
 // target — the caller's downstream guards (`endsWithNoReplySignal('')` returns
 // true) handle the no-content case explicitly via the `no_reply` log.
-function recoverableAssistantText(session: AgentSession): { text: string; source: 'leaf' | 'pre-tool' } | null {
+function recoverableAssistantText(
+  session: AgentSession,
+): { text: string; source: 'leaf' | 'mid-turn' | 'pre-tool' } | null {
   const leaf = session.sessionManager.getLeafEntry()
   if (!leaf) return null
 
   if (leaf.type === 'message' && leaf.message.role === 'assistant') {
-    if (leaf.message.stopReason !== 'stop') return null
-    return { text: visibleAssistantText(leaf.message), source: 'leaf' }
+    if (leaf.message.stopReason === 'stop') {
+      return { text: visibleAssistantText(leaf.message), source: 'leaf' }
+    }
+    // The model committed to a tool plan but its visible prose never reached
+    // the channel and no follow-up message that would have called a channel
+    // tool was persisted. Recover the stranded prose. Other non-'stop' stop
+    // reasons (length/error/aborted) are truncations, not deliberate replies.
+    if (leaf.message.stopReason === 'toolUse') {
+      return { text: visibleAssistantText(leaf.message), source: 'mid-turn' }
+    }
+    return null
   }
 
   // Pre-tool recovery: the leaf must be a toolResult message, and walking

package/src/cli/inspect.ts

@@ -45,8 +45,12 @@ export const inspectCommand = defineCommand({
 
     const isJson = args.json === true
     const liveSource = isJson ? undefined : await buildLiveSource(cwd)
-    const signal = installSigintAbort()
-    const escListener = isJson ? null : createEscListener()
+    const signalCtrl = installSigintAbort()
+    const signal = signalCtrl.signal
+    // Raw-mode Ctrl-C arrives as byte 0x03 and must abort the exit controller
+    // directly: under Bun a self-issued process.kill(SIGINT) does not reliably
+    // re-enter our process.once('SIGINT') handler, so the live tail never exits.
+    const escListener = isJson ? null : createEscListener(() => signalCtrl.abort())
     const liveHint = escListener === null ? undefined : escHintLine(color)
 
     // try/finally so a thrown loop never leaves the terminal stuck in raw mode.
@@ -108,14 +112,14 @@ async function buildLiveSource(cwd: string): Promise<LiveSourceFactory | undefin
     })
 }
 
-function installSigintAbort(): AbortSignal {
+function installSigintAbort(): AbortController {
   const ctrl = new AbortController()
   const onSig = (): void => {
     ctrl.abort()
   }
   process.once('SIGINT', onSig)
   process.once('SIGTERM', onSig)
-  return ctrl.signal
+  return ctrl
 }
 
 type EscListener = {
@@ -125,8 +129,10 @@ type EscListener = {
   stop: () => void
 }
 
-function createEscListener(): EscListener | null {
-  const stdin = process.stdin
+type RawInput = Pick<NodeJS.ReadStream, 'isTTY' | 'setRawMode' | 'resume' | 'pause' | 'on' | 'off'>
+
+export function createEscListener(onSigint: () => void, input: RawInput = process.stdin): EscListener | null {
+  const stdin = input
   if (!stdin.isTTY || typeof stdin.setRawMode !== 'function') return null
 
   const ctrl = createEscController({ debounceMs: ESC_LISTEN_DELAY_MS })
@@ -134,15 +140,17 @@ function createEscListener(): EscListener | null {
 
   const onData = (chunk: Buffer): void => {
     const { sigint } = ctrl.onChunk(chunk)
-    if (sigint) process.kill(process.pid, 'SIGINT')
+    if (sigint) onSigint()
   }
 
   const start = (): void => {
     if (active) return
     active = true
     stdin.setRawMode(true)
-    stdin.resume()
+    // Attach the data handler before resume() so no raw-mode keystroke can slip
+    // through between resuming the stream and registering the listener.
     stdin.on('data', onData)
+    stdin.resume()
   }
   const stop = (): void => {
     if (!active) return
@@ -153,7 +161,10 @@ function createEscListener(): EscListener | null {
     } catch {
       /* terminal already torn down */
     }
-    stdin.pause()
+    // Do NOT pause stdin here: this teardown hands control to the clack picker,
+    // and under Bun clack does not reliably re-flow a previously paused
+    // process.stdin, so its keypresses never arrive and arrow keys echo as raw
+    // bytes. Leaving the stream flowing lets clack own raw mode during the picker.
     ctrl.clearPending()
   }
 

package/src/init/index.ts

@@ -23,7 +23,7 @@ import { installGithubWebhooksEagerly, type EagerGithubWebhookInstallResult } fr
 import { buildGitignore, GITIGNORE_FILE } from './gitignore'
 import { buildHatchingPrompt } from './hatching'
 import type { OAuthLoginRunner, OAuthLoginResult } from './oauth-login'
-import { GITKEEP_FILE, PACKAGES_DIR } from './paths'
+import { GITKEEP_FILE, PACKAGES_DIR, PUBLIC_DIR } from './paths'
 import { type InstallResult, type InstallRunner, runBunInstall } from './run-bun-install'
 
 export { type InstallResult, type InstallRunner, runBunInstall } from './run-bun-install'
@@ -31,7 +31,7 @@ export { type InstallResult, type InstallRunner, runBunInstall } from './run-bun
 export type { EagerGithubWebhookInstallResult } from './github-webhook-install'
 export { formatEagerGithubWebhookInstallResult, installGithubWebhooksEagerly } from './github-webhook-install'
 
-export { GITKEEP_FILE, PACKAGES_DIR } from './paths'
+export { GITKEEP_FILE, PACKAGES_DIR, PUBLIC_DIR } from './paths'
 
 export { appendOrReplaceEnvKey, hasEnvKey, readEnvFile } from './env-file'
 
@@ -55,7 +55,15 @@ const MARKDOWN_FILES = ['AGENTS.md', 'IDENTITY.md', 'SOUL.md', 'USER.md'] as con
 // stay in `workspace/`. The directory is scaffolded empty so the layout is
 // discoverable on day one; a `.gitkeep` is written below so it survives the
 // initial commit.
-const DIRECTORIES = ['workspace', 'sessions', '.agents/skills', 'mounts', 'packages'] as const
+//
+// `public/` is a top-level sibling, NOT `workspace/public/`, on purpose:
+// role-based path hiding (src/sandbox/hidden-paths.ts) masks `workspace/` from
+// the guest tier but never masks `public/`, so `public/` is the one place a
+// guest turn can read and write. `workspace/` is an arbitrary free-write zone
+// with no reserved subdir names; a magic `workspace/public/` would silently
+// expose any subdir an agent happened to name `public`. A root sibling keeps
+// the deny-list flat (no carve-out) and the public/private split legible.
+const DIRECTORIES = ['workspace', 'public', 'sessions', '.agents/skills', 'mounts', 'packages'] as const
 
 export type GitInitResult = { ok: true; skipped: boolean } | { ok: false; reason: string }
 export type DockerAssetsResult = { ok: true; devMode: boolean } | { ok: false; reason: string }
@@ -552,12 +560,14 @@ export type ScaffoldOptions = {
 export async function scaffold(root: string, options: ScaffoldOptions = {}): Promise<void> {
   await Promise.all(DIRECTORIES.map((dir) => mkdir(join(root, dir), { recursive: true })))
 
-  // git does not track empty directories, so without this file the `packages/`
-  // workspace root would silently disappear from the initial commit and confuse
-  // the agent (its workspaces glob would resolve to nothing). The other
-  // DIRECTORIES are either gitignored (workspace, sessions, mounts) or
-  // immediately populated, so packages/ is the only one that needs this.
-  await writeFile(join(root, PACKAGES_DIR, GITKEEP_FILE), '', { flag: 'wx' }).catch(ignoreExists)
+  // git does not track empty directories, so without these files the empty
+  // `packages/` (a bun workspace root) and `public/` (the guest-visible zone)
+  // would silently disappear from the initial commit. The other DIRECTORIES are
+  // either gitignored (workspace, sessions, mounts) or immediately populated.
+  await Promise.all([
+    writeFile(join(root, PACKAGES_DIR, GITKEEP_FILE), '', { flag: 'wx' }).catch(ignoreExists),
+    writeFile(join(root, PUBLIC_DIR, GITKEEP_FILE), '', { flag: 'wx' }).catch(ignoreExists),
+  ])
 
   // Only fields without sensible defaults elsewhere are emitted. Everything
   // with a schema-provided default (e.g. `network.blockInternal`, `mounts`,

package/src/init/paths.ts

@@ -1,2 +1,3 @@
 export const PACKAGES_DIR = 'packages'
+export const PUBLIC_DIR = 'public'
 export const GITKEEP_FILE = '.gitkeep'

package/src/inspect/label.ts

@@ -20,6 +20,8 @@ export function originLabel(origin: MinimalSessionOrigin): string {
       return `Subagent ${origin.subagent} ← ${shortSessionId(origin.parentSessionId)}`
     case 'channel':
       return channelLabel(origin)
+    case 'system':
+      return `System ${origin.component}`
   }
 }