typeclaw 0.15.2 → 0.17.0

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'
@@ -164,6 +164,19 @@ export const SESSION_FRESHNESS_TTL_MS = 5 * 60 * 1000
 // instead of awaiting the same dead promise forever.
 export const ENSURE_LIVE_TIMEOUT_MS = 30_000
 
+// Thrown by ensureLive() when a teardown (roles reload or shutdown) raced
+// ahead of an in-flight creation. route() has no special handling — it
+// propagates to the adapter's outer catch, dropping this one inbound. The
+// next inbound creates a fresh, post-reload session, which is the intended
+// outcome: a message that arrived mid-reload is cheap to drop, far cheaper
+// than answering it through a session built with the stale role.
+export class StaleLiveSessionError extends Error {
+  constructor(keyId: string) {
+    super(`[channels] ${keyId}: live session creation raced a teardown; discarded`)
+    this.name = 'StaleLiveSessionError'
+  }
+}
+
 // Per-callback ceilings inside the ensureLive chain. The outer watchdog
 // catches the worst case, but per-step timeouts give better log
 // attribution (which step hung) AND graceful degradation: a hung name
@@ -562,6 +575,7 @@ export type ChannelRouter = {
     | { kind: 'recorded-after-send'; keyId: string }
     | { kind: 'no-live-session' }
   stop: () => Promise<void>
+  tearDownAllLive: () => Promise<void>
   liveCount: () => number
   __testing?: {
     flushDebounce: (key: ChannelKey) => Promise<void>
@@ -691,6 +705,14 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
   const stream = options.stream
   const liveSessions = new Map<string, LiveSession>()
   const creating = new Map<string, Promise<LiveSession>>()
+  // Bumped by tearDownAllLive() and stop() before they tear sessions down. An
+  // in-flight ensureLive() captures the value at creation start and re-checks
+  // it right before installing into liveSessions; if it changed, a teardown
+  // raced ahead of this creation (e.g. a roles.match reload), so the session
+  // was built with stale role context and must self-dispose instead of
+  // installing — otherwise it would reintroduce the very staleness the
+  // teardown was meant to clear.
+  let liveGeneration = 0
   const outboundCallbacks = new Map<ChannelKey['adapter'], Set<OutboundCallback>>()
   const typingCallbacks = new Map<ChannelKey['adapter'], Set<TypingCallback>>()
   const channelNameResolvers = new Map<ChannelKey['adapter'], Set<ChannelNameResolver>>()
@@ -909,6 +931,8 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     const inFlight = creating.get(keyId)
     if (inFlight) return inFlight
 
+    const generation = liveGeneration
+
     const promise = (async () => {
       await ensureLoaded()
       const record = mappings ? findRecord(mappings, key) : undefined
@@ -1073,6 +1097,17 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
       live.unsubTypingActivity = subscribeTypingActivity(created.session, live)
       installChannelReplyTerminalHook(live)
       installChannelOutputCap(live)
+
+      // A teardown (roles reload / shutdown) ran while this session was being
+      // built, so it carries stale role context. Dispose it instead of
+      // installing — installing here is the exact window the race exploits.
+      if (generation !== liveGeneration) {
+        logger.info(
+          `[channels] ${keyId}: discarding session created across a teardown (gen ${generation} → ${liveGeneration})`,
+        )
+        await tearDownLive(live)
+        throw new StaleLiveSessionError(keyId)
+      }
       liveSessions.set(keyId, live)
 
       if (isColdStart) {
@@ -1427,11 +1462,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
@@ -1457,12 +1487,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).
@@ -1628,6 +1667,12 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         logger.info(`[channels] ${keyId}: ignoring unknown command /${parsedCommand.name}`)
         return
       }
+      if (isSessionControlDenied(event)) {
+        logger.info(
+          `[channels] ${keyId}: denied command /${parsedCommand.name} by permissions (session.control) author=${event.authorId}`,
+        )
+        return
+      }
       const existingLive = liveSessions.get(keyId)
       if (!existingLive || existingLive.destroyed) {
         logger.info(`[channels] ${keyId}: ignoring command /${parsedCommand.name} with no live session`)
@@ -1710,17 +1755,24 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     scheduleDebouncedDrain(live)
   }
 
-  const isChannelRespondDenied = (event: InboundMessage): boolean => {
-    const partial: SessionOrigin = {
-      kind: 'channel',
-      adapter: event.adapter,
-      workspace: event.workspace,
-      chat: event.chat,
-      thread: event.thread,
-      lastInboundAuthorId: event.authorId,
-    }
-    return !permissions.has(partial, CORE_PERMISSIONS.channelRespond)
-  }
+  const inboundAuthorOrigin = (event: InboundMessage): SessionOrigin => ({
+    kind: 'channel',
+    adapter: event.adapter,
+    workspace: event.workspace,
+    chat: event.chat,
+    thread: event.thread,
+    lastInboundAuthorId: event.authorId,
+  })
+
+  const isChannelRespondDenied = (event: InboundMessage): boolean =>
+    !permissions.has(inboundAuthorOrigin(event), CORE_PERMISSIONS.channelRespond)
+
+  // Gated separately from channelRespond so a respond-capable guest (an
+  // operator can grant guest channelRespond for masked stranger turns)
+  // cannot /stop another speaker's in-flight turn. session.control is
+  // member-and-up by default.
+  const isSessionControlDenied = (event: InboundMessage): boolean =>
+    !permissions.has(inboundAuthorOrigin(event), CORE_PERMISSIONS.sessionControl)
 
   const updateLoopGuard = (live: LiveSession, event: InboundMessage): void => {
     if (!event.authorIsBot) {
@@ -2199,9 +2251,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
@@ -2325,6 +2382,27 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
   const stop = async (): Promise<void> => {
     if (gcTimer) clearInterval(gcTimer)
     gcTimer = null
+    liveGeneration++
+    const all = Array.from(liveSessions.values())
+    liveSessions.clear()
+    for (const live of all) {
+      await tearDownLive(live)
+    }
+  }
+
+  // Drops every in-memory session but KEEPS the on-disk records, so the next
+  // inbound per channel rehydrates the same transcript through a fresh
+  // createSession() — which re-renders the frozen system-prompt role block.
+  // This is how a `roles.<name>.match` reload reaches live channel sessions.
+  // Unlike stop() it leaves the GC timer running; unlike stale-rollover it
+  // keeps the sessionId, so history survives.
+  //
+  // Bumping liveGeneration BEFORE the snapshot is what makes this race-free:
+  // a session mid-creation (in `creating` but not yet in `liveSessions`) won't
+  // appear in the snapshot below, but it captured the old generation and will
+  // self-dispose at its install guard instead of resurrecting stale role state.
+  const tearDownAllLive = async (): Promise<void> => {
+    liveGeneration++
     const all = Array.from(liveSessions.values())
     liveSessions.clear()
     for (const live of all) {
@@ -2341,11 +2419,11 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     if (!commands.has(lowered)) {
       return { kind: 'unknown-command', name: lowered }
     }
-    // Permission gate runs BEFORE the live-session lookup so a guest user
-    // invoking /stop on a non-existent session gets 'permission-denied'
-    // (consistent answer regardless of session state) rather than leaking
-    // session presence via the 'no-live-session' vs 'permission-denied'
-    // distinction.
+    // Gates on session.control (not channel.respond) so a respond-capable
+    // guest cannot abort another speaker's turn. Runs BEFORE the live-session
+    // lookup so an unauthorized invoker gets 'permission-denied' regardless of
+    // session state, rather than leaking session presence via the
+    // 'no-live-session' vs 'permission-denied' distinction.
     const partial: SessionOrigin = {
       kind: 'channel',
       adapter: key.adapter,
@@ -2354,7 +2432,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
       thread: key.thread,
       lastInboundAuthorId: options.invokerId,
     }
-    if (!permissions.has(partial, CORE_PERMISSIONS.channelRespond)) {
+    if (!permissions.has(partial, CORE_PERMISSIONS.sessionControl)) {
       return { kind: 'permission-denied' }
     }
     const resolved = resolveLiveSessionForCommand(liveSessions, key)
@@ -2467,6 +2545,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     injectSubagentCompletionReminder,
     markTurnSkipped,
     stop,
+    tearDownAllLive,
     liveCount: () => liveSessions.size,
     __testing: {
       flushDebounce: async (key: ChannelKey) => {
@@ -2534,13 +2613,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
@@ -3001,7 +3088,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'`.
@@ -3009,6 +3096,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
@@ -3020,22 +3121,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/cli/role.ts

@@ -3,7 +3,7 @@ import { defineCommand } from 'citty'
 
 import { requireContainerRunning, resolveHostPort, resolveTuiToken } from '@/container'
 import { findAgentDir } from '@/init'
-import { runClaimSession } from '@/role-claim'
+import { reloadAfterClaim, runClaimSession } from '@/role-claim'
 
 import { c, errorLine } from './ui'
 
@@ -76,6 +76,15 @@ const claimSub = defineCommand({
 
     if (result.kind === 'completed') {
       s.stop(c.green(`Paired as ${result.payload.role}.`))
+      s.start('Reloading config so the new match rule takes effect...')
+      const reloaded = await reloadAfterClaim({ url })
+      if (reloaded.ok) {
+        s.stop(c.green('Config reloaded.'))
+      } else {
+        // The role is already persisted; a reload failure is non-fatal.
+        s.stop(c.yellow(`Config reload failed: ${reloaded.reason}`))
+        console.log(c.dim('Run `typeclaw reload` manually to apply the new match rule.'))
+      }
       outro(`Match rule added: ${c.bold(result.payload.matchRule)}`)
       return
     }

package/src/cli/ui.ts

@@ -252,16 +252,18 @@ export function printSlackAppManifestSetup(output: NodeJS.WritableStream = proce
 // the exact permission bitfield the adapter uses. No-ops when the token isn't
 // parseable as a Discord bot token so we never block onboarding on best-effort
 // guidance.
-export function printDiscordInviteHint(token: string): void {
+export function printDiscordInviteHint(token: string, output: NodeJS.WritableStream = process.stdout): void {
   const appId = deriveAppIdFromBotToken(token)
   if (appId === null) return
+  // URL stays OUT of note(): clack wraps long lines with a `│` gutter that
+  // corrupts copy-pasted URLs. Same fix as src/cli/oauth-callbacks.ts.
   note(
     [
-      buildDiscordInviteUrl(appId),
-      '',
-      'Open it, pick a server, click Authorize.',
+      'Open the URL below, pick a server, click Authorize.',
       "The bot won't receive messages until it's in at least one server.",
     ].join('\n'),
     'Invite the bot to a server',
   )
+  output.write(`${buildDiscordInviteUrl(appId)}\n`)
+  output.write('\n')
 }

package/src/config/reloadable.ts

@@ -11,6 +11,10 @@ export type CreateConfigReloadableOptions = {
   // hand-edits) take effect without a container restart. `roles.<name>.permissions`
   // changes still require a restart — see FIELD_EFFECTS in config.ts.
   permissions?: PermissionService
+  // Fired after replaceRoles when a `roles.<name>.match` edit is applied. The
+  // run stage wires this to the channel router so live sessions are recreated
+  // and pick up the new role in their (otherwise frozen) system prompt.
+  onRolesChanged?: () => void | Promise<void>
   // Skip the mount-path accessibility check inside validateConfig. Mount paths
   // in typeclaw.json are host paths — they don't resolve inside the container,
   // so the check would always fail on any agent that declares mounts. `mounts`
@@ -22,18 +26,20 @@ export type CreateConfigReloadableOptions = {
 export function createConfigReloadable({
   cwd,
   permissions,
+  onRolesChanged,
   skipMountValidation = false,
 }: CreateConfigReloadableOptions): Reloadable {
   return {
     scope: 'config',
     description: 'typeclaw.json runtime config',
-    reload: async () => doReload(cwd, permissions, skipMountValidation),
+    reload: async () => doReload(cwd, permissions, onRolesChanged, skipMountValidation),
   }
 }
 
 async function doReload(
   cwd: string,
   permissions: PermissionService | undefined,
+  onRolesChanged: (() => void | Promise<void>) | undefined,
   skipMountValidation: boolean,
 ): Promise<ReloadResult> {
   // Mount accessibility belongs to the validation surface, not loadConfigSync —
@@ -59,8 +65,9 @@ async function doReload(
     return { scope: 'config', ok: false, reason: message }
   }
 
-  if (permissions !== undefined && diff.applied.some((c) => c.path === 'roles.match')) {
-    permissions.replaceRoles(getConfig().roles)
+  if (diff.applied.some((c) => c.path === 'roles.match')) {
+    permissions?.replaceRoles(getConfig().roles)
+    await onRolesChanged?.()
   }
 
   return {

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'
 
@@ -39,14 +39,6 @@ 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).
@@ -55,7 +47,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 +552,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`,
@@ -576,11 +578,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] } }
+  // No default `member` match is seeded. A fresh chat agent starts with every
+  // inbound author resolving to `guest` (dropped) until the operator claims
+  // `owner` (runOwnerClaim, post-hatch) and explicitly grants others. GitHub is
+  // wired separately and seeds per-repo `member.match` entries scoped to the
+  // opted-in repos. See runOwnerClaim for the mute-until-claimed warning.
   await writeFile(join(root, CONFIG_FILE), `${JSON.stringify(config, null, 2)}\n`)
 
   const cron = {
@@ -1036,8 +1038,6 @@ 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
@@ -1319,24 +1319,6 @@ 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/paths.ts

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