fold-sessions : Sighting* -> Map<Run, Session>
step          : Map<Run, Session> -> Sighting -> Map<Run, Session>   ; pure, total

A sighting with no run, or whose service does not start with cc-, does not touch the table. step is total over every sighting the receiver accepts: an unknown state updates last_seen and counts.events and nothing else.

Session = {
  run          : string            ; key; the Claude Code session_id
  service      : string            ; cc-<last 6 of run>, the log's lane name
  origin       : string|nil        ; attrs.origin (cwd basename: repo or worktree dir)
  host         : string|nil        ; attrs.host  (hostname -s)
  sha          : string|nil        ; attrs.sha at last_seen
  mode, effort : string|nil        ; last NON-EMPTY value seen
  state        : busy | waiting | idle | ended
  stale        : bool              ; derived at read time, see Silence
  first_seen   : epoch ms          ; min start seen by THIS receiver process
  last_seen    : epoch ms          ; max start seen
  started      : epoch ms|nil      ; start of an observed SessionStart, else nil
  ended_at     : epoch ms|nil      ; start of an observed SessionEnd
  last_event   : string            ; state of the sighting that set `state`
  last_tool    : string|nil        ; attrs.tool of the newest Pre/PostToolUse
  open_tools   : int               ; |PreToolUse ids without a PostToolUse*|
  counts       : { events, tools, errors, turns }
}

first_seen and started are different fields on purpose. first_seen is when this receiver first heard of the session, which after a receiver restart can be days after the session began. started is non-nil only when a SessionStart was observed. The view never labels first_seen as "started".

Counts are deduplicated: tools counts distinct attrs.tool_use on PostToolUse / PostToolUseFailure; errors counts sightings with status=error (*Failure, *Denied), deduplicated on (state, tool_use, start); turns counts Stop / StopFailure deduplicated on start; events counts every accepted sighting and is the one count that duplicates inflate.

Four states. Each transition names the hook event, verbatim as state on the sighting, that causes it.

SubagentStop changes nothing because it says a subagent finished, not that the session is working. Observed 2026-10-06 across ten sessions on this box: it arrives seconds after the parent's Stop, and while it mapped to busy every finished session read busy until the stale window. (v2.5.1)

Notification changes nothing because the sighting does not say which kind it is. The raw payload does: in an earlier window of the hook log on this box (since rotated out), 130 notifications were idle_prompt and 8 were permission_prompt. In the 11.6 h window reviewed on 2026-10-07 all 32 were idle_prompt, each 60 to 61 s after a Stop (session dashboards note). The hook drops notification_type, so the receiver cannot tell "waiting for permission" from "idle at the prompt" by this event. PermissionRequest carries that signal instead, and is mapped.

busy means: the most recent state-bearing event is a turn or tool event newer than the most recent Stop. It does not mean a tool is running right now; between tool calls inside a turn the model is generating, and that is busy too. open_tools > 0 is the narrower "a tool is running" and is shown as a detail, not as the state.

digraph sessions {
  rankdir=LR;
  bgcolor=white;
  graph [fontname="Helvetica", fontsize=11, pad=0.3, nodesep=0.5, ranksep=0.7];
  node  [fontname="Helvetica", fontsize=10, style="rounded,filled", shape=box, penwidth=1.2];
  edge  [fontname="Helvetica", fontsize=9, color="#888888", fontcolor="#555555"];

  idle    [label="idle",    fillcolor="#f3f4f6", color="#374151", fontcolor="#374151"];
  busy    [label="busy",    fillcolor="#dcfce7", color="#15803d", fontcolor="#15803d"];
  waiting [label="waiting", fillcolor="#fef3c7", color="#b45309", fontcolor="#b45309"];
  ended   [label="ended",   fillcolor="#fee2e2", color="#b91c1c", fontcolor="#b91c1c"];

  idle    -> busy    [label="UserPromptSubmit\nPreToolUse ..."];
  busy    -> idle    [label="Stop / StopFailure"];
  busy    -> waiting [label="PermissionRequest\nElicitation"];
  idle    -> waiting [label="PermissionRequest"];
  waiting -> busy    [label="PostToolUse\nPermissionDenied\nElicitationResult"];
  waiting -> idle    [label="Stop"];
  idle    -> ended   [label="SessionEnd"];
  busy    -> ended   [label="SessionEnd"];
  waiting -> ended   [label="SessionEnd"];
  ended   -> idle    [label="SessionStart"];
}

