6.6 Cron Runner

1. Bot Identity

2. Purpose

CronRunner maintains the authoritative cron schedule for the entire Polytraders system. It reads a declarative cron manifest (cron_expression per task, UTC), fires each task at the correct wall-clock moment, serialises concurrent firings into an ordered queue, and emits an OperationsReport heartbeat after each dispatch. CronRunner never executes strategy logic or touches the CLOB directly; it is purely a scheduling and dispatch service. Internal-only — no API surface beyond the internal bus.

3. Why This Bot Matters

• Cron task not fired on schedule

  Downstream bots that rely on scheduled triggers (e.g. daily P&L reconciliation, pre-event quoting cycles) silently miss their window. Delayed reconciliation compounds drift.

• Two instances of CronRunner fire the same task simultaneously

  Duplicate fills or double-counted reconciliation records corrupt ledgers and inflate reported P&L.

• CronRunner crashes and does not recover

  All scheduled tasks across all 97 bots stop firing. The system drifts into an uncontrolled state without time-based governance.

• Missed quiet-hours suppression

  Strategies fire during configured quiet hours (e.g. market-open volatility windows), creating unintended exposure.

No worked examples on this bot yet. Worked examples are optional but strongly recommended — they turn an abstract failure mode into something a developer can verify in a fixture.

4. Required Polymarket Inputs

5. Required Internal Inputs

6. Parameter Guide

7. Detailed Parameter Instructions

{ "cron_expression": "0 * * * *" }

parseCron(p.cron_expression) || throw ConfigError('CRON_RUNNER_INVALID_EXPRESSION')

{ "enabled_strategies": [] }

if (!p.enabled_strategies.length) log.warn('CRON_RUNNER_NO_TARGETS')

{ "disable_during_quiet_hours": false }

if (p.disable_during_quiet_hours && isQuietHour(now)) { log.info('CRON_RUNNER_QUIET_HOURS_SKIP'); return; }

{ "max_concurrent_tasks": 20 }

if (p.max_concurrent_tasks > p.hard) throw ConfigError("PARAMETER_CHANGE_REQUIRES_APPROVAL")

8. Default Configuration

{
  "bot_id": "gov.cron_runner",
  "version": "2.0.0",
  "mode": "general_live",
  "defaults": {
    "cron_expression": "0 * * * *",
    "enabled_strategies": [],
    "disable_during_quiet_hours": false,
    "max_concurrent_tasks": 20
  }
}

9. Implementation Flow

1. On startup, load the cron manifest from the config store; parse each entry's cron_expression (UTC) and validate.
2. Register a ticker per unique cron expression; at each tick, collect all tasks whose expression matches the current UTC time.
3. Before dispatching any task, check KillSwitch active flag; if active, suppress trading-adjacent tasks but allow health and governance tasks.
4. For each eligible task, check disable_during_quiet_hours against the current UTC time window.
5. Dispatch the task trigger to each enabled_strategies entry via the internal message bus; log dispatch with a trace_id.
6. After dispatch, emit an OperationsReport heartbeat: { task_id, fired_at_ms, targets, suppressed_count, trace_id }.
7. Detect and deduplicate concurrent firings using a distributed lock keyed on (task_id, scheduled_at_ms); if lock is held, skip and emit CRON_RUNNER_DUPLICATE_FIRE.
8. Retain dispatch logs for 1 year for operational audit.

10. Reference Implementation

Loads a cron manifest, registers tickers, dispatches task triggers at UTC boundaries, deduplicates via distributed lock, and emits an OperationsReport per dispatch.

Pseudocode is language-agnostic. FETCH = read input. EMIT = produce output. Translate to TS/Python/Go/Rust.

// ---- STARTUP ----
FUNCTION init():
  manifest = FETCH config_store.GET('/cron-manifest')
  FOR entry IN manifest:
    validateCronExpression(entry.cron_expression)
    registerTicker(entry)  // fires onTick() when expression matches UTC now

// ---- PER-TICK HANDLER ----
FUNCTION onTick(entry, scheduled_at_ms):
  lock_key = entry.task_id + ':' + scheduled_at_ms
  IF NOT redis.SET(lock_key, NX=true, PX=5000):  // 5s TTL
    log.warn('CRON_RUNNER_DUPLICATE_FIRE', { task_id: entry.task_id })
    RETURN

  ks = FETCH killswitch.status()
  IF ks.active AND entry.task_class == 'trading':
    log.info('CRON_RUNNER_KILL_SWITCH_ACTIVE', { task_id: entry.task_id })
    RETURN

  IF entry.disable_during_quiet_hours AND isQuietHour(now()):
    log.info('CRON_RUNNER_QUIET_HOURS_SKIP', { task_id: entry.task_id })
    EMIT OperationsReport(event_type='CRON_TASK_SUPPRESSED', ...)
    RETURN

  IF NOT entry.enabled_strategies:
    log.warn('CRON_RUNNER_NO_TARGETS', { task_id: entry.task_id })
    RETURN

  trace_id = generateTraceId()
  FOR target IN entry.enabled_strategies:
    internal_bus.publish(topic='cron.trigger', payload={
      task_id:        entry.task_id,
      target:         target,
      scheduled_at:   scheduled_at_ms,
      trace_id:       trace_id
    })

  EMIT OperationsReport({
    report_id:        'ops_cronrunner_' + scheduled_at_ms,
    bot_id:           'gov.cron_runner',
    event_type:       'CRON_TASK_DISPATCHED',
    task_id:          entry.task_id,
    fired_at_ms:      scheduled_at_ms,
    targets:          entry.enabled_strategies,
    suppressed_count: 0,
    trace_id:         trace_id
  })

// ---- MANIFEST RELOAD ----
FUNCTION reloadManifest():
  // Called on config change event; validates and re-registers all tickers
  FOR entry IN FETCH config_store.GET('/cron-manifest'):
    validateCronExpression(entry.cron_expression)
  registerTickers(manifest)  // replaces existing registrations atomically

SDK calls used

• config_store.GET('/cron-manifest')
• redis.SET(lock_key, NX=true, PX=5000)
• killswitch.status()
• internal_bus.publish(topic='cron.trigger', payload=...)
• alerting.emit('CRON_RUNNER_DUPLICATE_FIRE', metadata)

Complexity: O(T) per tick where T = tasks matching the current cron boundary

11. Wire Examples

Input — what arrives on the wire

{
  "label": "Cron manifest entry",
  "source": "config_store",
  "payload": {
    "task_id": "daily_pnl_reconcile",
    "cron_expression": "0 0 * * *",
    "enabled_strategies": [
      "gov.pnl_reporter"
    ],
    "disable_during_quiet_hours": false,
    "task_class": "governance"
  }
}

Output — what the bot emits

{
  "label": "OperationsReport — CRON_TASK_DISPATCHED",
  "payload": {
    "report_id": "ops_cronrunner_1746792000000",
    "bot_id": "gov.cron_runner",
    "event_type": "CRON_TASK_DISPATCHED",
    "task_id": "daily_pnl_reconcile",
    "fired_at_ms": 1746792000000,
    "targets": [
      "gov.pnl_reporter"
    ],
    "suppressed_count": 0,
    "trace_id": "tr_abc123def456",
    "report_kind": "OperationsReport"
  }
}

12. Decision Logic

13. Standard Decision Output

This bot returns a OperationsReport object. See OperationsReport schema.

{
  "report_id": "ops_cronrunner_20260509T120000Z",
  "bot_id": "gov.cron_runner",
  "event_type": "CRON_TASK_DISPATCHED",
  "task_id": "daily_pnl_reconcile",
  "fired_at_ms": 1746792000000,
  "targets": [
    "gov.pnl_reporter"
  ],
  "suppressed_count": 0,
  "trace_id": "tr_abc123def456",
  "report_kind": "OperationsReport"
}

14. Reason Codes

15. Metrics & Logs

Metrics emitted

Alerts

Dashboards

• Grafana — Governance / CronRunner task dispatch timeline
• Grafana — Governance / Scheduled task suppression rate

16. Developer Reporting

{
  "bot_id": "gov.cron_runner",
  "event_type": "CRON_TASK_DISPATCHED",
  "task_id": "hourly_health_sweep",
  "fired_at_ms": 1746788400000,
  "targets": [
    "gov.health_heartbeat"
  ],
  "lock_acquired": true,
  "trace_id": "tr_00deadbeef01"
}

17. Plain-English Reporting

18. Failure-Mode Block

19. Failure-Injection Recipes

20. State & Persistence

Cold-start recovery

On restart, cron manifest is re-fetched from config store and tickers are re-registered. Locks expire naturally. No missed ticks are retroactively fired.

21. Concurrency & Idempotency

22. Dependencies

Depends on (must run first)

Emits to (downstream consumers)

External services

23. Security Surfaces

Abuse vectors considered

• Injecting a malformed cron expression to crash the scheduler
• Racing the distributed lock to trigger double-dispatch of financial tasks
• Modifying the cron manifest to fire tasks outside of approved windows

Mitigations

• All cron expressions are validated at manifest load; invalid entries are rejected with HARD_REJECT
• Distributed lock (Redis SET NX) enforces single-dispatch per (task_id, scheduled_at_ms)
• Config store changes are audit-logged; manifest reload events are emitted as OperationsReport entries
• CronRunner has no CLOB or on-chain access — it only publishes to the internal bus

24. Polymarket V2 Compatibility

API surfaces declared

Networks supported

25. Versioning & Migration

Migration history

26. Acceptance Tests

Unit Tests

Integration Tests

Property Tests

27. Operational Runbook

CronRunner incidents fall into three categories: no dispatch (process down or bus failure), duplicate fires (lock race or multiple instances), or manifest errors (invalid expressions). All three block downstream governance tasks.

On-call actions

Manual overrides

• polytraders gov cron force-dispatch --task-id <id> — Manually trigger a missed cron task after investigating root cause.

Healthcheck

Endpoint: /internal/health/cron-runner | Green: Last dispatch < 65 minutes ago; manifest loaded; Redis lock reachable. | Red: No dispatch in 15 minutes; Redis unreachable; manifest parse errors.

28. Promotion Gates

A bot does not advance to the next readiness state until every gate below is green. Gates are observable from production data — no subjective sign-off.

Promote to Shadow

Promote to Limited live

Promote to General live

29. Developer Checklist

Ready-to-ship score: 27/27 sections complete · 100%