Repository navigation
docs(rfc): propose snoozing a session until a chosen time - #23906
Pearcekieser wants to merge 1 commit into
Conversation
UX Review (Opus 5.5, fork) — ⏭️ skippedRevision |
First Principles Review (Opus 5.5, fork) — ⏭️ skippedRevision |
Design Review (Opus 5.5, fork) — ✅ PASSDesign-level review of Design-Verdict: PASS Docs-only RFC; the code anchors it cites exist on base and nothing is taken away. Notes
[DESIGN-REVIEWED] 5eb261f Description read[DESCRIPTION-READ] cae78836dcc63fef75906d1c3793f8b5166e337e4c594dd7961f050ad362769b That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
GPT 6.1 Review (fork) — ✅ no blocking findingsReviewed Review detailsNo findings. |
Opus 5.5 Review (fork) — ✅ no blocking findingsReviewed |
|
Replies to the Design Review notes on 216557c. note (non-blocking): per-browser wake acknowledgement Intended for this version. Each browser keeps its own unread state today: note (non-blocking): what an older gateway does with the keys Agreed, "ignore" undersells it. An older gateway reads the line without the keys, and its next save of that session writes the line without them. So after a downgrade the snooze is gone, not just its pending wake, and the session shows as a normal row. That is still safe: snooze never hides a session from an older gateway, and no transcript or other field is touched. I'll state this plainly in §7 in the same acceptance edit. |
|
HOLD at 216557c: the branch conflicts with main in The RFC is docs only and draft, all lanes pass, and your replies to both Design notes are sound. What would clear this:
A rebase is a new head and needs another review. — crew-pr-reviewer (r125) |
216557c to
13a4d00
Compare
|
Rebased on main, no behaviour change to the design. The new head is 13a4d00. It answers the r125 hold as follows.
|
|
Reply to the Design Review note on 13a4d00. note (non-blocking): a closed session that comes due is woken only if it is reopened Agreed, and that is the intended behaviour. The sweep reads the live slots only. A closed session has no row in the sidebar, so waking it would have nowhere to put it back, and a notification for a session the person closed would bring back something they deliberately set aside. It keeps its due time in the metadata line: reopened before that time, it comes back snoozed, and reopened after, the next sweep wakes it with no extra note. I'll add this to §4 Non-goals in the acceptance edit, so this head stays as reviewed and the backend PR doesn't read it as a gap. |
|
The two reds on 13a4d00 are one unrelated test, so I'll push one same-tree retrigger with no content change.
|
13a4d00 to
bde5be5
Compare
9b24fb3 to
67d2663
Compare
|
Replies to the Opus 5.5 review on 9b24fb3. Both are fixed in 67d2663. issue (blocking): stray fourth cell on the Fixed. The nitpick (non-blocking): §2 places Fixed. §2 now says |
|
Replies to the Design Review notes on 67d2663. note (non-blocking): whether the codec keeps unknown keys on a downgrade It keeps them, and §7 had this wrong. A slot save passes every metadata key it doesn't own through unchanged ( note (non-blocking): a session closed while snoozed wakes with no notification Intended, as answered earlier. I'll write it into §5.5's "Closed while snoozed" row and §4 Non-goals in the same push. |
|
Rebased on main at 18d6b4e. This head also carries the corrections promised in the 02:23Z reply: §7 now says an older gateway keeps the snooze keys (a slot save passes unowned keys through
note (non-blocking): reply to the Design Review note on where "needs the person" comes from Agreed. The exemption predicate is |
|
|
|
Rebased on main at 3073e60, no behaviour change. Newer RFC rows landed in the same README audit paragraph; main's text is kept and the snooze row and log sentence are added back once. The new head is fa50890, and |
|
Replies to the Design Review notes on fbc0760. note (non-blocking): the "verified at Agreed. When the design is accepted, the acceptance edit will re-read every symbol §2 cites against the base it lands on and move suggestion (non-blocking): a cutoff for a browser that has no acknowledgement record Adopted as you proposed. A browser with no record stores the time of its first load and ignores any |
|
HOLD at fbc0760 (maintainer decision pending). The draft is docs only, every lane passes, and the README change now adds just the snooze row and one audit sentence. Items 1 and 2 of our r125 hold are done. What would clear this:
The stale — crew-pr-reviewer (r145) |
|
Reply to the r145 hold on fbc0760. The new head is 3744338, rebased on main at 89dd26a with no other change.
note (non-blocking): reply to the Design Review note on who owns the wake acknowledgement §5.4 already states it once: the gateway owns |
bolichen97
left a comment
There was a problem hiding this comment.
Design brief (the sign-off is the maintainer's, so this is a comment, not an approval)
What it does: lets a person snooze a session until a chosen time, from all three session menus. The gateway stores snoozed_until in the slot metadata line, and a 15-second sweep wakes due sessions, including ones that came due while the gateway was down. A woken session reads as unread and fresh, and raises one dashboard notification. Snoozed rows move to a collapsed, grayed "N snoozed" zone, and a row with a pending approval or question stays visible.
Pros
- The gateway owns the due time, so a wake survives a restart and needs no open browser (the lesson from #12601).
- It is an attribute like Pin and Mute, not a new lifecycle state, which fits #18235.
- It reuses the mute route's contract (user-only, persist before publish,
slot_patch), so agents and apps cannot hide a session from its person. - It is additive: an older gateway ignores the keys and keeps them on save (
carry_unowned_metadata).
Cons / open points
- A new always-on 15-second sweep over live slots. It's cheap, but it is one more periodic loop. Could it ride an existing tick?
- Wake acknowledgement is kept per browser in localStorage, so two devices each mark the session unread once. The RFC calls this intended, and it matches how unread works today.
- A session closed while snoozed wakes silently on a late reopen with no notification. That's acceptable, but worth stating in the UI copy.
Tech debt: low. Two optional metadata fields, one route, one sweep loop. The client logic (zone split, ack cutoff) sits beside the existing dormant collapse.
Our pick: accept as written. If possible, fold the sweep into an existing periodic task rather than adding a new one.
|
Thanks for the brief, @bolichen97. Replies to the open points, then one question. suggestion (non-blocking): fold the sweep into an existing periodic task Adopted. The wake check now rides the gateway's existing 5-second dirty-slot flush tick ( note (non-blocking): two devices each mark a woken session unread once Agreed, kept as designed. §5.4 also has the first-load cutoff, so a new device or cleared storage doesn't mark every past wake unread. suggestion (non-blocking): say in the UI copy that a closed session wakes without a notification Adopted. A snoozed session's menu will show "Closing it skips the wake reminder." under its due time. §5.4 says this in the next push, and the sidebar PR carries the line. question: is your brief the acceptance? It ends "accept as written", but it also says the sign-off is the maintainer's, so I haven't recorded it. If you're accepting, say so here and I'll record your name and today's date in §11, flip the status to |
|
Rebased on main at ec2e1a1 (another RFC row in the README audit paragraph). This head also carries the changes promised in the 02:34Z reply: §5.3 and §10 now put the wake check on the existing 5-second dirty-slot flush tick, so snooze adds no periodic task of its own, and §5.4 adds the menu note that a session closed while snoozed wakes without a reminder. The new head is 855253c, and |
bolichen97
left a comment
There was a problem hiding this comment.
Thanks, re-read at 855253c. Both points from my design brief are addressed:
- The wake check now rides the existing 5-second dirty-slot flush tick (
_flush_loop) instead of a new 15-second loop. It is guarded so a failed wake never stops the flush, and it stops with the flush at shutdown. Open question 1 is marked resolved. - The Unsnooze menu now notes that a session closed while snoozed wakes without a reminder.
Nothing else changed. Our pick stays "accept as written". The sign-off is the maintainer's, so this remains a comment.
|
Maintainer direction signed: snooze riding the existing flush tick, and the Unsnooze note for sessions closed while snoozed. |
bolichen97
left a comment
There was a problem hiding this comment.
Re-read at 26d2018. The acceptance is recorded correctly: the status is accepted in the front matter, the summary line and the README row, §11 names the signer and the date and links the brief, re-read and sign-off, and doc-pr is set. The other edits are clarifications that fit the signed direction:
- the wake saves before it notifies, so a stop in between loses only the bell entry, never the unread mark;
- a session reopened after its due time raises its notification at the reopen;
- the Unsnooze note now reads "closing it skips the reminder at the due time".
No further comments. This stays a comment, since the RFC needs no approval from us.
|
HOLD at c39e016: merge conflict. The RFC itself is ready. Both items from our r145 hold are done: §5.4 now has the first-load cutoff, and bolichen97 signed the maintainer direction and re-read the acceptance edit at 26d2018. What blocks: GitHub reports the branch as conflicting with main. The only conflicting file is docs/request-for-change/README.md, where main has added more RFC rows and audit sentences since 19e0776. What would clear it: rebase on main and keep main's new rows alongside the snooze row. A new push needs another review. — crew-pr-reviewer (r146) |
Security Scope Review (fork) — 🔴 BLOCK (blocking)Which legitimate operations does no leg reported, and this was not the nothing-to-adjudicate short circuit No |
|
resolution: removed the per-tab manual reminder, so the wake mark and the browser's wake record now live in the same shared scope
|
bolichen97
left a comment
There was a problem hiding this comment.
Re-read at 39a4955. This is a comment, not an approval. One part changed since our brief at 26d2018: how a woken session shows as unread.
- Before: each browser marked the wake as a manual reminder, which lives only in one tab's sessionStorage.
- Now: every open window marks the wake the way a message arrival does, through the shared unread record (
mc-unread-shared). That includes a tab whose socket was down at the wake, once it reconnects. A tab opened later and a reload both show it, and a read in any window clears it in the others through the read relay. A window that has the session in focus records the wake and relays a read instead of marking it. Each browser records the wakes it has handled, so a reload does not mark one again. A muted session is still marked, because the person asked for this reminder.
This is a fix inside the same direction. The gateway still stores no unread state, so it adds no new server state and no new route, and it reuses the read relay that message arrivals already use. The direction we briefed is unchanged.
|
This changes behaviour users already rely on, so it needs a design sign-off from a maintainer before it can merge. A maintainer will post the decision here. To propose a design, follow the request-for-change process in CONTRIBUTING.md (docs/request-for-change/). Review result on this head: no blocking findings. The diff changes only docs: the new RFC and one row plus one sentence in the README, with no README text removed. PR Readiness passes on this head. We checked the code symbols the RFC cites against main: Optional notes, not requirements:
|
|
note (non-blocking): the three optional notes are in a5304f2 In reply to the review comment. Section 5.1 now says that |
bolichen97
left a comment
There was a problem hiding this comment.
Re-read at fdd005d (RFC: comment only, the sign-off is a maintainer's). Since 39a4955 the direction is unchanged. The changes are three fixes inside it:
snoozed_untiland its partner key joinSLOT_OWNED_META_KEYSinhistory_schema.py, asmuteddoes. Without that,carry_unowned_metadatawould put a cleared snooze back on the next save. This closes a real persistence gap.- The muted row drops "Mute silences message arrivals only." That follows from the §5.4 change, where a woken session is now marked unread like a message arrival.
- The tests section adds four cases: no notification while the save keeps failing, exactly one on the first save that succeeds, a wake-path error that does not stop the flush loop, and a woken or unsnoozed slot that reloads unsnoozed with no second notification.
The new note on §5.4 records my earlier re-read accurately. Nothing here needs a fresh decision. CI is green.
Code change approver recommendation: A person should decideWhy: the decider estimates a 7% chance that this change introduces a defect, within the 12% limit for approving on its own, but it is held at tier 2: design-doc-gate: D. This PR changes only documentation. It adds an accepted RFC for snoozing a session until a chosen time, plus one README index row and one audit-log sentence. I checked the code the RFC relies on against the repo at the PR's head:
The design holds together:
Tier: 2, held for a person: design-doc-gate: D. An automated recommendation, not a review: a maintainer still decides. It approves on its own only when the estimated chance of a defect is at most 12% and the change has at most 400 changed lines. Decider v3c (217fe607) · commit |
Adds rfc-session-snooze as a draft for a maintainer to accept, with its README index row and audit sentence. It records the user-only snooze route, the persisted due time, the gateway sweep that wakes sessions after a restart, and the snoozed sidebar zone that issue kirodotdev#21448 asks for.
Problem / Motivation
Goal: Record on main the accepted design for snoozing a session until a chosen time, so the implementation for #21448 has a recorded decision to land against.
#21448 asks for a way to set a session aside and have it come back at a chosen time, marked unread and fresh. It is parked, and its triage comment asks for a design through the request-for-change process. Snoozing adds a per-session state that the sidebar hides rows by, and a gateway-side wake, so the decision belongs on the base branch before the code.
Why it matters
Today a session you are not ready for either stays in the sidebar as noise or drops behind the dormant collapse, which never brings it back. bolichen97 accepted the snooze design on 2026-11-05, including where it sits against Dormant, Older and Pin (#18235), after two changes from the design brief. The First Principles lane reads that decision from the base branch, so this docs-only diff lands before the code.
Not a goal
What changed (motivation → approach → change)
The design gets its own document so its acceptance is recorded on its own.
docs/request-for-change/rfc-session-snooze.md,status: accepted. It specifies a user-onlyPATCH /api/chat/slots/{slot}/snoozethat persistssnoozed_untilin the slot metadata line, following the mute route's fences and persist-before-publish order. The wake check runs on the existing 5-second dirty-slot flush tick (_flush_loop), so snooze adds no periodic task of its own. It wakes due sessions, including ones that came due while the gateway was down, recordssnooze_woke_atand raises one dashboard notification. The browser draws snoozed rows grayed in a collapsed zone below each container's dormant zone, marks a woken session unread, and treats the wake as fresh activity. The Unsnooze menu notes that a session closed while snoozed skips the wake reminder. Section 5.5 covers running turns, queued messages, pin, mute, dormant, closing and the focused session. Snooze never closes, deletes or rebinds a session.docs/request-for-change/README.mdgets anacceptedrow and one audit-log sentence, both verified ate84971588e.The fork cannot arm auto-merge, so this needs a maintainer to merge it. #21448 also still needs
triagedbefore the implementation PRs can pass the Issue Gate.Backwards compatibility
Compatible: documentation only; no code, config or contract changes.
Removes nothing: the diff adds one RFC file, one README row and one log sentence.
Tests
python3 scripts/docs_lint.pypasses. No code changed, so no code tests apply.Manual verification
Checked each claim in §2 against
e84971588e:SessionActionsMenu.tsxis the one item list behind the three menus,api_chat_slot_mutedinchat_folders.py(through_toggle_slot_user_flag) is the persist-then-publish template,splitStaleSlotsreadsslotActivityTs, andmarkSlotUnreadtakes a string payload for a manual reminder.Screenshots / video
None; docs only.
Related Issues
Refs #21448. Related: #18235, #12601.
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)Contribution License Agreement
Contributions are accepted under the project's Apache-2.0 license; see the Licensing section of CONTRIBUTING.md.