docs(maestro): fix three factual errors in STRUCTURED-VIEW.md
- replay: since=0 returns the first page (still limit-bounded), not the whole log; clients page forward from the last returned cursor - PR_SET_PDEATHSIG is Linux-only; other platforms depend on the terminate() ladder running to completion - approval nonce is minted before cancelling the prior pending approval, not after
This commit is contained in:
+19
-11
@@ -23,10 +23,13 @@ a pane. `crates/maestro-acp` owns the daemon's side of that connection;
|
||||
`crates/maestro-daemon/src/projection.rs` folds what it receives into the two
|
||||
projections below.
|
||||
|
||||
The child is a real child of the daemon process: same process group, marked
|
||||
with `PR_SET_PDEATHSIG` so it dies with the daemon, and ended by
|
||||
`AcpSession::terminate` (`session/cancel`, a short grace, `SIGTERM`, then
|
||||
`SIGKILL`) from both `DELETE /api/sessions/:id` and daemon shutdown.
|
||||
The child is a real child of the daemon process: same process group, and on
|
||||
Linux marked with `PR_SET_PDEATHSIG` so it dies with the daemon even if the
|
||||
daemon exits without cleaning up; other platforms have no such signal and
|
||||
depend on an orderly shutdown/drop to terminate it. The ordinary path on
|
||||
every platform is `AcpSession::terminate` (`session/cancel`, a short grace,
|
||||
`SIGTERM`, then `SIGKILL`), called from both `DELETE /api/sessions/:id` and
|
||||
daemon shutdown.
|
||||
`docs/WORKTREES.md`'s kill-guard rule — an unforced kill refused while the
|
||||
session's worktree holds unsaved work — applies to a structured session
|
||||
exactly as it does to a terminal one; only what gets terminated differs (an
|
||||
@@ -191,9 +194,11 @@ read it:
|
||||
- **`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
|
||||
page after `n` (`since=0` is the whole log); `?before=<n>` returns the
|
||||
page immediately before `n`, still in ascending order — passing both is a
|
||||
`400`. `?limit` defaults to 100 and is clamped to 500. Each call re-folds
|
||||
page after `n` (`since=0` selects from the beginning, i.e. the first
|
||||
page); a client pages forward from there using the cursor of the last
|
||||
event returned. `?before=<n>` returns the page immediately before `n`,
|
||||
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
|
||||
@@ -223,10 +228,13 @@ pending decision, entirely on the daemon side:
|
||||
nonce that would make it "pending" never made it to disk in the first
|
||||
place. A restart therefore cannot resume a pending approval — see
|
||||
[Persistence](#persistence-recovery-and-dead-sessions).
|
||||
- **One live approval at a time.** A new permission request cancels whatever
|
||||
was already pending (`cancel_pending_approvals`) before minting its own
|
||||
nonce — ACP serializes requests through one connection, so this only ever
|
||||
fires if an adapter nonetheless overlaps two, and the newest one wins.
|
||||
- **One live approval at a time.** A new permission request mints its own
|
||||
nonce, then cancels whatever was already pending (`cancel_pending_approvals`)
|
||||
before installing itself as the new pending approval — ACP serializes
|
||||
requests through one connection, so this only ever fires if an adapter
|
||||
nonetheless overlaps two. Either way, the prior pending request is
|
||||
cancelled/cleared before the new one is installed, so the newest request
|
||||
wins.
|
||||
- **Single-use and duplicate resolution.**
|
||||
`POST /api/sessions/:id/structured/approvals/:nonce` **always answers
|
||||
`204`** for a known, live structured session — whether the nonce is the
|
||||
|
||||
Reference in New Issue
Block a user