@stage5/lumine 0.3.60 → 0.3.62

package/lib/admin.js

@@ -6252,6 +6252,10 @@ export function printRewardReviewResult({ operation, data }) {
     console.log(
       `Budgets: per user/day ${config.userDailyXP} XP/${config.userDailyCoins} Coins${config.userDailyClaims ? ` · ${config.userDailyClaims} claim(s)` : ""}`,
     );
+    if (config.missedRematch)
+      console.log(
+        `Missed-puzzle rematches: a variant ${config.missedRematch.afterDays} day(s) after a miss · ${config.missedRematch.perDay} a day · full first-try amounts, outside the daily claim count`,
+      );
     for (const rule of config.rules)
       console.log(`  ${formatRewardRuleLine(rule)}`);
   }
@@ -7397,8 +7401,64 @@ function printAiBucketRuleResult({ operation, data }) {
   return false;
 }
 
+// `admin reward-diagnostics`: one app's (or member's) reward audit trail.
+// The generic audit-event printer read runId/action/result, which these
+// events don't have, so every line printed "undefined".
+export function formatRewardDiagnostics(data, filters = {}) {
+  if (data.coverage === "unavailable")
+    return [`Reward diagnostics unavailable${data.reason ? `: ${data.reason}` : "."}`];
+  const events = Array.isArray(data.events) ? data.events : [];
+  const at = (seconds) =>
+    Number.isFinite(Number(seconds)) && Number(seconds) > 0
+      ? new Date(Number(seconds) * 1000).toISOString().slice(5, 16).replace("T", " ")
+      : "?";
+  const lines = [
+    `Reward diagnostics: ${events.length} event(s), ${at(data.since)} → ${at(data.until)} UTC${data.coverage ? ` (${data.coverage})` : ""}`,
+  ];
+  const tally = new Map();
+  for (const event of events) {
+    const key = event.operation || "?";
+    const outcomes = tally.get(key) || new Map();
+    const outcome = event.outcome || "?";
+    outcomes.set(outcome, (outcomes.get(outcome) || 0) + 1);
+    tally.set(key, outcomes);
+  }
+  for (const [operation, outcomes] of tally)
+    lines.push(`  ${operation}: ${[...outcomes].map(([outcome, n]) => `${n} ${outcome}`).join(", ")}`);
+  for (const event of events) {
+    const details = event.details || {};
+    const extras = [
+      details.httpStatus ? String(details.httpStatus) : "",
+      details.errorCode ? String(details.errorCode) : "",
+      Number.isFinite(Number(event.durationMs)) ? `${event.durationMs} ms` : "",
+    ].filter(Boolean);
+    lines.push(
+      `#${event.id} ${at(event.createdAt)} ${event.source || "?"} build ${event.buildId ?? "?"} user ${event.userId ?? "?"} ${event.operation || "?"} → ${event.outcome || "?"}${extras.length ? ` (${extras.join(", ")})` : ""}`,
+    );
+  }
+  if (Array.isArray(data.challenges) || Array.isArray(data.receipts))
+    lines.push(`Server records: ${data.challenges?.length ?? 0} challenge(s), ${data.receipts?.length ?? 0} receipt(s)${data.canonicalRecordsTruncated ? " (truncated)" : ""}.`);
+  for (const limitation of data.limitations || []) lines.push(`Note: ${typeof limitation === "string" ? limitation : JSON.stringify(limitation)}`);
+  if (data.nextCursor) {
+    // the next page needs the same scope and window
+    const again = [
+      filters.buildId ? `--build ${filters.buildId}` : "",
+      filters.userId ? `--user ${filters.userId}` : "",
+      filters.days ? `--days ${filters.days}` : "",
+    ].filter(Boolean).join(" ");
+    lines.push(`More: lumine admin reward-diagnostics ${again ? `${again} ` : ""}--cursor ${data.nextCursor}`);
+  }
+  return lines;
+}
+
 function printAdminResult({ operation, result }) {
   const data = result?.data || {};
+  if (operation.name === "reward-diagnostics.read") {
+    const query = new URLSearchParams(String(operation.path || "").split("?")[1] || "");
+    const filters = { buildId: query.get("buildId"), userId: query.get("userId"), days: query.get("days") };
+    for (const line of formatRewardDiagnostics(data, filters)) console.log(line);
+    return;
+  }
   if (operation.name === "spending.report" && data.spending) {
     console.log(formatSpending(data.spending));
     return;
@@ -7411,6 +7471,11 @@ function printAdminResult({ operation, result }) {
         : `${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.");
+    // Rematch variants to write in the next refill: missed puzzles with no unmet variant left for someone.
+    if (data.variantNeeds?.length) {
+      console.log(`Rematch variants needed (write as new sets with variantOf):`);
+      for (const need of data.variantNeeds) console.log(`  ${need.ruleId} ${need.setKey}: ${need.waiting} learner(s) waiting · ${need.variants} variant(s) so far`);
+    }
     return;
   }
   if (printChatSafetyResult({ operation, data })) return;

package/lib/build-review.js

@@ -938,19 +938,12 @@ async function runChromeReview({
       child.exitCode !== null || child.signalCode !== null;
     const closeRequestedAt = Date.now();
     stderrAfterClose = "";
-    await cdp.send("Browser.close").catch(() => {});
-    let forcedTermination = false;
-    const closeResult = await Promise.race([
-      closed,
-      delay(5_000).then(() => {
-        forcedTermination = true;
-        return stopChrome(child, closed);
-      }),
-    ]);
+    // Observation is complete; shutdown has its own bounded deadline.
+    clearTimeout(timer);
+    const closeResult = await closeReviewBrowser({ child, closed, cdp });
     return {
       ...closeResult,
       closeRequested: true,
-      forcedTermination,
       evidenceCompleteBeforeClose,
       exitedBeforeClose,
       closeDurationMs: Date.now() - closeRequestedAt,
@@ -972,12 +965,40 @@ async function runChromeReview({
   }
 }
 
+export async function closeReviewBrowser({ child, closed, cdp, graceMs = 12_000 }) {
+  // The macOS network-service watchdog can take ~10 s to print its shutdown
+  // diagnosis and exit 2. The former 5+3 s kill erased that evidence and made
+  // a completed app review look like an unexplained browser crash.
+  let closeAcknowledged = false, closeCommandError = null, forcedTermination = false;
+  const command = cdp.send("Browser.close").then(
+    () => { closeAcknowledged = true; },
+    error => { closeCommandError = String(error?.message || error).slice(0, 240); },
+  );
+  let result = await waitForChromeExit(closed, graceMs);
+  if (!result) {
+    forcedTermination = true;
+    result = await stopChrome(child, closed);
+  }
+  await command; // The CDP command has its existing timeout/channel-close bound.
+  return { ...result, forcedTermination, closeAcknowledged, closeCommandError };
+}
+
+async function waitForChromeExit(closed, milliseconds) {
+  let timer;
+  try {
+    return await Promise.race([
+      closed,
+      new Promise(resolve => { timer = setTimeout(() => resolve(null), milliseconds); }),
+    ]);
+  } finally { clearTimeout(timer); }
+}
+
 // SIGTERM, then SIGKILL if Chrome is still there after 3 s: a browser wedged
 // in teardown (the case this review must tolerate) can ignore SIGTERM, and
 // the review must never hang or leave Chrome running.
 async function stopChrome(child, closed) {
   child.kill("SIGTERM");
-  const ended = await Promise.race([closed, delay(3_000).then(() => null)]);
+  const ended = await waitForChromeExit(closed, 3_000);
   if (ended) return ended;
   child.kill("SIGKILL");
   return closed;
@@ -1151,6 +1172,8 @@ export async function runManagedBuildReview({ options, authToken, buildId }) {
       exitCode: browser.code,
       signal: browser.signal,
       closeRequested: browser.closeRequested === true,
+      closeAcknowledged: browser.closeAcknowledged === true,
+      closeCommandError: browser.closeCommandError || null,
       forcedTermination: browser.forcedTermination === true,
       exitedCleanly: browser.code === 0 && !browser.signal,
       stdioDrainTimedOut: browser.stdioDrainTimedOut === true,

package/lib/commands.js

@@ -3323,7 +3323,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 math-lab queue [--json]   (published sets remaining per grade, all-time claims, refill flags, rematch variants needed)
   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/package.json

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

package/sdk/BUILD_SDK_INDEX.md

@@ -1,8 +1,8 @@
 # Build SDK Index
 
-Version: 1.69.0
+Version: 1.71.0
 Updated: 2026-10-24
-Generated: 2026-10-24T02:37:05.998Z
+Generated: 2026-10-24T05:59:44.939Z
 
 ## Platform rules
 Each rule below is a way an app breaks once it runs inside Twinkle's sandboxed frame, even when the code itself is correct. They outrank every other guideline: follow them in every change, including small ones, and fix any break of them you see in code you touch.
@@ -1588,7 +1588,7 @@ world.updatePresence({ x, y, z, facing });
 
 ### Twinkle.rewards
 - await Twinkle.rewards.getStatus() | scopes: rewards:claim
-  - Returns: { mode: "live", dayKey, userDailyClaims, claimsToday, budgets: { userDailyXP, userDailyCoins }, rules: [{ id, title, howTo?, category?, series?, xp, coins, verifier: "numeric-quiz" | "completion", minSeconds?, progression?, retryReward: { xp, coins }, maxAttempts, available, setKey, questionCount }], challenges: [{ challengeId, ruleId, attempts, attemptsRemaining, state: "open" | "finished" | "earned", setKey, questions: [{ prompt, hint?, guide? }] }], history: [{ ruleId, xp, coins, attempt, createdAt }], balances: { xp, coins } } | { mode: "preview", dayKey?, rules, challenges: [], history: [], balances?, problems?: string[], message }
+  - Returns: { mode: "live", dayKey, userDailyClaims, claimsToday, craftDiscovery?: { pendingByRule: { [ruleId]: number } }, missedRematch?: { afterDays, perDay, usedToday, ready: [{ ruleId, setKey, variantOf, missed }], upcoming, nextReadyDay }, budgets: { userDailyXP, userDailyCoins }, rules: [{ id, title, howTo?, category?, series?, xp, coins, verifier: "numeric-quiz" | "completion", minSeconds?, progression?, retryReward: { xp, coins }, maxAttempts, available, setKey, questionCount }], challenges: [{ challengeId, ruleId, attempts, attemptsRemaining, state: "open" | "finished" | "earned", setKey, questions: [{ prompt, hint?, guide? }] }], history: [{ ruleId, xp, coins, attempt, createdAt }], balances: { xp, coins } } | { mode: "preview", dayKey?, rules, challenges: [], history: [], balances?, problems?: string[], message }
   - Read canonical earning rules (without answer keys), today’s started challenges, today’s receipts and balances. Drafts return preview mode: for the app's owner the rules come from the draft's own rewards.json and question sheet (problems lists what is still wrong with them); anyone else sees no rules. Unapproved or revoked published releases return an error.
   - rules[].available is false on a site day (UTC) the reviewer scheduled no questions for; show the rule as not available instead of starting it. xp/coins are the first-try amounts; retryReward is what a correct answer pays after a wrong one (equal to xp/coins unless the reviewer set a retry share). maxAttempts null means unlimited wrong answers until the site's daily reset (UTC midnight, 9:00 AM in Korea). retry.paidAttempts, when set, is the last attempt number a correct answer is still paid on: a later correct answer is recorded as solved (receipt xp 0, coins 0) and pays nothing — tell the learner before they pass it.
   - challenges lists challenges this viewer already started today with their questions, so an app can resume after a reload without calling start. A question's guide (reviewer-approved JSON teaching content: explanation, interactive-model configuration) is present only once the viewer has answered at least once, right or wrong; render it as the after-attempt lesson. claimsToday against userDailyClaims (null = uncapped) tells whether another bounty can still pay today.
@@ -1598,6 +1598,8 @@ world.updatePresence({ x, y, z, facing });
   - category and series are optional rewards.json labels for a long list. category is a short section header (up to 40 characters, e.g. "Bring friends"); series is a short lowercase key (e.g. "new-friend") tying repeat rules like vigil-friend-1/2/3 together, and rules in one series must share category, verifier, XP and Coins. The Earn page groups rules by category and shows each series as one row ("up to 3 a day", "1 of 3 today"); group the app's own rewards list the same way.
   - nonogram-picture-v1 uses Twinkle’s private, editorially reviewed picture bank. Set pictureSize to 5, 10 or 15 on each completion rule. Do not bundle daily solutions or a fixed answer catalog in app files. The collection is maintained through lumine admin nonogram; the reward amounts and daily limits still come from the approved rules.
   - Collection progression keeps every approved keyed set available independently of other players' solves. collectionSets lists { setKey, number }; challenges carry collection, practice, completed and completion. Live status includes viewerId for a per-viewer durable outbox. Attempts and completion persist across days/releases; the daily reward allowance does not reset a puzzle's paid tries. Existing receipts (including rematches), Vault solves/practice and studied guides count. Completed puzzles can be revisited; do not treat any receipt for the grade as completing all its puzzles. Collection rules support up to 500 permanent sets per rule; legacy queued/dated rules keep their 62-set limit.
+  - missedRematch appears when rewards.json declares missedRematch ({ afterDays, perDay }; it requires userDailyClaims) and the app has collection rules. A collection set may declare variantOf: another set's key, meaning the same puzzle with new numbers (an ordinary puzzle for everyone). A learner who missed any puzzle of a family (an original plus its variants) and has not solved one of its puzzles on the first try gets the family's first unmet puzzle as a rematch afterDays site days after their last answer in the family. ready lists today's rematches (variantOf is the family's original, missed the puzzle this learner got wrong most recently; once perDay are used it only keeps one already opened today): open setKey with start({ ruleId, setKey }) at any time (before or after today's bounties) and the challenge comes back with rematch: { variantOf, answered }: one answer, the rule's full first-try amounts, a receipt (rematch: true) that does not count toward userDailyClaims but does count toward the XP/Coin budgets. usedToday against perDay says how many rematches were opened today; opening one uses it. upcoming and nextReadyDay describe rematches not ready yet.
+  - For craft-discovery-v1 rules, live status includes craftDiscovery.pendingByRule: counts of this viewer’s unpaid discoveries eligible for each configured rule. Use these advisory counts to skip empty tier probes; they are not rewards or a promise that a later claim will succeed. claim still checks and consumes canonical proof transactionally. Refresh status after claims. Older servers and preview mode may omit this field.
 - await Twinkle.rewards.getReceipt({ challengeId }) | scopes: rewards:claim
   - Returns: { mode: "live", status: "awarded" | "completed" | "pending" | "expired" | "not_found", receipt: { id, challengeId, ruleId, reviewId, artifactVersionId, dayKey, xp, coins, attempt, createdAt } | null, balances: { xp, coins } } | { mode: "preview", status: "not_found", receipt: null, message }
   - Read an existing receipt for this app and signed-in viewer by server-issued challengeId, including previous UTC days and previous approved versions. Requires the current approved published release and runtime grant; a stale frame must reload first. Never awards, retries a claim, returns answer keys, or restores removed rewards permission.
@@ -1614,6 +1616,7 @@ world.updatePresence({ x, y, z, facing });
   - For nonogram-picture-v1, start returns completion { profile, completed: false, readyInSeconds, puzzle: { size, rows: number[][], cols: number[][] } }. Render those row and column clues; there is no progress call. Live readyInSeconds is the remaining approved minimum wait, so reopening a puzzle does not restart its clock. The private picture is durably bound to this exact viewer, app, release, rule, challenge and expiry. Reopening returns the same clues even after a refill. New challenges use unseen pictures; build_reward_picture_collection_complete means this size needs a refill. Offer practice/community puzzles while waiting.
   - For collection rules, setKey is required and must be one of the approved permanent keys. Start returns that exact question and persistent attempts. practice:true means no XP/Coins or official rating (daily allowance reached, earlier practice, or viewed archive guide); display that before answering. Merely opening a practice question does not consume its future eligibility, but answering it does. completed:true returns its lesson and completion, without a new challenge or payout. A current eligible daily-rematch puzzle must be opened as the rematch. A challenge still expires at the usual day/release boundary; reopen the same set to resume its saved attempts.
   - Live completion starts return readyInSeconds, the remaining server-enforced wait for that challenge (including a resumed challenge). Anchor it at response arrival and queue one claim after that time; do not poll claim while too early. Retain the finished proof in a per-viewer outbox and reconcile getReceipt after a lost reply or reload. It is timing metadata, not proof of completion or permission to pay. Older servers may omit it; use the rule minSeconds conservatively. Preview timing and receipts remain separate.
+  - A collection puzzle listed in getStatus().missedRematch.ready starts as a paid rematch, before or after today's bounties: rematch: { variantOf, answered }, attemptsRemaining 1, reward = the rule's full xp/coins, retryReward 0, and its receipt does not count toward userDailyClaims. A wrong answer ends the rematch (the puzzle stays in the collection as an ordinary missed puzzle); a right one pays and completes it.
 - await Twinkle.rewards.progress({ challengeId, completionToken?, frames?, record?, requestId? }) | scopes: rewards:claim
   - Returns: { mode: "live" | "preview", completion: { profile, token?, completed, failed?, decision?, message?, maxFrames? }, aiUsagePolicy? }
   - Verify a bounded batch of inputs for an approved server-simulated climb.

package/sdk/LUMINE_ADMIN.md

@@ -2826,8 +2826,9 @@ never previously been Featured from canonical evidence.
 
 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
+Subject3529, “What is special about Twinkle?”, had an October13 keep instruction,
+but Mikey removed it on October19 at06:28:27UTC (canonical event2504).
+Do not restore it from that superseded keep note. 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: