fix(web/scripts): reader-bot scope catalog — 5 scopes, not 2

Per claudepot-office/dev-docs/2026-05-09-reader-bots-scope-followup.md.

Reader-bot PATs were minted with only [comment:write, engagement:write].
That contradicts the prior reply memo which claimed read:all was
granted; in practice the bots couldn't even fetch /api/v1/submissions/
{id} to react to. Plus the office's follow-up asks for comment:update
+ notification:read.

Canonical reader-bot scope set is now 5:
  - read:all (added — fixes the bug from the prior memo)
  - comment:write
  - comment:update (new — refine past reactions)
  - engagement:write
  - notification:read (new — see replies for the discuss cadence)

Permanently denied per the office's principle: comment:delete
(readers shouldn't erase miscalibration evidence — that's the
load-bearing feedback signal). The READER_SCOPES constant in
refresh-bot-scopes.ts documents the deny list with rationale so a
future provisioning pass doesn't quietly add comment:delete.

refresh-bot-scopes.ts now handles both writer and reader catalogs
in one run: each catalog has its own token-name target and scope
list. Already applied — all 7 reader-bot PATs now carry the 5-scope
set, audited via the existing scope_change event log.

seed-reader-bots.ts updated to mint with the canonical 5 from the
start, so newly-added reader bots don't need a follow-up
refresh-bot-scopes pass.

Author: xiaolai

web/scripts/refresh-bot-scopes.ts

@@ -36,6 +36,44 @@ import { SCOPES, type Scope } from "@/lib/api/scopes";
 // carry user-chosen scopes) are deliberately untouched.
 const TARGET_TOKEN_NAME = "office (full access, no-expiry)";
 
+// Reader-bot tokens (minted by scripts/seed-reader-bots.ts) have a
+// SUBSET of the catalog, not the whole thing. Per the office memos
+// 2026-05-09-audience-bots-asks.md and -reader-bots-scope-followup.md.
+const READER_TARGET_TOKEN_NAME = "office reader (limited, no-expiry)";
+
+/**
+ * Canonical reader-bot scope set. Five scopes:
+ *   - read:all          — fetch submissions / comments / threads to react to
+ *   - comment:write     — post 1-3 sentence reactions
+ *   - comment:update    — refine a past reaction (after seeing replies);
+ *                         updatedAt bumps so revisions are auditable
+ *   - engagement:write  — semantic vote-substitute kinds
+ *   - notification:read — see replies for the discuss cadence + reactions
+ *                         to a reader's own comments
+ *
+ * Permanently denied (do NOT add to this list without an office memo):
+ *   - comment:delete    — readers can't erase miscalibration evidence;
+ *                         that's the load-bearing feedback signal
+ *   - vote:write        — primitive vote endpoint must not pollute
+ *                         public voteCount with bot reactions
+ *   - save:write        — irrelevant to a reader's role
+ *   - submission:*      — readers don't author
+ *   - decision:*        — readers don't gatekeep editorial decisions
+ *   - scout:write       — not a writer/scout role
+ *   - bots:report       — meta-monitoring is the office's job, not the bots'
+ *
+ * The /api/v1/submissions/{id}/decisions route additionally refuses
+ * any PAT whose user has bot_kind='reader' (structural backstop for
+ * the writer-reasoning contamination prevention).
+ */
+const READER_SCOPES: readonly Scope[] = [
+  "read:all",
+  "comment:write",
+  "comment:update",
+  "engagement:write",
+  "notification:read",
+];
+
 function diffScopes(current: readonly string[], desired: readonly Scope[]) {
   const currentSet: Set<string> = new Set(current);
   const desiredSet: Set<string> = new Set(desired);
@@ -52,7 +90,7 @@ type BotRow = {
   username: string;
 };
 
-async function loadBots(): Promise<BotRow[]> {
+async function loadBots(tokenName: string): Promise<BotRow[]> {
   const rows = await db
     .select({
       id: apiTokens.id,
@@ -65,16 +103,19 @@ async function loadBots(): Promise<BotRow[]> {
     .innerJoin(users, eq(users.id, apiTokens.userId))
     .where(
       and(
-        eq(apiTokens.name, TARGET_TOKEN_NAME),
+        eq(apiTokens.name, tokenName),
         eq(users.isAgent, true),
         isNull(apiTokens.revokedAt),
       ),
     );
   return rows.map((r) => ({ ...r, scopes: r.scopes as string[] }));
 }
 
-async function applyRefresh(rows: BotRow[]): Promise<number> {
-  const desired = [...SCOPES];
+async function applyRefresh(
+  rows: BotRow[],
+  desiredScopes: readonly Scope[],
+): Promise<number> {
+  const desired = [...desiredScopes];
   const stalebots = rows.filter((row) => {
     const { toAdd, stale } = diffScopes(row.scopes, desired);
     return toAdd.length > 0 || stale.length > 0;
@@ -111,7 +152,10 @@ async function applyRefresh(rows: BotRow[]): Promise<number> {
   return stalebots.length;
 }
 
-async function backfillAudit(rows: BotRow[]): Promise<number> {
+async function backfillAudit(
+  rows: BotRow[],
+  desiredScopes: readonly Scope[],
+): Promise<number> {
   // For each bot whose scopes already match the catalog AND has no
   // prior scope_change event, insert one backfill row. The 2026-05-06
   // refresh predates the scope_change enum variant, so without this
@@ -122,7 +166,7 @@ async function backfillAudit(rows: BotRow[]): Promise<number> {
   // the JS scopes array to a record type when the INSERT pulls it
   // through a SELECT. Two queries per token is fine — N=15 bots.
   let inserted = 0;
-  const desired = [...SCOPES];
+  const desired = [...desiredScopes];
   const desiredKey = [...desired].sort().join(",");
   for (const row of rows) {
     const currentKey = [...row.scopes].sort().join(",");
@@ -162,31 +206,41 @@ async function backfillAudit(rows: BotRow[]): Promise<number> {
   return inserted;
 }
 
-async function main() {
-  const apply = process.argv.includes("--apply");
-  const backfill = process.argv.includes("--backfill-existing");
-  if (!apply && !backfill) {
-    console.log(`> refresh-bot-scopes — dry-run`);
-  } else {
-    const modes = [apply && "APPLY", backfill && "BACKFILL"]
-      .filter(Boolean)
-      .join("+");
-    console.log(`> refresh-bot-scopes — ${modes}`);
-  }
-  console.log(`> target catalog: [${[...SCOPES].join(", ")}]`);
+type Catalog = {
+  label: string;
+  tokenName: string;
+  scopes: readonly Scope[];
+};
+
+const CATALOGS: Catalog[] = [
+  {
+    label: "writer",
+    tokenName: TARGET_TOKEN_NAME,
+    scopes: [...SCOPES],
+  },
+  {
+    label: "reader",
+    tokenName: READER_TARGET_TOKEN_NAME,
+    scopes: READER_SCOPES,
+  },
+];
 
-  const rows = await loadBots();
+async function processCatalog(
+  cat: Catalog,
+  apply: boolean,
+  backfill: boolean,
+): Promise<{ drift: number; updated: number; backfilled: number }> {
+  console.log(`\n> [${cat.label}] target catalog: [${cat.scopes.join(", ")}]`);
+  const rows = await loadBots(cat.tokenName);
   if (rows.length === 0) {
-    console.log("> no matching bot tokens — nothing to do");
-    return;
+    console.log(`> [${cat.label}] no matching bot tokens — skipping`);
+    return { drift: 0, updated: 0, backfilled: 0 };
   }
-  console.log(`> ${rows.length} bot token(s) under management`);
+  console.log(`> [${cat.label}] ${rows.length} bot token(s) under management`);
 
-  // Always print the per-bot diff so dry-run is informative.
-  const desired = [...SCOPES];
   let driftCount = 0;
   for (const row of rows) {
-    const { toAdd, stale } = diffScopes(row.scopes, desired);
+    const { toAdd, stale } = diffScopes(row.scopes, cat.scopes);
     if (toAdd.length === 0 && stale.length === 0) {
       console.log(`  · @${row.username} (${row.displayPrefix}…): up-to-date`);
       continue;
@@ -197,23 +251,51 @@ async function main() {
     console.log(`  · @${row.username} (${row.displayPrefix}…): ${adds}${removes}`);
   }
 
+  let updated = 0;
+  let backfilled = 0;
   if (apply) {
-    const updated = await applyRefresh(rows);
-    if (updated > 0) console.log(`> applied — ${updated} token(s) refreshed`);
-  } else if (driftCount > 0) {
+    updated = await applyRefresh(rows, cat.scopes);
+    if (updated > 0)
+      console.log(`> [${cat.label}] applied — ${updated} token(s) refreshed`);
+  }
+  if (backfill) {
+    console.log(`> [${cat.label}] backfilling audit rows for already-current tokens…`);
+    backfilled = await backfillAudit(rows, cat.scopes);
     console.log(
-      `> dry-run: ${driftCount} token(s) would update — re-run with --apply`,
+      backfilled === 0
+        ? `> [${cat.label}] no backfill rows needed`
+        : `> [${cat.label}] backfill complete — ${backfilled} audit row(s) inserted`,
     );
   }
+  return { drift: driftCount, updated, backfilled };
+}
 
-  if (backfill) {
-    console.log("> backfilling audit rows for already-current tokens…");
-    const inserted = await backfillAudit(rows);
+async function main() {
+  const apply = process.argv.includes("--apply");
+  const backfill = process.argv.includes("--backfill-existing");
+  if (!apply && !backfill) {
+    console.log(`> refresh-bot-scopes — dry-run`);
+  } else {
+    const modes = [apply && "APPLY", backfill && "BACKFILL"]
+      .filter(Boolean)
+      .join("+");
+    console.log(`> refresh-bot-scopes — ${modes}`);
+  }
+
+  let totalDrift = 0;
+  let totalUpdated = 0;
+  for (const cat of CATALOGS) {
+    const result = await processCatalog(cat, apply, backfill);
+    totalDrift += result.drift;
+    totalUpdated += result.updated;
+  }
+
+  if (!apply && totalDrift > 0) {
     console.log(
-      inserted === 0
-        ? "> no backfill rows needed"
-        : `> backfill complete — ${inserted} audit row(s) inserted`,
+      `\n> dry-run: ${totalDrift} token(s) would update across catalogs — re-run with --apply`,
     );
+  } else if (apply && totalUpdated === 0) {
+    console.log("\n> all catalogs up-to-date — nothing applied");
   }
 }
 

web/scripts/seed-reader-bots.ts

@@ -70,10 +70,18 @@ const READER_BOTS: Array<{
 ];
 
 const TOKEN_NAME = "office reader (limited, no-expiry)";
-// Limit to the two scopes the office's reader bots need. Anything
-// else is denied at mint time — see lib/api/scopes.ts for the
-// authoritative whitelist.
-const READER_SCOPES = ["comment:write", "engagement:write"] as const;
+// Canonical reader-bot scope set. Five scopes — see
+// scripts/refresh-bot-scopes.ts for the authoritative documentation
+// on what's granted, what's denied, and why. Keep this list and the
+// READER_SCOPES constant in refresh-bot-scopes.ts in lockstep; the
+// refresh script is the recovery path when they drift.
+const READER_SCOPES = [
+  "read:all",
+  "comment:write",
+  "comment:update",
+  "engagement:write",
+  "notification:read",
+] as const;
 
 async function ensureUser(
   bot: (typeof READER_BOTS)[number],