Architecture

Chronos is a centralized control plane: one chronosd process serves every per-user agent in the Matrix fleet. It is NOT a per-daemon timer — it is the single source of truth for scheduled time across the entire system.

Source files: chronos.frozen.kvx (design contract), cmd/chronosd/main.go (service entry).

---

The 5 layers

Chronos is built as five stacked layers, each with a single responsibility:

┌──────────────────────────────┐
│  Layer 5: API + Auth         │  HTTP surface for the MCP proxy
│  server/server.go            │  Two-layer auth (transport + principal)
└──────────────────────────────┘
              │
┌──────────────────────────────┐
│  Layer 4: Wake               │  Deliver the contextful turn to the agent
│  wake/wake.go                │  via the router's proven wake path
└──────────────────────────────┘
              │
┌──────────────────────────────┐
│  Layer 3: Dispatch           │  Poll-and-claim worker that fires due alarms
│  dispatch/dispatch.go        │  Retry ladder, at-least-once delivery
└──────────────────────────────┘
              │
┌──────────────────────────────┐
│  Layer 2: Schedule           │  Parse + next-fire computation
│  schedule/schedule.go        │  once (delay/absolute) + cron (5-field/@descriptor/@every)
└──────────────────────────────┘
              │
┌──────────────────────────────┐
│  Layer 1: Store              │  Postgres alarms table — the durable timer
│  store/store.go + alarms.go  │  State lives in the DB, never in memory
└──────────────────────────────┘

The core insight: the hard half (waking a suspended agent) already exists in the router. Chronos owns only the easy half (durable timing + context storage) and hands the fire off to the router's battle-tested EnsureStarted → waitDaemonReady → 6PN reverse-proxy path.

---

Topology

Chronos runs on the core-infra box alongside the router and gateway, as a systemd service. It shares the same Postgres instance the router and gateway use.

Chronos topology (3 network directions)
========================================

INBOUND (agent → chronosd)
  daemon's chronos.mjs → public nginx /chronos/ → 127.0.0.1:9096
  Purpose: post, list, cancel alarms

WAKE (chronosd → router)
  chronosd → POST 127.0.0.1:8088/internal/wake (wake-token auth)
  Purpose: request the router to wake a machine

DELIVER (router → daemon)
  router → fly.EnsureStarted → waitDaemonReady → POST :8080/chat over Fly 6PN
  Purpose: actually wake the machine + inject the context turn

Chronos never talks to Fly or the daemon directly. It reuses the router's existing wake-then-proxy path via one new router surface: POST /internal/wake.

---

Mission

Give every Matrix agent a reliable sense of time: schedule future work, defer mid-task, recur daily, and get woken with enough context to resume seamlessly.

Agents are episodic — a per-user daemon scales to zero between requests and has no way to act later or wait without holding an expensive live process. A centralized durable scheduler lets an agent set work down, release the machine, and be woken precisely when due.

Chronos is: the agent alarm clock + reminder service — post an alarm, get woken with context.

Chronos is NOT: a workflow engine, a job queue for heavy compute, or an on-chain trustless scheduler. It is off-chain timing + contextful wake delivery only.

---

Design principles

---

Relationship to other subsystems