typeclaw 0.1.5 → 0.2.0

package/src/channels/adapters/kakaotalk.ts

@@ -14,7 +14,7 @@ import {
 import type { KakaoAccountCredentials, KakaoConfig, PendingLoginState } from 'agent-messenger/kakaotalk'
 
 import type { ChannelRouter } from '@/channels/router'
-import { isAllowed, type ChannelAdapterConfig, type KakaotalkAdapterConfig } from '@/channels/schema'
+import type { ChannelAdapterConfig } from '@/channels/schema'
 import type {
   ChannelHistoryMessage,
   FetchHistoryArgs,
@@ -106,7 +106,7 @@ const consoleLogger: KakaotalkAdapterLogger = {
 
 export type KakaotalkAdapterOptions = {
   router: ChannelRouter
-  configRef: () => KakaotalkAdapterConfig
+  configRef: () => ChannelAdapterConfig
   logger?: KakaotalkAdapterLogger
   selfAliasesRef?: () => readonly string[]
   credentialsStore?: KakaoCredentialStore
@@ -162,20 +162,14 @@ function formatLabel(name: string | undefined, id: string, prefix = ''): string
 
 export function createOutboundCallback(deps: {
   client: Pick<KakaoTalkClient, 'sendMessage'>
-  configRef: () => ChannelAdapterConfig
   logger: KakaotalkAdapterLogger
   formatChannelTag: (workspace: string, chat: string) => Promise<string>
 }): OutboundCallback {
-  const { client, configRef, logger, formatChannelTag } = deps
+  const { client, logger, formatChannelTag } = deps
   return async (msg: OutboundMessage): Promise<SendResult> => {
     if (msg.adapter !== 'kakaotalk') {
       return { ok: false, error: `unknown adapter: ${msg.adapter}` }
     }
-    const config = configRef()
-    if (!isAllowed(config.allow, msg.workspace, msg.chat)) {
-      logger.warn(`[kakaotalk] outbound denied by allow rules: ${msg.workspace}/${msg.chat}`)
-      return { ok: false, error: 'denied by allow rules' }
-    }
     const text = msg.text ?? ''
     const attachments = msg.attachments ?? []
     if (attachments.length > 0) {
@@ -214,27 +208,12 @@ export function createOutboundCallback(deps: {
 
 export function createKakaoHistoryCallback(deps: {
   client: Pick<KakaoTalkClient, 'getMessages'>
-  configRef: () => ChannelAdapterConfig
   logger: KakaotalkAdapterLogger
-  channelResolver: Pick<KakaoChannelResolver, 'lookupChat' | 'refresh'>
   authorResolver: Pick<KakaoAuthorResolver, 'resolve'>
   selfUserIdRef: () => string | null
 }): HistoryCallback {
-  const { client, configRef, logger, channelResolver, authorResolver, selfUserIdRef } = deps
+  const { client, logger, authorResolver, selfUserIdRef } = deps
   return async (args: FetchHistoryArgs): Promise<FetchHistoryResult> => {
-    const config = configRef()
-    let lookup = channelResolver.lookupChat(args.chat)
-    if (lookup === null) {
-      await channelResolver.refresh()
-      lookup = channelResolver.lookupChat(args.chat)
-    }
-    // Fallback to the most restrictive bucket (group) when the resolver
-    // can't classify after refresh — keeps allow-rule enforcement strict
-    // rather than defaulting to a permissive bucket.
-    const workspace = lookup?.workspace ?? '@kakao-group'
-    if (!isAllowed(config.allow, workspace, args.chat)) {
-      return { ok: false, error: 'denied by allow rules' }
-    }
     const limit = clampLimit(args.limit, KAKAO_HISTORY_LIMIT_MAX)
     try {
       const messages = await client.getMessages(args.chat, {
@@ -311,16 +290,13 @@ export function createKakaotalkAdapter(options: KakaotalkAdapterOptions): Kakaot
 
   const historyCallback = createKakaoHistoryCallback({
     client,
-    configRef: options.configRef,
     logger,
-    channelResolver,
     authorResolver,
     selfUserIdRef: () => selfUserId,
   })
 
   const outboundCallback = createOutboundCallback({
     client,
-    configRef: options.configRef,
     logger,
     formatChannelTag,
   })
@@ -390,10 +366,7 @@ export function createKakaotalkAdapter(options: KakaotalkAdapterOptions): Kakaot
         ...(options.selfAliasesRef ? { selfAliases: options.selfAliasesRef() } : {}),
       })
       if (verdict.kind === 'drop') {
-        const bucket = channelResolver.lookupChat(event.chat_id)?.workspace ?? null
-        logger.info(
-          `[kakaotalk] dropped log_id=${event.log_id} reason=${verdict.reason}${dropHint(verdict.reason, bucket, event.chat_id)}`,
-        )
+        logger.info(`[kakaotalk] dropped log_id=${event.log_id} reason=${verdict.reason}${dropHint(verdict.reason)}`)
         return
       }
 
@@ -462,6 +435,15 @@ export function createKakaotalkAdapter(options: KakaotalkAdapterOptions): Kakaot
         logger.info(`[kakaotalk] authenticated as ${profile.nickname || profile.user_id} (${profile.user_id})`)
       } catch (err) {
         started = false
+        if (isKakaoUnauthorizedError(err)) {
+          const message =
+            'KakaoTalk sub-device session is stale (server returned 401 on getProfile). ' +
+            'This usually means the ~7-day token TTL has expired and the hostd renewal cron has not refreshed it yet — ' +
+            'either because the agent was just initialized without stored credentials, or because the encryption key ' +
+            'is missing/wrong. Run `typeclaw channel reauth kakaotalk` to mint fresh tokens, then `typeclaw reload`.'
+          logger.error(`[kakaotalk] ${message}`)
+          throw new Error(message)
+        }
         logger.error(`[kakaotalk] getProfile failed: ${describe(err)}`)
         throw err
       }
@@ -525,7 +507,8 @@ export function createKakaotalkAdapter(options: KakaotalkAdapterOptions): Kakaot
             `[kakaotalk] session is DEAD after KICKOUT — ${reason}. ` +
               'Likely a real cross-device login is fighting our session. ' +
               'Stop the other client, then run `typeclaw restart`. ' +
-              'If the conflict persists, re-run `typeclaw init` to mint a new device_uuid.',
+              'If the conflict persists, run `typeclaw channel reauth kakaotalk` to mint a fresh sub-device session ' +
+              '(the existing device_uuid is preserved by default so the new login skips phone-passcode confirmation).',
           )
           resetRecoveryEpisode()
           return
@@ -656,14 +639,8 @@ function markReadIfSupported(deps: {
   )
 }
 
-function dropHint(
-  reason: InboundDropReason,
-  bucket: '@kakao-dm' | '@kakao-group' | '@kakao-open' | null,
-  chatId: string,
-): string {
+function dropHint(reason: InboundDropReason): string {
   switch (reason) {
-    case 'not_in_allow_list':
-      return ` (add ${suggestedAllowPattern(bucket, chatId)} to channels.kakaotalk.allow to admit this chat)`
     case 'unknown_chat':
       return ' (chat not in cache after refresh and provisional registration; check earlier resolver-refresh-failed warnings)'
     case 'empty_text':
@@ -673,14 +650,18 @@ function dropHint(
   }
 }
 
-function suggestedAllowPattern(bucket: '@kakao-dm' | '@kakao-group' | '@kakao-open' | null, chatId: string): string {
-  if (bucket === '@kakao-dm') return `"kakao:dm/*" or "kakao:${chatId}"`
-  if (bucket === '@kakao-group') return `"kakao:group/*" or "kakao:${chatId}"`
-  if (bucket === '@kakao-open') return `"kakao:open/*" or "kakao:${chatId}"`
-  return `"kakao:${chatId}"`
-}
-
 function isKickoutError(err: unknown): boolean {
   if (!(err instanceof Error)) return false
   return err.message.includes('kicked') || err.message.includes('KICKOUT')
 }
+
+// String-match on agent-messenger's `Profile request failed: ${status}`
+// error format (see kakaotalk/client.js:544). The SDK throws KakaoTalkError
+// with code='profile_request_failed' for any non-2xx status, so we have to
+// inspect the message to tell 401 (expired sub-device token, needs renewal)
+// apart from 5xx (transient server issue). Until the SDK exposes a typed
+// `unauthorized` code, this is the realistic detection path.
+function isKakaoUnauthorizedError(err: unknown): boolean {
+  if (!(err instanceof Error)) return false
+  return /Profile request failed: 401\b/.test(err.message)
+}

package/src/channels/adapters/slack-bot-classify.ts

@@ -1,7 +1,7 @@
 import type { SlackFile, SlackSocketModeAppMentionEvent, SlackSocketModeMessageEvent } from 'agent-messenger/slackbot'
 
 import { matchesAnyAlias } from '@/channels/engagement'
-import { isAllowed, type ChannelAdapterConfig } from '@/channels/schema'
+import type { ChannelAdapterConfig } from '@/channels/schema'
 import type { InboundMessage } from '@/channels/types'
 
 import { slackTsToMillis } from './slack-bot-time'
@@ -38,7 +38,6 @@ export type InboundDropReason =
   | 'self_author' // event.user === botUserId; we never route our own messages back to ourselves
   | 'no_user' // event has no `user` field (e.g. system messages: channel_join, message_changed)
   | 'empty_text' // event has neither text nor files — nothing for the agent to act on
-  | 'not_in_allow_list' // workspace/channel not admitted by typeclaw.json `channels.slack-bot.allow`
   | 'pre_connect' // bot identity is not known yet, so mention/self/reply classification cannot be trusted
 
 export type InboundClassification =
@@ -67,7 +66,7 @@ export type SlackInboundContext = {
 // forces logging to stay exhaustive.
 export function classifyInbound(
   event: SlackInboundMessageEvent,
-  config: ChannelAdapterConfig,
+  _config: ChannelAdapterConfig,
   context: SlackInboundContext,
 ): InboundClassification {
   // Self-drop is the hard floor: never route our own messages back to
@@ -92,9 +91,6 @@ export function classifyInbound(
 
   const isDm = event.channel_type === 'im'
   const workspace = isDm ? '@dm' : context.teamId
-  if (!isAllowed(config.allow, workspace, event.channel)) {
-    return { kind: 'drop', reason: 'not_in_allow_list' }
-  }
 
   if (context.botUserId === null) {
     return { kind: 'drop', reason: 'pre_connect' }

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

@@ -8,7 +8,7 @@ import {
 } from '@/channels/membership'
 import { deriveMembershipFromHistory } from '@/channels/membership-from-history'
 import type { ChannelRouter } from '@/channels/router'
-import { isAllowed, type ChannelAdapterConfig } from '@/channels/schema'
+import type { ChannelAdapterConfig } from '@/channels/schema'
 import type {
   ChannelHistoryMessage,
   FetchAttachmentCallback,
@@ -170,15 +170,12 @@ export function createSlackTypingTracker(deps: {
 
 export function createTypingCallback(deps: {
   typingTracker: Pick<SlackTypingTracker, 'setStatus' | 'clearAfterSend'>
-  configRef: () => ChannelAdapterConfig
   logger: SlackBotAdapterLogger
   formatChannelTag?: (workspace: string, chat: string) => Promise<string>
 }): TypingCallback {
-  const { typingTracker, configRef, logger, formatChannelTag } = deps
+  const { typingTracker, logger, formatChannelTag } = deps
   return async (target: TypingTarget): Promise<void> => {
     if (target.adapter !== 'slack-bot') return
-    const config = configRef()
-    if (!isAllowed(config.allow, target.workspace, target.chat)) return
     const tag = formatChannelTag
       ? await formatChannelTag(target.workspace, target.thread ?? target.chat)
       : `channel=${target.thread ?? target.chat}`
@@ -370,23 +367,13 @@ function slackFailureForError(error: string): MembershipResolverFailure {
 // and is the most-tested wire format.
 export function createSlackHistoryCallback(deps: {
   token: string
-  configRef: () => ChannelAdapterConfig
   logger: SlackBotAdapterLogger
   botUserIdRef: () => string | null
   fetchImpl?: typeof fetch
 }): HistoryCallback {
-  const { token, configRef, logger, botUserIdRef } = deps
+  const { token, logger, botUserIdRef } = deps
   const fetchFn = deps.fetchImpl ?? fetch
   return async (args: FetchHistoryArgs): Promise<FetchHistoryResult> => {
-    const config = configRef()
-    if (!isAllowed(config.allow, '@dm', args.chat) && !isAllowedAnyTeam(config.allow, args.chat)) {
-      // Same defense-in-depth as outbound: refuse to fetch history for a
-      // channel the operator hasn't admitted, even if the agent somehow
-      // resolved its id. Returning an error rather than empty so the
-      // agent doesn't think the channel is genuinely silent.
-      return { ok: false, error: 'denied by allow rules' }
-    }
-
     const limit = clampLimit(args.limit, SLACK_HISTORY_LIMIT_MAX)
     const endpoint = args.thread === null ? 'conversations.history' : 'conversations.replies'
     const body = new URLSearchParams()
@@ -465,25 +452,6 @@ function clampLimit(requested: number, max: number): number {
   return Math.min(Math.floor(requested), max)
 }
 
-// Slack channel ids are globally unique on Slack's side, so a `channel:C…`
-// or `team:T/C` rule for any team admits this chat. We use this for the
-// history allow check because at fetch time we only know the channel id,
-// not the workspace (the tool resolves the chat from session origin and
-// the workspace doesn't always round-trip through cursor pagination).
-function isAllowedAnyTeam(rules: readonly string[], chat: string): boolean {
-  for (const rule of rules) {
-    if (rule === '*') return true
-    if (rule === 'team:*' || rule === 'guild:*') return true
-    if (rule.startsWith('channel:') && rule.slice(8) === chat) return true
-    if (rule.startsWith('team:')) {
-      const body = rule.slice(5)
-      const slash = body.indexOf('/')
-      if (slash !== -1 && body.slice(slash + 1) === chat) return true
-    }
-  }
-  return false
-}
-
 // Slack supports text+file in a single API call via `initial_comment`, and
 // honors `thread_ts` on every upload — both luxuries Discord lacks. So we
 // fold `text` into the FIRST attachment's `initial_comment` rather than
@@ -528,23 +496,17 @@ function buildMarkdownBlock(text: string): MarkdownBlock {
 
 export function createOutboundCallback(deps: {
   client: Pick<SlackBotClient, 'postMessage' | 'uploadFile'>
-  configRef: () => ChannelAdapterConfig
   logger: SlackBotAdapterLogger
   formatChannelTag: (workspace: string, chat: string) => Promise<string>
   readFile?: (path: string) => Promise<Buffer>
   typingTracker?: Pick<SlackTypingTracker, 'clearAfterSend'>
 }): OutboundCallback {
-  const { client, configRef, logger, formatChannelTag, typingTracker } = deps
+  const { client, logger, formatChannelTag, typingTracker } = deps
   const readFile = deps.readFile ?? readAttachmentBuffer
   return async (msg: OutboundMessage): Promise<SendResult> => {
     if (msg.adapter !== 'slack-bot') {
       return { ok: false, error: `unknown adapter: ${msg.adapter}` }
     }
-    const config = configRef()
-    if (!isAllowed(config.allow, msg.workspace, msg.chat)) {
-      logger.warn(`[slack-bot] outbound denied by allow rules: ${msg.workspace}/${msg.chat}`)
-      return { ok: false, error: 'denied by allow rules' }
-    }
     const text = msg.text ?? ''
     const attachments = msg.attachments ?? []
     if (text === '' && attachments.length === 0) {
@@ -672,14 +634,12 @@ export function createSlackBotAdapter(options: SlackBotAdapterOptions): SlackBot
 
   const typingCallback = createTypingCallback({
     typingTracker,
-    configRef: options.configRef,
     logger,
     formatChannelTag,
   })
 
   const historyCallback = createSlackHistoryCallback({
     token: options.token,
-    configRef: options.configRef,
     logger,
     botUserIdRef: () => botUserId,
   })
@@ -692,7 +652,6 @@ export function createSlackBotAdapter(options: SlackBotAdapterOptions): SlackBot
 
   const outboundCallback = createOutboundCallback({
     client,
-    configRef: options.configRef,
     logger,
     formatChannelTag,
     typingTracker,
@@ -865,13 +824,8 @@ function describe(err: unknown): string {
   return err instanceof Error ? err.message : String(err)
 }
 
-// Operator hints appended to drop logs. Kept short — full guidance lives in
-// docs. The not_in_allow_list hint is the highest-leverage one because that
-// failure mode is invisible from Slack's side (bot stays online).
 function dropHint(reason: InboundDropReason): string {
   switch (reason) {
-    case 'not_in_allow_list':
-      return ' (extend channels.slack-bot.allow in typeclaw.json to admit this team/channel)'
     case 'empty_text':
     case 'no_user':
     case 'pre_connect':

package/src/channels/adapters/telegram-bot-classify.ts

@@ -1,9 +1,9 @@
 import type { TelegramBotUser, TelegramMessage, TelegramMessageEntity } from 'agent-messenger/telegrambot'
 
-import { isAllowed, type ChannelAdapterConfig } from '@/channels/schema'
+import type { ChannelAdapterConfig } from '@/channels/schema'
 import type { InboundMessage } from '@/channels/types'
 
-export type InboundDropReason = 'self_author' | 'no_user' | 'empty_text' | 'not_in_allow_list' | 'pre_connect'
+export type InboundDropReason = 'self_author' | 'no_user' | 'empty_text' | 'pre_connect'
 
 export type InboundClassification =
   | { kind: 'drop'; reason: InboundDropReason }
@@ -13,13 +13,14 @@ export const TELEGRAM_WORKSPACE = 'telegram'
 
 // Telegram has no team/guild concept — every chat is identified by an
 // absolute (signed) numeric id. We pin `workspace` to a single bucket so
-// allow-rules like `tg:*` and `tg:<chat_id>` have a stable key to match
-// against. DMs use `private` chats and route the same way as group chats
-// from the router's perspective; `isDm` is set from `chat.type` so the
-// engagement layer can apply the DM-specific trigger.
+// match rules like `telegram:*` and `telegram:<chat_id>` resolve against
+// a stable key downstream in the permissions service. DMs use `private`
+// chats and route the same way as group chats from the router's
+// perspective; `isDm` is set from `chat.type` so the engagement layer
+// can apply the DM-specific trigger.
 export function classifyInbound(
   event: TelegramMessage,
-  config: ChannelAdapterConfig,
+  _config: ChannelAdapterConfig,
   bot: TelegramBotUser | null,
 ): InboundClassification {
   const author = event.from
@@ -34,9 +35,6 @@ export function classifyInbound(
   if (text === '') return { kind: 'drop', reason: 'empty_text' }
 
   const chat = String(event.chat.id)
-  if (!isAllowed(config.allow, TELEGRAM_WORKSPACE, chat)) {
-    return { kind: 'drop', reason: 'not_in_allow_list' }
-  }
 
   if (bot === null) {
     return { kind: 'drop', reason: 'pre_connect' }

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

@@ -3,7 +3,7 @@ import type { TelegramBotUser, TelegramMessage } from 'agent-messenger/telegramb
 
 import type { MembershipResolver, MembershipResolverFailure, MembershipResolverResult } from '@/channels/membership'
 import type { ChannelRouter } from '@/channels/router'
-import { isAllowed, type ChannelAdapterConfig } from '@/channels/schema'
+import type { ChannelAdapterConfig } from '@/channels/schema'
 import type {
   ChannelNameResolver,
   FetchAttachmentCallback,
@@ -77,12 +77,11 @@ export type TelegramBotAdapter = {
 
 export function createTypingCallback(deps: {
   token: string
-  configRef: () => ChannelAdapterConfig
   logger: TelegramBotAdapterLogger
   formatChannelTag?: (chat: string) => Promise<string>
   fetchImpl?: typeof fetch
 }): TypingCallback {
-  const { token, configRef, logger, formatChannelTag } = deps
+  const { token, logger, formatChannelTag } = deps
   const fetchImpl = deps.fetchImpl ?? fetch
   return async (target: TypingTarget): Promise<void> => {
     if (target.adapter !== 'telegram-bot') return
@@ -91,8 +90,6 @@ export function createTypingCallback(deps: {
     // a missed beat just gaps the indicator. There is no explicit clear,
     // so the 'stop' phase is a no-op.
     if (target.phase === 'stop') return
-    const config = configRef()
-    if (!isAllowed(config.allow, target.workspace, target.chat)) return
     const tag = formatChannelTag ? await formatChannelTag(target.chat) : `chat=${target.chat}`
     const body: Record<string, unknown> = { chat_id: target.chat, action: 'typing' }
     const threadId = parseThreadId(target.thread)
@@ -197,21 +194,15 @@ export function createTelegramMembershipResolver(deps: {
 
 export function createOutboundCallback(deps: {
   client: Pick<TelegramBotClient, 'sendMessage' | 'sendDocument'>
-  configRef: () => ChannelAdapterConfig
   logger: TelegramBotAdapterLogger
   formatChannelTag: (chat: string) => Promise<string>
   resolvePath?: (path: string) => string
 }): OutboundCallback {
-  const { client, configRef, logger, formatChannelTag, resolvePath } = deps
+  const { client, logger, formatChannelTag, resolvePath } = deps
   return async (msg: OutboundMessage): Promise<SendResult> => {
     if (msg.adapter !== 'telegram-bot') {
       return { ok: false, error: `unknown adapter: ${msg.adapter}` }
     }
-    const config = configRef()
-    if (!isAllowed(config.allow, msg.workspace, msg.chat)) {
-      logger.warn(`[telegram-bot] outbound denied by allow rules: ${msg.workspace}/${msg.chat}`)
-      return { ok: false, error: 'denied by allow rules' }
-    }
     const text = msg.text ?? ''
     const attachments = msg.attachments ?? []
     if (text === '' && attachments.length === 0) {
@@ -396,7 +387,6 @@ export function createTelegramBotAdapter(options: TelegramBotAdapterOptions): Te
 
   const typingCallback = createTypingCallback({
     token: options.token,
-    configRef: options.configRef,
     logger,
     formatChannelTag,
   })
@@ -405,7 +395,6 @@ export function createTelegramBotAdapter(options: TelegramBotAdapterOptions): Te
 
   const outboundCallback = createOutboundCallback({
     client,
-    configRef: options.configRef,
     logger,
     formatChannelTag,
   })
@@ -595,8 +584,6 @@ function dropHint(reason: InboundDropReason): string {
       return ' (channel post / anonymous; cannot attribute to an author)'
     case 'empty_text':
       return ' (message had no text and no recognized media; check Telegram privacy mode in @BotFather)'
-    case 'not_in_allow_list':
-      return ' (extend channels.telegram-bot.allow in typeclaw.json to admit this chat)'
     case 'pre_connect':
     case 'self_author':
       return ''

package/src/channels/index.ts

@@ -2,17 +2,18 @@ export { createChannelManager, type ChannelManager, type ChannelManagerOptions }
 export {
   createChannelRouter,
   type ChannelRouter,
+  type ClaimHandler,
+  type ClaimHandlerInput,
+  type ClaimHandlerOutcome,
   type CreateChannelRouterOptions,
   type CreateSessionForChannel,
 } from './router'
 export { createChannelsReloadable } from './reloadable'
 export {
   channelsSchema,
-  isAllowed,
   ADAPTER_IDS,
   STICKY_DEFAULT_WINDOW_MS,
   type AdapterId,
-  type AllowRule,
   type ChannelAdapterConfig,
   type ChannelsConfig,
   type EngagementConfig,

package/src/channels/manager.ts

@@ -1,6 +1,7 @@
 import { createHash } from 'node:crypto'
 import { join } from 'node:path'
 
+import type { PermissionService } from '@/permissions'
 import { SecretsKakaoCredentialStore } from '@/secrets/kakao-store'
 import { SecretsBackend } from '@/secrets/storage'
 
@@ -8,7 +9,7 @@ import { createDiscordBotAdapter, type DiscordBotAdapter } from './adapters/disc
 import { createKakaotalkAdapter, type KakaotalkAdapter } from './adapters/kakaotalk'
 import { createSlackBotAdapter, type SlackBotAdapter } from './adapters/slack-bot'
 import { createTelegramBotAdapter, type TelegramBotAdapter } from './adapters/telegram-bot'
-import { createChannelRouter, type ChannelRouter, type CreateSessionForChannel } from './router'
+import { createChannelRouter, type ChannelRouter, type ClaimHandler, type CreateSessionForChannel } from './router'
 import { ADAPTER_IDS, type AdapterId, type ChannelAdapterConfig, type ChannelsConfig } from './schema'
 
 export type ChannelManagerLogger = {
@@ -50,6 +51,17 @@ export type ChannelManagerOptions = {
   createKakaotalkAdapter?: typeof createKakaotalkAdapter
   createSlackAdapter?: typeof createSlackBotAdapter
   createTelegramAdapter?: typeof createTelegramBotAdapter
+  // Wake-up gate: forwarded to the router, which calls
+  // `permissions.has(origin, 'channel.respond')` BEFORE creating a
+  // session for any inbound. Optional here to keep direct manager-level
+  // tests easy to spin up; production wiring in src/run/index.ts always
+  // passes `pluginsLoaded.permissions`. Omitting it falls through to the
+  // router's grant-all default — see CreateChannelRouterOptions.
+  permissions?: PermissionService
+  // Forwarded to the router; intercepts DM inbounds carrying a role-claim
+  // code. Production wiring sets this from the role-claim subsystem (see
+  // src/run/index.ts). Tests typically omit it.
+  claimHandler?: ClaimHandler
 }
 
 export type ChannelManager = {
@@ -82,6 +94,8 @@ export function createChannelManager(options: ChannelManagerOptions): ChannelMan
     logger,
     ...(options.aliasesRef ? { configuredAliases: options.aliasesRef } : {}),
     ...(options.createSessionForChannel ? { createSessionForChannel: options.createSessionForChannel } : {}),
+    ...(options.permissions ? { permissions: options.permissions } : {}),
+    ...(options.claimHandler ? { claimHandler: options.claimHandler } : {}),
   })
   const createDiscordAdapter = options.createDiscordAdapter ?? createDiscordBotAdapter
   const createKakaotalk = options.createKakaotalkAdapter ?? createKakaotalkAdapter

package/src/channels/persistence.ts

@@ -6,7 +6,7 @@ import type { ChannelParticipant } from '@/agent/session-origin'
 import type { AdapterId } from './schema'
 import type { ChannelKey } from './types'
 
-const FILE_VERSION = 3
+const FILE_VERSION = 4
 
 // `sessionFile` is the basename (not the full path) of the JSONL transcript
 // for this (adapter, workspace, chat, thread) tuple. pi-coding-agent writes
@@ -25,11 +25,17 @@ export type ChannelSessionRecord = {
   workspace: string
   chat: string
   thread: string | null
-  sessionId: string
+  sessionId?: string
   sessionFile?: string
+  lastInboundAt?: number
   participants: ChannelParticipant[]
 }
 
+type FileV4 = {
+  version: 4
+  sessions: ChannelSessionRecord[]
+}
+
 type FileV3 = {
   version: 3
   sessions: ChannelSessionRecord[]
@@ -41,11 +47,13 @@ type FileV2 = {
 }
 
 export type ChannelSessionsLogger = {
+  info: (msg: string) => void
   warn: (msg: string) => void
   error: (msg: string) => void
 }
 
 const consoleLogger: ChannelSessionsLogger = {
+  info: (m) => console.log(m),
   warn: (m) => console.warn(m),
   error: (m) => console.error(m),
 }
@@ -82,17 +90,25 @@ export async function loadChannelSessions(
   }
   const version = (parsed as { version?: unknown }).version
   if (version === FILE_VERSION) {
-    const file = parsed as FileV3
+    const file = parsed as FileV4
     if (!Array.isArray(file.sessions)) return []
     return file.sessions.filter(isValidRecord)
   }
+  if (version === 3) {
+    const file = parsed as FileV3
+    if (!Array.isArray(file.sessions)) return []
+    return migrateV3ToV4(file.sessions.filter(isValidRecord), logger)
+  }
   if (version === 2) {
     const file = parsed as FileV2
     if (!Array.isArray(file.sessions)) return []
     const v2Records = file.sessions.filter(isValidV2Record)
-    return await migrateV2Records(agentDir, v2Records, logger)
+    const v3Records = await migrateV2Records(agentDir, v2Records, logger)
+    return migrateV3ToV4(v3Records, logger)
   }
-  logger.warn(`[channels] ${path} version ${String(version)} not supported (expected 2 or ${FILE_VERSION}); ignored`)
+  logger.warn(
+    `[channels] ${path} version ${String(version)} not supported (expected 2, 3, or ${FILE_VERSION}); ignored`,
+  )
   return []
 }
 
@@ -102,7 +118,7 @@ export async function saveChannelSessions(
   logger: ChannelSessionsLogger = consoleLogger,
 ): Promise<void> {
   const path = channelsSessionsPath(agentDir)
-  const payload: FileV3 = { version: FILE_VERSION, sessions: dedupe(sessions) }
+  const payload: FileV4 = { version: FILE_VERSION, sessions: dedupe(sessions) }
   try {
     await mkdir(dirname(path), { recursive: true })
     const tmp = `${path}.tmp`
@@ -123,7 +139,7 @@ export async function saveChannelSessions(
 // we'll be migrated forward.)
 async function migrateV2Records(
   agentDir: string,
-  v2Records: readonly Omit<ChannelSessionRecord, 'sessionFile'>[],
+  v2Records: readonly (Omit<ChannelSessionRecord, 'sessionFile' | 'sessionId'> & { sessionId: string })[],
   logger: ChannelSessionsLogger,
 ): Promise<ChannelSessionRecord[]> {
   if (v2Records.length === 0) return []
@@ -160,6 +176,13 @@ async function migrateV2Records(
   })
 }
 
+function migrateV3ToV4(v3Records: ChannelSessionRecord[], logger: ChannelSessionsLogger): ChannelSessionRecord[] {
+  logger.info(
+    `[channels] v3→v4: ${v3Records.length} record(s) migrated; first post-upgrade inbound will force fresh session`,
+  )
+  return v3Records.map((r) => ({ ...r, lastInboundAt: 0 }))
+}
+
 function dedupe(sessions: readonly ChannelSessionRecord[]): ChannelSessionRecord[] {
   const seen = new Map<string, ChannelSessionRecord>()
   for (const s of sessions) {
@@ -185,7 +208,9 @@ function isObject(v: unknown): v is Record<string, unknown> {
   return typeof v === 'object' && v !== null && !Array.isArray(v)
 }
 
-function isValidV2Record(v: unknown): v is Omit<ChannelSessionRecord, 'sessionFile'> {
+function isValidV2Record(
+  v: unknown,
+): v is Omit<ChannelSessionRecord, 'sessionFile' | 'sessionId'> & { sessionId: string } {
   if (!isObject(v)) return false
   const r = v as Record<string, unknown>
   return (
@@ -199,9 +224,18 @@ function isValidV2Record(v: unknown): v is Omit<ChannelSessionRecord, 'sessionFi
 }
 
 function isValidRecord(v: unknown): v is ChannelSessionRecord {
-  if (!isValidV2Record(v)) return false
+  if (!isObject(v)) return false
   const r = v as Record<string, unknown>
-  return r.sessionFile === undefined || typeof r.sessionFile === 'string'
+  return (
+    typeof r.adapter === 'string' &&
+    typeof r.workspace === 'string' &&
+    typeof r.chat === 'string' &&
+    (r.thread === null || typeof r.thread === 'string') &&
+    (r.sessionId === undefined || typeof r.sessionId === 'string') &&
+    (r.sessionFile === undefined || typeof r.sessionFile === 'string') &&
+    (r.lastInboundAt === undefined || typeof r.lastInboundAt === 'number') &&
+    Array.isArray(r.participants)
+  )
 }
 
 function describe(err: unknown): string {