Task notifications repeated identifiers and omitted useful activity details. Use task titles, actor and comment previews, and concrete field changes. Share bounded secret redaction per event after viewer access checks. Suppress updates without useful details. Verified with focused regression tests, package typechecks and server build, and the full green CI run. Greptile scored the final head 5/5 with no unresolved review threads. Co-Authored-By: Paperclip <noreply@paperclip.ing>
7.0 KiB
Toast semantics
Toasts are transient feedback, not a company activity feed. Live task notifications
are personal to the connected human, including in multiplayer and local_trusted
mode (local-board). Access to a task does not subscribe someone to notifications.
Which tasks qualify
A task qualifies when the viewer creates an ordinary human task, is its current
human assignee, comments directly in Paperclip, receives an open addressed request,
or performs a deliberate action included in the existing
Mine participation allowlist in
issue-participation.ts.
Read receipts, denied requests, and automatic read-time recovery cleanup do not
count. Automatic creator attribution, synchronized comments, and manual routine
runs also do not count. Comment source checks apply to historical imports.
A task also qualifies when its current description or a non-deleted comment
contains an explicit mention of the viewer: [Name](user://USER_ID). The shared
user-mention parser resolves the exact user ID; plain names and bare URLs do not
count. Existing comments are checked, so users need not have opened the task.
The event introducing the first mention can notify immediately. Removing the
only mention removes that qualification unless another participation rule holds.
Historical comment lookup uses an exact viewer-link regex backed by the existing
comment-body trigram index and returns at most one body for the shared parser.
Agent ownership, primary-agent preference, task/run responsibleUserId, company
membership, and involvement in a parent task do not qualify on their own.
Activity by any person or agent can notify a qualifying viewer. These rules do
not change Mine membership, task permissions, assignment, or inbox archive state.
Events and suppression
| Event | Toast behavior |
|---|---|
| Task created, updated, or commented on | Requires personal task eligibility. The viewer's own activity stays quiet. |
| Run failed, timed out, or cancelled | Requires eligibility for the persisted run's task. An event's task hint or agent identity is not sufficient. |
| Agent error without a task, or run without a task | No live toast. Status remains available in company views. |
| Run started or succeeded | No live toast. |
| Save, Copy, and other direct action feedback | Existing caller-owned feedback is unchanged. |
| Company join request | Existing join-request notification behavior is unchanged. |
Eligibility is an additional gate, not a promise that every event produces a toast. Existing rules still suppress activity for the task in view and run outcomes already represented by the visible task/run tree. Comment-driven updates can be combined with their paired comment event when that metadata is available. Intentional operator interruptions and workspace contention do not announce run failures. Duplicate terminal outcomes and failures older than five minutes (when timestamps are available) remain quiet. Reconnect suppression, per-category rate limits, content deduplication, and toast lifetime limits remain in effect. Hidden pages reconcile their data on return without replaying a notification backlog. Archiving a task is not a notification unsubscribe.
Delivery contract
The company WebSocket authorizes each event before evaluating relevance. Its
viewer-specific copy of the shared LiveEvent envelope contains toastEligible.
Only true permits a live task/run toast. Missing/false values, unresolved viewer
identity, and relevance lookup failures stay quiet. Agent-authenticated sockets
do not receive human toast eligibility. This field is computed per connection,
never persisted or published on the shared company event bus.
Authorized events still reach cache handling and component subscribers when eligibility is false. Lookup failure is logged but does not discard the authorized event. Existing task/run privacy checks and payload redaction remain in force. Task activity notifications use the task title as their heading. The body names the actor and previews the comment or describes the change, including the old and new status when available. Markdown in comment previews becomes plain text. Updates without a meaningful change stay quiet. Comment-driven updates produce one notification with the comment and its changes. Creation notifications name the creator. The title is limited to 120 characters and the body to 240.
After task-read authorization, the server adds the persisted task title and a
closed notificationDetails projection of the already-redacted activity. This
projection allows bounded comment IDs/previews, known status/priority values,
assignment/change flags, and comment/reopen context. It does not copy arbitrary
activity details, task descriptions, or raw change receipts. The title uses the
existing company-scoped identifier lookup. Comment previews read the complete
non-deleted comment by company, task, and comment ID. Task-registered secrets are
redacted from the complete title/comment before the preview is shortened, using
the same task redaction registry as HTTP reads. Titles and comment previews both apply the existing
pattern-based credential and configured username redaction, including creation
and update events without a comment. The notification
path uses the existing task-context indexes in two ordered reads, each limited to
129 rows. It accepts at most 128 distinct runs, 64 unique secrets and 64 KiB of
unique encrypted material, with a 16 KiB registry limit per run. Exceeding a limit
omits free text; the browser can use a previously loaded task title. HTTP history
reads retain their existing redaction behavior.
Authorized viewers share one identity/redaction promise for the same published
event. Each viewer still passes its own access check before reading that result.
The shared result contains redacted text and expires with the event object. Each
new event reads fresh redaction data; no plaintext secret values are cached.
Registry reads select only secret metadata, not full run contexts. Missing comments
and read/redaction failures omit the preview; they never reuse the event snippet.
If the optional task-identity lookup fails, the event still arrives. The browser uses a cached
title or Task; task identifiers remain in navigation links. Permission-check
failures do not use this fallback. Older servers can supply cached titles and
legacy activity details, but unspecified updates remain quiet.
When an authenticated comment event omits the comment ID, the visible task thread
refreshes through its authorized HTTP read instead of trying to hydrate the comment.
Closed sockets cannot deliver stale notifications after account/company changes.
No client-side task-list cache or new database migration is required. During a
mixed-version rollout, a new client receiving events from an older server stays
quiet until the server provides eligibility.
Verification
See inbox-search/toasts for the
two-user browser recipe and linked regression suites. The map describes coverage;
it is not evidence that a particular deployment passed that journey.