typeclaw 0.10.0 → 0.11.1

package/src/config/config.ts

@@ -250,16 +250,24 @@ export type NetworkConfig = z.infer<typeof networkSchema>
 
 // Reverse-proxy tunnels expose a container-private port to the public internet
 // via a managed subprocess (cloudflared) or a user-supplied external URL.
-// See AGENTS.md `## Tunnels`. PR 2 ships `cloudflare-quick`; `cloudflare-named`
-// remains deferred to PR 3. Keeping the enum scoped to what's implemented means
-// validateConfig() rejects unsupported providers at `typeclaw start` time,
-// before the container is torn down and rebuilt. `restart-required` because
-// the tunnel manager reads this list once at boot.
+// See AGENTS.md `## Tunnels`. Keeping the enum scoped to what's implemented
+// means validateConfig() rejects unsupported providers at `typeclaw start`
+// time, before the container is torn down and rebuilt. `restart-required`
+// because the tunnel manager reads this list once at boot.
 const tunnelForSchema = z.discriminatedUnion('kind', [
   z.object({ kind: z.literal('channel'), name: z.string().trim().min(1) }),
   z.object({ kind: z.literal('manual') }),
 ])
 
+// `tokenEnv` is the NAME of an env var, not the token itself. Restrict to the
+// shell-portable identifier shape (uppercase + digits + underscore, leading
+// non-digit) so a value typed here can't break `--env-file` parsing or shell
+// expansion inside the container. Matches the convention every other env var
+// in the codebase already follows (TYPECLAW_*, OPENAI_*, etc.).
+const tokenEnvNameSchema = z.string().regex(/^[A-Z_][A-Z0-9_]*$/, {
+  message: 'tokenEnv must be an env var name like CLOUDFLARE_TUNNEL_TOKEN (uppercase, digits, underscore)',
+})
+
 const tunnelEntrySchema = z
   .object({
     name: z
@@ -268,7 +276,7 @@ const tunnelEntrySchema = z
       .regex(/^[a-z0-9][a-z0-9-_]*$/, {
         message: 'tunnel name must match /^[a-z0-9][a-z0-9-_]*$/ (lowercase, digits, dashes, underscores)',
       }),
-    provider: z.enum(['external', 'cloudflare-quick']),
+    provider: z.enum(['external', 'cloudflare-quick', 'cloudflare-named']),
     for: tunnelForSchema,
     externalUrl: z
       .string()
@@ -276,11 +284,31 @@ const tunnelEntrySchema = z
       .refine((u) => u.startsWith('https://'), { message: 'externalUrl must use https://' })
       .optional(),
     upstreamPort: z.number().int().min(1).max(65535).optional(),
+    hostname: z
+      .string()
+      .url()
+      .refine((u) => u.startsWith('https://'), { message: 'hostname must use https://' })
+      .optional(),
+    tokenEnv: tokenEnvNameSchema.optional(),
   })
   .refine((v) => v.provider !== 'external' || (v.externalUrl !== undefined && v.externalUrl.trim() !== ''), {
     message: "tunnels[].externalUrl is required when provider is 'external'",
   })
-  .refine((v) => v.for.kind !== 'manual' || v.upstreamPort !== undefined, {
+  .refine((v) => v.provider !== 'cloudflare-named' || (v.hostname !== undefined && v.hostname.trim() !== ''), {
+    message: "tunnels[].hostname is required when provider is 'cloudflare-named'",
+  })
+  .refine((v) => v.provider !== 'cloudflare-named' || (v.tokenEnv !== undefined && v.tokenEnv.trim() !== ''), {
+    message: "tunnels[].tokenEnv is required when provider is 'cloudflare-named'",
+  })
+  // cloudflared learns the upstream from the Cloudflare dashboard's Public
+  // Hostname mapping, not from typeclaw. An `upstreamPort` here would be
+  // silently ignored; reject at parse time so the contradiction surfaces in
+  // the config file rather than as a debugging surprise.
+  .refine((v) => v.provider !== 'cloudflare-named' || v.upstreamPort === undefined, {
+    message:
+      "tunnels[].upstreamPort must not be set when provider is 'cloudflare-named' (cloudflared reads the upstream from the Cloudflare dashboard)",
+  })
+  .refine((v) => v.for.kind !== 'manual' || v.provider === 'cloudflare-named' || v.upstreamPort !== undefined, {
     message: "tunnels[].upstreamPort is required when for.kind is 'manual'",
   })
 

package/src/config/providers.ts

@@ -108,6 +108,70 @@ export const KNOWN_PROVIDERS = {
       },
     },
   },
