typeclaw 0.13.0 → 0.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typeclaw",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "homepage": "https://github.com/typeclaw/typeclaw#readme",
   "bugs": {
     "url": "https://github.com/typeclaw/typeclaw/issues"

package/src/agent/system-prompt.ts

@@ -12,7 +12,17 @@ TypeClaw is domain-agnostic — your purpose is defined by \`IDENTITY.md\`, your
 - **AGENTS.md** *(read on demand)* — your operating manual. Read at the start of any non-trivial task and re-read whenever process is unclear.
 - **\`memory/topics/\`** *(always injected below, READ-ONLY)* — sharded long-term memory, owned by the dreaming subagent. To capture something memorable, surface it in your reply or let the memory-logger append to \`memory/streams/\`; never edit memory shards directly.
 
-If a task reveals durable guidance or identity/user context, update the owning file (IDENTITY / SOUL / USER / AGENTS) — never memory shards.
+If a task reveals durable guidance or identity/user context, update the owning file (IDENTITY / SOUL / USER / AGENTS) — never memory shards. **Use this routing when you have something durable to record:**
+
+- *role, function, scope of work, who you are to this user* → IDENTITY.md
+- *voice, tone, register, language preferences, persona quirks* → SOUL.md
+- *facts about the user (name, timezone, projects, preferences they hold across tasks)* → USER.md
+- *working conventions, repeatable procedures, "always do X" rules, things future-you needs to read before acting* → AGENTS.md
+- *one-off context for this conversation only* → don't write a file; it'll be captured in \`memory/streams/\` automatically
+
+When in doubt between SOUL.md and AGENTS.md: if it describes *how you sound*, it's SOUL; if it describes *how you work*, it's AGENTS. Tone preferences ("be more terse") go to SOUL.md; process rules ("always run tests before committing") go to AGENTS.md.
+
+**Edit discipline.** Prefer rewriting in place to growing files. SOUL.md should stay short — a paragraph or two; if it's drifting past a screen, you're using it as a scratchpad and the model that reads it will start ignoring the back half. IDENTITY.md is similar — a few lines of who you are, not a résumé. AGENTS.md is the one allowed to grow. Don't rewrite SOUL.md on the first piece of tone feedback in a session — wait until the user repeats a preference or asks you directly to update it; a single off-day request isn't a durable change.
 
 ## Your workspace
 

package/src/agent/tools/skip-response.ts

@@ -39,10 +39,13 @@ export type SkipResponseDetails = {
 // `skip_response` is preferred whenever the model has a reason worth
 // recording. See session-origin.ts for the prompt-level decision rule.
 //
-// Order-dependence with `channel_reply`/`channel_send`: once `skip_response`
-// fires in a turn, the router rejects any subsequent tool-source send for
-// the same turn with `SKIP_RESPONSE_LOCK_ERROR`. The model gets a clear
-// error and learns to commit on the next turn instead of mid-turn.
+// Order-dependence with `channel_reply`/`channel_send` is asymmetric:
+//   - skip BEFORE any send → commits to silence; the router rejects any
+//     subsequent tool-source send this turn with `SKIP_RESPONSE_LOCK_ERROR`.
+//   - skip AFTER a send → accepted as a terminal no-op (`recorded-after-send`).
+//     The earlier reply stands; this posts nothing and ends the turn. Rejecting
+//     it (the old behavior) drove a livelock: denied a clean silent exit, the
+//     model re-sent, got re-denied on the next skip, and repeated to the cap.
 export function createSkipResponseTool({
   router,
   sessionId,
@@ -55,12 +58,14 @@ export function createSkipResponseTool({
       'Decline to send a user-facing reply this turn, with a logged reason. Use this ' +
       'instead of narrating "I have nothing to add" / "I will stay quiet" in your visible ' +
       'response. The reason is written to host logs (visible via `typeclaw logs -f`) but ' +
-      'never delivered to the user. The contract is bidirectional: after calling this, any ' +
-      '`channel_reply` / `channel_send` in the same turn will be rejected, AND calling this ' +
-      'after a `channel_reply` / `channel_send` has already landed in this turn will also ' +
-      'be rejected — commit to silence or commit to replying, not both. Decide before you ' +
-      'send, and call this as your terminal tool when you decide to stay silent. Prefer ' +
-      'this over the `NO_REPLY` text sentinel whenever you have a reason worth recording.',
+      'never delivered to the user. If you call this BEFORE sending anything this turn, it ' +
+      'commits you to silence and any later `channel_reply` / `channel_send` in the same ' +
+      'turn is rejected. If you call it AFTER a reply has already landed this turn (e.g. you ' +
+      'posted an ack and now want to wait quietly for a backgrounded subagent), it is ' +
+      'accepted as a terminal no-op: your earlier reply stands, nothing further is sent, and ' +
+      'your turn ends. Either way, call this as your terminal tool when you decide to stop ' +
+      'talking — do NOT keep sending "still working" updates. Prefer this over the ' +
+      '`NO_REPLY` text sentinel whenever you have a reason worth recording.',
     parameters: Type.Object({
       reason: Type.String({
         description:
@@ -85,33 +90,20 @@ export function createSkipResponseTool({
       }
 
       const result = router.markTurnSkipped({ parentSessionId: sessionId, reason })
-      if (result.kind === 'send-already-happened') {
-        // Symmetric counterpart of the send-after-skip lock in `router.send()`.
-        // The model already committed to replying earlier in this turn; calling
-        // skip_response now would land the reply AND claim silence at the same
-        // time, which is the contract violation the lock exists to prevent.
-        // Surface a clear error and refuse to stamp the flag so the rest of
-        // the turn behaves as a normal reply turn.
-        logger.warn(
-          formatChannelToolFailure(
-            'skip_response',
-            `channel send already happened this turn (reason=${JSON.stringify(reason)})`,
-          ),
-        )
-        const details: SkipResponseDetails = {
-          ok: false,
-          suppressed: false,
-          reason,
-          error: 'send-already-happened',
-        }
+      if (result.kind === 'recorded-after-send') {
+        // Reply-first skip: an ack already landed; this just ends the turn
+        // quietly. Not suppressed (the reply stands) and not an error (erroring
+        // here is what drove the historical re-send livelock). Router logged it.
+        const details: SkipResponseDetails = { ok: true, suppressed: false, reason }
         return {
           content: [
             {
               type: 'text' as const,
               text:
-                'skip_response denied: you already sent a channel reply in this turn. ' +
-                'Commit to silence or commit to replying, not both. ' +
-                'End your turn now; the reply you already sent stands.',
+                'skip_response accepted: your earlier channel reply this turn stands, and ' +
+                'no further message will be sent. End your turn now — do not send "still ' +
+                'working" updates while a backgrounded subagent runs; the completion ' +
+                'reminder will wake you when it finishes.',
             },
           ],
           details,

package/src/agent/tools/spawn-subagent.ts

@@ -103,6 +103,7 @@ export function createSpawnSubagentTool(options: CreateSpawnSubagentToolOptions)
       if (params.description !== undefined) payload.description = params.description
 
       const startedAt = now()
+      const spawnedByRole = permissions?.resolveRole(origin)
       const { handle, completion } = startSubagent(subagentName, {
         registry,
         createSessionForSubagent,
@@ -110,6 +111,7 @@ export function createSpawnSubagentTool(options: CreateSpawnSubagentToolOptions)
         userPrompt: params.prompt,
         payload: subagent.payloadSchema ? payload : undefined,
         parentSessionId,
+        ...(spawnedByRole !== undefined ? { spawnedByRole } : {}),
         ...(origin !== undefined ? { spawnedByOrigin: origin } : {}),
         taskId,
       })

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

@@ -45,7 +45,7 @@ export function createGithubWebhookHandler(options: GithubWebhookHandlerOptions)
 
     const selfId = options.selfId()
     const selfLogin = options.selfLogin()
-    const author = readAuthor(payload)
+    const author = readAuthor(event, payload)
     if (author !== null && isSelfAuthor(author, selfId, selfLogin)) {
       options.logger.info(
         `[github] dropped self-authored ${event}${action !== null ? `.${action}` : ''} from @${author.login}`,
@@ -363,13 +363,52 @@ function readRepository(payload: Record<string, unknown>): { owner: string; name
   return { owner: ownerLogin, name }
 }
 
-function readAuthor(payload: Record<string, unknown>): GithubUser | null {
-  const candidates = [payload.comment, payload.issue, payload.pull_request, payload.discussion, payload.review]
-  for (const candidate of candidates) {
+function readAuthor(event: string, payload: Record<string, unknown>): GithubUser | null {
+  for (const candidate of eventAuthorCandidates(event, payload)) {
     const user = readUser(readRecord(candidate)?.user)
     if (user !== null) return user
   }
-  return null
+  // Every GitHub webhook payload carries `sender` — the actor who triggered the
+  // delivery. It is the universal fallback so events not enumerated above (and
+  // any future ones the user adds to eventAllowlist) still drop self-authored
+  // deliveries instead of slipping past the guard.
+  return readUser(payload.sender)
+}
+
+// Maps each event to the entity whose `user` is the true author of THIS event,
+// listed before broader containers. A pull_request_review payload ships both
+// `pull_request` (the PR author) and `review` (the reviewer); the self-author
+// drop must see the reviewer, so `review` must come first. PR #455's flat order
+// (`pull_request` before `review`) made a self-review on someone else's PR
+// resolve to the PR author, slip past the drop, and loop (see PR #460).
+//
+// `pull_request` and `pull_request_review_thread` carry only the `pull_request`
+// container, whose `user` is the PR OPENER — not the actor of this delivery.
+// For these events the self-author question is "who triggered the action?"
+// (review_requested, edited, reopened, resolved, …), which is always
+// `payload.sender`, never the opener. Mapping them to `[]` makes readAuthor
+// skip the opener and fall through to the `sender` fallback. PR #462's
+// `['pull_request']` resolved to the opener, so a human action on a
+// bot-opened PR matched the bot and was wrongly dropped (the inbound landed
+// as awareness-only "Recent context" and the agent never replied).
+const PRIMARY_AUTHOR_KEYS: Record<string, readonly string[]> = {
+  issue_comment: ['comment'],
+  pull_request_review_comment: ['comment'],
+  discussion_comment: ['comment'],
+  commit_comment: ['comment'],
+  pull_request_review: ['review'],
+  pull_request_review_thread: [],
+  issues: ['issue'],
+  pull_request: [],
+  discussion: ['discussion'],
+  release: ['release'],
+}
+
+const FALLBACK_AUTHOR_KEYS = ['comment', 'review', 'issue', 'pull_request', 'discussion', 'release'] as const
+
+function eventAuthorCandidates(event: string, payload: Record<string, unknown>): unknown[] {
+  const keys = PRIMARY_AUTHOR_KEYS[event] ?? FALLBACK_AUTHOR_KEYS
+  return keys.map((key) => payload[key])
 }
 
 // Matches by id OR login. Issue #452 captured a self-responding loop where

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

@@ -53,6 +53,14 @@ export type GithubAdapterOptions = {
   // Test-only: replaces the wall-clock sleep used for the registration
   // delay above. Production leaves it undefined and we use `setTimeout`.
   sleep?: (ms: number) => Promise<void>
+  // How often to proactively refresh the token and update GH_TOKEN
+  // when the adapter is running but has not made an outbound API call
+  // recently. Zero disables the background refresh entirely.
+  // Default: 30 minutes.
+  tokenRefreshIntervalMs?: number
+  // Test-only: replaces `setInterval` so tests can control when the
+  // background refresh fires without waiting on real wall-clock time.
+  setInterval?: (handler: () => void, ms: number) => { clear: () => void }
 }
 
 export type GithubAdapter = {
@@ -68,6 +76,7 @@ const consoleLogger: GithubAdapterLogger = {
 }
 
 const DEFAULT_WEBHOOK_REGISTRATION_DELAY_MS = 2_000
+const DEFAULT_TOKEN_REFRESH_INTERVAL_MS = 30 * 60 * 1000
 
 export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapter {
   const logger = options.logger ?? consoleLogger
@@ -83,6 +92,7 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
   let selfLogin: string | null = null
   let started = false
   let managedHooks: ReadonlyArray<{ repo: string; hookId: number }> = []
+  let tokenRefreshTimer: { clear: () => void } | null = null
   const workspaceByChat = new Map<string, string>()
 
   const rememberWorkspace = (workspace: string, chat: string): void => {
@@ -168,6 +178,24 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
       // automatically when within 5 minutes of expiry.
       process.env.GH_TOKEN = await auth.token()
       started = true
+      // Keep GH_TOKEN warm even when the adapter is only receiving inbound
+      // webhooks and not making outbound API calls. This prevents `gh` CLI
+      // calls from the agent from failing with 401 after the token expires.
+      const tokenRefreshIntervalMs = options.tokenRefreshIntervalMs ?? DEFAULT_TOKEN_REFRESH_INTERVAL_MS
+      if (tokenRefreshIntervalMs > 0) {
+        const refresh = () => {
+          tokenFn().catch((err) => {
+            logger.error(`[github] periodic token refresh failed: ${err instanceof Error ? err.message : String(err)}`)
+          })
+        }
+        const setIntervalFn =
+          options.setInterval ??
+          ((handler: () => void, ms: number) => {
+            const timer = setInterval(handler, ms)
+            return { clear: () => clearInterval(timer) }
+          })
+        tokenRefreshTimer = setIntervalFn(refresh, tokenRefreshIntervalMs)
+      }
       logger.info(`[github] webhook listening on port ${options.configRef().webhookPort} as @${self.login}`)
       // Best-effort: App-only preflight that compares the installation's granted
       // permissions against the configured eventAllowlist and warns about gaps.
@@ -241,6 +269,10 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
         logDeregistrationOutcome(logger, deregistration)
         managedHooks = []
       }
+      if (tokenRefreshTimer !== null) {
+        tokenRefreshTimer.clear()
+        tokenRefreshTimer = null
+      }
       await auth.dispose()
       delete process.env.GH_TOKEN
       server = null

package/src/channels/router.ts

@@ -498,13 +498,15 @@ export type ChannelRouter = {
   // turn cannot drop a future legitimate reply.
   //
   // Returns:
-  //   - 'recorded'      — the live session was found and the skip was stamped
-  //   - 'send-already-happened' — a tool-source channel send already landed
-  //                       in this turn; the skip is refused (symmetric with
-  //                       the send-after-skip lock in `send()`) so the model
-  //                       cannot land a reply AND claim silence. The flag is
-  //                       NOT stamped, so the turn proceeds as a normal
-  //                       reply turn.
+  //   - 'recorded'      — silence-first: no send had landed this turn, so the
+  //                       skip was stamped and later tool-source sends are
+  //                       locked out via the send-after-skip guard in `send()`
+  //   - 'recorded-after-send' — reply-first: a tool-source channel send already
+  //                       landed this turn and the agent is now going quiet for
+  //                       the rest of it (the normal ack-then-wait pattern). The
+  //                       delivered reply stands; this skip posts nothing and is
+  //                       a terminal no-op. NOT stamped as a skipped turn (a
+  //                       reply already landed), and logged inline by the impl.
   //   - 'no-live-session' — no matching channel session (e.g. tool fired
   //                         outside a channel origin); the tool should
   //                         still log the reason but cannot suppress.
@@ -513,7 +515,7 @@ export type ChannelRouter = {
     reason: string
   }) =>
     | { kind: 'recorded'; keyId: string }
-    | { kind: 'send-already-happened'; keyId: string }
+    | { kind: 'recorded-after-send'; keyId: string }
     | { kind: 'no-live-session' }
   stop: () => Promise<void>
   liveCount: () => number
@@ -2254,13 +2256,22 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     reason: string
   }):
     | { kind: 'recorded'; keyId: string }
-    | { kind: 'send-already-happened'; keyId: string }
+    | { kind: 'recorded-after-send'; keyId: string }
     | { kind: 'no-live-session' } => {
     for (const live of liveSessions.values()) {
       if (live.destroyed) continue
       if (live.sessionId !== args.parentSessionId) continue
       if (live.successfulChannelSends > live.successfulSendsAtTurnStart) {
-        return { kind: 'send-already-happened', keyId: live.keyId }
+        // Reply-first skip ("acked, now going quiet"): accept as a terminal
+        // no-op, never stamp `skippedTurn`. The delivered reply stands and must
+        // not be suppressed, so stamping (which `validateChannelTurn` reads to
+        // drop the turn) would be wrong; the send-after-skip lock only needs to
+        // arm on the silence-first path. Rejecting this instead deadlocks the
+        // agentic loop: denied a clean silent exit the model re-sends, gets
+        // re-denied, and repeats until the per-turn send cap trips. Logged here
+        // since `validateChannelTurn` won't see a `skippedTurn` for it.
+        logger.info(`[channels] ${live.keyId} skip_after_send reason=${JSON.stringify(args.reason)}`)
+        return { kind: 'recorded-after-send', keyId: live.keyId }
       }
       live.skippedTurn = { turnSeq: live.turnSeq, reason: args.reason }
       return { kind: 'recorded', keyId: live.keyId }

package/src/doctor/channel-checks.ts

@@ -0,0 +1,328 @@
+import { join } from 'node:path'
+
+import { type AdapterId, type ChannelsConfig } from '@/channels'
+import { loadConfigSync, validateConfig } from '@/config'
+import { readEnvFile } from '@/init'
+import { SecretsBackend } from '@/secrets'
+import { channelFieldDefaultEnv } from '@/secrets/defaults'
+
+import type { CheckContext, CheckResult, DoctorCheck } from './types'
+
+// Host-stage channel adapter health checks. These cannot talk to Slack /
+// Discord / Telegram / KakaoTalk / GitHub APIs — that work belongs to the
+// container-stage `start()` preflight on each adapter (see
+// `src/channels/manager.ts` and individual adapters). What doctor CAN do
+// from the host is verify that the credentials the container will look for
+// are actually present and resolvable, so the operator gets a clear,
+// before-`typeclaw start` signal instead of a silent skip in the runtime
+// logs.
+//
+// Every check is gated on `ctx.hasAgentFolder` (typeclaw.json is required to
+// read the channels config) and additionally on the adapter being declared
+// AND enabled in typeclaw.json. A missing or `enabled: false` adapter
+// reports `skipped` so the operator can see the check ran without it
+// turning into noise on minimal setups.
+
+export function buildChannelChecks(): DoctorCheck[] {
+  return [
+    slackBotCredentials(),
+    discordBotCredentials(),
+    telegramBotCredentials(),
+    kakaotalkCredentials(),
+    githubCredentials(),
+    githubWebhookDelivery(),
+  ]
+}
+
+function slackBotCredentials(): DoctorCheck {
+  return {
+    name: 'channel.slack-bot.credentials',
+    category: 'channels',
+    description: 'slack-bot adapter has SLACK_BOT_TOKEN and SLACK_APP_TOKEN',
+    applies: (ctx) => ctx.hasAgentFolder,
+    run: (ctx) => runTokenAdapterCheck(ctx, 'slack-bot', ['SLACK_BOT_TOKEN', 'SLACK_APP_TOKEN']),
+  }
+}
+
+function discordBotCredentials(): DoctorCheck {
+  return {
+    name: 'channel.discord-bot.credentials',
+    category: 'channels',
+    description: 'discord-bot adapter has DISCORD_BOT_TOKEN',
+    applies: (ctx) => ctx.hasAgentFolder,
+    run: (ctx) => runTokenAdapterCheck(ctx, 'discord-bot', ['DISCORD_BOT_TOKEN']),
+  }
+}
+
+function telegramBotCredentials(): DoctorCheck {
+  return {
+    name: 'channel.telegram-bot.credentials',
+    category: 'channels',
+    description: 'telegram-bot adapter has TELEGRAM_BOT_TOKEN',
+    applies: (ctx) => ctx.hasAgentFolder,
+    run: (ctx) => runTokenAdapterCheck(ctx, 'telegram-bot', ['TELEGRAM_BOT_TOKEN']),
+  }
+}
+
+function kakaotalkCredentials(): DoctorCheck {
+  return {
+    name: 'channel.kakaotalk.credentials',
+    category: 'channels',
+    description: 'kakaotalk adapter has at least one account in secrets.json',
+    applies: (ctx) => ctx.hasAgentFolder,
+    async run(ctx) {
+      const channels = readDeclaredChannels(ctx)
+      if (channels === null) return configInvalidResult()
+      if (!isAdapterActive(channels, 'kakaotalk')) {
+        return { status: 'skipped', message: 'kakaotalk not configured' }
+      }
+      const block = readChannelsSecrets(ctx)?.kakaotalk
+      const accountCount = block?.accounts ? Object.keys(block.accounts).length : 0
+      if (accountCount === 0) {
+        return {
+          status: 'warning',
+          message: 'kakaotalk has no accounts in secrets.json',
+          details: ['Adapter will start but fail authentication and stay disconnected.'],
+          fix: { description: 'Run `typeclaw channel add kakaotalk` to log in an account.' },
+        }
+      }
+      return { status: 'ok', message: `kakaotalk has ${accountCount} account(s)` }
+    },
+  }
+}
+
+function githubCredentials(): DoctorCheck {
+  return {
+    name: 'channel.github.credentials',
+    category: 'channels',
+    description: 'github adapter has auth and webhookSecret in secrets.json',
+    applies: (ctx) => ctx.hasAgentFolder,
+    async run(ctx) {
+      const channels = readDeclaredChannels(ctx)
+      if (channels === null) return configInvalidResult()
+      if (!isAdapterActive(channels, 'github')) {
+        return { status: 'skipped', message: 'github not configured' }
+      }
+      const block = readChannelsSecrets(ctx)?.github
+      if (!block) {
+        return {
+          status: 'error',
+          message: 'github secrets missing from secrets.json',
+          details: ['Adapter requires both `auth` and `webhookSecret`.'],
+          fix: { description: 'Run `typeclaw channel set github` to configure GitHub auth.' },
+        }
+      }
+      const dotEnv = safeReadEnvFile(ctx.cwd)
+      const details: string[] = []
+      const webhookSecret = resolveSecretHostStage(block.webhookSecret, dotEnv)
+      if (webhookSecret === undefined || webhookSecret === '') {
+        details.push('webhookSecret is unset (resolves to empty string)')
+      }
+      if (block.auth.type === 'pat') {
+        const token = resolveSecretHostStage(block.auth.token, dotEnv)
+        if (token === undefined || token === '') {
+          details.push('auth.token (PAT) is unset (resolves to empty string)')
+        }
+      } else {
+        const key = resolveSecretHostStage(block.auth.privateKey, dotEnv)
+        if (key === undefined || key === '') {
+          details.push('auth.privateKey (App) is unset (resolves to empty string)')
+        }
+      }
+      if (details.length > 0) {
+        return {
+          status: 'error',
+          message: 'github credentials present but some fields resolve to empty',
+          details,
+          fix: { description: 'Run `typeclaw channel set github` to repopulate the missing fields.' },
+        }
+      }
+      return {
+        status: 'ok',
+        message: `github ${block.auth.type === 'pat' ? 'PAT' : 'App'} auth + webhookSecret resolved`,
+      }
+    },
+  }
+}
+
+function githubWebhookDelivery(): DoctorCheck {
+  return {
+    name: 'channel.github.webhook-delivery',
+    category: 'channels',
+    description: 'github webhook delivery has a public URL (webhookUrl or tunnel)',
+    applies: (ctx) => ctx.hasAgentFolder,
+    async run(ctx) {
+      const cfg = safeLoadConfig(ctx)
+      if (cfg === null) return configInvalidResult()
+      const github = cfg.channels.github
+      if (github === undefined || github.enabled === false) {
+        return { status: 'skipped', message: 'github not configured' }
+      }
+      const hasWebhookUrl = typeof github.webhookUrl === 'string' && github.webhookUrl.length > 0
+      const hasTunnel = cfg.tunnels.some((t) => t.for.kind === 'channel' && t.for.name === 'github')
+      if (hasWebhookUrl || hasTunnel) {
+        const source = hasWebhookUrl ? 'webhookUrl' : 'tunnel'
+        return { status: 'ok', message: `github webhook delivery configured via ${source}` }
+      }
+      if (github.repos.length === 0) {
+        return {
+          status: 'info',
+          message: 'github has no webhookUrl or tunnel, and no repos to register',
+          details: ['Webhooks will not be auto-registered until either webhookUrl or a tunnel binding is set.'],
+        }
+      }
+      return {
+        status: 'warning',
+        message: `github lists ${github.repos.length} repo(s) but has no public URL to deliver webhooks to`,
+        details: [
+          'Either set `channels.github.webhookUrl` in typeclaw.json,',
+          'or add a `tunnels[]` entry with `for: { kind: "channel", name: "github" }`.',
+        ],
+        fix: {
+          description: 'Configure webhookUrl or a github tunnel; see `typeclaw tunnel add` for managed tunnels.',
+        },
+      }
+    },
+  }
+}
+
+async function runTokenAdapterCheck(
+  ctx: CheckContext,
+  adapter: Extract<AdapterId, 'slack-bot' | 'discord-bot' | 'telegram-bot'>,
+  envNames: readonly string[],
+): Promise<CheckResult> {
+  const channels = readDeclaredChannels(ctx)
+  if (channels === null) return configInvalidResult()
+  if (!isAdapterActive(channels, adapter)) {
+    return { status: 'skipped', message: `${adapter} not configured` }
+  }
+  const dotEnv = safeReadEnvFile(ctx.cwd)
+  const channelSecrets = readChannelsSecrets(ctx)
+  const adapterSecrets = (channelSecrets?.[adapter] ?? {}) as Record<string, unknown>
+  const missing: string[] = []
+  for (const envName of envNames) {
+    if (hasTokenForEnv(adapter, envName, dotEnv, adapterSecrets)) continue
+    missing.push(envName)
+  }
+  if (missing.length > 0) {
+    return {
+      status: 'warning',
+      message: `${adapter} missing credentials: ${missing.join(', ')}`,
+      details: [
+        'Adapter will be skipped at start until credentials are present.',
+        'Resolution order: process.env wins over .env file value over secrets.json value.',
+      ],
+      fix: { description: 'Run `typeclaw channel set ' + adapter + '`, or add the env vars to .env.' },
+    }
+  }
+  return { status: 'ok', message: `${adapter} credentials present` }
+}
+
+// hasTokenForEnv resolves a single env-var-style credential the same way the
+// runtime does, plus one host-stage-specific source: process.env > .env file >
+// secrets.json. Empty strings count as unset, matching `src/secrets/resolve.ts`.
+function hasTokenForEnv(
+  adapter: AdapterId,
+  envName: string,
+  dotEnv: Map<string, string>,
+  adapterSecrets: Record<string, unknown>,
+): boolean {
+  const fromProcess = process.env[envName]
+  if (fromProcess !== undefined && fromProcess !== '') return true
+  const fromDotEnv = dotEnv.get(envName)
+  if (fromDotEnv !== undefined && fromDotEnv !== '') return true
+  const fieldName = fieldNameForEnv(adapter, envName)
+  if (fieldName === undefined) return false
+  const secret = adapterSecrets[fieldName]
+  if (!isSecretShape(secret)) return false
+  const resolved = resolveSecretHostStage(secret, dotEnv, envName)
+  return resolved !== undefined && resolved !== ''
+}
+
+// resolveSecretHostStage mirrors `resolveSecret` precedence but adds a .env
+// lookup before falling through to process.env. Doctor runs on the host and
+// never executes the container, so .env values are not in process.env. For
+// Secrets bound to a custom env var (e.g. `{ env: 'MY_TOKEN' }`), the runtime
+// would resolve via process.env.MY_TOKEN inside the container — on the host
+// that yields undefined even when the value is sitting in .env. So look up
+// the custom env name in the parsed .env map first.
+function resolveSecretHostStage(
+  secret: { value?: string; env?: string },
+  dotEnv: Map<string, string>,
+  defaultEnv?: string,
+): string | undefined {
+  const envName = secret.env ?? defaultEnv
+  if (envName !== undefined) {
+    const fromProcess = process.env[envName]
+    if (fromProcess !== undefined && fromProcess !== '') return fromProcess
+    const fromDotEnv = dotEnv.get(envName)
+    if (fromDotEnv !== undefined && fromDotEnv !== '') return fromDotEnv
+  }
+  return secret.value
+}
+
+function fieldNameForEnv(adapter: AdapterId, envName: string): string | undefined {
+  // Reverse-lookup using channelFieldDefaultEnv: scan the small set of known
+  // fields per adapter for the one whose default env matches. The set is
+  // tiny (1-2 entries) so the linear scan is fine.
+  const candidates: Record<string, readonly string[]> = {
+    'slack-bot': ['botToken', 'appToken'],
+    'discord-bot': ['token'],
+    'telegram-bot': ['token'],
+  }
+  const fields = candidates[adapter]
+  if (!fields) return undefined
+  for (const field of fields) {
+    if (channelFieldDefaultEnv(adapter, field) === envName) return field
+  }
+  return undefined
+}
+
+function isSecretShape(value: unknown): value is { value?: string; env?: string } {
+  if (typeof value !== 'object' || value === null) return false
+  const obj = value as Record<string, unknown>
+  const hasValue = typeof obj['value'] === 'string'
+  const hasEnv = typeof obj['env'] === 'string'
+  return hasValue || hasEnv
+}
+
+function readDeclaredChannels(ctx: CheckContext): ChannelsConfig | null {
+  const cfg = safeLoadConfig(ctx)
+  return cfg?.channels ?? null
+}
+
+function safeLoadConfig(ctx: CheckContext): ReturnType<typeof loadConfigSync> | null {
+  const result = validateConfig(ctx.cwd)
+  if (!result.ok) return null
+  try {
+    return loadConfigSync(ctx.cwd)
+  } catch {
+    return null
+  }
+}
+
+function safeReadEnvFile(cwd: string): Map<string, string> {
+  try {
+    return readEnvFile(cwd)
+  } catch {
+    return new Map()
+  }
+}
+
+function readChannelsSecrets(ctx: CheckContext): ReturnType<SecretsBackend['tryReadChannelsSync']> {
+  try {
+    return new SecretsBackend(join(ctx.cwd, 'secrets.json')).tryReadChannelsSync()
+  } catch {
+    return null
+  }
+}
+
+function isAdapterActive(channels: ChannelsConfig, adapter: AdapterId): boolean {
+  const slot = channels[adapter]
+  if (slot === undefined) return false
+  return slot.enabled !== false
+}
+
+function configInvalidResult(): CheckResult {
+  return { status: 'skipped', message: 'config invalid (covered by config.valid)' }
+}

package/src/doctor/checks.ts

@@ -21,6 +21,7 @@ import { buildDockerfile, DOCKERFILE } from '@/init/dockerfile'
 import { detectMissingDeps } from '@/init/ensure-deps'
 import { buildGitignore, GITIGNORE_FILE } from '@/init/gitignore'
 
+import { buildChannelChecks } from './channel-checks'
 import type { DoctorCheck } from './types'
 
 export function buildStaticChecks(opts: { dockerExec?: DockerExec } = {}): DoctorCheck[] {
@@ -40,6 +41,7 @@ export function buildStaticChecks(opts: { dockerExec?: DockerExec } = {}): Docto
     hostdRegistration(),
     containerState(dockerExec),
     containerHostPort(),
+    ...buildChannelChecks(),
   ]
 }
 

package/src/init/dockerfile.ts

@@ -1,4 +1,9 @@
 import type { DockerfileConfig, DockerfileFeatureToggle } from '@/config/config'
+import {
+  CLAUDE_CREDENTIALS_FILE_NAME,
+  CLAUDE_CREDENTIALS_RELATIVE_PATH,
+  CLAUDE_DEFAULT_CONFIG_DIR_NAME,
+} from '@/secrets/export-claude-credentials-file'
 
 import { GHCR_BASE_IMAGE_REPO } from './cli-version'
 
@@ -283,13 +288,19 @@ set -eu
 #                           no inbound exposure anyway.
 # link_persistent_home_files symlinks credential files that tools write
 # to $HOME into a bind-mounted location so they survive container
-# restarts. The canonical case is Codex CLI's ~/.codex/auth.json: codex
-# rewrites the file in place to rotate OAuth tokens, and the official
-# CI/CD guidance is to persist auth.json so refresh-token state
-# compounds across runs. The container's $HOME (/root by default) lives
-# on Docker's writable overlay and is wiped on every \`stop\`+\`start\`
-# cycle, so without this symlink the operator would have to re-paste
-# auth.json after every restart.
+# restarts. The container's $HOME (/root by default) lives on Docker's
+# writable overlay and is wiped on every \`stop\`+\`start\` cycle, so
+# without this symlink the operator would have to re-paste credentials
+# after every restart.
+#
+# Two files are linked today, both following the same contract:
+#   - ~/.codex/auth.json — Codex CLI rotates OAuth tokens in place by
+#     rewriting auth.json with refreshed credentials.
+#   - $CLAUDE_CONFIG_DIR/.credentials.json, or ~/.claude/.credentials.json
+#     by default — Claude Code rotates OAuth tokens in place by rewriting
+#     .credentials.json on every successful refresh (anthropics/claude-code
+#     #53063). Linux/Windows path; macOS uses the Keychain entry "Claude
+#     Code-credentials" with the same JSON shape.
 #
 # The persist root lives under /agent/.typeclaw/home/ (bind-mounted
 # from the agent folder via the -v <cwd>:/agent flag in start.ts).
@@ -329,6 +340,12 @@ link_persistent_home_files() {
   persist_root="\${TYPECLAW_PERSIST_HOME_ROOT:-/agent/.typeclaw/home}"
   mkdir -p "$persist_root/.codex" "$HOME/.codex"
   ln -sfn "$persist_root/.codex/auth.json" "$HOME/.codex/auth.json"
+  claude_config_dir="\${CLAUDE_CONFIG_DIR:-}"
+  if [ -z "$claude_config_dir" ]; then
+    claude_config_dir="$HOME/${CLAUDE_DEFAULT_CONFIG_DIR_NAME}"
+  fi
+  mkdir -p "$persist_root/${CLAUDE_DEFAULT_CONFIG_DIR_NAME}" "$claude_config_dir"
+  ln -sfn "$persist_root/${CLAUDE_CREDENTIALS_RELATIVE_PATH}" "$claude_config_dir/${CLAUDE_CREDENTIALS_FILE_NAME}"
 }
 
 start_xvfb() {

package/src/run/index.ts

@@ -43,7 +43,11 @@ import type { CronHandlerContext } from '@/plugin/types'
 import { createContainerBroker, publishForwardResult } from '@/portbroker'
 import { ReloadRegistry } from '@/reload'
 import { createClaimController } from '@/role-claim'
-import { exportCodexAuthFileForAgent, hydrateChannelEnvFromSecrets } from '@/secrets'
+import {
+  exportClaudeCredentialsFileForAgent,
+  exportCodexAuthFileForAgent,
+  hydrateChannelEnvFromSecrets,
+} from '@/secrets'
 import { createServer, type Server } from '@/server'
 import {
   createCommandRunner,
@@ -194,6 +198,19 @@ export async function startAgent({
     log: (message) => console.warn(message),
   })
 
+  // Same shape as the codex exporter above, gated on `docker.file.claudeCode`
+  // and `secrets.json#providers.anthropic`. Writes ~/.claude/.credentials.json
+  // so the Claude Code CLI in the container can run without the user pasting
+  // a CLAUDE_CODE_OAUTH_TOKEN. See src/secrets/export-claude-credentials-
+  // file.ts for the newer-wins compare that prevents clobbering Claude
+  // Code's in-place token refreshes, and the read-merge-write that preserves
+  // any mcpOAuth state in the file.
+  exportClaudeCredentialsFileForAgent({
+    agentDir: cwd,
+    claudeCodeEnabled: cwdConfig.docker.file.claudeCode,
+    log: (message) => console.warn(message),
+  })
+
   const claimController = createClaimController({
     cwd,
     permissions: pluginsLoaded.permissions,

package/src/secrets/claude-credentials-json.ts

@@ -0,0 +1,129 @@
+import type { ProviderCredential } from './schema'
+
+// Emit the on-disk shape Claude Code consumes at ~/.claude/.credentials.json
+// (Linux/Windows; macOS keeps this same JSON inside the Keychain entry
+// "Claude Code-credentials"). The single required top-level key is
+// `claudeAiOauth`. Field names use camelCase, not snake_case — diverging
+// from Codex CLI's `tokens.access_token` shape but matching every
+// third-party Claude Code integration we surveyed (ATLAS_OS, OmniRoute,
+// jcode, paperclip, opencode-claude-auth).
+//
+// `expiresAt` is MILLISECONDS since epoch, not seconds and not ISO. The
+// CLI carries no top-level expiry field outside `claudeAiOauth` — token
+// expiry is recorded both as `expiresAt` here and embedded in the JWT
+// `exp` claim of `accessToken`. The runtime exporter (export-claude-
+// credentials-file.ts) uses the JWT exp for its newer-wins compare,
+// mirroring the Codex CLI exporter's approach, because `expiresAt` is
+// the field Claude Code itself rewrites on in-place refresh.
+//
+// `mcpOAuth` (MCP server OAuth state) may coexist alongside
+// `claudeAiOauth` in the same file. This emitter accepts an optional
+// `preserveMcpOAuth` block so callers that read-merge-write the file
+// don't drop unrelated state. Codex CLI's file is fully owned by the
+// OAuth credential and has no equivalent; this is the one extra
+// complication versus emitCodexAuthJson.
+export type ClaudeAiOauthBlock = {
+  accessToken: string
+  refreshToken: string
+  expiresAt: number
+  scopes?: string[]
+  subscriptionType?: string
+}
+
+export type EmitClaudeCredentialsJsonOptions = {
+  preserveMcpOAuth?: unknown
+}
+
+export function emitClaudeCredentialsJson(
+  credential: ProviderCredential,
+  options: EmitClaudeCredentialsJsonOptions = {},
+): string {
+  if (credential.type !== 'oauth') {
+    throw new Error('emitClaudeCredentialsJson only accepts oauth-typed credentials')
+  }
+  const fields = credential as ProviderCredential & {
+    access?: unknown
+    refresh?: unknown
+    expires?: unknown
+    scopes?: unknown
+    subscriptionType?: unknown
+  }
+  const access = fields.access
+  const refresh = fields.refresh
+  if (typeof access !== 'string' || access.length === 0) {
+    throw new Error('credential is missing a non-empty `access` field')
+  }
+  if (typeof refresh !== 'string' || refresh.length === 0) {
+    throw new Error('credential is missing a non-empty `refresh` field')
+  }
+
+  // Resolution order for `expiresAt`:
+  //   1. `expires` on the credential (pi-ai writes absolute ms epoch here).
+  //   2. JWT `exp` claim decoded from `access`.
+  //   3. 0 — Claude Code treats a missing/zero expiry as "expired" and
+  //      triggers an immediate refresh on next use, which is the safe
+  //      fallback when neither source is available.
+  const expiresAt = readExpiryMs(fields, access)
+
+  const claudeAiOauth: ClaudeAiOauthBlock = {
+    accessToken: access,
+    refreshToken: refresh,
+    expiresAt,
+  }
+  if (Array.isArray(fields.scopes) && fields.scopes.every((s): s is string => typeof s === 'string')) {
+    claudeAiOauth.scopes = fields.scopes
+  }
+  if (typeof fields.subscriptionType === 'string' && fields.subscriptionType.length > 0) {
+    claudeAiOauth.subscriptionType = fields.subscriptionType
+  }
+
+  // Read-merge-write: preserve any existing `mcpOAuth` block the caller
+  // supplied. The emitter doesn't read disk itself (that's the exporter's
+  // job); the caller passes whatever it found at the existing file path.
+  const out: Record<string, unknown> = { claudeAiOauth }
+  if (options.preserveMcpOAuth !== undefined) {
+    out['mcpOAuth'] = options.preserveMcpOAuth
+  }
+  return `${JSON.stringify(out, null, 2)}\n`
+}
+
+// Extracts the JWT `exp` claim (seconds since epoch) and converts to ms.
+// Used by the runtime exporter's newer-wins compare and by emit's
+// `expiresAt` fallback. Returns null on any decode failure; the caller
+// treats that as "unknown freshness". Logic mirrors
+// decodeCodexAccessTokenExpiryMs verbatim — Claude Code OAuth access
+// tokens are standard JWTs with the same base64url-encoded payload
+// shape Codex uses.
+export function decodeClaudeAccessTokenExpiryMs(accessToken: string): number | null {
+  const parts = accessToken.split('.')
+  if (parts.length !== 3) return null
+  const middle = parts[1] ?? ''
+  if (middle === '') return null
+  const normalized = middle.replace(/-/g, '+').replace(/_/g, '/')
+  const padded = normalized + '='.repeat((4 - (normalized.length % 4)) % 4)
+  let payload: Record<string, unknown>
+  try {
+    const decoded = typeof atob === 'function' ? atob(padded) : Buffer.from(padded, 'base64').toString('utf8')
+    const parsed: unknown = JSON.parse(decoded)
+    if (!isPlainObject(parsed)) return null
+    payload = parsed
+  } catch {
+    return null
+  }
+  const exp = payload['exp']
+  if (typeof exp !== 'number' || !Number.isFinite(exp)) return null
+  return Math.floor(exp * 1000)
+}
+
+function readExpiryMs(fields: { expires?: unknown }, accessToken: string): number {
+  if (typeof fields.expires === 'number' && Number.isFinite(fields.expires)) {
+    return fields.expires
+  }
+  const fromJwt = decodeClaudeAccessTokenExpiryMs(accessToken)
+  if (fromJwt !== null) return fromJwt
+  return 0
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}

package/src/secrets/export-claude-credentials-file.ts

@@ -0,0 +1,279 @@
+import {
+  chmodSync,
+  mkdirSync,
+  readFileSync,
+  readlinkSync,
+  renameSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, isAbsolute, join, resolve } from 'node:path'
+
+import { decodeClaudeAccessTokenExpiryMs, emitClaudeCredentialsJson } from './claude-credentials-json'
+import type { ProviderCredential, Providers } from './schema'
+import { SecretsBackend } from './storage'
+
+const FILE_MODE = 0o600
+const DIR_MODE = 0o700
+export const CLAUDE_CREDENTIALS_FILE_NAME = '.credentials.json'
+export const CLAUDE_DEFAULT_CONFIG_DIR_NAME = '.claude'
+export const CLAUDE_CREDENTIALS_RELATIVE_PATH = join(CLAUDE_DEFAULT_CONFIG_DIR_NAME, CLAUDE_CREDENTIALS_FILE_NAME)
+
+export type ExportClaudeCredentialsFileResult =
+  | { action: 'skipped'; reason: SkipReason }
+  | { action: 'wrote'; path: string }
+  | { action: 'failed'; reason: string }
+
+export type SkipReason =
+  | 'claude-code-disabled'
+  | 'no-anthropic-credential'
+  | 'credential-not-oauth'
+  | 'on-disk-is-fresher'
+
+export type ExportClaudeCredentialsFileOptions = {
+  claudeCodeEnabled: boolean
+  providers: Providers
+  homeDir?: string
+  configDir?: string
+  now?: () => number
+  log?: (message: string) => void
+}
+
+// Writes typeclaw's anthropic OAuth credential to
+// $CLAUDE_CONFIG_DIR/.credentials.json (or $HOME/.claude/.credentials.json
+// by default) when it's safe to do so. The Dockerfile entrypoint shim
+// symlinks the same resolved credentials path to
+// /agent/.typeclaw/home/.claude/.credentials.json on every boot, so the
+// write follows the symlink and lands on the persistent host-side path —
+// same contract as exportCodexAuthFile.
+//
+// Three guards, cheapest first. The first two return without ever touching
+// the filesystem, which keeps the 90% case (users who don't enable
+// Claude Code) at zero overhead on every container start.
+export function exportClaudeCredentialsFileIfApplicable(
+  options: ExportClaudeCredentialsFileOptions,
+): ExportClaudeCredentialsFileResult {
+  if (!options.claudeCodeEnabled) return { action: 'skipped', reason: 'claude-code-disabled' }
+
+  const credential = options.providers['anthropic']
+  if (credential === undefined) return { action: 'skipped', reason: 'no-anthropic-credential' }
+  if (credential.type !== 'oauth') return { action: 'skipped', reason: 'credential-not-oauth' }
+
+  const targetPath = resolveClaudeCredentialsPath({
+    ...(options.homeDir !== undefined ? { homeDir: options.homeDir } : {}),
+    ...(options.configDir !== undefined ? { configDir: options.configDir } : {}),
+  })
+
+  try {
+    const existing = readExisting(targetPath)
+    if (!shouldOverwrite(existing, credential, options.now ?? Date.now)) {
+      return { action: 'skipped', reason: 'on-disk-is-fresher' }
+    }
+    const mcpOAuthOpt = existing?.mcpOAuth !== undefined ? { preserveMcpOAuth: existing.mcpOAuth } : {}
+    const contents = emitClaudeCredentialsJson(credential, mcpOAuthOpt)
+    writeAtomic(targetPath, contents)
+    return { action: 'wrote', path: targetPath }
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err)
+    options.log?.(`exportClaudeCredentialsFile: ${reason}`)
+    return { action: 'failed', reason }
+  }
+}
+
+type ExistingFile = {
+  onDiskAccessToken: string | null
+  onDiskExpiresAt: number | null
+  mcpOAuth: unknown
+}
+
+// Read once, parse once. Returns null when the file is missing OR
+// unparseable. Returning null short-circuits both branches of the
+// overwrite decision (the no-disk-file recovery path) AND drops any
+// non-recoverable mcpOAuth state — but if the file is unparseable
+// there's nothing to recover anyway. When parsing succeeds, we hand
+// back the access token (for the newer-wins compare) and the raw
+// mcpOAuth block (for read-merge-write preservation).
+function readExisting(targetPath: string): ExistingFile | null {
+  let raw: string
+  try {
+    raw = readFileSync(targetPath, 'utf8')
+  } catch {
+    return null
+  }
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    return null
+  }
+  if (typeof parsed !== 'object' || parsed === null) return null
+  const obj = parsed as Record<string, unknown>
+  const claudeBlock = obj['claudeAiOauth']
+  let onDiskAccessToken: string | null = null
+  let onDiskExpiresAt: number | null = null
+  if (typeof claudeBlock === 'object' && claudeBlock !== null) {
+    const claudeObj = claudeBlock as Record<string, unknown>
+    const access = claudeObj['accessToken']
+    if (typeof access === 'string' && access.length > 0) onDiskAccessToken = access
+    const expiresAt = claudeObj['expiresAt']
+    if (typeof expiresAt === 'number' && Number.isFinite(expiresAt) && expiresAt > 0) {
+      onDiskExpiresAt = expiresAt
+    }
+  }
+  return { onDiskAccessToken, onDiskExpiresAt, mcpOAuth: obj['mcpOAuth'] }
+}
+
+// Newer-wins: skip the write unless typeclaw's stored credential is
+// strictly fresher than the on-disk expiry. Claude Code rotates tokens
+// in-place (issue #53063 in anthropics/claude-code confirms it rewrites
+// .credentials.json with a fresher accessToken/refreshToken/expiresAt
+// on every successful refresh), so on a restart the file may legitimately
+// be ahead of secrets.json. We must not clobber that.
+//
+// Ties skip: when expiries match there's nothing to gain from a write,
+// and avoiding the I/O keeps the steady state at zero churn.
+//
+// existing === null OR existing.onDiskAccessToken === null OR expiry
+// undecodable from both expiresAt and JWT → return true. That's the "we
+// have a valid credential, the file is unusable, replace it" recovery case.
+function shouldOverwrite(
+  existing: ExistingFile | null,
+  credential: ProviderCredential & { expires?: unknown; access?: unknown },
+  now: () => number,
+): boolean {
+  if (existing === null) return true
+  if (existing.onDiskAccessToken === null) return true
+  const onDiskExpiry = readOnDiskExpiry(existing)
+  if (onDiskExpiry === null) return true
+  const credentialExpiry = readCredentialExpiry(credential, now)
+  return credentialExpiry > onDiskExpiry
+}
+
+function readOnDiskExpiry(existing: ExistingFile): number | null {
+  if (existing.onDiskExpiresAt !== null) return existing.onDiskExpiresAt
+  if (existing.onDiskAccessToken === null) return null
+  return decodeClaudeAccessTokenExpiryMs(existing.onDiskAccessToken)
+}
+
+// Resolution order for the credential's expiry:
+//   1. The `expires` field pi-ai writes (absolute ms epoch).
+//   2. The JWT `exp` claim decoded from `access`.
+//   3. Now — guarantees we still write on first boot when the credential
+//      lacks both, rather than silently skipping forever.
+function readCredentialExpiry(credential: { expires?: unknown; access?: unknown }, now: () => number): number {
+  if (typeof credential.expires === 'number' && Number.isFinite(credential.expires)) {
+    return credential.expires
+  }
+  if (typeof credential.access === 'string') {
+    const fromJwt = decodeClaudeAccessTokenExpiryMs(credential.access)
+    if (fromJwt !== null) return fromJwt
+  }
+  return now()
+}
+
+export function resolveClaudeCredentialsPath(options: { homeDir?: string; configDir?: string } = {}): string {
+  const configDir = resolveClaudeConfigDir(options.configDir)
+  if (configDir !== null) return join(configDir, CLAUDE_CREDENTIALS_FILE_NAME)
+  return join(options.homeDir ?? homedir(), CLAUDE_CREDENTIALS_RELATIVE_PATH)
+}
+
+function resolveClaudeConfigDir(configDir: string | undefined): string | null {
+  const raw = configDir ?? process.env['CLAUDE_CONFIG_DIR']
+  const trimmed = raw?.trim()
+  return trimmed === undefined || trimmed.length === 0 ? null : trimmed
+}
+
+// Atomic temp-then-rename, mirroring export-codex-auth-file.ts's
+// writeAtomic. The directory is created with 0700 and the file with 0600
+// because the credential carries a long-lived refresh token — leaking it
+// via lax permissions defeats the whole point. The 0600 chmod after
+// rename is belt-and-suspenders: writeFileSync's `mode` is applied at
+// create time, but umask can mask it down on some filesystems.
+//
+// Symlink preservation: the entrypoint shim will install
+// $HOME/.claude/.credentials.json as a symlink to
+// /agent/.typeclaw/home/.claude/.credentials.json. POSIX rename(2)
+// replaces the directory entry at the destination atomically and does
+// NOT follow symlinks, so a naive renameSync against the symlink path
+// would replace the symlink with a regular file, leaving the persistent
+// path empty and Claude Code's in-place token refresh silently lost on
+// every restart. Resolve the symlink target with readlinkSync and rename
+// against the real path so the symlink itself is preserved. The temp
+// file MUST live alongside the real target (same filesystem) because
+// renameSync across filesystems fails with EXDEV.
+function writeAtomic(targetPath: string, contents: string): void {
+  const realTarget = resolveSymlinkTarget(targetPath)
+  const dir = dirname(realTarget)
+  mkdirSync(dir, { recursive: true, mode: DIR_MODE })
+  const tmp = `${realTarget}.${process.pid}.${Date.now()}.tmp`
+  writeFileSync(tmp, contents, { encoding: 'utf8', mode: FILE_MODE })
+  try {
+    renameSync(tmp, realTarget)
+  } catch (err) {
+    try {
+      unlinkSync(tmp)
+    } catch {
+      // best-effort cleanup of the temp file when rename fails
+    }
+    throw err
+  }
+  try {
+    statSync(realTarget)
+    chmodSync(realTarget, FILE_MODE)
+  } catch {
+    // ignore — file vanished between rename and chmod is benign
+  }
+}
+
+// Returns the absolute path renameSync should target. When `path` is a
+// symlink (production: $HOME/.claude/.credentials.json -> /agent/...),
+// returns the resolved absolute target so we write through the link
+// instead of replacing it. Otherwise (tests, or first boot before the
+// shim installs the symlink), returns the path unchanged. readlinkSync
+// throws EINVAL when the path exists but isn't a symlink and ENOENT
+// when nothing is there — both cases fall through to the original path.
+function resolveSymlinkTarget(path: string): string {
+  let link: string
+  try {
+    link = readlinkSync(path)
+  } catch {
+    return path
+  }
+  return isAbsolute(link) ? link : resolve(dirname(path), link)
+}
+
+export type ExportClaudeCredentialsFileForAgentOptions = {
+  agentDir: string
+  claudeCodeEnabled: boolean
+  homeDir?: string
+  configDir?: string
+  log?: (message: string) => void
+}
+
+// Boot-time convenience wrapper for src/run/index.ts. Mirrors
+// exportCodexAuthFileForAgent: takes agentDir, never throws, returns a
+// result the caller can ignore. Secrets-file read failures are caught
+// and surfaced as 'failed' so the agent boot is never blocked by a
+// missing or malformed secrets.json.
+export function exportClaudeCredentialsFileForAgent(
+  options: ExportClaudeCredentialsFileForAgentOptions,
+): ExportClaudeCredentialsFileResult {
+  if (!options.claudeCodeEnabled) return { action: 'skipped', reason: 'claude-code-disabled' }
+  let providers: Providers
+  try {
+    providers = new SecretsBackend(join(options.agentDir, 'secrets.json')).tryReadProvidersSync()
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err)
+    options.log?.(`exportClaudeCredentialsFile: ${reason}`)
+    return { action: 'failed', reason }
+  }
+  return exportClaudeCredentialsFileIfApplicable({
+    claudeCodeEnabled: options.claudeCodeEnabled,
+    providers,
+    ...(options.homeDir !== undefined ? { homeDir: options.homeDir } : {}),
+    ...(options.configDir !== undefined ? { configDir: options.configDir } : {}),
+    ...(options.log !== undefined ? { log: options.log } : {}),
+  })
+}

