@stage5/lumine 0.2.41 → 0.2.42

package/README.md

@@ -214,6 +214,8 @@ events.
 
 ```bash
 lumine admin identity list --json
+lumine admin identity inspect Jay1216 \
+  --reason "Confirm account family before a quota-bucket change" --json
 lumine admin daily-run start --identity auto --comment-mode off --json
 lumine admin recommendations list --all --checkpoint recommendations.json --json
 lumine admin recommendations list --after 2026-08-14T00:00:00Z --all --json
@@ -248,6 +250,9 @@ lumine admin daily-run escalation add --target subject:123 \
   --note "Concrete privacy issue requiring owner review" --json
 lumine admin daily-run report --json
 lumine admin daily-run complete --json
+lumine admin escalation list --status all --json
+lumine admin escalation set 123 --status resolved \
+  --note "Final owner decision" --json
 ```
 
 Numeric recommendation targets default to subjects. Use `comment:<id>`,
@@ -280,7 +285,8 @@ resumed with the exact generated key.
 Subject and queue listings use opaque, stable snapshot cursors. `--all`
 follows them automatically, saves a checkpoint after every canonical page,
 and records completed queue coverage in the run audit; `--resume` continues
-the exact same request. Recommendation scans default to the previous completed
+the exact same request. With `--all --json`, bounded progress goes to stderr so
+stdout remains one pipe-safe JSON value. Recommendation scans default to the previous completed
 run's start boundary for at-least-once coverage. Use `--after` for an explicit
 timestamp or `--include-legacy`
 for an intentional all-history scan. Subject `--after` is inclusive and
@@ -293,6 +299,12 @@ the claim file. `daily-run report` summarizes confirmed mutations, completed
 queue coverage, explicitly recorded escalations, and the run brief before the
 run is completed.
 
+Identity inspection, escalation dispositions, AI-bucket maintenance, and
+approved Notable User additions are private operator bookkeeping and do not
+require a delegated daily run. Identity inspection always requires an audited
+`--reason`; raw email/DOB evidence additionally requires
+`--include-private-evidence`. Routine briefs omit raw email identities.
+
 The complete run lifecycle, command contracts, nullable fields, Karma approval
 behavior, pagination semantics, secret-subject behavior, presence isolation,
 and retry rules are documented in

package/lib/admin-workflows.js

