@stage5/lumine 0.3.78 → 0.3.80

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/lib/platformRules.generated.js

@@ -1,4 +1,4 @@
 // Generated by twinkle-api/scripts/generate-build-sdk-index.mjs from
 // constants/buildSdkManifest.json (platformRules, essentialSdk). Do not edit by hand.
 export const LUMINE_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.\n\n1. Every page that draws on a <canvas> (2D, WebGL or Three.js) says what kind of page it is on <html>: data-twinkle-game for a game that fills the screen, data-twinkle-document for a normal scrolling page with a drawing pad, chart, visualizer or background effect. Without it, unless the page lays itself out with Twinkle.preview, Twinkle guesses from the canvas, and any canvas larger than 160 px, even one hidden in a tab, locks the page to one screen so it no longer scrolls. Add the attribute together with the first canvas.\n2. Games (data-twinkle-game) size themselves from Twinkle.preview: subscribe with Twinkle.preview.subscribe(listener, { immediate: true }), size canvases and renderers from layout.stage or layout.viewport, and report the play area with Twinkle.preview.setPlayfield(). Never size a game from 100vh/100vw, window.innerWidth/innerHeight or visualViewport, and never draw a fake phone or browser frame unless the creator asks for a device mockup: those fight the host and leave the game blank, cropped or scrolling on phones. Pages marked data-twinkle-document use ordinary CSS layout instead.\n3. alert(), confirm() and prompt() are silently blocked: alert shows nothing, confirm() always returns false (so the action it guards never happens) and prompt() returns null. Use in-page UI instead: a message element, an in-page confirm step, an <input>.\n4. Apps cannot open new windows or tabs: window.open() and target=\"_blank\" links do nothing, and neither does a download link to an uploaded file. Open Twinkle pages with Twinkle.app.openContent(url) from a tap, save files with Twinkle.files.saveAs({ url, fileName }) (or { blob, fileName } for a file the app made), and show other web addresses as plain text.\n5. Do not use <form> elements: native form submission is blocked, so a submit button inside a form does nothing. Handle inputs and buttons in JavaScript.\n6. Code loads only from project files and Twinkle's vendor paths (/build/vendor/...). Package imports, CDN scripts, external network calls and app-local /api/* routes fail at runtime; use the Twinkle SDK for data, AI and storage.\n7. Call only Twinkle.* methods documented in the SDK reference. An invented or guessed method name throws and breaks the feature.\n8. Twinkle.privateDb and Twinkle.sharedDb save on a user action or as an occasional snapshot, never per frame, tick or keystroke: fast repeated writes are refused with 429 and the data is lost. A privateDb value is at most 16 KB. Keep live state in memory, and use Twinkle.world for realtime multiplayer.\n9. Start sound and image generation inside the viewer's tap or click handler. A Web Audio AudioContext stays silent until it is created or resumed in a tap (iPhones always enforce this), and Twinkle.ai.generateImage called from load or a timer fails with USER_ACTIVATION_REQUIRED.\n10. Call setPointerCapture only inside a pointerdown handler with that event's pointerId, wrapped in try/catch, and release only when hasPointerCapture says the element holds it. From click, mouse, timer or synthetic handlers it throws and the control stops working.\n11. Keyboard games call preventDefault for their keys (Space, arrows, WASD) from a window or document keydown listener added with { passive: false }, skipping inputs, textareas, selects and contenteditable, and make the playfield focusable; otherwise those keys scroll or jump the page during play.\n12. On phones a long press on game controls selects text or opens the Copy/Look Up menu unless the whole game area (controls, HUD, menus, empty play space) is marked data-twinkle-no-select and styled user-select: none; -webkit-user-select: none; -webkit-touch-callout: none. A game drawn without a canvas sets data-twinkle-game on <html> too, so Twinkle's phone touch protections apply. Keep inputs and copyable text selectable with data-twinkle-selectable.";
