---
name: daemon-state-diagram
description: Use when the user wants visual state machines of the cryochamber daemon — the overall event loop around inbox messages and TODO-triggered wakes, plus per-item lifecycles for a message and for a reminder — rendered as hand-written SVGs
---

# Daemon State Diagrams (hand-written SVG)

## Overview

Produce up to two SVG files under `docs/diagrams/`:

1. **`daemon-state.svg`** — one-page overview of the daemon's event loop
   around inbox messages and past-due TODOs (the default output).
2. **`lifecycles.svg`** — two stacked sections: how a single inbox
   message travels from arrival to reply, and how a single TODO
   (reminder) travels from creation through due / consumed /
   cleanly-finished or retried.

Decide which diagrams to produce from the user's ask. "Show how the daemon
reacts" → diagram 1. "Show how a message / TODO is consumed" → diagram 2.
"Both" → both files.

**Why hand-written SVG.** No build tool, no package pinning, no compile
step. The `.svg` drops straight into a browser, README, mdBook, or
GitHub preview. Fixed layouts like these state machines don't benefit
from auto-layout — pixel-perfect placement is actually an advantage
here. The cost is that the agent has to pick coordinates; the style
system below makes that cheap.

## Visual style (applies to every diagram)

- **State name on top, plain-language description below.** Use a `<g>`
  group per node with a `<rect>` for the shape and stacked `<text>`
  lines: one `.title` (bold, dark) and 1–3 `.desc` lines (10px, gray).
- **Events live on the edges, not in the nodes.** Every edge label is
  a `<text class="elabel">` with a paint-order halo so it cuts through
  crossing lines cleanly (`paint-order: stroke; stroke: white;
  stroke-width: 3.5;`).
- **Translate Rust identifiers into plain English.** Instead of
  `WakeFromSchedule` / `InboxChanged` / `consume_past_due` /
  `reschedule_consumed`, write "a reminder came due" / "new mail
  arrived" / "pick up every reminder whose time has passed" / "retry
  with a longer delay". The caption / legend block is the right place
  for the precise rules (hibernate precondition, unanswered-mail
  fallback, `2^k`-minute backoff cap).
- **Consistent palette.** Four semantic colours, each a (fill, stroke)
  pair:
  - `idle`   = `#eef5ff` / `#6b9bd8` — blue, daemon sleeping / waiting
  - `active` = `#fff5e6` / `#d8a15b` — orange, in-flight / agent running
  - `done`   = `#eaf7ea` / `#6bb06b` — green, finalised / terminal
  - `crash`  = `#fde8e8` / `#aa3333` — red, crash and retry branch
  - `entry`  = `#f3f3f3` / `#a0a0a0` — neutral pill for entry / exit
- **Shape per role.** Rounded rectangles (`rx="10"`) for ordinary
  states, pill shapes (`rx="32"` on a ~64px-tall rect) for entry /
  exit states. Crash branch edges use `stroke-dasharray: 5 3.5` and
  the red stroke colour.
- **Soft drop shadow on every node** via a single `<filter id="shadow">`
  — `feDropShadow dx="0.8" dy="1.6" stdDeviation="1.4" flood-opacity="0.2"`
  is the house style. Makes the diagram read as layered rather than
  flat, without looking skeuomorphic.

## Starter template

Every diagram starts from the same skeleton. Copy this, then edit
nodes and edges — do **not** rebuild the style block from scratch.