The table is authoritative; the diagram is a rendering of it. The PNG is produced by gmake diagrams.

Arrival order is not event order (property 2). The fold orders by start, then by a fixed precedence within one second, and only then by arrival:

key(s)      = (start, rank(state), arrival-seq)
rank        : SessionEnd 4 > Stop, StopFailure 3 > PermissionRequest, Elicitation 2 > everything else 1
state(run)  = transition applied by the sighting with the greatest key among state-bearing sightings

So a PostToolUse stamped in the same second as a Stop but delivered after it leaves the session idle, and a PreToolUse stamped one second after a Stop makes it busy whatever order they arrive in. A sighting older than the current state's key updates counts, first_seen, last_tool (if it is the newest tool event) and nothing else. The precedence encodes one assumption: within a second, a turn-ending event is the later one. A turn that ends and a new one that starts in the same second resolves idle until the next event, which is at most one tool call later.

Duplicates (property 3) are absorbed: open_tools is a set of tool_use ids, not a counter; a second PreToolUse with the same id is a no-op.

• Ring eviction. The session table is updated on ingest and does not depend on the ring. Evicting a session's early sightings from GET /sightings changes nothing in GET /sessions. This is the reason the fold lives in the receiver (5).
• Receiver restart. The table is in memory and starts empty, like the ring. After a restart every session reappears on its next event, with first_seen reset, started nil and counts from zero. Its state is whatever its first post-restart event implies; an idle session stays invisible until it does something. /info gains uptime_s context already; the view shows "since receiver start" when first_seen is within a minute of boot.
• Silence. An idle session emits nothing, so silence cannot mean ended: claude agents --json listed idle sessions started five days earlier. Two timers apply, both evaluated at read time:

stale    = state in {busy, waiting} and now - last_seen > 300 s     ; shown, not a state
expiry   = idle|busy|waiting: now - last_seen > CROWSNEST_SESSION_TTL_S (default 86400)
           ended:             now - ended_at  > 600 s
table    = at most 256 sessions; on overflow drop the least recent last_seen

stale exists because a busy session whose Stop was lost (a down receiver at that moment, a killed process) would otherwise read busy forever. Five minutes is longer than the longest tool call in the ring (one WebFetch at 11.8 s) by a wide margin and shorter than a coffee. An expired session is removed, not marked; it comes back on its next event.

crowsnest is publish/subscribe over a versioned contract, with the dashboard as one rendering of it. spec.org is that contract, and its rules already cover this change: MINOR versions are additive, consumers feature-detect by /info.capabilities, and MAJOR is the only compatibility gate. Hook calls stay the primary feed; nothing here changes how a hook reports.

When the receiver implements this, spec.org gains, in the same change:

Other implementations (the language receivers and reporters) MAY adopt v2.5 and MUST still accept a session.snapshot sighting as an ordinary sighting if they do not: that already holds, because name and state are free strings and the snapshot carries every required field.

Verified on 2026-10-06 against the v2.4 receiver: a session.snapshot sighting posted to POST /sightings returned 200 and was stored and served by GET /sightings like any other.

No POST, PUT or DELETE on /sessions. DELETE /sightings (the clear capability) clears the session table as well as the ring, so "clear" keeps meaning "start the view over". GET / gains _links.sessions, /info gains capability sessions and retention.sessions {cap, ttl_s}.

OpenAPI fragment, in the shape server.clj generates and spec.org inlines. with-cors adds the CORS headers and the options operation, so they are not repeated here.

