@stage5/lumine 0.3.34 → 0.3.36

package/lib/admin-daily.js

@@ -23,6 +23,7 @@ export function runAdmin(
   args,
   { outputFile, extraEnv, retryRead = false, spawnImpl = spawnSync } = {},
 ) {
+  const startedAt = performance.now();
   const attemptFile = outputFile
     ? `${outputFile}.attempt-${randomUUID()}.json`
     : null;
@@ -78,6 +79,7 @@ export function runAdmin(
     featured: ["list", "history"],
     sponsor: ["applications"],
     "bot-output": [null],
+    "math-lab": ["queue"],
     subjects: ["candidates"],
     subject: ["get"],
   };
@@ -96,6 +98,7 @@ export function runAdmin(
     const retried = runAdmin(args, { outputFile, extraEnv, spawnImpl });
     return {
       ...retried,
+      durationMs: Math.round(performance.now() - startedAt),
       attempts: 2,
       recovered: retried.ok,
       firstError:
@@ -104,6 +107,7 @@ export function runAdmin(
   }
   return {
     ok,
+    durationMs: Math.round(performance.now() - startedAt),
     attempts: 1,
     status: result.status,
     json: error ? { ok: false, status: "unconfirmed", error } : parsed,
@@ -159,6 +163,7 @@ export function renderBotOutput({ chatMessages, comments }, file) {
 }
 
 export async function dailyRunGather(options) {
+  const startedAt = performance.now();
   const dir = ensureDir(
     path.resolve(options.adminOutputDir || options.adminDir || "."),
   );
@@ -172,6 +177,7 @@ export async function dailyRunGather(options) {
       file,
       ok: res.ok,
       attempts: res.attempts,
+      durationMs: res.durationMs,
       recovered: Boolean(res.recovered),
       ...(res.ok ? {} : { error: res.json?.error || res.stderr }),
     });
@@ -180,6 +186,7 @@ export async function dailyRunGather(options) {
   step("energy-budget", ["energy-budget"], "energy-budget.json");
   step("news", ["news"], "news.json");
   step("brief", ["brief"], "brief.json");
+  step("math-lab-queue", ["math-lab", "queue"], "math-lab-queue.json");
   step("ai-costs-monthly", ["ai-costs", "monthly"], "ai-monthly.json");
   step("ai-costs-day", ["ai-costs", "day", yesterday], "ai-day.json");
   step("media-costs", ["media-costs", "monthly"], "media.json");
@@ -239,6 +246,8 @@ export async function dailyRunGather(options) {
   if (botOk) renderBotOutput({ chatMessages, comments }, path.join(dir, "bot-chats.txt"));
 
   const summary = {
+    collectedAt: new Date().toISOString(),
+    durationMs: Math.round(performance.now() - startedAt),
     dir,
     yesterdayUtc: yesterday,
     botOutput: {
@@ -377,13 +386,19 @@ fetch('daily-management-report.md',{cache:'no-store'}).then(r=>{if(!r.ok)throw n
 export function waitForReportServer(child, timeoutMs = 10000) {
   return new Promise((resolve, reject) => {
     let buf = "";
+    let stderr = "";
     let settled = false;
+    const clean = value => String(value || "")
+      .replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, "")
+      .replace(/[\u0000-\u001f\u007f]+/g, " ").trim().slice(-2048);
+    const diagnostic = message => new Error(`${message}${clean(stderr) ? ` ${clean(stderr)}` : ""}`);
     const finish = (error, url) => {
       if (settled) return;
       settled = true;
       clearTimeout(timer);
       child.stdout.removeListener("data", onData);
-      child.removeListener("exit", onExit);
+      child.stderr?.removeListener("data", onStderr);
+      child.removeListener("close", onClose);
       child.removeListener("error", onError);
       if (error) {
         child.kill();
@@ -399,29 +414,36 @@ export function waitForReportServer(child, timeoutMs = 10000) {
       if (!buf.includes("\n")) return;
       try {
         const parsed = JSON.parse(buf.split("\n")[0]);
+        if (parsed.ok === false) {
+          const reason = clean(parsed.error?.message || parsed.message || parsed.error);
+          return finish(diagnostic(`Report server failed to start${reason ? `: ${reason}` : "."}`));
+        }
         const url = new URL(parsed.data?.url);
         if (
           parsed.ok !== true ||
           parsed.status !== "success" ||
           url.protocol !== "http:" ||
-          url.hostname !== "127.0.0.1"
+          url.hostname !== "127.0.0.1" || url.username || url.password
         )
           throw new Error("invalid receipt");
         finish(null, url.href);
       } catch {
-        finish(new Error("Report server returned an invalid startup receipt."));
+        finish(diagnostic("Report server returned an invalid startup receipt."));
       }
     };
-    const onExit = (code) =>
-      finish(new Error(`Report server exited (${code}) before it was ready.`));
+    const onStderr = chunk => { stderr = (stderr + chunk).slice(-8192); };
+    // close follows drained stdio; exit can arrive before the error text.
+    const onClose = (code, signal) =>
+      finish(diagnostic(`Report server exited (${signal || code}) before it was ready.`));
     const onError = (error) => finish(error);
     const timer = setTimeout(
       () =>
-        finish(new Error("Report server did not start before its deadline.")),
+        finish(diagnostic("Report server did not start before its deadline.")),
       timeoutMs,
     );
     child.stdout.on("data", onData);
-    child.once("exit", onExit);
+    child.stderr?.on("data", onStderr);
+    child.once("close", onClose);
     child.once("error", onError);
   });
 }
@@ -488,10 +510,13 @@ export async function reportServe(
       "--json",
       "--no-update-check",
     ],
-    { detached: true, stdio: ["ignore", "pipe", "ignore"] },
+    { detached: true, stdio: ["ignore", "pipe", "pipe"] },
   );
   const url = await waitForReportServer(child);
   child.stdout.destroy();
+  // Keep draining diagnostics without retaining them or keeping the CLI up.
+  child.stderr?.resume();
+  child.stderr?.unref?.();
   child.unref();
   const opened = options.adminOpen
     ? openImpl("open", ["-a", "Google Chrome", url])

package/lib/admin.js

@@ -3973,6 +3973,9 @@ export function parseAdminOperation(options) {
       },
     );
   }
+  if (namespace === "math-lab" && action === "queue") {
+    return readOperation("math-lab.queue", "/cli/admin/math-lab/queue");
+  }
   if (namespace === "builds" && action === "review") {
     const parsed = parseAdminCommentTarget({ target, explicitType: "build" });
     if (parsed.type !== "build") {
@@ -7121,6 +7124,13 @@ function printRewardBankReport(data) {
       );
     }
   }
+  if (data.numericAnswers) {
+    const n = data.numericAnswers;
+    console.log(`Numeric answers (${n.serverAnswerContract}): ${n.decimalQuestions} decimal questions / ${n.questions} total · ${n.decimalsCreatedInWindow} new decimals`);
+    console.log(`  Decimal follow-up: ${n.decimalClaims.served} served · ${n.decimalClaims.answered} answered · first-try ${pct(n.decimalClaims.firstTryRate)} · ${n.decimalClaims.coverage}`);
+  } else {
+    console.log("Numeric answer telemetry: unavailable on this server version.");
+  }
   console.log(`Learners: ${data.learners.total}`);
   for (const row of data.learners.byRuleStep) {
     console.log(
@@ -7330,6 +7340,14 @@ function printAiBucketRuleResult({ operation, data }) {
 
 function printAdminResult({ operation, result }) {
   const data = result?.data || {};
+  if (operation.name === "math-lab.queue") {
+    console.log(`Math Lab: published artifact ${data.publishedArtifactVersionId}, review ${data.reviewId}, day ${data.dayKey} UTC.`);
+    for (const grade of data.grades || []) console.log(grade.available
+      ? `${grade.ruleId}: ${grade.current || "exhausted"}${grade.clearedToday ? " (cleared today)" : ""}; ${grade.remaining} unearned of ${grade.sets}${grade.refillDue ? `; refill to ${data.refillTarget}` : ""}`
+      : `${grade.ruleId}: queue unavailable`);
+    if (!data.complete) console.log("Queue coverage is incomplete; unavailable grades are not empty queues.");
+    return;
+  }
   if (printChatSafetyResult({ operation, data })) return;
   const chatReportLines = formatChatReportResult({ operation, data });
   if (chatReportLines) {

package/lib/api.js

@@ -372,7 +372,7 @@ export async function saveProjectFiles({
       // Required when the workspace has no filesHash (old/stale checkout).
       ...(force ? { force: true } : {}),
     },
-    timeoutMs: options.timeoutMs,
+    timeoutMs: options.validationTimeoutMs ?? options.timeoutMs,
   });
 }
 

package/lib/commands.js

@@ -1316,7 +1316,7 @@ export async function check(options) {
   const result = await requestJson({
     url: `${options.apiUrl}/cli/build/${buildId}/launch-check`,
     authToken: auth.token,
-    timeoutMs: options.timeoutMs,
+    timeoutMs: options.validationTimeoutMs ?? options.timeoutMs,
   });
   printCheck(result);
   if (!result.ok) process.exitCode = 1;
@@ -1373,7 +1373,7 @@ export async function launch(options) {
   const checkResult = await requestJson({
     url: `${options.apiUrl}/cli/build/${buildId}/launch-check`,
     authToken: auth.token,
-    timeoutMs: options.timeoutMs,
+    timeoutMs: options.validationTimeoutMs ?? options.timeoutMs,
   });
   printCheck(checkResult);
   const launchOk =
@@ -2479,6 +2479,7 @@ export function parseArgs(args) {
     "foreground",
     "open",
     "dryRun",
+    "preflight",
     "confirmEmailRule",
     "includePrefix",
     "allowSharedNetwork",
@@ -2802,6 +2803,8 @@ export function parseArgs(args) {
     adminEditionId: raw.editionId ? String(raw.editionId) : "",
     adminLeaseToken: raw.leaseToken ? String(raw.leaseToken) : "",
     adminFile: raw.file ? String(raw.file) : "",
+    rewardPreflight: Boolean(raw.preflight),
+    rewardApprovalFile: raw.approvalFile ? String(raw.approvalFile) : "",
     // admin craft revise --item <id|name> [--why] [--emoji] [--category]
     // (kept raw: a flag given without a text value is refused in
     // admin-craft.js rather than sent as the string "true")
@@ -2936,6 +2939,13 @@ export function parseArgs(args) {
         DEFAULT_TIMEOUT_MS,
       1000,
     ),
+    // Large saved projects can take longer than the ordinary 20s request
+    // deadline. The server bounds compiler work at 120s; leave transport room.
+    // An explicit --timeout-ms / environment setting still wins.
+    validationTimeoutMs: Math.max(
+      Number(raw.timeoutMs || process.env.TWINKLE_TIMEOUT_MS) || 150000,
+      1000,
+    ),
     help: !!raw.help || command === "help",
   };
 }
@@ -3255,6 +3265,7 @@ export function printHelp() {
   lumine admin chat-reports export <report-id> | --hold <hold-id> --out <new-dir> [--json]   (evidence package + SHA-256 manifest)
   lumine admin chat-reports suspend --user <id> --note <why> [--json]   (full ban: signs them out)
   lumine admin reward-review show <review-id> [--dir <path>] [--json]
+  lumine admin math-lab queue [--json]   (published sets remaining per grade, all-time claims, refill flags)
   lumine admin reward-review approve <review-id> [--config <rules.json>] [--reason <text>] [--json]   (approval publishes the approved version)
   lumine admin reward-review propose <review-id> --dir <edited-snapshot> --config <rules.json> [--reason <text>] [--title <new app name>] [--thumbnail <image|workspace>] [--json]
   lumine admin reward-review reject|revoke <review-id> --reason <text> [--json]

package/lib/rewards.js

@@ -18,6 +18,15 @@ import { resolveRequiredBuildIdOrSelected } from "./commands.js";
 
 const REWARDS_FILE = "rewards.json";
 
+export function reviewApprovalFromReceipt(receipt, buildId) {
+  if (!receipt || receipt.ready !== true || receipt.buildId !== buildId ||
+      !Number.isSafeInteger(receipt.sourceVersionId) || receipt.sourceVersionId <= 0 ||
+      !["sourceHash", "sheetHash", "configHash"].every(key => /^[a-f0-9]{64}$/.test(receipt[key] || ""))) {
+    throw new Error("Use the complete, ready preflight JSON for this Build as --approval-file.");
+  }
+  return Object.fromEntries(["buildId", "sourceVersionId", "sourceHash", "sheetHash", "configHash"].map(key => [key, receipt[key]]));
+}
+
 async function readWorkspaceRewardsJson(options) {
   const localProject = await findLocalProjectMetadata(
     path.resolve(options.dir || process.cwd()),
@@ -208,13 +217,39 @@ export async function rewardsCommand(options) {
     return;
   }
   if (action === "review") {
+    if (options.rewardPreflight && options.rewardApprovalFile)
+      throw new Error("Choose --preflight or --approval-file, not both.");
+    let receipt;
+    if (options.rewardApprovalFile) {
+      receipt = JSON.parse(await fs.readFile(path.resolve(options.rewardApprovalFile), "utf8"));
+    } else {
+      receipt = await requestJson({
+        url: `${options.apiUrl}/build/${buildId}/rewards/review-preflight`,
+        authToken: auth.token, timeoutMs: options.timeoutMs,
+      });
+    }
+    if (options.rewardPreflight) {
+      if (options.json) console.log(JSON.stringify(receipt, null, 2));
+      else {
+        console.log(`Build ${buildId}, saved v${receipt.savedVersion} (artifact ${receipt.sourceVersionId}).`);
+        console.log(receipt.publicationBehavior);
+        console.log(`Source: ${receipt.sourceHash}\nQuestion sheet: ${receipt.sheetHash}\nReward configuration: ${receipt.configHash}`);
+        for (const error of receipt.errors || []) console.log(`  - ${error}`);
+        console.log("Save this preflight with --json, review the candidate, then pass --approval-file <receipt.json> after approval.");
+      }
+      if (!receipt.ready) process.exitCode = 1;
+      return;
+    }
+    const expectedApproval = reviewApprovalFromReceipt(receipt, buildId);
+    if (receipt.willPublishImmediately && !options.rewardApprovalFile)
+      throw new Error("This owner's reward review publishes immediately. Run `lumine rewards review --preflight --json`, approve that exact candidate, then use `--approval-file <receipt.json>`.");
     await assertAuthScope({ options, auth, scope: "build:write" });
     const result = await requestJson({
       url: `${options.apiUrl}/build/${buildId}/rewards/reviews`,
       method: "POST",
       authToken: auth.token,
       timeoutMs: options.timeoutMs,
-      body: {},
+      body: { expectedApproval },
     });
     if (options.json) {
       console.log(JSON.stringify(result, null, 2));
@@ -222,10 +257,12 @@ export async function rewardsCommand(options) {
     }
     const reviewId = result?.policy?.latestReviewId;
     console.log(
-      `Sent Build ${buildId} for reward review${reviewId ? ` (request #${reviewId})` : ""}. State: ${result?.state || "unknown"}.`,
+      `Reward review for Build ${buildId}${reviewId ? ` (request #${reviewId})` : ""}. Server state: ${result?.state || "unknown"}.`,
     );
     console.log(
-      "The saved version and the question sheet on file are frozen for the reviewer. Saving again closes this request; send it again after the save.",
+      receipt.willPublishImmediately
+        ? "The server attempted automatic approval and publication. Check the returned state and published artifact before reporting it live."
+        : "The approved candidate is frozen for the reviewer. Saving again closes this request.",
     );
     return;
   }
@@ -239,6 +276,8 @@ function printRewardsHelp() {
   lumine rewards sheet <file.json>  Upload the private question sheet ({ rules: { <ruleId>: { questions?, sets? } } })
   lumine rewards sheet --show       Summarize the sheet on file (never prints answer keys)
   lumine rewards review             Send the saved version (with the sheet on file) for XP/Coin review, like "Send for review" on the website
+  lumine rewards review --preflight --json  Read exact version/source/sheet/config hashes and publication behavior; no mutation
+  lumine rewards review --approval-file <receipt.json>  Request only the exact approved preflight candidate; owner auto-approval publishes immediately
 
 rewards.json (project root) declares the economy the reviewer approves:
   { "userDailyXP", "userDailyCoins", "userDailyClaims"?,

package/package.json

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

package/sdk/BUILD_SDK_INDEX.md

@@ -1029,9 +1029,9 @@ const result = await Twinkle.characters.chat({ character: 'zero', thinkingMode:
   - Example: const { level } = await Twinkle.minecraft.getPlayArea({ id: 'twinkle-keep' });
 - async getPlayAreaChunks({ id, chunks: [[cx, cz], ...] }) | scopes: content:read
   - Returns: { scenes: [{ cx, cz, scene: { origin: [x,y,z], size: [w,h,d], palette, blocks, light, biomes, count, ... } | null }] }
-  - Up to 9 chunk columns of a play area in the /snap scene format (packed visible blocks with per-face light), cropped to the area's box. Stream the ones around the player.
+  - Up to 24 chunk columns of a play area in the /snap scene format (packed visible blocks with per-face light), cropped to the area's box. Stream the ones around the player.
   - Same scene format as getSnap; only blocks with a visible face inside the area are included. scene is null for a chunk that is not part of the area.
-  - At most 9 chunks per call; reads share the 180-per-minute build read limit, so cache chunks and load the nearest first.
+  - At most 24 chunks per call; reads share the 180-per-minute build read limit, so cache chunks and load the nearest first.
   - Example: const { scenes } = await Twinkle.minecraft.getPlayAreaChunks({ id: level.id, chunks: [[64, 29], [65, 29]] });
 - async createPlayArea({ name, world, box, spawn, id }) | scopes: content:write
   - Returns: { level }

package/sdk/LUMINE_ADMIN.md

@@ -622,6 +622,10 @@ additions are not the live inventory. At two or fewer remaining, prepare a
 refill to at least ten, with complete interactive guides, and track it until
 approved publication. Report one or zero remaining prominently. Details are
 in the linked guide's **Daily queue monitoring and refill** section.
+Read this inventory with `lumine admin math-lab queue --json`. Its receipt
+binds the published artifact and live reward review, includes all twelve
+grades, and reports incomplete coverage explicitly. Today’s cleared set stays
+current until UTC midnight, but no longer counts as unearned inventory.
 This is not part of Featured-only or newspaper-only work and is not a new
 scheduler, delegated API scope, or automatic extension of admin permissions.
 Use the expressly authorized owner Build workflow for Math Lab; retain the
@@ -878,6 +882,8 @@ type StandalonePost = {
   updatedAt: null;
   title: string | null;
   question: string | null;
+  grade?: "Pass" | "Fail" | "Masterpiece" | null; // Daily Reflection only
+  masterpieceType?: "heart" | "mind" | "heart_and_mind" | null;
   content: string | null;
   explanation: string | null;
   imagePath: string | null;
@@ -1152,7 +1158,7 @@ lumine admin report serve --file <dir>/daily-management-report.md [--port <n>] [
 ```
 
 These compose the documented commands in this contract, running them as child processes, so every scope check, audit and pagination rule applies unchanged.
-- **`gather`** saves each read-only report into `<dir>`. It follows `bot-output` to exhaustion and renders `bot-chats.txt`, then lists any failed step in `gather.json`. It also creates `review-state.json`: every source is fetched, not read. Children bypass update checks, require matching fresh stdout/file receipts, and retry an unconfirmed opted-in read at most once. Mutations never auto-retry. It needs the active run for run-scoped reads.
+- **`gather`** saves each read-only report into `<dir>`, including the canonical published Math Lab queue in `math-lab-queue.json`. It follows `bot-output` to exhaustion and renders `bot-chats.txt`, then lists any failed step in `gather.json`. Total/per-step `durationMs`, attempts and recovered reads make recurring slow or failing collection steps visible during the daily review. It also creates `review-state.json`: every source is fetched, not read. Children bypass update checks, require matching fresh stdout/file receipts, and retry an unconfirmed opted-in read at most once. Mutations never auto-retry. It needs the active run for run-scoped reads.
 - **`progress`** reads local review state and explicit operator acknowledgments, writes private `progress.json`, and keeps reading, canonical effort mutations, the run lease, and browser checks separate. Add all required duties for the actual run scope and its carryovers; collection alone is not a full review. A completed run lease cannot complete a pending duty. Reading acknowledgments bind to the current file bytes and are operator attestations, not proof of comprehension.
 - **`featured candidates`** returns Subjects posted after the Bangkok-midnight cutoff that are off the board and provably never Featured. Each one comes with its human/bot comment counts, explicit comment truncation/completeness, and whether Mikey has viewed it. Counts from truncated context are partial. An unavailable Subject context fails the collection. Eligibility only: ranking stays editorial.
 - **`report serve`** detaches a loopback server that answers only `/`, `marked.min.js` and the report Markdown. `--open` opens Chrome and reports whether the OS accepted the request. Render, navigation and original-source verification remain pending until actually checked. Startup failures stop only the child this command started.
@@ -1479,9 +1485,8 @@ Rule fields (all server-enforced, none inferred from app code):
 - Top-level `userDailyClaims`: receipts one learner may earn per site day
   across all rules. `1` is "one bounty a day".
 
-Math Lab's economy (Mikey, 2026-09-12): twelve level rules, one per grade per
-day, elementary 50,000 XP + 1,000 Coins, middle 70,000 + 5,000, high
-100,000 + 10,000; `retry` 50 % XP / 0 % Coins; `maxAttempts` null;
+Math Lab's economy (Mikey, equal pay 2026-10-04): twelve level rules, one per grade per
+day, all paying 70,000 XP + 5,000 Coins; `retry` 50 % XP / 0 % Coins; `maxAttempts` null;
 `userDailyClaims` 1; until-earned sets authored from the Korean curriculum.
 Arcade Typing (Mikey, 2026-09-12): XP for clearing campaign stages, up to
 10,000 XP per learner per day, no Coins. Platform ceilings: 100,000 XP /
@@ -1497,6 +1502,18 @@ also closes itself on that save). Rejection and revocation require a
 needs a new request. Never approve without reading the code; never approve a
 request whose `isLatest` is false.
 
+Mikey-owned apps automatically attempt approval and publication when the owner
+requests reward review. Before that write, run
+`lumine rewards review --preflight --json` and retain its complete receipt.
+It identifies the saved version, artifact ID, source hash, private sheet hash
+and effective reward configuration hash, and states the publication behavior.
+After Mikey approves that exact candidate, use
+`lumine rewards review --approval-file <receipt.json>`. The API checks those
+values under the build lock before freezing content; a change returns
+`build_reward_approval_stale`. There is no silent fallback to an unbound request.
+Saving a new preflight is read-only and is not approval. These commands require
+the matching API and CLI release.
+
 `propose <id> --dir <edited> --config rules.json [--reason]` sends the edited
 directory (text files only; dotfiles and tool folders skipped) as the
 reviewer's proposal: the review moves to `changes_offered`, the creator's card
@@ -2480,6 +2497,15 @@ Inspection never silently bypasses secret semantics. Until the selected bot is
 the author or has canonically responded/revealed, secret values and comments
 remain unavailable.
 
+Daily Reflection post reads and recommendation candidates include the stored
+`grade` and `masterpieceType` (nullable), independently of XP and recommendations.
+An absent grade is unknown. Verify `grade === "Masterpiece"` before placing one
+of Mikey's reflections anywhere on the newspaper front page; lower or missing
+grades can be considered for inside pages. The CLI does not infer a grade.
+Masterpiece is only an eligibility condition for his reflections: it does not
+award front-page placement, the lead, or editorial priority. Read the actual
+content and compare its significance to members with the day's other stories.
+
 ## Subject and Featured mutations
 
 ```bash
@@ -2996,6 +3022,12 @@ entertainment, likely comments and opportunities to join in are not the only
 measures of importance. Explain the values being communicated; do not reduce
 them to founder biography or an administrative announcement.
 
+**Editorial judgment (Mikey, 2026-10-15):** a Masterpiece grade never automatically
+earns a front-page slot or the lead. Use the project's canonical `CORE_VALUES.md`
+to assess the actual story's relevance to the community and its culture, alongside
+the other eligible stories. Give the substantive reason for the placement;
+neither the grade nor Mikey's authorship supplies that reason.
+
 Use clear, lively language that respects readers' intelligence. Give enough
 context for someone who missed the original post, and make the interesting
 part clear in the headline and opening. Avoid talking down to readers, forced