@stage5/lumine 0.3.68 → 0.3.70

package/lib/admin-duties.js

@@ -28,6 +28,8 @@ export function createDailyReviewState(dir, gather, previous = {}) {
     .map((step) => ({
       ...(step.ok ? fingerprint(dir, step.file) : { file: step.file }),
       fetched: step.ok,
+      ...(step.deferred ? { deferred: true, reason: step.reason } : {}),
+      ...(step.capturedAt ? { capturedAt: step.capturedAt, reused: Boolean(step.reused) } : {}),
       read: false,
     }));
   if (gather.botOutput.complete)
@@ -42,6 +44,14 @@ export function createDailyReviewState(dir, gather, previous = {}) {
     if (gather.buildReviews && (
       source.file === "rr-pending.json" || /^build-reviews-\d+\.json$/.test(source.file)
     )) continue;
+    if (gather.paperQueue && /^arena-paper-queue-\d+\.json$/.test(source.file)) continue;
+    if (gather.personalQueue && /^arena-today-queue-\d+\.json$/.test(source.file)) continue;
+    if (gather.rewardDiagnostics && /^reward-diagnostics(?:-\d+|-summary)?\.json$/.test(source.file)) continue;
+    if (gather.jevReview && /^jev-review(?:-\d+|-summary)?\.json$/.test(source.file)) continue;
+    if (gather.ownerWake?.collection && /^owner-wake(?:-sessions)?(?:-\d+)?\.json$/.test(source.file)) continue;
+    if (gather.botOutput && (
+      source.file === "bot-chats.txt" || /^bot-output-\d+\.json$/.test(source.file)
+    )) continue;
     if (!sources.some((current) => current.file === source.file)) sources.push({ ...source, retained: true, read: false });
   }
   return {
@@ -49,6 +59,7 @@ export function createDailyReviewState(dir, gather, previous = {}) {
     scope: previous.scope || "collection",
     sources,
     collectionFailures: gather.failed || [],
+    collectionDeferred: gather.deferred || [],
     requiredDuties: [...new Set(["effort-levels", "report-browser", ...(previous.requiredDuties || [])])],
     note: "Collection is not a full review. Add every duty required by the run scope and its carryovers. Reading and browser checks require explicit evidence acknowledgments.",
   };
@@ -157,8 +168,9 @@ export function summarizeDailyProgress(dir, state, evidence = {}) {
     .filter((item) => item.status !== "completed")
     .map((item) => item.id);
   const collectionFailures = state.collectionFailures || [];
+  const collectionDeferred = state.collectionDeferred || [];
   const complete =
-    collectionFailures.length === 0 && sources.every((item) => item.read) && incomplete.length === 0;
+    collectionFailures.length === 0 && collectionDeferred.length === 0 && sources.every((item) => item.read) && incomplete.length === 0;
   return {
     scope: state.scope || "declared-duties",
     coverageBasis: "declared sources and duties only",
@@ -166,6 +178,7 @@ export function summarizeDailyProgress(dir, state, evidence = {}) {
     effortAssignments,
     sources,
     collectionFailures,
+    collectionDeferred,
     duties,
     complete,
     reading: {

package/lib/admin-jev-review.js

@@ -0,0 +1,76 @@
+// Bounded owner-only frozen evidence. Collection never acknowledges reading
+// and never reconstructs missing input from the member's edited chat history.
+export const JEV_REVIEW_USAGE =
+  "Usage: lumine admin jev-routing review --since <unix|ISO> --until <unix|ISO> [--limit 1..20] [--cursor <cursor>] [--include-synthetic] [--all] [--json].";
+
+function invalid(message) {
+  const error = new Error(message);
+  error.code = "CLI_ADMIN_CLI_VALIDATION";
+  throw error;
+}
+
+function explicitTimestamp(value, name) {
+  if (typeof value !== "string" && typeof value !== "number") invalid(JEV_REVIEW_USAGE);
+  const text = String(value).trim();
+  if (!/^\d+$/.test(text) && !/^\d{4}-\d{2}-\d{2}(?:T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?(?:Z|[+-]\d{2}:\d{2}))?$/.test(text)) {
+    invalid(`--${name} requires an explicit Unix timestamp or ISO date, not a relative window.`);
+  }
+  const seconds = /^\d+$/.test(text) ? Number(text) : Math.floor(Date.parse(text) / 1000);
+  if (!Number.isSafeInteger(seconds) || seconds <= 0) invalid(`Invalid --${name} timestamp.`);
+  // Keep ISO input intact for the API's strict calendar/date-zone validation.
+  return { text, seconds };
+}
+
+export function buildJevRoutingReviewOperation({ action, target, extra, options = {} }) {
+  if (action !== "review" || target || extra) invalid(JEV_REVIEW_USAGE);
+  if (options.adminAll && options.adminCursor) {
+    invalid("Use --all from the beginning of the window, or --resume with its saved checkpoint; use --cursor only for an individual page.");
+  }
+  const since = explicitTimestamp(options.adminSince, "since");
+  const until = explicitTimestamp(options.adminUntil, "until");
+  if (until.seconds <= since.seconds || until.seconds - since.seconds > 8 * 86400) {
+    invalid("Use a fixed window with since < until, at most eight days.");
+  }
+  // The global parser's `limit` defaults to 50 for unrelated commands.
+  // `adminLimit` records only an explicitly supplied --limit.
+  const rawLimit = options.adminLimit;
+  const limit = rawLimit == null || rawLimit === "" ? 20 : Number(rawLimit);
+  if ((rawLimit != null && !["string", "number"].includes(typeof rawLimit)) ||
+      !Number.isSafeInteger(limit) || limit < 1 || limit > 20) invalid("--limit must be 1–20.");
+  if (options.adminIncludeSynthetic !== undefined && typeof options.adminIncludeSynthetic !== "boolean") {
+    invalid("--include-synthetic is a flag without a value.");
+  }
+  const includeSynthetic = options.adminIncludeSynthetic === true;
+  const query = new URLSearchParams({ since: since.text, until: until.text, limit: String(limit) });
+  if (includeSynthetic) query.set("includeSynthetic", "true");
+  if (options.adminCursor) query.set("cursor", String(options.adminCursor));
+  return {
+    name: "jevRouting.review",
+    method: "GET",
+    path: `/cli/admin/jev-routing/review?${query.toString()}`,
+    body: undefined,
+    mutates: false,
+    requiresRun: false,
+    pagination: {
+      collectionKey: "items",
+      after: since.seconds,
+      summaryKeys: ["collectionWindow", "coverage", "notes"],
+      filters: { since: since.text, until: until.text, includeSynthetic },
+    },
+  };
+}
+
+export function formatJevRoutingReview(data = {}) {
+  const window = data.collectionWindow || {};
+  const coverage = data.coverage || {};
+  const lines = [
+    `JEV review: [${window.since ?? "?"}, ${window.until ?? "?"}) · synthetic ${window.includeSynthetic ? "included" : "excluded"}`,
+    `${data.items?.length || 0} events returned · page ${coverage.status || "coverage unknown"}${coverage.fromBeginning === false ? " · resumed after a cursor" : ""}`,
+  ];
+  for (const item of data.items || []) {
+    lines.push(`#${item.eventId} ${item.route} · ${(item.reviewReasons || []).join(", ")} · selected ${item.selectedSource || "not recorded"} · frozen input ${item.contextAvailable ? "available" : item.contextUnavailableReason || "unavailable"}`);
+  }
+  if (data.nextCursor) lines.push(`Next cursor: ${data.nextCursor}`);
+  lines.push("Collection is not review. Read the JSON source pages; an exhausted resumed page does not prove the whole window was collected.");
+  return lines;
+}

package/lib/admin-owner-trace.js

@@ -4,7 +4,7 @@
 // no daily run needed. The server keeps 30 days.
 
 export const OWNER_TRACE_USAGE =
-  "Usage: lumine admin owner-trace [--since 2h|30m|3d|<iso>|<unix>] [--type route,feed-open,scroll-anchor,content-scroll,error,...] [--perf] [--wake] [--path <substring>] [--limit 300] [--json].";
+  "Usage: lumine admin owner-trace [--since 2h|30m|3d|<iso>|<unix>] [--until <unix-second>] [--cursor <time:id>] [--type route,feed-open,scroll-anchor,content-scroll,error,...] [--perf] [--wake] [--path <substring>] [--limit 300] [--json].";
 
 // --perf: only the performance events (tap-to-page timeline, slow API
 // requests, main-thread stalls, page load).
@@ -59,6 +59,15 @@ export function buildOwnerTraceOperation(options) {
   const query = new URLSearchParams();
   query.set("since", normalizeSince(options.adminSince));
   query.set("limit", String(limit));
+  if (options.adminUntil) {
+    const until = Number(options.adminUntil);
+    if (!Number.isSafeInteger(until) || until <= 0) throw validationError("--until must be a positive unix second.");
+    query.set("until", String(until));
+  }
+  if (options.adminCursor) {
+    if (!/^\d+:\d+$/.test(options.adminCursor)) throw validationError("--cursor must be a returned time:id pair.");
+    query.set("cursor", options.adminCursor);
+  }
   const types = String(options.adminType || "")
     .split(",")
     .map((type) => type.trim())
@@ -333,7 +342,7 @@ export function formatOwnerTrace(data) {
   const sessions = new Set(events.map((event) => event.sessionId));
   const since = Number(data?.since || 0);
   lines.push(
-    `Owner trace since ${since ? `${formatDay(since * 1000)} ${formatClock(since * 1000).slice(0, 5)}` : "?"} · ${events.length} event(s) · ${sessions.size} session(s)${data?.truncated ? " · older events cut off (raise --limit or narrow --since)" : ""}`,
+    `Owner trace since ${since ? `${formatDay(since * 1000)} ${formatClock(since * 1000).slice(0, 5)}` : "?"} · ${events.length} event(s) · ${sessions.size} session(s)${data?.truncated ? ` · more pages (keep --since/--until; --cursor ${data.nextCursor || "unavailable"})` : ""}`,
   );
   if (!events.length) {
     lines.push("Nothing recorded in this window.");

package/lib/admin.js

@@ -7,6 +7,7 @@ import {
   readdirSync,
   readFileSync,
   realpathSync,
+  statSync,
   writeFileSync,
 } from "node:fs";
 import path from "node:path";
@@ -48,6 +49,8 @@ import { buildSpendingOperation, completeSpendingReport, formatSpending } from "
 import { buildCraftOperation, formatCraftResult } from "./admin-craft.js";
 import { buildNonogramOperation, formatNonogramResult } from './admin-nonogram.js';
 import { buildArenaOperation, formatArenaResult } from "./admin-arena.js";
+import { buildJevRoutingReviewOperation, formatJevRoutingReview } from "./admin-jev-review.js";
+import { summarizeGameDiagnostics } from "./game-diagnostic-summary.js";
 import {
   buildSlidingBlockOperation,
   formatSlidingBlockResult,
@@ -1314,6 +1317,32 @@ function readEditorialFile(filePath) {
   }
 }
 
+function gameDiagnosticSummary(options) {
+  const filePath = String(options.adminFile || "").trim();
+  const outputPath = options.adminOutput ? String(options.adminOutput).trim() : null;
+  if (options.positional?.length !== 2 || !filePath || outputPath === "") {
+    throw cliValidationError("Usage: lumine admin game-diagnostics summarize --file <envelope.json> [--json]. This reads retained evidence locally.");
+  }
+  const maxBytes = 16 * 1024 * 1024;
+  let metadata;
+  try { metadata = statSync(filePath); }
+  catch { throw cliValidationError("Could not read the game diagnostic envelope."); }
+  if (!metadata.isFile() || metadata.size > maxBytes) {
+    throw cliValidationError("The game diagnostic envelope must be a regular file under 16 MB.");
+  }
+  if (outputPath) {
+    let outputMetadata;
+    try { outputMetadata = statSync(outputPath); }
+    catch (error) { if (error.code !== "ENOENT") throw error; }
+    if (path.resolve(outputPath) === path.resolve(filePath) ||
+        (outputMetadata?.dev === metadata.dev && outputMetadata?.ino === metadata.ino)) {
+      throw cliValidationError("Keep the raw evidence: summary output must differ from the input file, including aliases.");
+    }
+  }
+  const envelope = readAdminJsonFile(filePath, "game diagnostic envelope", { maxBytes });
+  return { ok: true, status: "success", changed: false, data: summarizeGameDiagnostics(envelope) };
+}
+
 export async function adminCommand(options) {
   const [namespace, action] = options.positional || [];
   const composite =
@@ -1323,15 +1352,21 @@ export async function adminCommand(options) {
         ? dailyRunProgress
         : namespace === "featured" && action === "candidates"
           ? featuredCandidates
+          : namespace === "game-diagnostics" && action === "summarize"
+            ? gameDiagnosticSummary
           : namespace === "report" && action === "serve"
             ? reportServe
             : null;
   if (composite) {
     const result = await composite(options);
     if (options.adminOutput) {
-      writeFileSync(options.adminOutput, JSON.stringify(result), {
-        mode: 0o600,
-      });
+      if (composite === gameDiagnosticSummary) {
+        writeAdminJsonFile(options.adminOutput, result, { privateFile: true });
+      } else {
+        writeFileSync(options.adminOutput, JSON.stringify(result), {
+          mode: 0o600,
+        });
+      }
     }
     console.log(JSON.stringify(result, null, options.json ? 0 : 2));
     if (result && result.ok === false) process.exitCode = 1;
@@ -2409,6 +2444,7 @@ const FEATURED_RUN_OPERATIONS = new Set([
 // run's write work without the newspaper, sponsor scan or bank seeding (the
 // API holds the same line through the run's scopes).
 const APPROVALS_RUN_EXCLUDED_OPERATIONS = new Set([
+  "subject.website-update.post",
   "news.claim",
   "news.print",
   "news.submit",
@@ -2427,6 +2463,7 @@ export function assertAdminOperationAllowedForRunScope({
         "news.claim",
         "news.submit",
         "news.print",
+        "subject.website-update.post",
         "daily-run.complete",
         "daily-run.fail",
       ].includes(operation.name)
@@ -2674,6 +2711,9 @@ export function parseAdminOperation(options) {
   if (namespace === "owner-trace") {
     return buildOwnerTraceOperation(options);
   }
+  if (namespace === "jev-routing") {
+    return buildJevRoutingReviewOperation({ action, target, extra, options });
+  }
   // Who holds which management level (admin-roles.js); read-only, no run.
   if (namespace === "roles") {
     return buildRolesOperation(options);
@@ -3696,7 +3736,8 @@ export function parseAdminOperation(options) {
     if (days > 30 || userId && !buildId) throw cliValidationError("Use --build with --user; --days must be 1–30.");
     return readOperation("reward-diagnostics.read", withQuery("/cli/admin/reward-diagnostics", {
       buildId: buildId || undefined, userId: userId || undefined, days,
-      before: options.adminCursor ? parseRequiredInteger(options.adminCursor, "--cursor", 1) : undefined
+      before: options.adminCursor ? parseRequiredInteger(options.adminCursor, "--cursor", 1) : undefined,
+      until: options.adminUntil ? parseRequiredInteger(options.adminUntil, "--until", 1) : undefined
     }), { requiresRun: false });
   }
 
@@ -4162,6 +4203,22 @@ export function parseAdminOperation(options) {
   }
 
   if (namespace === "subject") {
+    if (action === "post-update") {
+      if (target || extra || !options.adminFile) {
+        throw cliValidationError("Usage: lumine admin subject post-update --file <article.json> [--confirm]. Preview is the default.");
+      }
+      const article = readAdminJsonFile(options.adminFile, "--file", { maxBytes: 256 * 1024 });
+      if (!article || typeof article !== "object" || Array.isArray(article)) {
+        throw cliValidationError("The article file must contain one composed website-update object.");
+      }
+      if (options.adminConfirm && options.adminConfirm !== "true") {
+        throw cliValidationError("Pass --confirm on its own, without a value.");
+      }
+      const confirm = options.adminConfirm === "true";
+      if (confirm && options.adminDryRun) throw cliValidationError("Choose --confirm or --dry-run, not both.");
+      const operation = confirm ? writeOperation : bodyReadOperation;
+      return operation("subject.website-update.post", "POST", "/cli/admin/subjects/website-update", { article, confirm });
+    }
     if (action === "get") return subjectGetOperation(target, options);
     if (action === "comments") {
       const subjectId = parseSubjectId(target);
@@ -7595,6 +7652,10 @@ function printAdminResult({ operation, result }) {
     printOwnerTrace(data);
     return;
   }
+  if (operation.name === "jevRouting.review") {
+    for (const line of formatJevRoutingReview(data)) console.log(line);
+    return;
+  }
   if (operation.name === "roles.read") {
     printRoles(data);
     return;

package/lib/commands.js

@@ -2474,6 +2474,7 @@ export function parseArgs(args) {
   const booleanFlags = new Set([
     // lumine admin arena import --live
     "live",
+    "additive",
     "remove",
     "fault",
     "noAnnounce",
@@ -2507,6 +2508,7 @@ export function parseArgs(args) {
     "wake",
     "includeLegacy",
     "includePrivateEvidence",
+    "includeSynthetic",
     "allFlagged",
     "reviewed",
     "noReviewLoop",
@@ -2680,6 +2682,8 @@ export function parseArgs(args) {
     adminApprove: raw.approve ? String(raw.approve) : "",
     adminSinceRun: Boolean(raw.sinceRun),
     adminSince: raw.since ? String(raw.since) : "",
+    adminUntil: raw.until ? String(raw.until) : "",
+    adminIncludeSynthetic: Boolean(raw.includeSynthetic),
     adminPath: raw.path ? String(raw.path) : "",
     adminPerf: Boolean(raw.perf),
     adminWake: Boolean(raw.wake),
@@ -2701,6 +2705,7 @@ export function parseArgs(args) {
     // lumine admin arena (admin-arena.js)
     adminArenaAudio: raw.audio ? String(raw.audio) : "",
     adminArenaLive: parseBoolean(raw.live, false),
+    adminArenaAdditive: parseBoolean(raw.additive, false),
     adminArenaItem: raw.item ? String(raw.item) : "",
     adminArenaTo: raw.to ? String(raw.to) : "",
     adminClaimFile: raw.claim ? String(raw.claim) : "",
@@ -2851,6 +2856,10 @@ export function parseArgs(args) {
     adminTarget: raw.target ? String(raw.target) : "",
     adminActions: raw.actions ? String(raw.actions) : "",
     adminDate: raw.date ? String(raw.date) : "",
+    adminCostDate: raw.costDate ? String(raw.costDate) : "",
+    adminPhase: raw.phase ? String(raw.phase) : "",
+    adminMaxSteps: raw.maxSteps ?? "",
+    adminMaxSeconds: raw.maxSeconds ?? "",
     adminDays: raw.days ? String(raw.days) : "",
     adminSpendingMonth: raw.month,
     adminSpendingFrom: raw.from,
@@ -3316,7 +3325,7 @@ export function printHelp() {
   lumine admin cardcraft-review list [--status pending|approved|all] [--cursor <id>] | show <id> | approve|reject|revoke <id> [--reason <text>]
   lumine admin craft seed --build <id> --file <pairs.json> [--confirm] | stats --build <id> [--limit <1-100>] | revise --build <id> --item <id|name> [--why <text>] [--emoji <emoji>] [--category <field>] [--confirm] | revise --build <id> --pair <pairId|a+b> --why <text> [--confirm] | retire --build <id> --item <id|name> --reason <text> [--confirm] | unfizzle --build <id> [--since <iso>] [--pair <a+b>] [--confirm]   (Twinkle.craft curation: dry run without --confirm)
   lumine admin sliding-block status | add --file <levels.json> [--confirm]   (sliding-block-v1 campaign refills, RushHour: dry run without --confirm; the server solves each board and appends it)
-  lumine admin arena queue | import --dir <paper folder> [--audio audio/<exam>/<paper>] [--live] [--confirm] | status --item <id> --to live|retired|checked --confirm   (Arena's mock-exam bank: import is a validation-only dry run without --confirm; upload audio first with twinkle-api scripts/arena-upload-media.ts)
+  lumine admin arena queue | paper-queue [--cursor <id>] [--limit <1-100>] | import --dir <paper folder> [--audio audio/<exam>/<paper>] [--live] [--confirm] | status --item <id> --to live|retired|checked --confirm   (Arena's mock-exam bank: import is a validation-only dry run without --confirm; upload audio first with twinkle-api scripts/arena-upload-media.ts)
   lumine admin nonogram status | add --file <pictures.json> | retire <key> | restore <key> [--confirm]   (private reviewed pictures; changes are dry runs without --confirm)
   lumine admin build-plans stuck [--days <1-90>] [--all] | recheck <buildId> [<buildId> ...] [--confirm]   (Lumine Build plans stuck on one milestone: runs, Energy vs estimate, gradings, loop-guard state; recheck re-grades the current milestone with today's evaluator, free for the creator, dry run without --confirm)
   lumine admin storage list [--status pending|approved|rejected|all] [--cursor <id>] | show <user-id-or-username> | approve <request-id> [--size <500MB|1GB|2GB|n MB>] [--reason <text>] | reject <request-id> [--reason <text>] | grant <user-id-or-username> --size <500MB|1GB|2GB|n MB> [--reason <text>]
@@ -3324,6 +3333,7 @@ export function printHelp() {
   lumine admin meetup story list | show <crewId> | approve <crewId> [--note <text>] [--no-announce] | send-back <crewId> --note <text> | unpublish <crewId> --note <text>   (Bridge Builder story pages: publishes only what every tagged member's parent allowed)
   lumine admin reward-activity [--date YYYY-MM-DD] [--days <1..31>] [--build <id>] [--json]
   lumine admin reward-diagnostics [--build <id> --user <id>] [--days <1..30>] [--cursor <id>] [--json]
+  lumine admin game-diagnostics summarize --file <envelope.json> [--json]   (local retained sharedDb receipts; deduplicates stable events, preserves delivery and coverage limits)
   lumine admin chat-reports list [--status pending|open|reviewing|resolved|dismissed|all] [--cursor <id>] [--json]
   lumine admin chat-reports show <report-id> [--json]   (reported message snapshot + surrounding context)
   lumine admin chat-reports set <report-id> --status reviewing|resolved|dismissed|open --note <what was decided> [--json]
@@ -3339,13 +3349,14 @@ export function printHelp() {
   lumine admin reward-review reject|revoke <review-id> --reason <text> [--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 [--since-run|--after <date>|--include-legacy] [--all --checkpoint <file> [--resume]] [--cursor <cursor>] [--limit <number>] [--json]
-  lumine admin daily-run gather --output-dir <dir> [--date YYYY-MM-DD] [--json]   (all read-only daily reports + bot-output pages + bot-chats.txt)
+  lumine admin daily-run gather --output-dir <dir> [--cost-date YYYY-MM-DD] [--phase priority|evidence|all] [--max-steps 200] [--max-seconds 900] [--resume] [--json]   (closed UTC cost day; resumable collection, never automatic review)
   lumine admin daily-run progress --dir <dir> [--file <duty-evidence.json>] [--json]   (reading, canonical effort counts, pending duties)
   lumine admin featured candidates [--days 7] [--after <iso>] [--json]   (recent, provably never-Featured Subjects with comment counts)
   lumine admin report serve --file <report.md> [--port <n>] [--open] [--json]   (loopback report page with section nav)
   lumine admin builds review <build-url-or-id> [--output-dir <dir>] [--wait-ms <ms>] [--interact <steps.json>] [--browser-path <path>] [--json]
   lumine admin subjects candidates [--since-run|--after <date>|--include-legacy] [--effort unassigned] [--unviewed|--viewed] [--all --checkpoint <file> [--resume]] [--cursor <cursor>] [--json]
   lumine admin subject get|reveal <subject-url-or-id> [--json]
+  lumine admin subject post-update --file <article.json> [--confirm] [--json]
   lumine admin subject comments <subject-url-or-id> [--unviewed|--viewed] [--all --checkpoint <file> [--resume]] [--cursor <cursor>] [--json]
   lumine admin subject effort set <subject-id> --level <1|2|3> [--json]
   lumine admin subject creator set-made-by-poster <subject-id> [--json]
@@ -3372,6 +3383,7 @@ export function printHelp() {
   lumine admin reward-bank report <buildId> [--days 1] [--json]   (question-bank telemetry: generation outcomes, learners, payouts, ladder, questions to review)
   lumine admin owner-trace [--since 2h|30m|3d|<iso>] [--type route,feed-open,scroll-anchor,content-scroll,error,rejection,session,nav-timing,slow-request,stall,page-load,scroll-perf,scroll-frame] [--perf] [--wake] [--path <substring>] [--limit 300] [--json]   (--wake: sessions, 20 s wake profiles, bounded viewport geometry and dropped-event counts after loads or returns; network tags identify the upload network; what the website did on Mikey's own devices: routes with PUSH/POP/REPLACE, Home feed card opens, scroll-anchor restores, content scroll positions, window errors, and performance: tap-to-page timing, API requests over 1 s, main-thread stalls over 200 ms, page load, scroll frame pacing and slow-frame attribution (Long Animation Frame scripts on Chrome, feed card renders on Safari); --perf shows only those; kept 30 days)
   lumine admin roles [--min-level 1] [--limit 50] [--json]   (every user type with its management level and who holds it; admin pages need level 3, achievement points never pass level 2)
+  lumine admin jev-routing review --since <unix|ISO> --until <unix|ISO> [--limit 1..20] [--cursor <cursor> | --all --checkpoint <file> [--resume]] [--include-synthetic] [--json]   (bounded frozen evidence for paired disagreements and Auto fallbacks; collection is not review)
   lumine admin comment draft <target> [--type subject|comment|build|aiStory|dailyReflection] [--file <comment.md>] [--review-receipt <review.json>|--reviewed-version <id> --reviewed-via runtime|code] [--review-context <context.json>] [--identity zero|ciel|auto] [--json]
   lumine admin comment reply comment:<id> [--file <reply.md>] [--reviewed-version <id> --reviewed-via runtime|code] [--review-context <context.json>] [--identity zero|ciel|auto] [--json]
   lumine admin comment post --draft-id <id> [--json]

package/lib/game-diagnostic-summary.js

@@ -0,0 +1,204 @@
+import { createHash } from "node:crypto";
+
+const MAX_BYTES = 16 * 1024 * 1024;
+const MAX_ROWS = 10000;
+const DELIVERY_NUMBERS = new Set([
+  "v", "pending", "acknowledged", "requestFailures", "evicted", "expired",
+  "exhausted", "storageFailures", "oversized", "invalid", "attempt", "attempts",
+  "failures", "localEvictions", "coalescedBatches", "retryInMs"
+]);
+const DELIVERY_FIELDS = new Set([...DELIVERY_NUMBERS, "sending", "lastOutcome"]);
+const KINDS = new Set([
+  "lifecycle", "launch-outcome", "save-failed", "save-ok", "save-load-failed",
+  "save-protected", "save-recovered", "soundtrack-diagnostics", "error", "startup"
+]);
+const EVENTS = new Set([
+  "hidden", "visible", "blur", "focus", "pagehide", "session_started", "action",
+  "battle_choice", "board_solved", "board_started", "fight_left", "fight_result",
+  "fight_started", "input", "lesson_step", "progress", "puzzle_progress",
+  "runtime_error", "save_status", "scene", "stalled"
+]);
+const SOUNDTRACK_COUNTERS = new Set([
+  "ready", "recommendations", "recommendations-empty", "tag-load", "tag-search",
+  "tag-submit", "tag-remove", "lock-open", "lock-open-failed", "progress-load", "progress-save"
+]);
+const record = value => value !== null && typeof value === "object" &&
+  (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null);
+const positiveId = value => Number.isSafeInteger(value) && value > 0;
+const stableId = value => typeof value === "string" && /^[\w:.-]{1,160}$/.test(value);
+const hash = text => createHash("sha256").update(text).digest("hex");
+
+// Validate the pure helper too: a caller need not have used the CLI's file cap.
+// Sort keys for semantic comparison, but never mutate the retained source.
+function canonicalJson(value, limit = MAX_BYTES) {
+  let bytes = 0;
+  const ancestors = new Set();
+  const token = text => {
+    bytes += Buffer.byteLength(text);
+    if (bytes > limit) throw new Error("Game diagnostic JSON exceeds its byte limit.");
+    return text;
+  };
+  function visit(item, depth) {
+    if (depth > 32) throw new Error("Game diagnostic JSON exceeds depth 32.");
+    if (item === null || typeof item === "boolean") return token(JSON.stringify(item));
+    if (typeof item === "number" && Number.isFinite(item)) return token(JSON.stringify(item));
+    if (typeof item === "string") {
+      if (item.length > limit) throw new Error("Game diagnostic JSON exceeds its byte limit.");
+      return token(JSON.stringify(item));
+    }
+    if ((!Array.isArray(item) && !record(item)) || ancestors.has(item)) throw new Error("Game diagnostics require finite, acyclic JSON values.");
+    ancestors.add(item);
+    const parts = [];
+    if (Array.isArray(item)) {
+      parts.push(token("["));
+      for (let i = 0; i < item.length; i++) {
+        if (i) parts.push(token(","));
+        parts.push(visit(item[i], depth + 1));
+      }
+      parts.push(token("]"));
+    } else {
+      parts.push(token("{"));
+      for (const key of Object.keys(item).sort()) {
+        if (parts.length > 1) parts.push(token(","));
+        parts.push(token(JSON.stringify(key)), token(":"), visit(item[key], depth + 1));
+      }
+      parts.push(token("}"));
+    }
+    ancestors.delete(item);
+    return parts.join("");
+  }
+  return visit(value, 0);
+}
+
+function semanticJson(data) {
+  if (!record(data.delivery)) return canonicalJson(data, 16384);
+  const semantic = { ...data };
+  const remaining = Object.entries(data.delivery).filter(([key]) => !DELIVERY_FIELDS.has(key));
+  if (remaining.length) semantic.delivery = Object.fromEntries(remaining);
+  else delete semantic.delivery;
+  return canonicalJson(semantic, 16384);
+}
+
+function deliverySnapshot(data) {
+  if (!record(data.delivery)) return null;
+  const snapshot = {};
+  for (const key of DELIVERY_NUMBERS) {
+    const value = data.delivery[key];
+    if (Number.isSafeInteger(value) && value >= 0) snapshot[key] = value;
+  }
+  if (typeof data.delivery.sending === "boolean") snapshot.sending = data.delivery.sending;
+  if (["none", "viewer-changed", "acknowledged", "failed"].includes(data.delivery.lastOutcome)) snapshot.lastOutcome = data.delivery.lastOutcome;
+  return Object.keys(snapshot).length ? snapshot : null;
+}
+
+function coverageOf(value) {
+  if (value !== undefined && !record(value)) throw new Error("Game diagnostic coverage must be an object.");
+  const coverage = { complete: value?.complete === true };
+  if (value?.complete !== undefined && typeof value.complete !== "boolean") throw new Error("Coverage complete must be a boolean.");
+  for (const key of ["since", "until"]) if (value?.[key] !== undefined) {
+    if (!Number.isSafeInteger(value[key]) || value[key] < 0) throw new Error("Coverage boundaries must be nonnegative integers.");
+    coverage[key] = value[key];
+  }
+  if (coverage.since !== undefined && coverage.until !== undefined && coverage.since >= coverage.until) throw new Error("Coverage until must be after since.");
+  return coverage;
+}
+
+/** Local, metadata-only summary. Input rows remain the canonical evidence. */
+export function summarizeGameDiagnostics(envelope) {
+  if (!record(envelope) || !positiveId(envelope.buildId) ||
+      typeof envelope.topic !== "string" || !/^[\w.-]{1,100}$/.test(envelope.topic) ||
+      !Array.isArray(envelope.entries) || envelope.entries.length > MAX_ROWS) {
+    throw new Error("Expected {buildId, topic, entries}; buildId must be positive, topic a technical name and entries at most 10000 rows.");
+  }
+  canonicalJson(envelope);
+  const collection = coverageOf(envelope.coverage);
+  const receipts = new Map(), groups = new Map(), legacy = [], observations = [];
+  let duplicateInputRows = 0, stableRows = 0, unknownArtifactRows = 0;
+  for (const entry of envelope.entries) {
+    if (!record(entry) || !positiveId(entry.id) || !positiveId(entry.userId) || !positiveId(entry.topicId) || !record(entry.data)) {
+      throw new Error("Every diagnostic entry requires canonical positive id, userId, topicId and object data; payload viewerId is not identity.");
+    }
+    if (entry.buildId !== undefined && entry.buildId !== envelope.buildId) throw new Error("Entry buildId does not match the envelope.");
+    const data = entry.data;
+    if (data.artifactVersionId != null && !positiveId(data.artifactVersionId)) throw new Error("artifactVersionId must be positive or unknown.");
+    for (const field of ["eventId", "batchId"]) if (data[field] != null && !stableId(data[field])) throw new Error(`Invalid diagnostic ${field}.`);
+    const exact = canonicalJson(data, 16384);
+    const receiptHash = hash(canonicalJson([entry.userId, entry.topicId, data.artifactVersionId ?? null, exact]));
+    if (receipts.has(entry.id)) {
+      if (receipts.get(entry.id) !== receiptHash) throw new Error("Conflicting copies of one canonical entry ID; inspect the retained raw source.");
+      duplicateInputRows++;
+      continue;
+    }
+    receipts.set(entry.id, receiptHash);
+    const artifactVersionId = data.artifactVersionId ?? null;
+    if (artifactVersionId === null) unknownArtifactRows++;
+    const fields = { entryId: entry.id, userId: entry.userId, topicId: entry.topicId, artifactVersionId };
+    const snapshot = deliverySnapshot(data);
+    if (snapshot) observations.push({ ...fields, delivery: snapshot });
+    const idType = data.eventId != null ? "eventId" : data.batchId != null ? "batchId" : null;
+    if (!idType) { legacy.push(data); continue; }
+    stableRows++;
+    const key = canonicalJson([envelope.buildId, envelope.topic, entry.topicId, entry.userId, artifactVersionId, idType, data[idType]]);
+    let group = groups.get(key);
+    if (!group) {
+      group = { ...fields, idType, stableId: data[idType], hashes: new Map(), rows: 0 };
+      groups.set(key, group);
+    }
+    group.rows++;
+    const fingerprint = hash(semanticJson(data));
+    let variant = group.hashes.get(fingerprint);
+    if (!variant) { variant = { data, entryIds: [] }; group.hashes.set(fingerprint, variant); }
+    variant.entryIds.push(entry.id);
+  }
+
+  const counted = [...legacy], collisions = [];
+  let uniqueStableEvents = 0, retryDuplicateReceipts = 0, collisionGroups = 0, collidingReceipts = 0;
+  for (const group of groups.values()) {
+    if (group.hashes.size > 1) {
+      collisionGroups++; collidingReceipts += group.rows;
+      if (collisions.length < 100) collisions.push({ userId: group.userId, topicId: group.topicId,
+        artifactVersionId: group.artifactVersionId, idType: group.idType, stableId: group.stableId,
+        receipts: group.rows, variants: [...group.hashes].slice(0, 20).map(([sha256, variant]) => ({ sha256,
+          entryIds: variant.entryIds.slice(0, 20), omittedEntryIds: Math.max(0, variant.entryIds.length - 20) })),
+        omittedVariants: Math.max(0, group.hashes.size - 20) });
+      continue;
+    }
+    uniqueStableEvents++; retryDuplicateReceipts += group.rows - 1;
+    counted.push(group.hashes.values().next().value.data);
+  }
+  const byKind = {}, alzebraEventNames = {}, soundtrackCounters = {};
+  let invalidCounterMetrics = 0;
+  for (const data of counted) {
+    const kind = data.batchId && !data.kind ? "alzebra-batch" : KINDS.has(data.kind) ? data.kind : "other";
+    byKind[kind] = (byKind[kind] || 0) + 1;
+    if (kind === "alzebra-batch" && Array.isArray(data.events)) for (const event of data.events) {
+      const name = EVENTS.has(event?.name) ? event.name : "other";
+      alzebraEventNames[name] = (alzebraEventNames[name] || 0) + 1;
+    }
+    if (kind === "soundtrack-diagnostics" && record(data.counters)) for (const name of SOUNDTRACK_COUNTERS) {
+      const value = data.counters[name];
+      if (value === undefined) continue;
+      if (!record(value) || !["count", "failed", "durationMs", "maxMs"].every(key => Number.isSafeInteger(value[key]) && value[key] >= 0 && value[key] <= 1e11) || value.failed > value.count) {
+        invalidCounterMetrics++;
+        continue;
+      }
+      const total = soundtrackCounters[name] ||= { count: 0, failed: 0, durationMs: 0, maxMs: 0 };
+      total.count += value.count; total.failed += value.failed; total.durationMs += value.durationMs;
+      total.maxMs = Math.max(total.maxMs, value.maxMs);
+    }
+  }
+  observations.sort((a, b) => b.entryId - a.entryId);
+  return {
+    schema: 1, buildId: envelope.buildId, topic: envelope.topic, collection,
+    rows: { input: envelope.entries.length, canonical: receipts.size, duplicateInputRows,
+      stableRows, legacyRows: legacy.length, unknownArtifactRows },
+    deduplication: { coverage: receipts.size === 0 ? "empty" : legacy.length || unknownArtifactRows || collisionGroups ? "partial" : "complete",
+      uniqueStableEvents, retryDuplicateReceipts, collisionGroups, collidingReceipts,
+      countedEvents: counted.length, collisions, omittedCollisions: Math.max(0, collisionGroups - collisions.length) },
+    counts: { byKind, alzebraEventNames, soundtrackCounters, invalidCounterMetrics },
+    delivery: { observations: observations.slice(0, 100), totalObservations: observations.length,
+      omittedObservations: Math.max(0, observations.length - 100),
+      note: "Per-receipt client snapshots; cumulative counters are not summed. An acknowledged count concerns earlier client receipts, not this row's gameplay save." },
+    note: "Preserve and read the raw receipts. Legacy rows remain separate and may contain retries; unknown artifacts are not version evidence. Collisions are excluded from event counts. Collection completeness describes supplied server rows, not successful delivery of every client event."
+  };
+}

package/package.json

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