Session timeline (Core API)

Internal append-only event log for diagnosing session lifecycle and runner scheduling. Not exposed on v1/v2 public APIs.

Storage

Table SessionTimelineEvents (Postgres via EF Core):

Column	Purpose
`Id`	Monotonic cursor for pagination
`SessionId`	FK to session (`ON DELETE CASCADE`)
`OccurredAtUtc`	Event timestamp
`Kind`	`SessionTimelineEventKind` (smallint)
`NodeInstanceId`	Soft reference (no FK)
`RunnerTaskId`	Soft reference (no FK)
`NodeOutputId`	Soft reference (no FK)
`Detail`	Kind-specific numeric payload

No string metadata columns.

Event kinds

Kind	Value	When emitted
`SessionCreated`	1	Session persisted
`NodeConfigurationUpdated`	10	Node `Configuration` changed
`NodeStateChanged`	11	Node `LastState` changed (deduped if unchanged)
`ReprocessTriggered`	12	`ReprocessNodeAsync`
`NodeOutputRegistered`	13	After `CreateNodeOutputAsync` save
`TaskCreated`	20	After `CreateTaskAsync` save
`TaskClaimed`	21	Successful `ClaimTaskAsync`
`TaskExecutionStarted`	22	`SignalStartTaskExecutionAsync`
`TaskCompleted`	23	`CompleteTaskAsync` / `MarkTaskAsCompleteAsync`
`TaskFailed`	24	`FailTaskAsync` and claim retry exhaustion
`TaskSuperseded`	25	Join fingerprint supersede

Detail field

Kind	Detail
`NodeStateChanged`	`(short)NodeState`
`TaskFailed`	`(short)RunnerTaskState.Failed`
`TaskSuperseded`	`(short)SessionTimelineSupersedeReason` (`JoinFingerprintExpanded = 1`)

Read API

GET /api/sessions/{sessionId}/timeline

Query parameters:

after (long, default 0): return rows with Id > after
limit (int, default 500, max 2000)

Response shape:


{
  "sessionId": "...",
  "events": [
    {
      "id": 1,
      "at": "2026-06-03T12:00:00Z",
      "kind": "TaskCreated",
      "nodeInstanceId": 153,
      "runnerTaskId": 42,
      "nodeOutputId": null,
      "detail": null
    }
  ],
  "nextAfter": 1
}

agentic-cli


node dist/cli.js timeline <session-guid>

Uses the same endpoint as above. Optional --pretty for formatted JSON.

Implementation

Model: core/api/Models/SessionTimelineEvent.cs
Service: core/api/Services/SessionTimelineService.cs
Writes are best-effort: append failures are logged and do not fail the primary operation.

Existing sessions have no backfilled timeline rows.