@stage5/lumine 0.3.47 → 0.3.49

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.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

@@ -3261,6 +3261,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)

package/lib/constants.js

@@ -350,7 +350,7 @@ lumine save --summary "Describe the change"
 - Use local project files with relative or root-local imports only. Do not add package imports, CDN scripts, external network calls, or app-local /api/* routes.
 - Build apps run in sandboxed iframes without allow-forms. Do not use <form> elements, native form submission, requestSubmit(), or browser form navigation. Build input flows with JavaScript-handled inputs and buttons instead.
 ${LUMINE_MOBILE_SELECTION_GUIDANCE}
-- CAUTION: the preview runtime AUTO-DETECTS "game apps" — any <canvas> in the body (even a decorative background canvas) switches the app to viewport-app mode: html/body get overflow:hidden !important and body becomes a centering flexbox, so tall document-flow pages clip and stop scrolling. Document-style apps that use a canvas must call Twinkle.preview.subscribe (or getLayout/reserveInsets) early at boot — any of those opts out of auto game mode — then pad by layout.safeInsets and scroll within layout.viewport.height.
+- CAUTION: the preview runtime AUTO-DETECTS "game apps" — any <canvas> in the body except a small one on screen (both sides at most 160 CSS px: a visualizer, a sparkle, an icon) switches the app to viewport-app mode: html/body get overflow:hidden !important and body becomes a centering flexbox, so tall document-flow pages clip and stop scrolling. A hidden or not-yet-sized canvas counts too, and a page that sets data-twinkle-game keeps this layout with any canvas. Document-style apps with a larger canvas (a chart, a drawing pad, a background effect) set data-twinkle-document on <html> or <body>, or call Twinkle.preview.subscribe (or getLayout/reserveInsets) early at boot and then pad by layout.safeInsets and scroll within layout.viewport.height.
 - For canvas, WebGL, Three.js, fullscreen, or game builds, use Twinkle.preview for layout. Do not size roots from 100vh, 100vw, 100dvh, 100dvw, window.innerWidth, window.innerHeight, visualViewport, or document viewport dimensions.
 ${LUMINE_THREE_VENDOR_GUIDANCE}
 ${LUMINE_MATH_VENDOR_GUIDANCE}

package/package.json

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

package/sdk/BUILD_SDK_INDEX.md

@@ -2,7 +2,7 @@
 
 Version: 1.68.0
 Updated: 2026-10-16
-Generated: 2026-10-18T22:57:11.632Z
+Generated: 2026-10-19T05:26:13.264Z
 
 ## Notes
 - This SDK is injected into Build iframes via the Build preview/runtime.
@@ -25,7 +25,7 @@ Generated: 2026-10-18T22:57:11.632Z
 - Twinkle.ai.chat history entries must use { role, content }; map local message.text fields to content before passing history.
 - Live web search is enabled by default for Twinkle.ai.chat and for Medium/High Twinkle.ai.generateObject and Twinkle.characters.chat requests. App authors can pass webSearch: false to disable it for their app. Search uses the provider's live web-search tool and is included in AI Energy usage; structured and character Lite Mode remains tool-free.
 - Mobile long-press must not select game UI or open browser Copy/Look Up/image menus. The SDK provides no-selection/callout defaults for standard buttons, button-like ARIA controls, and canvases. Mark the entire custom gameplay wrapper data-twinkle-no-select, including HUD, labels, scores, menus, controls, and empty play space; also style it with user-select: none, -webkit-user-select: none, and -webkit-touch-callout: none for local previews. Protecting only one button or the canvas is insufficient. This behavior is independent of Twinkle.preview layout mode.
-- Played game pages block text selection, the long-press menu and page pinch-zoom everywhere except inputs, textareas, contenteditable and data-twinkle-selectable text, so text a game shows for copying (a chat log, a word to copy) needs data-twinkle-selectable. A page is a played game when the app sets data-twinkle-game on <html> or <body>, or, for apps that do not lay themselves out with Twinkle.preview, when a play-sized canvas is on screen: rendered, not pointer-events:none, and covering at least 30% of the viewport by its layout size; the page then stays a played game while that canvas is in the document, even hidden between screens. Set data-twinkle-game on a game that sizes itself with Twinkle.preview, a DOM-only game, or a small-canvas game; set data-twinkle-document to keep a canvas page (charts, drawing pad) an ordinary page; set data-twinkle-allow-zoom to keep page pinch-zoom on a game. Page layout is not affected by any of this.
+- Played game pages block text selection, the long-press menu and page pinch-zoom everywhere except inputs, textareas, contenteditable and data-twinkle-selectable text, so text a game shows for copying (a chat log, a word to copy) needs data-twinkle-selectable. A page is a played game when the app sets data-twinkle-game on <html> or <body>, or, for apps that do not lay themselves out with Twinkle.preview, when a play-sized canvas is on screen: rendered, not pointer-events:none, and covering at least 30% of the viewport by its layout size; the page then stays a played game while that canvas is in the document, even hidden between screens. Set data-twinkle-game on a game that sizes itself with Twinkle.preview, a DOM-only game, or a small-canvas game; set data-twinkle-document to keep a canvas page (charts, drawing pad) an ordinary page, which also keeps it out of viewport-app layout so it scrolls; set data-twinkle-allow-zoom to keep page pinch-zoom on a game. Viewport-app layout (html/body pinned to the screen, no page scroll) turns on for any canvas except a small one on screen (both sides at most 160 CSS px); data-twinkle-game keeps it for any canvas, and data-twinkle-document or laying the page out with Twinkle.preview turns it off.
 - Keep inputs/contenteditable usable. Mark genuinely copyable story/chat/user-written text data-twinkle-selectable and style it with user-select: text, -webkit-user-select: text, and -webkit-touch-callout: default. SDK defaults have low specificity so existing explicit copyable-text styles remain effective. Preserve document/reader selection; do not block document-wide touch/pointer events or disable scrolling/zoom to prevent selection.
 - Verify mobile long presses on controls, HUD, and empty play space in Safari and Chromium; confirm held controls still work and release/cancel correctly, and scrolling, typing, and copying still work. lumine check only detects a missing no-selection rule, not selector coverage or mobile behavior.
 - Build app tab mute is enforced by the host runtime automatically for standard media elements and Web Audio connections to AudioContext.destination. Apps with custom audio engines can also observe Twinkle.onAudioMuteChange and check Twinkle.isAudioMuted.