docs(maestro): fix five more factual errors in structured-session docs
Corrects recovery-as-two-operations, tmux-only survival on restart, replay's durable-vs-live-state gap, snapshot-vs-replay purpose, and the three-file persistence count. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
co-authored by
Claude Sonnet 5
parent
cdd4213ff5
commit
64741a027e
+15
-8
@@ -188,9 +188,10 @@ read it:
|
||||
a `ReducedState` covering the whole log as it stands, then streams
|
||||
`ProjectionUpdate { transcript, state }` for everything that happens next.
|
||||
There is no client-supplied resume cursor on this socket: every connection
|
||||
gets the full snapshot, not a gap-filled continuation. A client that needs
|
||||
history from before it was connected uses the replay endpoint below, not
|
||||
this socket.
|
||||
gets the full snapshot, not a gap-filled continuation, so a client never
|
||||
needs the replay endpoint just to obtain the current transcript. Use
|
||||
replay instead for cursor-bounded pagination through the durable log —
|
||||
history from before this connection, fetched a page at a time.
|
||||
- **`GET /api/sessions/:id/structured/replay`** — cursor-bounded pagination
|
||||
over the durable log, returning one `StructuredReplayEvent` (`cursor`,
|
||||
`transcript`, `state`) per matching line. `?since=<n>` returns the first
|
||||
@@ -200,9 +201,15 @@ read it:
|
||||
still in ascending order — passing both is a `400`. `?limit` defaults to
|
||||
100 and is clamped to 500. Each call re-folds
|
||||
the entire log from scratch to compute the state at every returned cursor,
|
||||
so a page reflects exactly the state *at* its cursor, not an
|
||||
approximation — at the cost of redoing the whole fold per request. A
|
||||
session that is not a live structured session (terminal, or a dead
|
||||
so a page reflects exactly the *durable* state at its cursor, not an
|
||||
approximation of it — at the cost of redoing the whole fold per request.
|
||||
That durable state is not always identical to what a live client saw at
|
||||
that moment, though: turn lifecycle transitions are broadcast live without
|
||||
a durable event backing them (see [Prompt and cancel](#prompt-and-cancel-bounded-liveness)),
|
||||
and a restored `Approval` row carries no pending nonce, because the nonce
|
||||
never reached disk (see [Approvals](#approvals)) — replay is exact and
|
||||
reconstructible, not a perfect record of everything the live view showed.
|
||||
A session that is not a live structured session (terminal, or a dead
|
||||
adapter) answers `409 not_structured` from either route rather than a
|
||||
coherent-looking but stale reply.
|
||||
|
||||
@@ -286,8 +293,8 @@ allowed to claim the daemon's idea of "the active turn."
|
||||
|
||||
## Persistence, recovery, and dead sessions
|
||||
|
||||
A structured session's durable state is three files next to its sidecar
|
||||
(`<id>.json`) in the sidecar directory:
|
||||
A structured session's durable state is three files in the sidecar
|
||||
directory: the sidecar itself (`<id>.json`), plus two next to it:
|
||||
|
||||
- **`<id>.events.jsonl`** — the unified event log. Each line is either a raw
|
||||
ACP `SessionNotification` (kept in its original JSON so old logs stay
|
||||
|
||||
Reference in New Issue
Block a user