typeclaw 0.3.1 → 0.5.0

package/src/config/config.ts

@@ -86,6 +86,36 @@ const dockerfileObjectSchema = z.object({
   gh: dockerfileFeatureSchema.default(true),
   python: z.boolean().default(true),
   tmux: dockerfileFeatureSchema.default(true),
+  // `fonts-noto-cjk` is a ~56MB metapackage that makes Chromium render
+  // Korean/Japanese/Chinese glyphs correctly in screenshots, `page.pdf()`,
+  // and any other raster output the agent-browser plugin produces. Default
+  // `true` because the alternative — silent tofu boxes (□□□) in CJK
+  // screenshots — is a confusing failure mode that an agent cannot self-
+  // diagnose from a screenshot it took itself. Opt-out with `cjkFonts:
+  // false` to save the ~56MB on agents that never touch CJK content.
+  // Boolean-only (no version pin) because the package is a metapackage
+  // tracking the upstream Noto release and version pinning offers no
+  // practical value.
+  cjkFonts: z.boolean().default(true),
+  // Opt into the cloudflared layer for `cloudflare-quick` tunnels. Default
+  // `true` so `tunnel add` / `channel add github` with the default Cloudflare
+  // Quick provider works on the next `start` without a separate Dockerfile
+  // edit. Opt-out with `cloudflared: false` to skip the ~35MB binary on
+  // agents that don't use tunnels.
+  cloudflared: z.boolean().default(true),
+  // Install xvfb so the entrypoint shim can spawn an Xvfb virtual X
+  // server and export DISPLAY, giving headed Chrome (agent-browser
+  // --headed, Playwright headful) a real X11 display to connect to.
+  // Default `true` because modern bot detection (Akamai/Cloudflare Bot
+  // Manager) fingerprints `--headless` and `--headless=new` regardless
+  // of UA spoof, and headed-via-Xvfb is the cheapest path to a passing
+  // fingerprint from a container. Opt-out with `xvfb: false` to save
+  // ~5MB image + ~10MB RAM/idle on agents that never touch a browser.
+  // The shim self-heals — when Xvfb isn't on PATH it execs the agent
+  // directly, no other Dockerfile or shim change needed. Boolean-only
+  // because the package has no API-stable versioning that matters
+  // here; xvfb tracks the upstream X server release.
+  xvfb: z.boolean().default(true),
   append: z.array(dockerfileLineSchema).default([]),
 })
 
@@ -205,32 +235,106 @@ export const networkSchema = z
 
 export type NetworkConfig = z.infer<typeof networkSchema>
 
-// `models` is a map from profile name to a single curated model ref. The
+// 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.
+const tunnelForSchema = z.discriminatedUnion('kind', [
+  z.object({ kind: z.literal('channel'), name: z.string().trim().min(1) }),
+  z.object({ kind: z.literal('manual') }),
+])
+
+const tunnelEntrySchema = z
+  .object({
+    name: z
+      .string()
+      .min(1)
+      .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']),
+    for: tunnelForSchema,
+    externalUrl: z
+      .string()
+      .url()
+      .refine((u) => u.startsWith('https://'), { message: 'externalUrl must use https://' })
+      .optional(),
+    upstreamPort: z.number().int().min(1).max(65535).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, {
+    message: "tunnels[].upstreamPort is required when for.kind is 'manual'",
+  })
+
+const tunnelsArraySchema = z
+  .array(tunnelEntrySchema)
+  .default([])
+  .superRefine((entries, ctx) => {
+    const seen = new Map<string, number>()
+    for (let i = 0; i < entries.length; i++) {
+      const name = entries[i]!.name
+      const prev = seen.get(name)
+      if (prev !== undefined) {
+        ctx.addIssue({
+          code: 'custom',
+          path: [i, 'name'],
+          message: `tunnels[${i}].name duplicates tunnels[${prev}].name ('${name}')`,
+        })
+      } else {
+        seen.set(name, i)
+      }
+    }
+  })
+
+// `models` maps a profile name to one or more curated model refs. The
 // `default` profile is mandatory; every other profile is optional and falls
 // back to `default` at resolution time (see `resolveProfile`).
 //
+// Each value is either a single `KnownModelRef` or a non-empty array of refs
+// forming a fallback chain: when a turn against the first ref fails (hard
+// throw or a soft provider error), the runtime disposes the failed session
+// and replays the same prompt against the next ref. Schema accepts both
+// shapes for ergonomics; the parsed value is always normalised to a
+// non-empty array so downstream consumers read a uniform `KnownModelRef[]`.
+//
 // Profile names are open strings; the runtime recognizes a handful of
 // well-known names by convention (`default`, `fast`, `deep`, `vision`) but
-// any string is valid. Subagents may declare a static profile preference;
-// callers may override per-spawn. Unknown profile names resolve to `default`
-// with a one-time warning at session construction.
+// any string is valid. Unknown profile names resolve to `default` with a
+// one-time warning at session construction.
 //
 // The pre-multi-model schema had a single `model: KnownModelRef` at the top
 // level. `migrateLegacyConfigShape` rewrites that to `models: { default: ... }`
 // on first load (and writes the result back to disk + commits via
 // `persistMigratedConfig`), so every downstream consumer sees the new shape.
+const modelRefOrChainSchema = z
+  .union([
+    z.enum(knownModelRefs),
+    z
+      .array(z.enum(knownModelRefs))
+      .min(1)
+      // Reject exact duplicates in a chain — retrying the same ref after the
+      // same class of failure is almost certainly a config typo, and silently
+      // deduping would mask user intent. Different models from the same
+      // provider (e.g. `["openai/gpt-5.4-nano", "openai/gpt-5.4-mini"]`) are
+      // still valid because they hit distinct upstream endpoints.
+      .refine((arr) => new Set(arr).size === arr.length, {
+        message: 'models chain must not contain duplicate refs',
+      }),
+  ])
+  .transform((value) => (Array.isArray(value) ? value : [value]))
 export const modelsSchema = z
-  .record(z.string().min(1), z.enum(knownModelRefs))
+  .record(z.string().min(1), modelRefOrChainSchema)
   .refine((m) => 'default' in m, { message: 'models.default is required' })
 
-// Zod's `z.record(..., refine)` doesn't refine the inferred type — the inferred
-// shape is `Record<string, KnownModelRef>` where every access is `T | undefined`.
-// The runtime guarantee (the `refine` above) is that `default` is present, so
-// we narrow the type here. Every consumer (auth.ts, agent/index.ts,
-// resolveProfile) reads `models.default` on the hot path; without this
-// narrowing they all have to assert or `?? throw`, which is noise around an
-// invariant the schema already enforces.
-export type Models = Record<string, KnownModelRef> & { default: KnownModelRef }
+// Zod's `z.record(..., refine)` doesn't refine the inferred type. The
+// `default` key is schema-enforced, so we narrow it here to spare every
+// consumer the `T | undefined` assertion noise.
+export type Models = Record<string, KnownModelRef[]> & { default: KnownModelRef[] }
 
 export const configSchema = z
   .object({
@@ -238,8 +342,10 @@ export const configSchema = z
     port: z.number().int().min(1).max(65535).default(DEFAULT_PORT),
     // `default(() => ...)` ensures every parsed config has at least
     // `models.default`. Direct `.default({ default: ... })` would short-circuit
-    // the refinement, so we lean on the lazy thunk form.
-    models: modelsSchema.default(() => ({ default: DEFAULT_MODEL_REF })) as unknown as z.ZodType<Models>,
+    // the refinement, so we lean on the lazy thunk form. The default value is
+    // shaped to match the post-transform output (always `KnownModelRef[]`),
+    // not the user-facing input shape.
+    models: modelsSchema.default(() => ({ default: [DEFAULT_MODEL_REF] })) as unknown as z.ZodType<Models>,
     // Defaults to `[]` so the field can be omitted from `typeclaw.json` (no
     // host paths exposed) without failing the whole config load. `typeclaw
     // init` omits this field so users don't see noise for the empty case.
@@ -258,6 +364,7 @@ export const configSchema = z
     docker: dockerSchema,
     git: gitSchema,
     roles: rolesConfigSchema.optional(),
+    tunnels: tunnelsArraySchema,
   })
   .catchall(z.unknown())
 
@@ -271,26 +378,28 @@ export function resolveModel(ref: KnownModelRef): Model<'openai-completions'> |
   return KNOWN_PROVIDERS[providerId].models[modelId as never]
 }
 
