typeclaw 0.12.0 → 0.13.0

package/src/cli/mount.ts

@@ -0,0 +1,157 @@
+import { defineCommand } from 'citty'
+
+import { addMount, listMounts, removeMount, type MountListEntry } from '@/config/mounts-mutation'
+import { findAgentDir, isInitialized } from '@/init'
+
+import { c, errorLine, successLine } from './ui'
+
+const listSub = defineCommand({
+  meta: {
+    name: 'list',
+    description: 'list host directories mounted into the agent container',
+  },
+  args: {
+    json: {
+      type: 'boolean',
+      description: 'emit mounts as JSON',
+      default: false,
+    },
+  },
+  async run({ args }) {
+    const cwd = ensureAgentDir()
+    const mounts = listMounts(cwd)
+    if (args.json) {
+      process.stdout.write(`${JSON.stringify({ mounts }, null, 2)}\n`)
+      return
+    }
+    process.stdout.write(`${formatMountList(mounts)}\n`)
+  },
+})
+
+const addSub = defineCommand({
+  meta: {
+    name: 'add',
+    description: 'add a host directory mount to typeclaw.json',
+  },
+  args: {
+    name: {
+      type: 'positional',
+      description: 'mount name; appears inside the container at /agent/mounts/<name>',
+      required: true,
+    },
+    path: {
+      type: 'positional',
+      description: 'host directory path to expose inside the container',
+      required: true,
+    },
+    'read-only': {
+      type: 'boolean',
+      description: 'mount read-only inside the container',
+      default: false,
+    },
+    description: {
+      type: 'string',
+      description: 'optional human-readable note stored in typeclaw.json',
+      required: false,
+    },
+  },
+  async run({ args }) {
+    const cwd = ensureAgentDir()
+    const result = addMount(cwd, args.name, args.path, {
+      readOnly: args['read-only'] === true,
+      ...(args.description !== undefined ? { description: args.description } : {}),
+    })
+    if (!result.ok) {
+      console.error(errorLine(result.reason))
+      process.exit(1)
+    }
+    process.stdout.write(`${successLine(`Added mount "${result.entry.name}".`)}\n`)
+    process.stdout.write(`${formatMountEntry(result.entry)}\n`)
+    process.stdout.write(`${c.dim('Apply change:')} ${c.cyan('typeclaw restart')}\n`)
+  },
+})
+
+const removeSub = defineCommand({
+  meta: {
+    name: 'remove',
+    description: 'remove a host directory mount from typeclaw.json',
+  },
+  args: {
+    name: {
+      type: 'positional',
+      description: 'mount name to remove',
+      required: true,
+    },
+  },
+  async run({ args }) {
+    const cwd = ensureAgentDir()
+    const result = removeMount(cwd, args.name)
+    if (!result.ok) {
+      console.error(errorLine(result.reason))
+      process.exit(1)
+    }
+    process.stdout.write(`${successLine(`Removed mount "${result.removed.name}".`)}\n`)
+    process.stdout.write(`${c.dim('Apply change:')} ${c.cyan('typeclaw restart')}\n`)
+  },
+})
+
+export const mountCommand = defineCommand({
+  meta: {
+    name: 'mount',
+    description: 'manage host directories mounted into the agent container',
+  },
+  subCommands: {
+    list: listSub,
+    add: addSub,
+    remove: removeSub,
+  },
+})
+
+export function formatMountList(mounts: readonly MountListEntry[]): string {
+  if (mounts.length === 0) return c.dim('No mounts configured.')
+
+  const nameWidth = Math.max(4, ...mounts.map((m) => m.name.length))
+  const modeWidth = 'MODE'.length
+  const statusWidth = Math.max(6, ...mounts.map((m) => m.status.length))
+  const lines: string[] = []
+  lines.push(
+    c.dim(
+      `${'NAME'.padEnd(nameWidth)}  ${'MODE'.padEnd(modeWidth)}  ${'STATUS'.padEnd(statusWidth)}  HOST PATH -> CONTAINER PATH`,
+    ),
+  )
+  for (const mount of mounts) {
+    const mode = mount.readOnly ? 'ro' : 'rw'
+    const statusText = mount.status.padEnd(statusWidth)
+    const status = mount.status === 'ok' ? c.green(statusText) : c.red(statusText)
+    lines.push(
+      `${mount.name.padEnd(nameWidth)}  ${mode.padEnd(modeWidth)}  ${status}  ${mount.resolvedPath} -> ${mount.targetPath}`,
+    )
+    if (mount.description !== undefined) {
+      lines.push(`${' '.repeat(nameWidth + modeWidth + statusWidth + 6)}${c.dim(mount.description)}`)
+    }
+    if (mount.statusReason !== undefined) {
+      lines.push(`${' '.repeat(nameWidth + modeWidth + statusWidth + 6)}${c.yellow(mount.statusReason)}`)
+    }
+  }
+  return lines.join('\n')
+}
+
+function formatMountEntry(mount: MountListEntry): string {
+  const mode = mount.readOnly ? 'read-only' : 'read-write'
+  const details = [
+    `${c.dim('host:')} ${mount.resolvedPath}`,
+    `${c.dim('container:')} ${mount.targetPath}`,
+    `${c.dim('mode:')} ${mode}`,
+  ]
+  if (mount.description !== undefined) details.push(`${c.dim('description:')} ${mount.description}`)
+  return details.join('\n')
+}
+
+function ensureAgentDir(): string {
+  const cwd = findAgentDir(process.cwd()) ?? process.cwd()
+  if (!isInitialized(cwd)) {
+    console.error(errorLine('TypeClaw config file not found. Run `typeclaw init` first, or cd into an agent folder.'))
+    process.exit(1)
+  }
+  return cwd
+}

