@stage5/lumine 0.2.68 → 0.2.70

package/lib/admin.js

@@ -23,6 +23,7 @@ import {
 } 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";
 
 const MAX_EDITORIAL_FILE_BYTES = 256 * 1024;
 const MAX_COMPOSED_TEXT_FILE_BYTES = 64 * 1024;
@@ -300,7 +301,10 @@ export async function adminCommand(options) {
           "Use --resume with the scan checkpoint instead of combining --all with --cursor.",
         );
       }
-      result = await runAutomaticPagination({
+      const paginate = operation.name === "featured.history" &&
+        operation.pagination.filters.subjectIds.length > FEATURED_HISTORY_BATCH_SIZE
+        ? runBatchedFeaturedHistory : runAutomaticPagination;
+      result = await paginate({
         options,
         operation,
         runId,
@@ -329,6 +333,15 @@ export async function adminCommand(options) {
       result = transformResult(await fetchOperation());
     }
   } 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.data = {
+        ok: false,
+        status: "unavailable",
+        error: { code: error.code, message: error.message, details: { httpStatus: 404 } },
+      };
+    }
     if (operation.featuredWorkflow && error.featuredProgress) {
       const serverError = error.data?.error;
       error.data = {
@@ -388,6 +401,9 @@ export async function adminCommand(options) {
         typeof operation.body.buildReviewUnderstanding === "string",
     });
   }
+  if (operation.name === "comment.edit") {
+    assertComposedCommentEditResult({ result, body: operation.body });
+  }
   if (operation.name === "ai-email-policy.set") {
     assertAiEmailPolicySetResult({ operation, result });
   }
@@ -423,6 +439,7 @@ function transformAdminResult({
     assertSubjectWindowResult({ operation, result: transformed });
   }
   if (operation.name === "builds.candidates") {
+    assertBuildWindowResult({ operation, result: transformed });
     transformed = normalizeAdminBuildCandidatesResult({
       result: transformed,
       siteUrl: options.siteUrl,
@@ -558,12 +575,11 @@ export function writeAdminResultOutput({ filePath, result, operation }) {
 }
 
 export function normalizeAdminBuildCandidatesResult({ result, siteUrl }) {
-  const builds = Array.isArray(result?.builds) ? result.builds : [];
-  const nextCursor = String(result?.cursor || "").trim() || null;
+  const builds = result.data.builds;
   return {
-    ok: true,
-    status: "success",
+    ...result,
     data: {
+      ...result.data,
       builds: builds.map((build) => {
         const id = Number(build?.id || 0);
         return {
@@ -580,15 +596,128 @@ export function normalizeAdminBuildCandidatesResult({ result, siteUrl }) {
           },
         };
       }),
-      pagination: {
-        nextCursor,
-        hasMore: Boolean(nextCursor),
-        exhausted: !nextCursor,
-      },
     },
   };
 }
 
+export function assertBuildWindowResult({ operation, result }) {
+  const p = result?.data?.pagination;
+  const mode = operation?.pagination?.coverageMode;
+  if (
+    result?.ok !== true ||
+    !Array.isArray(result?.data?.builds) ||
+    !p ||
+    p.mode !== mode ||
+    !Number.isSafeInteger(p.snapshotMaxId) ||
+    p.snapshotMaxId < 0 ||
+    !Number.isSafeInteger(p.snapshotTimeStamp) ||
+    p.snapshotTimeStamp < 0 ||
+    (mode === "legacy"
+      ? p.after !== null
+      : !Number.isSafeInteger(p.after) || p.after < 0) ||
+    (mode === "after" && p.after !== operation.pagination.after) ||
+    typeof p.exhausted !== "boolean" ||
+    p.hasMore !== !p.exhausted ||
+    (p.exhausted
+      ? p.nextCursor !== null
+      : typeof p.nextCursor !== "string" || !p.nextCursor)
+  ) {
+    const error = new Error(
+      "The API did not confirm the requested published-Build window and snapshot. Deploy the matching API; do not substitute an unbounded public browser scan.",
+    );
+    error.code = "LUMINE_ADMIN_BUILD_WINDOW_UNSUPPORTED";
+    throw error;
+  }
+}
+
+export function assertComposedCommentEditResult({ result, body }) {
+  const edit = result?.data?.edit;
+  if (
+    result?.ok === true &&
+    result?.data?.comment?.content === body.content &&
+    (!body.buildReviewUnderstanding ||
+      (edit?.buildReviewContextStored === true &&
+        edit?.reviewedBuildVersionId === body.reviewedBuildVersionId &&
+        Number.isSafeInteger(edit?.managementDraftId) &&
+        edit.managementDraftId > 0))
+  )
+    return;
+  const error = new Error(
+    "The API did not confirm the exact comment edit and its required Build review context. Inspect the canonical result before retrying; deploy the matching API if unsupported.",
+  );
+  error.code = "LUMINE_ADMIN_COMMENT_EDIT_UNCONFIRMED";
+  error.data = {
+    ok: false,
+    status: "validation_error",
+    error: {
+      code: error.code,
+      message: error.message,
+      details: { canonicalResult: result },
+    },
+  };
+  throw error;
+}
+
+function readAdminBuildReviewEvidence(options, parsedTarget) {
+  const version = options.adminReviewedBuildVersion
+    ? parseRequiredInteger(
+        options.adminReviewedBuildVersion,
+        "--reviewed-version",
+        1,
+      )
+    : undefined;
+  const method = options.adminBuildReviewMethod
+    ? parseAdminBuildReviewMethod(options.adminBuildReviewMethod)
+    : undefined;
+  const receipt = options.adminReviewReceipt
+    ? parseBuildReviewReceipt(options.adminReviewReceipt)
+    : null;
+  const understanding = options.adminReviewContext
+    ? readBuildReviewContextFile(options.adminReviewContext)
+    : undefined;
+  if (receipt && (version || method)) {
+    throw cliValidationError(
+      "Pass either --review-receipt or manual --reviewed-version/--reviewed-via evidence, not both.",
+    );
+  }
+  const reviewedBuildVersionId = receipt
+    ? Number(receipt.publishedArtifactVersionId)
+    : version;
+  const buildReviewMethod = receipt ? "runtime" : method;
+  if (understanding && (!reviewedBuildVersionId || !buildReviewMethod)) {
+    throw cliValidationError(
+      "--review-context requires confirmed Build review evidence.",
+    );
+  }
+  if ((reviewedBuildVersionId || buildReviewMethod) && !understanding) {
+    throw cliValidationError(
+      "Build review evidence requires --review-context <context.json>.",
+    );
+  }
+  if (
+    receipt &&
+    parsedTarget.type === "build" &&
+    Number(receipt.buildId) !== parsedTarget.id
+  ) {
+    throw cliValidationError(
+      "The review receipt belongs to a different Build.",
+    );
+  }
+  if (
+    !["build", "comment"].includes(parsedTarget.type) &&
+    (reviewedBuildVersionId || buildReviewMethod)
+  ) {
+    throw cliValidationError(
+      "Build review evidence applies only to build:<id> or a comment:<id> inside a Build.",
+    );
+  }
+  return {
+    ...(reviewedBuildVersionId ? { reviewedBuildVersionId } : {}),
+    ...(buildReviewMethod ? { buildReviewMethod } : {}),
+    ...(understanding ? { buildReviewUnderstanding: understanding } : {}),
+  };
+}
+
 export function assertComposedCommentDraftResult({
   result,
   expectedContent,
@@ -873,6 +1002,7 @@ function adminOperationRequiresRun(operation) {
       "identity.use",
       "identity.inspect",
       "economy.trace",
+      "bot.context",
       "rescue.wordle.audit",
       "daily-run.start",
       "daily-run.status",
@@ -1445,11 +1575,13 @@ export function parseAdminOperation(options) {
   }
 
   if (namespace === "builds" && action === "candidates") {
+    const window = parseBuildWindow(options);
     return readOperation(
       "builds.candidates",
-      withQuery("/build/public/list", {
-        sort: "recent",
-        scope: "all",
+      withQuery("/cli/admin/builds/candidates", {
+        sinceRun: window.mode === "since-run" ? "true" : "",
+        after: window.mode === "after" ? window.after : "",
+        includeLegacy: window.mode === "legacy" ? "true" : "",
         cursor: options.adminCursor,
         limit: options.limit,
       }),
@@ -1457,9 +1589,12 @@ export function parseAdminOperation(options) {
         pagination: {
           collectionKey: "builds",
           coverageQueue: "builds",
-          coverageMode: "all",
-          after: null,
-          filters: { sort: "recent", scope: "all" },
+          coverageMode: window.mode,
+          after:
+            window.mode === "after"
+              ? parseAfterForCoverage(window.after)
+              : null,
+          filters: { sort: "published-release", scope: "all" },
         },
       },
     );
@@ -1478,6 +1613,9 @@ export function parseAdminOperation(options) {
       body: undefined,
       mutates: false,
       buildId: parsed.id,
+      // Public artifact inspection also supports a one-comment correction;
+      // it never needs a full daily-management authorization envelope.
+      requiresRun: false,
     };
   }
 
@@ -1579,6 +1717,12 @@ export function parseAdminOperation(options) {
         options.adminIds,
         "--subject-ids",
       );
+      if (subjectIds.length > 20_000) {
+        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.");
+      }
       return readOperation(
         "featured.history",
         withQuery("/cli/admin/subjects/featured/history", {
@@ -1589,6 +1733,7 @@ export function parseAdminOperation(options) {
         {
           pagination: {
             collectionKey: "events",
+            summaryKeys: ["coverage", "subjects"],
             filters: { subjectIds },
           },
         },
@@ -1860,10 +2005,23 @@ 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].");
+    }
+    return readOperation(
+      "runtime.evidence",
+      withQuery(`/cli/admin/runtime-logs/hosts/${target}/evidence`, {
+        days: parseRequiredInteger(options.adminDays || "7", "--days", 1, 7),
+      }),
+      { requiresRun: false },
+    );
+  }
+
   if (namespace === "runtime-logs") {
     if (
       (action === "start" || action === "status" || action === "read") &&
-      !target &&
+      (!target || (action === "start" && ["primary", "target"].includes(target))) &&
       !extra
     ) {
       if (
@@ -1883,6 +2041,7 @@ export function parseAdminOperation(options) {
         mutates: action !== "status",
         requiresRun: false,
         runtimeLogAction: action === "read" ? "capture" : action,
+        ...(action === "start" && target ? { runtimeLogHost: target } : {}),
       };
     }
     if ((action === "resume" || action === "abandon") && !target && !extra) {
@@ -1978,6 +2137,36 @@ export function parseAdminOperation(options) {
     });
   }
 
+  if (namespace === "bot-output" && action === "context") {
+    const messageId = parseRequiredInteger(target, "bot message ID", 1);
+    const reason = String(options.adminReason || "").trim();
+    if (!reason || reason.length > MAX_IDENTITY_INSPECTION_REASON_LENGTH) {
+      throw cliValidationError(
+        "Explain the private bot investigation with --reason (1–500 characters).",
+      );
+    }
+    if (options.adminAll || options.adminDays) {
+      throw cliValidationError(
+        "Bot context is a narrow message-ID investigation, not an --all or --days scan.",
+      );
+    }
+    return writeOperation(
+      "bot.context",
+      "POST",
+      `/cli/admin/bot-output/${messageId}/context`,
+      {
+        reason,
+        cursor: options.adminCursor || undefined,
+        limit: parseRequiredInteger(
+          options.adminContextLimit ?? 20,
+          "--limit",
+          1,
+          40,
+        ),
+      },
+    );
+  }
+
   if (namespace === "bot-output" && !action) {
     if (options.adminDays && options.adminCursor) {
       throw cliValidationError(
@@ -2029,58 +2218,10 @@ export function parseAdminOperation(options) {
           "comment reply targets a comment: lumine admin comment reply comment:<id>.",
         );
       }
-      const reviewedBuildVersionId = options.adminReviewedBuildVersion
-        ? parseRequiredInteger(
-            options.adminReviewedBuildVersion,
-            "--reviewed-version",
-            1,
-          )
-        : undefined;
-      const buildReviewMethod = options.adminBuildReviewMethod
-        ? parseAdminBuildReviewMethod(options.adminBuildReviewMethod)
-        : undefined;
-      const reviewReceipt = options.adminReviewReceipt
-        ? parseBuildReviewReceipt(options.adminReviewReceipt)
-        : null;
-      const buildReviewUnderstanding = options.adminReviewContext
-        ? readBuildReviewContextFile(options.adminReviewContext)
-        : undefined;
-      if (reviewReceipt && (reviewedBuildVersionId || buildReviewMethod)) {
-        throw cliValidationError(
-          "Pass either --review-receipt or manual --reviewed-version/--reviewed-via evidence, not both.",
-        );
-      }
-      const confirmedBuildVersionId = reviewReceipt
-        ? Number(reviewReceipt.publishedArtifactVersionId)
-        : reviewedBuildVersionId;
-      const confirmedBuildReviewMethod = reviewReceipt
-        ? "runtime"
-        : buildReviewMethod;
-      if (
-        buildReviewUnderstanding &&
-        (!confirmedBuildVersionId || !confirmedBuildReviewMethod)
-      ) {
-        throw cliValidationError(
-          "--review-context requires confirmed Build review evidence.",
-        );
-      }
-      if (
-        (confirmedBuildVersionId || confirmedBuildReviewMethod) &&
-        !buildReviewUnderstanding
-      ) {
-        throw cliValidationError(
-          "Build review evidence requires --review-context <context.json>.",
-        );
-      }
-      if (
-        reviewReceipt &&
-        parsedTarget.type === "build" &&
-        Number(reviewReceipt.buildId) !== parsedTarget.id
-      ) {
-        throw cliValidationError(
-          "The review receipt belongs to a different Build.",
-        );
-      }
+      const reviewEvidence = readAdminBuildReviewEvidence(
+        options,
+        parsedTarget,
+      );
       if (parsedTarget.type === "build") {
         if (!options.adminFile) {
           throw cliValidationError(
@@ -2088,21 +2229,14 @@ export function parseAdminOperation(options) {
           );
         }
         if (
-          !confirmedBuildVersionId ||
-          !confirmedBuildReviewMethod ||
-          !buildReviewUnderstanding
+          !reviewEvidence.reviewedBuildVersionId ||
+          !reviewEvidence.buildReviewMethod ||
+          !reviewEvidence.buildReviewUnderstanding
         ) {
           throw cliValidationError(
             "After reviewing the project, pass review evidence and --review-context <context.json>.",
           );
         }
-      } else if (
-        parsedTarget.type !== "comment" &&
-        (confirmedBuildVersionId || confirmedBuildReviewMethod)
-      ) {
-        throw cliValidationError(
-          "Build review evidence applies only to build:<id> or a comment:<id> inside a Build.",
-        );
       }
       return writeOperation(
         "comment.draft",
@@ -2117,13 +2251,7 @@ export function parseAdminOperation(options) {
           ...(options.adminFile
             ? { content: readComposedTextFile(options.adminFile) }
             : {}),
-          ...(confirmedBuildVersionId
-            ? { reviewedBuildVersionId: confirmedBuildVersionId }
-            : {}),
-          ...(confirmedBuildReviewMethod
-            ? { buildReviewMethod: confirmedBuildReviewMethod }
-            : {}),
-          ...(buildReviewUnderstanding ? { buildReviewUnderstanding } : {}),
+          ...reviewEvidence,
         },
       );
     }
@@ -2148,7 +2276,13 @@ export function parseAdminOperation(options) {
         "comment.edit",
         "PUT",
         `/cli/admin/comments/${commentId}`,
-        { content: readComposedTextFile(options.adminFile) },
+        {
+          content: readComposedTextFile(options.adminFile),
+          ...readAdminBuildReviewEvidence(options, {
+            type: "comment",
+            id: commentId,
+          }),
+        },
         {
           correctionEligible: true,
           correctionCommentId: commentId,
@@ -2394,6 +2528,22 @@ export function parseSubjectWindow(options) {
   return { mode, after: mode === "after" ? options.adminAfter : "" };
 }
 
+export function parseBuildWindow(options) {
+  const selected = [
+    options.adminSinceRun ? "since-run" : "",
+    options.adminAfter ? "after" : "",
+    options.adminIncludeLegacy ? "legacy" : "",
+  ].filter(Boolean);
+  if (selected.length > 1) {
+    throw cliValidationError(
+      "Choose one Build window: --since-run, --after, or --include-legacy.",
+    );
+  }
+  const mode = selected[0] || "since-run";
+  if (mode === "after") parseAfterForCoverage(options.adminAfter);
+  return { mode, after: mode === "after" ? options.adminAfter : "" };
+}
+
 function parseUtcDayKey(value) {
   const dayKey = String(value || "").trim();
   const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(dayKey);
@@ -3247,6 +3397,16 @@ async function printSpooledAdminResult({ operation, result, storage }) {
 
 function printAdminResult({ operation, result }) {
   const data = result?.data || {};
+  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"}.`);
+    for (const recycle of evidence.recycles || []) {
+      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.");
+    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}`);
@@ -3360,6 +3520,14 @@ function printAdminResult({ operation, result }) {
       `Confirmed Build #${data.review.buildId} runtime at published artifact #${data.review.publishedArtifactVersionId}.`,
     );
     console.log(`Screenshot: ${data.screenshotPath}`);
+    if (data.review.interaction) {
+      console.log(
+        `Interaction script: ${data.review.interaction.stepsCompleted}/${data.review.interaction.stepsPlanned} step(s) ${data.review.interaction.status}.`,
+      );
+    }
+    for (const shot of data.review.screenshots || []) {
+      console.log(`  Screenshot [${shot.label}]: ${shot.path}`);
+    }
     console.log(`Review receipt: ${data.receiptPath}`);
     return;
   }
@@ -3508,6 +3676,20 @@ function printAdminResult({ operation, result }) {
     );
     return;
   }
+  if (data.escalation?.summary) {
+    const target =
+      data.escalation.url ||
+      `${data.escalation.targetType || "target"}:${data.escalation.targetId || "?"}`;
+    console.log(
+      `Escalation${data.escalation.auditId ? ` #${data.escalation.auditId}` : ""} recorded: ${String(data.escalation.severity || "attention").toUpperCase()} ${target} — ${data.escalation.summary}`,
+    );
+    if (data.escalation.auditId) {
+      console.log(
+        `Set its disposition later with: lumine admin escalation set ${data.escalation.auditId} --status <status> --note <decision>`,
+      );
+    }
+    return;
+  }
   if (Array.isArray(data.todos)) {
     printTodoItems(data.todos, "Private carry-over work");
     if (data.truncated) {

package/lib/assets.js

@@ -56,7 +56,7 @@ export async function assetsCommand(options) {
     return;
   }
   throw new Error(
-    'Usage: lumine assets [list] | lumine assets upload <file...> | lumine assets generate "<prompt>" --model <gpt-image-2|nano-banana> | lumine assets delete <assetId> | lumine assets prune [--yes]',
+    'Usage: lumine assets [list] | lumine assets upload <file...> | lumine assets generate "<prompt>" --model <gpt-image-2.5-flare|gpt-image-2.5-sunburst|gpt-image-2|nano-banana> | lumine assets delete <assetId> | lumine assets prune [--yes]',
   );
 }
 
@@ -65,18 +65,21 @@ export function resolveGenerateModel(options) {
   const model = GENERATE_MODEL_ALIASES[rawModel];
   if (!model) {
     throw new Error(
-      "--model is required: gpt-image-2 (best quality, slower, pricier) or nano-banana (Gemini — faster, cheaper). No default model is applied.",
+      "--model is required: gpt-image-2.5-flare (fast generation), gpt-image-2.5-sunburst (precise editing), gpt-image-2, or nano-banana. No default model is applied.",
     );
   }
   const rawQuality = String(options.quality || "").trim();
   if (rawQuality && !GENERATE_QUALITIES.has(rawQuality)) {
-    throw new Error("--quality must be low, medium, or high.");
+    throw new Error("--quality must be low, medium, high, xhigh, or max.");
   }
-  if (rawQuality && model !== "gpt-image-2") {
+  if (rawQuality && !model.startsWith("gpt-image-")) {
     throw new Error(
-      "--quality only applies to gpt-image-2; nano-banana has a single quality tier.",
+      "--quality only applies to GPT Image models; nano-banana has a single quality tier.",
     );
   }
+  if (model === "gpt-image-2" && ["xhigh", "max"].includes(rawQuality)) {
+    throw new Error("xhigh and max require a GPT Image 2.5 model.");
+  }
   return { model, quality: rawQuality || null };
 }
 
@@ -118,7 +121,7 @@ export async function assetsGenerate(options) {
   const prompt = String(options.positional[1] || "").trim();
   if (!prompt) {
     throw new Error(
-      'Usage: lumine assets generate "<prompt>" --model <gpt-image-2|nano-banana> [--quality low|medium|high] [--name <fileName>] [--yes]',
+      'Usage: lumine assets generate "<prompt>" --model <gpt-image-2.5-flare|gpt-image-2.5-sunburst|gpt-image-2|nano-banana> [--quality low|medium|high|xhigh|max] [--name <fileName>] [--yes]',
     );
   }
   const { model, quality } = resolveGenerateModel(options);
@@ -161,8 +164,8 @@ export async function assetsGenerate(options) {
       (option) => option.model === model,
     );
     const costLine = selectedOption
-      ? `  Estimated battery cost: ${formatBatteryPercent(selectedOption.energyUnits, estimate?.fullBatteryUnits)} of a full AI battery (~$${Number(selectedOption.estimatedUsd || 0).toFixed(2)})`
-      : "  Estimated battery cost: unavailable";
+      ? `  Estimated image output: ${formatBatteryPercent(selectedOption.energyUnits, estimate?.fullBatteryUnits)} of a full AI battery (~$${Number(selectedOption.estimatedUsd || 0).toFixed(2)}). Prompt input uses additional energy.`
+      : "  Estimated image output: unavailable";
     const remainingLine = estimate
       ? `  Battery remaining now:  ${formatBatteryPercent(estimate.energyRemaining, estimate.fullBatteryUnits)}`
       : "";