{
  "paths": {
    "/sessions": {
      "get": {
        "summary": "Session table — one record per run, folded on ingest (v2.5, 'sessions' capability)",
        "responses": {
          "200": {
            "description": "sessions, attention-first then most recent",
            "content": {
              "application/json": {
                "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Session" } }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Session": {
        "type": "object",
        "required": ["run", "service", "state", "stale", "first_seen", "last_seen", "counts"],
        "properties": {
          "run":        { "type": "string",  "description": "the sightings' run (Claude Code session_id); key" },
          "service":    { "type": "string",  "description": "cc-<last 6 of run>; the log's lane" },
          "origin":     { "type": ["string", "null"], "description": "attrs.origin — cwd basename" },
          "host":       { "type": ["string", "null"] },
          "sha":        { "type": ["string", "null"] },
          "mode":       { "type": ["string", "null"], "description": "last non-empty attrs.mode" },
          "effort":     { "type": ["string", "null"], "description": "last non-empty attrs.effort" },
          "state":      { "type": "string", "enum": ["busy", "waiting", "idle", "ended"] },
          "stale":      { "type": "boolean", "description": "busy|waiting with no sighting for 300 s" },
          "first_seen": { "type": "integer", "description": "epoch ms; first sighting seen by this receiver process" },
          "last_seen":  { "type": "integer", "description": "epoch ms" },
          "started":    { "type": ["integer", "null"], "description": "epoch ms of an observed SessionStart; null if not observed" },
          "ended_at":   { "type": ["integer", "null"] },
          "last_event": { "type": "string",  "description": "hook event that set state" },
          "last_tool":  { "type": ["string", "null"] },
          "open_tools": { "type": "integer" },
          "counts": {
            "type": "object",
            "properties": {
              "events": { "type": "integer" }, "tools": { "type": "integer" },
              "errors": { "type": "integer" }, "turns": { "type": "integer" }
            }
          }
        }
      }
    }
  }
}

The endpoint lands as one change: server.clj (route, openapi def, service-index, info, selftest fixtures) and spec.org (endpoint table, History row v2.5, the inline /openapi.json block) move together, or gmake crowsnest-spec-verify reports DRIFT and exits 1. That gate is the calibration for this section: run it once with only server.clj changed and confirm it fails before trusting its pass.

Aside, observed while reading: the run field description in the receiver's OpenAPI says "GET /sightings?run= returns the group". The router matches on path only; GET /sightings?run=<id> on the live receiver returned all 100 sightings. Either the filter or the sentence is wrong. Out of scope here; recorded so the v2.5 change does not copy the claim.

 Sightings | Sessions (4)                               receiver v2.5.0 · up 3h12m

 ● www.wal.sh       [07e8f6]  busy     Bash ×2  auto · medium   macbookpro   first seen 41m ago   2s ago
 ● racketcon-2026   [753a0c]  busy     WebFetch auto · medium   macbookpro   first seen 2h ago    4s ago
 ◐ wharfinger       [d4e1aa]  waiting  Bash     default         macbookpro   started 12m ago      38s ago
 ○ guile-sicp       [edc5f4]  idle     -        -               macbookpro   first seen 3h ago    9m ago
 ✕ skills           [aa454f]  ended    Read     auto            macbookpro   started 1h ago       ended 2m ago

 4 live · 1 ended · folded from 1 214 sightings since receiver start

Rows are grouped by project: a heading per origin, with worktree directories under worktrees/<name> folded into their repository when the path says so, and a count of busy, waiting and idle sessions on the heading.

Clicking a row sets the log filter to that service, so the log answers "what is it doing" and the sessions view answers "what exists".

Three buckets, then a key that does not move: waiting first, busy and idle together, ended last; within a bucket, started descending (first_seen when no SessionStart was seen), then run. A waiting session is the only row that asks something of the reader, so it rises. Nothing else moves a session in the list.

v2.5.0 sorted by state, then last_seen descending (iTerm2's "sorted by priority" choice). With ten concurrent sessions that thrashed: last_seen changes on every hook event, so busy sessions swapped places on every 2 s poll, and a session went from the busy block to the idle block at the end of every turn. The dashboard rail made it worse by ordering projects by their first appearance in this list, so whole projects jumped. From v2.5.2 the rail orders projects alphabetically, a project with a waiting session first. Recency is still shown, as the age on each row; it no longer drives position. Decaying long-idle sessions out of the list is a separate, later change.

claude agents --json (Claude Code 2.1.290) returns, per session: sessionId, name, kind, status, state, cwd, pid, startedAt, and id (first 8 of sessionId, background sessions only). Interactive sessions report status busy / idle; background sessions report state blocked. No tmux field is in the JSON; the tmux column in the example above comes from the interactive list.