package/src/cli/update.ts

@@ -9,7 +9,7 @@ const MANAGERS = ['auto', 'bun', 'npm', 'pnpm', 'yarn'] as const
 export const updateCommand = defineCommand({
   meta: {
     name: 'update',
-    description: 'update the globally installed typeclaw CLI',
+    description: 'update the installed typeclaw CLI (auto-detects global vs local)',
   },
   args: {
     manager: {
@@ -42,8 +42,9 @@ export const updateCommand = defineCommand({
       return
     }
 
-    process.stdout.write(`${c.cyan('Updating TypeClaw with:')} ${rendered}\n`)
-    const exitCode = await runUpdateCommand(plan.command)
+    const scopeLabel = plan.scope === 'global' ? 'global' : `local (${plan.cwd ?? '.'})`
+    process.stdout.write(`${c.cyan(`Updating TypeClaw [${scopeLabel}] with:`)} ${rendered}\n`)
+    const exitCode = await runUpdateCommand(plan.command, plan.cwd)
     if (exitCode !== 0) {
       console.error(errorLine(`Update command exited with code ${exitCode}.`))
       process.exit(exitCode)
@@ -58,7 +59,7 @@ function parseManager(value: string | undefined): UpdateManagerSelection | null
   return (MANAGERS as readonly string[]).includes(value) ? (value as UpdateManagerSelection) : null
 }
 
-async function runUpdateCommand(command: string[]): Promise<number> {
+async function runUpdateCommand(command: string[], cwd: string | undefined): Promise<number> {
   const bun = (globalThis as { Bun?: { spawn: typeof Bun.spawn } }).Bun
   if (!bun) {
     console.error(errorLine('bun runtime not available'))
@@ -67,6 +68,7 @@ async function runUpdateCommand(command: string[]): Promise<number> {
   try {
     const proc = bun.spawn({
       cmd: command,
+      cwd,
       stdin: 'inherit',
       stdout: 'inherit',
       stderr: 'inherit',

package/src/config/mounts-mutation.ts

@@ -0,0 +1,161 @@
+import { readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { commitSystemFileSync } from '@/git/system-commit'
+
+import {
+  configSchema,
+  expandMountPath,
+  loadConfigSyncOrDefaults,
+  mountSchema,
+  validateMount,
+  type Mount,
+} from './config'
+
+const CONFIG_FILE = 'typeclaw.json'
+const MOUNT_TARGET_PREFIX = '/agent/mounts'
+
+export type MountListEntry = Mount & {
+  resolvedPath: string
+  targetPath: string
+  status: 'ok' | 'error'
+  statusReason?: string
+}
+
+export type AddMountOptions = {
+  readOnly?: boolean
+  description?: string | undefined
+}
+
+export type AddMountResult = { ok: true; entry: MountListEntry } | { ok: false; reason: string }
+export type RemoveMountResult = { ok: true; removed: MountListEntry } | { ok: false; reason: string }
+
+export function listMounts(cwd: string): MountListEntry[] {
+  const mounts = loadConfigSyncOrDefaults(cwd).mounts
+  return mounts.map((mount) => toListEntry(mount, cwd))
+}
+
+export function addMount(cwd: string, name: string, path: string, options: AddMountOptions = {}): AddMountResult {
+  const mount = buildMount(name, path, options)
+  if (!mount.ok) return mount
+
+  const check = validateMount(mount.value, cwd)
+  if (!check.ok) return check
+
+  const parsed = readConfigRecord(cwd)
+  if (!parsed.ok) return parsed
+
+  const current = readMounts(parsed.value)
+  if (!current.ok) return current
+  if (current.value.some((m) => m.name === mount.value.name)) {
+    return {
+      ok: false,
+      reason: `Mount "${mount.value.name}" already exists. Remove it first with \`typeclaw mount remove ${mount.value.name}\`.`,
+    }
+  }
+
+  const next = { ...parsed.value, mounts: [...current.value, mount.value] }
+  const write = writeMounts(cwd, next, `mount: add ${mount.value.name}`)
+  if (!write.ok) return write
+  return { ok: true, entry: toListEntry(mount.value, cwd) }
+}
+
+export function removeMount(cwd: string, name: string): RemoveMountResult {
+  const trimmed = name.trim()
+  if (trimmed.length === 0) return { ok: false, reason: 'Mount name cannot be empty.' }
+
+  const parsed = readConfigRecord(cwd)
+  if (!parsed.ok) return parsed
+
+  const current = readMounts(parsed.value)
+  if (!current.ok) return current
+
+  const removed = current.value.find((m) => m.name === trimmed)
+  if (removed === undefined) return { ok: false, reason: `Mount "${trimmed}" not found in ${CONFIG_FILE}.` }
+
+  const next = { ...parsed.value, mounts: current.value.filter((m) => m.name !== trimmed) }
+  const write = writeMounts(cwd, next, `mount: remove ${trimmed}`)
+  if (!write.ok) return write
+  return { ok: true, removed: toListEntry(removed, cwd) }
+}
+
+function buildMount(
+  name: string,
+  path: string,
+  options: AddMountOptions,
+): { ok: true; value: Mount } | { ok: false; reason: string } {
+  const description = options.description?.trim()
+  const raw = {
+    name: name.trim(),
+    path,
+    readOnly: options.readOnly ?? false,
+    ...(description !== undefined && description.length > 0 ? { description } : {}),
+  }
+  const parsed = mountSchema.safeParse(raw)
+  if (!parsed.success) {
+    return { ok: false, reason: parsed.error.issues.map(formatIssue).join('; ') }
+  }
+  return { ok: true, value: parsed.data }
+}
+
+function readConfigRecord(cwd: string): { ok: true; value: Record<string, unknown> } | { ok: false; reason: string } {
+  try {
+    const raw = readFileSync(join(cwd, CONFIG_FILE), 'utf8')
+    const parsed = JSON.parse(raw) as unknown
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      return { ok: false, reason: `${CONFIG_FILE} must contain a JSON object.` }
+    }
+    return { ok: true, value: parsed as Record<string, unknown> }
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+      return { ok: false, reason: `${CONFIG_FILE} not found at ${cwd}. Run \`typeclaw init\` first.` }
+    }
+    return { ok: false, reason: `Failed to read ${CONFIG_FILE}: ${(error as Error).message}` }
+  }
+}
+
+function readMounts(record: Record<string, unknown>): { ok: true; value: Mount[] } | { ok: false; reason: string } {
+  const parsed = configSchema.safeParse(record)
+  if (!parsed.success) {
+    return { ok: false, reason: `${CONFIG_FILE} is invalid: ${parsed.error.issues.map(formatIssue).join('; ')}` }
+  }
+  return { ok: true, value: parsed.data.mounts }
+}
+
+function writeMounts(
+  cwd: string,
+  record: Record<string, unknown>,
+  commitMessage: string,
+): { ok: true } | { ok: false; reason: string } {
+  const parsed = configSchema.safeParse(record)
+  if (!parsed.success) {
+    return { ok: false, reason: `mounts block would be invalid: ${parsed.error.issues.map(formatIssue).join('; ')}` }
+  }
+
+  try {
+    writeFileSync(join(cwd, CONFIG_FILE), `${JSON.stringify(record, null, 2)}\n`)
+  } catch (error) {
+    return { ok: false, reason: `Failed to write ${CONFIG_FILE}: ${(error as Error).message}` }
+  }
+
+  commitSystemFileSync(cwd, CONFIG_FILE, commitMessage)
+  return { ok: true }
+}
+
+function toListEntry(mount: Mount, cwd: string): MountListEntry {
+  const resolvedPath = expandMountPath(mount.path, cwd)
+  const targetPath = `${MOUNT_TARGET_PREFIX}/${mount.name}`
+  const check = validateMount(mount, cwd)
+  return {
+    ...mount,
+    resolvedPath,
+    targetPath,
+    status: check.ok ? 'ok' : 'error',
+    ...(!check.ok ? { statusReason: check.reason } : {}),
+  }
+}
+
+function formatIssue(issue: { path: PropertyKey[]; message: string }): string {
+  const path = issue.path.length > 0 ? issue.path.map(String).join('.') : '<root>'
+  return `${path}: ${issue.message}`
+}

package/src/init/hatching.ts

@@ -38,7 +38,7 @@ Routing answers:
    1. \`write\` your name into \`IDENTITY.md\` (a first-person one-liner is fine: "I am <name>.").
    2. ${q1AliasStep} The agent folder's directory name is already an implicit alias — only add the answered name explicitly when it differs from the dir name (different casing, a different word, or extra forms like "<name>" plus a Latin transliteration). This wires plain-text addressing in channels: when a user writes your name in chat without an @-mention, the engagement layer will recognize it. \`alias\` is live-reloadable.
 2. **Q2 — the user's name.** Ask what to call them. After the answer: \`write\` it to both \`IDENTITY.md\` and \`USER.md\`.
-3. **Q3 — tone/personality.** Ask how they want you to show up (tone, language, formality). After the answer: \`write\` it into \`SOUL.md\`. If they shrug or don't care: **default to warm, friendly, and easygoing** — a kind colleague who genuinely likes the person they work with, uses contractions, makes small jokes, never stiff. Write that as the default into \`SOUL.md\`.
+3. **Q3 — tone/personality.** Ask how they want you to show up (tone, language, formality). After the answer: \`write\` it into \`SOUL.md\`. If they shrug or don't care: **default to warm, friendly, and easygoing** — a kind colleague who genuinely likes the person they work with, uses contractions, makes small jokes, never stiff. Write that as the default into \`SOUL.md\`. **Kaomoji affinity** — if their answer leans cute, adorable, warm, playful, soft, cozy, or is in Korean asking for 친근/귀엽/다정한 tone, append a line to \`SOUL.md\` like: \`I lean on kaomojis like (◕‿◕✿) and (｡･ω･｡) to carry warmth — emojis still welcome when they actually mean something, but kaomojis lead.\` This makes the bundled \`typeclaw-kaomoji\` skill auto-load later when you need it. Do not force this line if the user asked for a neutral, professional, or terse tone.
 
 **Do not ask what they want you to do, what project you'll work on, or why they installed you.** That reveals itself when they give you a real task. Probing here makes the tool feel heavy for someone just trying it out.
 

package/src/plugin/index.ts

@@ -75,6 +75,12 @@ export type { PermissionService } from '@/permissions'
 export type { LoadPluginEntryFn, ResolvedPlugin } from './loader'
 export { loadPluginEntry, derivePluginNameFromPackage } from './loader'
 export { materializeSkills, type MaterializedSkills, type SkillEntry } from './skills'
+export {
+  createLoadSkillTool,
+  type CreateLoadSkillToolOptions,
+  type LoadableSkill,
+  type LoadSkillArgs,
+} from './load-skill'
 export {
   buildPluginCronGlobalId,
   RESERVED_COMMAND_NAMES,

package/src/plugin/load-skill.ts

@@ -0,0 +1,99 @@
+import { z } from 'zod'
+
+import { defineTool } from './define'
+import type { Tool } from './types'
+
+// One unit of curated skill content a subagent can load on demand. The
+// `name` becomes a value in the tool's `name` enum; `description` is what
+// the model sees in the tool description block so it can decide which
+// skill to load WITHOUT having to load it first; `content` is the body
+// returned by the tool when the model picks this skill.
+export type LoadableSkill = {
+  name: string
+  description: string
+  content: string
+}
+
+export type CreateLoadSkillToolOptions = {
+  skills: readonly LoadableSkill[]
+  // Override the tool's top-level description. Defaults to a generic
+  // explanation of how the tool works followed by the per-skill menu.
+  // Plugins can pass a more specific framing (e.g. "Load a review skill
+  // …") so the subagent's instructions line up with the tool name.
+  description?: string
+}
+
+export type LoadSkillArgs = { name: string }
+
+// Build a typed `load_skill` tool a subagent can call to fetch the body
+// of a curated skill on demand. The factory closes over the `skills`
+// list so:
+//   - the `name` parameter is a Zod enum narrowed to exactly the skill
+//     names the caller supplied (typo-resistant; the model sees the
+//     allowed values in the tool's JSON Schema),
+//   - the tool's `description` lists every skill's name + description so
+//     the model can choose the right one BEFORE calling the tool, paying
+//     only one tool-call's worth of context for the body it actually
+//     needs,
+//   - unknown names are rejected by parameter validation, not by the
+//     handler — the runtime returns the validation error before
+//     `execute` runs.
+//
+// This is the runtime-loaded counterpart to TypeClaw's startup-time
+// skill discovery (`additionalSkillPaths` in `src/agent/index.ts`).
+// Subagents bypass the file-based resource loader, so the startup path
+// is unavailable to them; this factory gives plugin authors a typed way
+// to expose curated skills to their subagents via `customTools`.
+export function createLoadSkillTool(options: CreateLoadSkillToolOptions): Tool<LoadSkillArgs> {
+  const { skills } = options
+
+  if (skills.length === 0) {
+    throw new Error('createLoadSkillTool: `skills` must contain at least one entry')
+  }
+
+  const seen = new Set<string>()
+  for (const skill of skills) {
+    if (skill.name.length === 0) {
+      throw new Error('createLoadSkillTool: skill name must be non-empty')
+    }
+    if (seen.has(skill.name)) {
+      throw new Error(`createLoadSkillTool: duplicate skill name ${JSON.stringify(skill.name)}`)
+    }
+    seen.add(skill.name)
+  }
+
+  // z.enum requires a `[string, ...string[]]` tuple. Build it from the
+  // skill list so the JSON Schema surfaced to the model lists exactly
+  // the allowed values.
+  const names = skills.map((s) => s.name) as [string, ...string[]]
+
+  const description = options.description ?? buildDefaultDescription(skills)
+
+  return defineTool<LoadSkillArgs>({
+    description,
+    parameters: z.object({
+      name: z.enum(names).describe('The name of the skill to load. Must match one of the available skills.'),
+    }),
+    async execute(args) {
+      const skill = skills.find((s) => s.name === args.name)
+      if (skill === undefined) {
+        // Defensive: Zod enum validation should have rejected this
+        // before reaching the handler. Surface a clear message anyway.
+        const available = names.join(', ')
+        throw new Error(`Unknown skill ${JSON.stringify(args.name)}. Available skills: ${available}.`)
+      }
+      return {
+        content: [{ type: 'text' as const, text: skill.content }],
+        details: { name: skill.name, contentBytes: skill.content.length },
+      }
+    },
+  })
+}
+
+function buildDefaultDescription(skills: readonly LoadableSkill[]): string {
+  const menu = skills.map((s) => `- \`${s.name}\` — ${s.description}`).join('\n')
+  return `Load a curated skill by name. Returns the full skill body as text so you can apply it to the current task. Call this when you have identified which skill matches the task; do NOT load multiple skills speculatively.
+
+Available skills:
+${menu}`
+}

package/src/run/bundled-plugins.ts

@@ -4,6 +4,7 @@ import explorerPlugin from '@/bundled-plugins/explorer'
 import guardPlugin from '@/bundled-plugins/guard'
 import memoryPlugin from '@/bundled-plugins/memory'
 import operatorPlugin from '@/bundled-plugins/operator'
+import reviewerPlugin from '@/bundled-plugins/reviewer'
 import scoutPlugin from '@/bundled-plugins/scout'
 import securityPlugin from '@/bundled-plugins/security'
 import toolResultCapPlugin from '@/bundled-plugins/tool-result-cap'
@@ -41,5 +42,6 @@ export const BUNDLED_PLUGINS: ResolvedPlugin[] = [
   { name: 'agent-browser', version: undefined, source: '<bundled>', defined: agentBrowserPlugin },
   { name: 'explorer', version: undefined, source: '<bundled>', defined: explorerPlugin },
   { name: 'scout', version: undefined, source: '<bundled>', defined: scoutPlugin },
+  { name: 'reviewer', version: undefined, source: '<bundled>', defined: reviewerPlugin },
   { name: 'operator', version: undefined, source: '<bundled>', defined: operatorPlugin },
 ]

package/src/run/index.ts

@@ -43,7 +43,7 @@ import type { CronHandlerContext } from '@/plugin/types'
 import { createContainerBroker, publishForwardResult } from '@/portbroker'
 import { ReloadRegistry } from '@/reload'
 import { createClaimController } from '@/role-claim'
-import { hydrateChannelEnvFromSecrets } from '@/secrets'
+import { exportCodexAuthFileForAgent, hydrateChannelEnvFromSecrets } from '@/secrets'
 import { createServer, type Server } from '@/server'
 import {
   createCommandRunner,
@@ -181,6 +181,19 @@ export async function startAgent({
   // stay in env, the file stays user-owned. See src/secrets/hydrate.ts.
   hydrateChannelEnvFromSecrets({ agentDir: cwd })
 
+  // When the user has `docker.file.codexCli: true` AND a typeclaw-managed
+  // openai-codex OAuth credential in secrets.json, write ~/.codex/auth.json
+  // so the Codex CLI in the container can run without a second login. The
+  // exporter is failure-tolerant by design: any error (gate miss, fs error,
+  // corrupt file) returns a non-fatal result and the agent boot continues.
+  // See src/secrets/export-codex-auth-file.ts for the newer-wins compare
+  // that prevents clobbering Codex CLI's in-place token refreshes.
+  exportCodexAuthFileForAgent({
+    agentDir: cwd,
+    codexCliEnabled: cwdConfig.docker.file.codexCli,
+    log: (message) => console.warn(message),
+  })
+
   const claimController = createClaimController({
     cwd,
     permissions: pluginsLoaded.permissions,

package/src/secrets/codex-auth-json.ts

@@ -0,0 +1,67 @@
+import type { ProviderCredential } from './schema'
+
+// Emit the on-disk shape Codex CLI consumes at ~/.codex/auth.json. Mirrors
+// the modern (>= 0.93) shape: a single `tokens` object with access_token,
+// refresh_token, and optional account_id. Codex re-derives token expiry
+// from the JWT's `exp` claim on every load, so we deliberately omit a
+// top-level `expires` field even though typeclaw stores one.
+//
+// Pre-0.93 codex used a different layout (top-level OPENAI_API_KEY +
+// auth_mode discriminator + optional tokens). We don't emit that legacy
+// shape — every codex install old enough to require it has been replaced
+// by the version `docker.file.codexCli` installs in the container.
+export function emitCodexAuthJson(credential: ProviderCredential): string {
+  if (credential.type !== 'oauth') {
+    throw new Error('emitCodexAuthJson only accepts oauth-typed credentials')
+  }
+  const fields = credential as ProviderCredential & {
+    access?: unknown
+    refresh?: unknown
+    accountId?: 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')
+  }
+
+  const tokens: Record<string, string> = { access_token: access, refresh_token: refresh }
+  if (typeof fields.accountId === 'string' && fields.accountId.length > 0) {
+    tokens['account_id'] = fields.accountId
+  }
+  return `${JSON.stringify({ tokens }, null, 2)}\n`
+}
+
+// Extracts the JWT `exp` claim (seconds since epoch) and converts to ms.
+// Used by the runtime exporter's newer-wins compare: ~/.codex/auth.json
+// carries no top-level expiry, but the JWT inside `tokens.access_token`
+// does. Returns null on any decode failure; the caller treats that as
+// "unknown freshness" and falls back to overwriting from typeclaw's copy.
+export function decodeCodexAccessTokenExpiryMs(accessToken: string): number | null {
+  const parts = accessToken.split('.')
+  if (parts.length !== 3) return null
+  const middle = parts[1] ?? ''
+  if (middle === '') return null
+  // base64url → base64, then pad to a multiple of 4 (atob is strict).
+  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 isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}