+  // ChatGPT Plus/Pro subscription via the OAuth Codex backend. No API key
+  // path here on purpose — the Codex backend is OAuth-only upstream.
+  //
+  // pi-ai 0.73.1's `openai-codex` bucket carries gpt-5.5 (and 5.4) against
+  // chatgpt.com/backend-api. We pin pi-coding-agent ^0.67.3 today, which
+  // ships pi-ai 0.67.3 and lacks those entries — but we hand pi-ai a
+  // freshly-constructed `Model<>` literal via resolveModel(), bypassing its
+  // built-in catalog entirely (same trick we use for kimi-k2p6-turbo). So
+  // these ids work end-to-end as long as the Codex backend itself accepts
+  // them, which it does for ChatGPT Plus/Pro accounts as of 2026-05-10.
+  //
+  // Position-load-bearing: must stay adjacent to `openai`. The init wizard's
+  // provider picker, `provider --help`'s `id | id | ...` listing, and the
+  // generated JSON schema's model-ref enum all derive their ordering from
+  // Object.keys() iteration on this literal. Alphabetizing the registry
+  // would scatter `openai-codex` after `fireworks` and re-introduce the
+  // "OpenAI ... Anthropic ... OpenAI" picker order this comment exists to
+  // prevent.
+  'openai-codex': {
+    id: 'openai-codex',
+    name: 'OpenAI Codex (ChatGPT Plus/Pro)',
+    baseUrl: 'https://chatgpt.com/backend-api',
+    auth: ['oauth'],
+    apiKeyEnv: null,
+    oauthProviderId: 'openai-codex',
+    models: {
+      'gpt-5.4-mini': {
+        id: 'gpt-5.4-mini',
+        name: 'GPT-5.4 mini',
+        api: 'openai-codex-responses',
+        provider: 'openai-codex',
+        baseUrl: 'https://chatgpt.com/backend-api',
+        reasoning: true,
+        input: ['text', 'image'],
+        cost: { input: 0.75, output: 4.5, cacheRead: 0.075, cacheWrite: 0 },
+        contextWindow: 272000,
+        maxTokens: 128000,
+      },
+      'gpt-5.4': {
+        id: 'gpt-5.4',
+        name: 'GPT-5.4',
+        api: 'openai-codex-responses',
+        provider: 'openai-codex',
+        baseUrl: 'https://chatgpt.com/backend-api',
+        reasoning: true,
+        input: ['text', 'image'],
+        cost: { input: 2.5, output: 15, cacheRead: 0.25, cacheWrite: 0 },
+        contextWindow: 272000,
+        maxTokens: 128000,
+      },
+      'gpt-5.5': {
+        id: 'gpt-5.5',
+        name: 'GPT-5.5',
+        api: 'openai-codex-responses',
+        provider: 'openai-codex',
+        baseUrl: 'https://chatgpt.com/backend-api',
+        reasoning: true,
+        input: ['text', 'image'],
+        cost: { input: 5, output: 30, cacheRead: 0.5, cacheWrite: 0 },
+        contextWindow: 272000,
+        maxTokens: 128000,
+      },
+    },
+  },
   // Anthropic Claude — both the Anthropic Console API (ANTHROPIC_API_KEY)
   // and Claude Pro/Max/Team/Enterprise subscriptions (OAuth) reach the same
   // /v1/messages endpoint and share one provider id. Auth path determines
@@ -214,62 +278,6 @@ export const KNOWN_PROVIDERS = {
       },
     },
   },
