typeclaw 0.1.4 → 0.1.5

package/src/container/start.ts

@@ -3,7 +3,7 @@ import { existsSync } from 'node:fs'
 import { readFile, writeFile } from 'node:fs/promises'
 import { isAbsolute, join, resolve } from 'node:path'
 
-import { configSchema, expandMountPath, type Config } from '@/config/config'
+import { configSchema, expandMountPath, migrateLegacyConfigShape, type Config } from '@/config'
 import { send as sendToDaemon } from '@/hostd/client'
 import type { HttpInfoResult } from '@/hostd/protocol'
 import { ensureDaemon } from '@/hostd/spawn'
@@ -22,7 +22,7 @@ import { refreshPackageJson } from '@/init/packagejson'
 import { runBunUpdate, type UpdateRunner } from '@/init/run-bun-install'
 import { migrateKakaotalkCredentials } from '@/secrets'
 
-import { CONTAINER_PORT, findFreePort, isPortAllocatedError } from './port'
+import { CONTAINER_PORT, TUI_TOKEN_LABEL, findFreePort, isPortAllocatedError, resolveTuiToken } from './port'
 import {
   classifyRmStderr,
   cleanupRunCorpse,
@@ -57,6 +57,7 @@ export type StartPlan = {
   runArgs: string[]
   needsBuild: boolean
   hostPort: number
+  tuiToken: string | null
 }
 
 export type PlanStartOptions = {
@@ -65,6 +66,8 @@ export type PlanStartOptions = {
   imageExists: boolean
   forceBuild?: boolean
   hostdControl?: HostDaemonControl
+  publishHost?: string
+  tuiToken?: string | null
 }
 
 export type HostDaemonControl = {
@@ -127,6 +130,7 @@ export type StartResult =
       containerId: string
       built: boolean
       hostPort: number
+      tuiToken: string | null
       hostd: HostDaemonStatus
       // True when the container was already running and start() became a no-op.
       // Callers that want to distinguish "I just launched it" from "it was up
@@ -298,7 +302,17 @@ export async function start({
       : { state: 'disabled' as const }
     let hostdControl = hostd.state === 'registered' ? hostd.control : undefined
 
-    let plan = await planStart({ cwd, hostPort, imageExists: imageExisted, forceBuild, hostdControl })
+    const publishHost = await resolvePublishHost(exec)
+    const tuiToken = randomBytes(32).toString('base64url')
+    let plan = await planStart({
+      cwd,
+      hostPort,
+      imageExists: imageExisted,
+      forceBuild,
+      hostdControl,
+      publishHost,
+      tuiToken,
+    })
 
     let built = false
     if (plan.needsBuild) {
@@ -347,7 +361,15 @@ export async function start({
         hostd = await registerWithDaemon({ cwd, containerName, cliEntry, hostPort, reuseCurrentHostDaemon })
         hostdControl = hostd.state === 'registered' ? hostd.control : undefined
       }
-      plan = await planStart({ cwd, hostPort, imageExists: true, forceBuild: false, hostdControl })
+      plan = await planStart({
+        cwd,
+        hostPort,
+        imageExists: true,
+        forceBuild: false,
+        hostdControl,
+        publishHost,
+        tuiToken,
+      })
       run = await execRunWithConflictRetry(exec, plan.runArgs, cwd, containerName)
     }
 
@@ -370,6 +392,7 @@ export async function start({
       containerId,
       built,
       hostPort,
+      tuiToken,
       hostd: stripHostDaemonControl(hostd),
       alreadyRunning: false,
       autoUpgrade: upgrade,
@@ -403,6 +426,8 @@ export async function planStart({
   imageExists,
   forceBuild = false,
   hostdControl,
+  publishHost = '127.0.0.1',
+  tuiToken = null,
 }: PlanStartOptions): Promise<StartPlan> {
   const containerName = containerNameFromCwd(cwd)
   const imageTag = imageTagFromCwd(cwd)
@@ -416,7 +441,7 @@ export async function planStart({
   // the start() preflight force-removes any lingering corpse before the next
   // launch — so the only state Docker ever sees in `docker ps -a` is either
   // a running container or one the user has not started again yet.
-  const runArgs = ['run', '-d', '--name', containerName, '-p', `127.0.0.1:${hostPort}:${CONTAINER_PORT}`]
+  const runArgs = ['run', '-d', '--name', containerName, '-p', `${publishHost}:${hostPort}:${CONTAINER_PORT}`]
 
   // Network egress filter: when `typeclaw.json#network.blockInternal` is true,
   // grant the container CAP_NET_ADMIN at boot so the entrypoint shim can
@@ -443,6 +468,9 @@ export async function planStart({
   for (const [key, value] of Object.entries(composeLabels(cwd, containerName))) {
     runArgs.push('--label', `${key}=${value}`)
   }
+  if (tuiToken !== null) {
+    runArgs.push('--label', `${TUI_TOKEN_LABEL}=${tuiToken}`, '-e', `TYPECLAW_TUI_TOKEN=${tuiToken}`)
+  }
 
   if (existsSync(join(cwd, ENV_FILE))) {
     runArgs.push('--env-file', join(cwd, ENV_FILE))
@@ -493,20 +521,27 @@ export async function planStart({
     runArgs,
     needsBuild: forceBuild || !imageExists,
     hostPort,
+    tuiToken,
   }
 }
 
+async function resolvePublishHost(exec: DockerExec): Promise<string> {
+  const result = await exec(['version', '--format', '{{.Server.Platform.Name}}'])
+  if (result.exitCode === 0 && result.stdout.toLowerCase().includes('docker desktop')) return '0.0.0.0'
+  return '127.0.0.1'
+}
+
 export async function refreshDockerfile(cwd: string): Promise<void> {
   const cfg = await loadTypeclawConfig(cwd)
   await writeFile(
     join(cwd, DOCKERFILE),
-    buildDockerfile(cfg.dockerfile, { baseImageVersion: resolveBaseImageVersion(cwd) }),
+    buildDockerfile(cfg.docker.file, { baseImageVersion: resolveBaseImageVersion(cwd) }),
   )
 }
 
 export async function refreshGitignore(cwd: string): Promise<void> {
   const cfg = await loadTypeclawConfig(cwd)
-  await writeFile(join(cwd, GITIGNORE_FILE), buildGitignore(cfg.gitignore))
+  await writeFile(join(cwd, GITIGNORE_FILE), buildGitignore(cfg.git.ignore))
 }
 
 // Commits TypeClaw-owned system file(s) if any are dirty in git. Skips silently
@@ -623,13 +658,15 @@ async function reportAlreadyRunning(exec: DockerExec, cwd: string, containerName
       reason: `Container ${containerName} is running but its published host port could not be resolved.`,
     }
   }
-  const plan = await planStart({ cwd, hostPort, imageExists: true, forceBuild: false })
+  const tuiToken = await resolveTuiToken({ cwd, exec })
+  const plan = await planStart({ cwd, hostPort, imageExists: true, forceBuild: false, tuiToken })
   return {
     ok: true,
     plan,
     containerId,
     built: false,
     hostPort,
+    tuiToken,
     hostd: { state: 'disabled' },
     alreadyRunning: true,
     autoUpgrade: { kind: 'skipped-already-running' },
@@ -747,7 +784,7 @@ async function loadConfigJson(cwd: string): Promise<unknown> {
   } catch {
     return {}
   }
-  return JSON.parse(raw)
+  return migrateLegacyConfigShape(JSON.parse(raw)).json
 }
 
 type PreparedHostDaemonStatus =

package/src/doctor/checks.ts

@@ -390,7 +390,7 @@ function loadConfigStrictForTemplate(
   const result = validateConfig(cwd)
   if (!result.ok) return null
   const cfg = loadConfigSync(cwd)
-  return { dockerfile: cfg.dockerfile, gitignore: cfg.gitignore }
+  return { dockerfile: cfg.docker.file, gitignore: cfg.git.ignore }
 }
 
 async function safeRead(path: string): Promise<string | null> {

package/src/doctor/plugin-bridge.ts

@@ -1,4 +1,4 @@
-import { resolveHostPort } from '@/container'
+import { resolveHostPort, resolveTuiToken } from '@/container'
 import type { ClientMessage, DoctorCheckPayload, DoctorFixPayload, ServerMessage } from '@/shared'
 
 export type PluginBridgeOptions = {
@@ -80,12 +80,14 @@ async function dial(opts: PluginBridgeOptions): Promise<DialResult> {
   if (url === undefined) {
     try {
       const port = await resolveHostPort({ cwd: opts.cwd })
-      url = `ws://localhost:${port}`
+      const token = await resolveTuiToken({ cwd: opts.cwd })
+      url = buildBridgeUrl(port, token)
     } catch (err) {
       return { kind: 'unreachable', reason: err instanceof Error ? err.message : String(err) }
     }
   }
   const ws = new WebSocket(url)
+  const displayUrl = redactUrl(url)
   try {
     await new Promise<void>((resolve, reject) => {
       // `timer` is declared up front so `cleanup` can reference it without
@@ -97,6 +99,7 @@ async function dial(opts: PluginBridgeOptions): Promise<DialResult> {
         if (timer !== undefined) clearTimeout(timer)
         ws.removeEventListener('open', onOpen)
         ws.removeEventListener('error', onError)
+        ws.removeEventListener('close', onClose)
       }
       const onOpen = () => {
         cleanup()
@@ -104,7 +107,11 @@ async function dial(opts: PluginBridgeOptions): Promise<DialResult> {
       }
       const onError = (err: unknown) => {
         cleanup()
-        reject(err instanceof Error ? err : new Error(`failed to connect to ${url}`))
+        reject(new Error(`failed to connect to ${displayUrl}: ${err instanceof Error ? err.message : String(err)}`))
+      }
+      const onClose = () => {
+        cleanup()
+        reject(new Error(`connection to ${displayUrl} closed before opening`))
       }
       // Bun's WebSocket has no built-in connect timeout. Without this, a TCP
       // handshake that completes but never produces an Upgrade response
@@ -117,10 +124,11 @@ async function dial(opts: PluginBridgeOptions): Promise<DialResult> {
         try {
           ws.close()
         } catch {}
-        reject(new Error(`websocket connect timeout after ${timeoutMs}ms`))
+        reject(new Error(`timed out connecting to ${displayUrl} after ${timeoutMs}ms`))
       }, timeoutMs)
       ws.addEventListener('open', onOpen, { once: true })
       ws.addEventListener('error', onError, { once: true })
+      ws.addEventListener('close', onClose, { once: true })
     })
   } catch (err) {
     return { kind: 'unreachable', reason: err instanceof Error ? err.message : String(err) }
@@ -128,6 +136,22 @@ async function dial(opts: PluginBridgeOptions): Promise<DialResult> {
   return { kind: 'ok', ws, timeoutMs }
 }
 
+function buildBridgeUrl(port: number, token: string | null): string {
+  const url = new URL(`ws://127.0.0.1:${port}`)
+  if (token !== null) url.searchParams.set('token', token)
+  return url.toString()
+}
+
+function redactUrl(url: string): string {
+  try {
+    const parsed = new URL(url)
+    if (parsed.searchParams.has('token')) parsed.searchParams.set('token', '<redacted>')
+    return parsed.toString()
+  } catch {
+    return url
+  }
+}
+
 async function withRequest<R extends { kind: string }>(
   ws: WebSocket,
   timeoutMs: number,

package/src/init/dockerfile.ts

@@ -384,7 +384,7 @@ ${ghKeyringLayer}# Layer 2 (changes when the package list changes): the actual a
 # Cache mounts make a re-install nearly free when this layer is invalidated:
 # .deb files come straight from the host's BuildKit cache instead of being
 # refetched from Debian/GitHub mirrors. Package set is composed from the
-# \`dockerfile\` config block in typeclaw.json — toggles for tmux/python/gh/
+# \`docker.file\` config block in typeclaw.json — toggles for tmux/python/gh/
 # ffmpeg fan out into the args below. Baseline (git/ca-certificates/curl/
 # gnupg) is always installed because downstream layers depend on it.
 #
@@ -417,7 +417,7 @@ ${renderEntrypointShimLayer()}
 
 function renderToggleAptInstallLayer(toggleAptArgs: string[]): string {
   return `# Layer 1 (toggle apt install): packages requested via typeclaw.json
-# #dockerfile toggles. Baseline + Chrome runtime libs are already in the
+# #docker.file toggles. Baseline + Chrome runtime libs are already in the
 # base image; this layer only adds gh/tmux/python/ffmpeg if enabled.
 RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \\
     --mount=type=cache,target=/var/lib/apt/lists,sharing=locked \\
@@ -432,7 +432,7 @@ RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \\
 // two cannot drift — the published image is a function of this source, not
 // a checked-in Dockerfile that needs hand-syncing. The base intentionally
 // stops before the per-agent layers (gh keyring, apt feature toggles,
-// dockerfile.append, ENV, ENTRYPOINT) so users can still toggle them via
+// docker.file.append, ENV, ENTRYPOINT) so users can still toggle them via
 // typeclaw.json without forcing a base-image rebuild.
 //
 // Layer 2's apt-get install line installs only the baseline packages, NOT
@@ -587,7 +587,7 @@ RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \\
 
 function renderCustomDockerfileLines(lines: string[]): string {
   if (lines.length === 0) return ''
-  return `# Custom lines from typeclaw.json#dockerfile.append.
+  return `# Custom lines from typeclaw.json#docker.file.append.
 ${lines.join('\n')}
 
 `

package/src/init/gitignore.ts

@@ -39,7 +39,7 @@ channels/
 
 function renderCustomGitignoreEntries(entries: string[]): string {
   if (entries.length === 0) return ''
-  return `# Custom entries from typeclaw.json#gitignore.append.
+  return `# Custom entries from typeclaw.json#git.ignore.append.
 ${entries.join('\n')}
 
 `

package/src/init/index.ts

@@ -3,10 +3,16 @@ import { mkdir, readFile, writeFile } from 'node:fs/promises'
 import { basename, dirname, join, relative, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
-import { config, configSchema, type Config } from '@/config'
-import { DEFAULT_MODEL_REF, KNOWN_PROVIDERS, providerForModelRef, type KnownModelRef } from '@/config/providers'
+import { config, configSchema, migrateLegacyConfigShape, type Config } from '@/config'
+import {
+  DEFAULT_MODEL_REF,
+  KNOWN_PROVIDERS,
+  providerForModelRef,
+  type KnownModelRef,
+  type KnownProviderId,
+} from '@/config/providers'
 import { checkDockerAvailable, type DockerAvailability, type DockerExec, start } from '@/container'
-import { type Channels, type Secret, SecretsBackend } from '@/secrets'
+import { createSecretsStoreForAgent, type Channels, type Secret, SecretsBackend } from '@/secrets'
 import { createTui } from '@/tui'
 
 import { resolveBaseImageVersion, resolveScaffoldVersion } from './cli-version'
@@ -23,7 +29,6 @@ export { GITKEEP_FILE, PACKAGES_DIR } from './paths'
 
 const CONFIG_FILE = 'typeclaw.json'
 const CRON_FILE = 'cron.json'
-const SECRETS_FILE = '.env'
 const PACKAGE_FILE = 'package.json'
 
 const MARKDOWN_FILES = ['AGENTS.md', 'IDENTITY.md', 'SOUL.md', 'USER.md'] as const
@@ -269,10 +274,10 @@ export async function defaultRunHatching({
     // the preferred port, otherwise we'd connect to the wrong service.
     const hostPort = launch.hostPort
 
-    await waitForAgentFn(`http://localhost:${hostPort}`, { timeoutMs: 30_000 })
+    await waitForAgentFn(`http://127.0.0.1:${hostPort}`, { timeoutMs: 30_000 })
 
     const tui = tuiFactory({
-      url: `ws://localhost:${hostPort}`,
+      url: buildTuiUrl(hostPort, launch.tuiToken),
       initialPrompt: HATCHING_PROMPT,
     })
     await tui.run()
@@ -282,6 +287,12 @@ export async function defaultRunHatching({
   }
 }
 
+function buildTuiUrl(hostPort: number, token: string | null): string {
+  const url = new URL(`ws://127.0.0.1:${hostPort}`)
+  if (token !== null) url.searchParams.set('token', token)
+  return url.toString()
+}
+
 // Probe the server's plain HTTP fallback (non-upgrade requests get a 200 with
 // body "typeclaw agent") instead of opening a WebSocket. Opening a WS here
 // would trigger createSession on the server and burn an LLM session just to
@@ -484,7 +495,7 @@ export async function writeDockerAssets(root: string): Promise<DockerAssetsResul
     const typeclawConfig = await readTypeclawConfig(root)
     await writeFile(
       join(root, DOCKERFILE),
-      buildDockerfile(typeclawConfig.dockerfile, { baseImageVersion: resolveBaseImageVersion(root) }),
+      buildDockerfile(typeclawConfig.docker.file, { baseImageVersion: resolveBaseImageVersion(root) }),
       { flag: 'wx' },
     ).catch(ignoreExists)
 
@@ -502,7 +513,7 @@ async function readPackageJson(root: string): Promise<{ name?: string; dependenc
 async function readTypeclawConfig(root: string): Promise<Config> {
   try {
     const raw = await readFile(join(root, CONFIG_FILE), 'utf8')
-    return configSchema.parse(JSON.parse(raw))
+    return configSchema.parse(migrateLegacyConfigShape(JSON.parse(raw)).json)
   } catch (error) {
     if ((error as NodeJS.ErrnoException).code === 'ENOENT') return configSchema.parse({})
     throw error
@@ -558,15 +569,10 @@ export async function initGitRepo(cwd: string): Promise<GitInitResult> {
   }
 }
 
-// Writes the LLM provider's API key to `.env` (under its provider-specific
-// env var, e.g. OPENAI_API_KEY or FIREWORKS_API_KEY) and the channel adapter
-// tokens to `secrets.json#channels`. Two stores on purpose: api-keys land in
-// `.env` to match the `--env-file .env` boot contract (env-wins: `auth.ts`
-// reads the value at runtime via `setRuntimeApiKey` and never persists it to
-// `secrets.json`, see `src/agent/auth.ts`); channel tokens skip the .env hop
-// entirely and land in `secrets.json#channels` as `{ value }` Secrets that
-// `hydrateChannelEnvFromSecrets` injects into `process.env` only when the
-// canonical env var is unset, see `src/secrets/hydrate.ts`.
+// Writes LLM provider API keys to `secrets.json#providers` and channel adapter
+// tokens to `secrets.json#channels`. Both paths go through the structured
+// v2 secrets envelope so reruns can reuse existing values without depending on
+// host-stage env files.
 export async function writeSecrets(
   root: string,
   {
@@ -578,9 +584,7 @@ export async function writeSecrets(
     telegramBotToken,
   }: {
     model?: KnownModelRef
-    // Omitted on the OAuth path — credentials live in secrets.json instead.
-    // The .env file still gets written (empty) so post-init callers that
-    // read it don't ENOENT-crash.
+    // Omitted on the OAuth path — credentials live in secrets.json via the OAuth runner.
     apiKey?: string
     discordBotToken?: string
     slackBotToken?: string
@@ -590,12 +594,9 @@ export async function writeSecrets(
 ): Promise<void> {
   const providerId = providerForModelRef(model)
   const apiKeyEnv = KNOWN_PROVIDERS[providerId].apiKeyEnv
-  const lines: string[] = []
   if (apiKey !== undefined && apiKeyEnv !== null) {
-    lines.push(`${apiKeyEnv}=${apiKey}`)
+    createSecretsStoreForAgent(join(root, 'secrets.json')).set(providerId, { type: 'api_key', key: apiKey })
   }
-  const body = lines.length > 0 ? `${lines.join('\n')}\n` : ''
-  await writeFile(join(root, SECRETS_FILE), body)
 
   const channelTokens: Record<string, Record<string, Secret>> = {}
   if (discordBotToken !== undefined && discordBotToken !== '') {
@@ -623,6 +624,12 @@ export async function writeSecrets(
   backend.writeChannelsSync(merged)
 }
 
+export async function readExistingProviderApiKey(root: string, providerId: KnownProviderId): Promise<string | null> {
+  const provider = KNOWN_PROVIDERS[providerId]
+  if (provider.apiKeyEnv === null) return null
+  return new SecretsBackend(join(root, 'secrets.json')).tryReadProviderApiKeySync(providerId)
+}
+
 function isObjectRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value)
 }

package/src/reload/client.ts

@@ -16,22 +16,36 @@ export async function requestReload({
   timeoutMs = DEFAULT_TIMEOUT_MS,
 }: RequestReloadOptions): Promise<ReloadResult[]> {
   const ws = new WebSocket(url)
+  const displayUrl = redactUrl(url)
 
   await new Promise<void>((resolve, reject) => {
+    let timer: ReturnType<typeof setTimeout> | undefined
     const onOpen = () => {
       cleanup()
       resolve()
     }
     const onError = (err: unknown) => {
       cleanup()
-      reject(err instanceof Error ? err : new Error(`failed to connect to ${url}`))
+      reject(new Error(`failed to connect to ${displayUrl}: ${err instanceof Error ? err.message : String(err)}`))
+    }
+    const onClose = () => {
+      cleanup()
+      reject(new Error(`connection to ${displayUrl} closed before opening`))
     }
     const cleanup = () => {
+      if (timer !== undefined) clearTimeout(timer)
       ws.removeEventListener('open', onOpen)
       ws.removeEventListener('error', onError)
+      ws.removeEventListener('close', onClose)
     }
+    timer = setTimeout(() => {
+      cleanup()
+      ws.close()
+      reject(new Error(`timed out connecting to ${displayUrl} after ${timeoutMs}ms`))
+    }, timeoutMs)
     ws.addEventListener('open', onOpen, { once: true })
     ws.addEventListener('error', onError, { once: true })
+    ws.addEventListener('close', onClose, { once: true })
   })
 
   try {
@@ -57,3 +71,13 @@ export async function requestReload({
     ws.close()
   }
 }
+
+function redactUrl(url: string): string {
+  try {
+    const parsed = new URL(url)
+    if (parsed.searchParams.has('token')) parsed.searchParams.set('token', '<redacted>')
+    return parsed.toString()
+  } catch {
+    return url
+  }
+}

package/src/run/index.ts

@@ -87,6 +87,8 @@ export async function startAgent({
   // which is what we want, since there is no host daemon to honor it anyway.
   const containerName = process.env.TYPECLAW_CONTAINER_NAME
   const containerNameOpt = containerName !== undefined ? { containerName } : {}
+  const tuiToken = process.env.TYPECLAW_TUI_TOKEN
+  const tuiTokenOpt = tuiToken !== undefined && tuiToken !== '' ? { tuiToken } : {}
   reloadRegistry.register(createConfigReloadable({ cwd }))
 
   const pluginConfigsByName = loadPluginConfigsSync(cwd)
@@ -312,6 +314,7 @@ export async function startAgent({
     agentDir: cwd,
     pluginRuntime,
     ...containerNameOpt,
+    ...tuiTokenOpt,
     ...containerBrokerOpt,
   }).start()
 
@@ -343,7 +346,9 @@ export async function startAgent({
     }
   }
 
-  const url = `ws://localhost:${server.port}`
+  const serverPort = server.port
+  if (serverPort === undefined) throw new Error('server did not report a listening port')
+  const url = buildLocalTuiUrl(serverPort, tuiTokenOpt.tuiToken ?? null)
   const tui = createTui({ url, initialPrompt })
   const tuiPromise = tui.run()
   return {
@@ -361,6 +366,13 @@ export async function startAgent({
   }
 }
 
+function buildLocalTuiUrl(port: number, token: string | null): string {
+  if (token === null) return `ws://localhost:${port}`
+  const url = new URL(`ws://localhost:${port}`)
+  url.searchParams.set('token', token)
+  return url.toString()
+}
+
 async function disposeMaterializedSkills(pluginRuntime: PluginRuntime): Promise<void> {
   const pending = pluginRuntime.drainPendingDisposal()
   const current = pluginRuntime.get().materializedSkills

package/src/secrets/storage.ts

@@ -160,6 +160,21 @@ export class SecretsBackend implements AuthStorageBackend {
     }
   }
 
+  tryReadProviderApiKeySync(providerId: string, env: NodeJS.ProcessEnv = process.env): string | null {
+    if (!existsSync(this.secretsPath)) return null
+    let release: (() => void) | undefined
+    try {
+      release = this.acquireSyncLockWithRetry()
+      const credential = this.readEnvelope().providers[providerId]
+      if (credential?.type !== 'api_key') return null
+      const resolved =
+        resolveSecret(credential.key, providerKeyDefaultEnv(providerId), env) ?? credential.key.value ?? ''
+      return resolved.trim() !== '' ? resolved : null
+    } finally {
+      release?.()
+    }
+  }
+
   writeChannelsSync(next: Channels): void {
     this.ensureParentDir()
     this.ensureFileExists()