typeclaw 0.32.1 → 0.34.0

package/src/cron/count-state.ts

@@ -0,0 +1,208 @@
+import { existsSync } from 'node:fs'
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+
+import type { CronJob } from './schema'
+
+export const CRON_STATE_FILE = join('cron', 'state.json')
+
+type StateEntry = {
+  progressFingerprint: string
+  firedCount: number
+  lastAcceptedAt: string
+}
+
+type StateFile = {
+  version: 1
+  jobs: Record<string, StateEntry>
+}
+
+export type CountStore = {
+  // Fingerprint-aware: returns 0 unless the stored entry's recurrence
+  // fingerprint matches `job`. A stale fire from a previous job definition (or
+  // a resurrected entry after reload) therefore can't gate the live job.
+  get: (id: string, job: CronJob) => number
+  // Resolves `true` when the fire was accepted and counted, `false` when the
+  // job is no longer in the live set (removed/replaced while this was queued).
+  // Callers use the result to skip dispatching a stale job, not just to avoid
+  // miscounting it. The verdict is computed inside the write mutex, so it
+  // reflects any reconcile that landed before the write ran.
+  increment: (id: string, job: CronJob, at: number) => Promise<boolean>
+  // Re-applies boot-time reconciliation against a new job set (called on
+  // `typeclaw reload`) so re-added/changed jobs don't inherit stale counts.
+  reconcile: (jobs: CronJob[]) => Promise<void>
+}
+
+export type CountStoreIO = {
+  read: (path: string) => Promise<string | null>
+  write: (path: string, data: string) => Promise<void>
+}
+
+const realIO: CountStoreIO = {
+  read: async (path) => (existsSync(path) ? readFile(path, 'utf8') : null),
+  // Temp-file + rename keeps readers from ever seeing a half-written file.
+  write: async (path, data) => {
+    await mkdir(dirname(path), { recursive: true })
+    const tmp = `${path}.${process.pid}.${Date.now()}.tmp`
+    await writeFile(tmp, data, 'utf8')
+    await rename(tmp, path)
+  },
+}
+
+// `progressFingerprint` identifies the job's RECURRENCE IDENTITY, deliberately
+// excluding the mutable limits (`count`, `until`) and `enabled`. Two jobs with
+// the same id but a changed schedule/target are different recurrences, so the
+// fire counter resets. Bumping only `count` (3 → 5) leaves the fingerprint
+// unchanged, so progress is preserved and the job resumes firing.
+export function progressFingerprint(job: CronJob): string {
+  return JSON.stringify({
+    id: job.id,
+    schedule: job.schedule ?? null,
+    at: job.at ?? null,
+    timezone: job.timezone ?? null,
+    kind: job.kind,
+    target: targetIdentity(job),
+  })
+}
+
+function targetIdentity(job: CronJob): unknown {
+  if (job.kind === 'prompt') return { prompt: job.prompt, subagent: job.subagent ?? null, payload: job.payload ?? null }
+  if (job.kind === 'exec') return job.command
+  return { handler: String(job.handler) }
+}
+
+function matchingCount(entry: StateEntry | undefined, job: CronJob): number {
+  if (entry === undefined) return 0
+  return entry.progressFingerprint === progressFingerprint(job) ? entry.firedCount : 0
+}
+
+function serialize(state: StateFile): string {
+  return JSON.stringify(state)
+}
+
+function activeFingerprints(jobs: CronJob[]): Map<string, string> {
+  const map = new Map<string, string>()
+  for (const job of jobs) {
+    if (job.count !== undefined) map.set(job.id, progressFingerprint(job))
+  }
+  return map
+}
+
+export async function createCountStore(
+  agentDir: string,
+  jobs: CronJob[],
+  io: CountStoreIO = realIO,
+): Promise<CountStore> {
+  const path = join(agentDir, CRON_STATE_FILE)
+  const onDisk = await readState(path, io)
+  const state: StateFile = reconcile(onDisk, jobs)
+  // Serializes writes so concurrent increments (two jobs firing in the same
+  // tick) can't clobber each other via read-modify-write races.
+  let tail: Promise<void> = Promise.resolve()
+  // Guards against a straggler fire that lost a reconcile race re-adding a
+  // tombstone for a removed job: an increment whose id/fingerprint is not in
+  // the current live set is dropped. Maps each live id to its fingerprint.
+  let active = activeFingerprints(jobs)
+
+  // Only touch disk when reconciliation actually pruned/reset something.
+  // Avoids a force-committed no-op rewrite of cron/state.json on every boot.
+  if (serialize(state) !== serialize(onDisk)) {
+    await persist(path, state, io)
+  }
+
+  return {
+    get: (id, job) => matchingCount(state.jobs[id], job),
+    increment: (id, job, at) => {
+      const fp = progressFingerprint(job)
+      const run = tail.then(async () => {
+        // Re-check INSIDE the tail body, not just before queueing: a reconcile
+        // can land synchronously between the queue and this body running, so a
+        // sync-only guard would still let a straggler write a tombstone for a
+        // job that's since been removed. `active` reflects the latest reconcile.
+        if (active.get(id) !== fp) return false
+        const prev = matchingCount(state.jobs[id], job)
+        state.jobs[id] = {
+          progressFingerprint: fp,
+          firedCount: prev + 1,
+          lastAcceptedAt: new Date(at).toISOString(),
+        }
+        await persist(path, state, io)
+        return true
+      })
+      tail = run.then(
+        () => {},
+        () => {},
+      )
+      return run
+    },
+    reconcile: (nextJobs) => {
+      // In-memory map is authoritative for `get`, so it must settle before the
+      // caller arms timers; only the on-disk persist trails behind the mutex.
+      active = activeFingerprints(nextJobs)
+      state.jobs = reconcile(state, nextJobs).jobs
+      const run = tail.then(async () => {
+        await persist(path, state, io)
+      })
+      tail = run.catch(() => {})
+      return run
+    },
+  }
+}
+
+function emptyState(): StateFile {
+  return { version: 1, jobs: {} }
+}
+
+async function readState(path: string, io: CountStoreIO): Promise<StateFile> {
+  const raw = await io.read(path)
+  if (raw === null) return emptyState()
+  try {
+    return validateState(JSON.parse(raw))
+  } catch {
+    return emptyState()
+  }
+}
+
+// Durable on-disk state is untrusted: a corrupt or hand-edited file must never
+// crash the scheduler or feed a bogus count into expiry. Drop the whole file
+// on a version mismatch, and skip individual entries that aren't well-formed.
+function validateState(raw: unknown): StateFile {
+  if (typeof raw !== 'object' || raw === null) return emptyState()
+  const obj = raw as { version?: unknown; jobs?: unknown }
+  if (obj.version !== 1 || typeof obj.jobs !== 'object' || obj.jobs === null) return emptyState()
+
+  const jobs: Record<string, StateEntry> = {}
+  for (const [id, value] of Object.entries(obj.jobs as Record<string, unknown>)) {
+    if (typeof value !== 'object' || value === null) continue
+    const e = value as Record<string, unknown>
+    if (typeof e.progressFingerprint !== 'string') continue
+    if (typeof e.firedCount !== 'number' || !Number.isInteger(e.firedCount) || e.firedCount < 0) continue
+    if (typeof e.lastAcceptedAt !== 'string') continue
+    jobs[id] = {
+      progressFingerprint: e.progressFingerprint,
+      firedCount: e.firedCount,
+      lastAcceptedAt: e.lastAcceptedAt,
+    }
+  }
+  return { version: 1, jobs }
+}
+
+// Boot/reload reconciliation. The scary footgun is a job id removed and later
+// re-added with the SAME id: without this, the re-added job would inherit the
+// old counter and never fire. We drop entries for ids that are gone or no
+// longer counted, and reset entries whose recurrence fingerprint changed.
+export function reconcile(state: StateFile, jobs: CronJob[]): StateFile {
+  const byId = new Map(jobs.map((j) => [j.id, j]))
+  const next: Record<string, StateEntry> = {}
+  for (const [id, entry] of Object.entries(state.jobs)) {
+    const job = byId.get(id)
+    if (!job || job.count === undefined) continue
+    if (entry.progressFingerprint !== progressFingerprint(job)) continue
+    next[id] = entry
+  }
+  return { version: 1, jobs: next }
+}
+
+async function persist(path: string, state: StateFile, io: CountStoreIO): Promise<void> {
+  await io.write(path, JSON.stringify(state, null, 2))
+}

package/src/cron/index.ts

@@ -6,22 +6,10 @@ import type { SubagentRegistry } from '@/agent/subagents'
 
 import { type CronFile, parseCronFile } from './schema'
 
-export { createCronReloadable, type CreateCronReloadableOptions } from './reloadable'
-export {
-  createCronConsumer,
-  type CreateCronConsumerOptions,
-  type CronConsumer,
-  type CronConsumerLogger,
-  type CronSession,
-} from './consumer'
-export {
-  type ComputeNextFireResult,
-  computeNextFire,
-  createScheduler,
-  type JobDiff,
-  type Scheduler,
-  type SchedulerLogger,
-} from './scheduler'
+export { type CountStore, createCountStore } from './count-state'
+export { createCronReloadable } from './reloadable'
+export { createCronConsumer, type CronConsumer } from './consumer'
+export { computeNextFire, createScheduler, type JobDiff, type Scheduler } from './scheduler'
 export { aggregateCronList, type CronListEntry, type CronListSource } from './list'
 export {
   cronFileSchema,
@@ -31,7 +19,6 @@ export {
   type ExecJob,
   type HandlerJob,
   parseCronJson,
-  type ParseCronJsonOptions,
   type ParseCronResult,
   type ParsedCronJob,
   type PromptJob,

package/src/cron/list.ts

@@ -15,7 +15,10 @@ export type CronListEntry = {
   id: string
   source: CronListSource
   kind: 'prompt' | 'exec' | 'handler'
-  schedule: string
+  schedule: string | undefined
+  at: string | undefined
+  until: string | undefined
+  count: number | undefined
   timezone: string | undefined
   enabled: boolean
   scheduledByRole: string | undefined
@@ -35,15 +38,27 @@ export type AggregateCronListOptions = {
   // to its plugin + localId without re-parsing the global id.
   pluginJobs: readonly RegisteredCronJob[]
   now: number
+  // Durable fire progress for count-limited jobs. Without this, an exhausted
+  // count job would render with a future next-fire time and lie about being
+  // retired, so the listing threads the same firedCount the scheduler uses.
+  firedCount?: (job: CronJob) => number
 }
 
 export function aggregateCronList(opts: AggregateCronListOptions): CronListEntry[] {
+  const firedCount = opts.firedCount ?? (() => 0)
   const entries: CronListEntry[] = []
   for (const job of opts.userJobs) {
-    entries.push(toEntry(job, { kind: 'user' }, opts.now))
+    entries.push(toEntry(job, { kind: 'user' }, opts.now, firedCount(job)))
   }
   for (const reg of opts.pluginJobs) {
-    entries.push(toEntry(reg.job, { kind: 'plugin', pluginName: reg.pluginName, localId: reg.localId }, opts.now))
+    entries.push(
+      toEntry(
+        reg.job,
+        { kind: 'plugin', pluginName: reg.pluginName, localId: reg.localId },
+        opts.now,
+        firedCount(reg.job),
+      ),
+    )
   }
   // 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
@@ -55,17 +70,20 @@ export function aggregateCronList(opts: AggregateCronListOptions): CronListEntry
   return entries
 }
 
-function toEntry(job: CronJob, source: CronListSource, now: number): CronListEntry {
-  const fire = computeNextFire(job, now)
+function toEntry(job: CronJob, source: CronListSource, now: number, firedCount: number): CronListEntry {
+  const fire = computeNextFire(job, now, { firedCount })
   const base = {
     id: job.id,
     source,
     schedule: job.schedule,
+    at: job.at,
+    until: job.until,
+    count: job.count,
     timezone: job.timezone,
     enabled: job.enabled,
     scheduledByRole: job.scheduledByRole,
     nextFireMs: fire.ok ? fire.nextFire : null,
-    scheduleError: fire.ok ? undefined : fire.reason,
+    scheduleError: fire.ok || fire.expired ? undefined : fire.reason,
   } as const
   if (job.kind === 'prompt') {
     return {

package/src/cron/scheduler.ts

@@ -14,11 +14,22 @@ export type SchedulerLogger = {
   error: (msg: string) => void
 }
 
+// The scheduler uses the count store only to stop arming once a job's durable
+// count is exhausted (an optimization) and to reconcile progress on reload.
+// The authoritative count gate lives in the consumer, which owns accepted-fire
+// accounting — the scheduler must not be the correctness boundary because it
+// can't know whether the downstream coalescer will accept or skip a fire.
+export type SchedulerCountStore = {
+  get: (id: string, job: CronJob) => number
+  reconcile: (jobs: CronJob[]) => Promise<void>
+}
+
 export type CreateSchedulerOptions = {
   jobs: CronJob[]
   onFire: (job: CronJob) => void
   clock?: SchedulerClock
   logger?: SchedulerLogger
+  countStore?: SchedulerCountStore
 }
 
 export type JobDiff = {
@@ -51,6 +62,7 @@ export function createScheduler({
   onFire,
   clock = realClock,
   logger = consoleLogger,
+  countStore,
 }: CreateSchedulerOptions): Scheduler {
   const registry = new Map<string, CronJob>()
   for (const job of jobs) registry.set(job.id, job)
@@ -69,9 +81,16 @@ export function createScheduler({
     const job = currentEnabled(id)
     if (!job) return
 
-    const result = computeNextFire(job, clock.now())
+    const firedCount = job.count !== undefined ? (countStore?.get(id, job) ?? 0) : 0
+    const result = computeNextFire(job, clock.now(), { firedCount })
     if (!result.ok) {
-      logger.warn(`[cron] ${id} not scheduled: invalid schedule "${job.schedule}"${tzSuffix(job)}: ${result.reason}`)
+      if (result.expired) {
+        logger.info(`[cron] ${id} retired: ${result.reason}`)
+      } else {
+        logger.warn(
+          `[cron] ${id} not scheduled: invalid schedule "${job.schedule ?? job.at}"${tzSuffix(job)}: ${result.reason}`,
+        )
+      }
       return
     }
 
@@ -94,8 +113,7 @@ export function createScheduler({
     try {
       onFire(job)
     } catch (err) {
-      const message = err instanceof Error ? err.message : String(err)
-      logger.error(`[cron] ${job.id} onFire threw synchronously: ${message}`)
+      logger.error(`[cron] ${job.id} onFire threw synchronously: ${describe(err)}`)
     }
   }
 
@@ -153,6 +171,14 @@ export function createScheduler({
       registry.clear()
       for (const [id, job] of newRegistry) registry.set(id, job)
 
+      // Reconcile counts before arming so re-added/changed jobs don't inherit
+      // stale progress. `reconcile` settles the authoritative in-memory map
+      // synchronously; only the persist is async, so a failure there just means
+      // disk lags the (correct) in-memory state — log it, don't fail the reload.
+      countStore?.reconcile(next).catch((err) => {
+        logger.error(`[cron] failed to persist count reconciliation: ${describe(err)}`)
+      })
+
       for (const job of result.removed) cancel(job.id)
       for (const job of result.updated) {
         cancel(job.id)
@@ -167,7 +193,10 @@ export function createScheduler({
 
 function jobFingerprint(job: CronJob): string {
   return JSON.stringify({
-    schedule: job.schedule,
+    schedule: job.schedule ?? null,
+    at: job.at ?? null,
+    until: job.until ?? null,
+    count: job.count ?? null,
     enabled: job.enabled,
     timezone: job.timezone ?? null,
     kind: job.kind,
@@ -189,21 +218,67 @@ function jobPayload(job: CronJob): unknown {
   return { handler: String(job.handler) }
 }
 
-export type ComputeNextFireResult = { ok: true; nextFire: number } | { ok: false; reason: string }
+export type ComputeNextFireResult =
+  | { ok: true; nextFire: number }
+  // `expired` distinguishes a reached end-boundary (count/until/past `at`) from
+  // a malformed schedule: the former is silent and final, the latter warns.
+  | { ok: false; expired: true; reason: string }
+  | { ok: false; expired: false; reason: string }
 
-export function computeNextFire(job: CronJob, now: number): ComputeNextFireResult {
+export type ComputeNextFireOptions = {
+  // Accepted fires so far, sourced from the count store. Defaults to 0 so
+  // callers that don't track counts (cron list rendering, pure schedule
+  // preview) compute the raw next occurrence.
+  firedCount?: number
+}
+
+export function computeNextFire(
+  job: CronJob,
+  now: number,
+  options: ComputeNextFireOptions = {},
+): ComputeNextFireResult {
+  const firedCount = options.firedCount ?? 0
+  if (job.count !== undefined && firedCount >= job.count) {
+    return { ok: false, expired: true, reason: `count limit reached (${firedCount}/${job.count})` }
+  }
+
+  if (job.at !== undefined) {
+    const at = Date.parse(job.at)
+    if (Number.isNaN(at)) return { ok: false, expired: false, reason: `invalid "at": ${job.at}` }
+    if (at <= now) return { ok: false, expired: true, reason: `one-shot "at" already elapsed` }
+    return { ok: true, nextFire: at }
+  }
+
+  if (job.schedule === undefined) {
+    return { ok: false, expired: false, reason: `job has neither "schedule" nor "at"` }
+  }
+
+  let nextFire: number
   try {
     const expr = CronExpressionParser.parse(job.schedule, {
       currentDate: new Date(now),
       ...(job.timezone ? { tz: job.timezone } : {}),
     })
-    return { ok: true, nextFire: expr.next().getTime() }
+    nextFire = expr.next().getTime()
   } catch (err) {
     const reason = err instanceof Error ? err.message : String(err)
-    return { ok: false, reason }
+    return { ok: false, expired: false, reason }
   }
+
+  if (job.until !== undefined) {
+    const until = Date.parse(job.until)
+    if (!Number.isNaN(until) && nextFire > until) {
+      return { ok: false, expired: true, reason: `next occurrence is after "until" (${job.until})` }
+    }
+  }
+
+  return { ok: true, nextFire }
 }
 
 function tzSuffix(job: CronJob): string {
   return job.timezone ? ` (timezone "${job.timezone}")` : ''
 }
+
+function describe(err: unknown): string {
+  return err instanceof Error ? err.message : String(err)
+}

package/src/cron/schema.ts

@@ -9,7 +9,18 @@ const idPattern = /^[a-zA-Z0-9_-]+$/
 
 const baseJob = z.object({
   id: z.string().min(1).regex(idPattern, 'id must contain only letters, digits, hyphens, or underscores'),
-  schedule: z.string().min(1),
+  // `schedule` (recurring cron expression) and `at` (one-shot ISO instant) are
+  // mutually exclusive: exactly one must be present. Zod marks both optional so
+  // the discriminated union still parses; the XOR is enforced in parseCronFile
+  // where we can emit a job-id-scoped error message.
+  schedule: z.string().min(1).optional(),
+  at: z.string().min(1).optional(),
+  // End boundaries. `until` is an absolute ISO instant (last allowed fire,
+  // inclusive); `count` stops after N accepted fires. Both may coexist on one
+  // job — the scheduler stops at whichever limit is reached first. `count`
+  // progress is tracked out-of-band in cron-state.json, never written back here.
+  until: z.string().min(1).optional(),
+  count: z.number().int().positive().optional(),
   enabled: z.boolean().default(true),
   timezone: z.string().optional(),
   scheduledByRole: z.string().optional(),
@@ -57,11 +68,25 @@ export type CronFile = z.infer<typeof cronFileSchema>
 
 export type ParseCronResult = { ok: true; file: CronFile } | { ok: false; reason: string }
 
+// `edit` is the strict path for an agent writing/editing cron.json: a past
+// enabled `at` is rejected so a reminder scheduled in the past surfaces as an
+// error instead of silently becoming a never-firing no-op. `load` is the
+// tolerant path the scheduler uses on boot/reload: a fired or missed one-shot
+// lingers on disk with a now-past `at`, and rejecting it would brick the whole
+// file — so `load` accepts it and lets the scheduler retire it passively.
+export type ParseCronMode = 'edit' | 'load'
+
 export type ParseCronOptions = {
   // When provided, prompt jobs with a `subagent` field are validated against
   // the registry: the name must exist, and the optional `payload` must match
   // the registered subagent's payloadSchema (or be absent if no schema).
   subagents?: SubagentRegistry
+  // Injected by tests so past/future boundary checks on `at`/`until` are
+  // deterministic. Production omits it and validation reads the wall clock.
+  now?: number
+  // Defaults to `load` (reload-safe). Callers validating an agent edit pass
+  // `edit` to reject newly-scheduled past `at` reminders.
+  mode?: ParseCronMode
 }
 
 export type ParseCronJsonOptions = ParseCronOptions
@@ -74,7 +99,11 @@ export function parseCronJson(raw: string, options: ParseCronJsonOptions = {}):
     return { ok: false, reason: `cron.json is not valid JSON: ${err instanceof Error ? err.message : String(err)}` }
   }
 
-  return parseCronFile(json, options.subagents !== undefined ? { subagents: options.subagents } : {})
+  return parseCronFile(json, {
+    ...(options.subagents !== undefined ? { subagents: options.subagents } : {}),
+    ...(options.now !== undefined ? { now: options.now } : {}),
+    ...(options.mode !== undefined ? { mode: options.mode } : {}),
+  })
 }
 
 export function parseCronFile(raw: unknown, options: ParseCronOptions = {}): ParseCronResult {
@@ -91,17 +120,9 @@ export function parseCronFile(raw: unknown, options: ParseCronOptions = {}): Par
     }
     seen.add(job.id)
 
-    try {
-      const expr = CronExpressionParser.parse(job.schedule, job.timezone ? { tz: job.timezone } : undefined)
-      // cron-parser validates the timezone lazily on first next() call, not at
-      // parse time, so we must force evaluation here to catch bogus zones.
-      expr.next()
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err)
-      if (job.timezone && /invalid|unhandled timestamp|unrecognized/i.test(message)) {
-        return { ok: false, reason: `job ${job.id}: invalid timezone "${job.timezone}": ${message}` }
-      }
-      return { ok: false, reason: `job ${job.id}: invalid schedule "${job.schedule}": ${message}` }
+    const timingError = validateTiming(job, options.now ?? Date.now(), options.mode ?? 'load')
+    if (timingError !== null) {
+      return { ok: false, reason: `job ${job.id}: ${timingError}` }
     }
 
     if (job.scheduledByRole === undefined) {
@@ -128,6 +149,72 @@ export function parseCronFile(raw: unknown, options: ParseCronOptions = {}): Par
   return { ok: true, file }
 }
 
+type TimingJob = {
+  schedule?: string | undefined
+  at?: string | undefined
+  until?: string | undefined
+  count?: number | undefined
+  timezone?: string | undefined
+  enabled: boolean
+}
+
+function validateTiming(job: TimingJob, now: number = Date.now(), mode: ParseCronMode = 'load'): string | null {
+  const hasSchedule = job.schedule !== undefined
+  const hasAt = job.at !== undefined
+  if (hasSchedule === hasAt) {
+    return `must set exactly one of "schedule" (recurring) or "at" (one-shot)`
+  }
+
+  if (hasAt) {
+    if (job.timezone !== undefined) return `"timezone" is only valid with "schedule", not "at"`
+    if (job.until !== undefined) return `"until" is only valid with "schedule", not "at"`
+    if (job.count !== undefined && job.count !== 1) return `one-shot "at" jobs may only set "count": 1`
+    const at = parseInstant(job.at!)
+    if (at === null) return `invalid "at": "${job.at}" is not an ISO datetime with an explicit zone/offset`
+    // Reject a past reminder only on `edit`; `load` tolerates fired tombstones.
+    // See ParseCronMode for the full rationale.
+    if (mode === 'edit' && job.enabled && at <= now) return `"at" is in the past: "${job.at}"`
+    return null
+  }
+
+  let until: number | null = null
+  if (job.until !== undefined) {
+    until = parseInstant(job.until)
+    if (until === null) return `invalid "until": "${job.until}" is not an ISO datetime with an explicit zone/offset`
+    if (job.enabled && until <= now) return `"until" is in the past: "${job.until}"`
+  }
+
+  let firstFire: number
+  try {
+    const expr = CronExpressionParser.parse(job.schedule!, {
+      currentDate: new Date(now),
+      ...(job.timezone ? { tz: job.timezone } : {}),
+    })
+    firstFire = expr.next().getTime()
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err)
+    if (job.timezone && /invalid|unhandled timestamp|unrecognized/i.test(message)) {
+      return `invalid timezone "${job.timezone}": ${message}`
+    }
+    return `invalid schedule "${job.schedule}": ${message}`
+  }
+
+  if (job.enabled && until !== null && firstFire > until) {
+    return `schedule has no occurrence at or before "until" ("${job.until}")`
+  }
+
+  return null
+}
+
+// Accepts only absolute instants: an explicit `Z` or numeric offset is
+// required so "remind me at 9am" can never silently resolve to the host's
+// local zone. A bare `2026-06-09T09:00:00` (no zone) is rejected.
+function parseInstant(value: string): number | null {
+  if (!/[zZ]$|[+-]\d{2}:?\d{2}$/.test(value)) return null
+  const ms = Date.parse(value)
+  return Number.isNaN(ms) ? null : ms
+}
+
 function formatIssue(issue: { path: PropertyKey[]; message: string }): string {
   const path = issue.path.length > 0 ? issue.path.map(String).join('.') : '<root>'
   return `${path}: ${issue.message}`

package/src/doctor/channel-checks.ts

@@ -28,6 +28,7 @@ export function buildChannelChecks(): DoctorCheck[] {
     slackBotCredentials(),
     discordBotCredentials(),
     telegramBotCredentials(),
+    lineCredentials(),
     kakaotalkCredentials(),
     githubCredentials(),
     githubWebhookDelivery(),
@@ -64,6 +65,33 @@ function telegramBotCredentials(): DoctorCheck {
   }
 }
 
+function lineCredentials(): DoctorCheck {
+  return {
+    name: 'channel.line.credentials',
+    category: 'channels',
+    description: 'line adapter has at least one account in secrets.json',
+    applies: (ctx) => ctx.hasAgentFolder,
+    async run(ctx) {
+      const channels = readDeclaredChannels(ctx)
+      if (channels === null) return configInvalidResult()
+      if (!isAdapterActive(channels, 'line')) {
+        return { status: 'skipped', message: 'line not configured' }
+      }
+      const block = readChannelsSecrets(ctx)?.line
+      const accountCount = block?.accounts ? Object.keys(block.accounts).length : 0
+      if (accountCount === 0) {
+        return {
+          status: 'warning',
+          message: 'line has no accounts in secrets.json',
+          details: ['Adapter will start but fail authentication and stay disconnected.'],
+          fix: { description: 'Run `typeclaw channel add line` to log in an account.' },
+        }
+      }
+      return { status: 'ok', message: `line has ${accountCount} account(s)` }
+    },
+  }
+}
+
 function kakaotalkCredentials(): DoctorCheck {
   return {
     name: 'channel.kakaotalk.credentials',