typeclaw 0.3.0 → 0.4.0

package/src/cron/list.ts

@@ -0,0 +1,105 @@
+import type { RegisteredCronJob } from '@/plugin'
+
+import { computeNextFire } from './scheduler'
+import type { CronJob } from './schema'
+
+// `plugin` carries `localId` (the original key on `definePlugin({ cronJobs })`)
+// so callers can render "memory.dreaming" rather than the synthetic
+// `__plugin_memory_dreaming` global id the scheduler uses internally.
+export type CronListSource = { kind: 'user' } | { kind: 'plugin'; pluginName: string; localId: string }
+
+// Display-oriented snapshot of a CronJob, separated from CronJob itself
+// so the WS wire shape stays stable as CronJob accretes runtime-only
+// fields (scheduledByOrigin, future description, etc.).
+export type CronListEntry = {
+  id: string
+  source: CronListSource
+  kind: 'prompt' | 'exec' | 'handler'
+  schedule: string
+  timezone: string | undefined
+  enabled: boolean
+  scheduledByRole: string | undefined
+  // null when cron-parser rejects `schedule` — keeps such rows visible
+  // in the list with the original error preserved in `scheduleError`,
+  // rather than dropping them silently as the scheduler would.
+  nextFireMs: number | null
+  scheduleError: string | undefined
+  prompt: string | undefined
+  subagent: string | undefined
+  command: readonly string[] | undefined
+}
+
+export type AggregateCronListOptions = {
+  userJobs: readonly CronJob[]
+  // Registered entries (not flat CronJob[]) so each row can be attributed
+  // to its plugin + localId without re-parsing the global id.
+  pluginJobs: readonly RegisteredCronJob[]
+  now: number
+}
+
+export function aggregateCronList(opts: AggregateCronListOptions): CronListEntry[] {
+  const entries: CronListEntry[] = []
+  for (const job of opts.userJobs) {
+    entries.push(toEntry(job, { kind: 'user' }, opts.now))
+  }
+  for (const reg of opts.pluginJobs) {
+    entries.push(toEntry(reg.job, { kind: 'plugin', pluginName: reg.pluginName, localId: reg.localId }, opts.now))
+  }
+  // Sort by next-fire time ascending so the soonest-firing job is at the
+  // top. Jobs with a null nextFireMs (parse errors) sort to the bottom
+  // so the human-readable list keeps the actionable rows first. Disabled
+  // jobs still get a nextFireMs computed — they appear in the list with
+  // an "(disabled)" badge but their position reflects when they WOULD
+  // have fired had they been enabled.
+  entries.sort(compareByNextFire)
+  return entries
+}
+
+function toEntry(job: CronJob, source: CronListSource, now: number): CronListEntry {
+  const fire = computeNextFire(job, now)
+  const base = {
+    id: job.id,
+    source,
+    schedule: job.schedule,
+    timezone: job.timezone,
+    enabled: job.enabled,
+    scheduledByRole: job.scheduledByRole,
+    nextFireMs: fire.ok ? fire.nextFire : null,
+    scheduleError: fire.ok ? undefined : fire.reason,
+  } as const
+  if (job.kind === 'prompt') {
+    return {
+      ...base,
+      kind: 'prompt',
+      prompt: job.prompt,
+      subagent: job.subagent,
+      command: undefined,
+    }
+  }
+  if (job.kind === 'exec') {
+    return {
+      ...base,
+      kind: 'exec',
+      prompt: undefined,
+      subagent: undefined,
+      command: job.command,
+    }
+  }
+  // Handler jobs carry a function reference, not a serializable payload.
+  // Surface the row so the list stays complete; leave action fields undefined.
+  return {
+    ...base,
+    kind: 'handler',
+    prompt: undefined,
+    subagent: undefined,
+    command: undefined,
+  }
+}
+
+function compareByNextFire(a: CronListEntry, b: CronListEntry): number {
+  if (a.nextFireMs === null && b.nextFireMs === null) return a.id.localeCompare(b.id)
+  if (a.nextFireMs === null) return 1
+  if (b.nextFireMs === null) return -1
+  if (a.nextFireMs !== b.nextFireMs) return a.nextFireMs - b.nextFireMs
+  return a.id.localeCompare(b.id)
+}