-export const LUMINE_ESSENTIAL_SDK = "Features every app needs whenever they apply. When you build a new app or make a substantial change, add every one that applies as part of that change, without being asked. On a small, targeted request, add a missing one only when the request touches what it covers (a change to levels, scoring or saving: keep-place; a new screen: back-button); otherwise name it in one line so the creator can ask. Say in one line what you added. Never add one that does not apply.\n\n1. When: The app has a place worth keeping: a game, a level or score in play, an open document, drawing or editor, a quiz in progress, a chosen view. Use: Register Twinkle.app.lifecycle.onSuspend(() => smallState) and, at startup, restore from await Twinkle.app.lifecycle.getResumeState(). Phones unload apps that are not on screen (3D apps right away) and browsers kill tabs; without this the player starts over every time.\n2. When: The app has more than one view: a list and its details, menus, chapters, pages, settings. Use: Twinkle.app.history.push on each confirmed view change and Twinkle.app.history.subscribe to restore views, so Back and Forward move inside the app instead of leaving it.\n3. When: Progress, collections, unlocks, high scores or settings the viewer expects to still have tomorrow. Use: Twinkle.privateDb (Twinkle.sharedDb for what everyone sees), written on a user action or as an occasional snapshot, never per frame.\n4. When: The app shares or links to something inside itself (a level, a post, a result). Use: Twinkle.app.getShareUrl(pathSegment) for the link, and read the segment back at startup, instead of building twin-kle.com URLs by hand.";
+export const LUMINE_ESSENTIAL_SDK = "Features every app needs whenever they apply. When you build a new app or make a substantial change, add every one that applies as part of that change, without being asked. On a small, targeted request, add a missing one only when the request touches what it covers (a change to levels, scoring or saving: keep-place; a new screen: back-button); otherwise name it in one line so the creator can ask. Say in one line what you added. Never add one that does not apply.\n\n1. When: The app has a place worth keeping: a game, a level or score in play, an open document, drawing or editor, a quiz in progress, a chosen view or tab, a long page the viewer scrolls. Use: Register Twinkle.app.lifecycle.onSuspend(() => smallState, { work: [...] }) and, at startup, restore from await Twinkle.app.lifecycle.getResumeState(). The snapshot holds where the viewer is looking (scroll, open tab or view, selected item) and unfinished work (a game or level in play, a half-written answer, an unsaved drawing, a quiz in progress); list the work keys in { work }. A return (the phone unloaded the app, a reload, a quick switch away) gets everything back; a new visit (the next day, a new tab) starts at the app's start and gets only the work keys. Phones unload apps that are not on screen (3D apps right away) and browsers kill tabs; without this the player starts over every time.\n2. When: The app has more than one view: a list and its details, menus, chapters, pages, settings. Use: Twinkle.app.history.push on each confirmed view change and Twinkle.app.history.subscribe to restore views, so Back and Forward move inside the app instead of leaving it.\n3. When: Progress, collections, unlocks, high scores or settings the viewer expects to still have tomorrow. Use: Twinkle.privateDb (Twinkle.sharedDb for what everyone sees), written on a user action or as an occasional snapshot, never per frame.\n4. When: The app shares or links to something inside itself (a level, a post, a result). Use: Twinkle.app.getShareUrl(pathSegment) for the link, and read the segment back at startup, instead of building twin-kle.com URLs by hand.";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage5/lumine",
-  "version": "0.3.78",
+  "version": "0.3.80",
   "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
-Updated: 2026-11-01
-Generated: 2026-11-01T12:15:43.879Z
+Version: 1.80.0
+Updated: 2026-11-02
+Generated: 2026-11-02T01:36:03.543Z
 
 ## 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.
@@ -23,7 +23,7 @@ Each rule below is a way an app breaks once it runs inside Twinkle's sandboxed f
 ## Essential SDK features
 Features every app needs whenever they apply. When you build a new app or make a substantial change, add every one that applies as part of that change, without being asked. On a small, targeted request, add a missing one only when the request touches what it covers (a change to levels, scoring or saving: keep-place; a new screen: back-button); otherwise name it in one line so the creator can ask. Say in one line what you added. Never add one that does not apply.
 
-1. When: The app has a place worth keeping: a game, a level or score in play, an open document, drawing or editor, a quiz in progress, a chosen view. Use: Register Twinkle.app.lifecycle.onSuspend(() => smallState) and, at startup, restore from await Twinkle.app.lifecycle.getResumeState(). Phones unload apps that are not on screen (3D apps right away) and browsers kill tabs; without this the player starts over every time.
+1. When: The app has a place worth keeping: a game, a level or score in play, an open document, drawing or editor, a quiz in progress, a chosen view or tab, a long page the viewer scrolls. Use: Register Twinkle.app.lifecycle.onSuspend(() => smallState, { work: [...] }) and, at startup, restore from await Twinkle.app.lifecycle.getResumeState(). The snapshot holds where the viewer is looking (scroll, open tab or view, selected item) and unfinished work (a game or level in play, a half-written answer, an unsaved drawing, a quiz in progress); list the work keys in { work }. A return (the phone unloaded the app, a reload, a quick switch away) gets everything back; a new visit (the next day, a new tab) starts at the app's start and gets only the work keys. Phones unload apps that are not on screen (3D apps right away) and browsers kill tabs; without this the player starts over every time.
 2. When: The app has more than one view: a list and its details, menus, chapters, pages, settings. Use: Twinkle.app.history.push on each confirmed view change and Twinkle.app.history.subscribe to restore views, so Back and Forward move inside the app instead of leaving it.
 3. When: Progress, collections, unlocks, high scores or settings the viewer expects to still have tomorrow. Use: Twinkle.privateDb (Twinkle.sharedDb for what everyone sees), written on a user action or as an occasional snapshot, never per frame.
 4. When: The app shares or links to something inside itself (a level, a post, a result). Use: Twinkle.app.getShareUrl(pathSegment) for the link, and read the segment back at startup, instead of building twin-kle.com URLs by hand.
@@ -128,21 +128,32 @@ files:read, media:read, media:write, live:read, live:write, user:read, users:rea
   - Returns: Canonical shareable deep-link URL string, or null when app info is unavailable
   - Builds a canonical shareable deep link into this app, e.g. https://www.twin-kle.com/app/884/432-the-great-gatsby.
   - Example: await Twinkle.app.getShareUrl('432-the-great-gatsby');
-- lifecycle.onSuspend(getState) | scopes: none
+- lifecycle.onSuspend(getState, { work }) | scopes: none
   - Returns: off function
-  - Keep the viewer's place: Twinkle calls getState() for a small snapshot whenever the app is hidden, goes to the background, or every so often while in use, and hands it back the next time the app starts.
+  - Keep the viewer's place: Twinkle calls getState() for a small snapshot whenever the app is hidden, goes to the background, or every so often while in use. A return gets all of it back; a new visit gets only the keys listed in work.
   - Phones keep few apps loaded: an app that is not on screen can be unloaded at any time (3D apps right away), and the browser can kill the whole tab. Without a snapshot the viewer starts over.
-  - getState() returns a plain JSON object of at most 1 MB and must be quick (a 1.5 s budget, sync or a promise). Save what is needed to put the viewer back: level, position, score in play, the open view, unsaved edits, a quiz in progress.
-  - One handler per app; registering again replaces it. Long-term saves (collections, completed progress) still belong in Twinkle.privateDb.
-  - After a restart with a saved place, Twinkle keeps that place until the viewer does something in the app (a tap or key): snapshots taken while the app is still loading or waiting on a CONTINUE screen are not sent. Call saveNow() if the app changes the place on its own before that.
-  - Example: Twinkle.app.lifecycle.onSuspend(() => ({ level, hp, x: player.x, y: player.y, inventory }));
+  - Return or new visit: a start is a RETURN when the snapshot was taken in the same browser tab less than 30 minutes before (the phone unloaded the app, a reload, a quick switch away) and gets the whole snapshot back. Anything else is a NEW VISIT (the next day, after a long gap, a new tab): the app opens at its start, at the top, and gets back only the keys listed in work.
+  - work: the top-level snapshot keys that are unfinished work the viewer would be sorry to lose: a game or level in play, a half-written answer or draft, an unsaved drawing, a quiz in progress. Use work: true when the whole snapshot is that. Leave out where the viewer was looking (scroll position, open tab or view, selected article): it only comes back on a return. With no work option a new visit starts fresh.
+  - When the work is done (level won, answer sent, drawing saved) return that key as null: the next visit then starts fresh.
+  - getState() returns a plain JSON object of at most 1 MB and must be quick (a 1.5 s budget, sync or a promise). Save ids and small values, not whole data sets.
+  - One handler per app; registering again replaces it (with its work option). Long-term saves (collections, completed progress, settings) still belong in Twinkle.privateDb.
+  - After a restart with a saved place, Twinkle keeps that place until the viewer does something in the app (a tap, key or wheel scroll): snapshots taken while the app is still loading or waiting on a CONTINUE screen are not sent. Call saveNow() if the app changes the place on its own before that.
+  - Example: Twinkle.app.lifecycle.onSuspend(() => ({ scrollY: Math.round(window.scrollY), tab, game: inPlay ? { level, hp, x: player.x, y: player.y } : null }), { work: ['game'] });
 - async lifecycle.getResumeState() | scopes: none
