Skip to content

docs(rfc): propose snoozing a session until a chosen time - #23906

Open
Pearcekieser wants to merge 1 commit into
kirodotdev:mainfrom
Pearcekieser:feat/session-snooze
Open

Pearcekieser wants to merge 1 commit into
kirodotdev:mainfrom
Pearcekieser:feat/session-snooze

Conversation

@Pearcekieser

@Pearcekieser Pearcekieser commented Oct 25, 2026 •

Copy link
Copy Markdown
Contributor

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

  • Any code change. The backend and the sidebar changes follow in two later PRs that link this document.
  • Changing Dormant, Older sessions, folders or closing.
  • Slack, phone or email delivery of the wake.

What changed (motivation → approach → change)

The design gets its own document so its acceptance is recorded on its own.

  • New docs/request-for-change/rfc-session-snooze.md, status: accepted. It specifies a user-only PATCH /api/chat/slots/{slot}/snooze that persists snoozed_until in 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, records snooze_woke_at and 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.
  • Section 11 records the acceptance with links to the design brief, the re-read and the signed-direction comment.
  • docs/request-for-change/README.md gets an accepted row and one audit-log sentence, both verified at e84971588e.

The fork cannot arm auto-merge, so this needs a maintainer to merge it. #21448 also still needs triaged before 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.py passes. No code changed, so no code tests apply.

Manual verification

Checked each claim in §2 against e84971588e: SessionActionsMenu.tsx is the one item list behind the three menus, api_chat_slot_muted in chat_folders.py (through _toggle_slot_user_flag) is the persist-then-publish template, splitStaleSlots reads slotActivityTs, and markSlotUnread takes a string payload for a manual reminder.

Screenshots / video

None; docs only.

Related Issues

Refs #21448. Related: #18235, #12601.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

Contributions are accepted under the project's Apache-2.0 license; see the Licensing section of CONTRIBUTING.md.

@Pearcekieser
Pearcekieser requested review from a team and KiroCrewCaptain as code owners October 25, 2026 03:42
@github-actions github-actions Bot added the fork Pull request from a fork (external contributor) label Oct 25, 2026
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 25, 2026
@github-actions

github-actions Bot commented Oct 25, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5, fork) — ⏭️ skipped

Revision 5eb261f9c108b9499f6ae427aa2f5f232b9b6c04 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

github-actions Bot commented Oct 25, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5, fork) — ⏭️ skipped

Revision 5eb261f9c108b9499f6ae427aa2f5f232b9b6c04 ships no reviewable capability (docs, tests or generated files only), so there is nothing to inventory. Does not block merge.

@github-actions

github-actions Bot commented Oct 25, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5, fork) — ✅ PASS

Design-level review of 5eb261f9c108b9499f6ae427aa2f5f232b9b6c04 via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Docs-only RFC; the code anchors it cites exist on base and nothing is taken away.

Notes

  • Base has two _flush_loop definitions: dashboard/dashboard_persistence.py:99 and dashboard/state_parts/dashboard_services.py:775. §5.3 should say which tick runs the wake check, so the backend PR doesn't hook into the wrong one.