package/src/cron/scheduler.ts

@@ -177,12 +177,21 @@ function jobFingerprint(job: CronJob): string {
 
 function jobPayload(job: CronJob): unknown {
   if (job.kind === 'prompt') return { prompt: job.prompt, subagent: job.subagent ?? null, payload: job.payload ?? null }
-  return job.command
+  if (job.kind === 'exec') return job.command
+  // Use the handler's source as the discriminator. A constant placeholder
+  // would make every handler fingerprint identically, so a plugin reload
+  // that replaces the handler with a new implementation would be classified
+  // as `unchanged` by `diff()` — the old function reference would keep
+  // firing forever. `Function.prototype.toString()` returns the function's
+  // declared source (deterministic per declaration site, changes when the
+  // plugin module is re-imported with edits), which is the cheapest stable
+  // discriminator without keeping a separate identity Map. JSON-safe.
+  return { handler: String(job.handler) }
 }
 
-type ComputeNextFireResult = { ok: true; nextFire: number } | { ok: false; reason: string }
+export type ComputeNextFireResult = { ok: true; nextFire: number } | { ok: false; reason: string }
 
-function computeNextFire(job: CronJob, now: number): ComputeNextFireResult {
+export function computeNextFire(job: CronJob, now: number): ComputeNextFireResult {
   try {
     const expr = CronExpressionParser.parse(job.schedule, {
       currentDate: new Date(now),

package/src/cron/schema.ts

@@ -3,6 +3,7 @@ import { z } from 'zod'
 
 import type { SubagentRegistry } from '@/agent/subagents'
 import { validateSubagentPayload } from '@/agent/subagents'
+import type { CronHandlerContext } from '@/plugin/types'
 
 const idPattern = /^[a-zA-Z0-9_-]+$/
 
@@ -42,9 +43,16 @@ export const cronFileSchema = z.object({
   jobs: z.array(cronJobSchema).default([]),
 })
 
-export type CronJob = z.infer<typeof cronJobSchema>
-export type PromptJob = Extract<CronJob, { kind: 'prompt' }>
-export type ExecJob = Extract<CronJob, { kind: 'exec' }>
+export type ParsedCronJob = z.infer<typeof cronJobSchema>
+export type PromptJob = Extract<ParsedCronJob, { kind: 'prompt' }>
+export type ExecJob = Extract<ParsedCronJob, { kind: 'exec' }>
+
+export type HandlerJob = z.infer<typeof baseJob> & {
+  kind: 'handler'
+  handler: (ctx: CronHandlerContext) => Promise<void>
+}
+
+export type CronJob = ParsedCronJob | HandlerJob
 export type CronFile = z.infer<typeof cronFileSchema>
 
 export type ParseCronResult = { ok: true; file: CronFile } | { ok: false; reason: string }

package/src/doctor/checks.ts

@@ -35,7 +35,6 @@ export function buildStaticChecks(opts: { dockerExec?: DockerExec } = {}): Docto
     agentFolderNodeModules(),
     agentFolderGitRepo(),
     configValid(),
-    configBundledProfiles(),
     hostdHomeWritable(),
     hostdReachable(),
     hostdRegistration(),
@@ -215,55 +214,6 @@ function configValid(): DoctorCheck {
   }
 }
 
-// Warns (not errors) when a model profile that a bundled subagent prefers is
-// absent from `models`. Bundled subagents fall back to `default` silently
-// today, but the operator likely declared a `fast`/`deep`/`vision` model in
-// the design discussion's tier scheme expecting the bundled subagents to
-// pick them up. This check surfaces the gap once at `typeclaw doctor` time
-// instead of leaving it buried in container logs (where the rate-limited
-// fallback warning lives).
-//
-// We deliberately limit this to known bundled profiles (memory-logger=fast,
-// dreaming=deep, multimodal-looker=vision). Plugin-contributed subagents
-// would require loading the plugin registry — a heavyweight async path
-// that doesn't belong in doctor's static check surface.
-const BUNDLED_PROFILES: ReadonlyArray<{ profile: string; subagent: string }> = [
-  { profile: 'fast', subagent: 'memory-logger' },
-  { profile: 'deep', subagent: 'dreaming' },
-  { profile: 'vision', subagent: 'multimodal-looker (via look_at tool)' },
-]
-
-function configBundledProfiles(): DoctorCheck {
-  return {
-    name: 'config.bundled-profiles',
-    category: 'config',
-    description: 'bundled subagent profiles (`fast`, `deep`, `vision`) declared in models',
-    applies: (ctx) => ctx.hasAgentFolder,
-    async run(ctx) {
-      const validation = validateConfig(ctx.cwd)
-      if (!validation.ok) {
-        return { status: 'ok', message: 'skipped (config.valid will report the underlying error)' }
-      }
-      const config = loadConfigSync(ctx.cwd)
-      const declared = new Set(Object.keys(config.models))
-      const missing = BUNDLED_PROFILES.filter((p) => !declared.has(p.profile))
-      if (missing.length === 0) {
-        return { status: 'ok', message: 'all bundled subagent profiles declared' }
-      }
-      return {
-        status: 'warning',
-        message: `${missing.length} bundled profile(s) missing; will fall back to \`default\``,
-        details: missing.map(
-          (m) => `${m.profile}: used by ${m.subagent}; declare \`models.${m.profile}\` in typeclaw.json to override`,
-        ),
-        fix: {
-          description: 'Add the missing profile(s) under `models` in typeclaw.json. See the typeclaw-config skill.',
-        },
-      }
-    },
-  }
-}
-
 function hostdHomeWritable(): DoctorCheck {
   return {
     name: 'hostd.home-writable',

package/src/init/dockerfile.ts

@@ -56,6 +56,19 @@ export const CURL_IMPERSONATE_SHA256_ARM64 = '6766bc67fd3e8e2313875f32b36b5a3fab
 // the impersonation to whatever `curl_chrome` resolves to.
 export const CURL_IMPERSONATE_PROFILE = 'chrome136'
 
+// cloudflared powers `cloudflare-quick` tunnels. Pinned-version + per-arch
+// SHA256 mirrors the curl-impersonate pattern above: bumping requires updating
+// all three constants in the same commit, and the build fails loudly at
+// `sha256sum -c` if either hash is wrong for the version. To bump: pick a
+// release from https://github.com/cloudflare/cloudflared/releases, then
+//   curl -fsSLO .../cloudflared-linux-amd64 && shasum -a 256 cloudflared-linux-amd64
+// for each architecture. The version literal is the release tag exactly as it
+// appears on GitHub (no `v` prefix).
+export const CLOUDFLARED_VERSION = '2025.5.0'
+export const CLOUDFLARED_SHA256_AMD64 = 'a62266fd02041374f1fca0d85694aafdf7e26e171a314467356b471d4ebb2393'
+export const CLOUDFLARED_SHA256_ARM64 = '47e55e6eba2755239f641c2c4f89878643ac0d9eaa127a6c84a2cb43fa2e0f03'
+export const CLOUDFLARED_RELEASE_URL_BASE = 'https://github.com/cloudflare/cloudflared/releases/download'
+
 export const TYPECLAW_ENTRYPOINT_PATH = '/usr/local/bin/typeclaw-entrypoint'
 
 // IPv4 networks the container is forbidden to egress to when
@@ -283,9 +296,11 @@ RUN echo "${encoded}" | base64 -d > ${TYPECLAW_ENTRYPOINT_PATH} \\
 // names are the trixie-renamed variants from the 64-bit time_t ABI
 // transition; SONAMEs (libglib-2.0.so.0 etc.) are unchanged. Packages
 // without t64 here have no t64 sibling on trixie — verified against
-// packages.debian.org/trixie. Fonts are intentionally omitted: the
-// reported failure is launch-time linker errors, not rendering glyphs;
-// font packages (esp. fonts-noto-cjk) cost ~50MB+ for no launch impact.
+// packages.debian.org/trixie. Fonts are intentionally omitted from this
+// list: the failure these packages address is launch-time linker errors,
+// not rendering glyphs. CJK glyph rendering is a separate concern handled
+// by the `cjkFonts` toggle (see CJK_FONTS_PACKAGE / APT_FEATURES below),
+// which layers `fonts-noto-cjk` on top via the toggle apt install path.
 export const CHROME_RUNTIME_APT_PACKAGES_AMD64 = [
   'libasound2t64',
   'libatk-bridge2.0-0t64',
@@ -310,17 +325,26 @@ export const CHROME_RUNTIME_APT_PACKAGES_AMD64 = [
   'libxrandr2',
 ] as const
 
+// `fonts-noto-cjk` provides CJK glyphs for Chromium-rendered output
+// (screenshots, page.pdf()). Without it CJK text in agent-browser output
+// renders as `.notdef` tofu boxes. Treated as a toggle apt package (like
+// gh/tmux) rather than a base-image staple so users with `cjkFonts: false`
+// genuinely skip the ~56MB layer; baking into the base image would force
+// every GHCR-base user to ship the fonts regardless of their opt-out.
+export const CJK_FONTS_PACKAGE = 'fonts-noto-cjk'
+
 type AptFeature = {
   toAptArgs: (toggle: DockerfileFeatureToggle) => string[]
 }
 
-const APT_FEATURES: Record<'ffmpeg' | 'gh' | 'tmux' | 'python', AptFeature> = {
+const APT_FEATURES: Record<'ffmpeg' | 'gh' | 'tmux' | 'python' | 'cjkFonts', AptFeature> = {
   ffmpeg: { toAptArgs: (v) => singlePackageArgs('ffmpeg', v) },
   gh: { toAptArgs: (v) => singlePackageArgs('gh', v) },
   tmux: { toAptArgs: (v) => singlePackageArgs('tmux', v) },
   python: {
     toAptArgs: (v) => (v === true ? ['python3', 'python3-pip', 'python3-venv', 'python-is-python3'] : []),
   },
+  cjkFonts: { toAptArgs: (v) => (v === true ? [CJK_FONTS_PACKAGE] : []) },
 }
 
 export function buildDockerfile(
@@ -329,13 +353,14 @@ export function buildDockerfile(
 ): string {
   const toggleAptArgs = collectToggleAptArgs(config)
   const ghKeyringLayer = renderGhKeyringLayer(config.gh)
+  const cloudflaredLayer = renderCloudflaredLayer(config.cloudflared)
   const customLines = renderCustomDockerfileLines(config.append)
   const baseImageVersion = options.baseImageVersion ?? null
 
   const fromAndHeavyLayers =
     baseImageVersion !== null
-      ? renderVersionedHead(baseImageVersion, ghKeyringLayer, toggleAptArgs)
-      : renderInlineHead(ghKeyringLayer, toggleAptArgs)
+      ? renderVersionedHead(baseImageVersion, ghKeyringLayer, toggleAptArgs, cloudflaredLayer)
+      : renderInlineHead(ghKeyringLayer, toggleAptArgs, cloudflaredLayer)
 
   return `${BUILDKIT_HEADER}
 # AUTOGENERATED by typeclaw — do not edit.
@@ -377,7 +402,12 @@ CMD ["run"]
 // npm + `typeclaw start --build` immediately, instead of being blocked on a
 // fresh base-image release. The base image's copy is harmlessly overwritten
 // by this RUN — same path, same chmod.
-function renderVersionedHead(baseImageVersion: string, ghKeyringLayer: string, toggleAptArgs: string[]): string {
+function renderVersionedHead(
+  baseImageVersion: string,
+  ghKeyringLayer: string,
+  toggleAptArgs: string[],
+  cloudflaredLayer: string,
+): string {
   const toggleAptLayer = toggleAptArgs.length === 0 ? '' : `${renderToggleAptInstallLayer(toggleAptArgs)}\n\n`
   return `FROM ${GHCR_BASE_IMAGE_REPO}:${baseImageVersion}
 
@@ -385,7 +415,7 @@ WORKDIR /agent
 
 ARG TARGETARCH
 
-${ghKeyringLayer}${toggleAptLayer}${renderEntrypointShimLayer()}
+${ghKeyringLayer}${toggleAptLayer}${cloudflaredLayer}${renderEntrypointShimLayer()}
 
 `
 }
@@ -394,7 +424,7 @@ ${ghKeyringLayer}${toggleAptLayer}${renderEntrypointShimLayer()}
 // dev-mode runs (typeclaw installed via file: / link: spec) where the
 // matching :version GHCR tag does not yet exist, and by the test suite to
 // keep coverage of the full-stack layers independent of GHCR availability.
-function renderInlineHead(ghKeyringLayer: string, toggleAptArgs: string[]): string {
+function renderInlineHead(ghKeyringLayer: string, toggleAptArgs: string[], cloudflaredLayer: string): string {
   const baselineAndToggleArgs = [...BASELINE_APT_PACKAGES, ...toggleAptArgs]
   return `${FROM_AND_WORKDIR}
 
@@ -436,7 +466,23 @@ ${LAYER_4_AGENT_BROWSER_INSTALL}
 
 ${LAYER_5_CHROME_FOR_TESTING}
 
-${renderEntrypointShimLayer()}
+${cloudflaredLayer}${renderEntrypointShimLayer()}
+
+`
+}
+
+function renderCloudflaredLayer(enabled: boolean): string {
+  if (!enabled) return ''
+  return `# Layer 5.5 (optional): pinned cloudflared for cloudflare-quick tunnels.
+RUN ARCH_BIN="$(if [ "$TARGETARCH" = "arm64" ]; then echo arm64; else echo amd64; fi)" \
+ && ARCH_SHA="$(if [ "$TARGETARCH" = "arm64" ]; then echo ${CLOUDFLARED_SHA256_ARM64}; else echo ${CLOUDFLARED_SHA256_AMD64}; fi)" \
+ && cd /tmp \
+ && curl -fsSL -o cloudflared \
+      "${CLOUDFLARED_RELEASE_URL_BASE}/${CLOUDFLARED_VERSION}/cloudflared-linux-\${ARCH_BIN}" \
+ && echo "\${ARCH_SHA}  cloudflared" | sha256sum -c - \
+ && chmod +x cloudflared \
+ && mv cloudflared /usr/local/bin/cloudflared \
+ && /usr/local/bin/cloudflared --version > /dev/null
 
 `
 }
@@ -444,7 +490,7 @@ ${renderEntrypointShimLayer()}
 function renderToggleAptInstallLayer(toggleAptArgs: string[]): string {
   return `# Layer 1 (toggle apt install): packages requested via typeclaw.json
 # #docker.file toggles. Baseline + Chrome runtime libs are already in the
-# base image; this layer only adds gh/tmux/python/ffmpeg if enabled.
+# base image; this layer only adds gh/tmux/python/ffmpeg/cjkFonts if enabled.
 RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \\
     --mount=type=cache,target=/var/lib/apt/lists,sharing=locked \\
     apt-get update \\
@@ -570,12 +616,12 @@ RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \\
     fi`
 
 function defaultConfig(): DockerfileConfig {
-  return { ffmpeg: false, gh: true, python: true, tmux: true, append: [] }
+  return { ffmpeg: false, gh: true, python: true, tmux: true, cjkFonts: true, cloudflared: true, append: [] }
 }
 
 function collectToggleAptArgs(config: DockerfileConfig): string[] {
   const args: string[] = []
-  for (const key of ['ffmpeg', 'gh', 'python', 'tmux'] as const) {
+  for (const key of ['ffmpeg', 'gh', 'python', 'tmux', 'cjkFonts'] as const) {
     args.push(...APT_FEATURES[key].toAptArgs(config[key]))
   }
   return args

package/src/init/ensure-deps.ts

@@ -15,24 +15,35 @@ export type EnsureDepsOptions = {
   cwd: string
   install?: InstallRunner
   detect?: (cwd: string) => Promise<readonly string[]>
+  // Skip the pre-install drift detection and run `bun install --force`
+  // unconditionally. Used by `typeclaw start --build` when the agent declares
+  // typeclaw via `file:` or `link:`: bun's file-dep cache otherwise treats
+  // unchanged name+version as a cache hit even after the source on disk has
+  // changed, so the post-install re-detect at the bottom (the silent-no-op
+  // guard) stays — `--force` does NOT excuse us from verifying the install
+  // actually populated the agent's node_modules/.
+  force?: boolean
 }
 
 export async function ensureDepsInstalled(options: EnsureDepsOptions): Promise<EnsureDepsResult> {
   const { cwd } = options
   const install = options.install ?? runBunInstall
   const detect = options.detect ?? detectMissingDeps
+  const force = options.force ?? false
 
-  const missing = await detect(cwd)
-  if (missing.length === 0) return { ok: true, installed: false }
+  const missing = force ? [] : await detect(cwd)
+  if (!force && missing.length === 0) return { ok: true, installed: false }
 
-  const result = await install(cwd)
+  const result = await install(cwd, { force })
   if (!result.ok) return { ok: false, reason: result.reason, missing }
 
   // Re-probe: `bun install` returns 0 even when a file:-linked dep's own
   // package.json is unreachable (it silently no-ops on the target). Without
   // this check, we'd proceed to `docker run` with a known-broken
   // node_modules/ and the agent would crash with a confusing in-container
-  // `Cannot find package 'x'`.
+  // `Cannot find package 'x'`. This guard remains under `force` too —
+  // --force bypasses the cache but does not guarantee the install actually
+  // landed every declared dep.
   const stillMissing = await detect(cwd)
   if (stillMissing.length > 0) {
     return {

package/src/init/github-webhook-install.ts

@@ -0,0 +1,109 @@
+import { buildAuthStrategy } from '@/channels/adapters/github/auth'
+import { applyManagedPath, buildManagedPath, resolveAgentId } from '@/channels/adapters/github/managed-path'
+import { registerGithubWebhooks, type WebhookRegistrationResult } from '@/channels/adapters/github/webhook-register'
+import { DEFAULT_GITHUB_EVENT_ALLOWLIST } from '@/channels/schema'
+
+import type { GithubInitCredentials } from './index'
+
+// Host-side webhook install for `typeclaw channel add github` (and the
+// init-time GitHub branch). The container-side adapter still re-runs this on
+// every start so a missing/rotated tunnel URL eventually catches up, but
+// doing it eagerly here means the user sees the install succeed at CLI
+// time — no more "I added the channel, why isn't GitHub delivering events?"
+// when the URL is already known (external provider, or a user-set
+// webhookUrl).
+//
+// Only fires when an effective webhook URL is known up front: external
+// tunnel provider, or an explicit `webhookUrl`. Cloudflare quick tunnels
+// don't resolve until cloudflared boots inside the container, so they
+// stay on the existing deferred (tunnel-bridge → restartAdapter) path.
+
+export type EagerGithubWebhookInstallOptions = {
+  webhookUrl: string
+  webhookSecret: string
+  repos: readonly string[]
+  events?: readonly string[]
+  auth: GithubInitCredentials['auth']
+  // Agent folder (or container name). Used to derive a stable webhook URL
+  // path marker so this eager-installed hook is recognizable to the
+  // container-side adapter on every subsequent start, even after the
+  // public URL's hostname rotates. Optional only because legacy direct
+  // callers (host-side init flows on stable user-set webhookUrls) may
+  // omit it; production wiring in src/init/index.ts always passes it.
+  agentDir?: string
+  fetchImpl?: typeof fetch
+}
+
+export type EagerGithubWebhookInstallResult = WebhookRegistrationResult | { error: string; repos: [] }
+
+export async function installGithubWebhooksEagerly(
+  options: EagerGithubWebhookInstallOptions,
+): Promise<EagerGithubWebhookInstallResult> {
+  if (options.repos.length === 0) return { repos: [] }
+
+  let strategy: ReturnType<typeof buildAuthStrategy>
+  try {
+    strategy = buildAuthStrategy({
+      auth: authToSecretBlock(options.auth),
+      ...(options.fetchImpl !== undefined ? { fetchImpl: options.fetchImpl } : {}),
+    })
+  } catch (err) {
+    return { error: describe(err), repos: [] }
+  }
+
+  const managedPath =
+    options.agentDir !== undefined ? buildManagedPath(resolveAgentId({ agentDir: options.agentDir })) : undefined
+  const webhookUrl = managedPath !== undefined ? applyManagedPath(options.webhookUrl, managedPath) : options.webhookUrl
+
+  try {
+    const result = await registerGithubWebhooks({
+      token: () => strategy.token(),
+      webhookUrl,
+      webhookSecret: options.webhookSecret,
+      repos: options.repos,
+      events: options.events ?? DEFAULT_GITHUB_EVENT_ALLOWLIST,
+      ...(managedPath !== undefined ? { managedPath } : {}),
+      ...(options.fetchImpl !== undefined ? { fetchImpl: options.fetchImpl } : {}),
+    })
+    return result
+  } finally {
+    // PatAuthStrategy.dispose() is a no-op and AppAuthStrategy clears its
+    // cached installation token. Either way, releasing it here keeps the
+    // host CLI from holding onto credentials longer than needed.
+    await strategy.dispose().catch(() => {})
+  }
+}
+
+// Bridge the wizard/CLI's plaintext credentials union into the Secret-wrapped
+// shape buildAuthStrategy expects. Plain strings are wrapped as `{ value }`
+// so the underlying PatAuthStrategy resolver doesn't try (and fail) to read
+// from process.env.
+function authToSecretBlock(auth: GithubInitCredentials['auth']) {
+  if (auth.type === 'pat') {
+    return { type: 'pat' as const, token: { value: auth.pat } }
+  }
+  return {
+    type: 'app' as const,
+    appId: auth.appId,
+    privateKey: { value: auth.privateKey },
+    ...(auth.installationId !== undefined ? { installationId: auth.installationId } : {}),
+  }
+}
+
+function describe(err: unknown): string {
+  return err instanceof Error ? err.message : String(err)
+}
+
+export function formatEagerGithubWebhookInstallResult(result: EagerGithubWebhookInstallResult): string {
+  if ('error' in result) return `GitHub webhook install failed: ${result.error}`
+  const created = result.repos.filter((r) => r.action === 'created').length
+  const updated = result.repos.filter((r) => r.action === 'updated').length
+  const failed = result.repos.filter((r) => r.action === 'failed')
+  const parts: string[] = []
+  if (created > 0) parts.push(`${created} created`)
+  if (updated > 0) parts.push(`${updated} updated`)
+  if (failed.length > 0) parts.push(`${failed.length} failed`)
+  const summary = parts.length > 0 ? parts.join(', ') : 'no repos'
+  const tail = failed.length > 0 ? ` (${failed.map((f) => `${f.repo}: ${f.error}`).join('; ')})` : ''
+  return `GitHub webhooks: ${summary}.${tail}`
+}