-  - Returns: { state, savedAt, reason } or null
-  - At startup, the snapshot this viewer's last session of the app left behind (after an unload, a tab reload or crash), or null.
+  - Returns: { kind: 'return' | 'new_visit', state, savedAt, ageMs, reason } or null
+  - At startup, what the viewer's last session of the app left: on a return the whole snapshot, on a new visit only its work keys, or null to start fresh.
   - Resolves once, early; await it before drawing the first screen so the viewer does not see a fresh start flash by.
-  - Check the snapshot's shape before using it: it can come from an older version of the app. Ignore what you do not recognise.
+  - kind 'return': the same browser tab within 30 minutes (unloaded, reloaded, quick switch): state is the whole snapshot, so put the viewer back exactly, scroll included. kind 'new_visit': state holds only the work keys; open at the start (top of the page, first tab) and bring the unfinished work back. null: nothing to restore, start fresh.
+  - Restore from whatever saved.state contains: Twinkle has already left the scroll and view out on a new visit, so the usual if (saved) restore(saved.state) is right for both kinds. Check kind only to show something different, such as a 'Continue your game?' card on a new visit.
+  - Check the snapshot's shape before using it: it can come from an older version of the app, and on a new visit only work keys are there. Ignore what you do not recognise.
   - Closing the app with its Close button starts it fresh next time (no snapshot). The Build editor preview always starts fresh.
-  - Example: const saved = await Twinkle.app.lifecycle.getResumeState(); if (saved) restore(saved.state);
+  - Example: const saved = await Twinkle.app.lifecycle.getResumeState(); if (saved) restore(saved.state); // scroll and view are only in state on a return
+- lifecycle.onResume(handler) | scopes: none
+  - Returns: off function
+  - Hear when the app comes back on screen without restarting (Twinkle kept it loaded, or the browser froze the page and thawed it): handler({ kind: 'return' | 'new_visit', awayMs }).
+  - Same rule as a restart: away less than 30 minutes is a return (leave everything as it is); longer is a new visit, so do what a fresh start would: back to the start and the top, unfinished work kept.
+  - Called each time the app is back on screen after being hidden or in the background; not at startup (use getResumeState() there).
+  - Example: Twinkle.app.lifecycle.onResume(({ kind }) => { if (kind === 'new_visit') { openFrontPage(); window.scrollTo(0, 0); } });
 - async lifecycle.saveNow() | scopes: none
   - Returns: true once Twinkle has the snapshot, false otherwise
   - Take a snapshot right now, e.g. at a checkpoint or after an important step.
@@ -971,10 +982,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,25 +1017,29 @@ 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, tag, 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).
+  - tag is 'explorer' on web chat from someone walking Twinkle World right now (Twinkle MC Explorers): show them as Explorer instead of Web (in game: [Explorer] name). Otherwise null.
   - 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, tag, 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.
+  - tag is 'explorer' on web chat from someone walking Twinkle World right now (Twinkle MC Explorers): show them as Explorer instead of Web (in game: [Explorer] name). Otherwise null.
   - 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, tag, 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.
   - Send only on a user action (Enter or Send); never automatically.
+  - tag is 'explorer' on web chat from someone walking Twinkle World right now (Twinkle MC Explorers): show them as Explorer instead of Web (in game: [Explorer] name). Otherwise null.
   - Example: await Twinkle.minecraft.sendChat({ text: 'Hi from the website!' });
 - async muteChatUser({ userId, muted }) | scopes: content:write
   - Returns: { userId, muted }
@@ -1053,6 +1069,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 +1100,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 +1234,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 +1267,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