@stage5/lumine 0.3.34 → 0.3.35

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") {
@@ -7330,6 +7333,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/commands.js

@@ -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")
@@ -3255,6 +3258,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.35",
   "description": "Command line tools for launching Lumine builds on Twinkle.",
   "type": "module",
   "bin": {

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,12 @@ 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.
+
 ## Subject and Featured mutations
 
 ```bash