typeclaw 0.15.2 → 0.17.0

package/src/init/run-owner-claim.ts

@@ -43,7 +43,7 @@ export async function runOwnerClaim({ url, configuredChannels }: RunOwnerClaimOp
     initialValue: true,
   })
   if (isCancel(proceed) || proceed === false) {
-    log.info(`Skipping. Run ${c.bold('typeclaw role claim')} later when you're ready.`)
+    warnMuteUntilClaimed()
     return
   }
 
@@ -78,9 +78,27 @@ export async function runOwnerClaim({ url, configuredChannels }: RunOwnerClaimOp
   }
   if (result.kind === 'error') {
     s.stop(c.red(`Claim failed: ${result.payload.reason}`))
-    log.info(`You can retry with ${c.bold('typeclaw role claim')} anytime.`)
+    warnMuteUntilClaimed()
     return
   }
   s.stop(c.yellow(`Claim timed out — no DM received within the window.`))
-  log.info(`Run ${c.bold('typeclaw role claim')} when you're ready.`)
+  warnMuteUntilClaimed()
+}
+
+// Printed on every path that finishes init WITHOUT a successful owner claim.
+// Since the scoped-by-default change removed the `member: ["*"]` seeding, an
+// unclaimed chat agent resolves every inbound to `guest` and drops it — the
+// agent answers no one. This is a footgun unless the operator is told plainly,
+// so the warning is loud and names the exact recovery command.
+function warnMuteUntilClaimed(): void {
+  note(
+    [
+      `Your agent will respond to ${c.bold('no one')} until you claim the owner role —`,
+      `every inbound message is currently dropped.`,
+      '',
+      `Run ${c.bold('typeclaw role claim')} to pair yourself, then grant others`,
+      `with the agent (ask it: "respond to <user>") or by editing typeclaw.json#roles.`,
+    ].join('\n'),
+    c.yellow('Heads up: agent is muted'),
+  )
 }

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}`
   }
 }
 

package/src/inspect/live.ts

@@ -239,7 +239,12 @@ function messageEndToEvents(
       return event
     }
     if (payload.errorMessage !== undefined) {
-      return { cat: 'error', ts, message: payload.errorMessage }
+      return {
+        cat: 'error',
+        ts,
+        message: payload.errorMessage,
+        ...(payload.stopReason !== undefined ? { stopReason: payload.stopReason } : {}),
+      }
     }
     if (payload.usage !== undefined && (payload.usage.totalTokens > 0 || payload.stopReason !== undefined)) {
       return {

package/src/inspect/render.ts

@@ -39,6 +39,7 @@ function renderTag(event: InspectEvent, opts: RenderOptions): string {
     case 'tool':
       return tint(opts, 'yellow', padEnd(event.phase === 'start' ? 'tool ▸' : 'tool ◂', 9))
     case 'error':
+      if (event.stopReason === 'aborted') return tint(opts, 'yellow', padEnd('abort', 9))
       return tint(opts, 'red', padEnd('error', 9))
     case 'done':
       return tint(opts, 'gray', padEnd('done', 9))
@@ -73,8 +74,13 @@ function renderBody(event: InspectEvent, opts: RenderOptions): string {
       const result = renderResult(event.result, opts.maxTextLength ?? DEFAULT_MAX_TEXT)
       return `${event.name} → ${status}${result ? ` ${result}` : ''} (${dur})`
     }
-    case 'error':
-      return tint(opts, 'red', truncate(singleLine(event.message), opts.maxTextLength ?? DEFAULT_MAX_TEXT))
+    case 'error': {
+      const aborted = event.stopReason === 'aborted'
+      const text = truncate(singleLine(event.message), opts.maxTextLength ?? DEFAULT_MAX_TEXT)
+      const suffix =
+        event.stopReason !== undefined && !aborted ? ` ${tint(opts, 'dim', `(stop=${event.stopReason})`)}` : ''
+      return `${tint(opts, aborted ? 'yellow' : 'red', text)}${suffix}`
+    }
     case 'done':
       return renderDone(event, opts)
     case 'broadcast':

package/src/inspect/replay.ts

@@ -137,7 +137,12 @@ function* assistantEvents(
     }
   }
   if (typeof message.errorMessage === 'string' && message.errorMessage !== '') {
-    yield { cat: 'error', ts, message: message.errorMessage }
+    yield {
+      cat: 'error',
+      ts,
+      message: message.errorMessage,
+      ...(typeof message.stopReason === 'string' ? { stopReason: message.stopReason } : {}),
+    }
   }
   const usage = readUsage(message.usage)
   if (usage !== null && (usage.totalTokens > 0 || typeof message.stopReason === 'string')) {

package/src/inspect/types.ts

@@ -37,7 +37,10 @@ export type InspectEvent =
       isError?: boolean
       durationMs?: number
     }
-  | { cat: 'error'; ts: number; message: string }
+  // `stopReason` is the upstream-reported reason for the failed/aborted turn
+  // (e.g. 'error', 'aborted'). An 'aborted' stopReason is a user cancel, not a
+  // provider failure, and is rendered distinctly (see render.ts).
+  | { cat: 'error'; ts: number; message: string; stopReason?: string }
   | {
       cat: 'done'
       ts: number

package/src/permissions/builtins.ts

@@ -10,12 +10,26 @@ export const BUILTIN_ROLE_NAMES: readonly BuiltinRoleName[] = ['owner', 'trusted
 // set at boot via expandOwnerWildcard.
 export const CORE_PERMISSIONS = {
   channelRespond: 'channel.respond',
+  // Distinct from channelRespond so a respond-capable guest cannot abort
+  // other speakers' sessions. The /stop command (both the text-prefix and
+  // native-slash paths in the router) gates on this, not on channelRespond:
+  // an operator may grant guest channelRespond to let strangers drive masked
+  // turns, but session lifecycle control stays member-and-up.
+  sessionControl: 'session.control',
   cronSchedule: 'cron.schedule',
   cronModify: 'cron.modify',
   subagentSpawn: 'subagent.spawn',
   subagentCancel: 'subagent.cancel',
   subagentOutput: 'subagent.output',
   subagentSpawnOperator: 'subagent.spawn.operator',
+  // Phrased as capabilities to SEE, not to hide, so the role tower stays
+  // monotonic (a higher tier sees a strict superset of a lower tier).
+  // resolveHiddenPaths masks whatever the resolved role lacks: fsSeePrivate
+  // gates workspace/+memory/+sessions/, fsSeeSecrets gates .env+secrets.json.
+  // The fail-safe floor is the undefined origin (see has() in
+  // permissions.ts), not the guest role, which is now grantable.
+  fsSeePrivate: 'fs.see.private',
+  fsSeeSecrets: 'fs.see.secrets',
 } as const
 
 // Sentinel that `expandOwnerWildcard` swaps for the concrete union of
@@ -55,12 +69,15 @@ export const BUILTIN_ROLES: Readonly<Record<BuiltinRoleName, BuiltinRoleSpec>> =
     match: [{ kind: 'tui' }],
     permissions: [
       CORE_PERMISSIONS.channelRespond,
+      CORE_PERMISSIONS.sessionControl,
       CORE_PERMISSIONS.cronSchedule,
       CORE_PERMISSIONS.cronModify,
       CORE_PERMISSIONS.subagentSpawn,
       CORE_PERMISSIONS.subagentCancel,
       CORE_PERMISSIONS.subagentOutput,
       CORE_PERMISSIONS.subagentSpawnOperator,
+      CORE_PERMISSIONS.fsSeePrivate,
+      CORE_PERMISSIONS.fsSeeSecrets,
       'security.bypass.low',
       'security.bypass.medium',
       'security.bypass.high',
@@ -71,11 +88,14 @@ export const BUILTIN_ROLES: Readonly<Record<BuiltinRoleName, BuiltinRoleSpec>> =
     match: [],
     permissions: [
       CORE_PERMISSIONS.channelRespond,
+      CORE_PERMISSIONS.sessionControl,
       CORE_PERMISSIONS.cronSchedule,
       CORE_PERMISSIONS.subagentSpawn,
       CORE_PERMISSIONS.subagentCancel,
       CORE_PERMISSIONS.subagentOutput,
       CORE_PERMISSIONS.subagentSpawnOperator,
+      CORE_PERMISSIONS.fsSeePrivate,
+      CORE_PERMISSIONS.fsSeeSecrets,
       'security.bypass.low',
       'security.bypass.medium',
     ],
@@ -84,9 +104,11 @@ export const BUILTIN_ROLES: Readonly<Record<BuiltinRoleName, BuiltinRoleSpec>> =
     match: [],
     permissions: [
       CORE_PERMISSIONS.channelRespond,
+      CORE_PERMISSIONS.sessionControl,
       CORE_PERMISSIONS.subagentSpawn,
       CORE_PERMISSIONS.subagentCancel,
       CORE_PERMISSIONS.subagentOutput,
+      CORE_PERMISSIONS.fsSeePrivate,
       'security.bypass.low',
     ],
   },

package/src/permissions/grant.ts

@@ -1,6 +1,9 @@
 import { existsSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
 
+import { commitSystemFileSync } from '@/git/system-commit'
+
+import { BUILTIN_ROLES, isBuiltinRoleName } from './builtins'
 import { parseMatchRule } from './match-rule'
 
 // Appends `rule` to `typeclaw.json#roles.<name>.match`, creating the role
@@ -23,15 +26,97 @@ export type GrantOptions = {
   matchRule: string
 }
 
+export type GrantPermissionOptions = {
+  cwd: string
+  roleName: string
+  permission: string
+}
+
 export function grantRole(opts: GrantOptions): GrantResult {
   const validation = parseMatchRule(opts.matchRule)
   if (!validation.ok) {
     return { ok: false, reason: `invalid match rule '${opts.matchRule}': ${validation.error}` }
   }
 
-  const path = join(opts.cwd, CONFIG_FILE)
+  const loaded = loadConfigObject(opts.cwd, opts.roleName)
+  if (!loaded.ok) return loaded
+
+  const { obj, roles, role } = loaded
+  const existingMatch = Array.isArray(role.match) ? [...(role.match as unknown[])] : []
+
+  // Dedup by exact string equality — match rules canonicalize during load,
+  // and a literal duplicate in the file is a noise source the schema doesn't
+  // currently dedupe for us.
+  if (existingMatch.includes(opts.matchRule)) {
+    return { ok: true, added: false }
+  }
+
+  role.match = [...existingMatch, opts.matchRule]
+  roles[opts.roleName] = role
+  obj.roles = roles
+
+  const written = writeConfigObject(opts.cwd, obj)
+  if (!written.ok) return written
+
+  // Best-effort commit so a claimed role survives a fresh clone/rebuild — a
+  // failing commit leaves the on-disk grant intact (history, not correctness).
+  // Subject stays neutral: every grantRole caller hits this, not just claim.
+  commitSystemFileSync(opts.cwd, CONFIG_FILE, `${CONFIG_FILE}: grant ${opts.roleName} role`)
+
+  return written
+}
+
+// Appends `permission` to `typeclaw.json#roles.<name>.permissions`. For a
+// built-in role with no explicit `permissions[]`, the runtime treats the
+// field as "use built-in defaults" (see resolveOne in permissions.ts), so a
+// naive write of `[permission]` would NARROW the role to a single capability,
+// silently dropping its defaults. We materialize the current effective set
+// (explicit field if present, else the built-in default list) and append to
+// THAT, preserving every existing capability. Idempotent: a permission the
+// role already holds is a no-op.
+//
+// NOTE: `roles.permissions` is `restart-required` (FIELD_EFFECTS); the write
+// lands on disk but does not take effect until the next container restart.
+// Callers must surface that to the operator.
+export function grantRolePermission(opts: GrantPermissionOptions): GrantResult {
+  const loaded = loadConfigObject(opts.cwd, opts.roleName)
+  if (!loaded.ok) return loaded
+
+  const { obj, roles, role } = loaded
+  const effective = effectivePermissions(opts.roleName, role)
+
+  if (effective.includes(opts.permission)) {
+    return { ok: true, added: false }
+  }
+
+  role.permissions = [...effective, opts.permission]
+  roles[opts.roleName] = role
+  obj.roles = roles
+
+  return writeConfigObject(opts.cwd, obj)
+}
+
+function effectivePermissions(roleName: string, role: Record<string, unknown>): string[] {
+  if (Array.isArray(role.permissions)) {
+    return role.permissions.filter((p): p is string => typeof p === 'string')
+  }
+  if (isBuiltinRoleName(roleName)) {
+    return [...BUILTIN_ROLES[roleName].permissions]
+  }
+  return []
+}
+
+type LoadedConfig = {
+  ok: true
+  obj: Record<string, unknown>
+  roles: Record<string, unknown>
+  role: Record<string, unknown>
+}
+
+function loadConfigObject(cwd: string, roleName: string): LoadedConfig | { ok: false; reason: string } {
+  const path = join(cwd, CONFIG_FILE)
   if (!existsSync(path)) {
-    return { ok: false, reason: `${CONFIG_FILE} not found at ${opts.cwd}` }
+    return { ok: false, reason: `${CONFIG_FILE} not found at ${cwd}` }
   }
 
   let raw: string
@@ -54,26 +139,17 @@ export function grantRole(opts: GrantOptions): GrantResult {
 
   const obj = json as Record<string, unknown>
   const roles = isPlainObject(obj.roles) ? { ...obj.roles } : {}
-  const role = isPlainObject(roles[opts.roleName]) ? { ...(roles[opts.roleName] as Record<string, unknown>) } : {}
-  const existingMatch = Array.isArray(role.match) ? [...(role.match as unknown[])] : []
-
-  // Dedup by exact string equality — match rules canonicalize during load,
-  // and a literal duplicate in the file is a noise source the schema doesn't
-  // currently dedupe for us.
-  if (existingMatch.includes(opts.matchRule)) {
-    return { ok: true, added: false }
-  }
-
-  role.match = [...existingMatch, opts.matchRule]
-  roles[opts.roleName] = role
-  obj.roles = roles
+  const role = isPlainObject(roles[roleName]) ? { ...(roles[roleName] as Record<string, unknown>) } : {}
+  return { ok: true, obj, roles, role }
+}
 
+function writeConfigObject(cwd: string, obj: Record<string, unknown>): GrantResult {
+  const path = join(cwd, CONFIG_FILE)
   try {
     writeAtomic(path, `${JSON.stringify(obj, null, 2)}\n`)
   } catch (error) {
     return { ok: false, reason: `failed to write ${CONFIG_FILE}: ${describeError(error)}` }
   }
-
   return { ok: true, added: true }
 }
 

package/src/permissions/index.ts

@@ -24,6 +24,12 @@ export {
   type PermissionService,
   type UnknownPermissionWarning,
 } from './permissions'
-export { grantRole, type GrantOptions, type GrantResult } from './grant'
-export { matchesOrigin, type MatchableOrigin } from './resolve'
+export {
+  grantRole,
+  grantRolePermission,
+  type GrantOptions,
+  type GrantPermissionOptions,
+  type GrantResult,
+} from './grant'
+export { matchesOrigin, isDmChannelOrigin, type MatchableOrigin } from './resolve'
 export { MATCH_RULE_JSON_SCHEMA_PATTERN, rolesConfigSchema, type RoleConfig, type RolesConfig } from './schema'

package/src/permissions/permissions.ts

@@ -110,6 +110,13 @@ export function createPermissionService(opts: CreatePermissionServiceOptions = {
   function resolveRole(origin: SessionOrigin | undefined): string {
     if (origin === undefined) return 'guest'
 
+    // Runtime-owned infrastructure (memory, backup) acts on the operator's
+    // behalf over operator-owned state. It is constructed only by runtime/
+    // bundled code — inbound channel/cron content cannot produce this kind —
+    // so resolving it to owner is not a laundering vector. See the `system`
+    // origin doc in session-origin.ts.
+    if (origin.kind === 'system') return 'owner'
+
     if (origin.kind === 'cron') {
       const role = origin.scheduledByRole
       if (role !== undefined && byName.has(role)) return role
@@ -134,6 +141,15 @@ export function createPermissionService(opts: CreatePermissionServiceOptions = {
 
   return {
     has(origin, permission) {
+      // Fail-safe floor: an undefined origin holds nothing, regardless of
+      // role permissions. Previously this floor was implicit in `guest`
+      // being empty; now `guest` is grantable (an operator may grant it
+      // `channel.respond`), so the floor must live on the no-actor input
+      // instead. Keeps every downstream `has(maybeUndefined, ...)` check
+      // (bypass tiers, fs.see.*, subagent spawn) closed even after a guest
+      // grant. resolveRole/describe still report 'guest' for audit/display;
+      // only authorization is forced closed.
+      if (origin === undefined) return false
       const roleName = resolveRole(origin)
       const role = byName.get(roleName)
       if (!role) return false

package/src/permissions/resolve.ts

@@ -79,3 +79,13 @@ function matchesBucket(
   if (platform === 'telegram') return origin.workspace === 'dm' || origin.workspace.startsWith('@')
   return false
 }
+
+// True only for a 1:1 direct-message channel origin (a two-participant
+// conversation: the principal + the bot). Reuses the same per-adapter
+// workspace markers as the `dm` match-rule bucket. A DM is the only channel
+// shape with no third-party content buffered into a turn, so role-grant tools
+// treat an owner/trusted DM as injection-equivalent to the TUI; group/open
+// channels never qualify.
+export function isDmChannelOrigin(origin: { adapter: AdapterId; workspace: string }): boolean {
+  return matchesBucket('dm', { kind: 'channel', adapter: origin.adapter, workspace: origin.workspace, chat: '' })
+}

package/src/plugin/types.ts

@@ -250,6 +250,18 @@ export type SpawnSubagentOptions = {
   // `spawnedByOrigin: event.origin`. The runtime resolves `spawnedByRole`
   // from the origin via the PermissionService, so the spawning session's
   // role is inherited rather than forged from outside.
+  //
+  // TRUST MODEL: `spawnedByOrigin` accepts any SessionOrigin, including
+  // `{ kind: 'system' }`, which resolves to owner. That is intentional and
+  // not an escalation path: a plugin is a full-trust, in-process module with
+  // no sandbox (see AGENTS.md / docs/internals/skills) — it can already do
+  // anything the runtime can, so minting a system origin grants it nothing it
+  // lacks. The anti-forgery guarantee this API preserves is narrower and
+  // unaffected: inbound channel/cron CONTENT can never reach owner, because
+  // those origins are constructed by the runtime from the transport, never
+  // from message text, and a content-driven turn cannot produce a `system`
+  // origin. Bundled infra (memory, backup) uses `system` to act on the
+  // operator's own state; third-party plugins should pass `event.origin`.
   parentSessionId?: string
   spawnedByOrigin?: SessionOrigin
 }

package/src/role-claim/index.ts

@@ -10,6 +10,7 @@ export {
   type CreateClaimControllerOptions,
 } from './controller'
 export { formatClaimMatchRule, type PartialChannelOrigin } from './match-rule'
+export { reloadAfterClaim, type ReloadAfterClaimOptions, type ReloadAfterClaimResult } from './reload-after-claim'
 export {
   createPendingClaimRegistry,
   type ClaimResult,

package/src/role-claim/reload-after-claim.ts

@@ -0,0 +1,34 @@
+import { requestReload, type ReloadResult } from '@/reload'
+
+export interface ReloadAfterClaimOptions {
+  url: string
+  reload?: (opts: { url: string; scope: string }) => Promise<ReloadResult[]>
+}
+
+export type ReloadAfterClaimResult = { ok: true; results: ReloadResult[] } | { ok: false; reason: string }
+
+// Best-effort by contract: the role is already persisted to typeclaw.json by
+// the time a claim completes, so a reload failure here must NOT fail the claim.
+// Callers surface the reason but keep the claim successful.
+export async function reloadAfterClaim(opts: ReloadAfterClaimOptions): Promise<ReloadAfterClaimResult> {
+  const reload = opts.reload ?? requestReload
+  let results: ReloadResult[]
+  try {
+    results = await reload({ url: opts.url, scope: 'config' })
+  } catch (err) {
+    return { ok: false, reason: err instanceof Error ? err.message : String(err) }
+  }
+
+  // requestReload resolves even when the server reports a per-scope failure, so
+  // an exception-free call is not proof the config actually reloaded. Surface
+  // any failed scope (and an empty result, which means nothing reloaded) as a
+  // failure so the caller can tell the user to reload manually.
+  const failed = results.filter((r) => !r.ok)
+  if (failed.length > 0) {
+    return { ok: false, reason: failed.map((r) => `${r.scope}: ${r.reason}`).join('; ') }
+  }
+  if (results.length === 0) {
+    return { ok: false, reason: 'no reloadable config scope responded' }
+  }
+  return { ok: true, results }
+}

package/src/run/channel-session-factory.ts

@@ -7,7 +7,7 @@ import type { CreateSessionForSubagent, SubagentRegistry } from '@/agent/subagen
 import { capJsonlFileInPlace } from '@/bundled-plugins/tool-result-cap/cap-jsonl'
 import type { CapOptions } from '@/bundled-plugins/tool-result-cap/cap-result'
 import type { CreateSessionForChannel, ChannelRouter } from '@/channels'
-import type { PermissionService } from '@/permissions'
+import type { PermissionService, RolesConfig } from '@/permissions'
 import type { ReloadRegistry } from '@/reload'
 import type { SessionFactory } from '@/sessions'
 import type { Stream } from '@/stream'
@@ -47,6 +47,10 @@ export type BuildChannelSessionFactoryDeps = {
   // the production wiring can plumb in pluginsLoaded.permissions while tests
   // (or stand-alone callers) keep the previous no-annotation behavior.
   permissions?: PermissionService
+  // Re-reads roles from disk for the grant_role tool's hot-reload (reload then
+  // read, not an in-memory snapshot). Forwarded to createSession; the tool only
+  // mounts when permissions is also present.
+  reloadRoles?: () => RolesConfig | undefined
   // Test seam: lets a fake stand in for the agent session creator so tests
   // can assert exactly which CreateSessionOptions the factory builds without
   // needing a live LLM, plugin runtime, or session manager on disk.
@@ -124,6 +128,7 @@ export function buildChannelSessionFactory(deps: BuildChannelSessionFactoryDeps)
       ...(deps.containerName !== undefined ? { containerName: deps.containerName } : {}),
       ...(deps.runtimeVersion !== undefined ? { runtimeVersion: deps.runtimeVersion } : {}),
       ...(deps.permissions !== undefined ? { permissions: deps.permissions } : {}),
+      ...(deps.reloadRoles !== undefined ? { reloadRoles: deps.reloadRoles } : {}),
       ...(deps.liveSubagentRegistry !== undefined ? { liveSubagentRegistry: deps.liveSubagentRegistry } : {}),
       ...(deps.subagentRegistry !== undefined ? { subagentRegistry: deps.subagentRegistry } : {}),
       ...(deps.getCreateSessionForSubagent !== undefined

package/src/run/index.ts

@@ -24,7 +24,7 @@ import {
   type SubagentCompletionBridge,
 } from '@/channels'
 import { createTunnelBridge, type TunnelBridge } from '@/channels/tunnel-bridge'
-import { createConfigReloadable, getConfig, loadConfigSync, loadPluginConfigsSync } from '@/config'
+import { createConfigReloadable, getConfig, loadConfigSync, loadPluginConfigsSync, reloadConfig } from '@/config'
 import {
   type CronConsumer,
   type CronJob,
@@ -150,6 +150,7 @@ export async function startAgent({
     createConfigReloadable({
       cwd,
       permissions: pluginsLoaded.permissions,
+      onRolesChanged: () => channelManager.router.tearDownAllLive(),
       skipMountValidation: containerName !== undefined,
     }),
   )
@@ -244,6 +245,7 @@ export async function startAgent({
       getChannelRouter: () => channelManager.router,
       rehydrateCapOptions: resolveCapOptionsFromConfig(pluginConfigsByName['tool-result-cap']),
       permissions: pluginsLoaded.permissions,
+      reloadRoles: () => reloadRolesFromDisk(cwd),
       liveSubagentRegistry,
       liveSessionRegistry,
       subagentRegistry: pluginRuntime.get().subagents,
@@ -688,6 +690,21 @@ async function disposeMaterializedSkills(pluginRuntime: PluginRuntime): Promise<
   await Promise.allSettled(all.map((m) => m.dispose()))
 }
 
+// grant_role's hot-reload hook: reload the live config FROM DISK (grantRole
+// wrote typeclaw.json directly, bypassing the in-memory snapshot) and return
+// the fresh roles for permissions.replaceRoles. Mirrors the config reloadable's
+// reload-then-read order. Falls back to the current snapshot if the just-written
+// file fails to parse — the on-disk write still stands and the next reload picks
+// it up; replaceRoles with stale roles is no worse than not reloading.
+function reloadRolesFromDisk(cwd: string): ReturnType<typeof getConfig>['roles'] {
+  try {
+    reloadConfig(cwd)
+  } catch {
+    // keep the current pointer; see above
+  }
+  return getConfig().roles
+}
+
 async function startScheduler({
   cwd,
   loadCron,

package/src/sandbox/build.ts

@@ -13,6 +13,11 @@ export type SandboxedCommand = {
   commandString: string
 }
 
+// Fixed fd the rendered commandString opens to /dev/null for --ro-bind-data
+// file masks. 3 is the first fd above stdio; the bash tool's spawn does not
+// inherit it, so the redirect is part of the command string itself.
+const MASK_DATA_FD = 3
+
 // Pure: no I/O, no bwrap availability probe (that is `ensureBwrapAvailable`'s
 // job). Given a bash command and a policy, returns the bwrap-wrapped argv plus
 // a shell-quoted rendering of it. Knows nothing about subagents, origins, or
@@ -24,7 +29,9 @@ export function buildSandboxedCommand(command: string, policy: SandboxPolicy = {
     applyCommandFilter(command, policy.commandFilter)
   }
   const argv = buildArgv(command, policy)
-  return { argv, commandString: formatCommand(argv) }
+  const needsMaskFd = (policy.masks?.files?.length ?? 0) > 0
+  const commandString = needsMaskFd ? `${formatCommand(argv)} ${MASK_DATA_FD}</dev/null` : formatCommand(argv)
+  return { argv, commandString }
 }
 
 function buildArgv(command: string, policy: SandboxPolicy): string[] {
@@ -58,6 +65,38 @@ function buildArgv(command: string, policy: SandboxPolicy): string[] {
 
   argv.push('--ro-bind', '/usr', '/usr', '--ro-bind', '/etc', '/etc', '--dev', '/dev', '--tmpfs', '/tmp')
 
+  // Recreate the usr-merge root symlinks that --ro-bind /usr does NOT bring
+  // along. On the Debian base (oven/bun:1-slim) /bin /sbin /lib /lib64 are
+  // root-level symlinks into /usr; binding /usr exposes /usr/bin etc. but the
+  // root entries themselves are absent in the sandbox. That breaks every
+  // ABSOLUTE-path reference the kernel resolves WITHOUT consulting PATH:
+  //   - ELF interpreter (the dynamic loader) baked into PT_INTERP:
+  //     /lib/ld-linux-aarch64.so.1 (arm64) or /lib64/ld-linux-x86-64.so.2
+  //     (amd64). Missing it makes bwrap report "execvp bash: No such file or
+  //     directory" — the missing file is the loader, not bash.
+  //   - shebang lines: /bin/sh and /bin/bash are the most common interpreters
+  //     on earth; a script with "#!/bin/sh" fails "cannot execute: required
+  //     file not found" without /bin, even though /usr/bin/sh exists, because
+  //     the shebang path is literal and skips PATH.
+  // --ro-bind-try, not --ro-bind: the set is arch- and base-dependent (arm64
+  // oven/bun:1-slim ships /lib but no /lib64), and a hard bind of an absent
+  // source aborts bwrap. -try binds each only when present, keeping this
+  // builder pure (no host filesystem probe) and correct across arches/bases.
+  argv.push(
+    '--ro-bind-try',
+    '/bin',
+    '/bin',
+    '--ro-bind-try',
+    '/sbin',
+    '/sbin',
+    '--ro-bind-try',
+    '/lib',
+    '/lib',
+    '--ro-bind-try',
+    '/lib64',
+    '/lib64',
+  )
+
   if ((policy.proc ?? 'tmpfs') === 'tmpfs') {
     // --tmpfs /proc, never --proc /proc (OrbStack's kernel blocks
     // mount("proc",...) from user namespaces) and never --dev-bind /proc /proc
@@ -70,6 +109,8 @@ function buildArgv(command: string, policy: SandboxPolicy): string[] {
     appendMount(argv, mount)
   }
 
+  appendMasks(argv, policy)
+
   if (policy.cwd !== undefined) {
     argv.push('--chdir', policy.cwd)
   }
@@ -78,6 +119,15 @@ function buildArgv(command: string, policy: SandboxPolicy): string[] {
   return argv
 }
 
+function appendMasks(argv: string[], policy: SandboxPolicy): void {
+  for (const dir of policy.masks?.dirs ?? []) {
+    argv.push('--tmpfs', dir)
+  }
+  for (const file of policy.masks?.files ?? []) {
+    argv.push('--ro-bind-data', String(MASK_DATA_FD), file)
+  }
+}
+
 function appendMount(argv: string[], mount: SandboxMount): void {
   switch (mount.type) {
     case 'ro-bind':

package/src/sandbox/hidden-paths.ts

@@ -0,0 +1,41 @@
+import { join } from 'node:path'
+
+import type { SessionOrigin } from '@/agent/session-origin'
+import { CORE_PERMISSIONS } from '@/permissions/builtins'
+import type { PermissionService } from '@/permissions/permissions'
+
+export type HiddenPaths = {
+  dirs: string[]
+  files: string[]
+}
+
+const PRIVATE_DIRS = ['workspace', 'memory', 'sessions'] as const
+const SECRET_FILES = ['.env', 'secrets.json'] as const
+
+// The agent's private working surface and credential files are masked from
+// sandboxed bash unless the resolved role carries the matching fs.see.* grant.
+// `permissions.has` resolves the role from the live origin and fails safe to
+// guest (empty permissions) for an unclear/undefined origin, so a missing
+// grant — whether from a low tier or an unresolvable author — hides the path.
+//
+// The security.bypass.* fallback keeps custom roles (which may never name the
+// fs.see.* strings) working by capability: a role trusted enough to bypass
+// medium-severity guards is treated as trusted for filesystem visibility, and
+// bypass.low maps to the private-surface tier. fs.see.* always wins when
+// present; the fallback only fires when it is absent.
+export function resolveHiddenPaths(
+  permissions: PermissionService,
+  origin: SessionOrigin | undefined,
+  agentDir: string,
+): HiddenPaths {
+  const seesPrivate =
+    permissions.has(origin, CORE_PERMISSIONS.fsSeePrivate) ||
+    permissions.has(origin, 'security.bypass.low') ||
+    permissions.has(origin, 'security.bypass.medium')
+  const seesSecrets =
+    permissions.has(origin, CORE_PERMISSIONS.fsSeeSecrets) || permissions.has(origin, 'security.bypass.medium')
+
+  const dirs = seesPrivate ? [] : PRIVATE_DIRS.map((d) => join(agentDir, d))
+  const files = seesSecrets ? [] : SECRET_FILES.map((f) => join(agentDir, f))
+  return { dirs, files }
+}