typeclaw 0.3.1 → 0.4.0

package/src/config/config.ts

@@ -86,6 +86,23 @@ 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),
   append: z.array(dockerfileLineSchema).default([]),
 })
 
@@ -205,6 +222,62 @@ export const networkSchema = z
 
 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.
+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` is a map from profile name to a single curated model ref. The
 // `default` profile is mandatory; every other profile is optional and falls
 // back to `default` at resolution time (see `resolveProfile`).
@@ -258,6 +331,7 @@ export const configSchema = z
     docker: dockerSchema,
     git: gitSchema,
     roles: rolesConfigSchema.optional(),
+    tunnels: tunnelsArraySchema,
   })
   .catchall(z.unknown())
 
@@ -369,6 +443,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/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}` }
     }
@@ -710,6 +717,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()}`
+}

package/src/cron/consumer.ts

@@ -4,7 +4,9 @@ import type { SessionOrigin } from '@/agent/session-origin'
 import type { HookBus } from '@/plugin'
 import type { Stream, Unsubscribe } from '@/stream'
 
-import type { CronJob, ExecJob, PromptJob } from './schema'
+import type { CronJob, ExecJob, HandlerJob, PromptJob } from './schema'
+
+export type CronHandlerInvoker = (job: HandlerJob) => Promise<void>
 
 // `hooks`, `sessionId`, `agentDir`, and `getTranscriptPath` are optional so
 // test fakes can stay one-liners. When present, the consumer fires
@@ -40,6 +42,13 @@ export type CreateCronConsumerOptions = {
   stream: Stream
   cwd: string
   createSessionForCron: (job: PromptJob) => Promise<CronSession>
+  // Builds the `CronHandlerContext` for the job and awaits its `handler`.
+  // Wired by `src/run/index.ts` to reuse `runPromptForCommand` /
+  // `runExecForCommand` from the command runner so plugin cron handlers and
+  // container plugin commands share one implementation of `ctx.prompt` /
+  // `ctx.exec`. Optional so unit-test fakes that never schedule handler jobs
+  // stay one-liners.
+  invokeHandler?: CronHandlerInvoker
   logger?: CronConsumerLogger
 }
 
@@ -59,6 +68,7 @@ export function createCronConsumer({
   stream,
   cwd,
   createSessionForCron,
+  invokeHandler,
   logger = consoleLogger,
 }: CreateCronConsumerOptions): CronConsumer {
   const inFlight = new Set<string>()
@@ -81,8 +91,15 @@ export function createCronConsumer({
         try {
           if (job.kind === 'prompt') {
             await runPrompt(job, createSessionForCron, stream, logger)
-          } else {
+          } else if (job.kind === 'exec') {
             await runExec(job, cwd)
+          } else {
+            if (invokeHandler === undefined) {
+              throw new Error(
+                `handler job dispatched but no invokeHandler wired into the consumer (likely a misconfigured test or boot path)`,
+              )
+            }
+            await invokeHandler(job)
           }
         } catch (err) {
           const message = err instanceof Error ? err.message : String(err)
@@ -180,7 +197,29 @@ async function runPrompt(
 async function runExec(job: ExecJob, cwd: string): Promise<void> {
   const [cmd, ...args] = job.command
   if (!cmd) throw new Error(`exec job ${job.id}: empty command`)
-  const proc = Bun.spawn({ cmd: [cmd, ...args], cwd, stdout: 'pipe', stderr: 'pipe' })
+  // Inject TYPECLAW_PARENT_ORIGIN_JSON so a child that proxies into the
+  // agent (typically a `typeclaw <container-cmd>` invocation through the
+  // host CLI's container-command-client) can stamp its session's
+  // spawnedByOrigin with the cron job's provenance. Without this the
+  // proxy would default to a synthetic owner origin and silently elevate
+  // a guest- or member-scheduled cron job to owner.
+  const parentOrigin = {
+    kind: 'cron',
+    jobId: job.id,
+    jobKind: 'exec',
+    ...(job.scheduledByRole !== undefined ? { scheduledByRole: job.scheduledByRole } : {}),
+    ...(job.scheduledByOrigin !== undefined ? { scheduledByOrigin: job.scheduledByOrigin } : {}),
+  }
+  const proc = Bun.spawn({
+    cmd: [cmd, ...args],
+    cwd,
+    stdout: 'pipe',
+    stderr: 'pipe',
+    env: {
+      ...process.env,
+      TYPECLAW_PARENT_ORIGIN_JSON: JSON.stringify(parentOrigin),
+    },
+  })
   const code = await proc.exited
   if (code !== 0) {
     const stderr = await new Response(proc.stderr).text()
@@ -190,7 +229,8 @@ async function runExec(job: ExecJob, cwd: string): Promise<void> {
 
 function isCronJob(value: unknown): value is CronJob {
   if (typeof value !== 'object' || value === null) return false
-  const v = value as { id?: unknown; kind?: unknown }
+  const v = value as { id?: unknown; kind?: unknown; handler?: unknown }
   if (typeof v.id !== 'string') return false
-  return v.kind === 'prompt' || v.kind === 'exec'
+  if (v.kind === 'prompt' || v.kind === 'exec') return true
+  return v.kind === 'handler' && typeof v.handler === 'function'
 }

package/src/cron/index.ts

@@ -21,7 +21,15 @@ export {
   type CronConsumerLogger,
   type CronSession,
 } from './consumer'
-export { createScheduler, type JobDiff, type Scheduler, type SchedulerLogger } from './scheduler'
+export {
+  type ComputeNextFireResult,
+  computeNextFire,
+  createScheduler,
+  type JobDiff,
+  type Scheduler,
+  type SchedulerLogger,
+} from './scheduler'
+export { aggregateCronList, type CronListEntry, type CronListSource } from './list'
 export {
   buildCronMigrationCommitMessage,
   cronFileSchema,
@@ -31,7 +39,9 @@ export {
   type CronMigrationResult,
   type CronMigrationStep,
   type ExecJob,
+  type HandlerJob,
   migrateLegacyCronShape,
+  type ParsedCronJob,
   type PromptJob,
 } from './schema'
 
@@ -41,6 +51,12 @@ export type LoadCronResult = { ok: true; file: CronFile | null } | { ok: false;
 
 export type LoadCronOptions = {
   subagents?: SubagentRegistry
+  // When true (the default), legacy-shape migrations are written back
+  // to cron.json on disk and committed by the system-commit helper.
+  // Read-only inspection callers must pass `false` so an unaware
+  // `typeclaw cron list` against a legacy file does not produce a
+  // commit on whatever branch the user happens to be on.
+  persistMigrations?: boolean
 }
 
 export async function loadCron(agentDir: string, options: LoadCronOptions = {}): Promise<LoadCronResult> {
@@ -62,7 +78,8 @@ export async function loadCron(agentDir: string, options: LoadCronOptions = {}):
   }
 
   const migrated = migrateLegacyCronShape(parsed)
-  if (migrated.changed) {
+  const persistMigrations = options.persistMigrations ?? true
+  if (migrated.changed && persistMigrations) {
     await persistMigratedCron(path, migrated.json, agentDir, migrated.applied)
   }
 

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',