@stage5/lumine 0.3.49 → 0.3.51

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] [--path <substring>] [--limit 300] [--json].";
+  "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].";
 
 // --perf: only the performance events (tap-to-page timeline, slow API
 // requests, main-thread stalls, page load).
@@ -15,8 +15,14 @@ export const OWNER_TRACE_PERF_TYPES = [
   "page-load",
   "scroll-perf",
   "scroll-frame",
+  "wake",
 ];
 
+// --wake: the session headers and the wake profiles (what the site did in the
+// 20 s after each load or return to the tab), to compare Wi-Fi and cellular
+// wakes (the server tags both with the network).
+export const OWNER_TRACE_WAKE_TYPES = ["session", "wake"];
+
 const MAX_LIMIT = 2000;
 
 function validationError(message) {
@@ -61,6 +67,11 @@ export function buildOwnerTraceOperation(options) {
       if (!types.includes(type)) types.push(type);
     }
   }
+  if (options.adminWake) {
+    for (const type of OWNER_TRACE_WAKE_TYPES) {
+      if (!types.includes(type)) types.push(type);
+    }
+  }
   if (types.length) query.set("type", types.join(","));
   if (options.adminPath) query.set("path", String(options.adminPath));
   return {
@@ -103,6 +114,12 @@ function describeSession(data = {}, path = "") {
     data.mobile ? "mobile" : "",
     data.standalone ? "standalone (PWA)" : "browser tab",
     data.touch ? `touch ${data.touch}` : "",
+    data.navType === "back_forward"
+      ? "restored (iOS reloaded the discarded tab)"
+      : data.navType
+        ? `nav ${data.navType}`
+        : "",
+    describeNet(data.net),
   ].filter(Boolean);
   if (path) parts.push(`at ${path}`);
   return `${parts.join(" · ")}${data.ua ? `\n      ua: ${data.ua}` : ""}`;
@@ -140,6 +157,8 @@ export function describeOwnerTraceEvent(event) {
       return describeScrollPerf(data);
     case "scroll-frame":
       return describeScrollFrame(data);
+    case "wake":
+      return describeWake(data);
     case "stall":
       return `main thread blocked ${data.ms}ms${data.n > 1 ? ` (${data.n} stalls, ${data.total}ms blocked over ${data.span}ms)` : ""}`;
     case "page-load": {
@@ -160,6 +179,60 @@ export function describeOwnerTraceEvent(event) {
   }
 }
 
+// The network an upload came from: v4/v6 plus an opaque prefix hash. The same
+// tag = the same network (home Wi-Fi vs the carrier).
+function describeNet(net) {
+  if (!net?.id) return "";
+  return `net v${net.v}:${net.id}`;
+}
+
+// What the site did in the window after a load or a return to the tab.
+// A field the server cut to "[cut N chars]" arrives as a string: every list or
+// object is checked before use, so one trimmed row never breaks the output.
+function describeWake(data) {
+  const head =
+    data.kind === "load"
+      ? `LOAD${data.navType === "back_forward" ? " (iOS restore)" : data.navType ? ` (${data.navType})` : ""}`
+      : data.kind === "resume"
+        ? `RESUME after ${formatDuration(data.awayMs)}`
+        : "WAKE (kind unknown)";
+  const socket = isPlainObject(data.socket) ? data.socket : {};
+  const reasons = Array.isArray(socket.reasons) ? socket.reasons : [];
+  const top = Array.isArray(data.top) ? data.top : [];
+  const work = Object.entries(isPlainObject(data.work) ? data.work : {})
+    .map(([name, n]) => `${name}${n > 1 ? ` x${n}` : ""}`)
+    .join(", ");
+  const parts = [
+    head,
+    describeNet(data.net),
+    `${formatDuration(data.windowMs)}${data.end && data.end !== "window" ? ` (ended: ${data.end})` : ""}`,
+    `frames ${data.frames ?? "?"}, ${data.over50 ?? 0} >50ms, ${data.over100 ?? 0} >100ms, max ${data.maxFrameMs ?? "?"}ms, jank ${data.jankMs ?? 0}ms`,
+    data.stalls ? `${data.stalls} stall(s) ${data.stallMs}ms` : "",
+    `${data.requests ?? 0} requests${data.repeats ? ` (${data.repeats} repeats)` : ""}`,
+    data.images ? `${data.images} images` : "",
+    `socket ${socket.atStart === true ? "up" : socket.atStart === false ? "down" : "?"} at start, ${socket.connects ?? 0} connect(s), ${socket.disconnects ?? 0} disconnect(s)${socket.attempts ? `, ${socket.attempts} attempt(s)` : ""}${reasons.length ? ` [${reasons.join(", ")}]` : ""}`,
+    work ? `work ${work}` : "",
+    top.length
+      ? `top ${top.join(", ")}${data.topCut ? ` +${data.topCut} more` : ""}`
+      : "",
+    data._trimmed ? `trimmed ${JSON.stringify(data._trimmed)}` : "",
+  ].filter(Boolean);
+  return parts.join(" · ");
+}
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function formatDuration(ms) {
+  const n = Number(ms);
+  if (!Number.isFinite(n)) return "?";
+  if (n < 1000) return `${Math.round(n)}ms`;
+  if (n < 120_000) return `${Math.round(n / 100) / 10}s`;
+  if (n < 7_200_000) return `${Math.round(n / 60_000)}m`;
+  return `${Math.round(n / 360_000) / 10}h`;
+}
+
 // One Home/page scroll burst: frame pacing plus what was on screen.
 function describeScrollPerf(data) {
   const cards = (data.context?.cards || [])

package/lib/admin.js

@@ -6135,7 +6135,7 @@ export function formatRewardRuleLine(rule) {
   return parts.join(" · ");
 }
 
-function printRewardReviewResult({ operation, data }) {
+export function printRewardReviewResult({ operation, data }) {
   if (operation.name === "reward-review.list") {
     const reviews = Array.isArray(data.reviews) ? data.reviews : [];
     console.log(
@@ -6195,6 +6195,9 @@ function printRewardReviewResult({ operation, data }) {
     console.log("WARNING: the app's own reward check (rewards.verify.js) failed its self-test:");
     for (const finding of review.appCheckFindings) console.log(`  - ${finding}`);
   }
+  // rules only a timer checks: the same warning the creator saw before sending
+  for (const warning of Array.isArray(review.timerOnlyWarnings) ? review.timerOnlyWarnings : [])
+    console.log(`WARNING: ${warning}`);
   if (review.isLatest === false)
     console.log(
       "WARNING: a newer request exists for this app; decide on the latest one.",

package/lib/commands.js

@@ -2469,6 +2469,7 @@ export function parseArgs(args) {
     "resume",
     "sinceRun",
     "perf",
+    "wake",
     "includeLegacy",
     "includePrivateEvidence",
     "allFlagged",
@@ -2639,6 +2640,7 @@ export function parseArgs(args) {
     adminSince: raw.since ? String(raw.since) : "",
     adminPath: raw.path ? String(raw.path) : "",
     adminPerf: Boolean(raw.perf),
+    adminWake: Boolean(raw.wake),
     adminMinLevel: raw.minLevel === undefined ? null : raw.minLevel,
     adminIncludeLegacy: Boolean(raw.includeLegacy),
     adminIncludePrivateEvidence: parseBoolean(
@@ -3312,7 +3314,7 @@ export function printHelp() {
   lumine admin reward-bank coverage <buildId> [--max-step 3] [--json]
   lumine admin reward-bank seed <buildId> [--max-step 3] [--identity zero|ciel|auto] [--json]   (writes ONE missing seed question, lowest step first, billed to Zero/Ciel's AI Energy; inside a daily run or on its own, owner only)
   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] [--path <substring>] [--limit 300] [--json]   (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 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: only sessions and the 20 s wake profiles after each load or return, with the network tag that separates Wi-Fi from cellular; 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 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]

package/lib/rewards.js

@@ -68,7 +68,7 @@ async function checkDeclaration({
   });
 }
 
-function printDeclaration(result, { prefix = "" } = {}) {
+export function printDeclaration(result, { prefix = "" } = {}) {
   const rules = Array.isArray(result?.rules) ? result.rules : [];
   if (result?.ok) {
     console.log(
@@ -87,6 +87,9 @@ function printDeclaration(result, { prefix = "" } = {}) {
         `${prefix}  ${rule.id}: ${rule.title} · ${rule.xp} XP + ${rule.coins} Coins · ${what}`,
       );
     }
+    // rules only a timer checks (the server's warning; never blocks)
+    for (const warning of result.warnings || [])
+      console.log(`${prefix}WARNING: ${warning}`);
     if (result.nextStep) console.log(`${prefix}${result.nextStep}`);
     return;
   }

package/package.json

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