[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 .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 25, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review (fork) — ✅ no blocking findings

Reviewed 5eb261f9c108b9499f6ae427aa2f5f232b9b6c04 via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 5eb261f

@github-actions

github-actions Bot commented Oct 25, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review (fork) — ✅ no blocking findings

Reviewed 5eb261f9c108b9499f6ae427aa2f5f232b9b6c04 via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 5eb261f

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

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: markSlotUnread with a string payload records a manual reminder that only a local read clears, and the gateway stores no unread state. A woken session is a reminder the person asked for, so lighting it once in every browser they use matches how unread already works. Moving the acknowledgement to the gateway would mean adding server-side unread state that nothing else in the dashboard has. I'll write this into §5.4 in the same edit that records acceptance in §11, so this head stays as reviewed.

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.

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: checking Automated validation is still running labels Oct 25, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor

HOLD at 216557c: the branch conflicts with main in docs/request-for-change/README.md, where newer RFC rows have landed in the audit-log paragraph and the index table.

The RFC is docs only and draft, all lanes pass, and your replies to both Design notes are sound.

What would clear this:

  1. Rebase onto main and re-add the rfc-session-snooze row and log sentence.
  2. Write the two promised clarifications into §5.4 (each browser acknowledges a wake separately) and §7 (an older gateway drops the keys on its next save), or say you will do it in the acceptance edit before merge.
  3. A maintainer accepts or reshapes the design, or agrees to merge it as a draft.

A rebase is a new head and needs another review.

— crew-pr-reviewer (r125)

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

Rebased on main, no behaviour change to the design. The new head is 13a4d00. It answers the r125 hold as follows.

  1. Done. The branch is rebased on 27cb0849ed. Main's newer README rows and audit sentences are kept, and the rfc-session-snooze row and log sentence are added back. python3 scripts/docs_lint.py passes.
  2. Done in this head, not deferred to the acceptance edit. §5.4 now says each browser keeps its own wake acknowledgement, so a second browser marks the session unread once more, and that this is intended because unread state already lives in each browser. §7 now says an older gateway's next save drops the snooze keys, which loses the snooze itself, and that nothing else about the session is lost.
  3. Open. @bolichen97, could you accept or reshape the design, or merge it as a draft? If you accept here, I'll record your name and the date in §11 and flip the status before merge. Adding triaged to Snooze threads with a reminder that reappears as a notification, marks the chat unread, and resets its age #21448 at the same time would let the implementation PRs pass the Issue Gate.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: passed Eligible automated validation passed for the current revision merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Oct 25, 2026
@Pearcekieser

Copy link
Copy Markdown
Contributor Author

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.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 25, 2026
@Pearcekieser

Copy link
Copy Markdown
Contributor Author

The two reds on 13a4d00 are one unrelated test, so I'll push one same-tree retrigger with no content change.

Backend Tests (3.12, 7) ran 24,235 tests with 1 failure: test/test_side_readonly_spec_reap.py::test_an_unreadable_or_protected_checkout_keeps_its_variant. It failed with ExceptionGroup: multiple unraisable exception warnings: a RecursionError inside pytest's unraisable hook while it formatted a PosixPath ('PosixPath' object has no attribute '_str'), not an assertion. Coverage Gate fails because that shard failed. This PR changes only docs/request-for-change/README.md and the new RFC file, and nothing under src/ or test/.

@github-actions github-actions Bot removed the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Oct 30, 2026
@Pearcekieser

Copy link
Copy Markdown
Contributor Author

Replies to the Opus 5.5 review on 9b24fb3. Both are fixed in 67d2663.

issue (blocking): stray fourth cell on the rfc-agent-temp-reclaim row

Fixed. The rfc-agent-temp-reclaim row is back to main's text, and the snooze audit sentence now appears once, at the end of the audit paragraph. The cause was my rebase helper. When a conflict hunk started at the top of the table, it appended the sentence to the first line of main's side, which was that row. It has done this since the 10-29 17:48Z rebase. I misread that 5-line README diff as a row being reordered. The helper now strips the sentence from every table row, appends it only to the line directly above the table header, and refuses to finish unless the sentence appears exactly once. Every | [rfc-... row in the index now has three cells.

nitpick (non-blocking): §2 places splitStaleSlots in stale.ts

Fixed. §2 now says splitStaleSlots is in pages/staleCollapse.ts and useStaleCollapse in pages/chat-sidebar/stale.ts drives it.

@Pearcekieser

Pearcekieser commented Oct 30, 2026 •

Copy link
Copy Markdown
Contributor Author

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 (carry_unowned_metadata in src/kiro_crew/history_schema.py, used by build_full_line since v0.10.0). So an older gateway shows a snoozed session as a normal row and never wakes it, but its saves keep snoozed_until and snooze_woke_at. After an upgrade back, the sweep wakes any snooze that came due during the downgrade, late but once. I'll correct §7 to say this in the next push, and the backend PR will state it too. An earlier version of this reply said the opposite; I checked the code after posting it.

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.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

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 carry_unowned_metadata), and §4 and §5.5 now say a session closed while snoozed gets no wake while it stays closed. python3 scripts/docs_lint.py passes.

Opus 5.5 Review on 82775e0 reports "review incomplete": the job ended without a verdict, and its comment still shows the previous head. That's the pipeline, not a finding. A maintainer re-run of that job would give a verdict.

note (non-blocking): reply to the Design Review note on where "needs the person" comes from

Agreed. The exemption predicate is isStaleExempt in pages/chat-sidebar/stale.ts (staleCollapse.ts only takes it as a parameter). The sidebar PR will build its "stays in the list" check from the same pending_approval and needs_input fields that predicate reads, and not define the rule a second time.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

Security Scope Review on 82775e0 is also a job that never ran, not a finding: "the review scope was never resolved: the generate job did not finish (it timed out, failed or was cancelled), so no leg ran". With the incomplete Opus 5.5 Review, these are the two reds on this head, and both need a maintainer re-run. All other checks pass, and the PR changes only docs/request-for-change/README.md and the RFC file. I'm not pushing for these.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

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 python3 scripts/docs_lint.py passes. This push also re-runs the Opus 5.5 Review and Security Scope Review jobs, which never produced a verdict on 82775e0.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

Rebased on main at 6f13ecb, no behaviour change. Another RFC row 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 fbc0760, and python3 scripts/docs_lint.py passes.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

Replies to the Design Review notes on fbc0760.

note (non-blocking): the "verified at 0dab198632" line is ten days old

Agreed. When the design is accepted, the acceptance edit will re-read every symbol §2 cites against the base it lands on and move audited-at, last-audited and the README row's "Verified at" to that commit. If the next push is a conflict rebase instead, it will carry the same refresh.

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 snooze_woke_at older than that, so a new device or cleared storage no longer marks every past wake unread. The sidebar branch implements it (SNOOZE_WAKES_SINCE_LS_KEY in useSnoozeWakeAck.ts) with a test for the first-load case. §5.4 gets the same sentence in the next push.

@iamwhatever

Copy link
Copy Markdown
Contributor

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:

  1. The first-load cutoff you adopted on the Design note (a browser with no acknowledgement record ignores any snooze_woke_at older than its first load) is not yet in §5.4. As written, a new browser or cleared storage would mark every past wake unread. Please add that sentence.
  2. A maintainer accepts or reshapes the design (and the two open questions in §10), or agrees to merge it as a draft. §11 still says not yet accepted, and no maintainer has replied here.

The stale 0dab198632 audit line is fine to refresh in the acceptance edit, as you proposed. A new push needs another review.

— crew-pr-reviewer (r145)

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

Reply to the r145 hold on fbc0760. The new head is 3744338, rebased on main at 89dd26a with no other change.

  1. Done. §5.4 now says a browser with no acknowledgement record stores the time it first loads and ignores any snooze_woke_at older than that, so a new device or cleared storage no longer marks every past wake unread. The sidebar implementation already does this (SNOOZE_WAKES_SINCE_LS_KEY in useSnoozeWakeAck.ts, with a first-load test). python3 scripts/docs_lint.py passes, and the README still adds only the snooze row and one audit sentence.
  2. Open. @iamwhatever, since this hold is on a maintainer decision: could you accept or reshape the design, including the two open questions in §10, or merge it as a draft? If you accept here, I'll record your name and the date in §11, flip the status and refresh the 0dab198632 audit line in one push.

note (non-blocking): reply to the Design Review note on who owns the wake acknowledgement

§5.4 already states it once: the gateway owns snooze_woke_at, the instant a snooze ended, and each browser owns its acknowledgement of that instant, because unread state lives only in the browser. The sidebar PR follows that split, with the acknowledgement in useSnoozeWakeAck.ts and no gateway route for it.

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

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 (_flush_loop in dashboard/dashboard_persistence.py), after that tick's flush, and a failed wake is logged without stopping the flush. Snooze then adds no periodic loop of its own, stops with the flush at shutdown, and wakes within about 5 seconds of the due time. §5.3 and §10 question 1 in the next push say this, and the backend branch is being changed to match before its PR opens.

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 accepted, and refresh the 0dab198632 audit line in the same push. If the sign-off should come from someone else, I'll wait for them.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

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 python3 scripts/docs_lint.py passes.

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@bolichen97

Copy link
Copy Markdown
Contributor

Maintainer direction signed: snooze riding the existing flush tick, and the Unsnooze note for sessions closed while snoozed.

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in docs/request-for-change/ since this head went green (e849715 -> 19e0776); CI re-running.

@iamwhatever

Copy link
Copy Markdown
Contributor

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. rfc-session-snooze.md has not changed since that re-read, and every check on this head is green.

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)

@github-actions

github-actions Bot commented Nov 5, 2026

Copy link
Copy Markdown
Contributor

Security Scope Review (fork) — 🔴 BLOCK (blocking)

Which legitimate operations does 142431df708d5c4037dcf6f2250e034888c6ffee newly refuse? Model proposes, scripts/deny_diff.py decides — updated in place on each push. A script-confirmed regression blocks PR readiness.

no leg reported, and this was not the nothing-to-adjudicate short circuit

No [SCOPE-REVIEWED] marker for this head was produced, so the model's text is withheld: it cannot be shown to describe this revision. See the job logs.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

resolution: removed the per-tab manual reminder, so the wake mark and the browser's wake record now live in the same shared scope
mechanism: a wake is marked like a message arrival, in the shared unread record

  • A woken session can lose its unread badge in every other tab of the same browser (span=2bcfd4c5cd6a)

fixed in 39a4955: section 5.4 now marks a wake with the object form markSlotUnread({ slot }) in every open window, the way a message arrival is marked, so the mark goes into mc-unread-shared. A tab opened later restores it, and a read in any window clears it through the read relay. Each window marks a wake it sees from its own data, from a slot_patch or from the slot list it fetches after a reconnect. The localStorage record now only stops a later load from marking the same wake again. A window with the session in focus records the wake and relays a read. Section 2 describes both markSlotUnread forms, and the section 6 exit criteria test the second tab, the late tab and the reconnecting tab.

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@KiroCrewCaptain

