@stage5/lumine 0.3.33 → 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/builderStance.generated.js

@@ -0,0 +1,3 @@
+// GENERATED from CORE_VALUES.md ("For building agents") by
+// scripts/generate-builder-stance.mjs. Do not edit by hand.
+export const LUMINE_BUILDER_STANCE = "You are a tool for the creator. Your job is to understand what they want to make, or seem to want to make, and help them make the best version of it.\n\n- What to make is the creator's call. Never steer them toward or away from a kind of project, genre, mechanic or style because of your own taste.\n- Be opinionated about how to make their idea great. Like a trusted senior collaborator, point out the loose ends: gaps between what they asked for and what exists, unfinished parts, edge cases, and things that will break or feel off. Then say clearly what you would do next if you were them, and why. Let them decide.\n- When they ask for ideas, offer a few options that fit what they're making, say which one you'd pick for their goal and why, and don't push.\n- When their direction is vague or feeling-based (\"make it more epic\", \"it feels empty\", \"I don't like this\"), work out what they mean and make the result visibly respond to it. Ask one short question only when you genuinely can't tell.\n- Make it well: aim for the best, most complete and polished version of their idea, within what they asked.\n- Don't coach, lecture or comment on the creator themselves; let the work speak.";

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/constants.js

@@ -1,5 +1,6 @@
 import os from "os";
 import path from "path";
+import { LUMINE_BUILDER_STANCE } from "./builderStance.generated.js";
 
 export const DEFAULT_API_URL = "https://api.twinkle.network";
 export const DEFAULT_SITE_URL = "https://www.twin-kle.com";
@@ -173,6 +174,10 @@ export const LUMINE_AGENT_INSTRUCTIONS = `${LUMINE_AGENT_INSTRUCTIONS_MARKER}
 This directory contains Twinkle Build project files pulled by Lumine CLI. Use
 Lumine CLI as the source of truth for saving this workspace back to Twinkle.
 
+## Building For The Creator
+
+${LUMINE_BUILDER_STANCE}
+
 ## Source Of Truth
 
 - Read .twinkle/lumine-project.json before changing files.

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.33",
+  "version": "0.3.35",
   "description": "Command line tools for launching Lumine builds on Twinkle.",
   "type": "module",
   "bin": {
@@ -13,7 +13,8 @@
     "README.md"
   ],
   "scripts": {
-    "test": "node --test"
+    "test": "node --test",
+    "prepublishOnly": "node --test test/builderStanceSync.test.js"
   },
   "publishConfig": {
     "access": "public"

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
@@ -2673,6 +2696,12 @@ never previously been Featured from canonical evidence.
 
 ### Exact approved refresh and resumable comment encouragement
 
+Keep current manual pins from the past two days (Mikey, October 13, 2026).
+Verify canonical pin history and exclude those subjects from removal proposals.
+Subject 3529, “What is special about Twinkle?”, also has an explicit keep
+instruction. An absent pin is still never restored. This supersedes the older
+instruction to offer yesterday's manual pins for rotation.
+
 For the daily old-to-new proposal, prepare a canonical plan without changing pins:
 
 ```bash
@@ -2982,6 +3011,14 @@ to join in. Games, art, puzzles, friendships, shared reflections, and community
 discussions can all supply good stories; read the actual source to find the
 substance.
 
+**Community significance (Mikey, 2026-10-13):** substantive messages about
+Twinkle's shared values, purpose and direction deserve explicit front-page
+priority, including the lead when they are the day's most consequential story.
+Judge what the message means for members, regardless of who wrote it. Immediate
+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.
+
 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
@@ -3101,7 +3138,9 @@ make the call by reading:
 
 - **Choose the lead for readers aged 10–15.** Lead with the eligible front
   event whose substance is most likely to catch their interest and reward
-  reading. A thoughtful conversation, a funny or relatable reflection, a
+  reading, weighing community significance as well as immediate appeal.
+  A substantive statement of shared values or purpose, a thoughtful
+  conversation, a funny or relatable reflection, a
   striking creation, or an inviting community challenge can all qualify.
   Read the source and any supplied replies to understand the appeal; priority,
   recency, and the mere presence of an argument do not decide the lead.