```xml
<svg xmlns="http://www.w3.org/2000/svg"
     viewBox="-40 -95 1010 790"
     font-family="-apple-system, system-ui, 'Segoe UI', sans-serif">
  <defs>
    <filter id="shadow" x="-20%" y="-20%" width="140%" height="140%">
      <feDropShadow dx="0.8" dy="1.6" stdDeviation="1.4" flood-opacity="0.2"/>
    </filter>
    <marker id="arrow" viewBox="0 0 10 10" refX="8" refY="5"
            markerWidth="8" markerHeight="8" orient="auto-start-reverse">
      <path d="M0,0 L10,5 L0,10 z" fill="#4a5568"/>
    </marker>
    <marker id="arrow-red" viewBox="0 0 10 10" refX="8" refY="5"
            markerWidth="8" markerHeight="8" orient="auto-start-reverse">
      <path d="M0,0 L10,5 L0,10 z" fill="#aa3333"/>
    </marker>
    <style><![CDATA[
      .node   { stroke-width: 1.3; }
      .entry  { fill: #f3f3f3; stroke: #a0a0a0; }
      .idle   { fill: #eef5ff; stroke: #6b9bd8; }
      .active { fill: #fff5e6; stroke: #d8a15b; }
      .done   { fill: #eaf7ea; stroke: #6bb06b; }
      .crash  { fill: #fde8e8; stroke: #aa3333; }
      .title  { font-size: 13px; font-weight: 600; fill: #1e2838; text-anchor: middle; }
      .desc   { font-size: 10px; fill: #6a6e7a; text-anchor: middle; }
      .edge     { stroke: #4a5568; stroke-width: 1.3; fill: none; }
      .edge-red { stroke: #aa3333; stroke-width: 1.3; fill: none;
                  stroke-dasharray: 5 3.5; }
      .elabel, .elabel-red {
        font-size: 10px; text-anchor: middle; font-weight: 500;
        paint-order: stroke; stroke: white; stroke-width: 3.5;
        stroke-linejoin: round;
      }
      .elabel     { fill: #222; }
      .elabel-red { fill: #aa3333; }
      .big-title { font-size: 17px; font-weight: 700; fill: #1e2838; text-anchor: middle; }
    ]]></style>
  </defs>

  <text x="450" y="-65" class="big-title">Diagram Title Here</text>

  <!-- Node template: rounded rect with two-line description -->
  <g transform="translate(CX,CY)">
    <rect class="node idle" x="-90" y="-35" width="180" height="70"
          rx="10" filter="url(#shadow)"/>
    <text class="title" y="-8">State Name</text>
    <text class="desc"  y="8">first line of description,</text>
    <text class="desc"  y="22">second line if needed</text>
  </g>

  <!-- Pill template (entry / exit): short, fully rounded -->
  <g transform="translate(CX,CY)">
    <rect class="node entry" x="-80" y="-32" width="160" height="64"
          rx="32" filter="url(#shadow)"/>
    <text class="title" y="-6">Entry / Exit</text>
    <text class="desc"  y="10">short description</text>
    <text class="desc"  y="23">(two lines max)</text>
  </g>

  <!-- Straight edge template -->
  <path class="edge" d="M X1,Y1 L X2,Y2" marker-end="url(#arrow)"/>
  <text class="elabel" x="LX" y="LY">event name</text>

  <!-- Curved edge template (Q = quadratic Bézier) -->
  <path class="edge" d="M X1,Y1 Q CX,CY X2,Y2" marker-end="url(#arrow)"/>

  <!-- Loop-back arc template (C = cubic Bézier, pulls above the row) -->
  <path class="edge" d="M X1,Y1 C X1,-55 X2,-55 X2,Y2" marker-end="url(#arrow)"/>

  <!-- Red dashed crash edge -->
  <path class="edge-red" d="M X1,Y1 L X2,Y2" marker-end="url(#arrow-red)"/>
  <text class="elabel-red" x="LX" y="LY">crashed</text>

</svg>
```

## Layout rules

- **Grid.** Use three columns for the daemon-state diagram (column
  centres ~140 / 450 / 760, ~310px apart) and four rows (centres
  ~90 / 270 / 450 / 620, ~180px apart). This keeps nodes visually
  aligned without a layout engine.
- **Anchor coordinates to node edges, not centres.** A node at
  centre `(cx, cy)` with width 180 has left edge at `cx-90` and right
  edge at `cx+90`. Edges should start and end at those anchors so the
  arrowhead doesn't overlap the rect — e.g. `M 230,90 L 358,90` for
  two nodes with centres at `(140,90)` and `(450,90)`, leaving 2–5 px
  of air before the arrowhead.
- **Curved edges** use `Q cx,cy x2,y2` (one control point) for gentle
  diagonals between neighbouring cells, and `C x,y x,y x,y` (two
  control points) for loop-back arcs that pass above or below the
  main grid.
- **Bidirectional edges** get both `marker-start` and `marker-end`
  pointing at the same marker. `orient="auto-start-reverse"` on the
  marker definition makes the start arrow flip automatically.
- **Label placement.** For horizontal edges, put the label ~8 px
  above the line. For curved edges, put the label at roughly the
  Bézier midpoint — if the curve crosses other lines, the white halo
  will still make the label readable.
- **viewBox with generous top margin** when a loop-back arc exits the
  top of the grid (daemon-state's `decide → idle` arc peaks around
  y=−35). `viewBox="-40 -95 1010 790"` is the working frame for the
  daemon-state diagram; the lifecycles diagram uses a shorter top
  margin because nothing loops above.

## Workflow