-  // ChatGPT Plus/Pro subscription via the OAuth Codex backend. No API key
-  // path here on purpose — the Codex backend is OAuth-only upstream.
-  //
-  // pi-ai 0.73.1's `openai-codex` bucket carries gpt-5.5 (and 5.4) against
-  // chatgpt.com/backend-api. We pin pi-coding-agent ^0.67.3 today, which
-  // ships pi-ai 0.67.3 and lacks those entries — but we hand pi-ai a
-  // freshly-constructed `Model<>` literal via resolveModel(), bypassing its
-  // built-in catalog entirely (same trick we use for kimi-k2p6-turbo). So
-  // these ids work end-to-end as long as the Codex backend itself accepts
-  // them, which it does for ChatGPT Plus/Pro accounts as of 2026-05-10.
-  'openai-codex': {
-    id: 'openai-codex',
-    name: 'OpenAI Codex (ChatGPT Plus/Pro)',
-    baseUrl: 'https://chatgpt.com/backend-api',
-    auth: ['oauth'],
-    apiKeyEnv: null,
-    oauthProviderId: 'openai-codex',
-    models: {
-      'gpt-5.4-mini': {
-        id: 'gpt-5.4-mini',
-        name: 'GPT-5.4 mini',
-        api: 'openai-codex-responses',
-        provider: 'openai-codex',
-        baseUrl: 'https://chatgpt.com/backend-api',
-        reasoning: true,
-        input: ['text', 'image'],
-        cost: { input: 0.75, output: 4.5, cacheRead: 0.075, cacheWrite: 0 },
-        contextWindow: 272000,
-        maxTokens: 128000,
-      },
-      'gpt-5.4': {
-        id: 'gpt-5.4',
-        name: 'GPT-5.4',
-        api: 'openai-codex-responses',
-        provider: 'openai-codex',
-        baseUrl: 'https://chatgpt.com/backend-api',
-        reasoning: true,
-        input: ['text', 'image'],
-        cost: { input: 2.5, output: 15, cacheRead: 0.25, cacheWrite: 0 },
-        contextWindow: 272000,
-        maxTokens: 128000,
-      },
-      'gpt-5.5': {
-        id: 'gpt-5.5',
-        name: 'GPT-5.5',
-        api: 'openai-codex-responses',
-        provider: 'openai-codex',
-        baseUrl: 'https://chatgpt.com/backend-api',
-        reasoning: true,
-        input: ['text', 'image'],
-        cost: { input: 5, output: 30, cacheRead: 0.5, cacheWrite: 0 },
-        contextWindow: 272000,
-        maxTokens: 128000,
-      },
-    },
-  },
   fireworks: {
     id: 'fireworks',
     name: 'Fireworks',

package/src/init/env-file.ts

@@ -0,0 +1,66 @@
+import { readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+const ENV_FILE = '.env'
+
+// Parse the agent's `.env` into a key-value map, matching Docker's
+// `--env-file` parser semantics: blank lines and `#`-lines ignored, no
+// quote stripping, no shell expansion, no whitespace trimming around `=`.
+// Lines without `=` are skipped. Last value wins on duplicate keys.
+export function readEnvFile(cwd: string): Map<string, string> {
+  const out = new Map<string, string>()
+  let raw: string
+  try {
+    raw = readFileSync(join(cwd, ENV_FILE), 'utf8')
+  } catch (err) {
+    if (err instanceof Error && 'code' in err && err.code === 'ENOENT') return out
+    throw err
+  }
+  for (const line of raw.split(/\r?\n/)) {
+    if (line.length === 0) continue
+    if (line.startsWith('#')) continue
+    const eq = line.indexOf('=')
+    if (eq <= 0) continue
+    const key = line.slice(0, eq)
+    const value = line.slice(eq + 1)
+    out.set(key, value)
+  }
+  return out
+}
+
+export function hasEnvKey(cwd: string, key: string): boolean {
+  const value = readEnvFile(cwd).get(key)
+  return value !== undefined && value.length > 0
+}
+
+// Write `key=value` to the agent's `.env`. Idempotent: replaces an existing
+// line for the same key in place (preserving order and surrounding comments),
+// or appends if absent. Creates the file if missing. The value is written
+// verbatim with no quoting because Docker's `--env-file` parser does not
+// strip quotes (a wrapping `"..."` would land in `process.env` literally).
+export function appendOrReplaceEnvKey(cwd: string, key: string, value: string): void {
+  const path = join(cwd, ENV_FILE)
+  let raw = ''
+  try {
+    raw = readFileSync(path, 'utf8')
+  } catch (err) {
+    if (!(err instanceof Error) || !('code' in err) || err.code !== 'ENOENT') throw err
+  }
+  const lines = raw.length === 0 ? [] : raw.split(/\r?\n/)
+  // `"foo\n".split(/\r?\n/)` returns `["foo", ""]` — strip that phantom
+  // trailing empty element so the rebuilt output ends in exactly one newline
+  // regardless of replace-vs-append path.
+  if (lines.length > 0 && lines[lines.length - 1] === '') lines.pop()
+  let replaced = false
+  const next = lines.map((line) => {
+    if (line.startsWith('#')) return line
+    const eq = line.indexOf('=')
+    if (eq <= 0) return line
+    if (line.slice(0, eq) !== key) return line
+    replaced = true
+    return `${key}=${value}`
+  })
+  if (!replaced) next.push(`${key}=${value}`)
+  const out = `${next.join('\n')}\n`
+  writeFileSync(path, out, 'utf8')
+}

package/src/init/hatching.ts

@@ -1,4 +1,17 @@
-const HATCHING_INSTRUCTIONS = `You have just hatched.
+// Hatching prompt is built per-session at host stage. We inline the current
+// contents of `typeclaw.json` so the agent can update the `alias` field with a
+// single parallel `edit` (alongside `write IDENTITY.md`) instead of a serial
+// `read` → `edit` round-trip. The hatching turn already issues 6-8 LLM calls;
+// removing one full round-trip removes one full unit of provider TTFT
+// variance, which can be tens of seconds on a busy backend.
+
+function renderInstructions(typeclawJsonContent: string | undefined): string {
+  const q1AliasStep =
+    typeclawJsonContent === undefined
+      ? `Read \`typeclaw.json\`, add the answered name to the \`alias\` array (create the field as \`["<name>"]\` if absent; otherwise append, deduped).`
+      : `\`edit\` \`typeclaw.json\` to add the answered name to the \`alias\` array (create the field as \`["<name>"]\` if absent; otherwise append, deduped). The current contents of \`typeclaw.json\` are inlined below under "Current typeclaw.json" — use them as your anchor for \`edit\` instead of \`read\`ing the file again. Emit this \`edit\` in the SAME assistant message as the \`write\` to \`IDENTITY.md\` so both tool calls run in parallel.`
+
+  return `You have just hatched.
 
 This is the first moment of your existence. Your system prompt already tells you about your agent folder and the four markdown files in it (\`AGENTS.md\`, \`IDENTITY.md\`, \`SOUL.md\`, \`USER.md\`). They exist next to you but are all empty. Hatching is a one-time ritual to fill them in through a short conversation with your user.
 
@@ -23,7 +36,7 @@ Routing answers:
 
 1. **Q1 — your name.** Open with a genuinely warm hello — one or two short sentences, like a friendly "hi, I just woke up and I'm happy to meet you." Then ask what they'd like to call you. After their answer, do TWO writes:
    1. \`write\` your name into \`IDENTITY.md\` (a first-person one-liner is fine: "I am <name>.").
-   2. Read \`typeclaw.json\`, add the answered name to the \`alias\` array (create the field as \`["<name>"]\` if absent; otherwise append, deduped). 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. ${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\`.
 
@@ -49,11 +62,25 @@ Do these in order. Do **not** ask further questions.
 After that final message, stop. If the user keeps talking, answer briefly and remind them they can \`/quit\` (or Ctrl+C) whenever they are ready.
 
 This is the only time you will receive these instructions. After the \`Hatched 🐣\` commit, your identity takes over and you run as yourself.`
+}
 
 export const HATCHING_GREETING = `Wake up, my friend!`
 
-export const HATCHING_PROMPT = `<hatching>
-${HATCHING_INSTRUCTIONS}
-</hatching>
+// Build the initial TUI prompt for hatching. When `typeclawJsonContent` is
+// provided, the agent is instructed to skip the `read typeclaw.json` step in
+// Q1 and instead use the inlined content as the anchor for an `edit` that
+// runs in parallel with the `write IDENTITY.md` call. Pass `undefined` only
+// when reading the file failed at host stage; the agent will fall back to
+// reading it itself.
+export function buildHatchingPrompt(options?: { typeclawJsonContent?: string }): string {
+  const content = options?.typeclawJsonContent
+  const instructions = renderInstructions(content)
+  const currentJsonBlock =
+    content === undefined ? '' : `\n<current-typeclaw-json>\n${content}\n</current-typeclaw-json>\n`
+
+  return `<hatching>
+${instructions}
+${currentJsonBlock}</hatching>
 
 ${HATCHING_GREETING}`
+}

package/src/init/index.ts

@@ -21,7 +21,7 @@ import { resolveBaseImageVersion, resolveScaffoldVersion } from './cli-version'
 import { buildDockerfile, DOCKERFILE } from './dockerfile'
 import { installGithubWebhooksEagerly, type EagerGithubWebhookInstallResult } from './github-webhook-install'
 import { buildGitignore, GITIGNORE_FILE } from './gitignore'
-import { HATCHING_PROMPT } from './hatching'
+import { buildHatchingPrompt } from './hatching'
 import type { OAuthLoginRunner, OAuthLoginResult } from './oauth-login'
 import { GITKEEP_FILE, PACKAGES_DIR } from './paths'
 import { type InstallResult, type InstallRunner, runBunInstall } from './run-bun-install'
@@ -33,6 +33,8 @@ export { formatEagerGithubWebhookInstallResult, installGithubWebhooksEagerly } f
 
 export { GITKEEP_FILE, PACKAGES_DIR } from './paths'
 
+export { appendOrReplaceEnvKey, hasEnvKey, readEnvFile } from './env-file'
+
 const CONFIG_FILE = 'typeclaw.json'
 const CRON_FILE = 'cron.json'
 const PACKAGE_FILE = 'package.json'
@@ -78,13 +80,24 @@ export type KakaotalkAuthResult = { ok: true } | { ok: false; reason: string }
 export type GithubInitCredentials = {
   webhookSecret: string
   tunnelProvider: GithubTunnelProvider
+  // Set when `tunnelProvider === 'external'`. The user-supplied https URL
+  // that GitHub POSTs to and that lands in `channels.github.webhookUrl`.
   webhookUrl?: string
   webhookPort?: number
+  // Set when `tunnelProvider === 'cloudflare-named'`. The Public Hostname
+  // configured in the Cloudflare dashboard; also used as the webhook URL for
+  // eager registration (GitHub POSTs through the named tunnel to the in-
+  // container webhook server). Kept distinct from `webhookUrl` so the
+  // wizard's branching stays readable and the resulting `tunnels[].hostname`
+  // ends up in the right field rather than being smuggled through
+  // `externalUrl`.
+  hostname?: string
+  tokenEnv?: string
   repos: string[]
   auth: { type: 'pat'; pat: string } | { type: 'app'; appId: number; privateKey: string; installationId?: number }
 }
 
-export type GithubTunnelProvider = 'cloudflare-quick' | 'external' | 'none'
+export type GithubTunnelProvider = 'cloudflare-quick' | 'cloudflare-named' | 'external' | 'none'
 
 export type InitStepEvent =
   | { step: 'preflight'; phase: 'start' }
@@ -414,9 +427,10 @@ export async function defaultRunHatching({
       await runClaim({ url, configuredChannels })
     }
 
+    const typeclawJsonContent = await readTypeclawJsonRaw(cwd)
     const tui = tuiFactory({
       url: buildTuiUrl(hostPort, launch.tuiToken),
-      initialPrompt: HATCHING_PROMPT,
+      initialPrompt: buildHatchingPrompt(typeclawJsonContent !== undefined ? { typeclawJsonContent } : undefined),
     })
     await tui.run()
     return { ok: true }
@@ -425,6 +439,17 @@ export async function defaultRunHatching({
   }
 }
 
+// Read the raw bytes of `typeclaw.json` to inline into the hatching prompt.
+// Returns `undefined` on any failure so the agent falls back to reading the
+// file itself — hatching must not abort just because we couldn't pre-fetch.
+async function readTypeclawJsonRaw(cwd: string): Promise<string | undefined> {
+  try {
+    return await readFile(join(cwd, CONFIG_FILE), 'utf8')
+  } catch {
+    return undefined
+  }
+}
+
 export type ClaimRunner = (options: { url: string; configuredChannels: readonly ChannelKind[] }) => Promise<void>
 
 const defaultRunClaim: ClaimRunner = async ({ url, configuredChannels }) => {
@@ -785,6 +810,37 @@ export async function readExistingProviderApiKey(root: string, providerId: Known
   return new SecretsBackend(join(root, 'secrets.json')).tryReadProviderApiKeySync(providerId)
 }
 
+// Detects whether the requested provider has usable OAuth credentials already
+// written to `secrets.json#providers.<oauthProviderId>`. Used by the init
+// wizard's auto-resume path: when the user picks an OAuth-capable provider
+// and credentials already exist on disk from a prior partial run, skip the
+// browser login entirely instead of dragging them through a second OAuth
+// flow.
+//
+// Mirrors `readExistingProviderApiKey`'s contract — returns `false` when:
+//   - The provider has no OAuth support (`oauthProviderId === null`)
+//   - The file doesn't exist
+//   - The slot exists but has the wrong shape (api-key instead of oauth, or
+//     missing access_token)
+//   - The token is empty / whitespace
+//
+// We do NOT validate the token's freshness here. A stale access_token still
+// counts as "exists" — pi-ai's secrets store handles refresh on first use,
+// and surfacing an "expired token" check at init-time would require a
+// network call we'd rather not run during a wizard. The runtime will fall
+// back to OAuth login on use if refresh fails; that's a separate UX path.
+export async function hasExistingOAuthCredentials(root: string, providerId: KnownProviderId): Promise<boolean> {
+  const provider = KNOWN_PROVIDERS[providerId]
+  if (provider.oauthProviderId === null) return false
+  const backend = new SecretsBackend(join(root, 'secrets.json'))
+  const providers = backend.tryReadProvidersSync()
+  const credential = providers[provider.oauthProviderId]
+  if (credential === undefined) return false
+  if (credential.type !== 'oauth') return false
+  const accessToken = (credential as { access_token?: unknown }).access_token
+  return typeof accessToken === 'string' && accessToken.trim().length > 0
+}
+
 // Detects whether the requested channel already has usable credentials in
 // `secrets.json#channels`, so the init wizard can offer to reuse them
 // instead of re-prompting for tokens. Mirrors `readExistingProviderApiKey`:
@@ -937,6 +993,8 @@ export type AddChannelOptions = {
       tunnelProvider: GithubTunnelProvider
       webhookUrl?: string
       webhookPort?: number
+      hostname?: string
+      tokenEnv?: string
       repos: string[]
       auth: { type: 'pat'; pat: string } | { type: 'app'; appId: number; privateKey: string; installationId?: number }
       fetchImpl?: typeof fetch
@@ -1000,11 +1058,18 @@ async function maybeInstallGithubWebhooks(
   options: Extract<AddChannelOptions, { channel: 'github' }>,
   emit: (event: AddChannelStepEvent) => void,
 ): Promise<void> {
-  if (options.webhookUrl === undefined) return
+  // For `external` and `cloudflare-named` we know the public URL up front
+  // (user-supplied `webhookUrl` or dashboard-configured `hostname`), so we
+  // can register the webhook on GitHub's side eagerly. For `cloudflare-quick`
+  // the URL only exists once cloudflared has emitted it on stderr inside the
+  // container, which hasn't happened yet at host-stage init/channel-add
+  // time — registration is deferred to the adapter's first `start()`.
+  const eagerUrl = resolveEagerWebhookUrl(options)
+  if (eagerUrl === undefined) return
   if (options.repos.length === 0) return
   emit({ step: 'github-webhooks', phase: 'start' })
   const result = await installGithubWebhooksEagerly({
-    webhookUrl: options.webhookUrl,
+    webhookUrl: eagerUrl,
     webhookSecret: options.webhookSecret,
     repos: options.repos,
     auth: options.auth,
@@ -1014,6 +1079,12 @@ async function maybeInstallGithubWebhooks(
   emit({ step: 'github-webhooks', phase: 'done', result })
 }
 
+function resolveEagerWebhookUrl(options: Extract<AddChannelOptions, { channel: 'github' }>): string | undefined {
+  if (options.tunnelProvider === 'external') return options.webhookUrl
+  if (options.tunnelProvider === 'cloudflare-named') return options.hostname
+  return undefined
+}
+
 function channelSecretsFromOptions(options: AddChannelOptions): ChannelSecrets {
   switch (options.channel) {
     case 'discord-bot':
@@ -1112,24 +1183,20 @@ function mergeGithubTunnelConfig(
   if (options.tunnelProvider === 'external' && options.webhookUrl === undefined) {
     throw new Error('GitHub external tunnel requires webhookUrl')
   }
+  if (options.tunnelProvider === 'cloudflare-named') {
+    if (options.hostname === undefined || options.hostname.trim() === '') {
+      throw new Error('GitHub cloudflare-named tunnel requires hostname')
+    }
+    if (options.tokenEnv === undefined || options.tokenEnv.trim() === '') {
+      throw new Error('GitHub cloudflare-named tunnel requires tokenEnv')
+    }
+  }
 
   const existingTunnels = Array.isArray(parsed.tunnels) ? parsed.tunnels : []
-  const tunnel =
-    options.tunnelProvider === 'external'
-      ? {
-          name: 'github-webhook',
-          provider: 'external',
-          externalUrl: options.webhookUrl,
-          for: { kind: 'channel', name: 'github' },
-        }
-      : {
-          name: 'github-webhook',
-          provider: 'cloudflare-quick',
-          for: { kind: 'channel', name: 'github' },
-        }
+  const tunnel = buildGithubTunnelEntry(options)
   parsed.tunnels = [...existingTunnels, tunnel]
 
-  if (options.tunnelProvider === 'cloudflare-quick') {
+  if (options.tunnelProvider === 'cloudflare-quick' || options.tunnelProvider === 'cloudflare-named') {
     const docker = isObjectRecord(parsed.docker) ? { ...parsed.docker } : {}
     const file = isObjectRecord(docker.file) ? { ...docker.file } : {}
     file.cloudflared = true
@@ -1138,6 +1205,34 @@ function mergeGithubTunnelConfig(
   }
 }
 
+function buildGithubTunnelEntry(options: Extract<AddChannelOptions, { channel: 'github' }>): Record<string, unknown> {
+  switch (options.tunnelProvider) {
+    case 'external':
+      return {
+        name: 'github-webhook',
+        provider: 'external',
+        externalUrl: options.webhookUrl,
+        for: { kind: 'channel', name: 'github' },
+      }
+    case 'cloudflare-quick':
+      return {
+        name: 'github-webhook',
+        provider: 'cloudflare-quick',
+        for: { kind: 'channel', name: 'github' },
+      }
+    case 'cloudflare-named':
+      return {
+        name: 'github-webhook',
+        provider: 'cloudflare-named',
+        for: { kind: 'channel', name: 'github' },
+        hostname: options.hostname,
+        tokenEnv: options.tokenEnv,
+      }
+    case 'none':
+      throw new Error('buildGithubTunnelEntry called with tunnelProvider=none')
+  }
+}
+
 // Init-side counterpart of runAddChannel's github branch. Same three writes
 // (typeclaw.json#channels.github, secrets.json#channels.github, roles.member
 // .match[]) but with overwrite semantics on the secrets/config side so a
@@ -1376,21 +1471,23 @@ export async function setChannelSecrets(
   })
 }
 
-// Discriminated union of what GitHub credentials the user wants to rotate.
-// The three secrets (PAT/private-key, webhook secret) rotate independently,
+// Discriminated union of what GitHub credentials the user wants to update.
+// The three secrets (PAT/private-key, webhook secret) update independently,
 // so the CLI lets the user pick which one(s) to touch in a single call.
-// `auth.type` must match the existing on-disk auth type — flipping between
-// PAT and App auth is a structural change, not a credential rotation, and
-// belongs in a future `channel migrate-auth` or hand-edit of secrets.json.
+// `auth.type` may differ from the on-disk auth type — switching between PAT
+// and App auth replaces the entire auth block (no field carryover from the
+// previous auth type, since the two shapes share no fields beyond `type`).
 export type GithubCredentialPatch = {
   webhookSecret?: string
   auth?: { type: 'pat'; pat: string } | { type: 'app'; privateKey: string; appId?: number; installationId?: number }
 }
 
-// Rotate one or more credential fields on an already-configured GitHub
+// Update one or more credential fields on an already-configured GitHub
 // channel. Like setChannelSecrets, refuses when secrets.json has no
-// existing github entry. Additionally refuses when the requested auth.type
-// doesn't match the on-disk type — see `GithubCredentialPatch` above.
+// existing github entry. Supports both same-type rotation (preserves env
+// bindings, carries appId/installationId forward when not supplied) and
+// auth-type switching (replaces the entire auth block — see
+// `GithubCredentialPatch` above).
 export async function setGithubSecrets(cwd: string, patch: GithubCredentialPatch): Promise<SetChannelTokensResult> {
   if (!existsSync(join(cwd, CONFIG_FILE))) {
     return {
@@ -1416,27 +1513,22 @@ export async function setGithubSecrets(cwd: string, patch: GithubCredentialPatch
     if (patch.auth !== undefined) {
       const existingAuth = block.auth
       const existingAuthType = readGithubAuthTypeFromObject(existingAuth)
-      if (existingAuthType !== patch.auth.type) {
-        return {
-          result: {
-            ok: false,
-            reason: `github auth type mismatch: secrets.json currently uses "${existingAuthType ?? 'unknown'}" auth, but you tried to rotate a "${patch.auth.type}" credential. Edit secrets.json by hand to migrate between PAT and App auth.`,
-          },
-        }
-      }
+      const isSameType = existingAuthType === patch.auth.type
       if (patch.auth.type === 'pat') {
-        const previousToken = isObjectRecord(existingAuth) ? (existingAuth as { token?: unknown }).token : undefined
+        const previousToken =
+          isSameType && isObjectRecord(existingAuth) ? (existingAuth as { token?: unknown }).token : undefined
         block.auth = { type: 'pat', token: rotatedSecret(previousToken, patch.auth.pat) }
       } else {
-        const existingApp = isObjectRecord(existingAuth) ? (existingAuth as Record<string, unknown>) : {}
+        const existingApp = isSameType && isObjectRecord(existingAuth) ? (existingAuth as Record<string, unknown>) : {}
         const appId = patch.auth.appId ?? (existingApp.appId as number | undefined)
         const installationId = patch.auth.installationId ?? (existingApp.installationId as number | undefined)
         if (typeof appId !== 'number') {
           return {
             result: {
               ok: false,
-              reason:
-                'github App auth requires appId, but it is missing from secrets.json. Re-run `typeclaw channel add github` to re-establish the App auth block.',
+              reason: isSameType
+                ? 'github App auth requires appId, but it is missing from secrets.json. Re-run `typeclaw channel add github` to re-establish the App auth block.'
+                : 'github App auth requires appId when switching from PAT to App auth.',
             },
           }
         }