@@ -92,6 +92,7 @@ export async function runAutomaticPagination({
   fetchPage,
   transformPage,
   recordCoverage,
+  reportProgress = (message) => process.stderr.write(`${message}\n`),
 }) {
   if (!operation.pagination) {
     throw validationError("--all is supported only by paginated admin listings.");
@@ -152,6 +153,12 @@ export async function runAutomaticPagination({
     }
     state = { ...state, ...saved, resumed: true };
   }
+  const progressEnabled = options.json === true;
+  if (progressEnabled) {
+    reportProgress(
+      `Lumine admin ${operation.name}: ${state.resumed ? "resuming" : "starting"} canonical scan; checkpoint ${checkpointPath}.`,
+    );
+  }
   const pages = [];
   while (!state.exhausted) {
     if (state.pages >= MAX_AUTOMATIC_PAGES) {
@@ -230,6 +237,14 @@ export async function runAutomaticPagination({
       privateFile: true,
       maxBytes: MAX_ADMIN_CHECKPOINT_BYTES,
     });
+    if (
+      progressEnabled &&
+      (pages.length === 1 || state.pages % 10 === 0 || state.exhausted)
+    ) {
+      reportProgress(
+        `Lumine admin ${operation.name}: ${state.pages} page(s), ${state.scannedCount} row(s) scanned, ${state.items.length} candidate(s)${state.exhausted ? "; canonical snapshot exhausted." : "; continuing."}`,
+      );
+    }
   }
   const result = aggregatePageResult({
     operation,

package/lib/admin.js

@@ -21,6 +21,8 @@ const MAX_EDITORIAL_FILE_BYTES = 256 * 1024;
 const MAX_COMPOSED_TEXT_FILE_BYTES = 64 * 1024;
 const MAX_COMPOSED_TEXT_LENGTH = 10_000;
 const MAX_NOTABLE_NOTE_LENGTH = 2_000;
+const MAX_IDENTITY_INSPECTION_REASON_LENGTH = 500;
+const MAX_ESCALATION_DECISION_NOTE_LENGTH = 2_000;
 
 // Operator-composed persona text (plain UTF-8, not JSON). The agent writes
 // the content in the bot's persona itself; the server never invokes
@@ -498,8 +500,12 @@ function adminOperationRequiresRun(operation) {
       "identity.list",
       "identity.status",
       "identity.use",
+      "identity.inspect",
       "daily-run.start",
       "daily-run.status",
+      "escalation.list",
+      "escalation.set",
+      "notable.add",
     ].includes(operation.name) && !operation.name.startsWith("ai-bucket.")
   );
 }
@@ -540,6 +546,35 @@ export function parseAdminOperation(options) {
         { identity: parseIdentity(target) },
       );
     }
+    if (action === "inspect") {
+      const inspectionTarget = String(target || "").trim();
+      const reason = String(options.adminReason || "").trim();
+      if (!inspectionTarget) {
+        throw cliValidationError(
+          "Usage: lumine admin identity inspect <userId|username> --reason <management reason> [--include-private-evidence].",
+        );
+      }
+      if (!reason) {
+        throw cliValidationError(
+          "Explain why private identity evidence is needed with --reason <management reason>.",
+        );
+      }
+      if (reason.length > MAX_IDENTITY_INSPECTION_REASON_LENGTH) {
+        throw cliValidationError(
+          `An identity-inspection reason must be at most ${MAX_IDENTITY_INSPECTION_REASON_LENGTH} characters.`,
+        );
+      }
+      return writeOperation(
+        "identity.inspect",
+        "POST",
+        "/cli/admin/identity/inspect",
+        {
+          target: inspectionTarget,
+          reason,
+          includePrivateEvidence: options.adminIncludePrivateEvidence === true,
+        },
+      );
+    }
   }
 
   if (namespace === "ai-bucket" || namespace === "ai-buckets") {
@@ -639,6 +674,47 @@ export function parseAdminOperation(options) {
     }
   }
 
+  if (namespace === "escalation" || namespace === "escalations") {
+    if (!action || action === "list") {
+      const status = parseEscalationListStatus(options.adminStatus || "open");
+      return readOperation(
+        "escalation.list",
+        withQuery("/cli/admin/escalations", {
+          status,
+          limit: options.limit,
+        }),
+      );
+    }
+    if (action === "set") {
+      const escalationAuditId = parseRequiredInteger(
+        target,
+        "Escalation audit ID",
+        1,
+      );
+      const status = parseEscalationStatus(options.adminStatus);
+      const note = String(options.note || "").trim();
+      if (!note) {
+        throw cliValidationError(
+          "Record the decision or next step with --note <text>.",
+        );
+      }
+      if (note.length > MAX_ESCALATION_DECISION_NOTE_LENGTH) {
+        throw cliValidationError(
+          `An escalation decision note must be at most ${MAX_ESCALATION_DECISION_NOTE_LENGTH} characters.`,
+        );
+      }
+      return writeOperation(
+        "escalation.set",
+        "PUT",
+        `/cli/admin/escalations/${escalationAuditId}`,
+        { status, note },
+      );
+    }
+    throw cliValidationError(
+      "Usage: lumine admin escalation list [--status open|acknowledged|resolved|all] | escalation set <auditId> --status <status> --note <decision>.",
+    );
+  }
+
   if (
     (namespace === "recommend-queue" && (!action || action === "list")) ||
     (namespace === "recommendations" && action === "list")
@@ -1164,7 +1240,7 @@ export function parseAdminOperation(options) {
   }
 
   throw cliValidationError(
-    "Usage: lumine admin identity|daily-run|recommendations|builds|post|subjects|subject|featured|comment|announcement|chat|news|audit|brief|bot-output|notable ...",
+    "Usage: lumine admin identity|daily-run|escalation|recommendations|builds|post|subjects|subject|featured|comment|announcement|chat|news|audit|brief|bot-output|notable ...",
   );
 }
 
@@ -1543,6 +1619,30 @@ function parseCommentMode(value) {
   return mode;
 }
 
+function parseEscalationStatus(value) {
+  const status = String(value || "")
+    .trim()
+    .toLowerCase();
+  if (!["open", "acknowledged", "resolved"].includes(status)) {
+    throw cliValidationError(
+      "--status must be open, acknowledged, or resolved.",
+    );
+  }
+  return status;
+}
+
+function parseEscalationListStatus(value) {
+  const status = String(value || "open")
+    .trim()
+    .toLowerCase();
+  if (!["open", "acknowledged", "resolved", "all"].includes(status)) {
+    throw cliValidationError(
+      "--status must be open, acknowledged, resolved, or all.",
+    );
+  }
+  return status;
+}
+
 function parseOrderedIds(value) {
   const ids = String(value || "")
     .split(",")
@@ -1713,6 +1813,54 @@ function printAdminResult({ operation, result }) {
     console.log(`Notable-user candidates in this brief: ${notableCount}.`);
     return;
   }
+  if (data.inspection) {
+    const inspection = data.inspection;
+    console.log(
+      `Identity inspection for user #${inspection.targetUserId}: ${inspection.accounts?.length || 0} candidate account(s); oldest #${inspection.oldestAccount?.userId || "unknown"}.`,
+    );
+    if (inspection.manualBucket) {
+      console.log(
+        `AI bucket #${inspection.manualBucket.id} (${inspection.manualBucket.label}); ${inspection.manualBucket.memberCount} canonical member(s).`,
+      );
+    }
+    for (const account of inspection.accounts || []) {
+      console.log(
+        `  #${account.userId} ${account.username || "(no username)"} — joined ${account.joinedAt || "unknown"}; ${account.relationBasis.join(", ") || "no relation evidence"}${account.hasDateOfBirth ? "; DOB on file" : "; no DOB on file"}.`,
+      );
+      if (account.privateEvidence) {
+        console.log(
+          `    Private evidence: DOB ${account.privateEvidence.dateOfBirth || "none"}; verified email(s) ${account.privateEvidence.verifiedEmails.join(", ") || "none"}.`,
+        );
+      }
+    }
+    return;
+  }
+  if (Array.isArray(data.escalations)) {
+    console.log(`${data.escalations.length} escalation(s):`);
+    for (const escalation of data.escalations) {
+      const target =
+        escalation.url ||
+        `${escalation.targetType || "target"}:${escalation.targetId || "?"}`;
+      console.log(
+        `  #${escalation.auditId} ${String(escalation.status || "open").toUpperCase()} ${target} — ${escalation.summary}`,
+      );
+      if (escalation.decisionNote) {
+        console.log(`    Decision: ${escalation.decisionNote}`);
+      }
+    }
+    if (data.truncated) {
+      console.log(
+        "More matching escalations exist than the requested limit; raise --limit or narrow --status.",
+      );
+    }
+    return;
+  }
+  if (data.escalation?.decisionNote) {
+    console.log(
+      `Escalation #${data.escalation.auditId}: ${String(data.escalation.status).toUpperCase()} — ${data.escalation.decisionNote}`,
+    );
+    return;
+  }
   if (data.bucket && Array.isArray(data.memberUserIds)) {
     const added = Array.isArray(data.accounts)
       ? `; added ${data.accounts.length} explicit account(s)`

package/lib/commands.js

@@ -2226,6 +2226,7 @@ export function parseArgs(args) {
     "resume",
     "sinceRun",
     "includeLegacy",
+    "includePrivateEvidence",
     "noReviewLoop",
   ]);
 
@@ -2328,6 +2329,7 @@ export function parseArgs(args) {
     adminAfter: raw.after ? String(raw.after) : "",
     adminSinceRun: Boolean(raw.sinceRun),
     adminIncludeLegacy: Boolean(raw.includeLegacy),
+    adminIncludePrivateEvidence: parseBoolean(raw.includePrivateEvidence, false),
     adminAll: Boolean(raw.all),
     adminResume: Boolean(raw.resume),
     adminCheckpoint: raw.checkpoint ? String(raw.checkpoint) : "",
@@ -2338,6 +2340,7 @@ export function parseArgs(args) {
     adminTargetFile: raw.targetFile ? String(raw.targetFile) : "",
     adminReviewReceipt: raw.reviewReceipt ? String(raw.reviewReceipt) : "",
     adminSeverity: raw.severity ? String(raw.severity) : "",
+    adminStatus: raw.status ? String(raw.status) : "",
     adminWaitMs: raw.waitMs ? String(raw.waitMs) : "",
     adminBrowserPath: raw.browserPath ? String(raw.browserPath) : "",
     adminEffort: raw.effort ? String(raw.effort) : "",
@@ -2707,6 +2710,7 @@ export function printHelp() {
   lumine thumbnail generate ["<prompt>"] --model <gpt-image-2|nano-banana>
   lumine doctor runtime-assets
   lumine admin identity list|status|use <zero|ciel|auto> [--json]
+  lumine admin identity inspect <user-id|username> --reason <management-reason> [--include-private-evidence] [--json]
   lumine admin ai-bucket create --label <name> --note <text> [--json]
   lumine admin ai-bucket get --bucket-id <id> [--json]
   lumine admin ai-bucket accounts add --bucket-id <id> --user-ids <id,id,...> [--note <text>] [--json]
@@ -2714,6 +2718,8 @@ export function printHelp() {
   lumine admin daily-run start [--identity zero|ciel|auto] [--comment-mode off|draft|post] [--run-key <key>] [--json]
   lumine admin daily-run status|report|complete|fail [--reason <text>] [--json]
   lumine admin daily-run escalation add --target <target> --note <summary> [--severity attention|urgent] [--json]
+  lumine admin escalation list [--status open|acknowledged|resolved|all] [--limit <number>] [--json]
+  lumine admin escalation set <audit-id> --status open|acknowledged|resolved --note <decision> [--json]
   lumine admin recommendations list [--since-run|--after <date>|--include-legacy] [--all --checkpoint <file> [--resume]] [--content-types comment,dailyReflection] [--unviewed|--viewed] [--cursor <cursor>] [--json]
   lumine admin builds candidates [--all --checkpoint <file> [--resume]] [--cursor <cursor>] [--limit <number>] [--json]
   lumine admin builds review <build-url-or-id> [--output-dir <dir>] [--wait-ms <ms>] [--browser-path <path>] [--json]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage5/lumine",
-  "version": "0.2.41",
+  "version": "0.2.42",
   "description": "Command line tools for launching Lumine builds on Twinkle.",
   "type": "module",
   "bin": {

package/sdk/LUMINE_ADMIN.md

@@ -89,6 +89,40 @@ Mikey; routine administrator runs still escalate suspected alternate accounts
 and never auto-enforce. `accounts add` and `note set` still accept only an
 existing **unbanned** bucket.
 
+### Audited identity inspection
+
+Account-family evidence is private operator work, never a Zero/Ciel public
+action and never a reason to browse unrelated user activity. Use the dedicated
+lookup instead of direct database queries:
+
+```bash
+lumine admin identity inspect Jay1216 \
+  --reason "Confirm the account family before updating its quota bucket" --json
+lumine admin identity inspect Jay1216 \
+  --reason "Mikey requested DOB and email evidence for this decision" \
+  --include-private-evidence --json
+```
+
+The default result resolves the exact username or user ID from the writer,
+returns the canonical current AI bucket, orders candidate accounts oldest
+first, identifies the oldest account within the strongest canonical family
+boundary (bucket before email; never device alone) when that family fits in the
+bounded evidence set, reports whether each
+account has a DOB, and explains whether the link
+came from explicit bucket membership, a verified-email match, or bounded exact-
+device evidence. It does **not** reveal email addresses, DOB values, device IDs,
+IP evidence, private messages, or unrelated activity. `--include-private-evidence`
+adds DOB values and verified email addresses only; exact device IDs are never
+returned.
+
+Every inspection requires a concrete `--reason`. Before loading the evidence,
+the API commits a private `identity.inspect` audit receipt containing the real
+operator, requested target, reason, and whether private evidence was requested.
+The evidence itself is deliberately not copied into the audit log. Inspection
+is run-independent and has no public actor. Results are **candidate accounts
+for human judgment**, not an automatic ownership finding and never automatic
+grounds for moderation, bans, or bucket changes.
+
 ## Editorial priorities
 
 The CLI enforces none of this — it is the standing instruction for the operator
@@ -236,6 +270,29 @@ Two rules that keep the list worth reading:
   design. Do not delete, hide, argue with, or publicly accuse anyone, and do not
   warn a child that they are in trouble. Report it and let Mikey decide.
 
+Mikey's decision must remain attached after the originating run closes. These
+commands are private, run-independent bookkeeping:
+
+```bash
+lumine admin escalation list --json
+lumine admin escalation list --status all --json
+lumine admin escalation set 123 --status acknowledged \
+  --note "Mikey is reviewing the bot response" --json
+lumine admin escalation set 123 --status resolved \
+  --note "No user fault; this audit concerned Zero's response" --json
+```
+
+`list` defaults to unresolved `open` items. `--status` also accepts
+`acknowledged`, `resolved`, or `all`. The number passed to `set` is the original
+`run.escalation` audit ID returned by the run report/list. Every disposition is
+an immutable private `escalation.status.set` audit event. A revision allocated
+while the original escalation is locked orders concurrent decisions, so the
+last applied decision is the canonical status and annotation even if request
+audit IDs were reserved in another order. `--status open` can deliberately
+reopen an item with an explanatory note. Status filters walk indexed escalation
+history rather than a fixed latest-event window. No active run or public bot
+identity is used.
+
 ## Common JSON types
 
 All `--json` success output is one uncolored JSON value:
@@ -249,7 +306,9 @@ type Success<D> = {
 };
 ```
 
-Failures print one JSON value, write no progress prose, and exit nonzero:
+Failures print one JSON value to stdout and exit nonzero. A failing `--all`
+scan may already have written bounded page progress to stderr; stdout remains
+protocol-clean:
 
 ```ts
 type Failure = {
@@ -430,6 +489,8 @@ lumine admin identity status --json
 lumine admin identity use zero --json
 lumine admin identity use ciel --json
 lumine admin identity use auto --json
+lumine admin identity inspect Jay1216 \
+  --reason "Confirm the account family before a bucket change" --json
 ```
 
 Schemas:
@@ -448,6 +509,51 @@ type IdentityStatus = Success<{
 }>;
 
 type IdentityUse = IdentityStatus;
+
+type IdentityInspection = Success<{
+  inspection: {
+    targetUserId: number;
+    privateEvidenceIncluded: boolean;
+    manualBucket: {
+      id: number;
+      label: string;
+      memberCount: number;
+      isBanned: boolean;
+    } | null;
+    oldestAccount: IdentityCandidate | null;
+    oldestAccountBasis: "manual_bucket" | "verified_email" | "target_only";
+    oldestAccountComplete: boolean;
+    candidateAltCount: number;
+    accounts: IdentityCandidate[];
+    evidenceCoverage: {
+      deviceLookbackDays: number;
+      targetDeviceEvidenceRows: number;
+      targetDeviceIdsConsidered: number;
+      relatedDeviceEvidenceRows: number;
+      candidateLimit: number;
+      truncated: boolean;
+    };
+  };
+}>;
+
+type IdentityCandidate = {
+  userId: number;
+  username: string | null;
+  joinedAt: number | null;
+  isTarget: boolean;
+  isOldestAccount: boolean;
+  hasDateOfBirth: boolean;
+  banned: boolean;
+  deleted: boolean;
+  relationBasis: Array<
+    "target" | "manual_bucket" | "verified_email" | "exact_device"
+  >;
+  sharedDeviceCount: number;
+  privateEvidence?: {
+    dateOfBirth: string | null;
+    verifiedEmails: string[];
+  };
+};
 ```
 
 `identity use` changes only the preference for a future start. It never changes
@@ -465,6 +571,9 @@ lumine admin daily-run escalation add --target chatMessage:3768159 \
 lumine admin daily-run report --json
 lumine admin daily-run complete --json
 lumine admin daily-run fail --reason "operator stopped" --json
+lumine admin escalation list --status all --json
+lumine admin escalation set 123 --status resolved \
+  --note "Final owner decision" --json
 ```
 
 Schemas:
@@ -490,6 +599,10 @@ the current active run. Queue coverage is written automatically only after an
 `--all` traversal reaches canonical exhaustion; an interrupted scan remains in
 its local checkpoint and cannot be misreported as complete.
 
+Creating an escalation belongs to the active run; acknowledging, annotating,
+resolving, or reopening it does not. Use the run-independent `escalation`
+commands after Mikey responds instead of starting a follow-up delegated run.
+
 `lastRun` makes a lost-response retry of `complete` or `fail` possible after
 the active pointer has been cleared. Other run-scoped commands accept only the
 current unexpired `active` run. Completion first finalizes any mutation whose
@@ -617,6 +730,12 @@ the same API, run, and exact request. The final result can be copied to
 `--after` is inclusive, and every opaque cursor is bound to its original
 filters.
 
+For `--all --json`, stdout remains exactly one JSON value. Scan-start, first-
+page, every-tenth-page, and exhaustion progress is written to **stderr** with
+only page/scanned/candidate counts and the private checkpoint path. A long
+traversal therefore no longer looks stalled, while piping stdout to `jq` or a
+file remains safe.
+
 Recommendations default to `--since-run`: the server uses the previous
 completed run's start time (or the same bounded seven-day fallback used by the
 brief on a first run). That deliberate start-to-start overlap gives the queue
@@ -1264,6 +1383,22 @@ rows per source — retry with a narrower `--days` window, and do not complete
 the run while either flag remains true. Run it right after the
 brief, and **read every row** — the tool deliberately does no filtering,
 scoring, or keyword matching, because the judgment is the reviewing agent's.
+
+**Privacy boundary:** this is an audit of how Twinkle's bots treated members,
+not a moderation queue for members' private use of the tool. Treat private
+human messages and creative work as confidential context. Read every
+bot-authored row, but inspect adjacent human messages only when the minimum
+necessary context is needed to judge the bot's response; never browse the rest
+of a private conversation out of curiosity. Do not characterize or escalate a
+member's lawful private creative writing — including a teenager's romance
+fiction — merely because its subject is intimate or romantic. An escalation
+must identify what **Zero or Ciel** did (for example, an invented premise,
+pressure, sexualization, abuse, or a failed boundary), include only the narrow
+context needed for Mikey to decide a remedy, and never reuse private material
+for public editorial judgment, Notable User selection, or unrelated identity
+investigation. A separate concrete risk to a member may still be escalated,
+but it does not authorize a broader review of their private activity.
+
 Judge against the same values the editorial priorities encode:
 
 - **premises must be real.** The 08-11 message didn't merely choose a bad
@@ -1347,11 +1482,16 @@ farm-signal sections added the same day):
   ("$X so far today; complete days run ~$Y/day"). Real
   incident: a run report quoted a ~15%-complete day bucket ($5) as the site's
   daily AI spend (complete days were running ~$40-50). Flag accounts that jumped tiers or
-  dominate that report period. May be `{ unavailable: true }` if the cost
+  dominate that report period. Routine `topAccounts` rows identify the account
+  by user ID/username and expose only an `identitySummary` count/manual-bucket
+  flag; raw identity strings and verified email addresses are deliberately
+  omitted. Use reason-required `identity inspect`, with
+  `--include-private-evidence` only when Mikey's concrete decision needs the
+  addresses or DOB values. May be `{ unavailable: true }` if the cost
   report fails; say so rather than guessing. This section is also the run's
   AI-cost exploit watch: while reading it, actively look for the signatures the
   brief actually exposes — one risk group spanning several user IDs, repeated
-  plus-tag or dot-variant email families among top accounts, or heavy spend by
+  account groups in `farmSignals.inboxFamilies`, or heavy spend by
   accounts that `economy.topGainers` or `notableCandidates` independently marks
   as recent signups. Cross-check those signals against the escalation
   categories. Missing join-date or community data is unknown, not evidence that
@@ -1366,9 +1506,11 @@ farm-signal sections added the same day):
   execute them with
   `lumine admin notable add <userId|username> --note "<specific rationale>"`
   (idempotent —
-  an existing member returns `already_done`; requires the `notable:write`
-  scope, audited as `notable.add`, and writes through the management page's
-  own canonical service). Without his approval the run only proposes.
+  an existing member returns `already_done`; run-independent, privately audited
+  as `notable.add`, and writes through the management page's own canonical
+  service). It can therefore record Mikey's approval after the daily run has
+  closed without opening another delegated run. Without his approval the run
+  only proposes.
   **Always pass `--note`** with a concrete one-or-two-sentence record of what
   made them notable — real numbers and specifics from the brief window, not
   "active user". It lands in the management page's reason column, which is
@@ -1428,12 +1570,14 @@ farm-signal sections added the same day):
   Deliberately coarse: it is an onboarding health check, not per-child
   session tracking.
 - `farmSignals` — AI-cost farm signatures derivable with ZERO new data
-  collection: `inboxFamilies` (verified emails from accounts active in the
-  last `inboxFamilyActivityDays`, with only Gmail/googlemail's documented
+  collection: `inboxFamilies` (account groups formed from verified emails of
+  accounts active in the last `inboxFamilyActivityDays`, with only
+  Gmail/googlemail's documented
   plus-tag and dot aliases collapsed, flagging inboxes behind 3+ accounts) and
   `youngAccountAiUsage` (accounts under 30 days old drawing battery in the
-  whole-day `aiUsageDayWindow`). SIGNAL ONLY: siblings legitimately share a
-  parent inbox, so an inbox family is a reason to look, never proof or grounds
+  whole-day `aiUsageDayWindow`). The raw canonical inbox is never returned in
+  the routine brief. SIGNAL ONLY: siblings legitimately share a parent inbox,
+  so an inbox family is a reason to look, never proof or grounds
   for action. Feed real suspicions to the AI-cost escalation category. Shared
   AI device/IP risk evidence is already in `aiSpending.topRiskGroups`; do not
   guess it from inbox similarity.
@@ -1526,7 +1670,28 @@ type InsightsBrief = Success<{
         endDayInProgress: boolean;
         summary: unknown;
         byDay: unknown[];
-        topAccounts: unknown[];
+        topAccounts: Array<{
+          userId: number;
+          username: string;
+          eventCount: number;
+          requestCount: number;
+          estimatedCostUsd: number;
+          inputTokens: number;
+          cachedInputTokens: number;
+          cacheEligibleInputTokens: number;
+          outputTokens: number;
+          totalTokens: number;
+          imageCount: number;
+          audioSeconds: number;
+          energyUnits: number;
+          energyChargedUnits: number;
+          energyOverflowUnits: number;
+          coinCharged: number;
+          identitySummary: {
+            observedIdentityCount: number;
+            manualBucketObserved: boolean;
+          };
+        }>;
         topRiskGroups: unknown[];
       }
     | InsightUnavailable;
@@ -1614,7 +1779,6 @@ type InsightsBrief = Success<{
     | {
         inboxFamilyActivityDays: number;
         inboxFamilies: Array<{
-          inbox: string;
           accounts: Array<{
             userId: number;
             username: string | null;