1. **Analyse the daemon sources.** Read these files (in order) and
   summarise the state transitions around wake events, inbox handling,
   session run, and crash retry:
   - `src/daemon.rs` — top-level event loop, SIGUSR1 handling, inbox watcher
   - `src/daemon/schedule.rs` — how the next wake time is computed
   - `src/daemon/session.rs` — session launch and finalisation
   - `src/daemon/request.rs` — IPC request dispatch (`Receive`, `Send`,
     `TodoAdd`, …)
   - `src/daemon/effects.rs` — `SessionEffects` / `FsSessionEffects`
   - `src/daemon/inbox.rs` — `SessionInboxState` (which tracks the
     *reply obligation* for a received batch; the file itself is
     archived immediately at receive time)
   - `src/todo.rs` — `consume_past_due`, `reschedule_consumed`,
     `bump_attempt`, `retry_delay_minutes`
   - `src/message.rs` + `src/channel/store.rs` — `MessageStore`
     `read_and_archive_inbox` (no pending area; receive → archive
     atomically)
   Keep the summary in the conversation; do not invent a separate
   markdown file.

2. **Identify the states.** Minimum set for `daemon-state.svg` (add
   more only if the summary surfaces them):
   - `Idle` — daemon sleeping on 250 ms ticks; serves `Ping`, `Hello`,
     `Receive`, `Todo*`; refuses `Send` / `Hibernate`.
   - `Triggered` — `WakeFromSchedule` / `InboxChanged` / SIGUSR1
     sets `run_now`.
   - `Collect Reminders` — `TodoFile::consume_past_due` marks due
     items `done` and returns `Vec<(text, at)>`.
   - `Session Running` + `Serving Agent` — agent spawned; handles
     `Send` (also finalises any claimed inbox batch), `Receive`
     (archives the current inbox batch and records filenames in
     `SessionInboxState`), `Hibernate`, `Todo*`.
   - `Session Ends` — child exited / shutdown / timeout
     (`resolve_child_exit` / `resolve_interrupted_session`).
   - `Wrap Up` — `finalize_human_replies` writes a
     `from: cryochamber` fallback reply for any still-claimed batch,
     then `EventLogger::finish`.
   - `Pick Next Step` — `decide_next_step` → `PlanComplete` |
     `Hibernate` | `RotateProvider`.
   - `Plan Complete` — terminal; daemon exits.
   - `Retry After Crash` — `reschedule_consumed_after_crash` →
     `bump_attempt` + `2^k` minutes (capped at 1 day) → new TODO
     feeds back into `Collect Reminders`.

3. **Write the SVG file** at `docs/diagrams/<name>.svg` (create the
   directory if missing). Start from the skeleton above and fill in
   nodes / edges by grid coordinates. Re-use the style block verbatim —
   don't invent new colours or font sizes without reason.

4. **Validate.** Run an XML well-formedness check (the SVG must parse
   as XML) and verify each `id`, `class`, and `url(#...)` reference
   resolves. One quick smoke test:
   ```bash
   python3 -c 'import xml.etree.ElementTree as ET; ET.parse("docs/diagrams/daemon-state.svg")'
   ```
   If `xmllint` is available, `xmllint --noout docs/diagrams/*.svg`
   is even better.

5. **Ask the user whether to open the SVG.** After producing the
   file(s), show the output paths and ask a single yes/no question:

   > Wrote `docs/diagrams/daemon-state.svg`. Open it now? (y/n)

   On `y` (macOS), run `open docs/diagrams/daemon-state.svg` — it
   opens in the default browser / Preview. On Linux try `xdg-open`.
   Do **not** open the SVG without explicit consent.

## Files produced

- `docs/diagrams/daemon-state.svg` — overall event-loop state machine.
- `docs/diagrams/lifecycles.svg` — two stacked sections:
  - *How a Message Travels Through the Chamber*: Arrived → Waiting
    to be Read → Received (file archived immediately, reply
    obligation still open) → Answered by Agent **or** Answered by
    Chamber. There is **no crash-restore arc** — consumption is
    terminal; even on crash, the chamber writes the fallback from
    the obligation tracked in `SessionInboxState`.
  - *How a Reminder (TODO) Gets Consumed*: Created → Waiting → Due
    → Consumed → Cleanly Finished **or** Retried Later, where the
    retry branch creates a *new* reminder with `(attempt k)` suffix
    and `2^k`-minute delay capped at 1 day. Early exits from
    *Waiting*: *Marked Done* (`cryo-agent todo done`) and *Removed*
    (`cryo-agent todo remove`).

The `.svg` files are committable source artifacts — there is no
separate build output to gitignore.

## Message lifecycle (for the `lifecycles` diagram)

States, in order:
1. **Arrived** — file landed in `messages/inbox/` (external sync or
   direct drop).
2. **Waiting to be Read** — file sits in the inbox; the daemon uses
   its existence to schedule a wake but does not preview the body.
