@stage5/lumine 0.3.78 → 0.3.79

package/lib/admin-daily.js

@@ -190,6 +190,45 @@ export async function dailyRunGather(options, { run = runAdmin, now, clock } = {
     Object.assign(steps.at(-1), { ok: false, error });
   };
   const evidenceNames = /^(ai-costs|media-costs|reward-activity|reward-diagnostics|jev-review|jev-images|owner-wake|bot-output)/;
+  // A run started from a shell that then exits (`gather ... &`) used to be
+  // hung up and die before gather.json existed (11-02). Keep collecting like
+  // nohup, and keep gather.json current after every step, marked incomplete
+  // until the final summary replaces it, so an interrupted collection always
+  // leaves a readable receipt and `--resume` is only needed to finish it.
+  const ignoreHangup = () => {};
+  process.on("SIGHUP", ignoreHangup);
+  const writeProgress = () => {
+    try {
+      fs.writeFileSync(
+        path.join(dir, "gather.json"),
+        JSON.stringify(
+          {
+            inProgress: true,
+            note: "Collection is still running or was interrupted. Rerun the same gather with --resume to finish it; this file is replaced when it completes.",
+            updatedAt: new Date().toISOString(),
+            dir,
+            yesterdayUtc: yesterday,
+            costDateUtc: yesterday,
+            collection: { id: collection.collectionId, startedAt: collection.startedAt, phase: collection.phase },
+            steps,
+            failed: steps.filter((s) => !s.ok && !s.deferred).map((s) => s.name),
+            deferred: steps.filter((s) => s.deferred).map((s) => ({ name: s.name, reason: s.reason })),
+          },
+          null,
+          2,
+        ),
+        { mode: 0o600 },
+      );
+    } catch {
+      // Progress is best effort; the final summary below is authoritative.
+    }
+  };
+  try {
+    return await gatherSteps();
+  } finally {
+    process.removeListener("SIGHUP", ignoreHangup);
+  }
+  async function gatherSteps() {
   const step = (name, args, file) => {
     const res = collection.collect(name, args, file, evidenceNames.test(name) ? "evidence" : "priority", run);
     steps.push({
@@ -203,6 +242,7 @@ export async function dailyRunGather(options, { run = runAdmin, now, clock } = {
       reused: Boolean(res.reused),
       ...(res.deferred ? { deferred: true, reason: res.reason } : res.ok ? {} : { error: res.json?.error || res.stderr }),
     });
+    writeProgress();
     return res;
   };
   step("energy-budget", ["energy-budget"], "energy-budget.json");
@@ -411,6 +451,8 @@ export async function dailyRunGather(options, { run = runAdmin, now, clock } = {
   if (botOk) renderBotOutput({ chatMessages, comments }, path.join(dir, "bot-chats.txt"));
 
   const summary = {
+    // The collection finished (failed steps are listed separately).
+    inProgress: false,
     collectedAt: new Date().toISOString(),
     durationMs: Math.round(performance.now() - startedAt),
     dir,
@@ -460,6 +502,7 @@ export async function dailyRunGather(options, { run = runAdmin, now, clock } = {
     status: summary.failed.length ? "partial_failure" : summary.deferred.length ? "deferred" : "success",
     data: summary,
   };
+  }
 }
 
 // Recent, provably never-Featured Subjects with the context the editorial

package/lib/admin-member-trace.js

@@ -0,0 +1,247 @@
+// `lumine admin member-trace ...`: the owner trace switched on for specific
+// member accounts, so a bug one member reports (and Mikey cannot reproduce)
+// can be read the way his own are. The server keeps 30 days.
+//
+//   lumine admin member-trace list
+//   lumine admin member-trace on <username> --reason "<why>"
+//   lumine admin member-trace off <username>
+//   lumine admin member-trace <username> [--since 2h] [--source all|client|server] [...]
+//     (`member-trace read <username>` is the same, for a member named list/on/off/read)
+
+import { buildOwnerTraceOperation, formatOwnerTrace } from "./admin-owner-trace.js";
+
+export const MEMBER_TRACE_USAGE =
+  "Usage: lumine admin member-trace list | on <username> --reason <why> | off <username> | [read] <username> [--since 2h|30m|3d|<iso>|<unix>] [--until <unix-second>] [--cursor <time:id>] [--source all|client|server] [--type reload,route,chat-select,error,api,...] [--path <substring>] [--limit 300] [--json].";
+
+const ACTIONS = new Set(["list", "on", "off", "read"]);
+const SOURCES = new Set(["all", "client", "server"]);
+
+function validationError(message) {
+  const error = new Error(message);
+  error.code = "CLI_ADMIN_CLI_VALIDATION";
+  return error;
+}
+
+function memberName(value) {
+  const name = String(value || "").trim().replace(/^@/, "");
+  if (!name) throw validationError(MEMBER_TRACE_USAGE);
+  if (!/^[^\s/?#]{1,40}$/.test(name)) {
+    throw validationError("Name the member by username or user id.");
+  }
+  return name;
+}
+
+export function buildMemberTraceOperation({ action = "", target = "", options }) {
+  if (action === "list") {
+    return {
+      name: "member-trace.list",
+      method: "GET",
+      path: "/cli/admin/member-trace/accounts",
+      body: undefined,
+      mutates: false,
+      requiresRun: false,
+    };
+  }
+  if (action === "on") {
+    const reason = String(options.adminReason || "").trim();
+    if (!reason) {
+      throw validationError(
+        'Say why with --reason (for example --reason "General chat main keeps reloading").',
+      );
+    }
+    return {
+      name: "member-trace.on",
+      method: "POST",
+      path: "/cli/admin/member-trace/on",
+      body: { user: memberName(target), reason: reason.slice(0, 255) },
+      mutates: true,
+      requiresRun: false,
+    };
+  }
+  if (action === "off") {
+    return {
+      name: "member-trace.off",
+      method: "POST",
+      path: "/cli/admin/member-trace/off",
+      body: { user: memberName(target) },
+      mutates: true,
+      requiresRun: false,
+    };
+  }
+  const user = memberName(action === "read" ? target : action);
+  if (!ACTIONS.has(action) && target) {
+    throw validationError(MEMBER_TRACE_USAGE);
+  }
+  // the owner trace's filters (--since/--until/--cursor/--type/--path/--limit)
+  const owner = buildOwnerTraceOperation(options);
+  const query = new URLSearchParams(owner.path.split("?")[1] || "");
+  query.set("user", user);
+  const source = String(options.adminTraceSource || "").trim();
+  if (source) {
+    if (!SOURCES.has(source)) {
+      throw validationError("--source is all, client (the website on the device) or server (the API's view of its requests).");
+    }
+    query.set("source", source);
+  }
+  return {
+    name: "member-trace.read",
+    method: "GET",
+    path: `/cli/admin/member-trace?${query.toString()}`,
+    body: undefined,
+    mutates: false,
+    requiresRun: false,
+  };
+}
+
+function formatWhen(seconds) {
+  const value = Number(seconds);
+  if (!value) return "never";
+  return new Date(value * 1000).toISOString().replace("T", " ").slice(0, 16) + " UTC";
+}
+
+export function formatMemberTraceList(data) {
+  const accounts = Array.isArray(data?.accounts) ? data.accounts : [];
+  if (!accounts.length) return ["No member is traced."];
+  const lines = [`${accounts.length} traced member account(s):`];
+  for (const account of accounts) {
+    lines.push(
+      `  ${account.username || "?"} (#${account.userId}) · on since ${formatWhen(account.enabledAt)}${account.enabledByUsername ? ` by ${account.enabledByUsername}` : ""} · ${account.reason || "(no reason)"}`,
+    );
+    lines.push(
+      `      last 24 h: ${account.clientRows24h ?? "?"} website event(s) (last ${formatWhen(account.lastClientAt)}), ${account.serverRows24h ?? "?"} API request row(s) (last ${formatWhen(account.lastServerAt)})`,
+    );
+  }
+  return lines;
+}
+
+export function formatMemberTraceSwitch(data) {
+  const who = `${data?.username || "?"} (#${data?.userId ?? "?"})`;
+  if (data?.enabled) {
+    return [
+      data.alreadyOn
+        ? `Member trace was already on for ${who}.`
+        : `Member trace is on for ${who}. Every API process picks it up within ${data.effectiveWithinSeconds ?? 30} s; the website starts tracing at the member's next page load.`,
+    ];
+  }
+  return [
+    data?.wasOn
+      ? `Member trace is off for ${who}. Rows already kept expire after ${data.keptRowsExpireAfterDays ?? 30} days.`
+      : `Member trace was not on for ${who}.`,
+  ];
+}
+
+function count(map, key) {
+  map.set(key, (map.get(key) || 0) + 1);
+}
+
+function listCounts(map) {
+  return [...map.entries()]
+    .sort((a, b) => b[1] - a[1])
+    .map(([key, n]) => `${key} ×${n}`)
+    .join(", ");
+}
+
+// The plain-words summary the daily run reports: which website build the
+// device runs (as the website says and as the API saw it), page loads and how
+// they were opened, self-reloads by reason, errors.
+export function summarizeMemberTrace(data) {
+  const events = Array.isArray(data?.events) ? data.events : [];
+  const client = events.filter((event) => event.type !== "api" && event.type !== "api-dropped");
+  const server = events.filter((event) => event.type === "api" || event.type === "api-dropped");
+  const versions = new Map();
+  const bundles = new Map();
+  const navTypes = new Map();
+  const reloads = new Map();
+  const errors = new Map();
+  const loadCauses = new Map();
+  let socketDrops = 0;
+  let socketDropsVisible = 0;
+  let chatLoadingScreens = 0;
+  for (const event of client) {
+    const data = event.data || {};
+    if (event.type === "session") {
+      count(versions, data.version || "?");
+      if (data.entry) count(bundles, data.entry);
+      count(navTypes, data.navType || "?");
+    } else if (event.type === "boot") {
+      count(
+        loadCauses,
+        data.byCode ? `code:${data.byCode}` : data.on ? "tracing switched on" : data.navType === "reload" ? "reload by hand/browser" : data.navType || "?",
+      );
+    } else if (event.type === "socket" && data.e === "disconnect") {
+      socketDrops += 1;
+      if (data.vis === "visible") socketDropsVisible += 1;
+    } else if (event.type === "chat-loading" && data.e === "shown") {
+      chatLoadingScreens += 1;
+    } else if (event.type === "reload") {
+      count(reloads, data.reason || "?");
+    } else if (event.type === "error" || event.type === "rejection" || event.type === "boundary-error") {
+      count(errors, `${event.type}: ${String(data.msg || "").slice(0, 80)}`);
+    }
+  }
+  const apiVersions = new Map();
+  const statuses = new Map();
+  const devices = new Set();
+  let sessionLoads = 0;
+  for (const event of server) {
+    const data = event.data || {};
+    if (event.type !== "api") continue;
+    count(apiVersions, data.v || "?");
+    devices.add(event.sessionId);
+    const status = data.s === "aborted" ? "aborted" : Number(data.s) >= 400 ? String(data.s) : null;
+    if (status) count(statuses, status);
+    if (String(event.path || "").startsWith("/user/session") && !String(event.path).startsWith("/user/session/")) {
+      sessionLoads += 1;
+    }
+  }
+  const lines = [];
+  lines.push(
+    `Website: ${client.filter((event) => event.type === "session").length} page load(s)${navTypes.size ? ` (opened by ${listCounts(navTypes)})` : ""}${versions.size ? ` · version ${listCounts(versions)}` : ""}${bundles.size ? ` · bundle ${listCounts(bundles)}` : ""}`,
+  );
+  if (loadCauses.size) lines.push(`Why pages loaded: ${listCounts(loadCauses)}`);
+  lines.push(`Self-reloads: ${reloads.size ? listCounts(reloads) : "none recorded"}`);
+  lines.push(
+    `Socket drops: ${socketDrops}${socketDrops ? ` (${socketDropsVisible} while the page was visible)` : ""} · full chat loading screens: ${chatLoadingScreens}`,
+  );
+  lines.push(`Errors: ${errors.size ? listCounts(errors) : "none recorded"}`);
+  lines.push(
+    `API view: ${server.length} request row(s) from ${devices.size} device(s)${apiVersions.size ? ` · reported website version ${listCounts(apiVersions)}` : ""} · session loads ${sessionLoads}${statuses.size ? ` · failures ${listCounts(statuses)}` : ""}`,
+  );
+  if (!client.length && server.length) {
+    lines.push(
+      "  No website events: the device has not run a website build with the member trace yet (an older cached bundle?), or it has not loaded since tracing was switched on.",
+    );
+  }
+  return lines;
+}
+
+export function formatMemberTrace(data) {
+  const user = data?.user || {};
+  const who = `${user.username || "?"} (#${user.id ?? "?"})`;
+  const lines = [
+    `Member trace for ${who}${user.traced ? `, on since ${formatWhen(user.enabledAt)}: ${user.reason || ""}` : ", tracing is OFF (older rows only)"}${data?.source && data.source !== "all" ? ` · ${data.source} rows only` : ""}${data?.duplicates ? ` · ${data.duplicates} re-sent duplicate(s) hidden` : ""}`,
+  ];
+  for (const line of summarizeMemberTrace(data)) lines.push(`  ${line}`);
+  const events = Array.isArray(data?.events) ? data.events : [];
+  const client = events.filter((event) => event.type !== "api" && event.type !== "api-dropped");
+  const server = events.filter((event) => event.type === "api" || event.type === "api-dropped");
+  if (data?.source !== "server") {
+    lines.push("");
+    lines.push(...formatOwnerTrace({ ...data, events: client }, { title: "Website events (from the device)" }));
+  }
+  if (data?.source !== "client") {
+    lines.push("");
+    lines.push(...formatOwnerTrace({ ...data, events: server }, { title: "API view (requests from this account; session = device tag)" }));
+  }
+  return lines;
+}
+
+export function printMemberTraceResult(operation, data) {
+  const lines =
+    operation.name === "member-trace.list"
+      ? formatMemberTraceList(data)
+      : operation.name === "member-trace.read"
+        ? formatMemberTrace(data)
+        : formatMemberTraceSwitch(data);
+  for (const line of lines) console.log(line);
+}

package/lib/admin-news.js

@@ -252,6 +252,20 @@ export function validateNewsEditorial({ claim: claimValue, editorial }) {
 export function writeNewsClaimArtifacts({ result, outputPath, scaffoldPath }) {
   const claim = result?.data?.claim || null;
   const artifacts = { claimFile: null, scaffoldFile: null };
+  if (!claim) {
+    // Nothing to claim (the edition already printed, or the next one has not
+    // opened yet). Never overwrite an existing claim file with a null claim:
+    // that destroyed a valid claim when a run tried too early (11-01, 11-02).
+    const nextEditionAt = Number(result?.data?.newspaper?.nextEditionAt) || null;
+    artifacts.notClaimed = {
+      status: result?.status || null,
+      printDecision: result?.data?.newspaper?.printDecision || null,
+      nextEditionAt,
+      nextEditionAtIso: nextEditionAt ? new Date(nextEditionAt * 1000).toISOString() : null,
+      outputLeftUnchanged: outputPath || null,
+    };
+    return artifacts;
+  }
   if (outputPath) {
     artifacts.claimFile = writeAdminJsonFile(
       outputPath,

package/lib/admin-owner-trace.js

@@ -129,6 +129,7 @@ function describeSession(data = {}, path = "") {
       : data.navType
         ? `nav ${data.navType}`
         : "",
+    data.entry ? `bundle ${data.entry}` : "",
     describeNet(data.net),
   ].filter(Boolean);
   if (path) parts.push(`at ${path}`);
@@ -186,6 +187,24 @@ export function describeOwnerTraceEvent(event) {
     case "error":
     case "rejection":
       return `${data.msg || "(no message)"}${data.src ? ` (${data.src}:${data.line}:${data.col})` : ""}${data.status ? ` HTTP ${data.status}` : ""}`;
+    // the member trace's events (and the reload/chat ones the owner trace
+    // now records too)
+    case "reload":
+      return `SELF-RELOAD ${data.reason || "?"}${pairs(data, ["reason", "v"]) ? ` · ${pairs(data, ["reason", "v"])}` : ""}`;
+    case "chat-select":
+      return `channel ${data.channelId ?? "?"}${data.subchannel ? `/${data.subchannel}` : ""}${data.subchannelId ? ` (subchannel ${data.subchannelId})` : ""}${data.pathId ? ` · path ${data.pathId}` : ""}${data.chatType ? ` · ${data.chatType}` : ""}`;
+    case "boot":
+      return `page loaded${data.navType ? ` (${data.navType})` : ""}${data.byCode ? ` · reloaded by code: ${data.byCode} ${data.byCodeAgoMs ?? "?"}ms earlier${data.byCodeAt ? ` at ${data.byCodeAt}` : ""}` : data.navType === "reload" ? " · no code reload note (by hand or by the browser)" : ""}${data.kept ? ` · ${data.kept} batch(es) kept from an earlier page` : ""}${data.on ? ` · tracing switched on (${data.on})` : ""}`;
+    case "socket":
+      return `socket ${data.e || "?"}${data.reason ? ` (${data.reason})` : ""} · ${data.vis || "?"}${data.visibleForMs !== undefined ? ` ${formatDuration(data.visibleForMs)} after the page became visible` : ""}${data.upMs !== undefined ? ` · was up ${formatDuration(data.upMs)}` : ""}${data.downMs !== undefined ? ` · was down ${formatDuration(data.downMs)}` : ""}`;
+    case "chat-loading":
+      return data.e === "shown" ? 'full "Loading Twinkle Chat..." screen shown' : `full chat loading screen gone after ${formatDuration(data.ms)}`;
+    case "boundary-error":
+      return `error screen at ${data.at || "?"}: ${data.msg || "(no message)"}${data.lazy ? " · chunk load" : ""}${data.truncated ? " · truncated chunk" : ""}`;
+    case "api":
+      return describeApiRow(data, event.path);
+    case "api-dropped":
+      return `${data.count ?? "?"} more API request(s) in that minute not kept (cap)`;
     default:
       return pairs(data);
   }
@@ -251,6 +270,16 @@ function describeWake(data) {
   return parts.join(" · ");
 }
 
+// One request the API saw from a traced member: method, route, status, time,
+// the website version the request reported.
+function describeApiRow(data) {
+  const params = isPlainObject(data.p)
+    ? ` ${Object.entries(data.p).map(([key, value]) => `${key}=${value}`).join(",")}`
+    : "";
+  const server = [data.h ? `host ${data.h}` : "", data.pst ? `worker since ${new Date(data.pst * 1000).toISOString().slice(11, 19)}Z` : ""].filter(Boolean).join(" ");
+  return `${data.m || "?"} → ${data.s ?? "?"} in ${data.ms ?? "?"}ms · website v${data.v || "?"}${params}${server ? ` · ${server}` : ""}${data.ua ? ` · ua ${data.ua}` : ""}`;
+}
+
 function isPlainObject(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
@@ -336,13 +365,13 @@ function describeNavTiming(data) {
   return [head, `${data.nav || "?"} via ${data.via || "?"}`, ...steps, ...tail].join(" · ");
 }
 
-export function formatOwnerTrace(data) {
+export function formatOwnerTrace(data, { title = "Owner trace" } = {}) {
   const events = Array.isArray(data?.events) ? data.events : [];
   const lines = [];
   const sessions = new Set(events.map((event) => event.sessionId));
   const since = Number(data?.since || 0);
   lines.push(
-    `Owner trace since ${since ? `${formatDay(since * 1000)} ${formatClock(since * 1000).slice(0, 5)}` : "?"} · ${events.length} event(s) · ${sessions.size} session(s)${data?.truncated ? ` · more pages (keep --since/--until; --cursor ${data.nextCursor || "unavailable"})` : ""}`,
+    `${title} since ${since ? `${formatDay(since * 1000)} ${formatClock(since * 1000).slice(0, 5)}` : "?"} · ${events.length} event(s) · ${sessions.size} session(s)${data?.truncated ? ` · more pages (keep --since/--until; --cursor ${data.nextCursor || "unavailable"})` : ""}`,
   );
   if (!events.length) {
     lines.push("Nothing recorded in this window.");

package/lib/admin.js

@@ -44,6 +44,10 @@ import {
   buildOwnerTraceOperation,
   printOwnerTrace,
 } from "./admin-owner-trace.js";
+import {
+  buildMemberTraceOperation,
+  printMemberTraceResult,
+} from "./admin-member-trace.js";
 import { buildRolesOperation, printRoles } from "./admin-roles.js";
 import { buildSpendingOperation, completeSpendingReport, formatSpending } from "./admin-spending.js";
 import { buildCraftOperation, formatCraftResult } from "./admin-craft.js";
@@ -1872,6 +1876,7 @@ function transformAdminResult({
   }
   if (operation.name === "subjects.candidates") {
     assertSubjectWindowResult({ operation, result: transformed });
+    transformed = markSubjectsNeedingReveal(transformed);
   }
   if (operation.name === "builds.candidates") {
     assertBuildWindowResult({ operation, result: transformed });
@@ -1923,6 +1928,30 @@ export function assertRecommendationWindowResult({ operation, result }) {
   }
 }
 
+// A secret Subject's effort can't be set until its secret is revealed through
+// the canonical action (CLI_ADMIN_SECRET_REVEAL_REQUIRED). Say so on the
+// candidate itself, with the exact command, instead of failing at effort set.
+export function markSubjectsNeedingReveal(result) {
+  const subjects = result?.data?.subjects;
+  if (!Array.isArray(subjects)) return result;
+  return {
+    ...result,
+    data: {
+      ...result.data,
+      subjects: subjects.map((subject) => {
+        const needsReveal =
+          (subject?.secret?.hasSecret === true ||
+            subject?.hasSecretAnswer === true ||
+            subject?.hasSecretAttachment === true) &&
+          subject?.secret?.revealed !== true;
+        return needsReveal
+          ? { ...subject, needsReveal: true, revealCommand: `lumine admin subject reveal ${subject.id}` }
+          : subject;
+      }),
+    },
+  };
+}
+
 export function assertSubjectWindowResult({ operation, result }) {
   const mode = operation?.pagination?.coverageMode;
   if (!mode || mode === "legacy") return;
@@ -2714,6 +2743,10 @@ export function parseAdminOperation(options) {
   if (namespace === "owner-trace") {
     return buildOwnerTraceOperation(options);
   }
+  // The owner trace switched on for specific members (admin-member-trace.js).
+  if (namespace === "member-trace") {
+    return buildMemberTraceOperation({ action, target, options });
+  }
   if (namespace === "jev-routing") {
     return buildJevRoutingReviewOperation({ action, target, extra, options });
   }
@@ -6199,9 +6232,10 @@ async function printSpooledAdminResult({ operation, result, storage }) {
     console.log(`${count} subject(s):`);
     await forEachPaginatedResultItem(result, async (subject) => {
       console.log(
-        `#${subject.id} ${subject.title || "(untitled)"} — ${subject.author?.username || "unknown"} — effort ${subject.effortLevel ?? "unknown"}`,
+        `#${subject.id} ${subject.title || "(untitled)"} — ${subject.author?.username || "unknown"} — effort ${subject.effortLevel ?? "unknown"}${subject.needsReveal ? " — secret: reveal before setting effort" : ""}`,
       );
       console.log(`  ${subject.url}`);
+      if (subject.needsReveal) console.log(`  ${subject.revealCommand}`);
     });
   } else if (storage.collectionKey === "events") {
     console.log(`${count} audit event(s):`);
@@ -7691,6 +7725,10 @@ function printAdminResult({ operation, result }) {
     printOwnerTrace(data);
     return;
   }
+  if (String(operation.name || "").startsWith("member-trace.")) {
+    printMemberTraceResult(operation, data);
+    return;
+  }
   if (operation.name === "jevRouting.review") {
     for (const line of formatJevRoutingReview(data)) console.log(line);
     return;
@@ -8227,9 +8265,10 @@ function printAdminResult({ operation, result }) {
     console.log(`${data.subjects.length} subject(s):`);
     for (const subject of data.subjects) {
       console.log(
-        `#${subject.id} ${subject.title || "(untitled)"} — ${subject.author?.username || "unknown"} — effort ${subject.effortLevel ?? "unknown"}`,
+        `#${subject.id} ${subject.title || "(untitled)"} — ${subject.author?.username || "unknown"} — effort ${subject.effortLevel ?? "unknown"}${subject.needsReveal ? " — secret: reveal before setting effort" : ""}`,
       );
       console.log(`  ${subject.url}`);
+      if (subject.needsReveal) console.log(`  ${subject.revealCommand}`);
     }
     printPagination(data.pagination);
     return;
@@ -8248,6 +8287,19 @@ function printAdminResult({ operation, result }) {
     printPagination(data.pagination);
     return;
   }
+  if (data.artifacts?.notClaimed) {
+    const info = data.artifacts.notClaimed;
+    const opens = info.nextEditionAt
+      ? `${new Date(info.nextEditionAt * 1000).toISOString().replace(".000Z", "Z")} (${new Date(info.nextEditionAt * 1000).toLocaleString("en-US", { timeZone: "Asia/Seoul", hour: "2-digit", minute: "2-digit", month: "short", day: "numeric" })} KST)`
+      : "an unknown time";
+    console.log(
+      `No edition to claim${info.printDecision === "already_printed" ? ": today's paper is already printed" : ""}. The next edition opens at ${opens}.`,
+    );
+    if (info.outputLeftUnchanged) {
+      console.log(`${info.outputLeftUnchanged} was left unchanged. Run news claim again after the edition opens.`);
+    }
+    return;
+  }
   if (data.claim) {
     if (data.artifacts?.claimFile) {
       console.log(

package/lib/commands.js

@@ -2701,6 +2701,8 @@ export function parseArgs(args) {
     adminPath: raw.path ? String(raw.path) : "",
     adminPerf: Boolean(raw.perf),
     adminWake: Boolean(raw.wake),
+    // lumine admin member-trace <username> --source all|client|server
+    adminTraceSource: raw.source ? String(raw.source) : "",
     adminMinLevel: raw.minLevel === undefined ? null : raw.minLevel,
     adminIncludeLegacy: Boolean(raw.includeLegacy),
     adminIncludePrivateEvidence: parseBoolean(
@@ -3405,6 +3407,7 @@ export function printHelp() {
   lumine admin reward-bank seed <buildId> [--max-step 3] [--identity zero|ciel|auto] [--json]   (writes ONE missing seed question, lowest step first, billed to Zero/Ciel's AI Energy; inside a daily run or on its own, owner only)
   lumine admin reward-bank report <buildId> [--days 1] [--json]   (question-bank telemetry: generation outcomes, learners, payouts, ladder, questions to review)
   lumine admin owner-trace [--since 2h|30m|3d|<iso>] [--type route,feed-open,scroll-anchor,content-scroll,error,rejection,session,nav-timing,slow-request,stall,page-load,scroll-perf,scroll-frame] [--perf] [--wake] [--path <substring>] [--limit 300] [--json]   (--wake: sessions, 20 s wake profiles, bounded viewport geometry and dropped-event counts after loads or returns; network tags identify the upload network; what the website did on Mikey's own devices: routes with PUSH/POP/REPLACE, Home feed card opens, scroll-anchor restores, content scroll positions, window errors, and performance: tap-to-page timing, API requests over 1 s, main-thread stalls over 200 ms, page load, scroll frame pacing and slow-frame attribution (Long Animation Frame scripts on Chrome, feed card renders on Safari); --perf shows only those; kept 30 days)
+  lumine admin member-trace list | on <username> --reason <why> | off <username> | [read] <username> [--since 2h|30m|3d|<iso>] [--source all|client|server] [--type reload,route,chat-select,boot,session,error,rejection,boundary-error,api] [--path <substring>] [--limit 300] [--json]   (the owner trace switched on for specific member accounts to chase a bug they report: on/off are audited admin actions and take effect within 30 s; the website side records page loads with version and bundle, routes, chat channel/subchannel selection, every self-reload with its reason (kept on the device across the reload), error screens and window errors; the API side records each request from that account with its route, status, time and the website version it reported, so a device stuck on an old cached bundle still shows; read prints a plain summary first; kept 30 days)
   lumine admin roles [--min-level 1] [--limit 50] [--json]   (every user type with its management level and who holds it; admin pages need level 3, achievement points never pass level 2)
   lumine admin jev-images report [--days 1..30] | switch --area <all|arena_paper|arena_picture|study_record|thumbnail|sdk_decide> --mode on|off [--daily-cap <0-5000>] [--build <id>, sdk_decide only, no --daily-cap] | decide --area <area> --key <subject key> --decision <decision> | thumbnails --targets <subject:<id>,build:<id>,...> | --featured [--saved-only] [--json]   (JEV image checks: advisory only; per-area health, cost, agreement with final decisions and escalations for the daily run; switch is owner-only and needs no deploy; thumbnails adds notes for Featured review and never replaces or unfeatures anything)
   lumine admin jev-routing review --since <unix|ISO> --until <unix|ISO> [--limit 1..20] [--cursor <cursor> | --all --checkpoint <file> [--resume]] [--include-synthetic] [--json]   (bounded frozen evidence for paired disagreements and Auto fallbacks; collection is not review)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage5/lumine",
-  "version": "0.3.78",
+  "version": "0.3.79",
   "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.77.0
+Version: 1.78.0
 Updated: 2026-11-01
-Generated: 2026-11-01T12:15:43.879Z
+Generated: 2026-11-02T01:19:13.071Z
 
 ## 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.
@@ -971,10 +971,11 @@ const result = await Twinkle.characters.chat({ character: 'zero', thinkingMode:
   - map.heightUrlTemplate (or null) gives the land's shape on the same tile grid for 3D maps (ground heights; buildings and trees narrower than about 20 blocks are left out, so draw those from getTerrainChunks): a gzipped 'THM1' file, 16-byte little-endian header (magic, uint16 samples per side, uint16 blocks per sample, float64 source time) then samples x samples int16 heights row by row (z, then x); -32768 = no ground. Images and heights are served with CORS, so WebGL can use them.
   - Example: const { worlds } = await Twinkle.minecraft.getWorlds(); const w = worlds.find((x) => x.id === 'world'); const z = w.map.maxZoom; const blocksPerTile = w.map.blocksPerTileAtMaxZoom * 2 ** (w.map.maxZoom - z); const tx = Math.floor(blockX / blocksPerTile), ty = Math.floor(blockZ / blocksPerTile); const url = w.map.tileUrlTemplate.replace('{z}', z).replace('{x}', tx).replace('{y}', ty);
 - async getOnlinePlayers() | scopes: content:read
-  - Returns: { players: [{ name, world, x, y, z, isZero }], count, stale }
+  - Returns: { players: [{ name, world, x, y, z, isZero }], count, visitors: [{ userId, username, world, x, y, z, since }], visitorCount, stale }
   - List players currently online with their world and block coordinates. Zero appears with isZero: true and is not counted in count.
   - Cached for about 5 seconds; poll no faster than every 5 seconds.
   - Names are Minecraft usernames, not Twinkle usernames.
+  - visitors are website members walking the world from Twinkle MC Explorers (Twinkle usernames, not Minecraft names). They are online and visible in game but are not players on the server; count counts players only.
   - Example: const { players, count } = await Twinkle.minecraft.getOnlinePlayers();
 - async getZero() | scopes: content:read
   - Returns: { zero: { online, world, position: { x, y, z } | null, activity: 'idle'|'thinking'|'building'|'workshop', currentBuild: { id, title, status, placed, total, requester, world, bounds } | null, queue: [build], workshop: { world, min, max } | null, updatedAt }, stale }
@@ -1005,21 +1006,22 @@ const result = await Twinkle.characters.chat({ character: 'zero', thinkingMode:
   - Every change is logged on the server and emailed to the owner; the player is told in game.
   - Example: await Twinkle.minecraft.setPlayerRole({ uuid: person.uuid, role: 'builder' });
 - async getChat({ since } = {}) | scopes: content:read
-  - Returns: { events: [{ seq, at, kind: 'chat'|'zero'|'web'|'join'|'leave'|'death', name, text, userId, archived }], latestSeq, online, archiveReady, viewer: { canSend, muted, canModerate }, mutedUserIds }
+  - Returns: { events: [{ seq, at, kind: 'chat'|'zero'|'web'|'join'|'leave'|'death'|'visit'|'unvisit', name, text, userId, archived }], latestSeq, online, visitorCount, archiveReady, viewer: { canSend, muted, canModerate }, mutedUserIds }
   - Live server chat after a sequence number: player chat, Zero, messages sent from the web, joins, leaves and deaths.
   - Without since (or 0) it returns the newest 50 events, oldest first. Pass since = latestSeq from the previous response to get only new events. Poll every 2-3 seconds while the chat is visible; stop when hidden.
-  - kind: chat (a player), zero (Zero, the AI builder), web (someone chatting from the Twinkle app; userId is their Twinkle user id), join, leave, death. Private messages are never included.
+  - kind: chat (a player), zero (Zero, the AI builder), web (someone chatting from the Twinkle app; userId is their Twinkle user id), join, leave, death, visit (a website visitor arrived in the world; userId is their Twinkle user id), unvisit (they left). Private messages are never included.
   - name is a Minecraft username for chat/join/leave/death, and a Twinkle username for web.
   - viewer.canModerate is true only for the server owner; mutedUserIds is filled only for them.
+  - online counts players on the server; visitorCount counts website visitors walking the world (Twinkle MC Explorers).
   - Example: let since = 0; async function poll() { const { events, latestSeq } = await Twinkle.minecraft.getChat({ since }); since = latestSeq; render(events); } setInterval(poll, 2500);
 - async getChatHistory({ before, limit, query, includeArchived } = {}) | scopes: content:read
-  - Returns: { events: [{ seq, at, kind: 'chat'|'zero'|'web'|'join'|'leave'|'death', name, text, userId, archived }], hasMore, nextBefore: { at, seq } | null, includesArchived }
+  - Returns: { events: [{ seq, at, kind: 'chat'|'zero'|'web'|'join'|'leave'|'death'|'visit'|'unvisit', name, text, userId, archived }], hasMore, nextBefore: { at, seq } | null, includesArchived }
   - Older server chat, newest first, for scrolling back or searching past days.
   - before is the nextBefore cursor from the previous page; omit it to start from the newest. limit 1-100 (default 50). query searches message text and names (60 chars).
   - Chat from before the web chat bridge existed (imported from server logs) is archived: only the server owner can include it with includeArchived: true; others never receive it.
   - Example: const page = await Twinkle.minecraft.getChatHistory({ limit: 50 }); const older = await Twinkle.minecraft.getChatHistory({ before: page.nextBefore });
 - async sendChat({ text }) | scopes: content:write
-  - Returns: { event: { seq, at, kind: 'chat'|'zero'|'web'|'join'|'leave'|'death', name, text, userId, archived } }
+  - Returns: { event: { seq, at, kind: 'chat'|'zero'|'web'|'join'|'leave'|'death'|'visit'|'unvisit', name, text, userId, archived } }
   - Send a chat message from the app into the Minecraft server; players see it as [Web] <your Twinkle username>.
   - Signed-in viewers only. text is trimmed to 200 characters. About one message per 2.5 seconds and 10 per minute per person: 429 with code minecraft_chat_rate_limited and retryAfterMs.
   - 403 minecraft_chat_forbidden for accounts banned from chat; 400 minecraft_muted when the server owner muted them from web chat.
@@ -1053,6 +1055,7 @@ const result = await Twinkle.characters.chat({ character: 'zero', thinkingMode:
   - Built-in designs (redstone devices and so on) have no author and are public.
   - previewUrl is an image set with updateDesign, or null.
   - access says what this viewer may do: canOrder shows placement tools (builders, moderators, the owner).
+  - access.web is true for a website member with no Minecraft account (a visitor): they may ask Zero for builds (the first is reviewed) and their designs are always public.
   - Example: const { designs } = await Twinkle.minecraft.getDesigns({ query: 'castle' });
 - async getDesign({ id }) | scopes: content:read
   - Returns: { design: { id, version, name, category, summary, size: { width, height, depth }, blocks, status, author, authorUserId, visibility: 'private'|'public', previewUrl, createdAt }, size: [w, h, d], palette: [blockState], cells: number[] }
@@ -1083,27 +1086,50 @@ const result = await Twinkle.characters.chat({ character: 'zero', thinkingMode:
 - async checkPlacement({ designId, world, x, z, y?, facing?: 'north'|'east'|'south'|'west' }) | scopes: content:read
   - Returns: { check: { clear, reasons, world, facing, anchor, bounds: { min, max }, ground: { y, min, max, water }, builtBlocks, builtSamples, placedBy: [{ name, blocks }], design } }
   - Check a building site for a design: where it would sit and whether it would touch anyone's builds.
-  - Who may: the server owner, and builders or moderators identified by their linked Minecraft account (Twinkle.minecraft.createLinkCode + /link). Others get 403 minecraft_not_linked or minecraft_rank_too_low.
+  - Who may: the server owner, and builders or moderators identified by their linked Minecraft account (Twinkle.minecraft.createLinkCode + /link). Website members with no Minecraft account (visitors) may too; a visitor not approved yet has no builds to stop or undo. Others get 403 minecraft_not_linked or minecraft_rank_too_low.
   - The footprint is centred on x/z and turned to face facing; without y it sits on the ground. clear is false when built (non-natural) blocks stand in the footprint or 3 blocks around it, the ground is very uneven, or it would leave the world; reasons explains. placedBy lists players CoreProtect recorded placing blocks there.
   - Call on a user action (drop or rotate), not while dragging.
+  - Visitors (no Minecraft account) may only check or order a site within about 64 blocks of where they stand in Twinkle World (Twinkle.minecraft.visit): 403 minecraft_visit_closer otherwise; and about 10 checks or orders a minute (429 minecraft_web_order_rate_limited with retryAfterMs).
   - Example: const { check } = await Twinkle.minecraft.checkPlacement({ designId: 'harbor_house', world: 'world', x: 1200, z: 700, facing: 'south' }); outline.color = check.clear ? 'green' : 'red';
 - async buildDesign({ ...placement, force }) | scopes: content:write
-  - Returns: { jobId, check, priority }
+  - Returns: { jobId, check, priority, pending?, requestId? }
   - Order Zero to build a design at a site; he switches to creative and builds it before other work.
-  - Who may: the server owner, and builders or moderators identified by their linked Minecraft account (Twinkle.minecraft.createLinkCode + /link). Others get 403 minecraft_not_linked or minecraft_rank_too_low.
+  - Who may: the server owner; builders and moderators by their linked Minecraft account (createLinkCode + /link); and website members with no Minecraft account (visitors). A visitor's FIRST order is held for the server owner's review: the answer is { jobId: null, pending: true, requestId, check } and nothing is built yet; once approved (getVisitorRequests().mine.approved) they order like builders. Linked players below builder get 403 minecraft_rank_too_low.
   - Follow progress with getZero() (currentBuild) and getZeroBuilds().
   - Builders: one order waiting or building at a time, published designs or their own, and orders wait in the normal queue (priority false). Moderators: up to 3 orders, ahead of other work. The owner: no limit. force (build on a site that isn't clear) is owner-only.
+  - Visitors (no Minecraft account) may only check or order a site within about 64 blocks of where they stand in Twinkle World (Twinkle.minecraft.visit): 403 minecraft_visit_closer otherwise; and about 10 checks or orders a minute (429 minecraft_web_order_rate_limited with retryAfterMs).
   - Example: const { jobId } = await Twinkle.minecraft.buildDesign({ designId: 'harbor_house', world: 'world', x: 1200, z: 700, facing: 'south' });
+- async getVisitorRequests() | scopes: content:read
+  - Returns: { canReview, requests: [{ id, userId, username, uuid, designId, designName, blocks, world, anchor, facing, bounds, createdAt }], approved: [{ userId, username, approvedAt, approvedBy }], recent: [{ id, userId, username, decision, by, at, note }], mine: { approved, request, lastDecision } }
+  - Website visitors' first Zero build requests, waiting for review like a builder request; and the viewer's own status.
+  - Only the server owner, in an app they own, gets canReview: true and the full lists; everyone else gets empty lists and only mine (their own open request, whether they are approved, and their last decision).
+  - Example: const { canReview, requests, mine } = await Twinkle.minecraft.getVisitorRequests(); if (mine.request) showWaiting(mine.request);
+- async decideVisitorRequest({ id, approve, note }) | scopes: content:write
+  - Returns: { approved, built, jobId, check, message }
+  - Approve or reject a website visitor's first Zero build request. Approving makes them a visitor who may order like a builder from then on and places the held build.
+  - Server owner only, in an app they own; others get 403 minecraft_roles_forbidden.
+  - built is false (with check and message) when the site is no longer clear: they stay approved and can order again elsewhere.
+  - Example: await Twinkle.minecraft.decideVisitorRequest({ id: request.id, approve: true });
+- async withdrawVisitorRequest() | scopes: content:write
+  - Returns: { withdrawn }
+  - A visitor takes back their own build request that is still waiting for review.
+  - withdrawn is false when there was nothing waiting (or the viewer has a linked Minecraft account).
+  - Example: await Twinkle.minecraft.withdrawVisitorRequest();
+- async revokeVisitorBuilder({ userId }) | scopes: content:write
+  - Returns: { revoked }
+  - Take back a visitor's approval: their next Zero order is held for review again.
+  - Server owner only, in an app they own; others get 403 minecraft_roles_forbidden.
+  - Example: await Twinkle.minecraft.revokeVisitorBuilder({ userId: 101 });
 - async stopZero() | scopes: content:write
   - Returns: { stopped, message }
   - Stop the build Zero is doing right now (placed blocks stay).
-  - Who may: the server owner, and builders or moderators identified by their linked Minecraft account (Twinkle.minecraft.createLinkCode + /link). Others get 403 minecraft_not_linked or minecraft_rank_too_low.
+  - Who may: the server owner, and builders or moderators identified by their linked Minecraft account (Twinkle.minecraft.createLinkCode + /link). Website members with no Minecraft account (visitors) may too; a visitor not approved yet has no builds to stop or undo. Others get 403 minecraft_not_linked or minecraft_rank_too_low.
   - Anyone may stop or undo their own builds; moderators also builders' and members' builds and Zero's own projects; the owner anything.
   - Example: await Twinkle.minecraft.stopZero();
 - async undoBuild({ jobId }) | scopes: content:write
   - Returns: { undone, title, message }
   - Undo one of Zero's builds, putting back what was there before.
-  - Who may: the server owner, and builders or moderators identified by their linked Minecraft account (Twinkle.minecraft.createLinkCode + /link). Others get 403 minecraft_not_linked or minecraft_rank_too_low.
+  - Who may: the server owner, and builders or moderators identified by their linked Minecraft account (Twinkle.minecraft.createLinkCode + /link). Website members with no Minecraft account (visitors) may too; a visitor not approved yet has no builds to stop or undo. Others get 403 minecraft_not_linked or minecraft_rank_too_low.
   - Anyone may stop or undo their own builds; moderators also builders' and members' builds and Zero's own projects; the owner anything.
   - Example: await Twinkle.minecraft.undoBuild({ jobId });
 - async getSnaps({ before, limit, uuid } = {}) | scopes: content:read
@@ -1194,6 +1220,28 @@ const result = await Twinkle.characters.chat({ character: 'zero', thinkingMode:
   - It shows the world as last saved (the server saves every few minutes). Pair it with world.map.heightUrlTemplate for the land farther away.
   - Reads share the 180-per-minute build read limit: ask for 24 at a time, nearest first, and keep what you loaded.
   - Example: const { scenes } = await Twinkle.minecraft.getTerrainChunks({ world: 'world', chunks: [[71, 38], [72, 38]] });
+- async getFullChunks({ world, chunks: [[cx, cz], ...] }) | scopes: content:read
+  - Returns: { scenes: [{ cx, cz, scene: { origin: [x,y,z], size: [w,h,d], palette, blocks, light, biomes, count, wide? } | null }] }
+  - Every block with a visible face in chunk columns of a world (up to 24 per call): roofed interiors and caves too, unlike getTerrainChunks. For walking inside buildings near the viewer.
+  - Same scene format as getTerrainChunks and getPlayAreaChunks; larger, so ask only for the few columns around the viewer and use getTerrainChunks farther out.
+  - It shows the world as last saved (the server saves every few minutes) and is cached for about a minute.
+  - Reads share the 180-per-minute build read limit: keep what you loaded, nearest first.
+  - Only the land around the viewer's own visit spot: call visit first; chunks more than 4 columns from where they stand in that world get 403 minecraft_visit_closer (use getTerrainChunks there).
+  - Example: const { scenes } = await Twinkle.minecraft.getFullChunks({ world: 'world', chunks: [[71, 38]] });
+- async visit({ world, x, y, z, yaw, pitch, moving }) | scopes: content:write
+  - Returns: { players: [{ name, uuid, world, x, y, z, yaw, pitch, sneaking, isZero }], visitors: [{ userId, username, world, x, y, z, yaw, pitch, moving }], stale, full, serverTime, intervalMs }
+  - Visit the real Minecraft world from the app: report where the viewer is standing and get back where the players and the other visitors in that world are. In game, the visitor shows as a figure with their Twinkle username.
+  - Signed-in viewers only. Call it about every intervalMs (500 ms) while the viewer is in the world; faster calls get 429 minecraft_visit_rate_limited with retryAfterMs. Interpolate avatars between answers.
+  - A visitor is not a player on the server: they cannot break, place or use anything there. Members who own Minecraft play at twinklemc.site.
+  - The viewer is never in visitors. stale: true means player positions could not be refreshed (show the last ones).
+  - The figure disappears about 5 seconds after the last call; call leaveVisit when the viewer leaves or switches worlds. 403 minecraft_visit_forbidden for accounts banned from chat.
+  - full: true means the world already shows the most visitors it can (40): this viewer can look around but is not shown in game yet.
+  - Example: const view = await Twinkle.minecraft.visit({ world: 'world', x: 1146.5, y: 64, z: 618.5, yaw: 90, pitch: 0, moving: true }); drawAvatars(view.players, view.visitors);
+- async leaveVisit() | scopes: content:write
+  - Returns: { left }
+  - Stop visiting: the viewer's figure leaves the Minecraft world right away.
+  - Call it when the viewer leaves the world, switches worlds or closes the app; left is false when they were not visiting.
+  - Example: await Twinkle.minecraft.leaveVisit();
 - async createPlayArea({ name, world, box, spawn, id }) | scopes: content:write
   - Returns: { level }
   - Capture a box of a Minecraft world as a new play area (or re-capture an existing id). Runs in the background: poll getPlayArea until status is 'ready'.
@@ -1205,6 +1253,7 @@ const result = await Twinkle.characters.chat({ character: 'zero', thinkingMode:
   - Zero's build queue: the build he is on, the orders waiting (in the order he will take them) and the campaign steps he works through when no order waits. For an RTS-style build panel and for drawing queued footprints on a map.
   - Everyone can read it; mine marks the viewer's own orders (linked account). Orders always run before campaign steps.
   - noBuildWorlds lists worlds Zero never builds in (World 3, World 4): don't offer placement there.
+  - access.web is true for a website member with no Minecraft account (a visitor): they may ask Zero for builds (the first is reviewed) and their designs are always public.
   - Example: const { active, queue, campaign, access } = await Twinkle.minecraft.getBuildQueue();
 - async moveQueuedBuild({ jobId, to }) | scopes: content:write
   - Returns: same as getBuildQueue

package/sdk/LUMINE_ADMIN.md

@@ -1187,7 +1187,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.
 - **Arena members waiting for papers come first.** `arena paper-queue --cursor <member-id> --limit <1-100> --json` lists members blocked by the lack of a fresh complete published paper, using the member-facing pass/retry and solo-mastery rules. Follow every `nextCursor`, including after an empty page; require `demandBasis: waiting-published-papers-v1`. Group all pages by exam/difficulty and prioritize these waiting members before generic unseen-question depth. Failed ordinary papers remain retryable; open/pending-marking sittings are not publication waits. Ten successful distinct Full Hard clears, with Zero/Ciel allowed, are needed between solo mastery attempts. The pass and full-marks 20× XP/Coins rewards are separately reserved, each once. Publish complete independently reviewed papers and verify the same members can advance. `gather` collects this queue first as `arena-paper-queue-N.json`, with `paperQueue.complete/pages/waitingTracks`; missing/malformed/partial coverage must not be reported as an empty healthy queue. Use the workspace CLI until npm publication is verified. This step grants no new authoring spend or publication authority.
-- **`gather`** saves its fixed set of read-only reports into `<dir>`, including the canonical published Math Lab queue in `math-lab-queue.json` and all types of pending Build review requests in `build-reviews-N.json`. Build reviews follow `nextCursor` to exhaustion; `gather.json` → `buildReviews` records `complete`, attempted `pages` and collected `items`. A failed/malformed page, cursor loop or 100-page bound reports incomplete coverage, never an empty healthy queue. Read the current collection once; it replaces the rewards-only list. Older packages without `buildReviews` need a separate `review list --status pending` collection through cursor exhaustion. Previous queue receipts remain on disk as history but do not become current evidence or duplicate reading duties after a new gather. It is not the complete daily checklist: app refills/usage, individual review assessments, sponsor integrity and other duties need their own steps. Repository agents follow the current full-run coverage index in `agent-guides/lumine-admin.md`. 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`: collection never acknowledges reading. 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 its fixed set of read-only reports into `<dir>`, including the canonical published Math Lab queue in `math-lab-queue.json` and all types of pending Build review requests in `build-reviews-N.json`. Build reviews follow `nextCursor` to exhaustion; `gather.json` → `buildReviews` records `complete`, attempted `pages` and collected `items`. A failed/malformed page, cursor loop or 100-page bound reports incomplete coverage, never an empty healthy queue. Read the current collection once; it replaces the rewards-only list. Older packages without `buildReviews` need a separate `review list --status pending` collection through cursor exhaustion. Previous queue receipts remain on disk as history but do not become current evidence or duplicate reading duties after a new gather. It is not the complete daily checklist: app refills/usage, individual review assessments, sponsor integrity and other duties need their own steps. Repository agents follow the current full-run coverage index in `agent-guides/lumine-admin.md`. 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`: collection never acknowledges reading. While it runs, `gather.json` is rewritten after every step with `inProgress: true` and the steps so far; the final summary replaces it with `inProgress: false`. An `inProgress: true` file means the collection was interrupted: rerun the same gather with `--resume`. A hang-up from a closing parent shell no longer stops it. 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. `collectionFailures` includes failures without a page file, such as a cursor loop; acknowledging the available files cannot make an incomplete collection complete. A fresh successful gather clears those failures. 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.
@@ -2257,6 +2257,11 @@ lumine admin builds review build:884 --output-dir ./build-review \
   --interact ./build-review/steps.json --json
 ```
 
+A secret Subject's effort can't be set until its secret is revealed
+(`CLI_ADMIN_SECRET_REVEAL_REQUIRED`). `subjects candidates` marks such rows
+with `needsReveal: true` and the exact `revealCommand`
+(`lumine admin subject reveal <id>`); run it before `subject effort set`.
+
 Schemas:
 
 ```ts
@@ -3241,6 +3246,13 @@ lumine admin news submit --claim claim.json --file editorial.json \
 lumine admin news print --json
 ```
 
+When there is nothing to claim (today's paper is already printed, or the next
+edition has not opened yet), `news claim` writes no claim or scaffold file and
+leaves any existing `--output` file untouched. Its JSON carries
+`data.artifacts.notClaimed` with `nextEditionAt` (Unix seconds and ISO); the
+text output says when the next edition opens. The daily edition opens at 00:00
+UTC (09:00 KST).
+
 The Twinkle Newspaper (Build app 1929) is normally printed by a community
 member spending their own AI Energy. Making sure today's paper exists is part
 of every delegated website-management run: check `lumine admin news` early in