support_desk 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8d7e90a546ededcbf2f0f13d30a2929655e0d6bb343f11d114b0e539b8985bfb
-  data.tar.gz: 502d37cedab338e5f42db97b021ed01dd8ee46844600fc31d3240e9a1a09597c
+  metadata.gz: afefc82399ac7abf6a331cc44fceb5fd160694fea8c83025af5e5888399a18d2
+  data.tar.gz: c209e7f207e89de6e4e0b48ecdd8b2dfd4e7011b352cf2eaf52c82dd9b13260f
 SHA512:
-  metadata.gz: fae5879d3023eed0f45c24e275bf63fdaf5ac2f8e982a7d6b9ea6c9db4afe12036025c6ef20a1280031456978908414849719fb9ea28a6d53d5dd47a3c6995aa
-  data.tar.gz: 9e8e5df4a7e7f836c297a3509d4c2d23111a6f9365fdd34208e410db11e249aa0445c515fe19421efa4f883b43503cf65bc32efc207007ff46a55d9102b8a470
+  metadata.gz: 773a60b0710143ef412597a9789b2c37e5a41d99cbb965e5908d6035c11dcd5d97b0353c4f0777e5fd1e7644414ad01afa7c19379402a83e3cb9ef81353d0896
+  data.tar.gz: 120b9347b36642f5248ba4c6e95b1898886f666913729cedc28d02b0177e3a97c5136e12ab8052501921a2b812488d55359ed326ac361dd5cb9c5af76b1ff55f

data/CHANGELOG.md

@@ -4,6 +4,212 @@ All notable changes to this project are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.0] - 2026-10-18
+
+### Added
+
+- **Support apart from the inbox.** `config.thread_page = :support` reads a
+  case on the engine's own page, `/support/tickets/T-AB12CD`, which renders
+  chats' thread template (same bubbles, composer and realtime) with its way
+  back leading to the support list. `support_thread_path`, the list rows and
+  the redirect after opening a case follow the setting. The default,
+  `:chats`, is unchanged. A third Hotwire Native rule pushes the ticket page
+  under `:support`.
+- **A requester's own case always opens through chats.** chats finds every
+  thread and composer request through `viewer.chats`, which applies the
+  host's `inbox_scope`; a host keeping support out of its inbox would 404 its
+  requesters inside their own cases. The engine adds the viewer's own cases
+  to chats' `conversation_lookup_scopes` (`SupportDesk::ConversationAccess`,
+  `SupportDesk::Ticket.conversations_of`): by participation and blocks,
+  without the listing scope, each a direct conversation whose subject is that
+  very case. Nothing else the scope hides becomes reachable.
+- **`acknowledgement`**, a desk setting: the system line posted right under a
+  requester's first message, in the same transaction, and read for them as
+  it is posted (a receipt for their own words is never news). Same values and
+  interpolations as `opening_line`; nil by default, and the gem ships
+  `support_desk.thread.acknowledgement` to opt into.
+- An I18n key given as a line reads its `<key>_with_promise` variant when the
+  desk promises a time and the variant exists (the assistant lines already
+  did): the shipped acknowledgement is "Thanks, we got it." on a desk with
+  `reply_within = nil`, and adds the promise otherwise.
+- `SupportDesk.humanize_promise` and `DeskConfiguration#reply_promise`: the
+  promise in the unit the desk wrote it in, from the new
+  `support_desk.durations.*` keys.
+- `support_desk.thread.closed_notice` can interpolate `%{reply_within}`,
+  `%{desk}` and `%{label}`.
+
+### Changed
+
+- The answer promise (`support_reply_promise`, the wizard's line, and
+  `%{reply_within}` in every line) is now said in the unit `reply_within`
+  was configured in: `24.hours` reads "24 hours" where it read "1 day", and
+  `8.hours` reads "8 hours" where it read "about 8 hours". A duration of more
+  than one unit, or a fractional one, reads as before. Waits in the console
+  are unchanged.
+
+### Fixed
+
+- `SupportDesk::ConversationAccess` adds a requester's own cases as a lookup
+  scope (`conversation_lookup_scopes`, chats 0.5.1) instead of rescuing chats'
+  404: no exception is inspected, and a host's own `find_conversation` that
+  refuses a case is final. It only ever adds a scope beside the host's: a host
+  that returns no scopes for a viewer (a suspended account) opens nothing for
+  them, their cases included.
+- The ticket page resolves its conversation through chats' own
+  `find_conversation` (a chats controller bound to the request), so whatever
+  refuses a case at the chats URL refuses it on the ticket page too.
+- The access fallback and the ticket page require the case and its
+  conversation to point at each other (a direct conversation whose subject is
+  that case): a ticket mislinked to a group or to another conversation opens
+  nothing.
+- The ticket page resolves its conversation through chats' participation and
+  block rules: owning the case is no longer enough once the seat is gone.
+- The support list's "showing the N most recent" line under a long closed
+  section (`support_desk.tickets.closed_capped`) had no copy in English or
+  Spanish, so a requester with more than 20 closed cases read "translation
+  missing".
+
+### Compatibility
+
+- Requires chats >= 0.5.1; take both from GitHub by tag until they are on
+  rubygems. (The old `~> 0.3, >= 0.3.2` already admitted 0.4 and 0.5: `~> 0.3`
+  is `>= 0.3, < 1.0`.) 0.5.1 brings the lookup seam the access to a
+  requester's own case is built on. The whole suite runs on chats 0.5.1, the
+  reviewed package in `vendor/cache` built from tag v0.5.1 (6159ea1). The
+  chats 0.4.2 CI leg is gone: the constraint no longer admits it. Every CI job
+  asserts the chats it resolved (`CHATS_VERSION_UNDER_TEST`), so a later chats
+  release never silently becomes what CI tests. The dummy app's chats
+  migration is chats' current install template.
+
+## [0.3.2] - Unreleased
+
+### Fixed
+
+- Persist message-registration receipts atomically with clocks and turn revisions.
+  A new message with an earlier timestamp or smaller UUID is no longer dropped
+  as a replay. It invalidates the turn and triggers requester notifications and
+  handoff detection once, without rewinding clocks. This also fixes human-only
+  desks; no assistant configuration is needed to encounter the old defect.
+- Recovery discovers unregistered replies on closed cases and honors the desk's
+  reopen/locked policy. Repair also runs when the assistant is disabled; only
+  actual assistant dispatch requires one to be configured.
+- Public assistant assignment, release and reply refuse `turn: :current`.
+  Internal outreach and seat-taking use private paths and actual tokens.
+- Default Chats signatures render assistant messages using per-message
+  disclosure snapshots, including old 0.3.0 messages with provenance but no
+  assistant-row snapshot. Rename, mode change and flag-off do not erase old
+  disclosure. Human replies and approved drafts keep human signatures, and host
+  signature overrides remain authoritative. Transcript names are snapshotted
+  for new messages; older ones use their stored display name.
+- Correct the README signature override to preserve the human fallback.
+
+### Upgrade
+
+Run `rails generate support_desk:upgrade` and migrate **with support writes paused
+and all old web/jobs drained**. The new receipt table follows the existing ticket
+and message ID types and seeds historical messages up to the old role clocks.
+Old clocks cannot reveal lost callbacks behind that baseline: review suspect
+historical cases before resuming. Only 0.3.2 processes may write after cutover.
+See README for recovery, rollback limitations and the unchanged SQLite caveat.
+No gem publication or deployment is performed by this change.
+
+## [0.3.1] - 2026-09-19
+
+**Hardening the assistant, after an adversarial review of 0.3.0.** Nine
+defects, every one of them in the concurrency, recovery and kill-switch
+guarantees the release advertised rather than in what a green suite
+covered. Nothing here changes what an assistant may do; it changes what
+can happen to a case while she is doing it. `assign!` and `release!` take
+a `turn:` when `by:` is an assistant — the one API change — and a host
+with no assistant is untouched.
+
+### Fixed
+
+- **A customer's next question can no longer be answered around (R1).**
+  Reconciliation is a `SELECT`, and a requester never takes the case's row
+  lock, so a question could commit between the answer reading the case and
+  the answer writing to it: she replied to the previous one, and a human
+  approved a proposal from a page that predated the new one — `seen_turn`
+  was not evidence that the reviewer had seen the last committed message.
+  Every speaking path now takes the ticket's row lock and then the
+  conversation row chats updates inside every message insert, before
+  reconciling. The lock order is ticket → conversation everywhere, and it
+  is written down. **The guarantee is a row lock, so it holds on PostgreSQL
+  and MySQL and not on SQLite**, which has no row locks and whose WAL
+  snapshot reads straight through an open write transaction: a desk with an
+  assistant belongs on PostgreSQL or MySQL, and `doctor` now warns when it
+  is not.
+- **A seat is decided under the lock (R2).** `assign!` asked whether
+  anybody held the case, and whether she could hold it, *before* the
+  transition acquired the row. No threads were needed to break it: load an
+  unassigned case into one instance, give it to a person through another,
+  and the first instance took the seat from them. A topic cap or a pause
+  committed while a take waited for the lock was read too late in the same
+  way.
+- **A lost registration is repairable (R3).** A requester message that
+  committed while the process that should have registered it died left a
+  turn nothing could ever consume: reconciliation happened inside the
+  candidate answer's savepoint, the bumped revision made that very answer
+  stale, and the `StaleTurn` rolled the repair back with it — for ever,
+  while the clocks said `awaiting_requester` so no idle query could see the
+  case. The fold is now its own committed step, and
+  `redispatch_assistant_turns!` looks for unregistered messages before it
+  looks at clocks.
+- **Messages that share an instant no longer deadlock the turn (R4).** The
+  unseen-message test was "its id is not the one the clock was set from",
+  so every other message on that timestamp read as new: reconciliation
+  folded an already-registered one in again, bumped the revision, and made
+  the answer that discovered it stale. The retry did the same thing. "Seen"
+  is now the pair `(created_at, id)` compared in chats' own transcript
+  order, by the same rule in Ruby and in SQL.
+- **The silent sweep rechecks before it escalates (R5).** Its predicates
+  were true when it SELECTED its candidates. A person who answered, took
+  the case or reset the clock in between lost anyway: the case was marked
+  human-required, its priority went up, and the customer was told a person
+  was coming — on a case that already had one.
+- **Stranded seats come back (R6).** `deactivate!` promised the sweep would
+  release her cases; the sweep only ever visited configured assistants with
+  a `responds_within`, and only cases already overdue. An assistant with no
+  promise kept her seat for ever, and one removed by the documented kill
+  switch — which takes her configuration away — was not visited at all,
+  while the doctor's assistant checks returned early on exactly that state.
+  `SupportDesk.reclaim_assistant_seats!` (and `rake
+  support_desk:reclaim_assistant_seats`) reads the seats that exist.
+- **Running out of turns tells the host (R7).** The budget branch wrote the
+  `escalated` event, released her seat and posted the public hand-off line,
+  but only the outer `escalate!` published `:ticket_escalated` — so a
+  host's "a person is needed here" notifier never heard about a
+  conversation that ran out of turns. One private method now publishes it
+  for every hand-off.
+- **Disclosure on old messages stops moving (R8).** The requester-facing
+  signature resolved live configuration, so taking her out of the
+  initializer rewrote "— Rose · asistente virtual" into "— Rose" on
+  messages nobody had touched. Her name and mode are snapshotted onto her
+  own row and read back from it when nothing declares her any more. A
+  rename still renames history, deliberately; the README shows the
+  `Chats.config.message_signature` lambda for hosts that want each bubble
+  frozen.
+- **The kill switch is read after the wait (R9).** Eligibility was checked
+  before the case's row lock, and the policy then read `active?` off that
+  same stale copy, so an already-seated assistant whose job queued behind a
+  busy case could still speak after `deactivate!` had committed. Every verb
+  resolves her under the lock now, from the row. The ordinary in-flight
+  window — a switch that commits after that read — is documented rather
+  than claimed away.
+
+### Changed
+
+- `Ticket#assign!` and `Ticket#release!` take `turn:`. It is REQUIRED when
+  `by:` is an assistant (`ArgumentError` when omitted, `StaleTurn` when
+  stale) and ignored for a person, whose calls are unchanged.
+- `SupportDesk.release_silent_assistants!` runs
+  `reclaim_assistant_seats!` first, and its count includes what that
+  reclaimed.
+- The doctor's assistant invariants run whenever an assistant ROW exists,
+  not only while one is configured.
+- `Ticket.with_unregistered_requester_messages` — the scope behind the
+  repair half of redispatch.
+
 ## [0.3.0] - 2026-09-19
 
 **A machine can answer, and a person still owns every word it sends.** An

data/README.md

@@ -153,6 +153,7 @@ configuration mistake is a boot failure, never a 3 a.m. `NoMethodError`.
 | `current_agent_method` | `:current_user` | how the console finds the person answering (or define `current_agent` in your controller) |
 | `authenticate_method` | `:authenticate_user!` | your own filter, run before every requester screen |
 | `visible_desks_for` | `nil` (every desk) | `->(agent) { … }` returning the desks this agent may work; scopes the whole console |
+| `thread_page` | `:chats` | where a requester reads a case: `:chats` (its thread in the chats inbox) or `:support` (this engine's own ticket page, for support kept apart from the inbox; see [Support apart from the inbox](#support-apart-from-the-inbox)) |
 | `authorize_console` | `nil` (allow) | `->(agent, ticket, action) { … }`; asked before every console action, `ticket` is nil for `index`, `new`, `next` and `open_conversation`; a hook that raises **denies** |
 | `assistant(key) { … }` | — | declare an assistant (see [Assistants](#-assistants)); `config.assistants`, `config.assistant?(key)` read them back |
 | `default_assistant` | the only one declared | which assistant the `:default` desk gets when more than one exists |
@@ -185,7 +186,7 @@ SupportDesk.desk(:billing)  # another one (nil if nobody configured it)
 | `reply_policy` | `:anyone` | `:anyone` (a drop-in posts, signed; an unheld case is taken by whoever answers) · `:take_over` (replying reassigns) · `:assignee_only` (raises `NotAllowed`) |
 | `announce_assignments` | `:first_only` | `:first_only` ("Lucía is taking care of your request" once) · `:always` (hand-offs too) · `:never` |
 | `closed_tickets` | `:reopen_on_reply` | `:reopen_on_reply` (a requester writing reopens the case) · `:locked` (composer replaced by a notice) |
-| `reply_within` | `24.hours` | the SLA breach threshold **and** the promise the requester reads |
+| `reply_within` | `24.hours` | the SLA breach threshold **and** the promise the requester reads, said in the unit you write it in (`72.hours` reads "72 hours") |
 | `at_risk_after` | `4.hours` | when a waiting case starts showing as at risk |
 | `open_rate_limit` | `{ to: 5, within: 1.hour }` | how often one requester may **ask**; `nil` disables. Counts only cases the requester opened |
 | `max_open_tickets` | `5` | how many cases one requester may have open; `nil` disables. Same rule |
@@ -195,6 +196,7 @@ SupportDesk.desk(:billing)  # another one (nil if nobody configured it)
 | `auto_close_after` | `nil` | reserved for the sweep job: a duration after which an answered case closes itself |
 | `opening_line` | `nil` | the system line a requester-opened thread starts with (see [Writing first](#writing-first)) |
 | `opening_line_from_support` | the gem's I18n copy | the same line for a case the desk opened |
+| `acknowledgement` | `nil` | the system line posted right under a requester's first message ("Thanks, we got it…"; see [Writing first](#the-line-a-thread-opens-with)) |
 | `find_requester { \|query\| … }` | `nil` | how a console turns what an agent typed into a requester record |
 
 `SupportDesk.doctor.print` checks all of it against a running app (see
@@ -410,7 +412,7 @@ mount SupportDesk::Engine => "/support"   # CarHey mounts it at "/messages/suppo
 | `GET /support` | their cases — open ones as chats rows, closed ones folded away, and the door into a new one |
 | `GET /support/new` | the wizard: pick a topic, pick the thing, write. One URL, three Turbo frames |
 | `POST /support/tickets` | `ask_support!`, then straight into the conversation |
-| `GET /support/tickets/:id` | a stable URL for a case (`/support/tickets/T-AB12CD` works too), redirecting to its thread |
+| `GET /support/tickets/:id` | a stable URL for a case (`/support/tickets/T-AB12CD` works too): a redirect to its thread, or the page it is read on under `thread_page = :support` |
 
 The screens inherit `config.parent_controller`, so your layout, your
 authentication (`config.authenticate_method`) and your locale switching all
@@ -440,6 +442,54 @@ door in its place (`config.inbox_entry = :always | :when_tickets | :never`) —
 a support entry that only exists once you already have a ticket is
 undiscoverable.
 
+### Support apart from the inbox
+
+Some products want support to be a place of its own: a Support button that
+leads to the person's cases, rather than an official row among their
+conversations. Three settings say so:
+
+```ruby
+# config/initializers/support_desk.rb
+config.thread_page = :support     # a case is read at /support/tickets/T-AB12CD
+config.inbox_entry = :never       # no door in the chats inbox
+
+# config/initializers/chats.rb: support conversations out of the inbox, the unread badge and everything else that lists
+config.inbox_scope = ->(relation, _viewer) {
+  relation.where(subject_type: nil).or(relation.where.not(subject_type: "SupportDesk::Ticket"))
+}
+```
+
+(`subject_type: nil` keeps the conversations that are about nothing, which is
+most of them: `where.not` alone would hide those too.)
+
+The ticket page **is chats' thread**: the engine renders chats' own template,
+so the bubbles, the composer, read state, typing and realtime are the ones
+every other conversation has, with the desk's verified name in the header.
+Only the way back differs: it leads to the support list. Older pages, the
+composer and the live updates still go to chats' endpoints.
+
+Those endpoints find a conversation through the relations chats'
+`conversation_lookup_scopes` returns (chats >= 0.5.1), by default the viewer's
+inbox with the host's `inbox_scope` applied, so a scope that keeps support out
+of the inbox would also keep a requester out of their own case. The engine
+adds one relation after chats' own (`SupportDesk::ConversationAccess`): the
+viewer's **own** cases (`SupportDesk::Ticket.conversations_of`), through the
+same participation and block rules (`Chats::Conversation.inbox_for`) without
+the listing scope, each a direct conversation whose subject is that very
+case. Nobody gains a conversation they are not seated in, anything else the
+scope hides stays a 404, and a host's own `find_conversation` that refuses a
+case still refuses it. support_desk only ever adds a scope beside the host's:
+a host that must refuse a viewer entirely returns no scopes, and then nothing
+opens for them, their cases included. The ticket page asks chats the same
+question (chats' own `find_conversation`), so it never shows what the chats
+URL would refuse.
+
+Links follow the setting: `support_thread_path`, the list's rows and the
+redirect after a case is opened all lead to the ticket page, by reference.
+Telling the requester an answer arrived is then yours, since the chats
+badge no longer counts it: subscribe to `agent_replied` (see [Events](#events))
+and link the notification to `support_desk.ticket_path(ticket.reference)`.
+
 Hotwire Native hosts merge the engine's path rules into their own, AFTER any
 rule that could swallow them:
 
@@ -462,7 +512,7 @@ URL, so the back gesture and cold-boot deep links work.
 | `link_to_support(about:, text:, **html)` | the door into the wizard (nothing when there is nobody to ask, or nothing they may ask about) |
 | `support_unread_badge` | unread support messages, counted against the chats read horizon |
 | `support_desk_styles` | the bundled stylesheet tag for your `<head>` |
-| `support_reply_promise` | "We usually reply in under 24 hours", from `reply_within` |
+| `support_reply_promise` | "We usually reply in under 24 hours", from `reply_within` (also `SupportDesk.config.desk(key).reply_promise`) |
 | `support_ticket_state(ticket)` | "We're on it" · "We replied" · "We wrote to you" · "Closed" |
 | `support_inbox_door?(viewer)` | whether the inbox should show the door instead of a row (`inbox_entry`) |
 | `support_desk_record(key)`, `support_desk_avatar`, `support_desk_badge` | the desk as a counterpart: record, avatar (initials fallback), verified badge |
@@ -682,6 +732,33 @@ existing threads open exactly as they do today; `opening_line_from_support`
 has the gem's own copy as its default, because a message from a desk
 somebody never wrote to has to explain itself.
 
+And one line goes **under** the first message, for a case the requester
+opened: the answer to "did that go through?", posted in the same
+transaction, before anybody on the desk has read it.
+
+```ruby
+config.acknowledgement = :"support_desk.thread.acknowledgement"
+# => "Thanks, we got it. We usually reply in under 72 hours."
+```
+
+An I18n key reads its `<key>_with_promise` variant when the desk promises a
+time and the variant exists (the shipped key has one), so a desk with
+`reply_within = nil` says "Thanks, we got it." and nothing it cannot keep.
+The requester's read horizon moves through the acknowledgement as it is
+posted: it is a receipt for what they just wrote, never news to them.
+
+Same values and interpolations as the opening lines, nil by default. It
+never moves the clocks (it is a system message), it is pinned one database
+tick after the message when the clock did not move between the two inserts,
+and it is then the conversation's last message, which is what a list row
+previews. A reply into a case already open is not acknowledged again.
+
+`%{reply_within}` is the promise in the unit it was configured in
+(`SupportDesk.humanize_promise`: `72.hours` is "72 hours", never "3 days"),
+from `support_desk.durations.*`. The closed notice
+(`support_desk.thread.closed_notice`) takes the same three interpolations,
+so a locked case can say how soon a new one will be answered.
+
 ### From the console
 
 Add `new` to your routes and the queue grows a "Write to someone" button:
@@ -942,6 +1019,13 @@ one raises `SupportDesk::StaleTurn` and writes nothing. That one integer is
 also why this gem has no idempotency keys, no claim rows and no leases —
 "is this still the case you read?" is already answered.
 
+Every verb of hers takes it, and that includes taking and giving back the
+seat: `assign!(to: rose, by: rose, turn:)` and `release!(by: rose, turn:)`
+require it when `by:` is an assistant (an omitted turn is an
+`ArgumentError`, a stale one a `StaleTurn`), because a run that finished
+after the case moved on must not release the seat a newer one took. A
+**person's** calls are unchanged and take no turn.
+
 Two consequences worth knowing:
 
 - Check `ticket.assistant_turn == turn` in your job **before you spend
@@ -949,6 +1033,34 @@ Two consequences worth knowing:
 - A retry after a committed action is a `StaleTurn`, and that is correct:
   the work was done. Generated jobs `discard_on` it.
 
+#### Ticket, then conversation
+
+A turn is only as good as the reconciliation behind it, and reconciliation
+is a `SELECT`: on its own it cannot exclude a message that commits a
+millisecond later. Your customer never takes the case's row lock — they
+press send, and chats writes a message.
+
+What chats *does* take is the **conversation row**: every message insert
+updates `chats_conversations` inside its own transaction. So every path
+that speaks takes the ticket's row lock and then that row, before
+reconciling. A question already in flight holds it, so we wait for it and
+the turn goes stale; a question that starts after we hold it waits for us
+and raises a turn of its own. **The order is always ticket → conversation**,
+in this gem and in anything you add to it.
+
+What that does not cover: a message whose `INSERT` was already stamped when
+we won the row is still stamped earlier than the answer, so a transcript can
+show a question above an answer that did not address it. That is a
+genuinely simultaneous send, and its own turn follows.
+
+> [!IMPORTANT]
+> **This is a row lock, so it is PostgreSQL and MySQL.** SQLite has none:
+> it serializes writes, and in WAL mode a reconciliation `SELECT` reads the
+> last committed snapshot straight through a requester's open write
+> transaction, so a question committing behind an answer is still missed
+> there. Run PostgreSQL or MySQL for a production desk with an assistant —
+> `SupportDesk.doctor` warns when you haven't.
+
 ### Proposals in the console
 
 A pending proposal renders above the composer with its confidence, its
@@ -1020,6 +1132,32 @@ the turn and the whole policy that allowed it, `ticket.export` labels it
 marks it for staff. What a customer is told is a product decision; what your
 records say a machine wrote is not.
 
+**Historical disclosure is captured per message.** The default Chats signature
+renderer uses the assistant name and disclosure stored when the message was
+sent. Renaming, changing mode or removing configuration does not rewrite old
+signed bubbles. Human replies and human-approved drafts retain their normal
+human signatures. The assistant row snapshot is a fallback for legacy messages
+without provenance; their original disclosure cannot be reconstructed if it
+was never stored.
+
+A host's `Chats.config.message_signature` override remains authoritative. If
+you customize it, preserve the human fallback as well as the assistant snapshot:
+
+```ruby
+Chats.configure do |config|
+  config.message_signature = lambda do |message|
+    stamp = message.metadata["support_desk"]
+    name = if stamp.is_a?(Hash) && stamp["kind"] == "ai" && stamp["signed"] == true &&
+              stamp["display_name"].is_a?(String) && stamp["display_name"].present?
+      stamp["display_name"]
+    else
+      Chats.display_name_for(message.author)
+    end
+    I18n.t("chats.message.signature", name: name)
+  end
+end
+```
+
 ### Humans outrank
 
 - A person may answer a case she holds under **every** `reply_policy`.
@@ -1071,8 +1209,27 @@ whatever she would have said. `redispatch_assistant_turns` re-emits the turn
 for cases nobody acted on, which is safe precisely because the turn is
 consumed by the first action and every later one is a `StaleTurn`.
 
-`rake support_desk:assistant_status` reads and writes nothing, and is the
-line to put in a deploy check. `SupportDesk.doctor` covers the same ground
+`release_silent_assistants` runs `SupportDesk.reclaim_assistant_seats!`
+first, and you can run that on its own
+(`rake support_desk:reclaim_assistant_seats`). It is a different question
+from silence: it reads the **seats that exist** rather than the assistants
+this process happens to have configured, and gives back every one whose
+holder is switched off, no longer declared, or no longer allowed to hold a
+case — with no `responds_within` and no overdue clock anywhere in it. That
+is what makes `deactivate!` and a flag flipped off actually release her
+cases, and it is why the doctor's seat checks keep running when the
+configuration is gone.
+
+`redispatch_assistant_turns` also repairs before it decides: a requester
+message whose registration was lost after its commit leaves the clocks
+describing a case that no longer exists, so the task looks for unregistered
+**messages** and not only for idle clocks. The repair commits on its own,
+which is what makes a dead process followed by nothing but this task end in
+an actionable turn.
+
+`rake support_desk:assistant_status` reports current counts without changing
+tickets. Resolving configured assistants may create their identity rows or
+refresh their name/disclosure snapshots. `SupportDesk.doctor` covers the same ground
 with verdicts.
 
 ### What the model sees
@@ -1166,7 +1323,8 @@ acts_as_support_agent kind: :ai                                 # validated; see
 SupportDesk.assistant(key = nil)        # the Assistant record, memoised; nil when none is configured
 SupportDesk.reset_assistants!
 SupportDesk.ai_actor?(record)
-SupportDesk.release_silent_assistants!            # → Integer
+SupportDesk.release_silent_assistants!            # → Integer (runs reclaim_assistant_seats! first)
+SupportDesk.reclaim_assistant_seats!              # → Integer; seats she may no longer sit in
 SupportDesk.redispatch_assistant_turns!(older_than: 1.minute)   # → Integer
 ```
 
@@ -1176,7 +1334,7 @@ SupportDesk.redispatch_assistant_turns!(older_than: 1.minute)   # → Integer
 |---|---|
 | `SupportDesk::Assistant.for(key)` / `.active` | found or created; the on-duty scope |
 | `config` / `configured?` | her slice of the configuration; whether anything still declares her |
-| `name` `avatar` `autonomy` `disclosure` `max_turns` `responds_within` `may_open_conversations?` | read through the configuration, with safe answers when it is gone |
+| `name` `avatar` `autonomy` `disclosure` `max_turns` `responds_within` `may_open_conversations?` | read through the configuration; `name` and `disclosure` fall back to the snapshot on her row, the rest to the safe answer |
 | `disclosed?` `signs?` `notice?` | the mode, as predicates |
 | `disclosed_name` `display_name` `to_s` `support_agent_name` `support_agent_avatar` | what a requester sees |
 | `on_duty?` `support_capacity` | the agent contract |
@@ -1201,6 +1359,8 @@ assistant" it was).
 respond!(body, by:, turn:, files:, confidence:, sources:, metadata:, request:)   # → Outcome
 draft!(body, by:, turn:, …)                                                       # → Draft
 escalate!(by:, reason:, summary:, turn:, request:)
+assign!(to:, by:, reason:, note:, request:, turn:)   # turn: required when by: is an assistant
+release!(by:, reason: :released, request:, turn:)    # idem
 request_human!(by:, request:)          # by: must be the requester
 pause_assistant!(by:, reason:) / resume_assistant!(by:)
 
@@ -1213,6 +1373,7 @@ drafts   pending_draft   notes
 # scopes
 held_by_assistants   held_by_humans   needs_human   assistant_paused   assistant_capped
 resolved_by_assistant   with_pending_draft   assistant_idle_since(time)
+with_unregistered_requester_messages
 ```
 
 Columns: `assistant_revision`, `last_requester_message_id`,
@@ -1288,12 +1449,13 @@ the count is non-zero.
 `support_human_door(ticket)` helper.
 
 **Rake** — `support_desk:release_silent_assistants` ·
+`support_desk:reclaim_assistant_seats` ·
 `support_desk:redispatch_assistant_turns` (`OLDER_THAN=60`) ·
 `support_desk:assistant_status`.
 
 **Doctor** — `assistants (config)` · `assistant turn subscriber` ·
 `assistant authorship` · `assistant silence` · `assistant seats` ·
-`assistant idle turns` · `drafts` · `ai agents without policy`.
+`assistant idle turns` · `drafts` · `ai agents without policy` · `message registrations`.
 
 **Test helpers**
 
@@ -1310,10 +1472,54 @@ the count is non-zero.
 | `with_assistant_config(key = nil, **overrides) { … }` | |
 | `with_topic_assistant_cap(path, level) { … }` | rebuilds the frozen tree with one cap |
 
-### Upgrading to 0.3
+### Upgrading to 0.3.2 (including hosts without assistants)
+
+0.3.2 adds `support_desk_message_registrations`, an internal receipt per text
+message. A receipt, written with the ticket clocks and revision in one
+transaction, distinguishes a replay from an unseen message. Timestamp and UUID
+order are not evidence of delivery. Every unseen requester message invalidates
+the turn, notifies the host and runs handoff detection once, even if its timestamp
+is older; the SLA timestamps themselves never move backwards.
+
+**This upgrade requires a drained cutover; it is not rolling-safe.** The table
+is additive, but old processes cannot write receipts.
+
+1. Pause support writes and drain old web requests and jobs. Keep the assistant
+   disabled throughout the cutover.
+2. Run `rails generate support_desk:upgrade`, inspect the new migration, then
+   `rails db:migrate` while writes remain paused. Fresh installs get the same
+   migration from `support_desk:install`.
+3. The migration seeds existing text messages at or before each role's old
+   clock as the historical baseline. Messages beyond those clocks remain
+   discoverable by recovery. **Old data cannot prove whether a message behind
+   the clock lost its callback.** Review suspect historical cases explicitly;
+   the migration does not replay old notifications or reopen history en masse.
+4. Start only 0.3.2 processes. Run `SupportDesk.doctor` and
+   `SupportDesk.redispatch_assistant_turns!` before resuming support traffic.
+   Recovery checks closed cases as well: `:reopen_on_reply` reopens them, while
+   `:locked` preserves closure and dispatches no model work. Registration repair
+   also runs on desks with no assistant configured.
+5. Resume writes. An assistant rollout still requires its own staging checks
+   and disclosure decision. The serialization guarantee still requires
+   PostgreSQL/MySQL; SQLite does not acquire row locks.
+
+Do not roll back to an old writer while serving traffic: it would leave missing
+receipts. If a rollback is necessary, pause and drain first, keep the receipt
+table, and re-establish the historical baseline before a later upgrade. Removing
+a receipt deliberately permits processing that message again; it is an internal
+recovery action, not a normal host API.
+
+Public assistant `turn:` arguments must be the observed opaque token. Symbols
+such as `:current` are refused; private outreach and automatic seat-taking do
+not expose a public bypass. No new host-facing registration API is required.
+
+### Historical upgrade from 0.2 to 0.3.0
+
+The following describes the original assistants migration. When installing the
+current release, also follow the 0.3.2 cutover above.
 
 ```bash
-rails generate support_desk:upgrade   # copies the additive assistants migration
+rails generate support_desk:upgrade   # current releases also copy the receipt migration
 rails db:migrate
 ```
 
@@ -1464,10 +1670,13 @@ supportable), `find_requester` (callable, one argument), `engine mount`,
 (no half-NULL `opened_by`; warns on legacy NULL rows and names the backfill
 task), `awaiting` (agrees with the transcript), `references` (unique).
 Assistants (only where one is configured): `assistants (config)`,
-`assistant turn subscriber`, `assistant authorship`, `assistant silence`,
-`assistant seats`, `assistant idle turns`, `drafts`, and `ai agents without
-policy` — which warns about any host class declared `kind: :ai`, since every
-support write by it is refused.
+`assistant turn subscriber`, `assistant serialization` — which warns when
+the adapter takes no row locks, because the turn rests on them —
+`assistant authorship`, `assistant silence`, `assistant seats`, `assistant
+idle turns`, `drafts`, and `ai agents without policy`, which warns about any
+host class declared `kind: :ai`, since every support write by it is refused.
+The seat and draft checks also run once she is no longer configured, since
+that is exactly when a seat gets stranded.
 
 ## Compatibility
 
@@ -1536,12 +1745,14 @@ SupportDesk.desk(key = :default)       # the Desk record, found or created, memo
 SupportDesk.assistant(key = nil)       # the Assistant record, memoised; nil when none is configured
 SupportDesk.reset_assistants!          SupportDesk.ai_actor?(record)
 SupportDesk.release_silent_assistants!            # the net under a dead harness (schedule it)
+SupportDesk.reclaim_assistant_seats!              # seats an assistant may no longer sit in
 SupportDesk.redispatch_assistant_turns!(older_than: 1.minute)
 SupportDesk.find_topic("billing/invoice")
 SupportDesk.on(event, key: nil) { … }  SupportDesk.off(event, key)
 SupportDesk.doctor
 SupportDesk.native_path_rules(mount:, title:)   # Hotwire Native path rules for the requester screens
-SupportDesk.humanize_duration(24.hours)          # "1 day", in the reader's language
+SupportDesk.humanize_duration(24.hours)          # "1 day", in the reader's language (a wait: rounded)
+SupportDesk.humanize_promise(72.hours)           # "72 hours" (a promise: in the unit it was made in)
 SupportDesk.actor_key(record)                    # a stable key for an actor (GlobalID param); what event payloads store
 SupportDesk.requester_class?(klass)  .supportable_class?(klass)  .agent_class?(klass)
 SupportDesk.eligible?(record, condition)         # how both macros read their `if:`
@@ -1553,7 +1764,7 @@ SupportDesk::VERSION
 
 After checking out the repo, run `bundle install`, then `bundle exec rake ci`. The dummy app lives in `test/dummy` and mounts all three surfaces the way a real host does: the requester engine at `/messages/support`, `chats` at `/messages`, and the turnkey console at `/admin/support` — plus the same console again inside a host-owned `madmin` namespace, because "the console uses only the public API" is a claim that needs a second implementation to be worth anything.
 
-`chats` is the kernel this gem is a product on and the two are developed in lockstep, so the Gemfile points at a sibling checkout (`../chats`) whenever this gem needs a `chats` that is not on rubygems yet. It currently requires `chats` ~> 0.3 (the `verified:` messager option).
+`chats` is the kernel this gem is a product on and the two are developed in lockstep. support_desk requires `chats >= 0.5.1, < 1.0`. Until that is on rubygems, the bundle takes the reviewed chats package from `vendor/cache` (provenance and checksum in `vendor/cache/README.md`), so `bundle exec rake ci` needs no network and no sibling checkout.
 
 ## Contributing
 

data/app/controllers/support_desk/application_controller.rb

@@ -81,10 +81,13 @@ module SupportDesk
       respond_to?(:chats) ? chats : Chats::Engine.routes.url_helpers
     end
 
-    # Where a case is read and answered: its chats conversation, never a
-    # second thread UI of our own.
+    # Where a case is read and answered: its chats conversation, in the
+    # chats inbox (`thread_page = :chats`) or on this engine's ticket page
+    # (`:support`). Never a second thread UI of our own: that page renders
+    # chats' thread.
     def conversation_path_for(ticket)
       return root_path if ticket.conversation.nil?
+      return ticket_path(ticket.reference) if SupportDesk.config.support_thread_page?
 
       chats_routes.conversation_path(ticket.conversation)
     end