3. **Received** — `cryo-agent receive` routed through the daemon
   triggered `MessageStore::read_and_archive_inbox`: the file is
   archived under `messages/inbox/archive/` in the same step, and
   `SessionInboxState` records the filenames so the chamber knows a
   reply is still owed.
4a. **Answered by Agent** — a subsequent `cryo-agent send` in the
    same session counts as the reply; `SessionInboxState` clears.
4b. **Answered by Chamber** — session ends (clean exit *or* crash)
    with the obligation still open, so
    `finalize_human_replies` writes a `from: cryochamber` fallback.

Crash semantics: consumption is terminal. There is no arc from
*Received* back to *Waiting*; the file is gone from the inbox the
moment the agent reads it, and the fallback path handles the
unanswered obligation on crash.

## TODO lifecycle (for the `lifecycles` diagram)

1. **Created** — agent called `cryo-agent todo add --at TIME`.
2. **Waiting** — item sits in `todo.json` with a future `at`.
3. **Due** — `at ≤ now`; the scheduler picks it up on the next tick.
4. **Consumed** — the daemon flagged it `done = true` and started a
   session.
5a. **Cleanly Finished** — the session hibernated politely; the
    item stays done.
5b. **Retried Later** — the session crashed;
    `reschedule_consumed` created a **new** item whose text is
    suffixed `(attempt k)` and whose `at = now + 2^k` minutes
    (capped at 1 day). That new item re-enters *Waiting*.

Early exits from *Waiting*: **Marked Done** (`cryo-agent todo done`)
and **Removed** (`cryo-agent todo remove`).

## Quick reference

| Daemon concept | Code location |
|----------------|---------------|
| Event loop / wake | `src/daemon.rs::run_event_loop` |
| Next wake time | `src/daemon/schedule.rs::next_wake_from_todos` |
| Session IPC dispatch | `src/daemon.rs::handle_active_request` |
| Hibernate gate | `src/daemon/request.rs::resolve_hibernate_request` |
| Inbox claim / archive (single step) | `src/channel/store.rs::MessageStore::read_and_archive_inbox` |
| Reply-obligation tracking | `src/daemon/inbox.rs::SessionInboxState` |
| Fallback reply on unanswered batch | `src/daemon.rs::finalize_human_replies` |
| TODO consume + retry | `src/todo.rs` (`consume_past_due`, `bump_attempt`, `retry_delay_minutes`) |
| EventLogger + cryo.log | `src/log.rs` |

| SVG need | Pattern |
|----------|---------|
| Rounded-rect node | `<g transform="translate(cx,cy)"><rect class="node idle" x="-90" y="-35" width="180" height="70" rx="10" filter="url(#shadow)"/>…</g>` |
| Pill node | Same pattern with `rx="32"` on a rect of height ~64 |
| Straight arrow | `<path class="edge" d="M x1,y1 L x2,y2" marker-end="url(#arrow)"/>` |
| Curved arrow | `<path class="edge" d="M x1,y1 Q cx,cy x2,y2" marker-end="url(#arrow)"/>` |
| Loop-back arc | `<path class="edge" d="M x1,y1 C x1,top x2,top x2,y2" marker-end="url(#arrow)"/>` with `top` well outside the main grid |
| Bidirectional | Add `marker-start="url(#arrow)"` with `orient="auto-start-reverse"` on the marker def |
| Dashed crash edge | `class="edge-red"` and `marker-end="url(#arrow-red)"` |
| Edge label with halo | `<text class="elabel" x="lx" y="ly">event</text>` — the halo comes from CSS |

## Common mistakes

- **Drawing from memory.** The daemon re-injects crashed TODOs with
  `2^k`-minute backoff capped at 1 day, and it does *not* preview
  inbox bodies in the wake prompt — verify in `src/todo.rs` and
  `src/daemon.rs` before labelling. Also: receive is archive —
  there is no `inbox/pending/` directory and no crash-restore arc in
  the current code.
- **Writing labels without the halo.** A bare `<text>` on top of an
  edge becomes illegible wherever the edge crosses anything. Always
  use `class="elabel"` (or `elabel-red`) so the `paint-order`
  halo kicks in.
- **Anchoring edges to node centres.** The arrowhead will overlap
  the rect and look muddy. Start and end at the edge of each node.
- **Building the style block from scratch.** Copy the skeleton. The
  palette, drop shadow, and halo values are already tuned.
- **Opening the SVG without asking.** The last workflow step is a
  question, not an action.
- **Writing a markdown state-table next to the SVG.** The SVG is
  the artifact; extra prose belongs in the conversation or in a
  legend block inside the SVG.