Copy link
Copy Markdown
Collaborator

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: _toggle_slot_user_flag, carry_unowned_metadata, _SLOT_PATCH_FIELDS, MAX_LIVE_SLOTS, _FLUSH_INTERVAL, state.notify, markSlotUnread, mc-unread-shared and the read relay. Each exists where the RFC says. The _flush_loop in dashboard_services.py only delegates, so §5.3 names the one real loop. One thing done well: the gateway owns the due time and the wake instant, and the browser owns unread state. §5.3 also explains why the save comes before the notification by comparing what goes wrong in each order.

Optional notes, not requirements:

  • §5.1 (line 114): say that snoozed_until and snooze_woke_at join history_schema.SLOT_OWNED_META_KEYS, as muted does. Without that, carry_unowned_metadata puts a cleared snooze back on the next save. The session then wakes again after a restart, and an early unsnooze is undone. A matching §6 exit criterion would help: a woken or unsnoozed slot, saved and reloaded, comes back unsnoozed and raises no second notification.
  • §6 backend exit criteria (line 218): add the two ordering rules §5.3 calls deliberate. First, when the save fails, no notification is raised on this tick or on later ones. Second, an error in the wake path does not stop the flush loop.
  • §11 (line 287): link the re-read at 39a4955 that covers the §5.4 unread change, so the current design traces to an acceptance. Fold this into the next push you need anyway, such as a README conflict rebase.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

note (non-blocking): the three optional notes are in a5304f2

In reply to the review comment. Section 5.1 now says that snoozed_until and snooze_woke_at join SLOT_OWNED_META_KEYS, as muted does, so carry_unowned_metadata cannot put a cleared snooze back. The section 6 backend exit criteria now add three rules. No tick raises a notification while the save keeps failing. An error in the wake path does not stop the flush loop. A woken or unsnoozed slot comes back unsnoozed after a save and reload, with no second notification. Section 11 links the maintainer's re-read at 39a4955. This head also removes one sentence from the Muted row that understated what mute does.

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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_until and its partner key join SLOT_OWNED_META_KEYS in history_schema.py, as muted does. Without that, carry_unowned_metadata would 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.

@KiroCrewCaptain

KiroCrewCaptain commented Nov 11, 2026 •

Copy link
Copy Markdown
Collaborator

Code change approver recommendation: A person should decide

Why: 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:

  • _flush_loop exists in dashboard_persistence.py and runs a 5-second tick.
  • api_chat_slot_muted and _toggle_slot_user_flag apply the ownership and app fences, refuse unattributable callers and accept only dashboard users, not internal-auth callers. So the trust claim that the new route "inherits the mute route's fences" points at a real, sound template.
  • carry_unowned_metadata and SLOT_OWNED_META_KEYS (which includes muted) exist, so the RFC is right that a cleared snooze needs its keys in the owned set.
  • _SLOT_PATCH_FIELDS and MAX_LIVE_SLOTS = 500 exist.
  • In markSlotUnread, the object payload writes to the shared mc-unread-shared record and the string payload is a relay-immune manual sentinel, as the RFC says.

The design holds together:

  • It saves before it notifies, which avoids repeated bell entries.
  • It handles due times that passed while the gateway was down.
  • It covers the downgrade path, because older saves keep unknown

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 09985a3423 · 306 changed lines. If this recommendation is wrong, reply here: replies are how the approver is evaluated.

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.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor) readiness: passed Eligible automated validation passed for the current revision

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants