@stage5/lumine 0.2.67 → 0.2.68

package/lib/admin.js

@@ -8,6 +8,7 @@ import {
   readAdminJsonFile,
   validateNewsEditorial,
   writeNewsClaimArtifacts,
+  writeAdminJsonFile,
 } from "./admin-news.js";
 import {
   forEachPaginatedResultItem,
@@ -21,6 +22,7 @@ import {
   runManagedBuildReview,
 } from "./build-review.js";
 import { runAdminRuntimeLogWorkflow } from "./admin-runtime-logs.js";
+import { readApprovedFeaturedPlan, runFeaturedWorkflow } from "./admin-featured.js";
 
 const MAX_EDITORIAL_FILE_BYTES = 256 * 1024;
 const MAX_COMPOSED_TEXT_FILE_BYTES = 64 * 1024;
@@ -270,7 +272,9 @@ export async function adminCommand(options) {
         recommendationContentTypes,
         viewFilter,
       });
-    if (operation.name === "build.review") {
+    if (operation.featuredWorkflow) {
+      result = await runFeaturedWorkflow({ options, operation, authToken: auth.token, runId });
+    } else if (operation.name === "build.review") {
       result = await runManagedBuildReview({
         options,
         authToken: auth.token,
@@ -325,9 +329,26 @@ export async function adminCommand(options) {
       result = transformResult(await fetchOperation());
     }
   } catch (error) {
+    if (operation.featuredWorkflow && error.featuredProgress) {
+      const serverError = error.data?.error;
+      error.data = {
+        ok: false,
+        status: "partial_failure",
+        error: {
+          code: serverError?.code || error.code || "LUMINE_ADMIN_FEATURED_WORKFLOW_FAILED",
+          message: error.message,
+          details: {
+            ...(serverError && typeof serverError === "object" ? serverError.details : {}),
+            ...error.featuredProgress,
+            retryInstruction: "Resume the exact command with --resume; confirmed items are not replayed.",
+          },
+        },
+      };
+    }
     if (
       operation.mutates &&
       requestId &&
+      !operation.featuredWorkflow &&
       operation.name !== "post.skip-batch"
     ) {
       const retryInstruction = `Retry with --idempotency-key ${requestId}.`;
@@ -480,6 +501,14 @@ export function assertSubjectWindowResult({ operation, result }) {
 
 async function finishAdminOutput({ options, operation, result }) {
   const paginationStorage = getPaginatedResultStorage(result);
+  if (
+    options.adminOutput &&
+    !paginationStorage &&
+    operation.name !== "news.claim" &&
+    operation.name !== "post.skip-batch"
+  ) {
+    writeAdminResultOutput({ filePath: options.adminOutput, result, operation });
+  }
   if (options.json) {
     if (paginationStorage) {
       await writePaginatedResultJson({
@@ -507,6 +536,27 @@ async function finishAdminOutput({ options, operation, result }) {
   return result;
 }
 
+export function writeAdminResultOutput({ filePath, result, operation }) {
+  try {
+    return writeAdminJsonFile(filePath, result, { privateFile: true });
+  } catch (cause) {
+    const error = new Error(
+      `The canonical ${operation.name} result was received, but --output could not be saved: ${cause.message}. Do not repeat a successful mutation just to save its output.`,
+    );
+    error.code = "LUMINE_ADMIN_OUTPUT_WRITE_FAILED";
+    error.data = {
+      ok: false,
+      status: "error",
+      error: {
+        code: error.code,
+        message: error.message,
+        details: { canonicalResult: result, outputPath: String(filePath) },
+      },
+    };
+    throw error;
+  }
+}
+
 export function normalizeAdminBuildCandidatesResult({ result, siteUrl }) {
   const builds = Array.isArray(result?.builds) ? result.builds : [];
   const nextCursor = String(result?.cursor || "").trim() || null;
@@ -756,7 +806,7 @@ export function canonicalAdminRunScope(run) {
   const raw = run?.runScope;
   if (raw === undefined || raw === null || raw === "") return "full";
   const scope = String(raw);
-  if (scope === "full" || scope === "featured") return scope;
+  if (["full", "featured", "newspaper"].includes(scope)) return scope;
   throw cliValidationError(
     "The API returned an invalid administrator run scope.",
   );
@@ -778,6 +828,12 @@ const FEATURED_RUN_OPERATIONS = new Set([
   "featured.add",
   "featured.reorder",
   "featured.rotate",
+  "featured.plan",
+  "featured.apply",
+  "featured.comments.scan",
+  "featured.comments.acknowledge",
+  "featured.comments.recommend",
+  "featured.comments.report",
   "daily-run.complete",
   "daily-run.fail",
 ]);
@@ -786,6 +842,14 @@ export function assertAdminOperationAllowedForRunScope({
   operation,
   runScope,
 }) {
+  if (runScope === "newspaper") {
+    if (
+      ["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}.`,
+    );
+  }
   if (runScope !== "featured") return;
   const subjectCommentAlias =
     operation.name === "post.comments" &&
@@ -794,7 +858,7 @@ export function assertAdminOperationAllowedForRunScope({
     return;
   }
   throw cliValidationError(
-    `A Featured-only run does not authorize ${operation.name}. Complete or fail it before starting a full daily review.`,
+    `A Featured-only run does not authorize ${operation.name}. Use the review-bound Featured comment workflow for encouragement; do not start unrelated daily work to bypass scope.`,
   );
 }
 
@@ -1216,17 +1280,17 @@ export function parseAdminOperation(options) {
     if (action === "start") {
       const runScope = parseDailyRunScope(options.adminScope || "full");
       const commentMode = parseCommentMode(options.commentMode || "off");
-      if (runScope === "featured" && commentMode !== "off") {
+      if (runScope !== "full" && commentMode !== "off") {
         throw cliValidationError(
-          "A Featured-only run requires --comment-mode off.",
+          "A scoped run requires --comment-mode off.",
         );
       }
       return writeOperation(
         "daily-run.start",
         "POST",
-        runScope === "featured"
-          ? "/cli/admin/daily-runs/start/featured"
-          : "/cli/admin/daily-runs/start",
+        runScope === "full"
+          ? "/cli/admin/daily-runs/start"
+          : `/cli/admin/daily-runs/start/${runScope}`,
         {
           identity: options.adminIdentity
             ? parseIdentity(options.adminIdentity)
@@ -1483,6 +1547,30 @@ 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>.");
+      }
+      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 };
+    }
+    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 (action === "apply") {
+      readApprovedFeaturedPlan(options.adminFile, options.adminApprove);
+      return { ...writeOperation("featured.apply", "POST", "/cli/admin/subjects/featured/plan/apply", {}),
+        featuredWorkflow: "apply" };
+    }
     if (action === "list") {
       return readOperation("featured.list", "/cli/admin/subjects/featured");
     }
@@ -1528,7 +1616,7 @@ export function parseAdminOperation(options) {
   if (namespace === "post") {
     if (action === "get") return postGetOperation(target, options);
     if (action === "comments") {
-      const parsedTarget = parseRecommendationTarget({
+      const parsedTarget = parseAdminCommentTarget({
         target,
         explicitType: options.adminType,
       });
@@ -1729,7 +1817,9 @@ export function parseAdminOperation(options) {
           "ai-costs monthly uses UTC calendar months and does not accept --days.",
         );
       }
-      return readOperation("ai-costs.monthly", "/cli/admin/ai-costs/monthly");
+      return readOperation("ai-costs.monthly", "/cli/admin/ai-costs/monthly", {
+        requiresRun: false,
+      });
     }
     if (action === "day" && !extra) {
       if (options.adminDays) {
@@ -2243,6 +2333,7 @@ function featuredRotateOperation(options) {
     {
       removeIds,
       addIds,
+      ...(options.adminPostedAfter ? { postedAfter: options.adminPostedAfter } : {}),
     },
   );
 }
@@ -2524,7 +2615,7 @@ export function assertAdminTodoHandoffResult(result, expectedRunScope = null) {
     throw error;
   }
   const handoff = result?.data?.carryoverTodos;
-  if (runScope === "featured") {
+  if (runScope !== "full") {
     if (
       !runId ||
       !handoff ||
@@ -2536,7 +2627,7 @@ export function assertAdminTodoHandoffResult(result, expectedRunScope = null) {
       Number(handoff.newlySurfacedCount) !== 0
     ) {
       const error = cliValidationError(
-        "The API did not confirm that carry-over telemetry was suppressed for the Featured-only run.",
+        "The API did not confirm that carry-over telemetry was suppressed for the scoped run.",
       );
       error.code = "LUMINE_ADMIN_SCOPED_RUN_UNSUPPORTED";
       throw error;
@@ -2617,8 +2708,8 @@ function parseDailyRunScope(value) {
   const scope = String(value || "full")
     .trim()
     .toLowerCase();
-  if (!["full", "featured"].includes(scope)) {
-    throw cliValidationError("--scope must be full or featured.");
+  if (!["full", "featured", "newspaper"].includes(scope)) {
+    throw cliValidationError("--scope must be full, featured, or newspaper.");
   }
   return scope;
 }
@@ -3156,6 +3247,18 @@ async function printSpooledAdminResult({ operation, result, storage }) {
 
 function printAdminResult({ operation, result }) {
   const data = result?.data || {};
+  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(`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) {
+    console.log(JSON.stringify(data, null, 2));
+    return;
+  }
   if (Array.isArray(data.applications)) {
     console.log(`${data.applications.length} sponsor application(s):`);
     for (const application of data.applications) {
@@ -3300,6 +3403,13 @@ function printAdminResult({ operation, result }) {
         `  ${coverage.queue}: ${coverage.candidateCount} candidate(s), ${coverage.scannedCount} row(s) scanned across ${coverage.pages} page(s).`,
       );
     }
+    for (const item of report.featuredReviews || []) {
+      const coverage = item.coverage;
+      const counts = item.encouragement || {};
+      console.log(
+        `  Featured review #${item.review?.id || coverage?.reviewId}: ${coverage?.reviewed ? `${coverage.coveredSubjectIds.length}/${coverage.subjectCount} Subjects read, ${coverage.commentsRead} comments` : "not acknowledged as read"}; ${coverage?.complete ? "complete" : "incomplete"}; ${counts.newBasicRecommendations || 0} confirmed new basic recommendations, ${counts.alreadyDone || 0} already done, ${counts.rewardEligibilityGrants || 0} reward-permission grants, ${counts.directRewardsCreated || 0} direct rewards.`,
+      );
+    }
     for (const escalation of report.escalations) {
       const target =
         escalation.url ||

package/lib/commands.js

@@ -2379,6 +2379,7 @@ export function parseArgs(args) {
     adminCursor: raw.cursor ? String(raw.cursor) : "",
     adminAfter: raw.after ? String(raw.after) : "",
     adminPostedAfter: raw.postedAfter ? String(raw.postedAfter) : "",
+    adminApprove: raw.approve ? String(raw.approve) : "",
     adminSinceRun: Boolean(raw.sinceRun),
     adminIncludeLegacy: Boolean(raw.includeLegacy),
     adminIncludePrivateEvidence: parseBoolean(
@@ -2846,7 +2847,7 @@ export function printHelp() {
   lumine admin ai-bucket note set --bucket-id <id> --note <text> [--json]
   lumine admin ai-email-policy get --email <address> [--json]
   lumine admin ai-email-policy set --email <address> --mode <automatic|separate_accounts> --note <text> [--json]
-  lumine admin daily-run start [--scope full|featured] [--identity zero|ciel|auto] [--comment-mode off|draft|post] [--run-key <key>] [--json]
+  lumine admin daily-run start [--scope full|featured|newspaper] [--identity zero|ciel|auto] [--comment-mode off|draft|post] [--run-key <key>] [--json]
   lumine admin daily-run status|report|complete|fail [--run <completed-run-id>] [--reason <text>] [--json]
   lumine admin daily-run escalation add --target <target> --note <summary> [--severity attention|urgent] [--json]
   lumine admin escalation list [--status open|acknowledged|resolved|all] [--limit <number>] [--json]
@@ -2874,9 +2875,15 @@ export function printHelp() {
   lumine admin featured history --subject-ids <id,id,...> [--all --checkpoint <file> [--resume]] [--cursor <cursor>] [--json]
   lumine admin featured add --subject-ids <id,id,...> --posted-after <ISO-8601-or-Unix-time> [--json]
   lumine admin featured reorder --subject-ids <id,id,...> [--json]
-  lumine admin featured rotate --remove-subject-ids <id,id,...> --add-subject-ids <id,id,...> [--json]
+  lumine admin featured rotate --remove-subject-ids <id,id,...> --add-subject-ids <id,id,...> [--posted-after <timestamp>] [--json]
+  lumine admin featured plan --remove-subject-ids <ids> --add-subject-ids <ids> [--subject-ids <final-order>] --posted-after <timestamp> --output <plan.json> [--json]
+  lumine admin featured apply --file <plan.json> --approve <exact-plan-hash> [--json]
+  lumine admin featured comments scan --checkpoint <file> [--resume] [--json]
+  lumine admin featured comments acknowledge --checkpoint <scan-file> --reviewed [--json]
+  lumine admin featured comments recommend --file <decisions.json> --checkpoint <batch-file> [--resume] [--json]
+  lumine admin featured comments report --checkpoint <scan-file> [--json]
   lumine admin post get <target> [--type subject|comment|aiStory|dailyReflection] [--json]
-  lumine admin post comments <target> [--type subject|aiStory|dailyReflection] [--unviewed|--viewed] [--all --checkpoint <file> [--resume]] [--cursor <cursor>] [--json]
+  lumine admin post comments <target> [--type subject|build|aiStory|dailyReflection] [--unviewed|--viewed] [--all --checkpoint <file> [--resume]] [--cursor <cursor>] [--json]
   lumine admin post recommend <target> [--type subject|comment|aiStory|dailyReflection] [--anyone-can-reward] [--reward-twinkles 3] [--json]
   lumine admin post skip <target> [--type comment|aiStory|dailyReflection] [--reason <text>] [--json]
   lumine admin post skip-batch --target-file <json-or-lines> [--reason <text>] [--checkpoint <file> [--resume]] [--json]
@@ -2886,7 +2893,7 @@ export function printHelp() {
   lumine admin comment post --draft-id <id> [--json]
   lumine admin comment edit <comment-id> --file <comment.md> [--json]
   lumine admin brief [--days <1..30>] [--json]
-  lumine admin ai-costs monthly [--json]
+  lumine admin ai-costs monthly [--output <file.json>] [--json] (no active run required)
   lumine admin ai-costs day <YYYY-MM-DD> [--json]
   lumine admin media-costs monthly [--json]
   lumine admin energy-budget [--days <1..31>] [--json]
@@ -2992,7 +2999,7 @@ Options:
   --review-receipt <f>  Confirmed managed Build runtime review receipt
   --review-context <f>  Private JSON understanding from the reviewed Build
   --review-session <f>  Private production-log review lease/checkpoint
-  --reviewed            Confirm every downloaded production-log byte was reviewed
+  --reviewed            Explicitly acknowledge downloaded logs or Featured comment pages as read
   --severity <level>    Run escalation severity: attention or urgent
   --status <state>      Private escalation or todo lifecycle filter/state
   --wait-ms <ms>        Managed Build observation or sponsor watch duration
@@ -3008,6 +3015,7 @@ Options:
   --subject-ids <ids>   Complete ordered Featured subject IDs
   --remove-subject-ids <ids> Featured subjects approved for rotation removal
   --add-subject-ids <ids> Ordered replacement subjects for Featured rotation
+  --approve <hash>      Exact Featured plan hash, only after Mikey's go-ahead
   --bucket-id <id>      Unbanned AI identity bucket for account consolidation
   --label <name>        Name for a new unbanned AI identity bucket
   --user-ids <ids>      Explicit user IDs for an AI bucket batch (up to 500)

package/package.json

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

package/sdk/BUILD_SDK_INDEX.md

@@ -467,10 +467,10 @@ const result = await Twinkle.ai.chat({ message, history: chatHistory, systemProm
   - Use this instead of asking Twinkle.ai.chat to return JSON.
   - expectedStructure must be a JSON object that describes the exact returned object shape.
   - mode is accepted as an alias for thinkingMode, and mid is accepted as an alias for medium.
-  - Omit model to use the normal Lite/Medium/High routing. model accepts gpt-5.6-sol, claude-opus-5, or claude-fable-5-1, and every explicit model must be paired with thinkingMode: 'high'; unknown model IDs reject instead of silently falling back.
+  - Omit model to use the normal Lite/Medium/High routing. model accepts gpt-6-astra, gpt-5.6-sol, claude-opus-5, or claude-fable-5-1, and every explicit model must be paired with thinkingMode: 'high'; unknown model IDs reject instead of silently falling back.
   - thinkingMode low uses GPT-5.6 Luna and consumes the viewer's AI Energy from confirmed provider usage; its smaller model is usually cheaper than Medium or High.
   - thinkingMode medium uses Grok 4.6 with medium reasoning and consumes normal AI Energy.
-  - thinkingMode high without model uses GPT-5.6 Sol with high reasoning and consumes high AI Energy. Explicit model: 'gpt-5.6-sol' selects Sol with xhigh reasoning at the same High AI Energy tier.
+  - thinkingMode high without model uses GPT-5.6 Sol with high reasoning and consumes high AI Energy. Explicit model: 'gpt-5.6-sol' selects Sol with xhigh reasoning at the same High AI Energy tier. Explicit model: 'gpt-6-astra' selects GPT-6 Astra with xhigh reasoning and debits confirmed usage at its own model rates in the High tier.
   - claude-opus-5 uses Anthropic adaptive High thinking. claude-fable-5-1 uses Anthropic xhigh thinking and normally consumes more AI Energy for comparable token use. Both debit confirmed provider usage at the High tier.
   - Pass onStatus, onReasoning, and/or onText to stream progress from the same structured generation. onStatus receives high-level phases such as thinking, searching_web, responding, validating, and completed.
   - onReasoning receives accumulated provider-supplied, app-visible reasoning summaries plus { done, delta, requestId, status }. A provider retry may replace the accumulated summary; treat each callback's first argument as the current source of truth. This callback never exposes hidden/private model chain-of-thought.