package/src/secrets/index.ts

@@ -13,3 +13,13 @@ export {
   exportCodexAuthFileForAgent,
   exportCodexAuthFileIfApplicable,
 } from './export-codex-auth-file'
+
+export {
+  CLAUDE_CREDENTIALS_FILE_NAME,
+  CLAUDE_CREDENTIALS_RELATIVE_PATH,
+  CLAUDE_DEFAULT_CONFIG_DIR_NAME,
+  type ExportClaudeCredentialsFileResult,
+  exportClaudeCredentialsFileForAgent,
+  exportClaudeCredentialsFileIfApplicable,
+  resolveClaudeCredentialsPath,
+} from './export-claude-credentials-file'

package/src/skills/typeclaw-claude-code/SKILL.md

@@ -36,10 +36,11 @@ If `claude` is installed but no credential is set up, you have to broker the aut
 
 **Decision rule, top to bottom:**
 
-1. **Already authenticated?** Run `env | grep -E '^(ANTHROPIC_API_KEY|CLAUDE_CODE_OAUTH_TOKEN)='` — if either is present, skip auth entirely.
-2. **User has an Anthropic Console workspace** (API billing, no subscription) → API key path.
-3. **User has a Claude Pro/Max/Team/Enterprise subscription** → OAuth token path.
-4. **User is unsure** → ask which kind of Claude account they have. Both paths are now equally low-friction (one user action each — paste an API key, or run one command on their machine and paste the result), so the old "prefer API key when unsure" bias is gone. Pick by account shape, not by flow complexity.
+1. **`~/.claude/.credentials.json` already populated?** When typeclaw is configured with an `anthropic` OAuth credential (via `typeclaw provider add anthropic` or the init wizard) AND `docker.file.claudeCode: true`, the agent boot auto-emits the credential to `~/.claude/.credentials.json`. Check with `test -s ~/.claude/.credentials.json && jq -e '.claudeAiOauth.accessToken' ~/.claude/.credentials.json` — if it returns a string, Claude Code reads it on its own with no env var needed. Skip auth entirely.
+2. **Already authenticated via env?** Run `env | grep -E '^(ANTHROPIC_API_KEY|CLAUDE_CODE_OAUTH_TOKEN)='` — if either is present, skip auth entirely.
+3. **User has an Anthropic Console workspace** (API billing, no subscription) → API key path.
+4. **User has a Claude Pro/Max/Team/Enterprise subscription** → OAuth token path.
+5. **User is unsure** → ask which kind of Claude account they have. Both paths are now equally low-friction (one user action each — paste an API key, or run one command on their machine and paste the result), so the old "prefer API key when unsure" bias is gone. Pick by account shape, not by flow complexity.
 
 Both paths converge on the same final steps: read `.env`, merge one new `KEY=value` line, write back with the `nonWorkspaceWrite` guard ack, verify, and prompt the user to restart the container. Only the credential differs.
 

