@stage5/lumine 0.2.78 → 0.2.79

package/lib/admin.js

@@ -139,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
@@ -1453,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();
@@ -1484,7 +1584,7 @@ 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>.",
     );
   }
 
@@ -3794,6 +3894,32 @@ function printRewardReviewResult({ operation, data }) {
     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(

package/lib/commands.js

@@ -2902,7 +2902,8 @@ export function printHelp() {
   lumine admin reward-review list [--status pending|approved|all] [--cursor <id>] [--json]
   lumine admin reward-activity [--date YYYY-MM-DD] [--days <1..31>] [--build <id>] [--json]
   lumine admin reward-review show <review-id> [--dir <path>] [--json]
-  lumine admin reward-review approve <review-id> [--config <rules.json>] [--reason <text>] [--json]
+  lumine admin reward-review approve <review-id> [--config <rules.json>] [--reason <text>] [--json]   (approval publishes the approved version)
+  lumine admin reward-review propose <review-id> --dir <edited-snapshot> --config <rules.json> [--reason <text>] [--json]
   lumine admin reward-review reject|revoke <review-id> --reason <text> [--json]
   lumine admin recommendations list [--since-run|--after <date>|--include-legacy] [--all --checkpoint <file> [--resume]] [--content-types comment,dailyReflection] [--unviewed|--viewed] [--cursor <cursor>] [--json]
   lumine admin builds candidates [--since-run|--after <date>|--include-legacy] [--all --checkpoint <file> [--resume]] [--cursor <cursor>] [--limit <number>] [--json]
@@ -3015,7 +3016,7 @@ Options:
   --preview-url <url>   Twinkle Build preview origin
   --auth-file <path>    Saved login path
   --auth-token <token>  Override saved login
-  --dir <path>          Directory for pulled project files or a reward-review source snapshot
+  --dir <path>          Directory for pulled project files, a reward-review source snapshot, or the edited snapshot a reward-review proposal sends
   --config <file>       Replacement earning rules JSON for reward-review approve (default: the app's own proposal)
   --provider <agent>    Subscription agent for lumine agent: codex or claude-code
   --provider-path <p>   Override the selected agent CLI executable

package/package.json

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

package/sdk/LUMINE_ADMIN.md

@@ -1065,9 +1065,16 @@ and answer keys from a private question sheet the creator's Lumine uploads with
 readable by every player). **Send for review** freezes the code and proposes
 `rewards.json` merged with the sheet. Approval is Mikey's decision: read the
 frozen code, check that the amounts are right and that the app cannot be
-farmed, change anything that is wrong, approve. These commands need no daily
-run and can be used whenever a request arrives (the reviewer also receives a
-DM card per request).
+farmed, change anything that is wrong, approve. **Approval publishes** (since
+2026-09-15): the exact frozen snapshot goes live in the same transaction, with
+no Publish click by the creator; the app's previous release stays up until
+that commit lands. Instead of approving, the reviewer may **propose changes**:
+edit a copy of the frozen snapshot and offer it as the condition of approval.
+The creator sees every changed line and either accepts (the proposed version
+is approved and published) or declines (the request is rejected). Nothing in
+that flow joins the creator's team. These commands need no daily run and can
+be used whenever a request arrives (the reviewer also receives a DM card per
+request).
 
 ```bash
 lumine admin reward-review list --json                       # pending (default)
@@ -1077,7 +1084,10 @@ lumine admin reward-review show 2 --json                     # summary + file si
 lumine admin reward-review show 2 --dir /private/tmp/reward-review-2 --json
 lumine admin reward-review approve 2 --json                  # approve exactly what the app proposed
 lumine admin reward-review approve 2 --config rules.json \
-  --reason "Halved the stage amounts" --json                 # approve with changes
+  --reason "Halved the stage amounts" --json                 # approve with changes (publishes)
+lumine admin reward-review show 2 --dir /private/tmp/reward-review-2 --json   # then edit that directory…
+lumine admin reward-review propose 2 --dir /private/tmp/reward-review-2 \
+  --config rules.json --reason "Moved the claim after the stage clears" --json  # …and offer it
 lumine admin reward-review reject 2 --reason "Rewards fire on game over; nothing is earned" --json
 lumine admin reward-review revoke 2 --reason "Farmable; pausing until redesigned" --json
 ```
@@ -1156,12 +1166,49 @@ Arcade Typing (Mikey, 2026-09-12): XP for clearing campaign stages, up to
 10,000 Coins per rule and per learner per day, 10,000,000 XP / 1,000,000 Coins
 per app per day, 1,000,000,000 XP / 100,000,000 Coins per app lifetime.
 
-Approval freezes these rules with the reviewed snapshot; an approval without at
-least one rule is refused. Rejection and revocation require a `--reason` the
-creator reads verbatim in their workspace. Approval never publishes: the creator
-publishes the approved version themselves, and a later code save needs a new
-request. Never approve without reading the code; never approve a request whose
-`isLatest` is false.
+Approval freezes these rules with the reviewed snapshot and publishes that
+snapshot immediately (the result carries `published.version`); an approval
+without at least one rule is refused, and an approval whose creator has saved
+past the frozen version is refused as `build_reward_review_stale` (the request
+also closes itself on that save). Rejection and revocation require a
+`--reason` the creator reads verbatim in their workspace. A later code save
+needs a new request. Never approve without reading the code; never approve a
+request whose `isLatest` is false.
+
+`propose <id> --dir <edited> --config rules.json [--reason]` sends the edited
+directory (text files only; dotfiles and tool folders skipped) as the
+reviewer's proposal: the review moves to `changes_offered`, the creator's card
+and workspace show the note and every changed line, and the creator's
+**Accept & go live** publishes exactly those files with these rules (their
+workspace is replaced by the accepted version). **No thanks** rejects the
+request (`declinedByCreator: true`). A proposal must still use the rewards
+SDK, must differ from the submitted snapshot, and is refused once the creator
+saves past the submitted version. Offering again replaces the earlier offer;
+approving or rejecting while an offer is out decides the request as
+submitted. The website equivalent is the Management panel's "Edit a copy to
+propose changes" (a private workspace copy owned by the reviewer) followed by
+"Offer my copy with these rules".
+
+Each offer has a server-owned revision. Changing the files, rules or note
+creates a new revision; a creator looking at an older comparison or decline
+confirmation cannot answer the replacement offer. The creator sees its reward
+amounts as well as its file changes. Proposed rules stay separate from the
+submitted rules until acceptance, so `approve` without `--config` still uses
+the original submitted configuration. The CLI audits the offer atomically
+and includes file contents in its retry fingerprint.
+
+Approval also attempts a free preview thumbnail when the app has none. That
+capture uses the published version and cannot overwrite a later release or a
+thumbnail the creator chooses while it runs. It is best effort: a capture
+failure leaves publication successful and does not spend AI-image credits.
+
+The review copy carries independent copies of referenced uploaded media.
+Before freezing an offer, the server reuses the creator's original media and
+copies new reviewer media into the creator's library within their storage
+quota. Its final URLs are included in the comparison, so acceptance publishes
+those exact files and does not depend on keeping the review copy. Re-offers
+reuse the media; a failed transaction cleans up its copied objects. Declining
+leaves the offered media as unused uploads in the creator's library.
 
 ### Reward activity report (standing duty, every full daily review; added 2026-09-12)