From cdd4213ff5bbefc2df2f3fdee0d9c107ccb557b0 Mon Sep 17 00:00:00 2001 From: Miguel Palhas Date: Sat, 5 Sep 2026 03:38:32 +0100 Subject: [PATCH] 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 --- docs/STRUCTURED-VIEW.md | 30 +++++++++++++++++++----------- 1 file changed, 19 insertions(+), 11 deletions(-) diff --git a/docs/STRUCTURED-VIEW.md b/docs/STRUCTURED-VIEW.md index eed8abd..ce1a777 100644 --- a/docs/STRUCTURED-VIEW.md +++ b/docs/STRUCTURED-VIEW.md @@ -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=` returns the first - page after `n` (`since=0` is the whole log); `?before=` 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=` 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