@stage5/lumine 0.2.76 → 0.2.79

package/lib/admin.js

@@ -31,8 +31,14 @@ import {
   runManagedBuildReview,
 } from "./build-review.js";
 import { runAdminRuntimeLogWorkflow } from "./admin-runtime-logs.js";
-import { readApprovedFeaturedPlan, runFeaturedWorkflow } from "./admin-featured.js";
-import { FEATURED_HISTORY_BATCH_SIZE, runBatchedFeaturedHistory } from "./admin-featured-history.js";
+import {
+  readApprovedFeaturedPlan,
+  runFeaturedWorkflow,
+} from "./admin-featured.js";
+import {
+  FEATURED_HISTORY_BATCH_SIZE,
+  runBatchedFeaturedHistory,
+} from "./admin-featured-history.js";
 
 const MAX_EDITORIAL_FILE_BYTES = 256 * 1024;
 const MAX_COMPOSED_TEXT_FILE_BYTES = 64 * 1024;
@@ -133,6 +139,80 @@ function readBuildReviewContextFile(filePath) {
 const MAX_REWARD_CONFIG_FILE_BYTES = 256 * 1024;
 const REWARD_REVIEW_STATUSES = ["pending", "approved", "all"];
 const REWARD_REVIEW_DECISIONS = ["approve", "reject", "revoke"];
+const REWARD_PROPOSAL_MAX_FILES = 500;
+const REWARD_PROPOSAL_MAX_BYTES = 5 * 1024 * 1024;
+const REWARD_PROPOSAL_SKIPPED_DIRS = new Set([
+  ".git",
+  "node_modules",
+  ".lumine",
+  ".twinkle",
+]);
+
+// Reads a reviewer's edited copy of a reward-review snapshot (a directory
+// written by `show --dir`, then edited) back into project files for
+// `reward-review propose`. Text files only; dotfiles and tool directories
+// are skipped; paths are confined to the directory.
+export function readRewardProposalDirectory(directory) {
+  const requested = String(directory || "").trim();
+  if (!requested) {
+    throw cliValidationError(
+      "Pass the edited snapshot directory with --dir <path>.",
+    );
+  }
+  const root = path.resolve(requested);
+  let rootStat;
+  try {
+    rootStat = lstatSync(root);
+  } catch {
+    throw cliValidationError(`--dir ${root} does not exist.`);
+  }
+  if (!rootStat.isDirectory()) {
+    throw cliValidationError(`--dir ${root} must be a directory.`);
+  }
+  const realRoot = realpathSync(root);
+  const files = [];
+  let bytes = 0;
+  const walk = (dir) => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (entry.name.startsWith(".") || REWARD_PROPOSAL_SKIPPED_DIRS.has(entry.name))
+        continue;
+      const fullPath = path.join(dir, entry.name);
+      if (entry.isSymbolicLink()) {
+        throw cliValidationError(
+          `Refusing to read symlink inside the proposal directory: ${fullPath}`,
+        );
+      }
+      if (entry.isDirectory()) {
+        walk(fullPath);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      const buffer = readFileSync(fullPath);
+      if (buffer.includes(0)) {
+        throw cliValidationError(
+          `${fullPath} is not a text file. Twinkle project files must be UTF-8 text; media belongs in build assets.`,
+        );
+      }
+      bytes += buffer.length;
+      const relative = path.relative(realRoot, fullPath).split(path.sep).join("/");
+      files.push({ path: `/${relative}`, content: buffer.toString("utf8") });
+    }
+  };
+  walk(realRoot);
+  if (files.length === 0) {
+    throw cliValidationError(`--dir ${root} holds no project files.`);
+  }
+  if (files.length > REWARD_PROPOSAL_MAX_FILES) {
+    throw cliValidationError(
+      `A proposal may carry at most ${REWARD_PROPOSAL_MAX_FILES} files.`,
+    );
+  }
+  if (bytes > REWARD_PROPOSAL_MAX_BYTES) {
+    throw cliValidationError("A proposal may carry at most 5 MB of files.");
+  }
+  files.sort((a, b) => a.path.localeCompare(b.path));
+  return files;
+}
 
 // The reviewer's earning rules for one Build reward approval: budgets plus
 // server-verified numeric-quiz rules keyed by the rule IDs the app source
@@ -166,7 +246,7 @@ export function readRewardConfigFile(filePath) {
   }
   if (!Array.isArray(parsed.rules) || parsed.rules.length === 0) {
     throw cliValidationError(
-      "Approval needs at least one earning rule in rules[] (id, title, xp, coins, verifier: \"numeric-quiz\", questions[{prompt, answer}] and/or sets[{from, to?, questions}], optional maxAttempts (null = unlimited) and retry {xpPercent, coinsPercent}).",
+      'Approval needs at least one earning rule in rules[] (id, title, xp, coins, verifier: "numeric-quiz", questions[{prompt, answer}] and/or sets[{from, to?, questions}], optional maxAttempts (null = unlimited) and retry {xpPercent, coinsPercent}).',
     );
   }
   return parsed;
