your-attention 0.1.0 → 0.1.1

package/dist/src/core/inbox.js

@@ -0,0 +1,2463 @@
+// The inbox: every change to cards, answers, presence and tokens goes through
+// this one object. Storage calls are synchronous, so each change completes
+// before the next starts. Every change is written to storage before a method
+// returns, and memory holds only the open connections.
+import { newSecret, pairingCode, randomId, sha256 } from './crypto.js';
+import { parse, test as testRule,            } from './expr.js';
+import { HOOK_VERSION, HOOKS, deliverWebhook, isHook, postSigned,                                                                                       } from './hooks.js';
+import { isSealed, sealedFields, secretInputs, withoutSealed } from './sealed.js';
+import { MAX_DIAGRAMS, bodyProblemsMessage, checkDiagrams, diagramMessage, findDiagrams, requireChecked,                                         } from './diagrams.js';
+import { BUILTIN_WIDGETS, distinctWidgets, expandWidgets, fill, respond,                   } from './widgets.js';
+import { PinLock } from './pin.js';
+import { MemoryBlobs,                              } from './storage.js';
+import { cleanTags, SummarizedStorage,                                                        } from './summary.js';
+import { Usage } from './telemetry.js';
+import { MAX_TAGS } from './types.js';
+             
+                                                                                                                                                                                                                                                      
+                                                                                                                                                           
+                    
+
+export class InboxError extends Error {
+           status        ;
+  constructor(status        , message        ) {
+    super(message);
+    this.status = status;
+  }
+}
+
+                         
+                
+             
+ 
+
+/** Types an approved sentence into a herdr pane as the person's message, and names a pane's agent and tab. */
+                                 
+                                                                                                
+                                                  
+                                                  
+ 
+
+/** A herdr pane id, such as w6P:p2. It never starts with a dash, so herdr cannot read it as a flag. */
+export const PANE_ID = /^w[A-Za-z0-9]+:p[A-Za-z0-9]+$/;
+export const MAX_APPROVALS = 5;
+export const MAX_APPROVAL_CHARS = 1000;
+const MAX_APPROVAL_LABEL_CHARS = 120;
+
+                               
+                         
+                                        
+                                         
+                                             
+                                                                                            
+                                     
+                                                                                                                         
+                                          
+                                                                                                      
+                                                       
+                                                                                                        
+                                                                      
+                                                                                                                        
+                                                                                                                                   
+                         
+                                                                                                                
+                                                                                                             
+                                      
+                                                                                       
+                          
+                                                                                                                               
+                                         
+                                                                                  
+                                   
+ 
+
+export const SYSTEM_AGENT = 'system';
+/** The inbox itself, as the caller of the system cards it posts. */
+const INBOX         = { token: '', role: 'owner' };
+const PAIRING_TTL_MS = 10 * 60 * 1000;
+const MAX_PENDING_PAIRINGS = 5;
+const CLOSE_KINDS = new Set           (['retracted', 'self-answered', 'answered-in-terminal', 'resolved']);
+const HISTORY_LIMIT = 20;
+/** How long an agent stays online after its last connection closes, so a reconnect or the next long-poll keeps it online. */
+export const PRESENCE_GRACE_MS = 2000;
+/** How long the inbox remembers a message id, to apply a message once however many links bring it. */
+export const MESSAGE_MEMORY_MS = 24 * 60 * 60 * 1000;
+/** How long a message id stays reserved while its first copy is applied. */
+export const MESSAGE_RESERVATION_MS = 30_000;
+/** An open card whose agent has been offline this long is orphaned. */
+export const ORPHAN_MS = 60 * 60 * 1000;
+export const DEFAULT_PRIORITIES                  = [
+  { id: 'now', label: 'Decide now', definition: 'The agent cannot go on without the answer.', color: '#e5484d' },
+  { id: 'soon', label: 'Decide soon', definition: 'The agent needs the answer before it finishes.', color: '#c9a100' },
+  { id: 'later', label: 'Can wait', definition: 'The answer refines the work later.' },
+];
+/** The version of `DEFAULT_GUIDANCE`. It moves whenever that text changes, so a client reads the words it has not seen. */
+export const DEFAULT_GUIDANCE_VERSION = 5;
+export const DEFAULT_GUIDANCE = [
+  'On a card, "you" is the person who reads it. Write about yourself in the third person, as "this agent" or the name in `from`, never "I" or "we", so the person always knows who acts.',
+  'Write each card so the person can answer it without opening the session.',
+  'State the goal, the options you weighed, the evidence, and your recommendation.',
+  'Shape the answer options to the question. The person may leave any field empty.',
+  'Put each question next to the field that answers it. One question uses options. Two or more questions use questions, each with its own text and options, and never one options list after all the text. The page draws each question as its own section with a comment field. A question that needs a table or a widget beside it uses a form in the body.',
+  'Explain each option inside it, in its description: what this agent does if the person picks it, such as "This agent reruns the deploy." Never list the options with their explanations in the text.',
+  'Mark the option this agent recommends with recommended: true, and put only the reasons in the recommendation. The page shows them inside that option, so the person reads the pick once.',
+  'Never list questions in the text with the answers at the bottom. Write what you will check yourself as statements, not questions.',
+  'The page adds a comment box, Send answer and Skip at the bottom of every card. Add no general comment box or send button of your own.',
+  'When a card body or HTML asks several questions, give each one its own short comment field beside it, so the person can say why for that question alone.',
+  'When a card is about another agent, link its session so the person can go there in one click: [label](https://herdr.invalid/v1/pane/<pane id>), from `herdr agent list`. Link another card with [[card-id]].',
+  'Put text the person should copy, such as a command or an approval sentence, in inline code or a fenced block, and the page lets the person copy it with a click.',
+  'When an action needs the person\'s own words in a session, post the sentence as an approval on the card instead of asking the person to type it there.',
+  'A card title is one line of plain text: no Markdown and no links. Name the thing there, as "PR #93 — an empty list no longer looks like a success". Put the link in `text`, or in a field label in the body: both read inline Markdown.',
+  'To follow up on a card, post a new card with `follows: "<card id>"`. The inbox links the two cards both ways, and there is no reply to a card.',
+  'Never ask for a secret, such as an API key, in a text field. Place the secret widget in the card body, `key = widget secret {"name": "API_KEY"}`, and card_post seals it for this session.',
+  'Search earlier answers before you post, and never ask the same thing twice.',
+].join('\n');
+export const MAX_ATTACHMENTS = 10;
+export const MAX_ATTACHMENT_BYTES = 8 * 1024 * 1024;
+export const MAX_ANSWER_IMAGES = 10;
+/** How many card ids `unread` names before it only counts. A command line has a length. */
+export const UNREAD_ID_LIMIT = 20;
+// The images of one answer share a byte budget, because the route reads a body of 16 MB and base64 costs four thirds:
+// ten images of 8 MB each would make a body no route accepts.
+export const MAX_ANSWER_IMAGE_BYTES = 10 * 1024 * 1024;
+const ANSWER_IMAGE_TYPES = new Set(['image/png', 'image/jpeg', 'image/gif', 'image/webp']);
+/** Each stored file counts as at least this many bytes toward the upload limit, so tiny files cannot make unlimited blob writes. */
+export const MIN_FILE_CHARGE = 64 * 1024;
+/** The largest card, as stored, without its files. */
+export const MAX_CARD_BYTES = 256 * 1024;
+export const MAX_SOURCE_BYTES = 64 * 1024;
+export const MAX_FROM_CHARS = 80;
+export const MAX_VERSIONS = 50;
+export const MAX_WEBHOOKS = 5;
+export const MAX_SUBSCRIPTIONS = 20;
+const MAX_WEBHOOK_HEADERS = 10;
+/** How long one call to an answer webhook may take. */
+export const ANSWER_WEBHOOK_TIMEOUT_MS = 10_000;
+/** A call that started this long ago and never finished, such as one a crash cut off, goes again. */
+const DELIVERY_LEASE_MS = ANSWER_WEBHOOK_TIMEOUT_MS + 5_000;
+/** The first retry of an answer webhook waits this long, and each later one twice as long, up to an hour. */
+export const RETRY_FIRST_MS = 5_000;
+const RETRY_MAX_MS = 60 * 60 * 1000;
+/** After this long the inbox stops calling a webhook for one answer. The answer still waits for the agent stream. */
+export const RETRY_GIVE_UP_MS = 24 * 60 * 60 * 1000;
+/** Headers the inbox sets on each webhook call itself, or that the platform sets. */
+const RESERVED_HEADER = /^(content-type|content-length|host|transfer-encoding|connection|x-your-attention-.*)$/i;
+/** The pinned tag values one inbox keeps. A tag key or value is cut to 100 characters, as in the card's summary. */
+export const MAX_PINS = 20;
+export const MAX_TAG_CHARS = 100;
+/** How long a sign-in code from the phone dialog works. */
+export const SIGN_IN_CODE_TTL_MS = 5 * 60 * 1000;
+const MAX_SIGN_IN_CODES = 5;
+/** The most tag keys GET /v1/guidance lists, and the most values it lists for each key, so a busy inbox stays short. */
+export const MAX_TAG_KEYS = 20;
+export const MAX_TAG_VALUES = 15;
+/** How long a closed pairing request and its card stay before the sweep deletes them. */
+export const PAIRING_KEEP_MS = 24 * 60 * 60 * 1000;
+/** How long a cleared card, or a card nobody answered, stays after its last change before the purge deletes it. */
+export const PURGE_AFTER_MS = 30 * 24 * 60 * 60 * 1000;
+/** Where the purge keeps the files a delete could not remove, so a laptop retries them on its next pass. */
+const PENDING_FILE_DELETES = 'pending-file-deletes';
+/** The most cards one purge pass deletes, so no alarm does unbounded work. */
+export const PURGE_BATCH = 100;
+/** The share of the storage limit the purge keeps free, by deleting the oldest of those cards sooner. */
+export const STORAGE_HEADROOM = 0.2;
+/** How long the sweep keeps the presence row of an agent after it went offline. */
+export const PRESENCE_KEEP_MS = 30 * 24 * 60 * 60 * 1000;
+
+const PATCH_FIELDS = new Set(['title', 'text', 'body', 'html', 'recommendation']);
+const DELIVERIES = new Set          (['default', 'steer', 'followUp', 'force']);
+
+/** A card's state follows from its closure and its answer. */
+export function cardState(card                                               , answer                                                                )            {
+  // An answer saved after the agent closed the card still goes to the agent.
+  if (card.closed && !(answer && answer.savedAt > card.closed.at)) return 'closed';
+  if (!answer && card.triage?.state === 'pending') return 'in-triage';
+  if (!answer && card.triage?.state === 'held') return 'held';
+  if (!answer) return 'open';
+  if (answer.readAt) return 'read';
+  if (answer.deliveredAt) return 'delivered';
+  return 'answered';
+}
+
+/** The agent an answer goes to, or null for none. A guidance card closes as the person answers it, and its answer
+ * still goes to the agent that proposed the text. */
+function recipient(card      , answer        )                {
+  if (card.kind === 'system' && card.broadcast) return card.broadcast.from && card.token ? card.broadcast.from : null;
+  return card.deliver === 'stream' && cardState(card, answer) !== 'closed' ? card.agent : null;
+}
+
+/** One answer waiting for its webhook call, keyed by subscription and card, so a new answer replaces one still waiting. */
+                      
+              
+              
+               
+                                                      
+                  
+                   
+                  
+                                                                            
+                 
+                                                                         
+                 
+ 
+
+/** The id of an answer: the same on every webhook call that carries it, and new when the person changes the answer. */
+export function answerId(card        , savedAt        )         {
+  return `${card}@${savedAt}`;
+}
+
+                                          
+                                        
+
+/** A token's default tags, by agent id, as the inbox stores them under one `meta` key. */
+                         
+                
+                                                     
+             
+ 
+
+/**
+ * The tags a card stores: the agent's default tags under the card's own. A key on the card wins, and a key the card
+ * passes with an empty string drops that default for that card alone. Defaults past the tag limit lose, so the card's
+ * own tags always fit. Returns the merged tags, and the keys the card took from the defaults.
+ */
+export function mergeDefaultTags(defaults                        , own                                    )                                                                    {
+  const tags                         = {};
+  const inherited           = [];
+  for (const [k, value] of Object.entries(defaults)) {
+    // A plain object answers `toString` for every key, so the card's own tags are read by their own key only.
+    const mine = own !== undefined && Object.hasOwn(own, k) ? own[k] : undefined;
+    if (mine === '') continue;
+    if (mine !== undefined) { tags[k] = String(mine); continue; }
+    tags[k] = value;
+    inherited.push(k);
+  }
+  for (const [k, value] of Object.entries(own ?? {})) {
+    // `in` would see `constructor` and `toString` on any object, so a tag by those names would be dropped.
+    if (Object.hasOwn(defaults, k) || value === '') continue;
+    tags[k] = String(value);
+  }
+  // The card's own tags come last in insertion order, so the defaults give way at the limit, and a card that names
+  // more than the limit is refused rather than cut.
+  while (Object.keys(tags).length > MAX_TAGS && inherited.length) delete tags[inherited.pop()          ];
+  if (Object.keys(tags).length > MAX_TAGS) throw new InboxError(400, `a card takes at most ${MAX_TAGS} tags, with its agent's defaults`);
+  return { tags: Object.keys(tags).length ? tags : undefined, inherited };
+}
+
+export class Inbox {
+                   store         ;
+                   blobs           ;
+                   uploadLimit                    ;
+                   storageLimit                    ;
+                   readsPerDay                    ;
+                   checkDiagram                          ;
+                   checkBody                                          ;
+                   fallbackBody                                                      ;
+                   clientChecks         ;
+                   shownCardLimit                    ;
+                   now              ;
+                   approvalSender                            ;
+                   agents = new Map                        ();
+                   instances = new WeakMap                   ();
+                   pages = new Set          ();
+  /** The pages that need an unlock token, with the one they opened with and how to close them. */
+                   guarded = new Map                                                             ();
+  /** What each open page reports about the person, by page id. */
+                   viewers = new Map                                                                             ();
+                   extensions = new Map                                                                                      ();
+  /** Webhook deliveries still running, so tests and shutdown can wait for them. */
+           deliveries = new Set                  ();
+                   fetcher              ;
+  /** The usage counts the platform sends once a day, when the person left them on. */
+           usage       ;
+  /** The PIN a browser tab types before it acts as the owner. */
+           pin         ;
+
+  /** `keepPresence` is for a platform whose sockets outlive the object, such as a Durable Object that wakes from hibernation.
+   * `uploadLimitBytes` caps the bytes of every file this inbox ever stores. Deleting a file gives none back.
+   * `storageLimitBytes` caps what the inbox keeps in its storage now. A full inbox takes only writes that free space.
+   * `attachmentReadsPerDay` caps how many files the inbox serves in a day. */
+  constructor(store         , now               = Date.now, blobs            = new MemoryBlobs(), opts               = {}) {
+    // Each write to a card or an answer also writes the card's summary, which GET /v1/state reads.
+    this.store = new SummarizedStorage(store);
+    this.now = now;
+    this.blobs = blobs;
+    this.uploadLimit = opts.uploadLimitBytes;
+    this.storageLimit = opts.storageLimitBytes;
+    this.readsPerDay = opts.attachmentReadsPerDay;
+    this.checkDiagram = opts.checkDiagram;
+    this.checkBody = opts.checkBody;
+    this.fallbackBody = opts.fallbackBody;
+    this.clientChecks = opts.clientChecks === true;
+    this.shownCardLimit = opts.shownCardLimit;
+    this.approvalSender = opts.approvals;
+    // Workers refuse a fetch called as a method of another object, so the default calls it bare.
+    this.fetcher = opts.fetch ?? ((input, init) => fetch(input, init));
+    this.usage = new Usage(store, now, { alwaysOn: opts.usageAlwaysOn });
+    this.pin = new PinLock(store, now, opts.pinIterations);
+    // A page that opened before the PIN changed must unlock again.
+    this.pin.onChange(() => this.closeLockedPages());
+    markDialogCards(this.store);
+    // On a laptop, connections do not survive a restart, so nobody is online at start.
+    if (!opts.keepPresence) {
+      for (const p of store.list          ('presence')) {
+        if (p.online) store.put('presence', p.agent, { ...p, online: false });
+      }
+    }
+  }
+
+  /** Store a token whose secret the deployment chose, such as an owner token set as a Worker secret. */
+  async adoptToken(secret        , name        , role      )                 {
+    const id = secret.split('.')[0] ?? '';
+    if (!/^[0-9a-f]{12}$/.test(id) || !/^[0-9a-f]{12}\.[0-9a-f]{64}$/.test(secret)) throw new InboxError(400, 'a token is 12 hex digits, a dot, and 64 hex digits');
+    const token        = { id, hash: await sha256(secret), name, role, createdAt: this.now() };
+    this.store.put('tokens', id, token);
+    return token;
+  }
+
+  /** When the platform alarm must next call sweep(), or undefined when nothing waits. */
+  nextDeadline()                     {
+    const times           = [];
+    for (const p of this.store.list          ('presence')) {
+      if (p.online && p.leftAt !== undefined) times.push(p.leftAt + PRESENCE_GRACE_MS);
+      else if (!p.online) times.push((p.leftAt ?? p.lastSeen) + PRESENCE_KEEP_MS);
+    }
+    for (const p of this.store.list         ('pairings')) {
+      times.push(p.status === 'pending' || p.secret ? p.createdAt + PAIRING_TTL_MS : p.createdAt + PAIRING_KEEP_MS);
+    }
+    for (const c of this.store.list      ('cards')) {
+      if (c.triage?.state === 'pending' && c.triage.deadline) times.push(c.triage.deadline);
+      if (c.expiresAt && !c.closed && !this.store.get('answers', c.id)) times.push(c.expiresAt);
+    }
+    const oldest = this.purgeQueue()[0];
+    if (oldest) times.push(this.needsRoom() ? this.now() : oldest.since + PURGE_AFTER_MS);
+    for (const d of this.store.list            ('outbox')) times.push(d.nextAt);
+    return times.length ? Math.min(...times) : undefined;
+  }
+
+  // ---- tokens and pairing ----
+
+  /** Create a token and return its secret. The secret is shown once. */
+  async createToken(name        , role      , opts                          = {})                                            {
+    const id = randomId(6);
+    const secret = newSecret(id);
+    const token        = { id, hash: await sha256(secret), name, role, createdAt: this.now(), ...(opts.pinExempt && role === 'owner' ? { pinExempt: true } : {}) };
+    this.store.put('tokens', id, token);
+    return { token, secret };
+  }
+
+  async authenticate(secret                           )                             {
+    if (!secret) return undefined;
+    const id = secret.split('.')[0] ?? '';
+    const token = this.store.get       ('tokens', id);
+    if (!token) return undefined;
+    return (await sha256(secret)) === token.hash ? token : undefined;
+  }
+
+  listTokens()                        {
+    return this.store.list       ('tokens').map(({ hash: _hash, ...t }) => t);
+  }
+
+  /** Whether a token, by id, still exists: nobody signed it out or revoked it. */
+  hasToken(id        )          {
+    return !!this.store.get       ('tokens', id);
+  }
+
+  revokeToken(id        )       {
+    if (!this.store.get('tokens', id)) throw new InboxError(404, 'unknown token');
+    this.store.delete('tokens', id);
+    this.pin.dropUnlocks(id);
+    this.removeSubscriptions((s) => s.token === id, 'The token that asked for this webhook was revoked.');
+  }
+
+  /** Let an owner token act without the PIN, such as the laptop's owner-token file, which only this machine's user reads. */
+  exemptFromPin(id        )       {
+    const t = this.store.get       ('tokens', id);
+    if (t && t.role === 'owner' && !t.pinExempt) this.store.put       ('tokens', id, { ...t, pinExempt: true });
+  }
+
+  /** Whether a caller must unlock with the PIN, and whether it has. Every cookie, and every owner token that can
+   * travel as a link, needs the PIN once the inbox has one. `unlock` is the id of the unlock token the caller sent. */
+  async pinGate(token       , viaCookie         , secret                           )                                                                {
+    const gated = token.role === 'owner' && (viaCookie || !token.pinExempt);
+    if (!gated) return { gated, locked: false };
+    const unlock = await this.pin.verifyUnlock(secret, token.id);
+    return { gated, locked: !unlock && this.pin.isSet(), unlock };
+  }
+
+          closeLockedPages()       {
+    if (!this.pin.isSet()) return;
+    for (const [send, g] of this.guarded) {
+      if (this.pin.live(g.unlock)) continue;
+      this.guarded.delete(send);
+      g.close();
+    }
+  }
+
+  /** The owner's page asks for a code that signs one more device in, such as a phone that scans it. */
+  createSignInCode(caller        )                                      {
+    if (caller.role !== 'owner') throw new InboxError(403, 'only the owner signs a device in');
+    const now = this.now();
+    const live = this.signInCodes().filter((c) => {
+      if (c.expiresAt > now) return true;
+      this.store.delete('meta', c.key);
+      return false;
+    });
+    if (live.length >= MAX_SIGN_IN_CODES) throw new InboxError(429, 'too many sign-in codes are waiting; wait five minutes');
+    const code = randomId(16);
+    const expiresAt = now + SIGN_IN_CODE_TTL_MS;
+    this.store.put('meta', `signin:${code}`, { key: `signin:${code}`, expiresAt });
+    return { code, expiresAt };
+  }
+
+  /** A device turns a sign-in code into its own owner token. Each code works once. */
+  async redeemSignInCode(code        )                              {
+    const key = `signin:${String(code ?? '')}`;
+    const found = /^signin:[0-9a-f]{32}$/.test(key) ? this.store.get                                    ('meta', key) : undefined;
+    if (found) this.store.delete('meta', key);
+    if (!found || found.expiresAt <= this.now()) throw new InboxError(401, 'this sign-in code is not valid or has expired; scan a new one');
+    const { secret } = await this.createToken(`device signed in ${new Date(this.now()).toISOString().slice(0, 16).replace('T', ' ')}`, 'owner');
+    return { secret };
+  }
+
+          signInCodes()                                       {
+    return this.store.list                                        ('meta')
+      .filter((m)                                          => typeof m?.key === 'string' && m.key.startsWith('signin:'));
+  }
+
+  /** A client asks to pair. The person sees a system card with the code. */
+  requestPairing(name        , role      )          {
+    const clean = String(name || '').trim().slice(0, 80);
+    if (!clean) throw new InboxError(400, 'name is required');
+    if (role !== 'agent' && role !== 'owner' && role !== 'extension') throw new InboxError(400, 'role must be agent, owner or extension');
+    const pending = this.store.list         ('pairings').filter((p) => p.status === 'pending');
+    if (pending.length >= MAX_PENDING_PAIRINGS) throw new InboxError(429, 'too many pairing requests are waiting');
+    const pairing          = { id: randomId(8), name: clean, role, code: pairingCode(), status: 'pending', createdAt: this.now() };
+    // The request shows as a card, so it needs room before it counts as waiting.
+    this.makeRoom(`pair-${pairing.id}`);
+    this.store.put('pairings', pairing.id, pairing);
+    this.usage.record('pairings');
+    this.postCard({ token: '', role: 'owner' }, {
+      id: `pair-${pairing.id}`,
+      agent: SYSTEM_AGENT,
+      kind: 'system',
+      title: `Pair ${role === 'owner' ? 'a front-end' : role === 'extension' ? 'an extension' : 'an agent client'}: ${clean}`,
+      text: `A client asks for ${role === 'owner' ? 'full access, as a front-end' : role === 'extension' ? 'extension access: it reads every card and can hold or return them' : 'agent access'}. It shows the code ${pairing.code}. Approve only if the client shows the same code.`,
+      options: [
+        { id: 'approve', label: 'Approve', description: `The client shows ${pairing.code}` },
+        { id: 'deny', label: 'Deny' },
+      ],
+      priority: 'now',
+      deliver: 'none',
+    });
+    return pairing;
+  }
+
+  /** The client collects its token. The secret is returned once. */
+  collectPairing(id        )                                                {
+    const p = this.store.get         ('pairings', id);
+    if (!p) throw new InboxError(404, 'unknown pairing');
+    if (p.status !== 'approved' || !p.secret) return { status: p.status };
+    const { secret, ...rest } = p;
+    this.store.put('pairings', id, rest);
+    return { status: p.status, token: secret };
+  }
+
+          async resolvePairing(card      , answer        )                {
+    const id = card.id.slice('pair-'.length);
+    const p = this.store.get         ('pairings', id);
+    if (!p || p.status !== 'pending') return;
+    const choice = [answer.values['choice']].flat()[0];
+    if (choice === 'approve') {
+      // Mark the request first, so a second answer during the await mints nothing.
+      this.store.put         ('pairings', id, { ...p, status: 'approved' });
+      // The person approved this client on an unlocked page, and its token stays on that machine.
+      const { secret } = await this.createToken(p.name, p.role, { pinExempt: p.role === 'owner' });
+      this.store.put         ('pairings', id, { ...p, status: 'approved', secret });
+      this.closeAs(card, 'resolved', `Paired ${p.name}.`);
+    } else {
+      this.store.put         ('pairings', id, { ...p, status: 'denied' });
+      this.closeAs(card, 'resolved', `Denied ${p.name}.`);
+    }
+  }
+
+  // ---- cards ----
+
+  /** `checked` holds what checkCard found for the card's diagrams. A card with a diagram it does not hold is refused.
+   * `opts.revise` marks a patch, which edits one field and keeps the tags the card already carries. */
+  postCard(caller        , input         , storedFiles              , checked                  , places                                    , opts                       = {})       {
+    if (!input || typeof input !== 'object') throw new InboxError(400, 'card must be an object');
+    const title = String(input.title ?? '').trim();
+    if (!title) throw new InboxError(400, 'title is required');
+    const agent = String(input.agent ?? '').trim();
+    if (!agent) throw new InboxError(400, 'agent is required');
+    if (agent.length > 80) throw new InboxError(400, 'agent must be at most 80 characters');
+    if (title.length > 300) throw new InboxError(400, 'title must be at most 300 characters');
+    if (agent === SYSTEM_AGENT && caller.token !== '') throw new InboxError(403, 'the system agent is reserved');
+    this.makeRoom(input.id);
+    const levels = this.priorities();
+    const priority = input.priority ?? (levels.some((l) => l.id === 'soon') ? 'soon' : levels[0]?.id ?? 'soon');
+    if (!levels.some((l) => l.id === priority)) throw new InboxError(400, `priority must be one of ${levels.map((l) => l.id).join(', ')}`);
+    if (input.rating !== undefined && !(Number.isInteger(input.rating) && input.rating >= 1 && input.rating <= 5)) throw new InboxError(400, 'rating must be 1 to 5');
+    if (!input.multiple && Array.isArray(input.options) && input.options.filter((o) => o?.recommended === true).length > 1) throw new InboxError(400, 'a card without multiple takes at most one recommended option');
+    checkQuestions(input.questions);
+    const id = input.id ? String(input.id) : randomId(8);
+    if (!/^[\w.:-]{1,80}$/.test(id)) throw new InboxError(400, 'id must be 1 to 80 letters, digits, dots, colons, dashes or underscores');
+
+    const kind = input.kind ?? 'ask';
+    if (kind === 'system' && caller.token !== '') throw new InboxError(400, 'a system card from a client asks the inbox for something: send system.type subscribe or unsubscribe');
+    // A secret card that an older inbox stored still takes revisions. A new one is refused.
+    const before = this.store.get      ('cards', id);
+    if (kind === 'secret' && before?.kind !== 'secret') throw new InboxError(400, 'the secret card kind was removed. Place the secret widget in the card body instead: key = widget secret {"name": "API_KEY"}. The card_post tool fills its public key. A session that started before this change must restart to load that tool');
+    const now = this.now();
+    if (before && before.token !== caller.token && caller.role !== 'owner') throw new InboxError(403, 'another client owns this card');
+    // A card that carries an answer or a draft already names an option by its label. An id derived now would leave
+    // that pick pointing at no option, so the card keeps its options as they are.
+    const picked = !!this.store.get        ('answers', id) || !!before?.closed?.draft;
+    // A revision keeps what herdr answered about a pane it does not change, since only herdr sets a place.
+    const approvals = this.cleanApprovals(input.approvals, kind, places)?.map((a, i) => {
+      const kept = a.place ?? (before?.approvals?.[i]?.pane === a.pane ? before.approvals[i].place : undefined);
+      return kept ? { ...a, place: kept } : a;
+    });
+    const { body, template, expanded } = this.cardBody(input);
+    // The page drops what it cannot read of a body without a word, so the agent hears it here.
+    const bodyProblems = body === undefined || !this.checkBody || this.clientChecks ? [] : this.checkBody(String(body));
+    if (bodyProblems.length) throw new InboxError(400, bodyProblemsMessage(bodyProblems));
+    const secrets = body === undefined ? [] : secretInputs(String(body));
+    let widgets = before?.widgets;
+    let responses = before?.responses;
+    if (expanded) {
+      widgets = expanded.used.length ? distinctWidgets(expanded.used) : undefined;
+      responses = expanded.responses.length ? expanded.responses : undefined;
+    }
+    let attachments = before?.attachments;
+    if (input.attachments !== undefined) {
+      if (!Array.isArray(input.attachments) || input.attachments.length > MAX_ATTACHMENTS) throw new InboxError(400, `a card takes at most ${MAX_ATTACHMENTS} attachments`);
+      attachments = input.attachments.map((f, i) => {
+        if (!f || typeof f !== 'object') throw new InboxError(400, `attachment ${index(i)}: must be an object with src`);
+        if (f.ref) {
+          // A reference names a file this inbox stored: one postCardWithFiles just stored, or one the card already has.
+          const kept = before?.attachments?.find((a) => a.id !== undefined && a.id === f.ref?.id);
+          if (kept) return kept;
+          if (f.ref.id && storedFiles?.has(f.ref.id)) return f.ref;
+          throw new InboxError(400, `attachment ${index(i)}: ref must name a file this card already has`);
+        }
+        const src = String(f.src ?? '');
+        if (!/^https:\/\//.test(src)) throw new InboxError(400, `attachment ${index(i)}: src must be an https URL, or a data: URL posted through postCardWithFiles`);
+        let last        ;
+        try { last = decodeURIComponent(new URL(src).pathname.split('/').pop() || 'file'); } catch { throw new InboxError(400, `attachment ${index(i)}: src is not a valid URL`); }
+        const name = cleanName(f.name) || last;
+        return { url: src, name, type: typeFromName(name), alt: f.alt ? String(f.alt).slice(0, 300) : undefined };
+      });
+    }
+    const history                = before
+      ? [...(before.history ?? []), { version: before.version, title: before.title, text: before.text, recommendation: before.recommendation, body: before.body, html: before.html, at: before.updatedAt }].slice(-HISTORY_LIMIT)
+      : [];
+    // Every card an agent posts inherits its default tags, under the card's own. The inbox's own system cards keep none.
+    const mergedTags = caller.token === '' || kind === 'system' || opts.revise === true
+      ? { tags: input.tags }
+      : mergeDefaultTags(this.tagValues(caller.token, agent), ownTags(input.tags));
+    const card       = {
+      id,
+      agent,
+      token: before?.token ?? caller.token,
+      kind,
+      title,
+      text: input.text,
+      recommendation: input.recommendation,
+      body,
+      options: picked ? withKeptOptionIds(input.options, before) : withOptionIds(input.options),
+      multiple: input.multiple,
+      questions: input.questions,
+      approvals,
+      dialog: input.dialog === true ? true : undefined,
+      screen: input.screen,
+      secret: kind === 'secret' ? before?.secret : undefined,
+      secrets: secrets.length ? secrets : undefined,
+      html: input.html,
+      attachments: attachments?.length ? attachments : undefined,
+      template: template ?? before?.template,
+      widgets,
+      responses,
+      priority,
+      status: input.status ?? before?.status,
+      expiresAt: input.expiresAt,
+      rating: input.rating,
+      triage: before?.triage,
+      history: history.length ? history : undefined,
+      broadcast: before?.broadcast,
+      origin: cleanOrigin(input.origin),
+      from: input.from === undefined || input.from === null ? undefined : String(input.from).trim().slice(0, MAX_FROM_CHARS) || undefined,
+      tags: mergedTags.tags,
+      follows: input.follows ?? before?.follows,
+      followedBy: before?.followedBy,
+      deliver: input.deliver ?? 'stream',
+      version: (before?.version ?? 0) + 1,
+      createdAt: before?.createdAt ?? now,
+      updatedAt: now,
+      // A card triage sent back opens again when the agent revises it.
+      closed: before?.closed?.kind === 'returned' ? undefined : before?.closed,
+      replies: before?.replies ?? [],
+    };
+    // The inbox's own system cards quote an agent's words, such as proposed guidance, and the page shows a diagram there as its source.
+    if (!this.clientChecks && (kind !== 'system' || caller.token !== '')) requireChecked(findDiagrams(card), checked);
+    // History has its own cap, and the replies of older cards are stored data the card cap leaves out.
+    const size = new TextEncoder().encode(JSON.stringify({ ...card, history: undefined, replies: undefined })).length;
+    if (size > MAX_CARD_BYTES) throw new InboxError(413, `the card is ${size} bytes, over the limit of ${MAX_CARD_BYTES}. Attach large content as a file`);
+    this.store.put('cards', id, card);
+    this.store.index(id, searchText(card));
+    if (card.version === 1 && caller.token !== '') {
+      this.usage.record('cards');
+      this.usage.saw('tokens', caller.token);
+    }
+    if (card.follows && card.follows !== id) {
+      const prev = this.store.get      ('cards', card.follows);
+      if (prev) {
+        this.store.put('cards', prev.id, { ...prev, followedBy: id });
+        this.emit({ type: 'change', card: prev.id });
+      }
+    }
+    this.emit({ type: 'change', card: id });
+    // Agent cards go through the card.created hook before the person sees them.
+    if ((kind === 'ask' || kind === 'secret') && caller.token !== '') return this.requestTriage(card);
+    return card;
+  }
+
+  /** An inbox with a limit shows at most that many cards, so its state fits the hosted inbox's CPU time. The limit counts
+   * the inbox's own cards too, such as pairing requests, which a client without a token can make. A revision always fits. */
+          makeRoom(id                    )       {
+    const limit = this.shownCardLimit;
+    if (limit === undefined || (id && this.store.get('cards', String(id)))) return;
+    if ((this.store.count?.('summaries') ?? 0) >= limit) {
+      throw new InboxError(507, `the inbox shows ${limit} cards, the most it shows. The person must clear answered or closed cards before a new one fits`);
+    }
+  }
+
+  /** The body a card shows: its template filled, and its widgets placed. */
+          cardBody(input         )                                                                                                         {
+    let body = input.body;
+    let template                  ;
+    if (input.template) {
+      const t = this.getTemplate(String(input.template.name));
+      const v = input.template.version === undefined ? t.versions.at(-1) : t.versions.find((x) => x.version === input.template?.version);
+      if (!v) throw new InboxError(404, 'unknown template version');
+      body = fill(v.source, input.template.vars ?? {});
+      template = { name: t.name, version: v.version };
+    }
+    // An empty body is no body: a client that fills a missing field with "", or an agent that sends body: "", means a
+    // card without widgets, and the body checks would otherwise refuse it for a root statement it has no reason to have.
+    if (body === undefined || String(body).trim() === '') return { body: undefined, template };
+    const expanded = expandWidgets(String(body), (name, version) => this.widgetVersion(name, version));
+    return { body: expanded.body, template, expanded };
+  }
+
+  /** Parse every diagram the card would show, before the card commits. An await sits here, so the commit reads everything again. */
+          async checkCard(input         )                           {
+    if (this.clientChecks) return new Map();
+    return checkDiagrams(findDiagrams({ text: input.text, recommendation: input.recommendation, body: this.cardBody(input).body }), this.checkDiagram);
+  }
+
+  /** What this inbox checks itself before it takes a card. A posting client checks the rest, from GET /v1/info. */
+  checks()                                       {
+    return { diagrams: !this.clientChecks && !!this.checkDiagram, body: !this.clientChecks && !!this.checkBody };
+  }
+
+  /** The text, recommendation and body a post or a patch would store, after templates and widgets, without storing anything.
+   * A client that checks diagrams and bodies itself reads them here. */
+  preview(caller        , req                                                                                         )                                                            {
+    if (caller.role === 'extension') throw new InboxError(403, 'only the client that posts a card can preview it');
+    const input = req.id !== undefined ? this.patched(caller, String(req.id), req.edits ?? [], req.field).input : req.card;
+    if (!input || typeof input !== 'object') throw new InboxError(400, 'send {card} for a post, or {id, edits, field} for a patch');
+    return { text: input.text, recommendation: input.recommendation, body: this.cardBody(input).body };
+  }
+
+  /** The page could not draw a card it shows: a diagram that mermaid cannot parse, or a body the OpenUI parser reads in part.
+   * The card goes back to its agent with the errors, as a laptop inbox would have refused the post. Only the owner reports. */
+  drawFault(caller        , id        , sent                                                                                      )       {
+    if (caller.role !== 'owner') throw new InboxError(403, 'only the page reports what it cannot draw');
+    const report = sent && typeof sent === 'object' ? sent : {};
+    const card = this.getCard(id);
+    if (card.kind === 'system') throw new InboxError(400, 'a system card shows its diagrams as source');
+    if (Number(report.version) !== card.version) throw new InboxError(409, `the card is at version ${card.version}, and the page drew version ${String(report.version)}`);
+    if (card.closed || this.store.get        ('answers', id)) return card;
+    const renderer = String(report.renderer ?? '').replace(/[^\w.-]/g, '').slice(0, 20) || 'on the page';
+    const shown = findDiagrams(card);
+    const reported = (Array.isArray(report.diagrams) ? report.diagrams : []).slice(0, MAX_DIAGRAMS)                                           ;
+    // The page names a diagram by its source. One the card does not show is not this card's fault.
+    const diagrams = reported.flatMap((d) => {
+      const at = shown.find((x) => x.source === d?.source);
+      return at ? [diagramMessage(at.where, renderer, String(d.error ?? 'it does not draw').slice(0, 2000), 'the page could not draw it, and the inbox sent the card back')] : [];
+    });
+    const faults = card.body === undefined || !Array.isArray(report.body) ? [] : report.body.slice(0, 20).map((f) => String(f).slice(0, 1000)).filter(Boolean);
+    const reason = [...diagrams, ...(faults.length ? [bodyProblemsMessage(faults, 'so the inbox sent the card back')] : [])].join('\n\n');
+    if (!reason) throw new InboxError(400, 'the report names no diagram this card shows, and no fault in its body');
+    return this.sendBack(card, reason, 'The inbox page');
+  }
+
+  /** Close a card as returned and tell its agent why. */
+          sendBack(card      , reason        , by        )       {
+    this.closeAs(card, 'returned', reason);
+    for (const [k, subs] of this.agents) {
+      if (k === this.key(card.token ?? '', card.agent)) for (const send of subs) send({ type: 'returned', id: randomId(6), card: publicCard(card), reason, by });
+    }
+    return this.getCard(card.id);
+  }
+
+  // ---- extensions and hooks ----
+
+  /** An extension dials in for the hooks it names. A second connection with the same name replaces the first. */
+  connectExtension(caller        , reg                                , send                         )             {
+    const entry = { reg: this.checkExtension(caller, reg), token: caller.token, send };
+    const name = entry.reg.name;
+    this.extensions.set(name, entry);
+    // Screen the cards that came in while no extension was there.
+    if (entry.reg.hooks.includes('card.created')) {
+      for (const card of this.store.list      ('cards')) {
+        if ((card.kind !== 'ask' && card.kind !== 'secret') || card.closed || this.store.get('answers', card.id)) continue;
+        const t = card.triage;
+        if (t?.state === 'pending' && t.request && t.deadline && t.waiting?.includes(name)) {
+          // A call this extension missed while it reconnected.
+          send({ type: 'hook', version: HOOK_VERSION, id: t.request, hook: 'card.created', card: publicCard(card), deadline: t.deadline, person: this.person() });
+        } else if (!t || t.state === 'skipped' || (t.state === 'pending' && !t.waiting?.length)) this.requestTriage(card);
+      }
+    }
+    return () => { if (this.extensions.get(name) === entry) this.extensions.delete(name); };
+  }
+
+  /** Check and complete an extension registration without connecting it. */
+  checkExtension(caller        , reg                                )                        {
+    if (caller.role === 'agent') throw new InboxError(403, 'only an extension or owner token can register hooks');
+    const name = String(reg.name ?? '').trim();
+    if (!/^[\w.-]{1,40}$/.test(name)) throw new InboxError(400, 'name must be 1 to 40 letters, digits, dots, dashes or underscores');
+    const hooks = (reg.hooks ?? []).map(String);
+    if (!hooks.length || !hooks.every(isHook)) throw new InboxError(400, `hooks must name some of ${Object.keys(HOOKS).join(', ')}`);
+    const policy = reg.policy === 'fail-closed' ? 'fail-closed' : 'fail-open';
+    const asked = Number(reg.timeoutMs);
+    const timeoutMs = Math.min(Math.max(Number.isFinite(asked) && asked > 0 ? asked : HOOKS['card.created'].defaultTimeoutMs, 1000), 600_000);
+    return { name, hooks: hooks              , policy, timeoutMs };
+  }
+
+          requestTriage(card      )       {
+    const targets = [...this.extensions.values()].filter((e) => e.reg.hooks.includes('card.created'));
+    const now = this.now();
+    if (!targets.length) {
+      // Fail-open when triage is down: the card goes straight to the person, and a returning extension screens it.
+      const next = { ...card, triage: { state: 'skipped'         , reason: 'No triage extension was connected.', at: now } };
+      this.store.put('cards', card.id, next);
+      return next;
+    }
+    const request = randomId(8);
+    const deadline = now + Math.max(...targets.map((t) => t.reg.timeoutMs));
+    const policy = targets.some((t) => t.reg.policy === 'fail-closed') ? 'fail-closed'          : 'fail-open'         ;
+    const next       = { ...card, triage: { state: 'pending', by: targets.map((t) => t.reg.name).join(', '), request, waiting: targets.map((t) => t.reg.name), deadline, policy, at: now } };
+    this.store.put('cards', card.id, next);
+    this.emit({ type: 'change', card: card.id });
+    const person = this.person();
+    for (const t of targets) t.send({ type: 'hook', version: HOOK_VERSION, id: request, hook: 'card.created', card: publicCard(next), deadline, person });
+    return next;
+  }
+
+  /** An extension answers a card.created call. */
+  hookVerdict(caller        , request        , verdict         , reason        )       {
+    const card = this.store.list      ('cards').find((c) => c.triage?.request === request);
+    if (!card?.triage) throw new InboxError(404, 'unknown hook call');
+    const ext = [...this.extensions.values()].find((e) => e.token === caller.token && card.triage?.waiting?.includes(e.reg.name));
+    if (!ext) throw new InboxError(403, 'this hook call does not wait for this extension');
+    if (!(HOOKS['card.created'].verdicts                     ).includes(verdict)) throw new InboxError(400, 'verdict must be pass, hold or return');
+    if (card.triage.state !== 'pending') return card;
+    const clean = String(reason ?? '').slice(0, 1000);
+    const waiting = (card.triage.waiting ?? []).filter((n) => n !== ext.reg.name);
+    const now = this.now();
+    if (verdict === 'return') {
+      this.store.put('cards', card.id, { ...card, triage: { ...card.triage, state: 'returned', by: ext.reg.name, reason: clean, waiting: [], at: now } });
+      return this.sendBack(card, clean || 'Triage sent the card back.', 'Triage');
+    }
+    const triage = verdict === 'hold'
+      ? { ...card.triage, state: 'held'         , by: ext.reg.name, reason: clean, waiting: [], at: now }
+      : { ...card.triage, state: waiting.length ? 'pending'          : 'passed'         , waiting, reason: clean || card.triage.reason, at: now };
+    const next = { ...card, triage };
+    this.store.put('cards', card.id, next);
+    this.emit({ type: 'change', card: card.id });
+    return next;
+  }
+
+  /** The owner lets a held card through. */
+  release(id        )       {
+    const card = this.getCard(id);
+    if (!card.triage || card.triage.state !== 'held') return card;
+    const next = { ...card, triage: { ...card.triage, state: 'passed'         , reason: `Released by you. ${card.triage.reason ?? ''}`.trim(), at: this.now() } };
+    this.store.put('cards', id, next);
+    this.emit({ type: 'change', card: id });
+    return next;
+  }
+
+  addWebhook(hook        , url        , secret        )          {
+    if (!isHook(hook)) throw new InboxError(400, `hook must be one of ${Object.keys(HOOKS).join(', ')}`);
+    if (!/^https:\/\//.test(String(url))) throw new InboxError(400, 'url must be https');
+    if (this.webhooks().length >= MAX_WEBHOOKS) throw new InboxError(400, `an inbox takes at most ${MAX_WEBHOOKS} webhooks`);
+    const w          = { id: randomId(6), hook, url: String(url), secret };
+    this.store.put('meta', `webhook:${w.id}`, w);
+    return w;
+  }
+
+          webhooks()            {
+    return this.store.list         ('meta').filter((m)               => typeof m === 'object' && m !== null && 'url' in m && 'secret' in m);
+  }
+
+  listWebhooks()                            {
+    return this.webhooks().map(({ secret: _s, ...w }) => w);
+  }
+
+  deleteWebhook(id        )       {
+    this.store.delete('meta', `webhook:${id}`);
+  }
+
+          observeAnswer(card      , answer        )       {
+    // A sealed value opens only with the key in its session's memory, so no hook gets it.
+    const event            = { type: 'hook', version: HOOK_VERSION, id: randomId(8), hook: 'answer.saved', card: publicCard(card), answer: withoutSealed(card, answer) };
+    for (const e of this.extensions.values()) if (e.reg.hooks.includes('answer.saved')) e.send(event);
+    for (const w of this.webhooks().filter((x) => x.hook === 'answer.saved')) this.track(deliverWebhook(w, event, this.fetcher));
+  }
+
+          track(p                  )       {
+    this.deliveries.add(p);
+    void p.then(() => this.deliveries.delete(p), () => this.deliveries.delete(p));
+  }
+
+  // ---- answer webhooks ----
+
+  /** A client's system card: a request to send the answers to its cards to a webhook, or to stop. The owner approves each
+   * webhook on a system card the inbox posts, and nothing goes out before that. */
+  systemRequest(caller        , input         )                                                       {
+    const type = input?.system?.type;
+    if (type === 'subscribe') return this.subscribe(caller, input);
+    if (type !== 'unsubscribe') throw new InboxError(400, 'a system card from a client carries system.type subscribe or unsubscribe');
+    const agent = this.requestingAgent(caller, input);
+    return { removed: this.removeSubscriptions((s) => s.token === caller.token && s.agent === agent, `The agent ${agent} unsubscribed.`) };
+  }
+
+  /** The agent a client's system card speaks for. */
+          requestingAgent(caller        , input         )         {
+    if (caller.role === 'extension') throw new InboxError(403, 'an extension posts no cards');
+    const agent = String(input?.agent ?? '').trim();
+    if (!agent || agent.length > 80) throw new InboxError(400, 'agent is required, at most 80 characters');
+    if (agent === SYSTEM_AGENT) throw new InboxError(403, 'the system agent is reserved');
+    return agent;
+  }
+
+  /** A subscribe request: the webhook waits, pending, for the owner to approve it on its card. The secret is returned once. */
+  subscribe(caller        , input         )                                                                   {
+    const agent = this.requestingAgent(caller, input);
+    const req = input.system;
+    if (req?.type !== 'subscribe') throw new InboxError(400, 'a subscribe request carries system.type subscribe');
+    const mine = (s              )          => s.token === caller.token && s.agent === agent;
+    const url = webhookUrl(req.webhook?.url);
+    const headers = webhookHeaders(req.webhook?.headers);
+    const events = req.events ?? ['answer'];
+    if (!Array.isArray(events) || !events.length || events.some((e) => e !== 'answer')) throw new InboxError(400, 'events takes answer, the only event a webhook receives');
+    if (this.store.list              ('subscriptions').filter((s) => !mine(s)).length >= MAX_SUBSCRIPTIONS) {
+      throw new InboxError(429, `an inbox takes at most ${MAX_SUBSCRIPTIONS} answer webhooks`);
+    }
+    const id = randomId(8);
+    const cardId = `subscribe-${id}`;
+    this.makeRoom(cardId);
+    // One webhook for each agent and token: a new request replaces the one before.
+    this.removeSubscriptions(mine, 'The agent sent a new request, which replaces this one.');
+    const sub               = { id, agent, token: caller.token, url, headers, events: ['answer'], secret: randomId(24), status: 'pending', createdAt: this.now(), delivered: 0 };
+    this.store.put('subscriptions', id, sub);
+    const host = new URL(url).host;
+    // The card is Markdown, so the agent's words go in code spans, which show them as typed.
+    const code = (text        )         => `\`${text.replace(/`/g, "'")}\``;
+    const names = Object.keys(headers).map(code);
+    this.postCard(INBOX, {
+      id: cardId, agent: SYSTEM_AGENT, kind: 'system', deliver: 'none', priority: this.priorities()[0]?.id,
+      title: `Send the answers for ${agent} to a webhook?`,
+      text: `The agent ${code(agent)} asks the inbox to send each answer you give to its cards to ${code(url)}${names.length ? `, with the header${names.length === 1 ? '' : 's'} ${names.join(', ')}` : ''}. Whoever runs ${host} then reads those answers. Approve only if you know that address.`,
+      options: [
+        { id: 'approve', label: 'Approve', description: `The inbox sends each answer to the cards of ${code(agent)} to ${host}.` },
+        { id: 'deny', label: 'Deny', description: 'Nothing goes out. To stop a webhook you approved, change your answer to this.' },
+      ],
+    });
+    const card = { ...this.getCard(cardId), subscription: id };
+    this.store.put('cards', cardId, card);
+    return { subscription: this.publicSubscription(sub), card: publicCard(card), secret: sub.secret };
+  }
+
+          resolveSubscription(card      , answer        )       {
+    const sub = this.store.get              ('subscriptions', card.subscription ?? '');
+    // The webhook went before this answer, so the card keeps the outcome it closed with.
+    if (!sub) { this.closeAs(card, 'resolved', card.closed?.outcome ?? 'This webhook is gone.'); return; }
+    const host = new URL(sub.url).host;
+    if ([answer.values['choice']].flat()[0] === 'approve') {
+      this.store.put              ('subscriptions', sub.id, { ...sub, status: 'approved', approvedAt: sub.approvedAt ?? this.now() });
+      this.closeAs(card, 'resolved', `Sending the answers for ${sub.agent} to ${host}. To stop, change your answer to Deny.`);
+      return;
+    }
+    this.removeSubscriptions((s) => s.id === sub.id, sub.status === 'approved' ? `Stopped: no more answers for ${sub.agent} go to ${host}.` : `Denied: nothing goes to ${host}.`);
+  }
+
+  /** Remove the webhooks that match, with the calls still waiting, and close the card of each with the outcome. */
+          removeSubscriptions(match                              , outcome        )         {
+    const gone = this.store.list              ('subscriptions').filter(match);
+    for (const s of gone) {
+      this.store.delete('subscriptions', s.id);
+      for (const d of this.store.list            ('outbox')) if (d.sub === s.id) this.store.delete('outbox', d.key);
+      const card = this.store.get      ('cards', `subscribe-${s.id}`);
+      if (card) this.closeAs(card, 'resolved', outcome);
+    }
+    return gone.length;
+  }
+
+  /** The owner removes any webhook, and a client the ones it asked for. */
+  deleteSubscription(caller        , id        )       {
+    const sub = this.store.get              ('subscriptions', id);
+    if (!sub) throw new InboxError(404, 'unknown subscription');
+    if (caller.role !== 'owner' && sub.token !== caller.token) throw new InboxError(403, 'another client owns this subscription');
+    this.removeSubscriptions((s) => s.id === id, sub.token === caller.token ? `The agent ${sub.agent} unsubscribed.` : 'You removed this webhook.');
+  }
+
+  /** Every webhook for the owner, and its own for any other client. */
+  listSubscriptions(caller        )                       {
+    if (caller.role === 'extension') throw new InboxError(403, 'an extension reads no webhooks');
+    return this.store.list              ('subscriptions').filter((s) => caller.role === 'owner' || s.token === caller.token).map((s) => this.publicSubscription(s));
+  }
+
+          publicSubscription(s              )                     {
+    const { token: _t, secret: _s, headers, ...rest } = s;
+    return { ...rest, headers: Object.keys(headers), waiting: this.store.list            ('outbox').filter((d) => d.sub === s.id).length };
+  }
+
+  /** Queue the answer for the webhook of its card's agent and token, and call it now. */
+          queueAnswer(card      , answer        )       {
+    if (card.deliver !== 'stream') return;
+    const sub = this.store.list              ('subscriptions').find((s) => s.status === 'approved' && s.token === (card.token ?? '') && s.agent === card.agent);
+    if (!sub) return;
+    const now = this.now();
+    const key = `${sub.id}:${card.id}`;
+    this.store.put            ('outbox', key, { key, sub: sub.id, card: card.id, savedAt: answer.savedAt, attempts: 0, firstAt: now, nextAt: now });
+    this.track(this.deliverAnswers());
+  }
+
+  /** Call the webhook of each answer that is due. An answer calls it at once, and the platform alarm calls it after sweep()
+   * for each retry. Each call carries the agent stream's answer event, with the answer's id. */
+  async deliverAnswers()                {
+    const now = this.now();
+    const calls                  = [];
+    for (const item of this.store.list            ('outbox')) {
+      if (item.nextAt > now) continue;
+      const sub = this.store.get              ('subscriptions', item.sub);
+      const card = this.store.get      ('cards', item.card);
+      const answer = this.store.get        ('answers', item.card);
+      // The card went to another agent, the person changed the answer, or the agent read it already.
+      if (!sub || sub.status !== 'approved' || !card || card.agent !== sub.agent || (card.token ?? '') !== sub.token || !answer || answer.savedAt !== item.savedAt || answer.readAt) {
+        this.store.delete('outbox', item.key);
+        continue;
+      }
+      // Hold the call before the await, so a second run does not make it again. A call that a crash cut off goes after the lease.
+      this.store.put            ('outbox', item.key, { ...item, nextAt: now + DELIVERY_LEASE_MS, calling: true });
+      const id = answerId(card.id, answer.savedAt);
+      // A sealed value opens only with the key in its session's memory, so the webhook gets the rest of the answer.
+      const ev              = { type: 'answer', id, card: publicCard(card), answer: withoutSealed(card, answer) };
+      const headers = { ...sub.headers, 'x-your-attention-event': 'answer', 'x-your-attention-delivery': id };
+      calls.push(postSigned(sub.url, sub.secret, headers, ev, ANSWER_WEBHOOK_TIMEOUT_MS, this.fetcher).then((r) => this.called(item, r)));
+    }
+    // A call that fails to record its result, such as on a store that closed, must not stop the alarm's other work.
+    await Promise.allSettled(calls);
+  }
+
+  /** Record how a webhook call went: a 2xx marks the answer read, and anything else waits for the next retry. */
+          called(item            , r                                  )       {
+    const now = this.now();
+    const current = this.store.get            ('outbox', item.key);
+    const sub = this.store.get              ('subscriptions', item.sub);
+    // The webhook went, or a newer answer took this call's place while it ran and has its own schedule.
+    if (!sub || !current || current.savedAt !== item.savedAt) return;
+    if (r.ok) {
+      this.store.delete('outbox', item.key);
+      const { lastError: _e, ...rest } = sub;
+      this.store.put              ('subscriptions', sub.id, { ...rest, delivered: sub.delivered + 1 });
+      const answer = this.store.get        ('answers', item.card);
+      // The webhook has the answer, as an agent that acknowledges it on its stream.
+      if (answer && answer.savedAt === item.savedAt && !answer.readAt) {
+        this.store.put        ('answers', item.card, { ...answer, deliveredAt: answer.deliveredAt ?? now, readAt: now });
+        this.emit({ type: 'change', card: item.card });
+      }
+      return;
+    }
+    const reason = r.reason ?? 'the webhook failed';
+    if (now - item.firstAt >= RETRY_GIVE_UP_MS) {
+      this.store.delete('outbox', item.key);
+      this.store.put              ('subscriptions', sub.id, { ...sub, lastError: { at: now, reason: `${reason}; the inbox stopped trying after 24 hours` } });
+      return;
+    }
+    const attempts = item.attempts + 1;
+    this.store.put              ('subscriptions', sub.id, { ...sub, lastError: { at: now, reason } });
+    const { calling: _c, ...waiting } = current;
+    this.store.put            ('outbox', item.key, { ...waiting, attempts, nextAt: now + Math.min(RETRY_FIRST_MS * 2 ** (attempts - 1), RETRY_MAX_MS) });
+  }
+
+  getCard(id        )       {
+    const card = this.store.get      ('cards', id);
+    if (!card) throw new InboxError(404, 'unknown card');
+    return card;
+  }
+
+  /** Post a card whose attachments include data: URLs. The bytes go to the blob store first,
+   * then the card commits in one synchronous step, and the files it replaced are deleted. */
+  async postCardWithFiles(caller        , input         )                {
+    if (!input || typeof input !== 'object') throw new InboxError(400, 'card must be an object');
+    // Only herdr names a pane's agent and tab: a place the agent sent is dropped.
+    // Only herdr names a pane's agent and tab: the places go around postCard, so an agent cannot supply one.
+    const approvals = this.cleanApprovals(input.approvals, input.kind ?? 'ask');
+    const places = approvals ? await this.describePanes(approvals) : undefined;
+    const checked = await this.checkCard(input);
+    const files = input.attachments;
+    if (!Array.isArray(files) || !files.some((f) => /^data:/.test(String(f?.src ?? '')))) return this.postCard(caller, input, undefined, checked, places);
+    if (files.length > MAX_ATTACHMENTS) throw new InboxError(400, `a card takes at most ${MAX_ATTACHMENTS} attachments`);
+    const id = input.id ? String(input.id) : randomId(8);
+    // Check the id before it goes into a blob key.
+    if (!/^[\w.:-]{1,80}$/.test(id)) throw new InboxError(400, 'id must be 1 to 80 letters, digits, dots, colons, dashes or underscores');
+    const before = this.store.get      ('cards', id);
+    if (before && before.token !== caller.token && caller.role !== 'owner') throw new InboxError(403, 'another client owns this card');
+    if (files.some((f) => !f || typeof f !== 'object')) throw new InboxError(400, 'each attachment must be an object with src');
+    const decoded = files.map((f, i) => (/^data:/.test(String(f?.src ?? '')) ? decodeDataUrl(i, f) : undefined));
+    // Count the bytes before the first await, so two posts at once cannot both fit under the limit.
+    const bytes = decoded.reduce((n, d) => n + (d ? Math.max(d.bytes.length, MIN_FILE_CHARGE) : 0), 0);
+    const { used, limit } = this.uploads();
+    if (limit !== undefined && used + bytes > limit) {
+      throw new InboxError(413, `these files are ${bytes} bytes, and this inbox has stored ${used} of its lifetime limit of ${limit} bytes`);
+    }
+    this.store.put('meta', 'uploaded-bytes', used + bytes);
+    const stored               = [];
+    const refund = ()                => this.refundUploads(stored, bytes);
+    // Wait for every put, so a put that fails leaves none of the others behind. Each key is listed before its put starts.
+    const settled = await Promise.allSettled(files.map(async (f, i)                         => {
+      const d = decoded[i];
+      if (!d) return f;
+      const key = `${id}.${i}.${randomId(6)}`;
+      const name = cleanName(f.name) || `attachment-${i + 1}`;
+      const type = attachmentType({ name, type: d.type });
+      const ref             = { id: key, name, type, size: d.bytes.length, alt: f.alt ? String(f.alt).slice(0, 300) : undefined };
+      stored.push(ref);
+      await this.blobs.put(key, d.bytes, type);
+      return { src: '', ref };
+    }));
+    const failed = settled.find((r) => r.status === 'rejected');
+    if (failed) {
+      await refund();
+      throw failed.reason;
+    }
+    const resolved = settled.map((r) => (r                                         ).value);
+    let card      ;
+    let prior                  ;
+    try {
+      // Read the card again right before the commit, with no await between: another update may have landed meanwhile.
+      prior = this.store.get      ('cards', id);
+      card = this.postCard(caller, { ...input, id, attachments: resolved }, new Set(stored.map((f) => f.id ?? '')), checked, places);
+    } catch (e) {
+      await refund();
+      throw e;
+    }
+    const kept = new Set(card.attachments?.map((f) => f.id));
+    await Promise.all((prior?.attachments ?? []).filter((f) => f.id && !kept.has(f.id)).map((f) => this.blobs.delete(f.id ?? '')));
+    return card;
+  }
+
+  /** Whether the inbox keeps more than its storage limit. A full inbox takes only writes that free space. */
+  storageFull()          {
+    return this.storageLimit !== undefined && (this.store.bytes?.() ?? 0) >= this.storageLimit;
+  }
+
+  /** The bytes of files this inbox has stored since it was created, and its lifetime limit, if it has one. */
+  uploads()                                              {
+    return { used: this.store.get        ('meta', 'uploaded-bytes') ?? 0, limit: this.uploadLimit };
+  }
+
+  /** The bytes of a file, for the owner, an extension, or the client that posted its card. */
+  async attachment(caller        , id        )                                                                {
+    // A key is <card id>.<index>.<random>, and a card id may contain dots.
+    const card = this.getCard(id.split('.').slice(0, -2).join('.') || id);
+    if (caller.role === 'agent' && card.token !== caller.token) throw new InboxError(403, 'another client owns this card');
+    const answer = this.store.get        ('answers', card.id);
+    const file = card.attachments?.find((f) => f.id === id)
+      ?? [answer, ...(answer?.previous ?? [])].flatMap((a) => a?.images ?? []).find((f) => f.id === id);
+    if (!file) throw new InboxError(404, 'unknown attachment');
+    // Each client has its own daily budget, so an agent's downloads never use up the owner's. A refused download reads no blob.
+    if (this.readsPerDay !== undefined) {
+      const key = `reads:${new Date(this.now()).toISOString().slice(0, 10)}:${caller.token}`;
+      const n = this.store.get                            ('meta', key)?.n ?? 0;
+      if (n >= this.readsPerDay) throw new InboxError(429, `you downloaded ${this.readsPerDay} files from this inbox today`);
+      this.store.put('meta', key, { key, n: n + 1 });
+    }
+    const blob = await this.blobs.get(id);
+    // A cloud inbox deletes files after a while, and the card keeps listing them.
+    if (!blob) throw new InboxError(410, `${file.name} is no longer stored`);
+    return { file, bytes: blob.bytes };
+  }
+
+  /** Why the person won't see a revision of this card, when they answered it or it is closed. The page keeps such a card in
+   * Sent and never asks again, so the agent hears it with the revision instead. */
+  revisionWarning(id        )                     {
+    const card = this.store.get      ('cards', id);
+    if (!card) return undefined;
+    const s = cardState(card, this.store.get        ('answers', id));
+    if (s === 'open' || s === 'in-triage' || s === 'held') return undefined;
+    return `Card ${id} ${s === 'closed' ? 'is closed' : 'was already answered'}, so this revision stays in the person's Sent list: the person is not notified, and won't answer it again. To ask again, post a new card with follows: "${id}".`;
+  }
+
+  /** Edit a card the way a coding agent edits a file: each edit replaces text that occurs exactly once. */
+  patchCard(caller        , id        , edits                                , field         , checked                  )       {
+    const { card, input } = this.patched(caller, id, edits, field);
+    const next = this.postCard(caller, input, undefined, checked, undefined, { revise: true });
+    // A patch edits the body the widgets already filled, so the card still shows them and keeps their responses, and any the patch placed.
+    if (!card.widgets) return next;
+    const responses = [...(card.responses ?? []), ...(next.responses ?? [])];
+    const kept = { ...next, widgets: distinctWidgets([...card.widgets, ...(next.widgets ?? [])]), ...(responses.length ? { responses } : {}) };
+    this.store.put('cards', kept.id, kept);
+    return kept;
+  }
+
+  /** patchCard, with the diagrams of the patched card checked first. */
+  async patchCardChecked(caller        , id        , edits                                , field         )                {
+    const checked = await this.checkCard(this.patched(caller, id, edits, field).input);
+    return this.patchCard(caller, id, edits, field, checked);
+  }
+
+  /** The card a patch would post, and the card it edits. */
+          patched(caller        , id        , edits                                , field         )                                 {
+    const card = this.owned(caller, id);
+    const f = field ?? (card.body !== undefined ? 'body' : card.html !== undefined ? 'html' : 'text');
+    if (!PATCH_FIELDS.has(f)) throw new InboxError(400, `field must be one of ${[...PATCH_FIELDS].join(', ')}`);
+    if (!Array.isArray(edits) || !edits.length) throw new InboxError(400, 'edits must be a list of {old, new}');
+    let text = String((card                                      )[f] ?? '');
+    for (const [i, e] of edits.entries()) {
+      const old = String(e?.old ?? '');
+      // An empty old text fills a field that is empty.
+      if (!old && !text) { text = String(e.new ?? ''); continue; }
+      // A patch that replaces text with itself changes nothing, so it is a mistake rather than a revision: accepting it
+      // bumped the version, told the person their card changed, and made a "did this text survive?" probe look like an
+      // edit.
+      if (old && String(e.new ?? '') === old) throw new InboxError(400, `edit ${i + 1}: new is identical to old, so it changes nothing`);
+      const count = old ? text.split(old).length - 1 : 0;
+      if (count !== 1) {
+        // A count alone leaves the agent guessing at text it cannot see. Naming the closest stored lines lets it patch
+        // from the real text instead of from the payload it remembers sending.
+        const near = count === 0 ? nearestLines(text, old) : [];
+        const hint = near.length
+          ? `; the closest stored lines are ${near.map((l) => JSON.stringify(l)).join(', ')}`
+          : count === 0 ? '; no stored line shares a word with it, so read the card and take the text from there' : '';
+        throw new InboxError(409, `edit ${i + 1}: the old text occurs ${count} times in ${f}, and it must occur once${hint}`);
+      }
+      text = text.replace(old, () => String(e.new ?? ''));
+    }
+    const { token: _t, version: _v, createdAt: _c, updatedAt: _u, closed: _cl, replies: _r, history: _h, triage: _tr, followedBy: _fb, broadcast: _b, template: _tp, attachments: _a, widgets: _w, responses: _rs, ...rest } = card;
+    return { card, input: { ...rest, [f]: text } };
+  }
+
+  /** The agent sets a state label on its own card. An empty label clears it. */
+  setStatus(caller        , id        , status        )       {
+    const card = this.owned(caller, id);
+    const clean = String(status ?? '').trim().slice(0, 60);
+    const next = { ...card, status: clean || undefined };
+    this.store.put('cards', id, next);
+    this.emit({ type: 'change', card: id });
+    return next;
+  }
+
+  // ---- templates ----
+
+  saveTemplate(name        , source        , feedback         )           {
+    return this.saveVersion('templates', 'template', name, source, feedback);
+  }
+
+  /** Templates and widgets keep every version, with the feedback each one answers. */
+          saveVersion(kind                         , label        , name        , source        , feedback         , extra                                       = {})           {
+    if (!/^[\w.-]{1,60}$/.test(String(name ?? ''))) throw new InboxError(400, `${label} name must be 1 to 60 letters, digits, dots, dashes or underscores`);
+    if (!String(source ?? '').trim()) throw new InboxError(400, 'source is required');
+    if (String(source).length > MAX_SOURCE_BYTES) throw new InboxError(413, `source must be at most ${MAX_SOURCE_BYTES} characters`);
+    const before = this.store.get          (kind, name);
+    const versions = before?.versions ?? [];
+    if (versions.length >= MAX_VERSIONS) throw new InboxError(400, `${label} ${name} has ${MAX_VERSIONS} versions, the most it keeps. Save it under a new name`);
+    for (const [k, v] of Object.entries(extra)) if (v !== undefined && String(v).length > MAX_SOURCE_BYTES) throw new InboxError(413, `${k} must be at most ${MAX_SOURCE_BYTES} characters`);
+    const when = String(extra.when ?? '').trim() || undefined;
+    const response = String(extra.response ?? '').trim() ? String(extra.response) : undefined;
+    const next           = { name, versions: [...versions, { version: versions.length + 1, source: String(source), feedback: feedback ? String(feedback) : undefined, ...(when ? { when } : {}), ...(response ? { response } : {}), at: this.now() }] };
+    this.store.put(kind, name, next);
+    return next;
+  }
+
+  // ---- widgets ----
+
+  saveWidget(name        , source        , feedback         , extra                                       = {})           {
+    if (!/^\s*root\s*=/m.test(String(source ?? ''))) throw new InboxError(400, 'a widget must define root, the part a card places');
+    if (BUILTIN_WIDGETS.some((w) => w.name === name)) throw new InboxError(400, `${name} is a built-in widget: save yours under another name`);
+    return this.saveVersion('widgets', 'widget', name, source, feedback, extra);
+  }
+
+  /** The widgets an agent can place, each with when to use it and the values it takes, as agents read them in the card guidance. */
+  widgetCatalog()         {
+    const lines = this.listWidgets().map((w) => {
+      const v = w.versions.at(-1);
+      if (!v) return '';
+      const values = [...new Set([...v.source.matchAll(/\{\{(\w+)\}\}/g)].map((m) => m[1]))];
+      return `- ${w.name}: ${v.when ?? 'No hook: read its source with GET /v1/widgets/' + w.name + ' first.'}${values.length ? ` Its values: ${values.join(', ')}.` : ''}`;
+    }).filter(Boolean);
+    return lines.length ? `Widgets you can place in a card body with a line \`part = widget <name> {json values}\`:\n${lines.join('\n')}` : '';
+  }
+
+  getWidget(name        )           {
+    const w = BUILTIN_WIDGETS.find((x) => x.name === name) ?? this.store.get          ('widgets', name);
+    if (!w) throw new InboxError(404, `unknown widget ${name}`);
+    return w;
+  }
+
+  /** The built-in widgets first, then the saved ones. */
+  listWidgets()             {
+    return [...BUILTIN_WIDGETS, ...this.store.list          ('widgets').filter((w) => !BUILTIN_WIDGETS.some((b) => b.name === w.name))];
+  }
+
+          widgetVersion(name        , version         )               {
+    const w = this.getWidget(name);
+    const v = version === undefined ? w.versions.at(-1) : w.versions.find((x) => x.version === version);
+    if (!v) throw new InboxError(404, `unknown version ${version} of widget ${name}`);
+    return { name, version: v.version, source: v.source, ...(v.response ? { response: v.response } : {}) };
+  }
+
+  getTemplate(name        )           {
+    const t = this.store.get          ('templates', name);
+    if (!t) throw new InboxError(404, 'unknown template');
+    return t;
+  }
+
+  listTemplates()             {
+    return this.store.list          ('templates');
+  }
+
+  // ---- settings, priority levels and guidance ----
+
+  settings()           {
+    return this.store.get          ('meta', 'settings') ?? { allowHtml: false };
+  }
+
+  setSettings(input                               )           {
+    const next           = { ...this.settings(), ...(typeof input.allowHtml === 'boolean' ? { allowHtml: input.allowHtml } : {}) };
+    if (input.groupBy !== undefined) next.groupBy = this.checkGroupBy(input.groupBy);
+    if (input.pins !== undefined) next.pins = this.checkPins(input.pins);
+    // A pin or an unpin travels as its own change, so two devices that pin at the same moment both keep their value.
+    if (input.pinAdd !== undefined || input.pinRemove !== undefined) {
+      const same = (a                  , b                  ) => a[0] === b[0] && a[1] === b[1];
+      const add = input.pinAdd === undefined ? [] : this.checkPins(input.pinAdd);
+      const remove = input.pinRemove === undefined ? [] : this.checkPins(input.pinRemove);
+      const current = next.pins ?? [];
+      const kept = current.filter((p) => !remove.some((r) => same(r, p)));
+      const merged = [...kept, ...add.filter((a) => !kept.some((k) => same(k, a)))];
+      // A pin the inbox cannot keep is refused, so the person hears it rather than losing the value quietly.
+      if (merged.length > MAX_PINS) throw new InboxError(400, `pins takes at most ${MAX_PINS}; unpin a value first`);
+      next.pins = merged;
+    }
+    this.store.put('meta', 'settings', next);
+    this.emit({ type: 'change', card: '' });
+    return next;
+  }
+
+          checkGroupBy(groupBy         )         {
+    const raw = typeof groupBy === 'string' && groupBy.startsWith('tag:') ? groupBy.slice(4) : '';
+    const key = raw.trim();
+    if (!(groupBy === 'none' || groupBy === 'priority' || groupBy === 'agent' || (key.length >= 1 && key.length <= MAX_TAG_CHARS))) {
+      throw new InboxError(400, 'groupBy must be none, priority, agent or tag:<key>');
+    }
+    // The key is stored the way it is matched, so `tag: topic ` groups the cards tagged `topic`.
+    return key && groupBy !== 'none' ? `tag:${key}` : groupBy          ;
+  }
+
+  /** Pins reach the queue the page draws, so a pair that isn't a tag key and its value is refused rather than stored. */
+          checkPins(pins         )                     {
+    if (!Array.isArray(pins) || pins.length > MAX_PINS) throw new InboxError(400, `pins must be a list of at most ${MAX_PINS} [key, value] pairs`);
+    return pins.map((pair, i) => {
+      if (!Array.isArray(pair) || pair.length !== 2) throw new InboxError(400, `pin ${i + 1}: give a tag key and its value`);
+      const [key, value] = pair.map((side) => (typeof side === 'string' ? side.trim() : ''));
+      if (!key || !value) throw new InboxError(400, `pin ${i + 1}: the tag key and its value are both required`);
+      if (key.length > MAX_TAG_CHARS || value.length > MAX_TAG_CHARS) throw new InboxError(400, `pin ${i + 1}: the tag key and its value are at most ${MAX_TAG_CHARS} characters`);
+      return [key, value];
+    });
+  }
+
+  priorities()                  {
+    const saved = this.store.get                 ('meta', 'priorities');
+    if (!saved) return DEFAULT_PRIORITIES;
+    // A default level saved without a color keeps its default color.
+    return saved.map((l) => (l.color ? l : { ...l, color: DEFAULT_PRIORITIES.find((d) => d.id === l.id)?.color }));
+  }
+
+  /** An agent proposes new priority levels. They reorder the whole queue, so the person approves them on a system card. */
+  proposePriorities(levels                 )       {
+    const clean = this.checkPriorities(levels);
+    const id = `priorities-${randomId(4)}`;
+    this.postCard({ token: '', role: 'owner' }, {
+      id, agent: SYSTEM_AGENT, kind: 'system', deliver: 'none', priority: this.priorities()[0]?.id,
+      title: 'Change the priority levels?',
+      text: `An agent proposes these levels. They apply to every card in the queue.\n\n${clean.map((l) => `- ${l.label} (${l.id})${l.definition ? `: ${l.definition}` : ''}${l.rule ? `\n  rule: ${l.rule}` : ''}`).join('\n')}`,
+      options: [{ id: 'approve', label: 'Apply them' }, { id: 'reject', label: 'Keep the current levels' }],
+    });
+    this.store.put('meta', `proposal:${id}`, clean);
+    return this.getCard(id);
+  }
+
+          resolvePriorityProposal(card      , answer        )       {
+    const levels = this.store.get                 ('meta', `proposal:${card.id}`);
+    this.store.delete('meta', `proposal:${card.id}`);
+    if (!levels || [answer.values['choice']].flat()[0] !== 'approve') { this.closeAs(card, 'resolved', 'Kept the current priority levels.'); return; }
+    this.setPriorities(levels);
+    this.closeAs(card, 'resolved', `Applied ${levels.length} priority levels.`);
+  }
+
+  setPriorities(levels                 )                  {
+    const clean = this.checkPriorities(levels);
+    this.store.put('meta', 'priorities', clean);
+    this.emit({ type: 'change', card: '' });
+    return clean;
+  }
+
+          checkPriorities(levels                 )                  {
+    if (!Array.isArray(levels) || !levels.length || levels.length > 10) throw new InboxError(400, 'give 1 to 10 priority levels');
+    const seen = new Set        ();
+    const clean = levels.map((l, i) => {
+      const id = String(l?.id ?? '');
+      if (!/^[\w-]{1,30}$/.test(id) || seen.has(id)) throw new InboxError(400, `level ${i + 1}: id must be unique, 1 to 30 letters, digits, dashes or underscores`);
+      seen.add(id);
+      const label = String(l.label ?? '').trim();
+      if (!label) throw new InboxError(400, `level ${i + 1}: label is required`);
+      const rule = l.rule ? String(l.rule) : undefined;
+      if (rule) {
+        try { parse(rule); } catch (e) { throw new InboxError(400, `level ${i + 1}: ${(e         ).message}`); }
+      }
+      const color = l.color ? String(l.color).toLowerCase() : undefined;
+      if (color && !/^#[0-9a-f]{6}$/.test(color)) throw new InboxError(400, `level ${i + 1}: color must be #rrggbb`);
+      return { id, label, definition: String(l.definition ?? ''), rule, ...(color ? { color } : {}) };
+    });
+    return clean;
+  }
+
+  /** The level a card shows: the first level whose rule matches it, or the level the agent gave. */
+  effectivePriority(card                    , levels = this.priorities(), answer                                     = this.store.get        ('answers', card.id))         {
+    const scope                        = {
+      kind: card.kind, agent: card.agent, priority: card.priority, status: card.status ?? null, rating: card.rating ?? null,
+      tags: card.tags ?? {}, blocked: card.kind === 'blocked', answered: !!answer,
+      waitMinutes: Math.floor((this.now() - card.createdAt) / 60000), harness: card.origin?.harness ?? null,
+    };
+    for (const l of levels) {
+      if (!l.rule) continue;
+      try { if (testRule(l.rule, scope)) return l.id; } catch { /* stored rules always parse */ }
+    }
+    return levels.some((l) => l.id === card.priority) ? card.priority : levels[0]?.id ?? card.priority;
+  }
+
+  guidance()           {
+    return this.store.get          ('meta', 'guidance') ?? { text: DEFAULT_GUIDANCE, version: DEFAULT_GUIDANCE_VERSION, at: 0 };
+  }
+
+  /** The tag keys in use with their values and counts, for GET /v1/guidance and card_guidance, so an agent reuses a
+   * value another card set instead of inventing a near miss. It counts the open cards and the cards cleared or closed
+   * in the last PURGE_AFTER_MS, and drops the rest, so a value nobody uses anymore leaves the list. Keys sort by their
+   * total count, then by key, and values by count, then by value, cut to MAX_TAG_KEYS keys and MAX_TAG_VALUES values
+   * each. It reads the summaries the state already reads, and a whole card only for one cleared inside the window. */
+  tagsInUse()             {
+    const cutoff = this.now() - PURGE_AFTER_MS;
+    const counts = new Map                             ();
+    const count = (tags                                    )       => {
+      // A summary written before tags were cleaned still counts the way the print cleans them, so a stored line break
+      // can never forge a line in an agent's card_guidance.
+      for (const [key, value] of Object.entries(cleanTags(tags) ?? {})) {
+        const values = counts.get(key) ?? new Map                ();
+        values.set(value, (values.get(value) ?? 0) + 1);
+        counts.set(key, values);
+      }
+    };
+    for (const s of this.store.list             ('summaries')) {
+      // A card that closed before the window still shows until the person clears it, and its tags are no longer in use.
+      if (cardState(s, s.answer) === 'closed' && (s.closed?.at ?? 0) < cutoff) continue;
+      count(s.tags);
+    }
+    // A cleared card keeps no summary, so the list reads the card itself, and only while its clear is inside the window.
+    for (const c of this.store.list             ('cleared')) {
+      if (c.archivedAt < cutoff) continue;
+      count(this.store.get      ('cards', c.id)?.tags);
+    }
+    const byName = (a        , b        )         => (a < b ? -1 : a > b ? 1 : 0);
+    return [...counts.entries()]
+      .map(([key, values]) => {
+        const list = [...values.entries()].map(([value, n]) => ({ value, count: n })).sort((a, b) => b.count - a.count || byName(a.value, b.value));
+        return { key, total: list.reduce((n, v) => n + v.count, 0), values: list };
+      })
+      .sort((a, b) => b.total - a.total || byName(a.key, b.key))
+      .slice(0, MAX_TAG_KEYS)
+      .map(({ key, values }) => ({ key, values: values.slice(0, MAX_TAG_VALUES) }));
+  }
+
+  /** An agent proposes new card guidance. The person approves it, and picks who receives it, on a system card. With `by`,
+   * the answer and its comment go to the agent that proposed the text, which may acknowledge it or retract the card. */
+  proposeGuidance(text        , message        , by                                    )       {
+    const clean = String(text ?? '').trim();
+    if (!clean) throw new InboxError(400, 'text is required');
+    // The person reads the message to decide, so a proposal without one is refused rather than shown unexplained.
+    const why = String(message ?? '').trim();
+    if (!why) throw new InboxError(400, 'a guidance proposal needs a message: say what changed and why, for the person who approves it');
+    if (why.length > 2000) throw new InboxError(400, 'message must be at most 2000 characters');
+    // The widget catalog reaches agents beside the guidance text, and never inside it: a proposal carries only the text.
+    // Any complete catalog line counts, so a paste that drops the header is refused too.
+    const bullets = this.widgetCatalog().split('\n').slice(1).filter((l) => l.trim());
+    if (bullets.some((l) => clean.includes(l))) throw new InboxError(400, 'the proposal includes the widget catalog, which the inbox adds beside the guidance text and which is not part of it: propose the text without those lines');
+    const from = by ? String(by.agent ?? '').trim() : '';
+    if (from.length > 80) throw new InboxError(400, 'agent must be at most 80 characters');
+    if (from === SYSTEM_AGENT) throw new InboxError(403, 'the system agent is reserved');
+    const base = this.guidance();
+    const id = `guidance-${randomId(4)}`;
+    const cardText = `${from ? `The agent ${from}` : 'An agent'} proposes this guidance for writing cards. It goes out only if you approve it.\n\n${clean}`;
+    // The card keeps no list of agents: the page lists the online ones from live presence when it draws the card, and
+    // an offline agent reads the new version when it reconnects or calls card_guidance.
+    const broadcast = { text: clean, message: why, ...(from ? { from } : {}), base: { version: base.version, text: base.text } };
+    // The stored card has the proposal in its text and in broadcast, and the guidance it starts from, so it is measured
+    // whole before anything is stored. The margin covers the card's other fields, which stay under a kilobyte.
+    const size = new TextEncoder().encode(JSON.stringify({ text: cardText, broadcast })).length + 2048;
+    if (size > MAX_CARD_BYTES) throw new InboxError(413, `the guidance card would be ${size} bytes, over the limit of ${MAX_CARD_BYTES}: propose a shorter text`);
+    this.postCard({ token: '', role: 'owner' }, {
+      id, agent: SYSTEM_AGENT, kind: 'system', deliver: 'none', priority: this.priorities()[0]?.id,
+      title: 'Send new card guidance to agents?',
+      text: cardText,
+      options: [{ id: 'approve', label: 'Approve and send' }, { id: 'reject', label: 'Reject' }],
+    });
+    const card       = {
+      ...this.getCard(id),
+      ...(from && by?.caller.token ? { token: by.caller.token } : {}),
+      broadcast,
+    };
+    this.store.put('cards', id, card);
+    this.emit({ type: 'change', card: id });
+    return card;
+  }
+
+  /** Apply or drop the proposed guidance, close the card, and send the answer to the agent that proposed the text. */
+          resolveBroadcast(card      , answer        )       {
+    if (!card.broadcast) return;
+    this.closeAs(card, 'resolved', this.applyBroadcast(card.broadcast, answer));
+    if (card.broadcast.from) this.flush(card.broadcast.from);
+  }
+
+          applyBroadcast(broadcast                                , answer        )         {
+    if ([answer.values['choice']].flat()[0] !== 'approve') return 'Rejected: the guidance did not change.';
+    // The ticked agents, or every connected one when the answer names none. Only connected agents get the event.
+    const picked = Array.isArray(answer.values['agents']) ? new Set((answer.values['agents']             ).map(String)) : undefined;
+    const guidance           = { text: broadcast.text, version: this.guidance().version + 1, at: this.now() };
+    this.store.put('meta', 'guidance', guidance);
+    let sent = 0;
+    for (const [k, subs] of this.agents) {
+      const agent = k.slice(k.indexOf('\n') + 1);
+      if (picked && !picked.has(agent)) continue;
+      for (const send of subs) send({ type: 'guidance', id: randomId(6), guidance });
+      sent++;
+    }
+    return `Sent guidance version ${guidance.version} to ${sent} connected agent${sent === 1 ? '' : 's'}. The others get it when they connect.`;
+  }
+
+  /** The cards a client may read, with their states: all of them for the owner. */
+  listCards(caller        )                                     {
+    return this.store.list      ('cards')
+      .filter((c) => caller.role === 'owner' || c.token === caller.token)
+      .map((c) => ({ card: publicCard(c), state: cardState(c, this.store.get        ('answers', c.id)) }));
+  }
+
+  /** The title, text preview and clear time of each card the caller may read, by id, for the card links on screen.
+   * A cleared card leaves the state but stays stored until the purge, so its links still name it. Ids it never stored are left out. */
+  linkedCards(caller        , ids          )                                                                           {
+    if (ids.length > MAX_LOOKUP) throw new InboxError(400, `name at most ${MAX_LOOKUP} card ids`);
+    const out                                                                       = [];
+    for (const id of ids) {
+      const card = this.store.get      ('cards', id);
+      if (!card || (caller.role !== 'owner' && card.token !== caller.token)) continue;
+      out.push([id, { title: card.title, ...(card.text ? { preview: card.text.slice(0, 300) } : {}), ...(card.archivedAt ? { archivedAt: card.archivedAt } : {}) }]);
+    }
+    // fromEntries makes every id an own key, even one named like an Object property.
+    return Object.fromEntries(out);
+  }
+
+          owned(caller        , id        )       {
+    const card = this.getCard(id);
+    if (caller.role !== 'owner' && card.token !== caller.token) throw new InboxError(403, 'another client owns this card');
+    return card;
+  }
+
+          closeAs(card      , kind           , outcome        , draft        )       {
+    const current = this.getCard(card.id);
+    // A card closed while triage checks it needs no verdict any more.
+    const triage = current.triage?.state === 'pending' ? { ...current.triage, state: 'skipped'         , waiting: [], reason: 'The card closed before triage answered.' } : current.triage;
+    // A draft the person recorded stays with the card, whoever closes it next, so their words are never lost.
+    const kept = draft ?? current.closed?.draft;
+    const closed       = { ...current, triage, closed: { kind, outcome, at: this.now(), ...(kept ? { draft: kept } : {}) } };
+    this.store.put('cards', card.id, closed);
+    this.emit({ type: 'change', card: card.id });
+    return closed;
+  }
+
+  /** The agent retracts its card or answers it itself. */
+  close(caller        , id        , kind           , outcome        , ifUnanswered = false)       {
+    const card = this.owned(caller, id);
+    if (!CLOSE_KINDS.has(kind)) throw new InboxError(400, 'unknown close kind');
+    const answer = this.store.get        ('answers', id);
+    if (ifUnanswered && answer) throw new InboxError(409, 'the person already answered this card');
+    return this.closeAs(card, kind, String(outcome || '').slice(0, 2000) || 'No outcome given.');
+  }
+
+  /** The person dismisses a card: it closes without the agent hearing anything, and the form values and the comment on
+   * screen are recorded with the time, even when both are empty. No answer is stored, so no stream receives an event, and
+   * a revision the agent sends later is saved but leaves the card in Sent. Only the owner reads the draft. */
+  dismiss(caller        , id        , input                                          = {})       {
+    if (caller.role !== 'owner') throw new InboxError(403, 'only the owner dismisses a card');
+    const card = this.getCard(id);
+    if (card.closed) throw new InboxError(409, 'this card is already closed');
+    // A secret field holds the secret itself, and a dismissal is not an answer to seal it, so it stays out of the record.
+    // The other fields and the comment are the person's own words about the card, so they stay.
+    const sealed = sealedFields(card);
+    const values = !input.values || typeof input.values !== 'object' || Array.isArray(input.values)
+      ? {} : Object.fromEntries(Object.entries(input.values                           ).filter(([k]) => !sealed.includes(k)));
+    return this.closeAs(card, 'dismissed', 'Nothing was sent to the agent.', { values, comment: String(input.comment ?? '').trim(), at: this.now() });
+  }
+
+  /** A successor agent takes over a card, and with it any answer not yet delivered. */
+  claim(caller        , id        , agent        )       {
+    const card = this.getCard(id);
+    if (caller.role !== 'owner' && card.token !== caller.token) throw new InboxError(403, 'another client owns this card');
+    const token = caller.role === 'owner' ? card.token : caller.token;
+    // A guidance card stays the inbox's system card: the successor takes over as the agent that proposed the text.
+    const next = card.kind === 'system' && card.broadcast
+      ? { ...card, token, broadcast: { ...card.broadcast, from: String(agent) } }
+      : { ...card, agent: String(agent), token };
+    this.store.put('cards', id, next);
+    this.emit({ type: 'change', card: id });
+    this.flush(String(agent));
+    return next;
+  }
+
+  // ---- answers ----
+
+  async answer(id        , input                                                                                                                                                )                  {
+    const posted = this.getCard(id);
+    const delivery = input.delivery ?? 'default';
+    if (!DELIVERIES.has(delivery)) throw new InboxError(400, 'unknown delivery');
+    const values = input.values && typeof input.values === 'object' ? { ...input.values } : {};
+    if (input.images !== undefined && !Array.isArray(input.images)) throw new InboxError(400, 'images must be a list');
+    // A secret field takes only a sealed value, so plain text never reaches storage. An empty one declines.
+    for (const field of sealedFields(posted)) {
+      // An own property only: a field named like an inherited one, such as constructor, is empty when the answer leaves it out.
+      const v = Object.hasOwn(values, field) ? values[field] : undefined;
+      if (v === undefined || v === null || v === '') delete values[field];
+      else if (!isSealed(v)) throw new InboxError(400, `${field} takes only a sealed value: seal it with the public key on the card`);
+      if (input.images?.some((f) => f?.field === field)) throw new InboxError(400, `${field} takes no images`);
+    }
+    // A pairing request takes a code and its card goes a day later, and the sweep deletes the answer without its
+    // files, so an image here would be stored bytes nothing can name again. The stored pairing decides, not the id:
+    // an agent may post a card of its own called `pair-something`, and that one is neither swept nor a request.
+    const request = posted.id.startsWith('pair-') && this.store.get         ('pairings', posted.id.slice('pair-'.length));
+    if (request && input.images?.length) throw new InboxError(400, 'a pairing request takes a code, not images');
+    const { images, refund } = await this.storeAnswerImages(posted, input.images);
+    let card      ;
+    try {
+      // Storing images awaited, so another session may have claimed the card while the files were written. Read it
+      // again, and deliver to whoever holds it now: the claim's own flush ran before this answer existed.
+      card = this.getCard(id);
+    } catch (e) {
+      // The card went while the files were written, as `reset` does, so nothing will ever name these files: give the
+      // bytes back rather than leave them charged against the inbox's lifetime upload limit.
+      await refund();
+      throw e;
+    }
+    const before = this.store.get        ('answers', id);
+    const answer         = {
+      card: id,
+      version: Number(input.version ?? card.version),
+      values,
+      comment: String(input.comment ?? '').trim(),
+      ...(images.length ? { images } : {}),
+      delivery,
+      savedAt: this.now(),
+      deliveredAt: null,
+      readAt: null,
+      forcedAt: null,
+      previous: before ? [...before.previous, { ...before, previous: undefined }                            ] : [],
+    };
+    const responses = (card.responses ?? []).map((r) => respond(r.template, values, r.values)).filter(Boolean);
+    if (responses.length) answer.responses = responses;
+    // An approval sent for this version of the card stays sent, so a second answer never types it again.
+    const kept = before && before.version === answer.version ? (before.approvalResults ?? []).map((r) => (r && !('error' in r) ? r : null)) : [];
+    if (kept.some(Boolean)) answer.approvalResults = kept;
+    for (const p of answer.previous) delete (p                   ).previous;
+    this.store.put('answers', id, answer);
+    this.store.index(id, `${searchText(card)}\n${answer.comment}`);
+    this.usage.record('answers');
+    this.emit({ type: 'change', card: id });
+    if (card.kind === 'system' && card.id.startsWith('pair-')) await this.resolvePairing(card, answer);
+    else if (card.kind === 'system' && card.broadcast) this.resolveBroadcast(card, answer);
+    else if (card.kind === 'system' && card.id.startsWith('priorities-')) this.resolvePriorityProposal(card, answer);
+    else if (card.kind === 'system' && card.subscription) this.resolveSubscription(card, answer);
+    else this.flush(card.agent);
+    if (card.kind !== 'system') {
+      const saved = this.store.get        ('answers', id) ?? answer;
+      this.observeAnswer(card, saved);
+      this.queueAnswer(card, saved);
+    }
+    return this.store.get        ('answers', id) ?? answer;
+  }
+
+  /** Type each approval the owner turned on in the card's answer into its pane, once per card version, and record what
+   * happened on the answer. Only an owner's answer sends: an agent's call returns the answer unchanged. */
+  async sendApprovals(caller        , id        )                              {
+    const answer = this.store.get        ('answers', id);
+    const sender = this.approvalSender;
+    const card = this.store.get      ('cards', id);
+    if (!sender || caller.role !== 'owner' || !answer || !card?.approvals?.length) return answer;
+    const approvals = card.approvals;
+    const results                   = approvals.map((_, i) => answer.approvalResults?.[i] ?? null);
+    const claimed           = [];
+    approvals.forEach((_, i) => {
+      const r = results[i];
+      if (answer.values[`approval_${i}`] !== true || (r && !('error' in r))) return;
+      // The person read other sentences on the version they answered, so the inbox sends none of the new ones.
+      if (answer.version !== card.version) { results[i] = { error: 'the card changed after you answered it: answer it again to send this' }; return; }
+      results[i] = { sendingAt: this.now() };
+      claimed.push(i);
+    });
+    if (!results.some(Boolean)) return answer;
+    // The claim is written before the first await, so an answer saved meanwhile carries it and never sends again.
+    this.store.put('answers', id, { ...answer, approvalResults: results });
+    this.emit({ type: 'change', card: id });
+    for (const i of claimed) {
+      const a = approvals[i] ;
+      let result                ;
+      try {
+        await sender.send(a.pane, a.text);
+        result = { sentAt: this.now() };
+      } catch (e) {
+        result = { error: e instanceof Error ? e.message : String(e) };
+      }
+      this.recordApproval(id, answer.version, i, result);
+    }
+    return this.store.get        ('answers', id);
+  }
+
+  /** Replace the claim on one approval with what the send did, on whichever answer to that card version is current. */
+          recordApproval(id        , version        , i        , result                )       {
+    const answer = this.store.get        ('answers', id);
+    const claim = answer?.approvalResults?.[i];
+    if (!answer || answer.version !== version || !claim || !('sendingAt' in claim)) return;
+    const results = [...(answer.approvalResults ?? [])];
+    results[i] = result;
+    this.store.put('answers', id, { ...answer, approvalResults: results });
+    this.emit({ type: 'change', card: id });
+  }
+
+  /** What herdr says about each approval's pane, one entry per approval, empty when herdr does not know the pane. */
+          async describePanes(approvals            )                                             {
+    const describe = this.approvalSender?.describe?.bind(this.approvalSender);
+    if (!describe) return approvals.map(() => undefined);
+    return Promise.all(approvals.map((a) => describe(a.pane).catch(() => undefined)));
+  }
+
+  /** A card's approvals, checked. A place comes only from `places`, which herdr answered, so an agent cannot set one. */
+          cleanApprovals(input         , kind        , places                                    )                         {
+    if (input === undefined || input === null) return undefined;
+    if (!this.approvalSender) throw new InboxError(400, 'this inbox does not send approvals: only an inbox on the computer that runs herdr types into a pane');
+    if (kind !== 'ask') throw new InboxError(400, 'only an ask card takes approvals');
+    if (!Array.isArray(input)) throw new InboxError(400, 'approvals must be a list of {pane, text, label}');
+    if (input.length > MAX_APPROVALS) throw new InboxError(400, `a card takes at most ${MAX_APPROVALS} approvals`);
+    if (!input.length) return undefined;
+    return input.map((a         , i)           => {
+      const at = `approval ${i + 1}`;
+      if (!a || typeof a !== 'object') throw new InboxError(400, `${at}: must be an object with pane and text`);
+      const { pane, text, label } = a                           ;
+      if (typeof pane !== 'string' || !PANE_ID.test(pane)) throw new InboxError(400, `${at}: pane must be a herdr pane id, such as w6P:p2`);
+      if (typeof text !== 'string' || !text.trim()) throw new InboxError(400, `${at}: text must be the message to send`);
+      if (text.length > MAX_APPROVAL_CHARS) throw new InboxError(400, `${at}: text must be at most 1,000 characters`);
+      // herdr reads an argument that starts with a dash as an option, and takes no -- before the text.
+      if (text.startsWith('-')) throw new InboxError(400, `${at}: text must not start with a dash`);
+      if (label !== undefined && (typeof label !== 'string' || label.length > MAX_APPROVAL_LABEL_CHARS)) throw new InboxError(400, `${at}: label must be at most ${MAX_APPROVAL_LABEL_CHARS} characters`);
+      const kept = cleanPlace(places?.[i]);
+      return { pane, text, ...(label ? { label } : {}), ...(kept ? { place: kept } : {}) };
+    });
+  }
+
+  /** Delete files a caller wrote and give their bytes back to the lifetime upload limit, for a write that cannot stand. */
+          async refundUploads(stored                   , bytes        )                {
+    await Promise.all(stored.map((f) => this.blobs.delete(f.id ?? '')));
+    this.store.put('meta', 'uploaded-bytes', Math.max(0, this.uploads().used - bytes));
+  }
+
+  /** Store the images pasted into an answer, and return their references. Each must be a base64 image of a type the page
+   * shows, within the attachment limit. The files count against the upload limit like a card's files. */
+          async storeAnswerImages(card      , input                                                    )                                                                 {
+    const none = { images: []                , refund: async ()                => {} };
+    if (input === undefined) return none;
+    if (!Array.isArray(input)) throw new InboxError(400, 'images must be a list');
+    if (input.length > MAX_ANSWER_IMAGES) throw new InboxError(400, `an answer takes at most ${MAX_ANSWER_IMAGES} images`);
+    const decoded = input.map((f, i) => {
+      if (!f || typeof f !== 'object' || !/^data:/.test(String(f.src ?? ''))) throw new InboxError(400, `image ${i + 1}: src must be a base64 data: URL`);
+      const d = decodeDataUrl(i, f);
+      if (!ANSWER_IMAGE_TYPES.has(d.type)) throw new InboxError(400, `image ${i + 1}${f.name ? ` (${cleanName(f.name)})` : ''} is ${d.type}: an answer takes only PNG, JPEG, GIF or WebP images`);
+      return d;
+    });
+    const bytes = decoded.reduce((n, d) => n + Math.max(d.bytes.length, MIN_FILE_CHARGE), 0);
+    const { used, limit } = this.uploads();
+    if (bytes > MAX_ANSWER_IMAGE_BYTES) throw new InboxError(413, `these images are ${bytes} bytes, and an answer takes at most ${MAX_ANSWER_IMAGE_BYTES}`);
+    if (limit !== undefined && used + bytes > limit) throw new InboxError(413, `these images are ${bytes} bytes, and this inbox has stored ${used} of its lifetime limit of ${limit} bytes`);
+    if (bytes) this.store.put('meta', 'uploaded-bytes', used + bytes);
+    const stored               = [];
+    // A caller that cannot keep the references deletes the files and gives the bytes back, as a card post does.
+    const refund = ()                => this.refundUploads(stored, bytes);
+    const settled = await Promise.allSettled(input.map(async (f, i)                => {
+      const d = decoded[i] ;
+      const key = `${card.id}.a${i}.${randomId(6)}`;
+      const ref             = { id: key, name: cleanName(f.name) || `pasted-${i + 1}.${d.type.slice(6).replace('jpeg', 'jpg')}`, type: d.type, size: d.bytes.length, ...(f.field ? { field: String(f.field).slice(0, 80) } : {}) };
+      stored.push(ref);
+      await this.blobs.put(key, d.bytes, d.type);
+    }));
+    const failed = settled.find((r) => r.status === 'rejected');
+    if (failed) {
+      await refund();
+      throw (failed                         ).reason;
+    }
+    return { images: stored, refund };
+  }
+
+  /** The model has the answer in its context. */
+  ack(caller        , id        )         {
+    this.owned(caller, id);
+    const answer = this.store.get        ('answers', id);
+    if (!answer) throw new InboxError(404, 'no answer for this card');
+    if (!answer.readAt) {
+      const next = { ...answer, readAt: this.now(), deliveredAt: answer.deliveredAt ?? this.now() };
+      this.store.put('answers', id, next);
+      this.emit({ type: 'change', card: id });
+      return next;
+    }
+    return answer;
+  }
+
+  /** Send an unread answer again, marked to interrupt the agent. */
+  force(id        )         {
+    const answer = this.store.get        ('answers', id);
+    if (!answer) throw new InboxError(404, 'no answer for this card');
+    if (answer.readAt) return answer;
+    const next         = { ...answer, delivery: 'force', deliveredAt: null, forcedAt: this.now() };
+    this.store.put('answers', id, next);
+    this.emit({ type: 'change', card: id });
+    const card = this.getCard(id);
+    this.flush(recipient(card, next) ?? card.agent);
+    // A webhook call that waits for its retry goes now. A call still running keeps its lease, so it never goes twice at once.
+    const now = this.now();
+    for (const d of this.store.list            ('outbox')) {
+      if (d.card === id && !(d.calling && d.nextAt > now)) this.store.put            ('outbox', d.key, { ...d, nextAt: Math.min(d.nextAt, now) });
+    }
+    this.track(this.deliverAnswers());
+    return this.store.get        ('answers', id) ?? next;
+  }
+
+  /** Answers that wait for an agent that is offline. Agents query and claim them. */
+  deadLetters()                                   {
+    return this.store.list        ('answers')
+      .filter((a) => !a.deliveredAt)
+      .map((a) => ({ card: this.getCard(a.card), answer: a }))
+      .filter(({ card, answer }) => { const to = recipient(card, answer); return to !== null && !this.isOnline(to); });
+  }
+
+  /** The answers this caller has not consumed: stored, and never acknowledged. `agent` narrows it to one agent, which
+   * is what a watcher asks about. The ids come with the count, so a caller can acknowledge them without a second read. */
+  unread(caller        , agent         )                                      {
+    const mine = this.store.list        ('answers')
+      .filter((a) => !a.readAt)
+      .filter((a) => {
+        const card = this.store.get      ('cards', a.card);
+        if (!card) return false;
+        // A guidance card closes as the person answers it, and its answer waits for the agent that proposed the text.
+        const guidance = card.kind === 'system' && card.broadcast;
+        if (guidance ? recipient(card, a) === null : cardState(card, a) === 'closed') return false;
+        if (caller.role !== 'owner' && card.token !== caller.token) return false;
+        return agent === undefined || (guidance ? card.broadcast?.from : card.agent) === agent;
+      })
+      .map((a) => a.card)
+      .sort();
+    return { unread: mine.length, cards: mine.slice(0, UNREAD_ID_LIMIT) };
+  }
+
+  /** Cards that match the words, best first. `answered` keeps only cards the person answered. */
+  search(query        , limit = 20, answered = false)                                    {
+    const hits = this.store.search(String(query || ''), answered ? Math.max(limit * 5, 100) : limit);
+    return hits
+      .filter((h) => !answered || this.store.get('answers', h.card))
+      .slice(0, limit)
+      .map((h) => ({ card: this.store.get      ('cards', h.card), answer: this.store.get        ('answers', h.card) }))
+      .filter((r)                                                  => !!r.card)
+      .map(({ card, answer }) => (answer ? { card: publicCard(card), answer } : { card: publicCard(card) }));
+  }
+
+  /** This inbox's stable identity, the same over every link to it. */
+  id()         {
+    let id = this.store.get        ('meta', 'inbox-id');
+    if (!id) { id = randomId(8); this.store.put('meta', 'inbox-id', id); }
+    return id;
+  }
+
+  /** The stored result of a message this client sent before, by its id. */
+  recallMessage(key        )                                               {
+    const m = this.store.get                                              ('messages', key);
+    // A reservation whose request died, such as in a crash, lets the message be applied again.
+    if (m && m.status === 0 && this.now() - m.at > MESSAGE_RESERVATION_MS) return undefined;
+    return m;
+  }
+
+  rememberMessage(key        , status        , body        )       {
+    this.store.put('messages', key, { key, status, body, at: this.now() });
+  }
+
+  forgetMessage(key        )       {
+    this.store.delete('messages', key);
+  }
+
+  // ---- default tags ----
+
+  /** The default tags this caller set for one agent id. A token reads only the defaults it set itself. */
+  defaultTags(caller        , agent        )              {
+    if (caller.role !== 'agent') throw new InboxError(403, 'only an agent reads its own default tags');
+    const id = this.agentId(agent);
+    return { agent: id, tags: this.storedTags(caller.token, id) };
+  }
+
+  /** Set, merge, remove or clear the default tags this caller keeps for one agent id. Every card that agent posts
+   * inherits them, under its own tags. */
+  setDefaultTags(caller        , input                           )              {
+    if (caller.role !== 'agent') throw new InboxError(403, 'only an agent sets its own default tags');
+    const agent = this.agentId(input.agent);
+    const from = input.from === undefined ? 'card_tags' : String(input.from);
+    if (!/^[A-Za-z_][\w.-]{0,39}$/.test(from)) throw new InboxError(400, 'from must be 1 to 40 letters, digits, dots, dashes or underscores');
+    const key = `tags:${caller.token}`;
+    const row = this.store.get               ('meta', key);
+    const agents = { ...(row?.agents ?? {}) };
+    const tags                             = input.clear === true ? {} : { ...(agents[agent] ?? {}) };
+    if (input.tags !== undefined) {
+      if (!input.tags || typeof input.tags !== 'object' || Array.isArray(input.tags)) throw new InboxError(400, 'tags must be an object of tag keys and values');
+      for (const [k, v] of Object.entries(input.tags)) {
+        if (!k) throw new InboxError(400, 'each tag needs a key');
+        if (k.length > MAX_TAG_CHARS) throw new InboxError(400, `tag key ${k.slice(0, 20)}… must be at most ${MAX_TAG_CHARS} characters`);
+        const value = String(v ?? '');
+        if (!value) throw new InboxError(400, `tag ${k} has an empty value: leave it out, or remove it`);
+        if (value.length > MAX_TAG_CHARS) throw new InboxError(400, `tag ${k} must be at most ${MAX_TAG_CHARS} characters`);
+        tags[k] = { value, from };
+      }
+    }
+    if (input.remove !== undefined) {
+      if (!Array.isArray(input.remove)) throw new InboxError(400, 'remove must be a list of tag keys');
+      for (const k of input.remove.map(String)) delete tags[String(k)];
+    }
+    if (Object.keys(tags).length > MAX_TAGS) throw new InboxError(400, `an agent keeps at most ${MAX_TAGS} default tags`);
+    if (Object.keys(tags).length) agents[agent] = tags;
+    else delete agents[agent];
+    if (Object.keys(agents).length) this.store.put               ('meta', key, { token: caller.token, agents, at: this.now() });
+    else this.store.delete('meta', key);
+    return { agent, tags };
+  }
+
+  /** Every token's default tags, or one agent's, for the owner. */
+  defaultTagsList(caller        , agent         )                                                                       {
+    if (caller.role !== 'owner') throw new InboxError(403, 'only the owner reads every default tag');
+    const out                                                                       = [];
+    for (const row of this.store.list               ('meta')) {
+      if (typeof row?.token !== 'string' || !row.agents) continue;
+      for (const [id, tags] of Object.entries(row.agents)) {
+        if ((agent === undefined || id === agent) && tags && Object.keys(tags).length) out.push({ token: row.token, agent: id, tags });
+      }
+    }
+    return out;
+  }
+
+  /** The tag keys a post by this caller takes from its defaults, read after the card commits. The route names them in
+   * the reply, so an agent knows what it inherited without reading the card back. */
+  inheritedTags(caller        , input         )           {
+    if (caller.token === '' || (input.kind ?? 'ask') === 'system') return [];
+    return mergeDefaultTags(this.tagValues(caller.token, String(input.agent ?? '').trim()), ownTags(input.tags)).inherited;
+  }
+
+  /** The defaults this token keeps for one agent id, by value. */
+          tagValues(token        , agent        )                         {
+    return Object.fromEntries(Object.entries(this.storedTags(token, agent)).map(([k, t]) => [k, t.value]));
+  }
+
+          storedTags(token        , agent        )                             {
+    return this.store.get               ('meta', `tags:${token}`)?.agents?.[agent] ?? {};
+  }
+
+          agentId(agent         )         {
+    const id = String(agent ?? '').trim();
+    if (!id) throw new InboxError(400, 'agent is required');
+    if (id.length > 80) throw new InboxError(400, 'agent must be at most 80 characters');
+    return id;
+  }
+
+  // ---- connections ----
+
+          key(token        , agent        )         {
+    return `${token}\n${agent}`;
+  }
+
+  isOnline(agent        )          {
+    return this.store.get          ('presence', agent)?.online ?? false;
+  }
+
+  /** An agent connects. `instance` names the agent process, and stays the same across its reconnects. `resumed` marks a
+   * connection the platform rebuilt for a socket that stayed open, such as a Durable Object waking from hibernation:
+   * the agent already got its `hello` on that socket, so it gets none again. `channelOff` says the session discards
+   * channel notifications, and a connection that leaves it out keeps what the last one said. */
+  connect(caller        , agent        , send           , instance         , opts                                              = {})             {
+    if (String(agent).length > 80) throw new InboxError(400, 'agent must be at most 80 characters');
+    const k = this.key(caller.token, agent);
+    let set = this.agents.get(k);
+    if (!set) this.agents.set(k, (set = new Set()));
+    set.add(send);
+    if (instance) this.instances.set(send, instance);
+    this.usage.saw('agents', agent);
+    if (instance) this.usage.saw('instances', instance);
+    if (caller.token) this.usage.saw('tokens', caller.token);
+    this.setPresence(agent, true, opts.channelOff);
+    if (!opts.resumed) send({ type: 'hello', agent, version: 1, guidance: this.guidance().version });
+    this.flush(agent);
+    if (instance) this.resend(caller.token, agent, send, instance);
+    return () => {
+      const s = this.agents.get(k);
+      if (!s?.delete(send)) return;
+      if (s.size === 0) this.agents.delete(k);
+      const stillOpen = [...this.agents.keys()].some((x) => x.endsWith(`\n${agent}`));
+      if (!stillOpen) this.putPresence(agent, { online: true, lastSeen: this.now(), leftAt: this.now() });
+    };
+  }
+
+  /** `channelOff` is undefined for a connection that says nothing about the channel, which keeps what is stored. */
+          setPresence(agent        , online         , channelOff          )       {
+    const before = this.store.get          ('presence', agent);
+    const off = channelOff ?? before?.channelOff;
+    const next           = { ...before, agent, online, lastSeen: this.now() };
+    delete next.channelOff;
+    if (off) next.channelOff = true;
+    // A live connection has no closing time, and one left from an earlier close would arm the alarm for a past moment.
+    if (online) delete next.leftAt;
+    this.store.put          ('presence', agent, next);
+    this.emit({ type: 'presence', agent, online });
+  }
+
+  /** Write a presence change over what is stored, so the fields a change does not name stay. */
+          putPresence(agent        , change                   )       {
+    const before = this.store.get          ('presence', agent);
+    this.store.put          ('presence', agent, { ...before, agent, online: false, lastSeen: this.now(), ...change });
+  }
+
+  /** Send a new agent process each answer an earlier process received but never read, such as one a session got before it restarted. */
+          resend(token        , agent        , send           , instance        )       {
+    for (const answer of this.store.list        ('answers')) {
+      if (!answer.deliveredAt || answer.readAt || answer.deliveredTo?.includes(instance)) continue;
+      const card = this.store.get      ('cards', answer.card);
+      if (!card || recipient(card, answer) !== agent || (card.token ?? '') !== token) continue;
+      const next         = { ...answer, deliveredTo: [...(answer.deliveredTo ?? []), instance] };
+      this.store.put('answers', answer.card, next);
+      send({ type: 'answer', id: randomId(6), card: publicCard(card), answer: next });
+    }
+  }
+
+  /** Deliver each answer the agent has not received yet. */
+          flush(agent        )       {
+    for (const answer of this.store.list        ('answers')) {
+      if (answer.deliveredAt) continue;
+      const card = this.store.get      ('cards', answer.card);
+      if (!card || recipient(card, answer) !== agent) continue;
+      const subs = this.agents.get(this.key(card.token ?? '', agent));
+      if (!subs || subs.size === 0) continue;
+      const to = [...subs].map((f) => this.instances.get(f)).filter((x)              => !!x);
+      const next         = { ...answer, deliveredAt: this.now(), ...(to.length ? { deliveredTo: to } : {}) };
+      this.store.put('answers', answer.card, next);
+      const ev             = { type: 'answer', id: randomId(6), card: publicCard(card), answer: next };
+      for (const send of subs) send(ev);
+      this.emit({ type: 'change', card: card.id });
+    }
+  }
+
+  /** A page opens its event stream. `viewer` is the page's own id, for its presence reports. */
+  subscribePage(send          , viewer         , guard                                                    )             {
+    this.pages.add(send);
+    if (guard) this.guarded.set(send, guard);
+    if (viewer) this.usage.saw('pages', viewer);
+    if (viewer) { this.viewers.set(viewer, this.viewers.get(viewer) ?? { visible: true, activeAt: this.now(), focus: null }); this.personChanged(); }
+    // A socket that wakes after the PIN changed closes at once.
+    if (guard && this.pin.isSet() && !this.pin.live(guard.unlock)) queueMicrotask(() => this.closeLockedPages());
+    return () => {
+      this.pages.delete(send);
+      this.guarded.delete(send);
+      if (viewer && this.viewers.delete(viewer)) this.personChanged();
+    };
+  }
+
+  /** A page reports whether it is visible, that the person did something, and the card on its screen. */
+  reportViewer(viewer        , report                                                                )                 {
+    if (!/^[\w-]{4,64}$/.test(String(viewer))) throw new InboxError(400, 'viewer must be 4 to 64 letters, digits, dashes or underscores');
+    const before = this.viewers.get(viewer) ?? { visible: true, activeAt: null, focus: null };
+    const next = {
+      visible: typeof report.visible === 'boolean' ? report.visible : before.visible,
+      activeAt: report.active ? this.now() : before.activeAt,
+      focus: report.focus === undefined ? before.focus : report.focus ? String(report.focus) : null,
+    };
+    this.viewers.set(viewer, next);
+    // Extensions hear about a change in what the person sees, not about every keypress.
+    if (next.visible !== before.visible || next.focus !== before.focus) return this.personChanged();
+    const person = this.person();
+    this.store.put('meta', 'person', person);
+    return person;
+  }
+
+  person()                 {
+    const views = [...this.viewers.values()];
+    const shown = views.filter((v) => v.visible).sort((a, b) => (b.activeAt ?? 0) - (a.activeAt ?? 0));
+    const activeAt = views.reduce               ((m, v) => (v.activeAt !== null && (m === null || v.activeAt > m) ? v.activeAt : m), null);
+    return { pages: views.length, visible: shown.length > 0, activeAt, focus: shown[0]?.focus ?? null, at: this.now() };
+  }
+
+          personChanged()                 {
+    const person = this.person();
+    this.store.put('meta', 'person', person);
+    const event            = { type: 'hook', version: HOOK_VERSION, id: randomId(8), hook: 'person.changed', person };
+    for (const e of this.extensions.values()) if (e.reg.hooks.includes('person.changed')) e.send(event);
+    return person;
+  }
+
+  /** The page code changed: open pages reload and keep their drafts. */
+  announceCode()       {
+    this.emit({ type: 'code' });
+  }
+
+          emit(ev           )       {
+    for (const send of this.pages) send(ev);
+  }
+
+  /** Called by the platform alarm: ends presence after its grace, forgets old message ids,
+   * resolves late hook calls, and expires pairing requests and cards. */
+  sweep()       {
+    const now = this.now();
+    for (const p of this.store.list          ('presence')) {
+      const open = [...this.agents.keys()].some((x) => x.endsWith(`\n${p.agent}`));
+      if (p.online && p.leftAt !== undefined && now - p.leftAt >= PRESENCE_GRACE_MS && !open) {
+        // The agent was last seen when its connection closed, not when the alarm noticed.
+        this.putPresence(p.agent, { online: false, lastSeen: p.leftAt });
+        this.emit({ type: 'presence', agent: p.agent, online: false });
+      } else if (!p.online && now - (p.leftAt ?? p.lastSeen) >= PRESENCE_KEEP_MS) {
+        // The row of an agent gone this long only makes GET /v1/state bigger. A reconnect writes a fresh one.
+        this.store.delete('presence', p.agent);
+      }
+    }
+    // Download counts from earlier days go.
+    const today = `reads:${new Date(now).toISOString().slice(0, 10)}:`;
+    for (const m of this.store.list         ('meta')) {
+      const key = (m                     )?.key;
+      if (typeof key === 'string' && key.startsWith('reads:') && !key.startsWith(today)) this.store.delete('meta', key);
+      const expiresAt = (m                           )?.expiresAt;
+      if (typeof key === 'string' && key.startsWith('signin:') && typeof expiresAt === 'number' && expiresAt <= now) this.store.delete('meta', key);
+    }
+    this.pin.sweep();
+    for (const m of this.store.list                             ('messages')) {
+      if (now - m.at > MESSAGE_MEMORY_MS) this.store.delete('messages', m.key);
+    }
+    for (const card of this.store.list      ('cards')) {
+      const t = card.triage;
+      if (t?.state === 'pending' && t.deadline && t.deadline <= now) {
+        const late = (t.waiting ?? []).join(', ') || 'triage';
+        const triage = t.policy === 'fail-closed'
+          ? { ...t, state: 'held'         , reason: `${late} did not answer in time, and its policy holds the card.`, waiting: [], at: now }
+          : { ...t, state: 'passed'         , reason: `${late} did not answer in time, so the card went through.`, waiting: [], at: now };
+        this.store.put('cards', card.id, { ...card, triage });
+        this.emit({ type: 'change', card: card.id });
+      }
+      if (card.expiresAt && card.expiresAt <= now && !card.closed && !this.store.get('answers', card.id)) {
+        this.closeAs(card, 'expired', 'The agent stopped waiting for an answer.');
+      }
+    }
+    for (const p of this.store.list         ('pairings')) {
+      if (now - p.createdAt >= PAIRING_KEEP_MS) {
+        // A day later, the request and its card go, so pairing requests cannot pile up.
+        this.store.delete('pairings', p.id);
+        this.store.delete('cards', `pair-${p.id}`);
+        this.store.delete('answers', `pair-${p.id}`);
+        this.store.index(`pair-${p.id}`, '');
+        this.emit({ type: 'change', card: `pair-${p.id}` });
+        continue;
+      }
+      if (now - p.createdAt < PAIRING_TTL_MS) continue;
+      // A token nobody collected in time is dropped, so its secret never stays in storage.
+      if (p.secret) {
+        const { secret: _s, ...rest } = p;
+        this.store.put         ('pairings', p.id, rest);
+        continue;
+      }
+      if (p.status !== 'pending') continue;
+      this.store.put         ('pairings', p.id, { ...p, status: 'denied' });
+      const card = this.store.get      ('cards', `pair-${p.id}`);
+      if (card && !card.closed) this.closeAs(card, 'resolved', 'The pairing request expired.');
+    }
+  }
+
+  /** Everything a page needs to draw the inbox. */
+  /** Clear the cards you dealt with: answered, retracted or closed. Search still finds them. */
+  archive(caller        )                       {
+    if (caller.role !== 'owner') throw new InboxError(403, 'only the owner clears the inbox');
+    const now = this.now();
+    let archived = 0;
+    for (const card of this.store.list      ('cards')) {
+      if (card.archivedAt) continue;
+      const answer = this.store.get        ('answers', card.id);
+      const s = cardState(card, answer);
+      if (!['closed', 'answered', 'delivered', 'read'].includes(s)) continue;
+      this.store.put('cards', card.id, { ...card, archivedAt: now });
+      archived++;
+    }
+    if (archived) this.emit({ type: 'change', card: '' });
+    return { archived };
+  }
+
+  /** Remove every card, answer and attached file. Tokens, templates, widgets, settings and guidance stay. */
+  async reset(caller        )                               {
+    if (caller.role !== 'owner') throw new InboxError(403, 'only the owner resets the inbox');
+    const cards = this.store.list      ('cards');
+    for (const card of cards) await Promise.all(this.drop(card).map((f) => this.blobs.delete(f)));
+    this.emit({ type: 'change', card: '' });
+    return { removed: cards.length };
+  }
+
+  /** Called by the platform alarm after sweep(). Deletes the cards of `purgeQueue` whose 30 days are up, and the oldest
+   * others while the storage is past its headroom, at most PURGE_BATCH a pass. It removes what `reset` removes for each. */
+  async purge()                               {
+    const now = this.now();
+    const files           = [];
+    let removed = 0;
+    for (const { id, since } of this.purgeQueue()) {
+      if (removed >= PURGE_BATCH || (now - since < PURGE_AFTER_MS && !this.needsRoom())) break;
+      const card = this.store.get      ('cards', id);
+      if (!card) {
+        // A row whose card is gone would stay due forever, so it goes too.
+        this.store.delete('cleared', id);
+        this.store.delete('summaries', id);
+        continue;
+      }
+      files.push(...this.drop(card));
+      removed++;
+    }
+    // Every record goes before the first await, so no request sees half a batch.
+    if (removed) this.emit({ type: 'change', card: '' });
+    // The records are gone already, so a failed delete must not stop the alarm that called this. R2 deletes the file
+    // 30 days after its upload anyway, and a laptop retries the delete on its next pass.
+    const retry = this.store.get          ('meta', PENDING_FILE_DELETES) ?? [];
+    const settled = await Promise.allSettled([...retry, ...files].map((f) => this.blobs.delete(f)));
+    const failed = [...retry, ...files].filter((_, i) => settled[i]?.status === 'rejected').slice(0, PURGE_BATCH * 10);
+    if (failed.length) this.store.put('meta', PENDING_FILE_DELETES, failed);
+    else if (retry.length) this.store.delete('meta', PENDING_FILE_DELETES);
+    return { removed };
+  }
+
+  /** The cards the purge may delete, oldest first, each with the time its 30 days start: a cleared card from when the
+   * person cleared it, and a card nobody answered from its last revision. An answered card on show stays.
+   * It reads the summaries and the oldest PURGE_BATCH cleared rows: a pass deletes no more, and the later rows are newer.
+   * So its time follows the cards on show, never the cleared ones or the size of their text. */
+          purgeQueue()                                  {
+    const queue = this.store.first             ('cleared', PURGE_BATCH).map((c) => ({ id: c.id, since: c.archivedAt }));
+    for (const s of this.store.list             ('summaries')) {
+      if (!s.answer) queue.push({ id: s.id, since: s.updatedAt });
+    }
+    return queue.sort((a, b) => a.since - b.since);
+  }
+
+  /** Whether the storage holds more than its limit less the headroom the purge keeps free. */
+          needsRoom()          {
+    return this.storageLimit !== undefined && (this.store.bytes?.() ?? 0) > this.storageLimit * (1 - STORAGE_HEADROOM);
+  }
+
+  /** Delete a card's records and search entry, and return the ids of its files and answer images, for the caller to
+   * delete. The records go first: an answer that lands while the files are deleted then finds no card, and `answer`
+   * refunds the images it had already stored instead of leaving them where this list cannot name them. */
+          drop(card      )           {
+    const answer = this.store.get        ('answers', card.id);
+    const images = [answer, ...(answer?.previous ?? [])].flatMap((a) => a?.images ?? []);
+    this.store.delete('answers', card.id);
+    this.store.delete('cards', card.id);
+    this.store.index(card.id, '');
+    return [...(card.attachments ?? []), ...images].flatMap((f) => (f.id ? [f.id] : []));
+  }
+
+  /** GET /v1/state: a summary of each card the page shows, with the states, presence and levels. It reads only the
+   * summaries, so its time grows with the cards on show, never with the size of their text or the cleared ones. */
+  summaryState()   
+                                                                                                                                        
+                                                                                                        
+    {
+    const cards = this.store.list             ('summaries').sort((a, b) => a.createdAt - b.createdAt);
+    const answers                                = {};
+    for (const c of cards) if (c.answer) answers[c.id] = c.answer;
+    const presence = Object.fromEntries(this.store.list          ('presence').map((p) => [p.agent, p]));
+    const levels = this.priorities();
+    const states                            = {};
+    const priorities                         = {};
+    for (const c of cards) {
+      states[c.id] = this.shownState(c, presence[c.agent], c.answer);
+      priorities[c.id] = this.effectivePriority(c, levels, c.answer);
+    }
+    return { cards, answers, presence, states, priorities, levels, settings: this.settings(), guidance: this.guidance() };
+  }
+
+  /** GET /v1/cards/<id>: the whole card, its answer, its state, and the rev of its summary. `owner` keeps what only the
+   * person reads, such as the draft they left on a card they dismissed. */
+  cardDetail(id        , owner = false)                                                                  {
+    const card = this.getCard(id);
+    const answer = this.store.get        ('answers', id);
+    // A body stored before the inbox checked bodies may not draw whole, so the client gets what it can draw.
+    const fallback = card.body !== undefined ? this.fallbackBody?.(card.body) : undefined;
+    const summary = this.store.get             ('summaries', id);
+    const shown = owner && card.closed ? { ...publicCard(card), closed: card.closed } : publicCard(card);
+    return {
+      card: fallback ? { ...shown, bodyFallback: fallback } : shown,
+      ...(answer ? { answer } : {}),
+      state: this.shownState(card, this.store.get          ('presence', card.agent), answer),
+      ...(summary ? { rev: summary.rev } : {}),
+    };
+  }
+
+  /** Whether an open card's agent has left long ago, so another session can claim it. A row the sweep pruned counts as gone,
+   * and so does a card whose agent never connected, once the card itself is old enough. */
+          orphaned(c                    , s           , p                      , now        )          {
+    if (s !== 'open' || c.deliver !== 'stream') return false;
+    if (p) return !p.online && now - p.lastSeen > ORPHAN_MS;
+    return now - (c.updatedAt ?? c.createdAt) > ORPHAN_MS;
+  }
+
+  /** A card's state, with orphaned for an open card whose agent left long ago: another session can claim it. */
+          shownState(c                    , p                      , answer                                                                )            {
+    return this.orphaned(c, cardState(c, answer), p, this.now()) ? 'orphaned' : cardState(c, answer);
+  }
+
+  state()   
+                                                                                                                          
+                                                                                                        
+    {
+    const cards = this.store.list      ('cards').filter((c) => !c.archivedAt).map(publicCard).sort((a, b) => a.createdAt - b.createdAt)
+      // A body stored before the inbox checked bodies may not draw whole, so the page gets what it can draw.
+      .map((c) => { const f = c.body !== undefined ? this.fallbackBody?.(c.body) : undefined; return f ? { ...c, bodyFallback: f } : c; });
+    const shown = new Set(cards.map((c) => c.id));
+    const answers = Object.fromEntries(this.store.list        ('answers').filter((a) => shown.has(a.card)).map((a) => [a.card, a]));
+    const presence = Object.fromEntries(this.store.list          ('presence').map((p) => [p.agent, p]));
+    const now = this.now();
+    const states = Object.fromEntries(cards.map((c) => {
+      const s = cardState(c, answers[c.id]);
+      return [c.id, this.orphaned(c, s, presence[c.agent], now) ? 'orphaned' : s];
+    }));
+    const levels = this.priorities();
+    // The answers are read already, so each card costs no storage read of its own.
+    const priorities = Object.fromEntries(cards.map((c) => [c.id, this.effectivePriority(c, levels, answers[c.id])]));
+    return { cards, answers, presence, states, priorities, levels, settings: this.settings(), guidance: this.guidance() };
+  }
+}
+
+const TYPES_BY_EXTENSION                         = {
+  png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', gif: 'image/gif', webp: 'image/webp', pdf: 'application/pdf',
+  md: 'text/markdown', markdown: 'text/markdown', txt: 'text/plain', log: 'text/plain', csv: 'text/csv', json: 'application/json',
+  html: 'text/html', htm: 'text/html',
+};
+
+/** At most as many ids as a card's text links with [[card-id]]. */
+const MAX_LOOKUP = 20;
+const index = (i        )         => i + 1;
+
+/**
+ * Before cards had `dialog`, the Claude Code AskUserQuestion hook was the only poster of `questions`, and the channel and
+ * the herdr sidecar read `questions` as "this card has a terminal dialog". This marks each card that hook stored then, once
+ * per inbox, so an answer on a card still open at the upgrade closes its dialog. The hook posts ids `ask-<8 hex digits>`.
+ */
+function markDialogCards(store         )       {
+  if (store.get         ('meta', 'dialog-marked')) return;
+  for (const c of store.list      ('cards')) {
+    if (c.dialog === undefined && c.questions?.length && c.origin?.harness === 'claude-code' && /^ask-[0-9a-f]{8}$/.test(c.id)) store.put('cards', c.id, { ...c, dialog: true });
+  }
+  store.put('meta', 'dialog-marked', true);
+}
+
+/**
+ * Each option with an id, as a stored card always carries one. `card_post` documents an option as `{label, description,
+ * recommended}` and an agent may also post a plain label, so the inbox derives an id from the label when the post has
+ * none: the label in lowercase, each run of other characters as one dash, and a number when two options share a label.
+ * An id the agent gave stays as it is, and a derived id steps around every id the card already carries, so the ids
+ * are unique. A card that carries an answer or a draft gets none: its pick names a label.
+ */
+/**
+ * The same options for a card that carries an answer or a draft, which keeps the identity its pick names. No id is
+ * derived here, and an option whose label a stored option had keeps that option's id, so a re-post that resends the
+ * labels keeps the pick resolving.
+ */
+function withKeptOptionIds(options                      , before                  )                       {
+  if (!Array.isArray(options) || !before?.options) return options;
+  const byLabel = new Map(before.options.filter((o) => o && typeof o.id === 'string' && o.id).map((o) => [o.label, o.id ]));
+  return options.map((o) => {
+    if (!o || typeof o !== 'object' || (typeof o.id === 'string' && o.id)) return o;
+    const id = byLabel.get(o.label);
+    return id ? { ...o, id } : o;
+  });
+}
+
+function withOptionIds(options                      )                       {
+  if (!Array.isArray(options)) return options;
+  const taken = new Set        ();
+  for (const o of options) if (o && typeof o === 'object' && typeof o.id === 'string' && o.id) taken.add(o.id);
+  return options.map((o, i) => {
+    if (!o || typeof o !== 'object' || (typeof o.id === 'string' && o.id)) return o;
+    const label = typeof o.label === 'string' ? o.label : '';
+    const base = (label.toLowerCase().match(/[\p{L}\p{N}]+/gu) ?? []).join('-').slice(0, 60) || `option-${index(i)}`;
+    let id = base;
+    for (let n = 2; taken.has(id); n++) id = `${base}-${n}`;
+    taken.add(id);
+    return { ...o, id };
+  });
+}
+
+/** The page draws each question from these fields, and the answer picks an option by its label, so two options with one label could not be told apart. */
+function checkQuestions(questions         )       {
+  if (questions === undefined) return;
+  if (!Array.isArray(questions)) throw new InboxError(400, 'questions must be a list of {question, text, options, multiSelect}');
+  questions.forEach((q                             , i) => {
+    const at = `question ${index(i)}`;
+    if (!q || typeof q !== 'object' || typeof q.question !== 'string' || !q.question.trim()) throw new InboxError(400, `${at}: question must be a non-empty string`);
+    if (q.text !== undefined && typeof q.text !== 'string') throw new InboxError(400, `${at}: text must be a string`);
+    if (q.options === undefined) return;
+    if (!Array.isArray(q.options)) throw new InboxError(400, `${at}: options must be a list of {label, description, recommended}`);
+    const labels = new Set        ();
+    for (const o of q.options) {
+      if (!o || typeof o !== 'object' || typeof o.label !== 'string') throw new InboxError(400, `${at}: each option needs a label`);
+      if (labels.has(o.label)) throw new InboxError(400, `${at}: two options have the label ${o.label}`);
+      labels.add(o.label);
+    }
+    if (!q.multiSelect && q.options.filter((o) => o.recommended === true).length > 1) throw new InboxError(400, `${at}: a question without multiSelect takes at most one recommended option`);
+  });
+}
+
+/** The text search matches: the card's words, its tags, and its file names. */
+function searchText(card      )         {
+  // A card stored before this field existed may hold anything the store accepted then, so read it defensively.
+  const questions = (Array.isArray(card.questions) ? card.questions : []).flatMap((q) => [q?.question, q?.text, ...(Array.isArray(q?.options) ? q.options : []).map((o) => o?.label)]);
+  return [card.title, card.text, card.recommendation, card.body, ...questions, card.status, ...Object.entries(card.tags ?? {}).map(([k, v]) => `${k} ${v}`), ...(card.attachments ?? []).map((a) => a.name)]
+    .filter(Boolean).join('\n');
+}
+
+const ORIGIN_FIELDS = ['harness', 'session', 'name', 'host', 'cwd', 'herdrPane', 'herdrWorkspace', 'herdrTab']         ;
+
+/** A post's tags as the merge reads them: an object of values, or nothing. A client that sends anything else keeps the
+ * tags it sent on the card, as it always did. */
+function ownTags(tags         )                                     {
+  return tags && typeof tags === 'object' && !Array.isArray(tags) ? (tags                          ) : undefined;
+}
+
+/** The origin fields the page knows, each a string of at most 200 characters. */
+function cleanOrigin(origin         )                     {
+  if (!origin || typeof origin !== 'object') return undefined;
+  const out         = {};
+  for (const k of ORIGIN_FIELDS) {
+    const v = (origin                           )[k];
+    if (v !== undefined && v !== null && v !== '') out[k] = String(v).slice(0, 200);
+  }
+  return Object.keys(out).length ? out : undefined;
+}
+
+/** What herdr said about a pane, as short strings, or undefined when it said nothing. */
+function cleanPlace(place         )                            {
+  if (!place || typeof place !== 'object') return undefined;
+  const out                = {};
+  for (const k of ['agent', 'title', 'tab', 'workspace']         ) {
+    const v = (place                           )[k];
+    if (typeof v === 'string' && v.trim()) out[k] = v.trim().slice(0, 120);
+  }
+  return Object.keys(out).length ? out : undefined;
+}
+
+function cleanName(name         )         {
+  return name ? String(name).replace(/[\\/\x00-\x1f]/g, '_').slice(0, 120) : '';
+}
+
+function decodeDataUrl(i        , f               )                                                   {
+  const m = /^data:([\w.+-]+\/[\w.+-]+)(?:;[\w=.+-]+)*;base64,([A-Za-z0-9+/=\s]+)$/.exec(String(f.src));
+  if (!m) throw new InboxError(400, `attachment ${i + 1}: src must be an https URL or a base64 data: URL`);
+  const data = (m[2] ?? '').replace(/\s/g, '');
+  const size = Math.floor((data.length * 3) / 4);
+  if (size > MAX_ATTACHMENT_BYTES + 2) throw new InboxError(413, `attachment ${i + 1}${f.name ? ` (${cleanName(f.name)})` : ''} is ${size} bytes, over the limit of ${MAX_ATTACHMENT_BYTES}`);
+  let raw        ;
+  try { raw = atob(data); } catch { throw new InboxError(400, `attachment ${i + 1}: the base64 data is malformed`); }
+  // A loop, not `Uint8Array.from(raw, ...)`: the callback that form calls once per byte is most of the time this route
+  // spends on a large screenshot.
+  const bytes = new Uint8Array(raw.length);
+  for (let k = 0; k < raw.length; k++) bytes[k] = raw.charCodeAt(k);
+  return { type: (m[1] ?? '').toLowerCase(), bytes };
+}
+
+/** The type of a file by its extension, or application/octet-stream for an extension the inbox does not know. */
+export function typeFromName(name        )         {
+  return TYPES_BY_EXTENSION[name.split('.').pop()?.toLowerCase() ?? ''] ?? 'application/octet-stream';
+}
+
+/** A file's type, or the type its name gives when an agent sent it as application/octet-stream. */
+export function attachmentType(file                                 )         {
+  return !file.type || file.type === 'application/octet-stream' ? typeFromName(file.name) : file.type;
+}
+
+/** A webhook address the inbox calls: https only, as for the owner's webhooks. */
+function webhookUrl(url         )         {
+  const text = String(url ?? '');
+  let parsed     ;
+  try { parsed = new URL(text); } catch { throw new InboxError(400, 'webhook.url must be an https URL'); }
+  if (parsed.protocol !== 'https:') throw new InboxError(400, 'webhook.url must be https');
+  if (text.length > 2000) throw new InboxError(400, 'webhook.url must be at most 2,000 characters');
+  // A backtick is the one URL character that ends a code span on the card, and %60 is the same address.
+  return parsed.href.replace(/`/g, '%60');
+}
+
+/** The headers a client sends with each call: names a header can have, values on one line, and none the inbox sets itself. */
+function webhookHeaders(headers         )                         {
+  if (headers === undefined || headers === null) return {};
+  if (typeof headers !== 'object' || Array.isArray(headers)) throw new InboxError(400, 'webhook.headers must be an object of header names and values');
+  const entries = Object.entries(headers                           );
+  if (entries.length > MAX_WEBHOOK_HEADERS) throw new InboxError(400, `webhook.headers takes at most ${MAX_WEBHOOK_HEADERS} headers`);
+  const out                         = {};
+  const seen = new Set        ();
+  for (const [name, value] of entries) {
+    if (seen.has(name.toLowerCase())) throw new InboxError(400, `webhook header ${name}: given twice, in two cases`);
+    seen.add(name.toLowerCase());
+    if (!/^[A-Za-z0-9!#$%&'*+.^_`|~-]{1,64}$/.test(name)) throw new InboxError(400, `webhook header ${JSON.stringify(name.slice(0, 64))}: not a header name`);
+    if (RESERVED_HEADER.test(name)) throw new InboxError(400, `webhook header ${name}: the inbox sets it itself`);
+    const v = String(value ?? '');
+    if (/[\r\n\0]/.test(v) || v.length > 2000) throw new InboxError(400, `webhook header ${name}: the value must be one line of at most 2,000 characters`);
+    out[name] = v;
+  }
+  return out;
+}
+
+/** A card without what only the person reads: the id of the token that posted it, and the draft they left on a card
+ * they dismissed. */
+export function publicCard(card      )       {
+  const { token: _token, ...rest } = card;
+  if (!rest.closed?.draft) return rest;
+  const { kind, outcome, at } = rest.closed;
+  return { ...rest, closed: { kind, outcome, at } };
+}
+
+/** The stored lines that share the most words with a text that matched nothing, so an error can name what is there. */
+function nearestLines(text        , old        )           {
+  const words = [...new Set(old.toLowerCase().split(/\s+/).filter((w) => w.length >= 3))].slice(0, 8);
+  if (!words.length) return [];
+  return text.split('\n')
+    .map((line) => ({ line: line.trim(), score: words.filter((w) => line.toLowerCase().includes(w)).length }))
+    .filter((c) => c.line !== '' && c.score > 0)
+    .sort((a, b) => b.score - a.score || b.line.length - a.line.length)
+    .slice(0, 3)
+    .map((c) => c.line.slice(0, 180));
+}