package/src/skills/typeclaw-claude-code/references/auth-flow.md

@@ -4,6 +4,41 @@ Deep dive for the auth paths. Read it when `SKILL.md`'s "First-time auth (intera
 
 The two paths are intentionally symmetric: in both, the user produces one string on their side, pastes it to you, you validate it, you do read-modify-write on `.env`, you offer a restart. Only the credential differs.
 
+## Path 0 — auto-export from typeclaw's anthropic OAuth credential
+
+If the user has already configured an `anthropic` OAuth credential in typeclaw (via `typeclaw provider add anthropic` or the init wizard) AND `docker.file.claudeCode: true`, the agent boot in `src/run/index.ts` auto-emits the credential to `~/.claude/.credentials.json` before `claude` ever runs. The destination matches Claude Code's documented Linux/Windows credential path; macOS uses the Keychain entry `"Claude Code-credentials"` with the same JSON shape, which typeclaw does not target (typeclaw runs Claude Code inside a Linux container).
+
+The on-disk shape:
+
+```json
+{
+  "claudeAiOauth": {
+    "accessToken": "sk-ant-oat01-...",
+    "refreshToken": "sk-ant-ort01-...",
+    "expiresAt": 1730000000000,
+    "scopes": ["user:inference", "user:profile", "user:sessions:claude_code", "user:mcp_servers"],
+    "subscriptionType": "max"
+  }
+}
+```
+
+Field names are camelCase and `expiresAt` is **milliseconds** since epoch (not seconds, not ISO).
+
+### Newer-wins on every boot
+
+The exporter compares typeclaw's stored `expires` against the JWT `exp` claim embedded in the on-disk `accessToken`. Strictly fresher wins; ties skip. Claude Code rotates tokens in place by rewriting `.credentials.json` on every successful refresh (anthropics/claude-code#53063), so on a restart the on-disk file may legitimately be ahead of `secrets.json` and must not be clobbered. The persistent-`$HOME` symlink the entrypoint shim installs (`~/.claude/.credentials.json` → `/agent/.typeclaw/home/.claude/.credentials.json`) is what makes the in-place refresh survive `stop`+`start`.
+
+If `.credentials.json` already carries an `mcpOAuth` block (MCP server OAuth state), the exporter preserves it on overwrite. Only the `claudeAiOauth` block is rewritten.
+
+### When Path 0 does NOT fire
+
+- `docker.file.claudeCode: false` — the install layer is off, no point exporting.
+- `secrets.json#providers.anthropic` is absent — nothing to export.
+- The stored credential is api-key shape — Claude Code reads API keys from `ANTHROPIC_API_KEY` env, not from `.credentials.json`. Fall back to Path A.
+- The on-disk JWT `exp` is already fresher — Claude Code refreshed in-place, skip.
+
+In each of those cases the agent boots without touching the file and Path A or Path B applies. The exporter is failure-tolerant: any error (read, write, fs guard) is logged via `console.warn` and the boot continues — Claude Code will then surface the missing credential on first invocation, which is the existing fallback.
+
 ## Path A — API key (recap)
 
 The API key path lives entirely in `SKILL.md` because there's nothing to elaborate. Summary: