@stage5/lumine 0.3.14 → 0.3.16

package/lib/admin-owner-trace.js

@@ -0,0 +1,160 @@
+// `lumine admin owner-trace`: the owner's client trace from Mikey's own
+// devices (routes, Home feed card opens, scroll-anchor restores, content-page
+// scroll positions, window errors), read when he reports a UI issue. Read-only;
+// no daily run needed. The server keeps 30 days.
+
+export const OWNER_TRACE_USAGE =
+  "Usage: lumine admin owner-trace [--since 2h|30m|3d|<iso>|<unix>] [--type route,feed-open,scroll-anchor,content-scroll,error,...] [--path <substring>] [--limit 300] [--json].";
+
+const MAX_LIMIT = 2000;
+
+function validationError(message) {
+  const error = new Error(message);
+  error.code = "CLI_ADMIN_CLI_VALIDATION";
+  return error;
+}
+
+function normalizeSince(value) {
+  const raw = String(value || "").trim();
+  if (!raw) return "2h";
+  if (/^\d+\s*[smhd]$/i.test(raw) || /^\d{9,14}$/.test(raw)) {
+    return raw.replace(/\s+/g, "");
+  }
+  const parsed = Date.parse(raw);
+  if (!Number.isFinite(parsed)) {
+    throw validationError(
+      "--since must look like 30m, 2h, 3d, an ISO date or a unix time.",
+    );
+  }
+  return String(Math.floor(parsed / 1000));
+}
+
+export function buildOwnerTraceOperation(options) {
+  const limitRaw = options.adminLimit;
+  let limit = 300;
+  if (limitRaw !== null && limitRaw !== undefined && limitRaw !== "") {
+    limit = Number(String(limitRaw).trim());
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > MAX_LIMIT) {
+      throw validationError(`--limit must be an integer 1-${MAX_LIMIT}.`);
+    }
+  }
+  const query = new URLSearchParams();
+  query.set("since", normalizeSince(options.adminSince));
+  query.set("limit", String(limit));
+  if (options.adminType) query.set("type", String(options.adminType));
+  if (options.adminPath) query.set("path", String(options.adminPath));
+  return {
+    name: "owner-trace.read",
+    method: "GET",
+    path: `/cli/admin/owner-trace?${query.toString()}`,
+    body: undefined,
+    mutates: false,
+    requiresRun: false,
+  };
+}
+
+function pad(value, size) {
+  return String(value).padStart(size, "0");
+}
+
+function formatClock(ms) {
+  const date = new Date(ms);
+  return `${pad(date.getHours(), 2)}:${pad(date.getMinutes(), 2)}:${pad(date.getSeconds(), 2)}.${pad(date.getMilliseconds(), 3)}`;
+}
+
+function formatDay(ms) {
+  const date = new Date(ms);
+  return `${date.getFullYear()}-${pad(date.getMonth() + 1, 2)}-${pad(date.getDate(), 2)}`;
+}
+
+function pairs(data, skip = []) {
+  return Object.entries(data || {})
+    .filter(([key, value]) => !skip.includes(key) && value !== undefined && value !== null && value !== "")
+    .map(([key, value]) => `${key}=${typeof value === "object" ? JSON.stringify(value) : value}`)
+    .join(" ");
+}
+
+function describeSession(data = {}, path = "") {
+  const parts = [
+    data.version ? `v${data.version}` : "",
+    data.vw && data.vh ? `${data.vw}x${data.vh}${data.dpr ? ` @${data.dpr}x` : ""}` : "",
+    data.vvh ? `visual ${data.vvh}h` : "",
+    data.platform || "",
+    data.mobile ? "mobile" : "",
+    data.standalone ? "standalone (PWA)" : "browser tab",
+    data.touch ? `touch ${data.touch}` : "",
+  ].filter(Boolean);
+  if (path) parts.push(`at ${path}`);
+  return `${parts.join(" · ")}${data.ua ? `\n      ua: ${data.ua}` : ""}`;
+}
+
+export function describeOwnerTraceEvent(event) {
+  const data = event.data || {};
+  switch (event.type) {
+    case "route": {
+      const feed = data.feedNav
+        ? ` · feedNav ${data.feedNav.ct}:${data.feedNav.id}${data.feedNav.action ? ` ${data.feedNav.action}` : ""}`
+        : "";
+      const intent = data.feedIntent ? ` · intent ${data.feedIntent}` : "";
+      const otherKeys = (data.stateKeys || []).filter(
+        (key) => key !== "homeFeedNavigation" && key !== "homeFeedActionIntent",
+      );
+      return `${data.nav || "?"}${data.from ? ` from ${data.from}` : ""}${feed}${intent}${otherKeys.length ? ` · state ${otherKeys.join(",")}` : ""}${data.hash ? ` · ${data.hash}` : ""}`;
+    }
+    case "feed-open":
+      return `${data.action || "open"} ${data.ct}:${data.id}${data.via ? ` via ${data.via}` : ""}${data.el ? ` (${data.el})` : ""}${data.to ? ` → ${data.to}` : ""}${data.pos ? ` · card #${data.pos}` : ""}${data.surface && data.surface !== "home" ? ` · ${data.surface}` : ""}`;
+    case "scroll-anchor":
+      return `${data.e || "?"} ${pairs(data, ["e"])}`.trim();
+    case "content-scroll":
+      return `${data.phase} ${data.ct}:${data.id} scrollTop=${data.st} height=${data.sh} viewport=${data.vh}`;
+    case "error":
+    case "rejection":
+      return `${data.msg || "(no message)"}${data.src ? ` (${data.src}:${data.line}:${data.col})` : ""}${data.status ? ` HTTP ${data.status}` : ""}`;
+    default:
+      return pairs(data);
+  }
+}
+
+export function formatOwnerTrace(data) {
+  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 ? " · older events cut off (raise --limit or narrow --since)" : ""}`,
+  );
+  if (!events.length) {
+    lines.push("Nothing recorded in this window.");
+    return lines;
+  }
+  let day = "";
+  let session = "";
+  for (const event of events) {
+    const ms = Number(event.clientTime) || Number(event.serverTime) * 1000;
+    const eventDay = formatDay(ms);
+    if (eventDay !== day) {
+      day = eventDay;
+      lines.push(`── ${day}`);
+    }
+    if (event.sessionId !== session) {
+      session = event.sessionId;
+      if (event.type !== "session") {
+        lines.push(`  · session ${String(session).slice(0, 8)} (continued)`);
+      }
+    }
+    if (event.type === "session") {
+      lines.push(
+        `  ${formatClock(ms)}  ── session ${String(session).slice(0, 8)} · ${describeSession(event.data, event.path)}`,
+      );
+      continue;
+    }
+    lines.push(
+      `  ${formatClock(ms)}  ${event.type.padEnd(14)} ${event.path || "-"}  ${describeOwnerTraceEvent(event)}`.trimEnd(),
+    );
+  }
+  return lines;
+}
+
+export function printOwnerTrace(data) {
+  for (const line of formatOwnerTrace(data)) console.log(line);
+}

package/lib/admin.js

@@ -33,6 +33,10 @@ import {
   runManagedBuildReview,
 } from "./build-review.js";
 import { runAdminRuntimeLogWorkflow } from "./admin-runtime-logs.js";
+import {
+  buildOwnerTraceOperation,
+  printOwnerTrace,
+} from "./admin-owner-trace.js";
 import {
   dailyRunGather,
   dailyRunProgress,
@@ -285,7 +289,7 @@ function buildApprovalOperation({ action, target, options }) {
 // Code agent passes wrote (no model is called), then review what they could
 // not settle (Mikey 2026-10-06: bulk AI work runs on Claude Code agents).
 const ENGLISH_USAGE =
-  "Use: lumine admin english import <verdicts.json> --pass a|b | adjudicate <verdicts.json> | add-questions <questions.json> | relevel <moves.json> | summary | review [--limit <n>] | accept|retire <questionId> [--reason <text>] | retag <questionId> --skill <code> [--reason <text>]";
+  "Use: lumine admin english import <verdicts.json> --pass a|b | adjudicate <verdicts.json> | add-questions <questions.json> | relevel <moves.json> | mastery <userId> --reason <why> | backfill-distractors | summary | review [--limit <n>] | accept|retire <questionId> [--reason <text>] | retag <questionId> --skill <code> [--reason <text>]";
 const ENGLISH_IMPORT_MAX = 500;
 
 function buildEnglishOperation({ action, target, options }) {
@@ -320,6 +324,20 @@ function buildEnglishOperation({ action, target, options }) {
   if (action === "summary") {
     return readOperation("english.summary", "/cli/admin/english/tag-summary", { requiresRun: false });
   }
+  // One learner's per-skill mastery and the sentences a report may use.
+  // Private learner data: a reason is required and every read is audited.
+  if (action === "mastery") {
+    const userId = String(target || "");
+    const reason = String(options.adminReason || "").trim();
+    if (!/^\d+$/.test(userId) || reason.length < 8 || reason.length > 500) throw cliValidationError(ENGLISH_USAGE);
+    // POST: the reason travels in the body, never in a URL that access logs keep.
+    // A read, not a write: writes save their full response as a receipt file,
+    // and a child's learning data must never be left on disk.
+    return { ...bodyReadOperation("english.mastery", "POST", "/cli/admin/english/mastery", { userId: Number(userId), reason }), requiresRun: false, timeoutMs: 60000 };
+  }
+  if (action === "backfill-distractors") {
+    return writeOperation("english.backfill_distractors", "POST", "/cli/admin/english/backfill-distractors", {}, { requiresRun: false, timeoutMs: 300000 });
+  }
   if (action === "review" && !target) {
     return readOperation("english.review", withQuery("/cli/admin/english/review", { limit: limitOf(100, 20) }), { requiresRun: false });
   }
@@ -2005,6 +2023,11 @@ export function parseAdminOperation(options) {
   const [namespace = "", action = "", target = "", extra = ""] =
     options.positional;
 
+  // The owner's client trace (admin-owner-trace.js); read-only, no run.
+  if (namespace === "owner-trace") {
+    return buildOwnerTraceOperation(options);
+  }
+
   if (namespace === "correction" || namespace === "corrections") {
     if (!action || action === "status") {
       return readOperation(
@@ -2074,7 +2097,11 @@ export function parseAdminOperation(options) {
           `An identity-inspection reason must be at most ${MAX_IDENTITY_INSPECTION_REASON_LENGTH} characters.`,
         );
       }
-      return writeOperation(
+      // A read: writes keep their full response as a receipt file under
+      // ./work/lumine-admin, and private identity evidence must never be left
+      // on disk by default. The server still audits who looked, when and why
+      // (one row per call). `--output <file>` saves a 0600 copy on purpose.
+      return bodyReadOperation(
         "identity.inspect",
         "POST",
         "/cli/admin/identity/inspect",
@@ -2100,17 +2127,20 @@ export function parseAdminOperation(options) {
         `A network-evidence reason must be at most ${MAX_IDENTITY_INSPECTION_REASON_LENGTH} characters.`,
       );
     }
-    return writeOperation(
-      "identity.network",
-      "POST",
-      "/cli/admin/identity/network",
-      {
-        target: networkTarget,
-        reason,
-        includePrivateEvidence: options.adminIncludePrivateEvidence === true,
-      },
-      { requiresRun: false },
-    );
+    // A read for the same reason as identity inspect: no receipt on disk.
+    return {
+      ...bodyReadOperation(
+        "identity.network",
+        "POST",
+        "/cli/admin/identity/network",
+        {
+          target: networkTarget,
+          reason,
+          includePrivateEvidence: options.adminIncludePrivateEvidence === true,
+        },
+      ),
+      requiresRun: false,
+    };
   }
 
   if (namespace === "economy" && action === "trace") {
@@ -5878,6 +5908,21 @@ function printEnglishResult({ operation, data }) {
     console.log(`Pass ${data.pass}: ${data.stored} stored of ${data.received} (${data.invalid} invalid, ${data.unknownQuestion} unknown questions) · ${data.decided} decided: ${data.auto} accepted automatically, ${data.review} for review (${Object.entries(data.reasons || {}).map(([k, v]) => `${k} ${v}`).join(", ") || "-"})`);
     return;
   }
+  if (operation.name === "english.mastery") {
+    console.log(`User #${data.userId} · last ${data.windowDays} days · ${data.responses} honest answers · ${data.skillsSeen} skills seen (mastery = ${Math.round(data.target * 100)}% right on the first try)`);
+    const label = { fact: "facts only", focus: "NEXT FOCUS", gap: "CLEAR GAP", strength: "strength", "clear-strength": "CLEAR STRENGTH" };
+    if (!data.reportable?.length) console.log("Nothing reportable yet: no skill has enough evidence.");
+    for (const r of data.reportable || []) {
+      console.log(`  [${label[r.kind] || r.kind}] ${r.nameEn} · ${r.correct}/${r.responses} first try · ${r.items} questions · ${r.days} days · P(below) ${r.pBelow.toFixed(2)}`);
+      console.log(`      report may say: ${r.wordingEn}`);
+    }
+    if (data.practiceOnly?.length) console.log(`  practice only (not enough evidence yet): ${data.practiceOnly.map((s) => `${s.nameEn} ${s.responses}`).join(" · ")}`);
+    return;
+  }
+  if (operation.name === "english.backfill_distractors") {
+    console.log(`Wrong-choice labels restored on ${data.filled} of ${data.candidates} agent-written questions.`);
+    return;
+  }
   if (operation.name === "english.adjudicate") {
     console.log(`Adjudicated ${data.received}: ${data.keep} kept · ${data.fix} fixed (new versions) · ${data.retire} retired · ${data.skipped?.length || 0} skipped${data.skipped?.length ? ` (${data.skipped.slice(0, 5).map((s) => `${s.ref}: ${s.why}`).join("; ")})` : ""}`);
     return;
@@ -6061,6 +6106,10 @@ function printAdminResult({ operation, result }) {
     printRewardBankReport(data);
     return;
   }
+  if (operation.name === "owner-trace.read") {
+    printOwnerTrace(data);
+    return;
+  }
   if (operation.name.startsWith("reward-bank.")) {
     if (operation.name === "reward-bank.seed") {
       console.log(

package/lib/build-review.js

@@ -536,7 +536,7 @@ export async function runInteractionSteps({
   };
 }
 
-function findChromeExecutable(explicitPath = "") {
+export function findChromeExecutable(explicitPath = "") {
   const candidates = [
     explicitPath,
     process.env.CHROME_PATH,
@@ -589,7 +589,7 @@ function delay(milliseconds) {
   return new Promise((resolve) => setTimeout(resolve, milliseconds));
 }
 
-function createCdpPipe(child) {
+export function createCdpPipe(child) {
   const commandPipe = child.stdio[3];
   const eventPipe = child.stdio[4];
   if (!commandPipe || !eventPipe) {

package/lib/commands.js

@@ -2371,6 +2371,8 @@ export function parseArgs(args) {
     "json",
     "keepAssets",
     "noBrowser",
+    "noSave",
+    "poolEvents",
     "includeComments",
     "anyoneCanReward",
     "full",
@@ -2493,6 +2495,8 @@ export function parseArgs(args) {
     adminPostedAfter: raw.postedAfter ? String(raw.postedAfter) : "",
     adminApprove: raw.approve ? String(raw.approve) : "",
     adminSinceRun: Boolean(raw.sinceRun),
+    adminSince: raw.since ? String(raw.since) : "",
+    adminPath: raw.path ? String(raw.path) : "",
     adminIncludeLegacy: Boolean(raw.includeLegacy),
     adminIncludePrivateEvidence: parseBoolean(
       raw.includePrivateEvidence,
@@ -2546,6 +2550,10 @@ export function parseArgs(args) {
     sponsorOutcome: raw.outcome ? String(raw.outcome) : "",
     sponsorFailureReason: raw.reason ? String(raw.reason) : "",
     sponsorNoLeaseKeeper: Boolean(raw.noLeaseKeeper),
+    sponsorPoolEvents: Boolean(raw.poolEvents),
+    sponsorNotifyCommand: raw.notify ? String(raw.notify) : "",
+    sponsorLoopMinutes: raw.minutes ?? "",
+    sponsorNoSave: Boolean(raw.noSave),
     sponsorHoldEverySeconds: raw.holdEverySeconds,
     sponsorUpdateFile: raw.file ? String(raw.file) : "",
     sponsorUpdatePhase: raw.phase ? String(raw.phase) : "",
@@ -2920,7 +2928,8 @@ export function printHelp() {
   lumine sponsor agreement|apply|status|withdraw
   lumine sponsor capacity [--concurrency <n>] [--helpers <n>] [--daily-limit <n>] [--weekly-limit <n>]
   lumine sponsor duty start [--provider <codex|claude-code>] --model <name> --effort <level> [--service-tier <tier>]
-  lumine sponsor duty watch [--wait-ms <ms>] [--json]
+  lumine sponsor duty watch [--wait-ms <ms>] [--pool-events] [--json]
+  lumine sponsor duty watch-loop [--minutes <n>] [--pool-events] [--notify <command>] [--json]
   lumine sponsor duty pause|resume|stop
   lumine sponsor job status|pulse|begin <job-id>
   lumine sponsor job update <job-id> --file <path> [--phase <name>]
@@ -2933,6 +2942,7 @@ export function printHelp() {
   lumine sponsor job rename <job-id> <title>
   lumine sponsor job describe <job-id> <text>
   lumine sponsor job update <job-id> --file <path> --kind question
+  lumine sponsor job preview <job-id> [--no-save] [--no-browser] [--wait-ms <ms>]
   lumine sponsor job complete <job-id> --summary <text>
   lumine sponsor job fail <job-id> --reason <text>
   lumine sponsor jobs
@@ -2991,8 +3001,8 @@ export function printHelp() {
   lumine thumbnail generate ["<prompt>"] --model <gpt-image-2.5-flare|gpt-image-2.5-sunburst|gpt-image-2|nano-banana>
   lumine doctor runtime-assets
   lumine admin identity list|status|use <zero|ciel|auto> [--json]
-  lumine admin identity inspect <user-id|username> --reason <management-reason> [--include-private-evidence] [--json]
-  lumine admin identity network <user-id|username> --reason <management-reason> [--include-private-evidence] [--json]   (addresses this account used; who shares the small ones)
+  lumine admin identity inspect <user-id|username> --reason <management-reason> [--include-private-evidence] [--output <file>] [--json]   (nothing kept on disk unless --output; that copy is 0600)
+  lumine admin identity network <user-id|username> --reason <management-reason> [--include-private-evidence] [--output <file>] [--json]   (addresses this account used; who shares the small ones)
   lumine admin economy trace <user-id|username> --reason <management-reason> [--days <1..30>] [--json]
   lumine admin rescue wordle-audit --reason <management-reason> [--days <1..30>] [--json]
   lumine admin ai-bucket create --label <name> --note <text> [--json]
@@ -3019,7 +3029,7 @@ export function printHelp() {
   lumine admin review list [--type rewards|project|storage|cardcraft] [--status queue|pending|approved|rejected|all] [--cursor <c>] | show <type:id> [--dir <path>] | approve <type:id> [--config <rules.json>] [--size <500MB|1GB|2GB|n MB>] [--reason <text>] | reject|revoke <type:id> [--reason <text>] | propose rewards:<id> --dir <edited-snapshot> --config <rules.json>
   lumine admin approvals list [--status pending|approved|rejected|all] [--type dob|mentor|meetup] | show <id> | approve <id> [--reason <text>] | reject <id> [--reason <text>] | supermod <id> [--reason <text>]   (management approvals with evidence: birthdates, teacher signups, meetups)
   lumine admin teachers audit [--limit <1-100>] | revoke <userId> --reason <text>   (approved teachers, riskiest first; revoke removes the status cleanly)
-  lumine admin english import <verdicts.json> --pass a|b | adjudicate <file> | add-questions <file> | relevel <file> | summary | review [--limit <n>] | accept|retire <questionId> | retag <questionId> --skill <code>   (English skill tags and bank upkeep for Grammarbles; content written by Claude Code agents)
+  lumine admin english import <verdicts.json> --pass a|b | adjudicate <file> | add-questions <file> | relevel <file> | mastery <userId> --reason <why> | backfill-distractors | summary | review [--limit <n>] | accept|retire <questionId> | retag <questionId> --skill <code>   (English skill tags and bank upkeep for Grammarbles; content written by Claude Code agents)
   lumine admin reward-review list [--status pending|approved|all] [--cursor <id>] [--json]
   lumine admin cardcraft-review list [--status pending|approved|all] [--cursor <id>] | show <id> | approve|reject|revoke <id> [--reason <text>]
   lumine admin storage list [--status pending|approved|rejected|all] [--cursor <id>] | show <user-id-or-username> | approve <request-id> [--size <500MB|1GB|2GB|n MB>] [--reason <text>] | reject <request-id> [--reason <text>] | grant <user-id-or-username> --size <500MB|1GB|2GB|n MB> [--reason <text>]
@@ -3071,6 +3081,7 @@ export function printHelp() {
   lumine admin reward-bank coverage <buildId> [--max-step 3] [--json]
   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] [--path <substring>] [--limit 300] [--json]   (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; kept 30 days)
   lumine admin comment draft <target> [--type subject|comment|build|aiStory|dailyReflection] [--file <comment.md>] [--review-receipt <review.json>|--reviewed-version <id> --reviewed-via runtime|code] [--review-context <context.json>] [--identity zero|ciel|auto] [--json]
   lumine admin comment reply comment:<id> [--file <reply.md>] [--reviewed-version <id> --reviewed-via runtime|code] [--review-context <context.json>] [--identity zero|ciel|auto] [--json]
   lumine admin comment post --draft-id <id> [--json]