@@ -178,18 +258,26 @@ export function readRewardConfigFile(filePath) {
 export function writeRewardReviewSnapshot({ directory, files }) {
   const requested = String(directory || "").trim();
   if (!requested) {
-    throw cliValidationError("Pass a new or empty directory with --dir <path>.");
+    throw cliValidationError(
+      "Pass a new or empty directory with --dir <path>.",
+    );
   }
   const root = path.resolve(requested);
   if (root === path.resolve("/")) {
-    throw cliValidationError("Pass a new or empty directory with --dir <path>.");
+    throw cliValidationError(
+      "Pass a new or empty directory with --dir <path>.",
+    );
   }
   // The snapshot must land in a directory that holds nothing else, so the
   // reviewer never reads stale files from another review or clobbers a real
   // workspace, and so no pre-existing symlink can redirect a write.
   if (existsSync(root)) {
     const stat = lstatSync(root);
-    if (stat.isSymbolicLink() || !stat.isDirectory() || readdirSync(root).length) {
+    if (
+      stat.isSymbolicLink() ||
+      !stat.isDirectory() ||
+      readdirSync(root).length
+    ) {
       throw cliValidationError(
         `--dir ${root} must be a new or empty directory (not a symlink, file, or populated folder).`,
       );
@@ -382,7 +470,12 @@ export async function adminCommand(options) {
         viewFilter,
       });
     if (operation.featuredWorkflow) {
-      result = await runFeaturedWorkflow({ options, operation, authToken: auth.token, runId });
+      result = await runFeaturedWorkflow({
+        options,
+        operation,
+        authToken: auth.token,
+        runId,
+      });
     } else if (operation.name === "build.review") {
       result = await runManagedBuildReview({
         options,
@@ -409,9 +502,12 @@ export async function adminCommand(options) {
           "Use --resume with the scan checkpoint instead of combining --all with --cursor.",
         );
       }
-      const paginate = operation.name === "featured.history" &&
-        operation.pagination.filters.subjectIds.length > FEATURED_HISTORY_BATCH_SIZE
-        ? runBatchedFeaturedHistory : runAutomaticPagination;
+      const paginate =
+        operation.name === "featured.history" &&
+        operation.pagination.filters.subjectIds.length >
+          FEATURED_HISTORY_BATCH_SIZE
+          ? runBatchedFeaturedHistory
+          : runAutomaticPagination;
       result = await paginate({
         options,
         operation,
@@ -443,11 +539,16 @@ export async function adminCommand(options) {
   } catch (error) {
     if (operation.name === "runtime.evidence" && error.status === 404) {
       error.code = "CLI_ADMIN_RUNTIME_EVIDENCE_NOT_DEPLOYED";
-      error.message = "The runtime evidence route is not deployed on the requested host. Evidence is unknown; deploy the matching API and activate the collector in an authorized primary-generation release. No restart or host substitution was attempted.";
+      error.message =
+        "The runtime evidence route is not deployed on the requested host. Evidence is unknown; deploy the matching API and activate the collector in an authorized primary-generation release. No restart or host substitution was attempted.";
       error.data = {
         ok: false,
         status: "unavailable",
-        error: { code: error.code, message: error.message, details: { httpStatus: 404 } },
+        error: {
+          code: error.code,
+          message: error.message,
+          details: { httpStatus: 404 },
+        },
       };
     }
     if (operation.featuredWorkflow && error.featuredProgress) {
@@ -456,12 +557,18 @@ export async function adminCommand(options) {
         ok: false,
         status: "partial_failure",
         error: {
-          code: serverError?.code || error.code || "LUMINE_ADMIN_FEATURED_WORKFLOW_FAILED",
+          code:
+            serverError?.code ||
+            error.code ||
+            "LUMINE_ADMIN_FEATURED_WORKFLOW_FAILED",
           message: error.message,
           details: {
-            ...(serverError && typeof serverError === "object" ? serverError.details : {}),
+            ...(serverError && typeof serverError === "object"
+              ? serverError.details
+              : {}),
             ...error.featuredProgress,
-            retryInstruction: "Resume the exact command with --resume; confirmed items are not replayed.",
+            retryInstruction:
+              "Resume the exact command with --resume; confirmed items are not replayed.",
           },
         },
       };
@@ -649,7 +756,11 @@ async function finishAdminOutput({ options, operation, result }) {
     operation.name !== "news.claim" &&
     operation.name !== "post.skip-batch"
   ) {
-    writeAdminResultOutput({ filePath: options.adminOutput, result, operation });
+    writeAdminResultOutput({
+      filePath: options.adminOutput,
+      result,
+      operation,
+    });
   }
   if (options.json) {
     if (paginationStorage) {
@@ -1098,8 +1209,16 @@ export function assertAdminOperationAllowedForRunScope({
 }) {
   if (runScope === "newspaper") {
     if (
-      ["news.status", "news.claim", "news.submit", "news.print", "daily-run.complete", "daily-run.fail"].includes(operation.name)
-    ) return;
+      [
+        "news.status",
+        "news.claim",
+        "news.submit",
+        "news.print",
+        "daily-run.complete",
+        "daily-run.fail",
+      ].includes(operation.name)
+    )
+      return;
     throw cliValidationError(
       `A newspaper-only run does not authorize ${operation.name}.`,
     );
@@ -1137,6 +1256,7 @@ function adminOperationRequiresRun(operation) {
       "escalation.list",
       "escalation.set",
       "notable.add",
+      "notable.remove",
       "notable.status",
       "runtime-logs.start",
       "runtime-logs.status",
@@ -1393,7 +1513,9 @@ export function parseAdminOperation(options) {
     if (action === "show" || action === "get") {
       const reviewId = parseRequiredInteger(target, "Reward review ID", 1);
       if (options.dir && !snapshotDir) {
-        throw cliValidationError("Pass a new or empty directory with --dir <path>.");
+        throw cliValidationError(
+          "Pass a new or empty directory with --dir <path>.",
+        );
       }
       return readOperation(
         "reward-review.show",
@@ -1405,6 +1527,32 @@ export function parseAdminOperation(options) {
         { requiresRun: false, reviewId, snapshotDir },
       );
     }
+    if (action === "propose") {
+      // Offer an edited copy of the snapshot as the condition of approval:
+      // the creator accepts (which publishes it) or declines (which rejects).
+      const reviewId = parseRequiredInteger(target, "Reward review ID", 1);
+      const reason = String(options.adminReason || "").trim();
+      if (reason.length > 1000) {
+        throw cliValidationError("--reason must be at most 1000 characters.");
+      }
+      if (!options.adminConfigFile) {
+        throw cliValidationError(
+          "lumine admin reward-review propose <id> needs --config <rules.json> (the rules the creator's acceptance publishes) and --dir <edited snapshot>.",
+        );
+      }
+      const files = readRewardProposalDirectory(options.dir);
+      return writeOperation(
+        "reward-review.propose",
+        "POST",
+        `/cli/admin/reward-reviews/${reviewId}/propose`,
+        {
+          files,
+          config: readRewardConfigFile(options.adminConfigFile),
+          reason,
+        },
+        { requiresRun: false, reviewId, fileCount: files.length },
+      );
+    }
     if (REWARD_REVIEW_DECISIONS.includes(action)) {
       const reviewId = parseRequiredInteger(target, "Reward review ID", 1);
       const reason = String(options.adminReason || "").trim();
@@ -1420,7 +1568,8 @@ export function parseAdminOperation(options) {
       if (action === "approve") {
         // Without --config the app's own proposal (rewards.json + sheet, frozen
         // in the request) is approved as it stands; --config replaces it.
-        if (options.adminConfigFile) body.config = readRewardConfigFile(options.adminConfigFile);
+        if (options.adminConfigFile)
+          body.config = readRewardConfigFile(options.adminConfigFile);
       } else if (options.adminConfigFile) {
         throw cliValidationError(
           "--config is only used with approve; rejections and revocations take --reason.",
@@ -1435,19 +1584,29 @@ export function parseAdminOperation(options) {
       );
     }
     throw cliValidationError(
-      "Usage: lumine admin reward-review list [--status pending|approved|all] [--cursor <id>] | show <id> [--dir <path>] | approve <id> [--config <rules.json>] [--reason <text>] | reject <id> --reason <text> | revoke <id> --reason <text>.",
+      "Usage: lumine admin reward-review list [--status pending|approved|all] [--cursor <id>] | show <id> [--dir <path>] | approve <id> [--config <rules.json>] [--reason <text>] | propose <id> --dir <edited-snapshot> --config <rules.json> [--reason <text>] | reject <id> --reason <text> | revoke <id> --reason <text>.",
     );
   }
 
   if (namespace === "reward-activity" || namespace === "reward-telemetry") {
     // Read-only claim telemetry for the daily run: no run lease, no mutation.
-    const days = options.adminDays ? parseRequiredInteger(options.adminDays, "--days", 1) : 7;
+    const date = options.adminDate
+      ? parseUtcDayKey(options.adminDate)
+      : undefined;
+    const days = options.adminDays
+      ? parseRequiredInteger(options.adminDays, "--days", 1)
+      : date
+        ? 1
+        : 7;
     if (days > 31) throw cliValidationError("--days must be at most 31.");
     return readOperation(
       "reward-activity.report",
       withQuery("/cli/admin/reward-activity", {
         days: String(days),
-        buildId: options.buildIdFlag ? String(parseRequiredInteger(options.buildIdFlag, "--build", 1)) : "",
+        date,
+        buildId: options.buildIdFlag
+          ? String(parseRequiredInteger(options.buildIdFlag, "--build", 1))
+          : "",
       }),
       { requiresRun: false },
     );
@@ -1623,9 +1782,7 @@ export function parseAdminOperation(options) {
       const runScope = parseDailyRunScope(options.adminScope || "full");
       const commentMode = parseCommentMode(options.commentMode || "off");
       if (runScope !== "full" && commentMode !== "off") {
-        throw cliValidationError(
-          "A scoped run requires --comment-mode off.",
-        );
+        throw cliValidationError("A scoped run requires --comment-mode off.");
       }
       return writeOperation(
         "daily-run.start",
@@ -1899,27 +2056,68 @@ export function parseAdminOperation(options) {
   if (namespace === "featured") {
     if (action === "comments") {
       if (!["scan", "acknowledge", "recommend", "report"].includes(target)) {
-        throw cliValidationError("Usage: featured comments scan|acknowledge|recommend|report --checkpoint <file>.");
+        throw cliValidationError(
+          "Usage: featured comments scan|acknowledge|recommend|report --checkpoint <file>.",
+        );
       }
-      if (options.adminAll || options.adminCursor || options.adminUnviewed || options.adminViewed || options.adminAfter) {
-        throw cliValidationError("The Featured review covers every comment; filtered or caller-supplied cursors are not supported.");
+      if (
+        options.adminAll ||
+        options.adminCursor ||
+        options.adminUnviewed ||
+        options.adminViewed ||
+        options.adminAfter
+      ) {
+        throw cliValidationError(
+          "The Featured review covers every comment; filtered or caller-supplied cursors are not supported.",
+        );
       }
-      return { ...writeOperation(`featured.comments.${target}`, "POST", "/cli/admin/subjects/featured/reviews", {}),
-        mutates: target !== "report", featuredWorkflow: target };
+      return {
+        ...writeOperation(
+          `featured.comments.${target}`,
+          "POST",
+          "/cli/admin/subjects/featured/reviews",
+          {},
+        ),
+        mutates: target !== "report",
+        featuredWorkflow: target,
+      };
     }
     if (action === "plan") {
-      if (!options.adminPostedAfter) throw cliValidationError("A Featured plan requires --posted-after <timestamp>.");
-      return writeOperation("featured.plan", "POST", "/cli/admin/subjects/featured/plan", {
-        removeIds: parseFeaturedSubjectIds(options.adminRemoveIds, "--remove-subject-ids"),
-        addIds: parseFeaturedSubjectIds(options.adminAddIds, "--add-subject-ids"),
-        ...(options.adminIds ? { finalIds: parseOrderedIds(options.adminIds) } : {}),
-        postedAfter: options.adminPostedAfter,
-      });
+      if (!options.adminPostedAfter)
+        throw cliValidationError(
+          "A Featured plan requires --posted-after <timestamp>.",
+        );
+      return writeOperation(
+        "featured.plan",
+        "POST",
+        "/cli/admin/subjects/featured/plan",
+        {
+          removeIds: parseFeaturedSubjectIds(
+            options.adminRemoveIds,
+            "--remove-subject-ids",
+          ),
+          addIds: parseFeaturedSubjectIds(
+            options.adminAddIds,
+            "--add-subject-ids",
+          ),
+          ...(options.adminIds
+            ? { finalIds: parseOrderedIds(options.adminIds) }
+            : {}),
+          postedAfter: options.adminPostedAfter,
+        },
+      );
     }
     if (action === "apply") {
       readApprovedFeaturedPlan(options.adminFile, options.adminApprove);
-      return { ...writeOperation("featured.apply", "POST", "/cli/admin/subjects/featured/plan/apply", {}),
-        featuredWorkflow: "apply" };
+      return {
+        ...writeOperation(
+          "featured.apply",
+          "POST",
+          "/cli/admin/subjects/featured/plan/apply",
+          {},
+        ),
+        featuredWorkflow: "apply",
+      };
     }
     if (action === "list") {
       return readOperation("featured.list", "/cli/admin/subjects/featured");
@@ -1930,10 +2128,17 @@ export function parseAdminOperation(options) {
         "--subject-ids",
       );
       if (subjectIds.length > 20_000) {
-        throw cliValidationError("Featured history accepts at most 20000 subject IDs per CLI scan.");
+        throw cliValidationError(
+          "Featured history accepts at most 20000 subject IDs per CLI scan.",
+        );
       }
-      if (subjectIds.length > FEATURED_HISTORY_BATCH_SIZE && !options.adminAll) {
-        throw cliValidationError("Pass --all to automatically batch history reads larger than 100 subjects.");
+      if (
+        subjectIds.length > FEATURED_HISTORY_BATCH_SIZE &&
+        !options.adminAll
+      ) {
+        throw cliValidationError(
+          "Pass --all to automatically batch history reads larger than 100 subjects.",
+        );
       }
       return readOperation(
         "featured.history",
@@ -2118,11 +2323,11 @@ export function parseAdminOperation(options) {
     );
   }
 
-  if (namespace === "notable" && action === "add") {
+  if (namespace === "notable" && ["add", "remove"].includes(action) && !extra) {
     const rawTarget = String(target || "").trim();
     if (!rawTarget) {
       throw cliValidationError(
-        "Usage: lumine admin notable add <userId|username> --note <text>.",
+        `Usage: lumine admin notable ${action} <userId|username> --note <text>.`,
       );
     }
     const body = /^\d+$/.test(rawTarget)
@@ -2133,7 +2338,9 @@ export function parseAdminOperation(options) {
     const note = String(options.note || "").trim();
     if (!note) {
       throw cliValidationError(
-        "Pass what made this user notable with --note <text>.",
+        action === "remove"
+          ? "Explain why this user should be removed with --note <text>."
+          : "Pass what made this user notable with --note <text>.",
       );
     }
     if (note.length > MAX_NOTABLE_NOTE_LENGTH) {
@@ -2143,8 +2350,8 @@ export function parseAdminOperation(options) {
     }
     body.note = note;
     return writeOperation(
-      "notable.add",
-      "POST",
+      `notable.${action}`,
+      action === "remove" ? "DELETE" : "POST",
       "/cli/admin/notable-users",
       body,
     );
@@ -2218,8 +2425,14 @@ export function parseAdminOperation(options) {
   }
 
   if (namespace === "runtime") {
-    if (action !== "evidence" || !["primary", "target"].includes(target) || extra) {
-      throw cliValidationError("Usage: lumine admin runtime evidence primary|target [--days 1..7].");
+    if (
+      action !== "evidence" ||
+      !["primary", "target"].includes(target) ||
+      extra
+    ) {
+      throw cliValidationError(
+        "Usage: lumine admin runtime evidence primary|target [--days 1..7].",
+      );
     }
     return readOperation(
       "runtime.evidence",
@@ -2233,7 +2446,8 @@ export function parseAdminOperation(options) {
   if (namespace === "runtime-logs") {
     if (
       (action === "start" || action === "status" || action === "read") &&
-      (!target || (action === "start" && ["primary", "target"].includes(target))) &&
+      (!target ||
+        (action === "start" && ["primary", "target"].includes(target))) &&
       !extra
     ) {
       if (
@@ -2679,7 +2893,9 @@ function featuredRotateOperation(options) {
     {
       removeIds,
       addIds,
-      ...(options.adminPostedAfter ? { postedAfter: options.adminPostedAfter } : {}),
+      ...(options.adminPostedAfter
+        ? { postedAfter: options.adminPostedAfter }
+        : {}),
     },
   );
 }
@@ -3398,7 +3614,9 @@ function printAdminEnergyBudget(energyBudget) {
       `AI Energy budget health, last completed UTC day ${headline.dayKey}: ${formatAdminUsd(headline.chargedUsd)} charged, ${formatAdminUsd(headline.overflowUsd)} overflow, ${headline.users} user(s), ${headline.recharges} recharge(s), ${headline.runs.total.runs} run(s), ${headline.telemetry.metrics.busy_refusal.count} busy refusal(s).`,
     );
   } else {
-    console.log("AI Energy budget health: no completed UTC day in the requested window.");
+    console.log(
+      "AI Energy budget health: no completed UTC day in the requested window.",
+    );
   }
   console.log(
     "day        | charged | overflow | users | rechg | runs | calls/run avg/p90 | $/run avg/p90 | stops chg/unchg | busy | telemetry rows",
@@ -3416,7 +3634,9 @@ function printAdminEnergyBudget(energyBudget) {
     console.log("Flags: none.");
     return;
   }
-  console.log(`Flags (${flags.length}) — record each as a carry-over todo and escalate; never auto-enforce:`);
+  console.log(
+    `Flags (${flags.length}) — record each as a carry-over todo and escalate; never auto-enforce:`,
+  );
   for (const flag of flags) {
     console.log(`  ${flag.dayKey} ${flag.code}: ${flag.message}`);
   }
@@ -3616,25 +3836,41 @@ function formatRewardReviewLine(review) {
 }
 
 // One reviewer-facing line per earning rule: amounts, what a later try pays,
-// how many tries, and which Korean days the dated sets cover.
+// how many tries, and which site days (UTC) the dated sets cover.
 export function formatRewardRuleLine(rule) {
-  const parts = [`rule ${rule.id}: ${rule.title} · ${rule.xp} XP + ${rule.coins} Coins`];
+  const parts = [
+    `rule ${rule.id}: ${rule.title} · ${rule.xp} XP + ${rule.coins} Coins`,
+  ];
   if (rule.verifier === "completion") {
-    parts.push(`completion · pays when the app reports it finished at least ${rule.minSeconds || 0}s after start · once per learner per day`);
+    parts.push(
+      `completion · pays when the app reports it finished at least ${rule.minSeconds || 0}s after start · once per learner per day`,
+    );
     return parts.join(" · ");
   }
   if (rule.retry) {
-    parts.push(`retry pays ${Math.floor((rule.xp * rule.retry.xpPercent) / 100)} XP + ${Math.floor((rule.coins * rule.retry.coinsPercent) / 100)} Coins`);
+    parts.push(
+      `retry pays ${Math.floor((rule.xp * rule.retry.xpPercent) / 100)} XP + ${Math.floor((rule.coins * rule.retry.coinsPercent) / 100)} Coins${rule.retry.paidAttempts ? ` through try ${rule.retry.paidAttempts} (later solves pay nothing)` : ""}`,
+    );
   }
-  parts.push(rule.maxAttempts === null ? "unlimited tries" : `${rule.maxAttempts ?? 3} tries`);
+  parts.push(
+    rule.maxAttempts === null
+      ? "unlimited tries"
+      : `${rule.maxAttempts ?? 3} tries`,
+  );
   const standing = Array.isArray(rule.questions) ? rule.questions.length : 0;
   const sets = Array.isArray(rule.sets) ? rule.sets : [];
   if (sets.length && rule.progression === "until-earned") {
     const keys = sets.map((set, index) => set.key || `set-${index + 1}`);
-    parts.push(`${sets.length} until-earned set(s) in order: ${keys.join(", ")}${standing ? ` · ${standing} standing question(s)` : ""}`);
+    parts.push(
+      `${sets.length} until-earned set(s) in order: ${keys.join(", ")}${standing ? ` · ${standing} standing question(s)` : ""}`,
+    );
   } else if (sets.length) {
-    const days = sets.map((set) => (set.to && set.to !== set.from ? `${set.from}..${set.to}` : set.from));
-    parts.push(`${sets.length} dated set(s): ${days.join(", ")}${standing ? ` · ${standing} standing question(s)` : " · no standing questions"}`);
+    const days = sets.map((set) =>
+      set.to && set.to !== set.from ? `${set.from}..${set.to}` : set.from,
+    );
+    parts.push(
+      `${sets.length} dated set(s): ${days.join(", ")}${standing ? ` · ${standing} standing question(s)` : " · no standing questions"}`,
+    );
   } else {
     parts.push(`${standing} question(s)`);
   }
@@ -3644,32 +3880,79 @@ export function formatRewardRuleLine(rule) {
 function printRewardReviewResult({ operation, data }) {
   if (operation.name === "reward-review.list") {
     const reviews = Array.isArray(data.reviews) ? data.reviews : [];
-    console.log(`${reviews.length} reward review(s) (${data.filter || "pending"}):`);
-    for (const review of reviews) console.log(`  ${formatRewardReviewLine(review)}`);
+    console.log(
+      `${reviews.length} reward review(s) (${data.filter || "pending"}):`,
+    );
+    for (const review of reviews)
+      console.log(`  ${formatRewardReviewLine(review)}`);
     if (data.nextCursor) console.log(`More: --cursor ${data.nextCursor}`);
     return;
   }
   const review = data.review || {};
   console.log(formatRewardReviewLine(review));
   if (operation.name === "reward-review.decide") {
-    console.log(`Decision recorded: ${operation.decision}. ${review.reason ? `Reason: ${review.reason}` : ""}`.trim());
+    console.log(
+      `Decision recorded: ${operation.decision}. ${review.reason ? `Reason: ${review.reason}` : ""}`.trim(),
+    );
+    if (review.published) {
+      console.log(
+        `Published on approval: version ${review.published.version} (artifact ${review.published.artifactVersionId}, ${review.published.transition}). The app is live now.`,
+      );
+    }
+  }
+  if (operation.name === "reward-review.propose") {
+    console.log(
+      `Proposal offered to the creator (${operation.fileCount} file(s) sent). They can accept (which publishes your version with these rules) or decline (which rejects the request).`,
+    );
+  }
+  if (review.proposal) {
+    const summary = review.proposal.diffSummary || {};
+    console.log(
+      `Proposal: ${summary.total ?? 0} file(s) changed (${summary.added ?? 0} added, ${summary.updated ?? 0} updated, ${summary.deleted ?? 0} deleted)${review.proposal.note ? ` · note: ${review.proposal.note}` : ""}${review.status === "changes_offered" ? " · waiting for the creator" : ""}`,
+    );
+    for (const file of review.proposal.changedFiles || [])
+      console.log(`  ${file.status}: ${file.path}`);
+  }
+  if (review.status === "rejected" && review.declinedByCreator) {
+    console.log("The creator declined the proposed changes; the request is closed.");
+  }
+  if (review.status === "approved" && review.publishedArtifactVersionId) {
+    console.log(
+      `Approved and published (artifact version ${review.publishedArtifactVersionId}).`,
+    );
   }
   if (Array.isArray(review.detectedRuleIds)) {
-    console.log(`Rule IDs found in source (heuristic): ${review.detectedRuleIds.join(", ") || "none"}`);
+    console.log(
+      `Rule IDs found in source (heuristic): ${review.detectedRuleIds.join(", ") || "none"}`,
+    );
   }
-  if (review.isLatest === false) console.log("WARNING: a newer request exists for this app; decide on the latest one.");
-  if (review.isLive) console.log("This review is the live approval currently paying out.");
+  if (review.isLatest === false)
+    console.log(
+      "WARNING: a newer request exists for this app; decide on the latest one.",
+    );
+  if (review.isLive)
+    console.log("This review is the live approval currently paying out.");
   if (review.awarded) {
-    console.log(`Paid by this review: ${review.awarded.awards} awards to ${review.awarded.earners} people · ${review.awarded.xp} XP · ${review.awarded.coins} Coins (app lifetime ${review.appLifetime?.xp ?? 0} XP / ${review.appLifetime?.coins ?? 0} Coins)`);
+    console.log(
+      `Paid by this review: ${review.awarded.awards} awards to ${review.awarded.earners} people · ${review.awarded.xp} XP · ${review.awarded.coins} Coins (app lifetime ${review.appLifetime?.xp ?? 0} XP / ${review.appLifetime?.coins ?? 0} Coins)`,
+    );
   }
   const config = review.config || {};
   if (Array.isArray(config.rules)) {
-    console.log(`Budgets: day ${config.dailyXP} XP/${config.dailyCoins} Coins · per user/day ${config.userDailyXP} XP/${config.userDailyCoins} Coins${config.userDailyClaims ? ` · ${config.userDailyClaims} claim(s)` : ""} · lifetime ${config.lifetimeXP} XP/${config.lifetimeCoins} Coins`);
-    for (const rule of config.rules) console.log(`  ${formatRewardRuleLine(rule)}`);
+    console.log(
+      `Budgets: day ${config.dailyXP} XP/${config.dailyCoins} Coins · per user/day ${config.userDailyXP} XP/${config.userDailyCoins} Coins${config.userDailyClaims ? ` · ${config.userDailyClaims} claim(s)` : ""} · lifetime ${config.lifetimeXP} XP/${config.lifetimeCoins} Coins`,
+    );
+    for (const rule of config.rules)
+      console.log(`  ${formatRewardRuleLine(rule)}`);
   }
   if (Array.isArray(review.files)) {
-    console.log(`Source: ${review.files.length} file(s)${data.snapshotDirectory ? ` written to ${data.snapshotDirectory}` : " (pass --dir <path> to write the snapshot)"}`);
-    for (const file of review.files) console.log(`  ${file.path} (${file.bytes ?? Buffer.byteLength(String(file.content || ""), "utf8")} bytes)`);
+    console.log(
+      `Source: ${review.files.length} file(s)${data.snapshotDirectory ? ` written to ${data.snapshotDirectory}` : " (pass --dir <path> to write the snapshot)"}`,
+    );
+    for (const file of review.files)
+      console.log(
+        `  ${file.path} (${file.bytes ?? Buffer.byteLength(String(file.content || ""), "utf8")} bytes)`,
+      );
   }
   console.log("Use --json for the full record.");
 }
@@ -3677,22 +3960,42 @@ function printRewardReviewResult({ operation, data }) {
 function printRewardActivity(data) {
   const apps = Array.isArray(data.apps) ? data.apps : [];
   const suspects = Array.isArray(data.suspects) ? data.suspects : [];
-  console.log(`Reward activity ${data.from} → ${data.to} (${data.days} day(s)): ${apps.length} app(s) paid, ${suspects.length} flagged player-day(s).`);
+  console.log(
+    `Reward activity ${data.from} → ${data.to} (${data.days} day(s)): ${apps.length} app(s) paid, ${suspects.length} flagged player-day(s).`,
+  );
   for (const app of apps) {
-    console.log(`  app ${app.buildId} ${app.title}: ${app.claims} claim(s) · ${app.earners} earner(s) · ${app.xp} XP · ${app.coins} Coins · ${app.flagged} flagged`);
+    console.log(
+      `  app ${app.buildId} ${app.title}: ${app.claims} claim(s) · ${app.earners} earner(s) · ${app.xp} XP · ${app.coins} Coins · ${app.flagged} flagged`,
+    );
   }
   if (!suspects.length) {
-    console.log("Nothing unusual: no claim on the minimum time, no bursts, no sweeps, no repeated cap days, no guessing.");
+    console.log(
+      "Nothing unusual: no claim on the minimum time, no bursts, no sweeps, no repeated cap days, no guessing.",
+    );
     return;
   }
   console.log("Flagged (worst first):");
   for (const s of suspects) {
-    const parts = [`${s.flags.join("+")}`, `user ${s.userId}${s.username ? ` ${s.username}` : ""}`, `app ${s.buildId} ${s.title}`, s.dayKey, `${s.claims} claim(s) · ${s.xp} XP`];
-    if (s.fastClaims) parts.push(`${s.fastClaims} on the minimum (fastest ${s.minElapsedSeconds}s)`);
-    if (s.guessing) parts.push(`${s.guessing} challenge(s) with ${data.limits?.guessingAttempts ?? 15}+ wrong answers`);
+    const parts = [
+      `${s.flags.join("+")}`,
+      `user ${s.userId}${s.username ? ` ${s.username}` : ""}`,
+      `app ${s.buildId} ${s.title}`,
+      s.dayKey,
+      `${s.claims} claim(s) · ${s.xp} XP`,
+    ];
+    if (s.fastClaims)
+      parts.push(
+        `${s.fastClaims} on the minimum (fastest ${s.minElapsedSeconds}s)`,
+      );
+    if (s.guessing)
+      parts.push(
+        `${s.guessing} challenge(s) with ${data.limits?.guessingAttempts ?? 15}+ wrong answers`,
+      );
     console.log(`  ${parts.join(" · ")}`);
   }
-  console.log("Flags: fast = claimed within 5 s of the rule's minimum; burst = 3+ claims in 10 min; sweep = 75%+ of an app's completion rules within 30 min; cap = at the per-learner day cap; daily-max = at the cap on 3+ days; guessing = 15+ wrong answers on one quiz challenge. None is proof: read the player before acting.");
+  console.log(
+    "Flags: fast = claimed within 5 s of the rule's minimum; burst = 3+ claims in 10 min; sweep = 75%+ of an app's completion rules within 30 min; cap = at the per-learner day cap; daily-max = at the cap on 3+ days; guessing = 15+ wrong answers on one quiz challenge. None is proof: read the player before acting.",
+  );
 }
 
 function printAdminResult({ operation, result }) {
@@ -3707,20 +4010,34 @@ function printAdminResult({ operation, result }) {
   }
   if (operation.name === "runtime.evidence") {
     const evidence = data.evidence || {};
-    console.log(`Runtime evidence (${data.host?.requested || "unknown"}): ${evidence.status || "unknown"}.`);
-    console.log(`Samples: ${evidence.coverage?.samples ?? "unknown"}; latest: ${evidence.coverage?.lastAtMs ?? "unknown"}; age ms: ${evidence.coverage?.ageMs ?? "unknown"}.`);
+    console.log(
+      `Runtime evidence (${data.host?.requested || "unknown"}): ${evidence.status || "unknown"}.`,
+    );
+    console.log(
+      `Samples: ${evidence.coverage?.samples ?? "unknown"}; latest: ${evidence.coverage?.lastAtMs ?? "unknown"}; age ms: ${evidence.coverage?.ageMs ?? "unknown"}.`,
+    );
     for (const recycle of evidence.recycles || []) {
-      console.log(`  ${recycle.id}: ${recycle.outcome}; under load: ${recycle.observedUnderLoad ?? "unknown"}.`);
+      console.log(
+        `  ${recycle.id}: ${recycle.outcome}; under load: ${recycle.observedUnderLoad ?? "unknown"}.`,
+      );
     }
-    console.log("Missing evidence is unknown, not healthy. A recovered topology does not verify interrupted user work. Use --json for full evidence.");
+    console.log(
+      "Missing evidence is unknown, not healthy. A recovered topology does not verify interrupted user work. Use --json for full evidence.",
+    );
     return;
   }
   if (operation.name === "featured.plan") {
     for (const pair of data.plan?.replacements || []) {
-      console.log(`${pair.remove.id} ${pair.remove.title} -> ${pair.add.id} ${pair.add.title}`);
+      console.log(
+        `${pair.remove.id} ${pair.remove.title} -> ${pair.add.id} ${pair.add.title}`,
+      );
     }
-    console.log(`Proposed final order: ${(data.plan?.finalIds || []).join(",")}`);
-    console.log(`Plan hash: ${data.planHash}. Obtain Mikey's approval before using featured apply --file <plan.json> --approve ${data.planHash}.`);
+    console.log(
+      `Proposed final order: ${(data.plan?.finalIds || []).join(",")}`,
+    );
+    console.log(
+      `Plan hash: ${data.planHash}. Obtain Mikey's approval before using featured apply --file <plan.json> --approve ${data.planHash}.`,
+    );
     return;
   }
   if (operation.featuredWorkflow) {