@stage5/lumine 0.3.48 → 0.3.50

package/lib/admin-build-plans.js

@@ -0,0 +1,118 @@
+// `lumine admin build-plans stuck|recheck`: Lumine Build plans whose current
+// milestone is not finishing (twinkle-api controllers/cli/admin/buildPlans.ts).
+// stuck lists running plans with their current milestone's runs, Energy vs
+// estimate, gradings and loop-guard state (flagged ones only unless --all).
+// recheck re-grades the current milestone of up to 10 builds with today's
+// evaluator, free for the creator; it is a dry run unless --confirm is given.
+
+export const BUILD_PLANS_USAGE =
+  "Usage: lumine admin build-plans stuck [--days <1-90>] [--all] | recheck <buildId> [<buildId> ...] [--confirm] [--json]";
+const RECHECK_MAX = 10;
+
+function validationError(message) {
+  const error = new Error(message);
+  error.code = "CLI_ADMIN_CLI_VALIDATION";
+  return error;
+}
+
+function confirmed(options) {
+  const confirm = options.adminConfirm;
+  // absent is "", a bare --confirm is "true"
+  if (confirm !== "" && confirm !== "true") {
+    throw validationError("Pass --confirm on its own, without a value.");
+  }
+  return confirm === "true";
+}
+
+export function buildBuildPlansOperation({ action, options }) {
+  if (!action || action === "stuck") {
+    const query = new URLSearchParams();
+    if (options.adminDays) {
+      const days = Number(options.adminDays);
+      if (!Number.isSafeInteger(days) || days < 1 || days > 90) {
+        throw validationError("--days must be a whole number from 1 to 90.");
+      }
+      query.set("days", String(days));
+    }
+    if (options.adminAll) query.set("all", "1");
+    const qs = query.toString();
+    return {
+      name: "build-plans.stuck",
+      method: "GET",
+      path: `/cli/admin/build-plans/stuck${qs ? `?${qs}` : ""}`,
+      body: undefined,
+      mutates: false,
+      requiresRun: false,
+    };
+  }
+  if (action === "recheck") {
+    const ids = (options.positional || [])
+      .slice(2)
+      .map((value) => String(value).split(","))
+      .flat()
+      .filter(Boolean)
+      .map((value) => Number(value));
+    if (
+      !ids.length ||
+      ids.length > RECHECK_MAX ||
+      ids.some((id) => !Number.isSafeInteger(id) || id <= 0)
+    ) {
+      throw validationError(`Give 1 to ${RECHECK_MAX} build ids. ${BUILD_PLANS_USAGE}`);
+    }
+    const confirm = confirmed(options);
+    return {
+      name: confirm ? "build-plans.recheck" : "build-plans.recheck.preview",
+      method: "POST",
+      path: "/cli/admin/build-plans/recheck",
+      body: { buildIds: [...new Set(ids)], dryRun: !confirm },
+      mutates: confirm,
+      requiresRun: false,
+      // One grading per build, one at a time, each up to a few minutes.
+      timeoutMs: 15 * 60 * 1000,
+    };
+  }
+  throw validationError(BUILD_PLANS_USAGE);
+}
+
+function formatRow(row) {
+  const ratio = row.energyRatio == null ? "?" : `${row.energyRatio}x`;
+  const milestone =
+    row.milestoneIndex == null ? "-" : `${row.milestoneIndex + 1}/${row.milestones}`;
+  const coverage = row.coverage
+    ? ` files ${row.coverage.shown}/${row.coverage.total}${row.coverage.toolRounds ? ` +${row.coverage.toolFilesRead} read in ${row.coverage.toolRounds} rounds` : ""}${row.coverage.omittedReferenced ? `, ${row.coverage.omittedReferenced} referenced omitted` : ""}`
+    : "";
+  const state = row.stalled
+    ? ` STALLED(${row.stallReason})`
+    : row.wouldStall
+      ? ` would stall (${row.wouldStall})`
+      : "";
+  return `Build ${row.buildId}: milestone ${milestone} (${row.milestonesDone} done), ${row.runs} runs, Energy ${ratio} of estimate, ${row.evaluations ?? "?"} gradings, non-pass streak ${row.consecutiveNonPass ?? "?"}, ${row.passed}/${row.criteria} passing, ${row.unverified} unverified${state};${coverage}${row.flags?.length ? ` [${row.flags.join(", ")}]` : ""}`;
+}
+
+export function formatBuildPlansResult({ operation, data }) {
+  if (operation.name === "build-plans.stuck") {
+    const rows = data?.rows || [];
+    return [
+      `${data?.running ?? 0} running build plan(s); ${data?.inWindow ?? rows.length} updated in the last ${data?.days} days or stalled (${data?.stalled ?? 0} stalled); ${rows.length} shown.`,
+      ...rows.map(formatRow),
+    ];
+  }
+  const lines = [];
+  for (const error of data?.errors || []) {
+    lines.push(`Skipped "${error.value}": ${error.reason === "duplicate" ? "listed twice" : "not a build id"}`);
+  }
+  if (data?.dryRun) {
+    lines.push(`Dry run: would recheck ${data?.buildIds?.length || 0} build(s).`);
+    for (const row of data?.rows || []) lines.push(formatRow(row));
+    lines.push("Nothing was graded. Add --confirm to recheck them (free for the creators).");
+    return lines;
+  }
+  for (const result of data?.results || []) {
+    lines.push(
+      result?.ok
+        ? `${result.replayed ? "(already rechecked by this request) " : ""}Build ${result.buildId}: milestone ${result.milestoneIndex + 1} ${result.verdict}, ${result.passed}/${result.criteria} passing, ${result.unverified} unverified${result.milestoneCompleted ? ", milestone completed" : ""}${result.stalled ? `, stalled (${result.stalled.reason})` : ""}${result.fileCoverage ? `; files ${result.fileCoverage.shownFiles}/${result.fileCoverage.totalFiles} + ${result.fileCoverage.toolFilesRead || 0} read in ${result.fileCoverage.toolRounds || 0} rounds` : ""}${result.usage ? `; cost ${result.usage.energyUnits} Energy units (${result.usage.inputTokens} in / ${result.usage.outputTokens} out tokens), not charged to the creator` : ""}`
+        : `Build ${result?.buildId}: not rechecked (${result?.reason === "run_in_progress" ? "a Lumine run is in progress; try again later" : result?.reason || "unknown"})`,
+    );
+  }
+  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] [--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

@@ -49,6 +49,10 @@ import {
   buildSlidingBlockOperation,
   formatSlidingBlockResult,
 } from "./admin-sliding-block.js";
+import {
+  buildBuildPlansOperation,
+  formatBuildPlansResult,
+} from "./admin-build-plans.js";
 import { formatChatReportResult } from "./admin-chat-reports.js";
 import { formatIdentityDeviceUsage } from "./admin-identity-inspection.js";
 import {
@@ -2646,6 +2650,10 @@ export function parseAdminOperation(options) {
   if (namespace === "sliding-block") {
     return buildSlidingBlockOperation({ action, options });
   }
+  // Stuck Lumine Build plans and their free recheck (admin-build-plans.js).
+  if (namespace === "build-plans") {
+    return buildBuildPlansOperation({ action, options });
+  }
 
   if (namespace === "correction" || namespace === "corrections") {
     if (!action || action === "status") {
@@ -7389,6 +7397,11 @@ function printAdminResult({ operation, result }) {
       console.log(line);
     return;
   }
+  if (operation.name.startsWith("build-plans.")) {
+    for (const line of formatBuildPlansResult({ operation, data }))
+      console.log(line);
+    return;
+  }
   if (operation.name.startsWith("craft.")) {
     const lines = formatCraftResult({ operation, data });
     if (lines) {

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(
@@ -3261,6 +3263,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 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>]
   lumine admin meetup list [--status review|active|completed|all] | show <crewId> | info <crewId> <userId> --decision ask|accept|ask-again|withdraw [--note <text>] | set-branch <crewId> <userId> --branch "<name>" [--note <text>] | branches [list [--status pending|official|rejected|all] | show <id> | approve <id> | reject <id> [--note <text>] | merge <id> --into <officialId>] | emails [list|send <id>|discard <id>|review on|off] | friends [status|on|off] | funnel [--days <1-90>] | announce-checkins [--send] [--as zero|ciel]   (Bridge Builder crews and check-ins)
   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)
@@ -3311,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/package.json

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