-// Resolves a profile name (e.g. `fast`, `deep`, `vision`) to a concrete model
-// ref. Unknown profiles fall back to `default` so callers can pass through
+// Resolves a profile name (e.g. `fast`, `deep`, `vision`) to its fallback
+// chain. Unknown profiles fall back to `default` so callers can pass through
 // arbitrary subagent-declared or user-overridden strings without crashing.
-// Returns the resolved ref plus whether it came from the requested profile or
-// from the `default` fallback, so the caller can warn once per session
-// instead of every prompt.
+// `refs` is non-empty (the schema guarantees `default` exists and every value
+// is at least one ref). `ref` is the head of the chain — the model the
+// session is created with first. Callers that don't implement fallback can
+// keep reading `ref`; fallback-aware callers iterate `refs`.
 export type ResolvedProfile = {
   ref: KnownModelRef
+  refs: KnownModelRef[]
   profile: string
   fellBackToDefault: boolean
 }
 
 export function resolveProfile(models: Models, name: string | undefined): ResolvedProfile {
   const requested = name ?? 'default'
-  const ref = models[requested]
-  if (ref !== undefined) {
-    return { ref, profile: requested, fellBackToDefault: false }
+  const refs = models[requested]
+  if (refs !== undefined) {
+    return { ref: refs[0]!, refs, profile: requested, fellBackToDefault: false }
   }
   const fallback = models.default
-  return { ref: fallback, profile: 'default', fellBackToDefault: true }
+  return { ref: fallback[0]!, refs: fallback, profile: 'default', fellBackToDefault: true }
 }
 
 // Resolves a mount's `path` field to an absolute host path, mirroring shell
@@ -369,6 +478,7 @@ export const FIELD_EFFECTS: Record<string, FieldEffect> = {
   channels: 'applied',
   portForward: 'restart-required',
   network: 'restart-required',
+  tunnels: 'restart-required',
   'docker.file': 'restart-required',
   'git.ignore': 'restart-required',
   // Split: `match` lists are reload-safe (typeclaw role claim, hand-edits

package/src/config/models-mutation.ts

@@ -17,8 +17,16 @@ const CONFIG_FILE = 'typeclaw.json'
 
 export type ModelProfileEntry = {
   profile: string
+  // Head of the fallback chain. Kept under the legacy `ref` name so callers
+  // that only care about the active model (the common case) don't need to
+  // dereference `refs[0]`. The chain itself is exposed as `refs`.
   ref: KnownModelRef
+  refs: KnownModelRef[]
   providerId: KnownProviderId
+  // Credential status for every provider referenced by the chain. The chain's
+  // overall status is `available` only when every entry resolves; otherwise
+  // it is `missing-credentials`, and `missingProviders` names which.
+  missingProviders: KnownProviderId[]
   isDefault: boolean
   credentialStatus: 'available' | 'missing-credentials'
 }
@@ -28,14 +36,18 @@ export type ModelMutationResult = { ok: true } | { ok: false; reason: string }
 export function listModelProfiles(cwd: string, env: NodeJS.ProcessEnv = process.env): ModelProfileEntry[] {
   const models = loadConfigSync(cwd).models
   const out: ModelProfileEntry[] = []
-  for (const [profile, ref] of Object.entries(models)) {
-    const providerId = providerForModelRef(ref)
+  for (const [profile, refs] of Object.entries(models)) {
+    const headRef = refs[0]!
+    const providerId = providerForModelRef(headRef)
+    const missingProviders = uniqueProviders(refs).filter((p) => !hasUsableCredential(cwd, p, env))
     out.push({
       profile,
-      ref,
+      ref: headRef,
+      refs,
       providerId,
+      missingProviders,
       isDefault: profile === 'default',
-      credentialStatus: hasUsableCredential(cwd, providerId, env) ? 'available' : 'missing-credentials',
+      credentialStatus: missingProviders.length === 0 ? 'available' : 'missing-credentials',
     })
   }
   // `default` always first; remaining profiles alphabetical so output is stable.
@@ -47,6 +59,19 @@ export function listModelProfiles(cwd: string, env: NodeJS.ProcessEnv = process.
   return out
 }
 
+function uniqueProviders(refs: ReadonlyArray<KnownModelRef>): KnownProviderId[] {
+  const seen = new Set<KnownProviderId>()
+  const out: KnownProviderId[] = []
+  for (const r of refs) {
+    const p = providerForModelRef(r)
+    if (!seen.has(p)) {
+      seen.add(p)
+      out.push(p)
+    }
+  }
+  return out
+}
+
 export function listAvailableModelRefs(): KnownModelRef[] {
   return listKnownModelRefs()
 }
@@ -158,14 +183,18 @@ export function removeProfile(cwd: string, profile: string): ModelMutationResult
 
 function writeProfile(cwd: string, profile: string, ref: KnownModelRef, message: string): ModelMutationResult {
   const existing = readModelsRaw(cwd)
-  const next = existing === null ? { default: ref } : { ...existing, [profile]: ref }
+  const next: Record<string, string | string[]> = existing === null ? { default: ref } : { ...existing, [profile]: ref }
   if (existing === null && profile !== 'default') {
     next.default = ref
   }
   return writeModels(cwd, next, message)
 }
 
-function writeModels(cwd: string, models: Record<string, string>, commitMessage: string): ModelMutationResult {
+function writeModels(
+  cwd: string,
+  models: Record<string, string | string[]>,
+  commitMessage: string,
+): ModelMutationResult {
   const path = join(cwd, CONFIG_FILE)
   let parsed: Record<string, unknown>
   try {
@@ -207,10 +236,15 @@ function writeModels(cwd: string, models: Record<string, string>, commitMessage:
   return { ok: true }
 }
 
-function readModelsRaw(cwd: string): Record<string, string> | null {
+// Returns the raw `models` block from disk in its on-disk shape: each value
+// is `string | string[]` (the user-facing schema). Writers preserve whichever
+// shape was already present for profiles they don't touch — converting a
+// hand-authored fallback chain back to a single string would silently drop
+// the fallback.
+function readModelsRaw(cwd: string): Record<string, string | string[]> | null {
   try {
     const raw = readFileSync(join(cwd, CONFIG_FILE), 'utf8')
-    const parsed = JSON.parse(raw) as { models?: Record<string, string> }
+    const parsed = JSON.parse(raw) as { models?: Record<string, string | string[]> }
     return parsed.models ?? null
   } catch (error) {
     if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null

package/src/config/providers-mutation.ts

@@ -136,8 +136,8 @@ export function findModelsReferencingProvider(cwd: string, providerId: string):
   const models = readModelsOrNull(cwd)
   if (models === null) return []
   const out: string[] = []
-  for (const [profile, ref] of Object.entries(models)) {
-    if (refTargetsProvider(ref, providerId)) out.push(profile)
+  for (const [profile, refs] of Object.entries(models)) {
+    if (refs.some((r) => refTargetsProvider(r, providerId))) out.push(profile)
   }
   return out
 }
@@ -212,12 +212,16 @@ function readEnvKey(env: NodeJS.ProcessEnv, key: string): string | undefined {
 function buildProviderReferenceMap(models: Models | null): Map<string, string[]> {
   const out = new Map<string, string[]>()
   if (models === null) return out
-  for (const [profile, ref] of Object.entries(models)) {
-    const providerId = safeProviderForRef(ref)
-    if (providerId === null) continue
-    const existing = out.get(providerId) ?? []
-    existing.push(profile)
-    out.set(providerId, existing)
+  for (const [profile, refs] of Object.entries(models)) {
+    for (const ref of refs) {
+      const providerId = safeProviderForRef(ref)
+      if (providerId === null) continue
+      const existing = out.get(providerId) ?? []
+      if (!existing.includes(profile)) {
+        existing.push(profile)
+        out.set(providerId, existing)
+      }
+    }
   }
   return out
 }

package/src/container/start.ts

@@ -87,7 +87,7 @@ export type StartOptions = {
   // Hostd's supervisor restart callback already runs inside the daemon process.
   // Reusing that daemon avoids a self-shutdown when disk source has drifted.
   reuseCurrentHostDaemon?: boolean
-  ensureDeps?: (cwd: string) => Promise<EnsureDepsResult>
+  ensureDeps?: (cwd: string, opts?: { force?: boolean }) => Promise<EnsureDepsResult>
   // Test seam for the typeclaw-version auto-upgrade. Production callers omit
   // this and get the real autoUpgradeTypeclawDep (which reads the CLI's own
   // package.json). Tests inject a stub to simulate `bun -g update typeclaw`
@@ -149,7 +149,7 @@ export async function start({
   allocatePort = findFreePort,
   cliEntry,
   reuseCurrentHostDaemon = false,
-  ensureDeps = (dir) => ensureDepsInstalled({ cwd: dir }),
+  ensureDeps = (dir, opts) => ensureDepsInstalled({ cwd: dir, ...opts }),
   autoUpgrade = (dir) => autoUpgradeTypeclawDep({ cwd: dir }),
   forceBunUpdate = runBunUpdate,
   readInstalledVersion = readInstalledTypeclawVersionFromAgent,
@@ -235,7 +235,14 @@ export async function start({
     // node_modules/ partially populated. The container then crashes with
     // `Cannot find package 'x'` because the agent folder is bind-mounted into
     // /agent and the container has no node_modules of its own.
-    const deps = await ensureDeps(cwd)
+    //
+    // Force-reinstall ONLY when --build is set AND typeclaw is declared via
+    // a local link. Bun's file-dep cache otherwise serves stale source on
+    // subsequent installs (PR #243 dogfooding wasted three rebuilds + a
+    // manual version bump before this gate existed). Registry-spec users
+    // skip the force path because their install is already cache-correct.
+    const forceDepsReinstall = forceBuild && (await hasLocallyLinkedTypeclawDep(cwd))
+    const deps = await ensureDeps(cwd, { force: forceDepsReinstall })
     if (!deps.ok) {
       return { ok: false, reason: `dependency install failed: ${deps.reason}` }
     }
@@ -448,7 +455,24 @@ 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', `${publishHost}:${hostPort}:${CONTAINER_PORT}`]
+  //
+  // `--shm-size=2g` is mandatory for the bundled Chrome (agent-browser) to
+  // survive heavy pages. Docker's default /dev/shm is 64MB; Chrome uses
+  // shared memory for the renderer process and silently crashes mid-load
+  // on any site with a large DOM or non-trivial WebGL. The crash surfaces
+  // as a blank page or "target closed" with no clear cause — easy to
+  // misattribute to bot detection. 2g matches the Playwright/Puppeteer
+  // canonical recommendation and is a memory cap, not an allocation (only
+  // used pages count against the host).
+  const runArgs = [
+    'run',
+    '-d',
+    '--name',
+    containerName,
+    '--shm-size=2g',
+    '-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
@@ -710,6 +734,26 @@ async function detectDevSource(cwd: string): Promise<string | null> {
   }
 }
 
+// True when the agent's package.json declares typeclaw via `file:` or
+// `link:` — i.e. a developer is iterating on the typeclaw source via a
+// locally-linked checkout. `bun install` keys its file-dep cache on
+// name+version, so it treats a stale cached copy as a cache hit even
+// after the source on disk has changed. `typeclaw start --build` uses
+// this gate to force `bun install --force` only in dev: registry-spec
+// users (`^X.Y.Z`, `~X.Y.Z`, exact pins) pay nothing because their
+// install path is already cache-correct.
+async function hasLocallyLinkedTypeclawDep(cwd: string): Promise<boolean> {
+  try {
+    const raw = await readFile(join(cwd, PACKAGE_FILE), 'utf8')
+    const pkg = JSON.parse(raw) as { dependencies?: Record<string, string> }
+    const spec = pkg.dependencies?.typeclaw
+    if (typeof spec !== 'string') return false
+    return spec.startsWith('file:') || spec.startsWith('link:')
+  } catch {
+    return false
+  }
+}
+
 // A missing typeclaw.json is tolerated (e.g. test fixtures, freshly-cloned
 // folder mid-init). Anything else — malformed JSON, schema-invalid config,
 // invalid mount entry — must surface so the user sees they configured a mount

package/src/cron/bridge.ts

@@ -0,0 +1,136 @@
+import { resolveHostPort, resolveTuiToken } from '@/container'
+import type { ClientMessage, CronListEntryPayload, ServerMessage } from '@/shared'
+
+export type CronListBridgeOptions = {
+  cwd: string
+  url?: string
+  timeoutMs?: number
+}
+
+export type CronListBridgeResult =
+  | { kind: 'ok'; jobs: CronListEntryPayload[]; nowMs: number }
+  | { kind: 'unreachable'; reason: string }
+  | { kind: 'timeout' }
+  | { kind: 'error'; reason: string }
+
+const DEFAULT_TIMEOUT_MS = 15_000
+
+export async function fetchCronList(opts: CronListBridgeOptions): Promise<CronListBridgeResult> {
+  const reach = await dial(opts)
+  if (reach.kind !== 'ok') return reach
+  const { ws, timeoutMs } = reach
+  const requestId = randomId()
+  try {
+    return await awaitReply(ws, timeoutMs, requestId)
+  } finally {
+    ws.close()
+  }
+}
+
+type DialResult = { kind: 'ok'; ws: WebSocket; timeoutMs: number } | { kind: 'unreachable'; reason: string }
+
+async function dial(opts: CronListBridgeOptions): Promise<DialResult> {
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS
+  let url = opts.url
+  if (url === undefined) {
+    try {
+      const port = await resolveHostPort({ cwd: opts.cwd })
+      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) => {
+      // Mirrors the wedged-handshake timeout from src/doctor/plugin-bridge.ts.
+      // Bun's WebSocket has no built-in connect timeout; a stuck Upgrade
+      // never fires 'open' nor 'error', so `typeclaw cron list` would hang.
+      let timer: ReturnType<typeof setTimeout> | undefined
+      const cleanup = () => {
+        if (timer !== undefined) clearTimeout(timer)
+        ws.removeEventListener('open', onOpen)
+        ws.removeEventListener('error', onError)
+        ws.removeEventListener('close', onClose)
+      }
+      const onOpen = () => {
+        cleanup()
+        resolve()
+      }
+      const onError = (err: unknown) => {
+        cleanup()
+        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`))
+      }
+      timer = setTimeout(() => {
+        cleanup()
+        try {
+          ws.close()
+        } catch {}
+        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) }
+  }
+  return { kind: 'ok', ws, timeoutMs }
+}
+
+async function awaitReply(ws: WebSocket, timeoutMs: number, requestId: string): Promise<CronListBridgeResult> {
+  const outgoing: ClientMessage = { type: 'cron_list', requestId }
+  ws.send(JSON.stringify(outgoing))
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => {
+      ws.removeEventListener('message', onMessage)
+      resolve({ kind: 'timeout' })
+    }, timeoutMs)
+    const onMessage = (event: MessageEvent) => {
+      let msg: ServerMessage
+      try {
+        msg = JSON.parse(String(event.data)) as ServerMessage
+      } catch (err) {
+        clearTimeout(timer)
+        ws.removeEventListener('message', onMessage)
+        resolve({ kind: 'error', reason: err instanceof Error ? err.message : String(err) })
+        return
+      }
+      if (msg.type !== 'cron_list_result' || msg.requestId !== requestId) return
+      clearTimeout(timer)
+      ws.removeEventListener('message', onMessage)
+      if (msg.result.ok) {
+        resolve({ kind: 'ok', jobs: msg.result.jobs, nowMs: msg.result.nowMs })
+      } else {
+        resolve({ kind: 'error', reason: msg.result.reason })
+      }
+    }
+    ws.addEventListener('message', onMessage)
+  })
+}
+
+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
+  }
+}
+
+function randomId(): string {
+  return `cron-${crypto.randomUUID()}`
+}