@snagset/server 0.1.15 → 0.1.18

package/dist/routes/threads.js

@@ -4,6 +4,7 @@ import { THREAD_REF_PREFIX } from "../vendor/types/names.js";
 import { ID_PREFIX } from "../vendor/types/names.js";
 import { csrfOk } from "./owner.js";
 import { queueCommentNotice, queueResolvedNotice } from "../mail/notify.js";
+import { dropAssignedBy, queueAssignedNotice } from "../mail/assigned.js";
 import { effectiveWriteMode } from "./sessions.js";
 import { mcpAllows, scopeDenied, checkWriteBudget, budgetExhausted, recordAgentWrite, agentReviewer, } from "./mcpAuth.js";
 import { inPool } from "./assignees.js";
@@ -12,13 +13,13 @@ import { queueIntegrationEvent } from "../integrations/outbox.js";
 import { inOrg } from "../db/scope.js";
 import { isStudioModerator } from "../studioReviewers.js";
 /**
- * Wire id ⇄ row id — 05 §3.5, verbatim: *"id uuid PRIMARY KEY — client-minted
+ * Wire id ⇄ row id, verbatim: *"id uuid PRIMARY KEY — client-minted
  * UUIDv7; wire form 'thr_…'"*.
  *
  * The row is a bare uuid so it indexes and joins as one; the prefixed form is
  * the identity everything OUTSIDE the database uses, because a bare uuid in a
  * webhook payload, a GitHub issue marker or a support ticket tells you nothing
- * about what you are looking at (foundations §2.10).
+ * about what you are looking at.
  *
  * Both directions live here rather than at each call site. The widget mints
  * the id, so the very first POST arrives prefixed, and a server that stores
@@ -33,10 +34,10 @@ function rowId(wire, prefix) {
 }
 const wireId_ = (row, prefix) => prefix + row;
 /**
- * §2.2's envelope. `details` was missing from this file's copy while
+ * The envelope. `details` was missing from this file's copy while
  * `comments.ts` had it, so every `field_not_permitted` here — including the
  * long-standing refusal to move a thread between rounds — shipped without the
- * `details.field` §6.9 registers for that code. A client cannot mark the
+ * `details.field` registers for that code. A client cannot mark the
  * offending input without it.
  */
 function fail(c, status, code, message, details) {
@@ -44,8 +45,8 @@ function fail(c, status, code, message, details) {
 }
 /**
  * Every request runs inside a transaction with `app.org_id` set, which is what
- * makes 08 §9.2's RLS policies do anything at all. It is set even where the
- * connecting role can bypass them (D50) — the day someone points DATABASE_URL
+ * makes the RLS policies do anything at all. It is set even where the
+ * connecting role can bypass them — the day someone points DATABASE_URL
  * at a properly restricted role, every query here has to already be correct,
  * and a `SET LOCAL` added later would be added under incident conditions.
  */
@@ -57,12 +58,12 @@ function fail(c, status, code, message, details) {
  * added to each by hand after a link session's list was caught carrying a
  * private reply: a rule answered in three places drifts.
  *
- * ── TEAM-ONLY (05 §6.4a) ──
+ * ── TEAM-ONLY ──
  *
  * A `private` reply is for the studio's eyes and never reaches a reviewer
  * session or an agent. The owner sees all of them.
  *
- * ── TOMBSTONES, FOR THE OWNER ONLY (§3.11) ──
+ * ── TOMBSTONES, FOR THE OWNER ONLY ──
  *
  * A deleted comment is a row with `body` NULL. Everyone else gets it filtered
  * out, as before — the widget drops it and has nothing to render a hole with.
@@ -73,10 +74,10 @@ function fail(c, status, code, message, details) {
  * on the studio's screen as a tombstone exactly until the next poll replaced
  * the row, and then gone.
  *
- * The tombstone is §3.11's shape — id, NULL body, deletedAt, the author's
- * NAME only — plus `createdAt`, which §3.11 leaves out and the studio needs:
+ * The tombstone is the shape — id, NULL body, deletedAt, the author's
+ * NAME only — plus `createdAt`, which leaves out and the studio needs:
  * a hole is placed in time by when it was written. `seq` stays server-side
- * for §3.11's reason, and the author's id and kind go with the words.
+ * for the reason, and the author's id and kind go with the words.
  */
 function commentsJson(tx, asOwner) {
     return tx `COALESCE(
@@ -96,7 +97,7 @@ function commentsJson(tx, asOwner) {
     '[]'::json)`;
 }
 export function threadRoutes(sql, 
-/** The 10-second cache (05 §4.4), not a fresh SELECT per handler. Every
+/** The 10-second cache, not a fresh SELECT per handler. Every
  *  route here starts by resolving `{uid}`, and on a database one round trip
  *  away that lookup was costing more than the work it introduced. */
 projects, 
@@ -105,8 +106,8 @@ projects,
  *  not need to know how storage is configured. */
 features, 
 /**
- * Is a mail transport configured (08 §4.8)? Same gate `commentRoutes` takes,
- * and for the same reason: with no transport, 08 §4.8 wants notifications
+ * Is a mail transport configured ? Same gate `commentRoutes` takes,
+ * and for the same reason: with no transport, the design wants notifications
  * "off and say so, rather than silently queueing" — rows that would otherwise
  * accumulate for the life of the install and arrive in one burst the day
  * somebody configures Resend.
@@ -115,11 +116,13 @@ notifications = async () => false,
 /** Where this instance lives (SNAGSET_BASE_URL) — the brief's screenshot links are absolute. */
 baseUrl = async () => "http://localhost:8080", 
 /**
- * D95/D97: the site's tracker connections — id, provider, and whether
+ * The site's tracker connections — id, provider, and whether
  * issues are made on every new thread. Injected so this file never opens
  * a token; the worker does that.
  */
-trackers = async () => []) {
+trackers = async () => [], 
+/** How long an assignment waits before its email (SNAGSET_ASSIGN_MAIL_DELAY_S). */
+assignDelayMs) {
     const app = new Hono();
     /** Resolve `{uid}`, and 404 rather than leak whether a uid exists. */
     const project = (uid) => projects.get(uid);
@@ -129,7 +132,7 @@ trackers = async () => []) {
     // request and, worse, ran AFTER the real one and overwrote
     // `Access-Control-Allow-Headers` with a hand-typed `content-type` — harmless
     // only because a preflight never reaches this far.
-    /** 05 §6.1 — what the widget reads at mount to know what this deployment can do. */
+    /** What the widget reads at mount to know what this deployment can do. */
     app.get("/api/v1/projects/:uid/config", async (c) => {
         const p = await project(c.req.param("uid"));
         if (!p)
@@ -137,7 +140,7 @@ trackers = async () => []) {
         c.header("x-snagset-config-version", String(p.config_version));
         c.header("ETag", `"${p.config_etag}"`);
         /**
-         * CACHEABLE, briefly — D66 makes this the stub's visibility check, fetched
+         * CACHEABLE, briefly — the decision makes this the stub's visibility check, fetched
          * once per visitor per page-load-cluster rather than per page. 60 seconds:
          * long enough that a browsing session costs one request, short enough that
          * flipping the audience in the dashboard lands within a minute.
@@ -148,7 +151,7 @@ trackers = async () => []) {
         // full body to a stranger origin, and the split below would be theatre.
         c.header("Vary", "Origin");
         /**
-         * 05 §7.2's ORIGIN-AWARE BODY, finally conformed to (D69) — Eurico's
+         * The ORIGIN-AWARE BODY, finally conformed to — the maintainer's
          * question, verbatim: "the api gets the url that should be there and then
          * just validates in the frontend?" Which is this design: the server never
          * learns the page's URL (the browser sends only its origin, which CORS
@@ -158,14 +161,14 @@ trackers = async () => []) {
          * for it is printed in their page source.
          *
          * A stranger origin still gets a 200 with the public subset (writeMode
-         * included) rather than a 403: the fetch is also how D2's origin
+         * included) rather than a 403: the fetch is also how the origin
          * suggestion is born, and the stub on an archive.org mirror needs a
          * readable "writable: false" to stay dormant — a CORS-omitted header would
          * do that too, but this route is public-read so the suggestion flow works.
          * `originAllowed` is absent (never false) when there is no Origin header:
          * same-origin pages and curl are not strangers.
          */
-        // D91 — the switch, 05 §4.9 layer 6: a paused site is writable from
+        // The switch, layer 6: a paused site is writable from
         // nowhere, and the stub reads `writable` and stays dormant. Said before
         // the origin verdict, because "switched off" is the more useful sentence.
         const paused = p.status !== "active";
@@ -179,9 +182,9 @@ trackers = async () => []) {
             // mode is a complete product, not a degraded one.
             features: await features(p.org_id),
             /**
-             * EFFECTIVE, not the raw column — D66 turns this field into the thing
+             * EFFECTIVE, not the raw column — turns this field into the thing
              * that decides whether every visitor sees the toolbar, and the raw value
-             * lies during D1's grace: a site 25 hours old still says `open` while
+             * lies during the grace: a site 25 hours old still says `open` while
              * every write is already refused. The session route learned this first
              * (see effectiveWriteMode's own comment); the config route repeating the
              * raw column would show a toolbar nobody can type into.
@@ -191,9 +194,9 @@ trackers = async () => []) {
         };
         if (!writable)
             return c.json({ ...base, reason: paused ? "project_paused" : "origin_not_allowed" });
-        // T10/M2-22: the round HISTORY rides the config the widget already fetches
+        // T10/: the round HISTORY rides the config the widget already fetches
         // at mount, so the dock's selector costs no extra request. Behind the
-        // origin split with `keyPrefix` (§7.2): the least sensitive PRIVATE things
+        // origin split with `keyPrefix`: the least sensitive PRIVATE things
         // on the project, which is not the same as public.
         const rounds = await inOrg(sql, p.org_id, (tx) => tx `
       SELECT number, name, closed_at IS NOT NULL AS closed
@@ -207,7 +210,7 @@ trackers = async () => []) {
         });
     });
     /**
-     * 05 §6.4 — the list, endpoint 7, which the route table marks **W/D**.
+     * The list, endpoint 7, which the route table marks **W/D**.
      *
      * ONE endpoint, TWO audiences, and the credential decides the scope. That is
      * the spec's design and not a shortcut: a dashboard is not a different kind
@@ -224,7 +227,7 @@ trackers = async () => []) {
      * cross-origin credentialed read is refused by the browser whatever this
      * returns.
      *
-     * `route` is the generated projection off the anchor (§3.5), so filtering by
+     * `route` is the generated projection off the anchor, so filtering by
      * it is an index scan rather than a JSONB walk on every row.
      */
     app.get("/api/v1/projects/:uid/threads", async (c) => {
@@ -238,7 +241,7 @@ trackers = async () => []) {
         const owner = c.get("owner");
         const asOwner = !!owner && owner.orgId === p.org_id;
         /**
-         * An MCP token with `threads:read` (07 §8.2) reads with the studio's
+         * An MCP token with `threads:read` reads with the studio's
          * FILTERS but not the studio's PRIVACY, and the split is deliberate.
          *
          * Filters: an agent asked to "list the open snags on checkout" needs
@@ -246,10 +249,10 @@ trackers = async () => []) {
          * Denying those would make `list_threads` return the latest open round of
          * the default environment and call it the project.
          *
-         * Privacy: `private` threads and team-only replies (§6.4a) stay OUT. 07's
+         * Privacy: `private` threads and team-only replies stay OUT. The
          * scope table grants "list and read threads, comments, anchor state" and
-         * says nothing about private, while §8.6 mitigation 7 is *scope
-         * minimalism* and §8.2 separates `context:read` precisely because the
+         * says nothing about private, while the design is *scope
+         * minimalism* and separates `context:read` precisely because the
          * personal-data-bearing half should not ride along by default. A team-only
          * note is the studio talking about the client; an agent that reads one and
          * quotes it into a pull request has published it.
@@ -265,8 +268,8 @@ trackers = async () => []) {
         // Better a sentence naming the missing scope than a confident short list.
         if (mcp && !asAgent)
             return scopeDenied(c, "threads:read");
-        // §6.4's filters. `status` and `q` stay dashboard-only. `round` used to be
-        // gated the same way (`asOwner ? … : null`), which is the M2-22 bug: a
+        // The filters. `status` and `q` stay dashboard-only. `round` used to be
+        // gated the same way (`asOwner ? …: null`), which is the bug: a
         // review-link session's `?round` was silently discarded and every reader
         // without an owner cookie saw every round's pins forever, including ones
         // long since closed. A reviewer session may now ask for a round exactly
@@ -276,7 +279,7 @@ trackers = async () => []) {
         const requestedRound = Number(c.req.query("round")) || null;
         const q = asStudio ? (c.req.query("q") ?? "").trim() : "";
         /**
-         * `?assignee=rev_…|unassigned` — 05 §6.4b's triage filter ("what has
+         * `?assignee=rev_…|unassigned` — the triage filter ("what has
          * nobody picked up"). `unassigned` is a word rather than an empty value
          * because `assignee=` with nothing after it is indistinguishable from an
          * absent parameter on the wire. Studio-only, like status and q: a filter
@@ -291,7 +294,7 @@ trackers = async () => []) {
             }
         }
         /**
-         * `?since=` — 05 §6.3's delta poll, and A10's whole realtime story.
+         * `?since=` — the delta poll, and the whole realtime story.
          *
          * *"`GET …/threads?since=<iso>` returns everything with `updated_at >
          * since`, plus the `deleted[]` tombstone array. The client keeps
@@ -303,14 +306,14 @@ trackers = async () => []) {
          * forever in a background tab.
          */
         /**
-         * `?key=SN-14` — 05 §6.3's server-side permalink, and the thing that makes
+         * `?key=SN-14` — the server-side permalink, and the thing that makes
          * a shared link survive a round.
          *
          * `?snag_t=SN-14` resolves LOCALLY in the widget, against the list it
          * already holds. That list is round-scoped: a non-owner reader defaults to
          * the latest OPEN round. So a permalink to a thread from a closed round —
          * which is most permalinks anyone bothers to share, since they share the
-         * ones that mattered — found nothing and showed F-06's "we could not find
+         * ones that mattered — found nothing and showed F-the "we could not find
          * that comment". The thread was there the whole time, one round back.
          *
          * An exact match on `UNIQUE (project_id, key)`, so at most one row, and it
@@ -318,7 +321,7 @@ trackers = async () => []) {
          * named a specific thread, which is a stronger statement of intent than
          * any default. Privacy is not ignored — a private thread is absent for a
          * non-owner, which reads as "no such key" rather than confirming it exists
-         * (§6.4a's rule for `GET /threads/{id}`).
+         * (the rule for `GET /threads/{id}`).
          */
         const key = c.req.query("key")?.trim().toUpperCase();
         const sinceRaw = c.req.query("since");
@@ -333,7 +336,7 @@ trackers = async () => []) {
         /**
          * ── WHY `visible` IS A COLUMN AND NOT A FILTER ──
          *
-         * 05 §6.4a, acceptance A36: a thread the studio marks `private` must land
+         * Acceptance A36: a thread the studio marks `private` must land
          * in the caller's `deleted[]` so a cached copy is DROPPED. With the
          * predicate in the WHERE clause the row simply stops being returned, which
          * is indistinguishable from "nothing changed" — the client keeps showing a
@@ -342,7 +345,7 @@ trackers = async () => []) {
          *
          * Only the two genuine VISIBILITY conditions are computed. Status, search,
          * environment and round are FILTERS: status does not hide a thread, and a
-         * thread can never change environment or round (D2 — `environment_id` is
+         * thread can never change environment or round (`environment_id` is
          * set at creation and a thread never moves), so none of them can take a
          * client from seeing a thread to not seeing it.
          *
@@ -389,7 +392,7 @@ trackers = async () => []) {
         JOIN environments e ON e.id = t.environment_id
         -- Joined for the round filter, and the join is the fix for a real
         -- trap: threads.round_number is the thread's position WITHIN its round
-        -- (01 §5.2 -- the number on the pin), while rounds.number is which
+        -- (-- the number on the pin), while rounds.number is which
         -- round it is. Two different integers whose names differ by one word,
         -- and filtering on the first is how round=1 returned the single thread
         -- that happened to be first in its round.
@@ -421,7 +424,7 @@ trackers = async () => []) {
                     : tx `AND t.assignee_id = ${assigneeFilter}::uuid`}
           -- Absent round query param: an OWNER still sees every round
           -- (unchanged), but a non-owner reader defaults to the latest OPEN
-          -- round, so a fresh page load is D2-clean rather than showing a
+          -- round, so a fresh page load is -clean rather than showing a
           -- round that closed weeks ago. The ORDER BY number DESC LIMIT 1
           -- correlated subquery is cheap here -- one project's round table
           -- is a handful of rows, never a scan of threads.
@@ -476,11 +479,11 @@ trackers = async () => []) {
          * clocks, one comparison: if the app server ran even a second ahead of the
          * database, every thread updated inside that second would be skipped on the
          * next poll and never returned again — a permanently missing comment, on a
-         * skew nobody would think to look for. 05 §12.3 says the client must never
+         * skew nobody would think to look for. The design says the client must never
          * use its own clock; the same argument applies one layer down.
          */
         const [clock] = await sql `SELECT now() AS now`;
-        // §6.3's tombstones. Ids only — the client already has these threads, and
+        // The tombstones. Ids only — the client already has these threads, and
         // a body would be handing back the private content that made it invisible.
         const visible = rows.filter((r) => r["visible"] !== false);
         const deleted = rows
@@ -494,7 +497,7 @@ trackers = async () => []) {
         });
     });
     /**
-     * 05 §6.2 — create. The whole thing is one transaction because a thread
+     * Create. The whole thing is one transaction because a thread
      * without its first comment is not a snag, it is a pin nobody can read.
      */
     app.post("/api/v1/projects/:uid/threads", async (c) => {
@@ -506,11 +509,11 @@ trackers = async () => []) {
             return fail(c, 401, "unauthorized", "Open your review link, or reload the page, and try again.");
         }
         if (p.status !== "active") {
-            // D91: the switch is off — writes refused, reads work (05 §4.9 layer 6).
+            // The switch is off — writes refused, reads work (layer 6).
             return fail(c, 403, "project_paused", "This site's widget is switched off. Its owner can switch it back on.");
         }
         if (!session.perm.includes("thread:create")) {
-            // §4.8's matrix. A read-only session gets a sentence about permission,
+            // The matrix. A read-only session gets a sentence about permission,
             // not about authentication — they ARE signed in.
             return fail(c, 403, "forbidden", "This review link does not allow new comments.");
         }
@@ -532,8 +535,8 @@ trackers = async () => []) {
         }
         const commentBody = typeof body.comment?.body === "string" && body.comment.body ? body.comment.body : null;
         const commentId = rowId(body.comment?.id, ID_PREFIX.comment) ?? randomUUID();
-        // The attachments uploaded moments ago, to be BOUND by the write below (05
-        // §6.6). Until that runs they are `pending` rows with no owner: §3.6's
+        // The attachments uploaded moments ago, to be BOUND by the write below
+        // Until that runs they are `pending` rows with no owner: The
         // CHECK forbids a bound attachment without exactly one of
         // thread_id/comment_id, which is what makes an orphan detectable rather
         // than merely unlikely. The bind is scoped to this project AND to rows
@@ -546,7 +549,7 @@ trackers = async () => []) {
         //
         // This used to read `createdBy.holderSecret` off the request and mint a
         // reviewer from it — a second, weaker answer to "who is this?" sitting
-        // beside the session that already answers it. 05 §4.4 is explicit that a
+        // beside the session that already answers it. The design is explicit that a
         // session's identity is decided at exchange and never taken from a request,
         // and leaving the body path in place would have meant a caller could author
         // as anyone by presenting a secret they had seen once.
@@ -563,7 +566,7 @@ trackers = async () => []) {
                  * work never was the cost. The *count* was.
                  *
                  * What survives is the ORDER, because the order is load-bearing —
-                 * §2.1's allocation still row-locks the project before the insert
+                 * the allocation still row-locks the project before the insert
                  * reads it, still serialises creation per project, and still yields a
                  * gapless human id. A CTE does not relax that: data-modifying CTEs run
                  * exactly once, to completion, and the insert that reads pseq/rseq
@@ -585,14 +588,14 @@ trackers = async () => []) {
         `;
                 // Kept as its own statement rather than folded into the write below,
                 // because these two are the only failures a caller can act on and
-                // §6.9 gives them distinct codes. A single statement that inserted
+                // the design gives them distinct codes. A single statement that inserted
                 // nothing would have to report "something was missing".
                 if (!ctx?.environment_id) {
                     throw new HttpError(400, "environment_not_found", envKey
                         ? `This project has no environment called "${envKey}".`
                         : "This project has no default environment.");
                 }
-                // The active round: highest number, not closed. D2 — a thread belongs
+                // The active round: highest number, not closed. — a thread belongs
                 // to whichever round was active when it was created, and never moves.
                 if (!ctx.round_id)
                     throw new HttpError(409, "no_active_round", "This project has no open round.");
@@ -639,7 +642,7 @@ trackers = async () => []) {
           ),
           -- The author's row: seen now, and the counters the assignee pool
           -- reads (05 section 3.4, section 6.4b -- "everyone who has
-          -- commented" is thread_count > 0 OR comment_count > 0). Until D90
+          -- commented" is thread_count > 0 OR comment_count > 0). Until
           -- nothing moved thread_count at all, so a client whose only act
           -- was leaving a pin was invisible to the pool. ONE update: two
           -- data-modifying CTEs touching the same row in one statement is
@@ -695,7 +698,7 @@ trackers = async () => []) {
                         pageUrl: body.context?.url ?? "",
                     }, randomUUID());
                 }
-                // D95: a site whose tracker makes an issue on every new thread. Same
+                // A site whose tracker makes an issue on every new thread. Same
                 // transaction as the thread, keyed on the thread, so a retried POST
                 // cannot make a second issue.
                 for (const link of await trackers(p.org_id, p.id)) {
@@ -720,7 +723,7 @@ trackers = async () => []) {
             if (e instanceof HttpError)
                 return fail(c, e.status, e.code, e.message);
             /**
-             * A RETRY IS NOT AN ERROR — 05 §11's idempotency, by natural key.
+             * A RETRY IS NOT AN ERROR — the idempotency, by natural key.
              *
              * A double-tapped Send, or a reviewer on a train whose request landed
              * while their connection dropped before the response did, sends the same
@@ -731,7 +734,7 @@ trackers = async () => []) {
              * connection is the moment they try again, or give up and stop using it.
              *
              * The id makes this decidable with no header and no client change: the
-             * widget already mints it (§6.2), so a second POST carrying an id we
+             * widget already mints it, so a second POST carrying an id we
              * already hold IS the same request. Returning what the first one created
              * is the whole of the fix.
              *
@@ -787,7 +790,7 @@ trackers = async () => []) {
         }
     });
     /**
-     * 05 §6.4 — status changes, endpoint 9, marked **W/D** like the list.
+     * Status changes, endpoint 9, marked **W/D** like the list.
      *
      * IT SHIPPED WITH NO AUTHENTICATION CHECK AT ALL. Not a weak one — none: the
      * handler read the uid, read the body and wrote. `bearerAuth` was mounted on
@@ -798,15 +801,15 @@ trackers = async () => []) {
      *
      * Two credentials are legitimate here and they are checked separately: an
      * OWNER of this project's org, and a reviewer session carrying
-     * `thread:resolve` (§4.8's matrix — it is in the default link grant, because
-     * a client marking their own snag done is the loop D4 is built around).
+     * `thread:resolve` (the matrix — it is in the default link grant, because
+     * a client marking their own snag done is the loop the decision is built around).
      */
     /**
-     * 05 §6.4 endpoint 8 — one thread — and D93's brief: the same row as
+     * Endpoint 8 — one thread — and the brief: the same row as
      * `text/markdown` when the id ends in `.md`, for curl, an agent's shell or
      * a ticket body. The privacy rule is the list's: a private thread is absent
      * for a non-owner, which reads as "no such thread" rather than confirming
-     * one exists (§6.4a), and team-only replies stay out of a client's copy.
+     * one exists, and team-only replies stay out of a client's copy.
      */
     app.get("/api/v1/projects/:uid/threads/:id", async (c) => {
         const p = await project(c.req.param("uid"));
@@ -877,10 +880,10 @@ trackers = async () => []) {
         const mcp = c.get("mcp");
         const asOwner = !!owner && owner.orgId === p.org_id;
         /**
-         * `mark_ready` (07 §8.3) lands here — and this is the whole of an agent's
+         * `mark_ready` lands here — and this is the whole of an agent's
          * write surface on a thread, `threads:write`.
          *
-         * §8.6 mitigation 4: *"an agent can propose, never dispose"*. There is
+         * *"an agent can propose, never dispose"*. There is
          * deliberately no tool that resolves a thread, and the refusal below is
          * where that is actually true rather than merely absent from a tool list:
          * an agent PATCHing `status: 'resolved'` on this route is refused even
@@ -897,20 +900,20 @@ trackers = async () => []) {
             return fail(c, 403, "forbidden", "This review link does not allow changing status.");
         }
         const body = (await c.req.json().catch(() => null));
-        // D2: a thread belongs to exactly one round and NEVER moves. Refused
+        // A thread belongs to exactly one round and NEVER moves. Refused
         // explicitly rather than ignored, because a caller that sends `round` and
         // gets a 200 will believe it moved — and the whole model rests on the fact
-        // that it did not. §6.9's `field_not_permitted` is the registered code.
+        // that it did not. The `field_not_permitted` is the registered code.
         for (const field of ["round", "roundId", "roundNumber"]) {
             if (body && field in body) {
                 return fail(c, 422, "field_not_permitted", "A comment stays in the round it was left in. Rounds are periods of time, not folders.", { field });
             }
         }
         /**
-         * `private` — 05 §6.4, and the write that makes `deleted[]` mean something.
+         * `private`, and the write that makes `deleted[]` mean something.
          *
          * Studio-only, like the thread-level field it is: an owner always may, a
-         * reviewer session needs the link permission that names it. §6.4 is
+         * reviewer session needs the link permission that names it. The design is
          * explicit that this is `403 field_not_permitted` with `details.field`
          * rather than a silently ignored field, because a caller who sends
          * `private: true` and gets a 200 will believe the thread is private.
@@ -922,14 +925,14 @@ trackers = async () => []) {
             });
         }
         if (wantsPrivate !== undefined && asAgent && !asOwner) {
-            // §8.2: an agent write is never laundered into a trust tier it did not
+            // An agent write is never laundered into a trust tier it did not
             // earn, and team-only is the studio's register.
             return fail(c, 403, "field_not_permitted", "An agent cannot make a thread team-only.", {
                 field: "private",
             });
         }
         /**
-         * `assignee` — 05 §6.4b, D90. A reviewer id from the pool, or null to
+         * `assignee`. A reviewer id from the pool, or null to
          * un-assign. Same register as `private`: the studio's own routing of
          * work, so an owner always may, a reviewer session needs the permission
          * that names it, and a refusal is `403 field_not_permitted` with
@@ -951,7 +954,7 @@ trackers = async () => []) {
                 }
             }
             if (asAgent && !asOwner) {
-                // 07 §8.6 mitigation 4 again: an agent proposes, never disposes —
+                // Again: an agent proposes, never disposes
                 // and handing a thread to a person is disposing of it.
                 return fail(c, 403, "field_not_permitted", "An agent cannot assign a comment to someone.", {
                     field: "assignee",
@@ -973,7 +976,7 @@ trackers = async () => []) {
             return fail(c, 400, "validation_failed", "status must be one of open, progress, review, resolved.");
         }
         /**
-         * F-26's expected version — 01 §1221, AC-1-11's "no silent overwrite".
+         * F-26's expected version, the "no silent overwrite".
          *
          * `threads.version` has been incremented on every write since 0001 and
          * READ by nothing: the column existed, the guarantee did not. Two studio
@@ -984,7 +987,7 @@ trackers = async () => []) {
          * OPTIONAL, deliberately. A caller that sends no `version` is saying "I am
          * not editing a copy I read earlier" — the CLI, an agent acting on a fresh
          * read, a curl. Making it mandatory would break every existing caller to
-         * protect a case they are not in, and 05 §11.1's additive rule forbids
+         * protect a case they are not in, and the additive rule forbids
          * that. The dashboard and the widget send it because they ARE editing a
          * copy they read earlier, which is exactly the population F-26 is about.
          */
@@ -1001,7 +1004,7 @@ trackers = async () => []) {
                 return fail(c, 403, "forbidden", "An agent may mark a snag ready for review, but not resolve it. " +
                     "Whoever reported it decides when it is fixed — tell your user it is ready.");
             }
-            // 07 §8.4's stop signal, spent before the write rather than after it.
+            // The stop signal, spent before the write rather than after it.
             const spent = await checkWriteBudget(sql, mcp.tokenId);
             if (spent !== null)
                 return budgetExhausted(c);
@@ -1027,6 +1030,20 @@ trackers = async () => []) {
         let conflict;
         // Set by the transaction when the candidate assignee is not in the pool.
         let badAssignee = false;
+        // Read by the transaction when an assignee is being set.
+        let previousAssignee = null;
+        /**
+         * The person pressing the button, as the assignment mail needs them:
+         * never mailed about handing a snag to themselves, and — when they ARE
+         * the assignee and move its status — the mail about it is dropped,
+         * because they have plainly seen it. An agent is nobody here: it cannot
+         * assign, and its `mark_ready` is not the assignee looking.
+         */
+        const actor = asOwner
+            ? { userId: owner.userId, email: owner.email }
+            : session && !asAgent
+                ? { reviewerId: session.sub }
+                : null;
         const [row] = await inOrg(sql, p.org_id, async (tx) => {
             /**
              * F-26's check, INSIDE the transaction and holding the row.
@@ -1053,7 +1070,7 @@ trackers = async () => []) {
                 }
             }
             /**
-             * The candidate must be IN THE POOL — §6.4b's predicate, shared with
+             * The candidate must be IN THE POOL — the predicate, shared with
              * the pool route — and in THIS project. Blocked and erased reviewers
              * keep the assignments they have but take no new ones; a guest who
              * never wrote is not assignable; a reviewer id from another project is
@@ -1068,9 +1085,18 @@ trackers = async () => []) {
                     badAssignee = true;
                     return [];
                 }
+                // Who held it BEFORE, under the row lock the UPDATE below would take
+                // anyway: re-sending the assignee a thread already has is not a new
+                // assignment, and must not be a second mail.
+                const [was] = await tx `
+          SELECT assignee_id FROM threads
+           WHERE id = ${threadRow}::uuid AND project_id = ${p.id}::uuid
+           FOR UPDATE
+        `;
+                previousAssignee = was?.assignee_id ?? null;
             }
             /**
-             * §6.4 consequence TWO of three, and it runs before the CTE rather than
+             * Consequence TWO of three, and it runs before the CTE rather than
              * inside it.
              *
              * *"every comment on a thread becoming private is set `private = true` in
@@ -1159,7 +1185,7 @@ trackers = async () => []) {
       `;
             /**
              * `thread.resolved` — B2's second topic, queued in the SAME transaction
-             * as the status change (07 §2.5), so a resolve that commits without its
+             * as the status change, so a resolve that commits without its
              * notification is impossible and a notification about a resolve that
              * rolled back cannot exist.
              *
@@ -1186,7 +1212,35 @@ trackers = async () => []) {
                     pageUrl: String(t["context"]?.["url"] ?? ""),
                 });
             }
-            // D95: our status is canonical, the tracker's follows — queued here, in
+            /**
+             * "this snag is yours now", an hour from now and only if it is
+             * still true then (`mail/assigned.ts`). Queued here, in the transaction
+             * that assigned it, like every outbox row; only when it is a NEW holder
+             * and only when mail is configured at all (off and say so,
+             * rather than rows that arrive in a burst the day somebody sets it up).
+             */
+            if (assigneeRow && assigneeRow !== previousAssignee && actor && updated?.[0] && (await notifications())) {
+                const t = updated[0];
+                const actorName = asOwner
+                    ? owner.name || owner.email
+                    : ((await tx `SELECT name FROM reviewers WHERE id = ${session.sub}::uuid`)[0]?.name ?? "Someone");
+                await queueAssignedNotice(tx, {
+                    orgId: p.org_id,
+                    projectId: p.id,
+                    threadId: threadRow,
+                    threadKey: String(t["key"] ?? ""),
+                    version: Number(t["version"] ?? 0),
+                    assigneeId: assigneeRow,
+                    actor,
+                    actorName,
+                    ...(assignDelayMs !== undefined ? { delayMs: assignDelayMs } : {}),
+                });
+            }
+            // …and the assignee moving the status themselves has seen it.
+            if (status !== undefined && actor && updated?.[0]) {
+                await dropAssignedBy(tx, threadRow, actor);
+            }
+            // Our status is canonical, the tracker's follows — queued here, in
             // the transaction that moved it, keyed on the version so every change
             // is one row. The worker maps by state type: resolved closes as
             // completed, anything else reopens; a thread with no issue is skipped.
@@ -1207,7 +1261,7 @@ trackers = async () => []) {
         });
         /**
          * F-26, on the wire. 409 and not 412: `If-Match` semantics would make this
-         * a header concern, and 01 §1221 describes a product event ("someone else
+         * a header concern, and the design describes a product event ("someone else
          * updated this while you were typing") that the client renders with **Post
          * anyway** and **See what changed** — a conflict, not a failed
          * precondition. `currentVersion` rides along so the refetch has something
@@ -1225,7 +1279,7 @@ trackers = async () => []) {
         if (!row)
             return fail(c, 404, "thread_not_found", "No such thread in this project.");
         /**
-         * 07 §8.6 mitigation 8: every agent write lands in `events` with the
+         * Every agent write lands in `events` with the
          * reviewer id and the token id.
          *
          * A SECOND transaction, and this is the one place that is not ideal: the
@@ -1262,12 +1316,12 @@ trackers = async () => []) {
      * 05 endpoint 10 — deleting a whole thread, project-scoped like the PATCH
      * above. The studio, any thread; a reviewer, their own.
      *
-     * §4.8's matrix gives a reviewer "own only", behind the link permission
+     * The matrix gives a reviewer "own only", behind the link permission
      * `thread:delete:own` — on by default since 0.1.14 for guests and new
      * links, because the widget offered Delete on a reviewer's own snag and
      * this route refused it. "Own" is narrower than "opened": every live
      * comment in the thread must be theirs, so nobody's reply goes with it.
-     * An agent is still refused (§8.6 mitigation 4 — an agent proposes, never
+     * An agent is still refused (an agent proposes, never
      * disposes, and deleting is the most disposing act there is).
      *
      * ── SOFT, LIKE A SITE ──
@@ -1279,7 +1333,7 @@ trackers = async () => []) {
      * column, and an operator who deletes the wrong thread has a row to
      * restore. `version` and `updated_at` move with it so a `?since=` poll —
      * every other open dashboard, every reviewer's widget — gets the id in
-     * `deleted[]` and drops its copy (§6.3), rather than showing a thread that
+     * `deleted[]` and drops its copy, rather than showing a thread that
      * is gone until somebody reloads.
      *
      * ── THE COMMENTS ARE LEFT ALONE, DELIBERATELY ──
@@ -1289,7 +1343,7 @@ trackers = async () => []) {
      * thread's `deleted_at`; the two comment routes that address a comment by
      * its own id (commentEdit.ts) answer 404 once its thread is deleted. So
      * tombstoning them would hide nothing more today, and it would make the
-     * delete irreversible — §3.11's tombstone NULLs the body, and a restored
+     * delete irreversible — the tombstone NULLs the body, and a restored
      * thread with every word gone is not a restore. The counters stay as they
      * are for the same reason.
      *
@@ -1307,7 +1361,7 @@ trackers = async () => []) {
      *     with and never looks back at the thread. A tracker row would be
      *     dropped by its worker anyway ("the thread is gone"); dropping it here
      *     says so in one place. Rows already in flight are left to finish.
-     *   · Linked issues in GitHub, Linear, Jira or Slack are NOT touched. 07's
+     *   · Linked issues in GitHub, Linear, Jira or Slack are NOT touched. The
      *     `thread.deleted` event is not built, and closing a developer's issue
      *     because a comment was moderated is not obviously what anyone wants.
      *     An inbound webhook for that issue finds no thread and is ignored.
@@ -1344,7 +1398,7 @@ trackers = async () => []) {
                 if (!session.perm.includes("thread:delete:own")) {
                     return fail(c, 403, "forbidden", "Your review link does not allow deleting comments.");
                 }
-                // A studio owner or admin signed in from the widget (D122) deletes
+                // A studio owner or admin signed in from the widget deletes
                 // any thread, as in the dashboard.
                 const moderator = await inOrg(sql, p.org_id, (tx) => isStudioModerator(tx, p.org_id, session.sub));
                 const [t] = moderator ? [{ all_mine: true, any: true }] : await inOrg(sql, p.org_id, (tx) => tx `
@@ -1366,7 +1420,7 @@ trackers = async () => []) {
             }
         }
         else {
-            // §4.8's matrix: member, admin and owner may; a viewer may not. Nobody
+            // The matrix: member, admin and owner may; a viewer may not. Nobody
             // can be GIVEN a viewer seat yet (members.ts wires owner and admin only),
             // so this is the rule written down where it applies, before the day the
             // seat exists and every route has to be audited for it.
@@ -1397,7 +1451,7 @@ trackers = async () => []) {
         `;
                 return !!was;
             }
-            // The thread's own pictures and any bound to its comments: FOLDBACK
+            // The thread's own pictures and any bound to its comments:
             // section A6 hangs an attachment off exactly one of the two.
             await tx `
         UPDATE attachments SET deleted_at = now()
@@ -1437,7 +1491,7 @@ class HttpError extends Error {
         this.code = code;
     }
 }
-/** Rows → 00 §5's `Thread`. The shape the widget already renders, unchanged. */
+/** Rows → the `Thread`. The shape the widget already renders, unchanged. */
 function shape(r) {
     return {
         id: wireId_(r.id, ID_PREFIX.thread),
@@ -1473,7 +1527,7 @@ function shape(r) {
                 isTeam: !!r.assignee_is_team,
             }
             : null,
-        // D95: where this thread lives elsewhere — the GitHub issue, later the
+        // Where this thread lives elsewhere — the GitHub issue, later the
         // Linear and Jira ones. Always an array, so a merge can clear it.
         refs: r.refs ?? [],
         createdAt: new Date(r.created_at).toISOString(),