typeclaw 0.3.0 → 0.4.0

package/src/cli/usage.ts

@@ -6,7 +6,7 @@ import { formatJson, formatReport } from '@/usage/report'
 
 import { parseSince, parseUntil, USAGE_COMMON_ARGS } from './usage-args'
 
-const SUBCOMMANDS = ['daily', 'session', 'models'] as const
+const SUBCOMMANDS = ['daily', 'session', 'models', 'origin'] as const
 type Subcommand = (typeof SUBCOMMANDS)[number]
 type View = 'summary' | Subcommand
 
@@ -18,6 +18,13 @@ const COMMON_ARGS = {
   },
 }
 
+// Captured by the parent's `setup` hook (which citty runs BEFORE the matched
+// subcommand's `run`, with the full parent-level argv parsed). Subcommands
+// read this in their own `run` to recover global options like `--since` that
+// appeared before the subcommand name. Single-instance CLI processes only —
+// no concurrency.
+let parentRunArgs: Record<string, unknown> | undefined
+
 const subcommand = (view: View, description: string) =>
   defineCommand({
     meta: { name: view, description },
@@ -26,7 +33,7 @@ const subcommand = (view: View, description: string) =>
       ...(view === 'session' ? { limit: { type: 'string' as const, description: 'max sessions (default 20)' } } : {}),
     },
     async run({ args }) {
-      await emit(view, args)
+      await emit(view, mergeParentArgs(args))
     },
   })
 
