typeclaw 0.32.1 → 0.34.0

package/src/hostd/daemon.ts

@@ -7,7 +7,7 @@ import type { Socket, UnixSocketListener } from 'bun'
 import type { PortForward } from '@/config'
 import { defaultDockerExec, type DockerExec } from '@/container'
 import type { PortForwardEvent } from '@/portbroker'
-import { kakaoChannelBlockSchema } from '@/secrets/schema'
+import { kakaoChannelBlockSchema, lineChannelBlockSchema } from '@/secrets/schema'
 import { SecretsBackend } from '@/secrets/storage'
 
 import { isDaemonReachable } from './client'
@@ -410,19 +410,27 @@ export async function startDaemon(opts: DaemonOptions = {}): Promise<Daemon> {
 
   const handleSecretsPatch = async (req: {
     containerName: string
-    patch: { channels: { kakaotalk: unknown } }
+    patch: { channels: { kakaotalk: unknown } | { line: unknown } }
   }): Promise<RpcResponse> =>
     runSerially(req.containerName, async () => {
       const cwd = cwds.get(req.containerName)
       if (!cwd) return { ok: false, reason: `not registered: ${req.containerName}` }
-      const parsed = kakaoChannelBlockSchema.safeParse(req.patch?.channels?.kakaotalk)
-      if (!parsed.success) {
-        return { ok: false, reason: parsed.error.issues.map((issue) => issue.message).join('; ') }
+      const channelsPatch = req.patch?.channels
+      // Exactly one personal-account channel block per patch. KakaoTalk and
+      // LINE both write their structured account block through this RPC; the
+      // key present in the patch selects which block to validate and merge.
+      const patch =
+        'line' in channelsPatch
+          ? { key: 'line' as const, parsed: lineChannelBlockSchema.safeParse(channelsPatch.line) }
+          : { key: 'kakaotalk' as const, parsed: kakaoChannelBlockSchema.safeParse(channelsPatch.kakaotalk) }
+      if (!patch.parsed.success) {
+        return { ok: false, reason: patch.parsed.error.issues.map((issue) => issue.message).join('; ') }
       }
+      const data = patch.parsed.data
       const backend = new SecretsBackend(join(cwd, 'secrets.json'))
       await backend.updateChannelsAsync(async (channels) => ({
         result: undefined,
-        next: { ...channels, kakaotalk: parsed.data },
+        next: { ...channels, [patch.key]: data },
       }))
       const result: SecretsPatchResult = { containerName: req.containerName, patched: true }
       return { ok: true, result }

package/src/hostd/protocol.ts

@@ -1,5 +1,5 @@
 import type { PortForward } from '@/config'
-import type { KakaoChannelBlock } from '@/secrets/schema'
+import type { KakaoChannelBlock, LineChannelBlock } from '@/secrets/schema'
 
 export type Request =
   | {
@@ -15,7 +15,11 @@ export type Request =
   | { kind: 'list' }
   | { kind: 'status'; containerName: string }
   | { kind: 'restart'; containerName: string; build?: boolean }
-  | { kind: 'secrets-patch'; containerName: string; patch: { channels: { kakaotalk: KakaoChannelBlock } } }
+  | {
+      kind: 'secrets-patch'
+      containerName: string
+      patch: { channels: { kakaotalk: KakaoChannelBlock } | { line: LineChannelBlock } }
+    }
   | { kind: 'http-info' }
   | { kind: 'version' }
   | { kind: 'shutdown' }

package/src/init/gitignore.ts

@@ -23,7 +23,7 @@ export const TRULY_IGNORED_PATTERNS = [
 // The reconciler MUST fail-closed and never untrack these, even if a custom
 // git.ignore.append pattern (e.g. `**`) matches them — doing so would drop
 // runtime-owned state out of git.
-export const SYSTEM_MANAGED_ROOTS = ['sessions/', 'memory/', 'channels/', 'todo/'] as const
+export const SYSTEM_MANAGED_ROOTS = ['sessions/', 'memory/', 'channels/', 'todo/', 'cron/'] as const
 
 export function buildGitignore(config: GitignoreConfig = { append: [] }): string {
   const customEntries = renderCustomGitignoreEntries(config.append)

package/src/init/index.ts

@@ -139,6 +139,9 @@ export type HatchRunner = (options: {
 
 export type KakaotalkAuthRunner = (options: { cwd: string }) => Promise<KakaotalkAuthResult>
 
+export type LineAuthResult = { ok: true } | { ok: false; reason: string }
+export type LineAuthRunner = (options: { cwd: string }) => Promise<LineAuthResult>
+
 // Discriminated by `kind` so the type system enforces "you can't pass an
 // API key to an OAuth provider, and you can't pass an OAuth runner to an
 // API-key provider". Optional model defaults to DEFAULT_MODEL_REF, which is
@@ -834,7 +837,7 @@ export async function hasExistingOAuthCredentials(root: string, providerId: Know
 // kakaotalk` anyway — better to re-auth now during init.
 export async function hasExistingChannelSecrets(
   root: string,
-  channel: 'discord' | 'slack' | 'telegram' | 'kakaotalk' | 'github',
+  channel: 'discord' | 'slack' | 'telegram' | 'line' | 'kakaotalk' | 'github',
 ): Promise<boolean> {
   const channels = new SecretsBackend(join(root, 'secrets.json')).tryReadChannelsSync()
   if (channels === null) return false
@@ -854,6 +857,21 @@ export async function hasExistingChannelSecrets(
       // surfaced as a hard error inside `runAddChannel` to prevent silent
       // overwrites.
       return false
+    case 'line': {
+      // A usable LINE block needs a current account whose record carries an
+      // auth_token. Unlike KakaoTalk there are no renewal fields (email +
+      // encrypted password) to require — LINE has no unattended renewal cron.
+      const block = channels.line
+      if (!isObjectRecord(block)) return false
+      const current = (block as { currentAccount?: unknown }).currentAccount
+      if (typeof current !== 'string' || current.length === 0) return false
+      const accounts = (block as { accounts?: unknown }).accounts
+      if (!isObjectRecord(accounts)) return false
+      const account = accounts[current]
+      if (!isObjectRecord(account)) return false
+      const authToken = (account as { auth_token?: unknown }).auth_token
+      return typeof authToken === 'string' && authToken.length > 0
+    }
     case 'kakaotalk': {
       const block = channels.kakaotalk
       if (!isObjectRecord(block)) return false
@@ -924,7 +942,7 @@ function ignoreExists(error: NodeJS.ErrnoException): void {
 // scaffold-test cases above demonstrates how easy it is to lose a single
 // behavior under a mode flag.
 
-export type ChannelKind = 'discord-bot' | 'slack-bot' | 'telegram-bot' | 'kakaotalk' | 'github'
+export type ChannelKind = 'discord-bot' | 'slack-bot' | 'telegram-bot' | 'line' | 'kakaotalk' | 'github'
 
 // Public adapter names match the typeclaw.json `channels.*` keys exactly.
 // The CLI takes these as the optional positional arg, the picker shows
@@ -934,15 +952,18 @@ export const CHANNEL_KINDS: ReadonlyArray<ChannelKind> = [
   'slack-bot',
   'discord-bot',
   'telegram-bot',
+  'line',
   'kakaotalk',
   'github',
 ]
 
-export type AddChannelStep = 'kakaotalk-auth' | 'config' | 'secrets' | 'github-webhooks'
+export type AddChannelStep = 'line-auth' | 'kakaotalk-auth' | 'config' | 'secrets' | 'github-webhooks'
 
 export type AddChannelStepEvent =
   | { step: 'config'; phase: 'start' }
   | { step: 'config'; phase: 'done' }
+  | { step: 'line-auth'; phase: 'start' }
+  | { step: 'line-auth'; phase: 'done'; result: LineAuthResult }
   | { step: 'kakaotalk-auth'; phase: 'start' }
   | { step: 'kakaotalk-auth'; phase: 'done'; result: KakaotalkAuthResult }
   | { step: 'secrets'; phase: 'start' }
@@ -960,6 +981,7 @@ export type AddChannelOptions = {
   | { channel: 'discord-bot'; discordBotToken: string }
   | { channel: 'slack-bot'; slackBotToken: string; slackAppToken: string }
   | { channel: 'telegram-bot'; telegramBotToken: string }
+  | { channel: 'line'; runLineAuth: LineAuthRunner }
   | { channel: 'kakaotalk'; runKakaotalkAuth: KakaotalkAuthRunner }
   | {
       channel: 'github'
@@ -986,6 +1008,13 @@ export async function runAddChannel(options: AddChannelOptions): Promise<void> {
   // drops messages — the same trap `runInit` already guards against. Aborting
   // before any file write means the user's next `typeclaw channel add
   // kakaotalk` retry has no half-applied state to clean up.
+  if (options.channel === 'line') {
+    emit({ step: 'line-auth', phase: 'start' })
+    const result = await options.runLineAuth({ cwd: options.cwd })
+    emit({ step: 'line-auth', phase: 'done', result })
+    if (!result.ok) throw new Error(`LINE authentication failed: ${result.reason}`)
+  }
+
   if (options.channel === 'kakaotalk') {
     emit({ step: 'kakaotalk-auth', phase: 'start' })
     const result = await options.runKakaotalkAuth({ cwd: options.cwd })
@@ -1065,6 +1094,10 @@ function channelSecretsFromOptions(options: AddChannelOptions): ChannelSecrets {
       return { botToken: options.slackBotToken, appToken: options.slackAppToken }
     case 'telegram-bot':
       return { token: options.telegramBotToken }
+    case 'line':
+      // LINE auth writes its structured account block directly to
+      // secrets.json#channels.line before config mutation.
+      return {}
     case 'kakaotalk':
       // KakaoTalk auth writes its structured multi-account block directly to
       // secrets.json#channels.kakaotalk before config mutation.

package/src/init/line-auth.ts

@@ -0,0 +1,98 @@
+import { join } from 'node:path'
+
+import { LineClient as RealLineClient, LineCredentialManager, type LineLoginResult } from 'agent-messenger/line'
+
+import { SecretsLineCredentialStore } from '@/secrets/line-store'
+
+export type LineBootstrapStatus = { ok: true } | { ok: false; reason: string }
+
+export type LineLoginCallbacks = {
+  onQRUrl?: (url: string) => void
+  onPincode: (pin: string) => void
+}
+
+// QR is the default because a LINE account may have no usable e-mail/password
+// (social-login accounts), and QR only adds bootstrap-time UX — the persisted
+// credential (auth_token + certificate) is identical regardless of method.
+export type LineLoginInput =
+  | {
+      method: 'qr'
+      agentDir: string
+      callbacks: LineLoginCallbacks
+      client?: LineLoginClient
+    }
+  | {
+      method: 'email'
+      email: string
+      password: string
+      agentDir: string
+      callbacks: LineLoginCallbacks
+      client?: LineLoginClient
+    }
+
+// Structural subset of the upstream LineClient the bootstrap drives. Declared
+// here so tests can inject a fake without standing up the real LOCO client.
+export type LineLoginClient = {
+  loginWithQR(options: { onQRUrl: (url: string) => void; onPincode: (pin: string) => void }): Promise<LineLoginResult>
+  loginWithEmail(options: {
+    email: string
+    password: string
+    onPincode: (pin: string) => void
+  }): Promise<LineLoginResult>
+}
+
+export function lineSecretsPath(agentDir: string): string {
+  return join(agentDir, 'secrets.json')
+}
+
+export async function runLineBootstrap(input: LineLoginInput): Promise<LineBootstrapStatus> {
+  try {
+    const store = new SecretsLineCredentialStore({ mode: 'host', secretsPath: lineSecretsPath(input.agentDir) })
+    // The LINE SDK persists the minted auth_token + certificate by calling
+    // setAccount() on whatever credential manager the client was built with.
+    // Wiring our secrets.json-backed store in here means a successful login
+    // writes straight to secrets.json#channels.line — no second copy in
+    // ~/.config/agent-messenger to keep in sync.
+    const client = input.client ?? buildLineClient(store)
+
+    const result =
+      input.method === 'qr'
+        ? await client.loginWithQR({
+            onQRUrl: (url) => input.callbacks.onQRUrl?.(url),
+            onPincode: input.callbacks.onPincode,
+          })
+        : await client.loginWithEmail({
+            email: input.email,
+            password: input.password,
+            onPincode: input.callbacks.onPincode,
+          })
+
+    if (!result.authenticated || result.account_id === undefined) {
+      const reason = result.message ?? result.error ?? 'LINE login did not authenticate'
+      return { ok: false, reason }
+    }
+
+    // The SDK persists the account by calling setAccount() on the credential
+    // manager as a side effect of login. We can't assume it did: read the
+    // record back and require an auth_token before declaring success, so a
+    // login that authenticated but failed to persist surfaces as an error
+    // instead of a green "added" with an empty secrets.json#channels.line.
+    const persisted = await store.getAccount(result.account_id)
+    if (persisted === null || persisted.auth_token === '') {
+      return { ok: false, reason: 'LINE login authenticated but did not persist credentials' }
+    }
+
+    await store.setCurrentAccount(result.account_id)
+    return { ok: true }
+  } catch (err) {
+    return { ok: false, reason: err instanceof Error ? err.message : String(err) }
+  }
+}
+
+function buildLineClient(store: SecretsLineCredentialStore): LineLoginClient {
+  // The upstream LineClient constructor takes a LineCredentialManager. Our
+  // store implements the same setAccount/getAccount surface the login path
+  // calls, so it stands in as the credential manager via a structural cast.
+  const credManager = store as unknown as LineCredentialManager
+  return new RealLineClient(credManager) as unknown as LineLoginClient
+}

package/src/init/models-dev.ts

@@ -20,6 +20,9 @@ const PROVIDER_TO_MODELS_DEV: Record<KnownProviderId, string> = {
   // catalog. models.dev tracks the underlying model metadata under `zai`,
   // so we route lookups there. The curated entries still get surfaced.
   'zai-coding': 'zai',
+  xai: 'xai',
+  minimax: 'minimax',
+  deepseek: 'deepseek',
 }
 
 export type ModelOption = {

package/src/init/run-owner-claim.ts

@@ -10,6 +10,7 @@ const CHANNEL_LABELS: Record<ChannelKind, string> = {
   'discord-bot': 'Discord',
   github: 'GitHub',
   'telegram-bot': 'Telegram',
+  line: 'LINE',
   kakaotalk: 'KakaoTalk',
 }
 

package/src/init/validate-api-key.ts

@@ -7,6 +7,9 @@ const PROVIDER_PROBE: Partial<Record<KnownProviderId, { url: string; authHeader:
   fireworks: { url: 'https://api.fireworks.ai/inference/v1/models', authHeader: 'bearer' },
   zai: { url: 'https://api.z.ai/api/paas/v4/models', authHeader: 'bearer' },
   'zai-coding': { url: 'https://api.z.ai/api/coding/paas/v4/models', authHeader: 'bearer' },
+  xai: { url: 'https://api.x.ai/v1/models', authHeader: 'bearer' },
+  minimax: { url: 'https://api.minimax.io/v1/models', authHeader: 'bearer' },
+  deepseek: { url: 'https://api.deepseek.com/models', authHeader: 'bearer' },
 }
 
 // When a base-URL override (ANTHROPIC_BASE_URL / OPENAI_BASE_URL) points at a
@@ -159,8 +162,20 @@ export const API_KEY_DASHBOARD_URL: Partial<Record<KnownProviderId, string>> = {
   fireworks: 'https://fireworks.ai/account/api-keys',
   zai: 'https://docs.z.ai/devpack/tool/claude#api-key',
   'zai-coding': 'https://docs.z.ai/devpack/tool/claude#api-key',
+  xai: 'https://console.x.ai',
+  minimax: 'https://platform.minimax.io/user-center/basic-information/interface-key',
+  deepseek: 'https://platform.deepseek.com/api_keys',
 }
 
+// MiniMax sells the same `minimax` provider under two billing surfaces that
+// each hand out a key on a DIFFERENT dashboard page: pay-as-you-go API keys
+// (the API_KEY_DASHBOARD_URL above) and Token Plan "Subscription Keys"
+// (sk-cp-…, this URL). Both keys are Bearer tokens for the same api.minimax.io
+// endpoint and store in the same MINIMAX_API_KEY slot — the runtime doesn't
+// care which. The init wizard surfaces the choice only to deep-link the
+// correct dashboard, so a Token Plan subscriber isn't sent to the paygo page.
+export const MINIMAX_TOKEN_PLAN_DASHBOARD_URL = 'https://platform.minimax.io/user-center/payment/token-plan'
+
 export function providersWithApiKeyProbe(): KnownProviderId[] {
   return Object.keys(PROVIDER_PROBE) as KnownProviderId[]
 }

package/src/inspect/label.ts

@@ -5,6 +5,7 @@ const ADAPTER_DISPLAY: Record<string, string> = {
   'discord-bot': 'Discord',
   github: 'GitHub',
   'telegram-bot': 'Telegram',
+  line: 'LINE',
   kakaotalk: 'KakaoTalk',
 }
 

package/src/permissions/match-rule.ts

@@ -16,7 +16,7 @@
 // error messages with typo suggestions; a single big regex would only ever
 // say "didn't match".
 
-export const PLATFORMS = ['slack', 'discord', 'telegram', 'kakao', 'github'] as const
+export const PLATFORMS = ['slack', 'discord', 'telegram', 'line', 'kakao', 'github'] as const
 export type Platform = (typeof PLATFORMS)[number]
 
 const SUBAGENT_NAME = /^[a-z][a-z0-9-]*$/
@@ -35,9 +35,10 @@ export type MatchRule =
       workspace?: string
       chat?: string
       // Buckets for DM-style scopes. `slack:dm/*`, `discord:dm/*`,
-      // `kakao:dm/*`, `kakao:group/*`, `kakao:open/*` produce `bucket` only
-      // (no workspace, no chat).
-      bucket?: 'dm' | 'group' | 'open'
+      // `kakao:dm/*`, `kakao:group/*`, `kakao:open/*`, `line:dm/*`,
+      // `line:group/*`, `line:square/*` produce `bucket` only (no workspace,
+      // no chat).
+      bucket?: 'dm' | 'group' | 'open' | 'square'
       author?: string
     }
 
@@ -50,7 +51,7 @@ export type ParseMatchRuleResult = { ok: true; value: MatchRule } | { ok: false;
 // this to `author:` only, the JSON schema would reject typos with a generic
 // "did not match pattern" error and the user would lose the actionable hint.
 export const MATCH_RULE_REGEX_SOURCE =
-  '^(tui|cron|subagent(:[a-z][a-z0-9-]*)?|\\*|(slack|discord|telegram|kakao|github):[^\\s]+)(\\s+[a-zA-Z][a-zA-Z0-9_]*:[^\\s]+)*$'
+  '^(tui|cron|subagent(:[a-z][a-z0-9-]*)?|\\*|(slack|discord|telegram|line|kakao|github):[^\\s]+)(\\s+[a-zA-Z][a-zA-Z0-9_]*:[^\\s]+)*$'
 
 export function parseMatchRule(input: string): ParseMatchRuleResult {
   if (input !== input.trim() || input.length === 0) {
@@ -164,15 +165,16 @@ function parseChannelScope(platform: Platform, rest: string, author: string | un
       }
     }
 
-    if (head === 'dm' || head === 'group' || head === 'open') {
-      if (platform !== 'kakao' && (head === 'group' || head === 'open')) {
-        return { ok: false, error: `bucket '${head}' is only valid for kakao` }
+    if (head === 'dm' || head === 'group' || head === 'open' || head === 'square') {
+      const bucketError = invalidBucketForPlatform(head, platform)
+      if (bucketError !== null) {
+        return { ok: false, error: bucketError }
       }
       if (tail === '') {
         return { ok: false, error: `bucket '${platform}:${head}/' requires '*' or a chat id` }
       }
       if (tail === '*') {
-        return { ok: true, value: buildChannelRule(platform, { bucket: head as 'dm' | 'group' | 'open', author }) }
+        return { ok: true, value: buildChannelRule(platform, { bucket: head, author }) }
       }
       // `slack:dm/<id>` — keep the bucket plus the specific chat. We omit a
       // separate workspace field; DM IDs are globally unique within a
@@ -180,7 +182,7 @@ function parseChannelScope(platform: Platform, rest: string, author: string | un
       return {
         ok: true,
         value: buildChannelRule(platform, {
-          bucket: head as 'dm' | 'group' | 'open',
+          bucket: head,
           chat: tail,
           author,
         }),
@@ -199,12 +201,26 @@ function parseChannelScope(platform: Platform, rest: string, author: string | un
   }
 
   // No slash: `slack:T0123` or `kakao:dm` (bare bucket — error).
-  if (rest === 'dm' || rest === 'group' || rest === 'open') {
+  if (rest === 'dm' || rest === 'group' || rest === 'open' || rest === 'square') {
     return { ok: false, error: `bucket '${platform}:${rest}' requires a chat id or '*'` }
   }
   return { ok: true, value: buildChannelRule(platform, { workspace: rest, author }) }
 }
 
+// `dm` is universal. `group`/`open` are KakaoTalk buckets; `group`/`square`
+// are LINE buckets. Reject a bucket on a platform whose workspace shapes don't
+// produce it, so a typo'd rule fails loudly instead of silently never matching.
+function invalidBucketForPlatform(bucket: 'dm' | 'group' | 'open' | 'square', platform: Platform): string | null {
+  if (bucket === 'dm') return null
+  if (bucket === 'open') {
+    return platform === 'kakao' ? null : `bucket 'open' is only valid for kakao`
+  }
+  if (bucket === 'square') {
+    return platform === 'line' ? null : `bucket 'square' is only valid for line`
+  }
+  return platform === 'kakao' || platform === 'line' ? null : `bucket 'group' is only valid for kakao or line`
+}
+
 function parseGithubChannelScope(rest: string, author: string | undefined): ParseMatchRuleResult {
   const [owner, repo, ...chatParts] = rest.split('/')
   if (owner === undefined || owner === '' || repo === undefined || repo === '') {
@@ -230,7 +246,7 @@ function buildChannelRule(
   parts: {
     workspace?: string
     chat?: string
-    bucket?: 'dm' | 'group' | 'open'
+    bucket?: 'dm' | 'group' | 'open' | 'square'
     author?: string
   },
 ): MatchRule {

package/src/permissions/resolve.ts

@@ -7,6 +7,7 @@ const ADAPTER_TO_PLATFORM: Record<AdapterId, Platform> = {
   'discord-bot': 'discord',
   github: 'github',
   'telegram-bot': 'telegram',
+  line: 'line',
   kakaotalk: 'kakao',
 }
 
@@ -63,10 +64,16 @@ function matchesChannel(rule: Extract<MatchRule, { kind: 'channel' }>, origin: M
 // the origin's workspace is `@dm` (Slack) or `dm` (Discord). KakaoTalk uses
 // the workspace prefix itself.
 function matchesBucket(
-  bucket: 'dm' | 'group' | 'open',
+  bucket: 'dm' | 'group' | 'open' | 'square',
   origin: Extract<MatchableOrigin, { kind: 'channel' }>,
 ): boolean {
   const platform = ADAPTER_TO_PLATFORM[origin.adapter]
+  if (platform === 'line') {
+    if (bucket === 'dm') return origin.workspace === '@line-dm'
+    if (bucket === 'group') return origin.workspace === '@line-group'
+    if (bucket === 'square') return origin.workspace === '@line-square'
+    return false
+  }
   if (platform === 'kakao') {
     if (bucket === 'dm') return origin.workspace === '@kakao-dm'
     if (bucket === 'group') return origin.workspace === '@kakao-group'

package/src/role-claim/match-rule.ts

@@ -25,11 +25,15 @@ export type PartialChannelOrigin = {
   authorId: string
 }
 
-const ADAPTER_TO_PLATFORM: Record<ChannelKey['adapter'], 'slack' | 'discord' | 'telegram' | 'kakao' | 'github'> = {
+const ADAPTER_TO_PLATFORM: Record<
+  ChannelKey['adapter'],
+  'slack' | 'discord' | 'telegram' | 'kakao' | 'line' | 'github'
+> = {
   'slack-bot': 'slack',
   'discord-bot': 'discord',
   github: 'github',
   'telegram-bot': 'telegram',
+  line: 'line',
   kakaotalk: 'kakao',
 }
 

package/src/run/index.ts

@@ -30,9 +30,11 @@ import {
 import { createTunnelBridge, type TunnelBridge } from '@/channels/tunnel-bridge'
 import { createConfigReloadable, getConfig, loadConfigSync, loadPluginConfigsSync, reloadConfig } from '@/config'
 import {
+  type CountStore,
   type CronConsumer,
   type CronJob,
   type CronFile,
+  createCountStore,
   createCronConsumer,
   createCronReloadable,
   createScheduler,
@@ -77,7 +79,12 @@ type BunServer = ReturnType<Server['start']>
 export type TuiFactory = (options: TuiOptions) => { run: () => Promise<unknown> }
 
 export type LoadCronFn = (agentDir: string, options?: { subagents?: SubagentRegistry }) => Promise<LoadCronResult>
-export type SchedulerFactory = (options: { cwd: string; file: CronFile; onFire: (job: CronJob) => void }) => Scheduler
+export type SchedulerFactory = (options: {
+  cwd: string
+  file: CronFile
+  onFire: (job: CronJob) => void
+  onCountStore?: (store: CountStore) => void
+}) => Scheduler | Promise<Scheduler>
 export type ChannelManagerFactory = typeof createChannelManager
 export type TunnelManagerFactory = (options: TunnelManagerOptions) => TunnelManager
 
@@ -419,9 +426,23 @@ export async function startAgent({
   })
   subagentConsumer.start()
 
+  // Populated by startScheduler's factory (onCountStore). The consumer
+  // subscribes before this is set, but only touches the holder at fire time
+  // (reading the count via `get` and recording it via `increment`) — and the
+  // scheduler (the sole cron publisher) is armed only AFTER the holder is
+  // populated, so no count-limited fire can observe an undefined holder. If
+  // another cron publisher is ever added, create the store before this point.
+  let cronCountStore: CountStore | undefined
   const cronConsumer = createCronConsumer({
     stream,
     cwd,
+    countStore: {
+      get: (id, job) => cronCountStore?.get(id, job) ?? 0,
+      // Holder is always set before any fire (see above); the `false` fallback
+      // fails safe — skip dispatch rather than run an uncounted count-job — for
+      // the unreachable case where a fire somehow predates the holder.
+      increment: (id, job, at) => cronCountStore?.increment(id, job, at) ?? Promise.resolve(false),
+    },
     invokeHandler: async (job) => {
       const snap = pluginRuntime.get()
       const registered = snap.registry.cronJobs.find((j) => j.globalId === job.id)
@@ -532,6 +553,11 @@ export async function startAgent({
 
   const internalJobs = () => pluginCronJobs(pluginRuntime.get().registry)
   const factory = createSchedulerFor ?? makeDefaultSchedulerFactory(internalJobs)
+  // Subscribe the consumer BEFORE the scheduler arms any timers. The stream
+  // delivers only to live subscribers (no replay), so a fire published before
+  // the subscription exists would be lost. Subscribing to an empty stream is
+  // harmless when there are no jobs.
+  cronConsumer.start()
   const scheduler = await startScheduler({
     cwd,
     loadCron,
@@ -539,10 +565,12 @@ export async function startAgent({
     stream,
     hasInternalJobs: internalJobs().length > 0,
     getSubagents: () => pluginRuntime.get().subagents,
+    onCountStore: (store) => {
+      cronCountStore = store
+    },
   })
 
   if (scheduler) {
-    cronConsumer.start()
     reloadRegistry.register(
       createCronReloadable({ cwd, scheduler, internalJobs, getSubagents: () => pluginRuntime.get().subagents }),
     )
@@ -721,6 +749,7 @@ export async function startAgent({
     ...mcpManagerOpt,
     agentDir: cwd,
     pluginRuntime,
+    getFiredCount: (job) => cronCountStore?.get(job.id, job) ?? 0,
     claimController,
     commandRunnerFactory,
     tunnelManager,
@@ -838,6 +867,7 @@ async function startScheduler({
   stream,
   hasInternalJobs,
   getSubagents,
+  onCountStore,
 }: {
   cwd: string
   loadCron: LoadCronFn
@@ -845,6 +875,7 @@ async function startScheduler({
   stream: Stream
   hasInternalJobs: boolean
   getSubagents?: () => SubagentRegistry
+  onCountStore?: (store: CountStore) => void
 }): Promise<Scheduler | null> {
   let result: LoadCronResult
   const subagents = getSubagents?.()
@@ -864,13 +895,19 @@ async function startScheduler({
   const onFire = (job: CronJob) => {
     stream.publish({ target: { kind: 'cron', jobId: job.id }, payload: job })
   }
-  const scheduler = createSchedulerFor({ cwd, file, onFire })
+  const scheduler = await createSchedulerFor({ cwd, file, onFire, onCountStore })
   scheduler.start()
   return scheduler
 }
 
 function makeDefaultSchedulerFactory(internalJobs: () => CronJob[]): SchedulerFactory {
-  return ({ file, onFire }) => createScheduler({ jobs: [...file.jobs, ...internalJobs()], onFire })
+  return async ({ cwd, file, onFire, onCountStore }) => {
+    const jobs = [...file.jobs, ...internalJobs()]
+    const countStore = await createCountStore(cwd, jobs)
+    // Share the one store instance with the consumer's authoritative count gate.
+    onCountStore?.(countStore)
+    return createScheduler({ jobs, onFire, countStore })
+  }
 }
 
 // Exported for the regression test in `merge-subagents.test.ts`. The shim