@@ -36,10 +43,14 @@ export const usageCommand = defineCommand({
     description: 'report LLM token usage and cost for this agent folder',
   },
   args: COMMON_ARGS,
+  setup({ args }) {
+    parentRunArgs = args as unknown as Record<string, unknown>
+  },
   subCommands: {
     daily: subcommand('daily', 'one row per calendar day'),
     session: subcommand('session', 'top sessions by cost'),
     models: subcommand('models', 'one row per provider/model'),
+    origin: subcommand('origin', 'one row per session origin (tui/cron/channel/subagent)'),
   },
   async run({ args }) {
     // citty invokes both the matched subcommand's `run` and the parent's
@@ -50,6 +61,23 @@ export const usageCommand = defineCommand({
   },
 })
 
+// citty's subcommand `run` only sees args that came AFTER the subcommand
+// name (the child's rawArgs is pre-sliced), so `usage --since=X origin` would
+// silently drop `--since` despite the help text advertising it as a global
+// option. The parent's `setup` runs first with the full parent-level parse
+// (which includes everything: global options + subcommand options merged),
+// so we capture it there and merge it as a fallback under any explicitly-set
+// child arg. Child-wins so `usage --since=A origin --since=B` still honours B.
+function mergeParentArgs(childArgs: Record<string, unknown>): Record<string, unknown> {
+  if (parentRunArgs === undefined) return childArgs
+  const merged: Record<string, unknown> = { ...parentRunArgs }
+  for (const key of Object.keys(childArgs)) {
+    const v = childArgs[key]
+    if (v !== undefined && v !== '' && v !== false) merged[key] = v
+  }
+  return merged
+}
+
 async function emit(view: View, args: Record<string, unknown>): Promise<void> {
   const cwdArg = typeof args.cwd === 'string' && args.cwd.length > 0 ? args.cwd : process.cwd()
   const agentDir = findAgentDir(cwdArg) ?? cwdArg

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
@@ -881,7 +956,16 @@ export type ValidateConfigResult = { ok: true } | { ok: false; reason: string }
 // confusing path-sharing error (or, on some Linux setups, silently bind-mount
 // an empty auto-created directory). First-failure reporting matches the
 // schema-error path's shape; users fix one and re-run.
-export function validateConfig(cwd: string): ValidateConfigResult {
+export type ValidateConfigOptions = {
+  // Skip the mount-path accessibility check. Host-side callers leave this
+  // false (the default) so missing mount directories surface as a precise
+  // pre-`docker run` error. Container-side callers (the reload registry)
+  // set it true because mount paths in typeclaw.json are host paths and
+  // don't resolve inside the container's filesystem.
+  skipMounts?: boolean
+}
+
+export function validateConfig(cwd: string, options: ValidateConfigOptions = {}): ValidateConfigResult {
   let raw: string
   try {
     raw = readFileSync(join(cwd, CONFIG_FILE), 'utf8')
@@ -907,9 +991,11 @@ export function validateConfig(cwd: string): ValidateConfigResult {
     return { ok: false, reason: `${CONFIG_FILE} is invalid: ${formatZodError(result.error)}` }
   }
 
-  for (const mount of result.data.mounts) {
-    const check = validateMount(mount, cwd)
-    if (!check.ok) return check
+  if (!options.skipMounts) {
+    for (const mount of result.data.mounts) {
+      const check = validateMount(mount, cwd)
+      if (!check.ok) return check
+    }
   }
 
   return { ok: true }

package/src/config/reloadable.ts

@@ -11,24 +11,42 @@ export type CreateConfigReloadableOptions = {
   // hand-edits) take effect without a container restart. `roles.<name>.permissions`
   // changes still require a restart — see FIELD_EFFECTS in config.ts.
   permissions?: PermissionService
+  // Skip the mount-path accessibility check inside validateConfig. Mount paths
+  // in typeclaw.json are host paths — they don't resolve inside the container,
+  // so the check would always fail on any agent that declares mounts. `mounts`
+  // is `restart-required` anyway, so reload never applies mount changes. Set
+  // this when wiring the reloadable from a container-stage context.
+  skipMountValidation?: boolean
 }
 
-export function createConfigReloadable({ cwd, permissions }: CreateConfigReloadableOptions): Reloadable {
+export function createConfigReloadable({
+  cwd,
+  permissions,
+  skipMountValidation = false,
+}: CreateConfigReloadableOptions): Reloadable {
   return {
     scope: 'config',
     description: 'typeclaw.json runtime config',
-    reload: async () => doReload(cwd, permissions),
+    reload: async () => doReload(cwd, permissions, skipMountValidation),
   }
 }
 
-async function doReload(cwd: string, permissions: PermissionService | undefined): Promise<ReloadResult> {
+async function doReload(
+  cwd: string,
+  permissions: PermissionService | undefined,
+  skipMountValidation: boolean,
+): Promise<ReloadResult> {
   // Mount accessibility belongs to the validation surface, not loadConfigSync —
   // validateConfig is the single gate that every host-side caller goes through.
   // Run it before swapping the live config pointer so a mount that vanished
   // between starts surfaces as a reload failure (`mounts` is restart-required
   // anyway, so the user has to restart to pick up changes; better to flag the
   // problem now than to let restart fail later).
-  const validated = validateConfig(cwd)
+  //
+  // Container-side reload skips mount validation: mounts are host paths and
+  // statSync against them inside the container always fails. The host-side
+  // `start` / `restart` / doctor paths still gate on the full validateConfig.
+  const validated = validateConfig(cwd, { skipMounts: skipMountValidation })
   if (!validated.ok) {
     return { scope: 'config', ok: false, reason: validated.reason }
   }

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

@@ -1,8 +1,12 @@
+import type { AgentSession } from '@/agent'
+import { subscribeProviderErrors } from '@/agent/provider-error'
 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
@@ -20,6 +24,12 @@ export type CronSession = {
   agentDir?: string
   getTranscriptPath?: () => string | undefined
   origin?: SessionOrigin
+  // Underlying agent session, exposed so the consumer can subscribe to
+  // `message_end` events and surface soft provider errors (billing, rate
+  // limit, network — pi-coding-agent encodes these in the assistant message
+  // instead of throwing, so the outer try/catch never sees them). Optional
+  // so existing test fakes that only need `prompt` keep working.
+  session?: AgentSession
 }
 
 export type CronConsumerLogger = {
@@ -32,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
 }
 
@@ -51,6 +68,7 @@ export function createCronConsumer({
   stream,
   cwd,
   createSessionForCron,
+  invokeHandler,
   logger = consoleLogger,
 }: CreateCronConsumerOptions): CronConsumer {
   const inFlight = new Set<string>()
@@ -72,9 +90,16 @@ export function createCronConsumer({
         inFlight.add(job.id)
         try {
           if (job.kind === 'prompt') {
-            await runPrompt(job, createSessionForCron, stream)
-          } else {
+            await runPrompt(job, createSessionForCron, stream, logger)
+          } 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)
@@ -98,6 +123,7 @@ async function runPrompt(
   job: PromptJob,
   createSessionForCron: (job: PromptJob) => Promise<CronSession>,
   stream: Stream,
+  logger: CronConsumerLogger,
 ): Promise<void> {
   if (job.subagent !== undefined) {
     // Propagate the cron job's role and origin into the spawned subagent.
@@ -123,6 +149,12 @@ async function runPrompt(
     return
   }
   const session = await createSessionForCron(job)
+  const unsubProviderErrors =
+    session.session !== undefined
+      ? subscribeProviderErrors(session.session, (err) => {
+          logger.error(`[cron] ${job.id}: LLM call failed: ${err.message}`)
+        })
+      : null
   const turnEvent =
     session.hooks && session.sessionId !== undefined && session.agentDir !== undefined
       ? {
@@ -151,6 +183,7 @@ async function runPrompt(
       })
     }
   } finally {
+    unsubProviderErrors?.()
     if (session.hooks && session.sessionId !== undefined) {
       await session.hooks.runSessionEnd({
         sessionId: session.sessionId,
@@ -164,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()
@@ -174,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)
   }