@stage5/lumine 0.2.65 → 0.2.67

package/lib/admin.js

@@ -20,6 +20,7 @@ import {
   parseBuildReviewReceipt,
   runManagedBuildReview,
 } from "./build-review.js";
+import { runAdminRuntimeLogWorkflow } from "./admin-runtime-logs.js";
 
 const MAX_EDITORIAL_FILE_BYTES = 256 * 1024;
 const MAX_COMPOSED_TEXT_FILE_BYTES = 64 * 1024;
@@ -171,6 +172,7 @@ export async function adminCommand(options) {
     scope: operation.mutates ? "build:write" : "build:read",
   });
   let runId = 0;
+  let runScope = null;
   let correctionSessionId = 0;
   let correctionSession = null;
   if (adminOperationRequiresRun(operation)) {
@@ -216,6 +218,10 @@ export async function adminCommand(options) {
       }
       throw noActiveRunError();
     }
+    if (selectedRun) {
+      runScope = canonicalAdminRunScope(selectedRun);
+      assertAdminOperationAllowedForRunScope({ operation, runScope });
+    }
     if (options.adminIdentity && (selectedRun || correctionSession)) {
       const requestedIdentity = parseIdentity(options.adminIdentity);
       const canonicalIdentity = correctionSession
@@ -237,7 +243,7 @@ export async function adminCommand(options) {
     options.idempotencyKey || (operation.mutates ? `cli:${randomUUID()}` : "");
   let result;
   try {
-    const fetchOperation = async (requestPath = operation.path) =>
+    const fetchOperation = async (requestPath = operation.path, signal) =>
       requestJson({
         method: operation.method,
         url: `${options.apiUrl}${requestPath}`,
@@ -247,14 +253,14 @@ export async function adminCommand(options) {
           ...(runId ? { "x-lumine-admin-run-id": String(runId) } : {}),
           ...(correctionSessionId
             ? {
-                "x-lumine-admin-correction-session-id": String(
-                  correctionSessionId,
-                ),
+                "x-lumine-admin-correction-session-id":
+                  String(correctionSessionId),
               }
             : {}),
           ...(requestId ? { "x-lumine-idempotency-key": requestId } : {}),
         },
         timeoutMs: options.timeoutMs,
+        signal,
       });
     const transformResult = (rawResult) =>
       transformAdminResult({
@@ -277,6 +283,13 @@ export async function adminCommand(options) {
         runId,
         parseTarget: parseRecommendationTarget,
       });
+    } else if (operation.name.startsWith("runtime-logs.")) {
+      result = await runAdminRuntimeLogWorkflow({
+        options,
+        operation,
+        authToken: auth.token,
+        requestId,
+      });
     } else if (options.adminAll) {
       if (options.adminCursor) {
         throw cliValidationError(
@@ -289,18 +302,21 @@ export async function adminCommand(options) {
         runId,
         fetchPage: fetchOperation,
         transformPage: transformResult,
-        recordCoverage: async (coverage) =>
-          requestJson({
-            method: "POST",
-            url: `${options.apiUrl}/cli/admin/daily-runs/coverage`,
-            authToken: auth.token,
-            body: coverage,
-            headers: {
-              "x-lumine-admin-run-id": String(runId),
-              "x-lumine-idempotency-key": `cli:queue-coverage:${runId}:${adminValueFingerprint(coverage).slice(0, 32)}`,
-            },
-            timeoutMs: options.timeoutMs,
-          }),
+        recordCoverage: shouldRecordAdminQueueCoverage(runScope)
+          ? async (coverage, signal) =>
+              requestJson({
+                method: "POST",
+                url: `${options.apiUrl}/cli/admin/daily-runs/coverage`,
+                authToken: auth.token,
+                body: coverage,
+                headers: {
+                  "x-lumine-admin-run-id": String(runId),
+                  "x-lumine-idempotency-key": `cli:queue-coverage:${runId}:${adminValueFingerprint(coverage).slice(0, 32)}`,
+                },
+                timeoutMs: options.timeoutMs,
+                signal,
+              })
+          : undefined,
       });
     } else {
       if (options.adminResume) {
@@ -355,7 +371,7 @@ export async function adminCommand(options) {
     assertAiEmailPolicySetResult({ operation, result });
   }
   if (operation.name === "daily-run.start") {
-    assertAdminTodoHandoffResult(result);
+    assertAdminTodoHandoffResult(result, operation.body.scope);
   }
   if (operation.name === "news.claim") {
     const artifacts = writeNewsClaimArtifacts({
@@ -382,6 +398,9 @@ function transformAdminResult({
   if (operation.name === "recommendations.list") {
     assertRecommendationWindowResult({ operation, result: transformed });
   }
+  if (operation.name === "subjects.candidates") {
+    assertSubjectWindowResult({ operation, result: transformed });
+  }
   if (operation.name === "builds.candidates") {
     transformed = normalizeAdminBuildCandidatesResult({
       result: transformed,
@@ -431,6 +450,34 @@ export function assertRecommendationWindowResult({ operation, result }) {
   }
 }
 
+export function assertSubjectWindowResult({ operation, result }) {
+  const mode = operation?.pagination?.coverageMode;
+  if (!mode || mode === "legacy") return;
+  const after = result?.data?.pagination?.after;
+  const snapshotTimeStamp = result?.data?.pagination?.snapshotTimeStamp;
+  if (
+    !Number.isSafeInteger(after) ||
+    after < 0 ||
+    !Number.isSafeInteger(snapshotTimeStamp) ||
+    snapshotTimeStamp < 0
+  ) {
+    const error = new Error(
+      "The deployed API did not confirm the bounded Subject window and snapshot. Deploy the matching API before using this CLI; use --include-legacy only for an intentional historical scan.",
+    );
+    error.code = "LUMINE_ADMIN_SUBJECT_WINDOW_UNSUPPORTED";
+    error.data = {
+      ok: false,
+      status: "validation_error",
+      error: {
+        code: error.code,
+        message: error.message,
+        details: { requestedMode: mode },
+      },
+    };
+    throw error;
+  }
+}
+
 async function finishAdminOutput({ options, operation, result }) {
   const paginationStorage = getPaginatedResultStorage(result);
   if (options.json) {
@@ -449,7 +496,11 @@ async function finishAdminOutput({ options, operation, result }) {
     return result;
   }
   if (paginationStorage) {
-    await printSpooledAdminResult({ result, storage: paginationStorage });
+    await printSpooledAdminResult({
+      operation,
+      result,
+      storage: paginationStorage,
+    });
     return result;
   }
   printAdminResult({ operation, result });
@@ -693,7 +744,64 @@ export function resolveOperatorViewFilter({ operation, unviewed, viewed }) {
   );
 }
 
+function requestedOperatorViewFilter(options) {
+  return options.adminUnviewed
+    ? "unviewed"
+    : options.adminViewed
+      ? "viewed"
+      : null;
+}
+
+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;
+  throw cliValidationError(
+    "The API returned an invalid administrator run scope.",
+  );
+}
+
+export function shouldRecordAdminQueueCoverage(runScope) {
+  return runScope === "full";
+}
+
+const FEATURED_RUN_OPERATIONS = new Set([
+  "subjects.candidates",
+  "subject.get",
+  "subject.comments",
+  "subject.reveal",
+  "subject.feature",
+  "subject.unfeature",
+  "featured.list",
+  "featured.history",
+  "featured.add",
+  "featured.reorder",
+  "featured.rotate",
+  "daily-run.complete",
+  "daily-run.fail",
+]);
+
+export function assertAdminOperationAllowedForRunScope({
+  operation,
+  runScope,
+}) {
+  if (runScope !== "featured") return;
+  const subjectCommentAlias =
+    operation.name === "post.comments" &&
+    /^\/cli\/admin\/subjects\/\d+\/comments(?:\?|$)/.test(operation.path);
+  if (FEATURED_RUN_OPERATIONS.has(operation.name) || subjectCommentAlias) {
+    return;
+  }
+  throw cliValidationError(
+    `A Featured-only run does not authorize ${operation.name}. Complete or fail it before starting a full daily review.`,
+  );
+}
+
 function adminOperationRequiresRun(operation) {
+  if (typeof operation.requiresRun === "boolean") {
+    return operation.requiresRun;
+  }
   return (
     ![
       "identity.list",
@@ -710,6 +818,14 @@ function adminOperationRequiresRun(operation) {
       "escalation.list",
       "escalation.set",
       "notable.add",
+      "notable.status",
+      "runtime-logs.start",
+      "runtime-logs.status",
+      "runtime-logs.capture",
+      "runtime-logs.complete",
+      "runtime-logs.resume",
+      "runtime-logs.abandon",
+      "energy-budget.report",
     ].includes(operation.name) &&
     !operation.name.startsWith("ai-bucket.") &&
     !operation.name.startsWith("ai-email-policy.") &&
@@ -740,7 +856,10 @@ export function parseAdminOperation(options) {
 
   if (namespace === "correction" || namespace === "corrections") {
     if (!action || action === "status") {
-      return readOperation("correction.status", "/cli/admin/corrections/status");
+      return readOperation(
+        "correction.status",
+        "/cli/admin/corrections/status",
+      );
     }
     if (action === "start") {
       const commentId = parseRequiredInteger(target, "comment ID", 1);
@@ -1095,16 +1214,26 @@ export function parseAdminOperation(options) {
 
   if (namespace === "daily-run") {
     if (action === "start") {
+      const runScope = parseDailyRunScope(options.adminScope || "full");
+      const commentMode = parseCommentMode(options.commentMode || "off");
+      if (runScope === "featured" && commentMode !== "off") {
+        throw cliValidationError(
+          "A Featured-only run requires --comment-mode off.",
+        );
+      }
       return writeOperation(
         "daily-run.start",
         "POST",
-        "/cli/admin/daily-runs/start",
+        runScope === "featured"
+          ? "/cli/admin/daily-runs/start/featured"
+          : "/cli/admin/daily-runs/start",
         {
           identity: options.adminIdentity
             ? parseIdentity(options.adminIdentity)
             : undefined,
-          commentMode: parseCommentMode(options.commentMode || "off"),
-          runKey: options.runKey || defaultDailyRunKey(),
+          commentMode,
+          scope: runScope,
+          runKey: options.runKey || defaultDailyRunKey(runScope),
         },
       );
     }
@@ -1112,6 +1241,25 @@ export function parseAdminOperation(options) {
       return readOperation("daily-run.status", "/cli/admin/daily-runs/status");
     }
     if (action === "report") {
+      const positionalRun = String(target || "").trim();
+      const flaggedRun = String(options.adminRun || "").trim();
+      if (
+        extra ||
+        (positionalRun && flaggedRun && positionalRun !== flaggedRun)
+      ) {
+        throw cliValidationError(
+          "Usage: lumine admin daily-run report [--run <completed-run-id>] [--json].",
+        );
+      }
+      const historicalRun = positionalRun || flaggedRun;
+      if (historicalRun) {
+        const runId = parseRequiredInteger(historicalRun, "run ID", 1);
+        return readOperation(
+          "daily-run.report",
+          `/cli/admin/daily-runs/${runId}/report`,
+          { requiresRun: false, historicalRunId: runId },
+        );
+      }
       return readOperation("daily-run.report", "/cli/admin/daily-runs/report");
     }
     if (action === "escalation" && target === "add") {
@@ -1286,13 +1434,21 @@ export function parseAdminOperation(options) {
     if (action === "get") return subjectGetOperation(target, options);
     if (action === "comments") {
       const subjectId = parseSubjectId(target);
+      const operatorView = requestedOperatorViewFilter(options);
       return readOperation(
         "subject.comments",
         withQuery(`/cli/admin/subjects/${subjectId}/comments`, {
           cursor: options.adminCursor,
           limit: options.limit,
         }),
-        { pagination: { collectionKey: "comments" } },
+        {
+          pagination: {
+            collectionKey: "comments",
+            filters: {
+              ...(operatorView ? { operatorView } : {}),
+            },
+          },
+        },
       );
     }
     if (action === "reveal") {
@@ -1330,6 +1486,29 @@ export function parseAdminOperation(options) {
     if (action === "list") {
       return readOperation("featured.list", "/cli/admin/subjects/featured");
     }
+    if (action === "history") {
+      const subjectIds = parseFeaturedSubjectIds(
+        options.adminIds,
+        "--subject-ids",
+      );
+      return readOperation(
+        "featured.history",
+        withQuery("/cli/admin/subjects/featured/history", {
+          subjectIds: subjectIds.join(","),
+          cursor: options.adminCursor,
+          limit: options.limit,
+        }),
+        {
+          pagination: {
+            collectionKey: "events",
+            filters: { subjectIds },
+          },
+        },
+      );
+    }
+    if (action === "add") {
+      return featuredAddOperation(options);
+    }
     if (action === "reorder") {
       return featuredReorderOperation(options);
     }
@@ -1360,13 +1539,21 @@ export function parseAdminOperation(options) {
         parsedTarget.type === "subject"
           ? `/cli/admin/subjects/${parsedTarget.id}/comments`
           : `/cli/admin/posts/${parsedTarget.type}/${parsedTarget.id}/comments`;
+      const operatorView = requestedOperatorViewFilter(options);
       return readOperation(
         "post.comments",
         withQuery(path, {
           cursor: options.adminCursor,
           limit: options.limit,
         }),
-        { pagination: { collectionKey: "comments" } },
+        {
+          pagination: {
+            collectionKey: "comments",
+            filters: {
+              ...(operatorView ? { operatorView } : {}),
+            },
+          },
+        },
       );
     }
     if (action === "recommend") {
@@ -1518,6 +1705,23 @@ export function parseAdminOperation(options) {
     );
   }
 
+  if (namespace === "notable" && action === "status" && !extra) {
+    const rawTarget = String(target || "").trim();
+    if (!rawTarget) {
+      throw cliValidationError(
+        "Usage: lumine admin notable status <userId|username>.",
+      );
+    }
+    const query = /^\d+$/.test(rawTarget)
+      ? { userId: parseRequiredInteger(rawTarget, "user ID", 1) }
+      : { username: rawTarget };
+    return readOperation(
+      "notable.status",
+      withQuery("/cli/admin/notable-users/status", query),
+      { requiresRun: false },
+    );
+  }
+
   if (namespace === "ai-costs") {
     if (action === "monthly" && !target && !extra) {
       if (options.adminDays) {
@@ -1527,7 +1731,105 @@ export function parseAdminOperation(options) {
       }
       return readOperation("ai-costs.monthly", "/cli/admin/ai-costs/monthly");
     }
-    throw cliValidationError("Usage: lumine admin ai-costs monthly [--json].");
+    if (action === "day" && !extra) {
+      if (options.adminDays) {
+        throw cliValidationError(
+          "ai-costs day reads one closed UTC day and does not accept --days.",
+        );
+      }
+      const positionalDay = String(target || "").trim();
+      const flaggedDay = String(options.adminDate || "").trim();
+      if (positionalDay && flaggedDay && positionalDay !== flaggedDay) {
+        throw cliValidationError(
+          "Pass the same UTC day once, either positionally or with --date.",
+        );
+      }
+      const dayKey = parseUtcDayKey(positionalDay || flaggedDay);
+      return readOperation(
+        "ai-costs.day",
+        `/cli/admin/ai-costs/day/${dayKey}`,
+        { requiresRun: false },
+      );
+    }
+    throw cliValidationError(
+      "Usage: lumine admin ai-costs monthly | ai-costs day <YYYY-MM-DD> [--json].",
+    );
+  }
+
+  if (namespace === "energy-budget" && !action) {
+    if (options.adminDays) {
+      const days = Number(options.adminDays);
+      if (!Number.isInteger(days) || days < 1 || days > 31) {
+        throw cliValidationError("--days must be an integer between 1 and 31.");
+      }
+    }
+    return readOperation(
+      "energy-budget.report",
+      withQuery("/cli/admin/energy-budget/report", { days: options.adminDays }),
+      { requiresRun: false },
+    );
+  }
+
+  if (namespace === "runtime-logs") {
+    if (
+      (action === "start" || action === "status" || action === "read") &&
+      !target &&
+      !extra
+    ) {
+      if (
+        action !== "start" &&
+        !String(options.adminReviewSession || "").trim()
+      ) {
+        throw cliValidationError(
+          "Pass the production-log review session with --review-session <file>.",
+        );
+      }
+      return {
+        name:
+          action === "read" ? "runtime-logs.capture" : `runtime-logs.${action}`,
+        method: action === "status" ? "GET" : "POST",
+        path: "",
+        body: undefined,
+        mutates: action !== "status",
+        requiresRun: false,
+        runtimeLogAction: action === "read" ? "capture" : action,
+      };
+    }
+    if ((action === "resume" || action === "abandon") && !target && !extra) {
+      return {
+        name: `runtime-logs.${action}`,
+        method: "POST",
+        path: "",
+        body: undefined,
+        mutates: true,
+        requiresRun: false,
+        runtimeLogAction: action,
+      };
+    }
+    if ((action === "finish" || action === "complete") && !target && !extra) {
+      if (!String(options.adminReviewSession || "").trim()) {
+        throw cliValidationError(
+          "Pass the production-log review session with --review-session <file>.",
+        );
+      }
+      if (!options.adminReviewed) {
+        throw cliValidationError(
+          "Inspect every downloaded runtime-log artifact, then confirm with --reviewed.",
+        );
+      }
+      return {
+        name: "runtime-logs.complete",
+        method: "POST",
+        path: "",
+        body: undefined,
+        mutates: true,
+        requiresRun: false,
+        runtimeLogAction: "complete",
+      };
+    }
+    throw cliValidationError(
+      "Usage: lumine admin runtime-logs start | status|read --review-session <file> | finish --review-session <file> --reviewed | resume | abandon [--review-session <file>].",
+    );
   }
 
   if (namespace === "media-costs") {
@@ -1779,15 +2081,19 @@ export function parseAdminOperation(options) {
   }
 
   throw cliValidationError(
-    "Usage: lumine admin identity|economy|rescue|sponsor|daily-run|escalation|todo|recommendations|builds|post|subjects|subject|featured|comment|announcement|chat|news|audit|brief|ai-costs|media-costs|bot-output|notable ...",
+    "Usage: lumine admin identity|economy|rescue|sponsor|daily-run|escalation|todo|recommendations|builds|post|subjects|subject|featured|comment|announcement|chat|news|audit|brief|ai-costs|media-costs|energy-budget|runtime-logs|bot-output|notable ...",
   );
 }
 
 function subjectsListOperation(options) {
+  const operatorView = requestedOperatorViewFilter(options);
+  const subjectWindow = parseSubjectWindow(options);
   return readOperation(
     "subjects.candidates",
     withQuery("/cli/admin/subjects", {
-      after: options.adminAfter,
+      sinceRun: subjectWindow.mode === "since-run" ? "true" : "",
+      after: subjectWindow.mode === "after" ? subjectWindow.after : "",
+      includeLegacy: subjectWindow.mode === "legacy" ? "true" : "",
       cursor: options.adminCursor,
       effort: options.adminEffort,
       limit: options.limit,
@@ -1796,11 +2102,15 @@ function subjectsListOperation(options) {
       pagination: {
         collectionKey: "subjects",
         coverageQueue: "subjects",
-        coverageMode: options.adminAfter ? "after" : "all",
-        after: options.adminAfter
-          ? parseAfterForCoverage(options.adminAfter)
-          : null,
-        filters: { effort: options.adminEffort || "all" },
+        coverageMode: subjectWindow.mode,
+        after:
+          subjectWindow.mode === "after"
+            ? parseAfterForCoverage(subjectWindow.after)
+            : null,
+        filters: {
+          effort: options.adminEffort || "all",
+          ...(operatorView ? { operatorView } : {}),
+        },
       },
     },
   );
@@ -1890,6 +2200,22 @@ function featuredReorderOperation(options) {
   );
 }
 
+function featuredAddOperation(options) {
+  const addIds = parseFeaturedSubjectIds(options.adminIds, "--subject-ids");
+  const postedAfter = String(options.adminPostedAfter || "").trim();
+  if (!postedAfter) {
+    throw cliValidationError(
+      "New Featured additions require --posted-after <ISO-8601-or-Unix-time>.",
+    );
+  }
+  return writeOperation(
+    "featured.add",
+    "POST",
+    "/cli/admin/subjects/featured/additions",
+    { addIds, postedAfter },
+  );
+}
+
 function featuredRotateOperation(options) {
   const removeIds = parseFeaturedSubjectIds(
     options.adminRemoveIds,
@@ -1961,6 +2287,42 @@ export function parseRecommendationWindow(options) {
   return { mode, after: mode === "after" ? options.adminAfter : "" };
 }
 
+export function parseSubjectWindow(options) {
+  const selected = [
+    options.adminSinceRun ? "since-run" : "",
+    options.adminAfter ? "after" : "",
+    options.adminIncludeLegacy ? "legacy" : "",
+  ].filter(Boolean);
+  if (selected.length > 1) {
+    throw cliValidationError(
+      "Choose one Subject 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);
+  if (!match) {
+    throw cliValidationError(
+      "Pass a real UTC calendar date in YYYY-MM-DD format.",
+    );
+  }
+  const parsed = new Date(`${dayKey}T00:00:00.000Z`);
+  if (
+    !Number.isFinite(parsed.getTime()) ||
+    parsed.toISOString().slice(0, 10) !== dayKey
+  ) {
+    throw cliValidationError(
+      "Pass a real UTC calendar date in YYYY-MM-DD format.",
+    );
+  }
+  return dayKey;
+}
+
 function parseAfterForCoverage(value) {
   const raw = String(value || "").trim();
   if (/^\d+$/.test(raw)) {
@@ -2151,12 +2513,40 @@ export function formatAdminJsonError(error) {
   };
 }
 
-export function assertAdminTodoHandoffResult(result) {
+export function assertAdminTodoHandoffResult(result, expectedRunScope = null) {
   const runId = Number(result?.data?.run?.id || 0);
+  const runScope = canonicalAdminRunScope(result?.data?.run);
+  if (expectedRunScope && runScope !== expectedRunScope) {
+    const error = cliValidationError(
+      `The API returned a ${runScope} run when the CLI requested ${expectedRunScope}.`,
+    );
+    error.code = "LUMINE_ADMIN_RUN_SCOPE_UNSUPPORTED";
+    throw error;
+  }
   const handoff = result?.data?.carryoverTodos;
+  if (runScope === "featured") {
+    if (
+      !runId ||
+      !handoff ||
+      handoff.included !== false ||
+      !Array.isArray(handoff.items) ||
+      handoff.items.length !== 0 ||
+      Number(handoff.count) !== 0 ||
+      handoff.surfacedForRunId !== null ||
+      Number(handoff.newlySurfacedCount) !== 0
+    ) {
+      const error = cliValidationError(
+        "The API did not confirm that carry-over telemetry was suppressed for the Featured-only run.",
+      );
+      error.code = "LUMINE_ADMIN_SCOPED_RUN_UNSUPPORTED";
+      throw error;
+    }
+    return handoff;
+  }
   if (
     !runId ||
     !handoff ||
+    handoff.included === false ||
     !Array.isArray(handoff.items) ||
     Number(handoff.count) !== handoff.items.length ||
     Number(handoff.surfacedForRunId) !== runId ||
@@ -2223,6 +2613,16 @@ function parseCommentMode(value) {
   return mode;
 }
 
+function parseDailyRunScope(value) {
+  const scope = String(value || "full")
+    .trim()
+    .toLowerCase();
+  if (!["full", "featured"].includes(scope)) {
+    throw cliValidationError("--scope must be full or featured.");
+  }
+  return scope;
+}
+
 function parseEscalationStatus(value) {
   const status = String(value || "")
     .trim()
@@ -2436,7 +2836,7 @@ function parseChoice(value, label, choices) {
   return normalized;
 }
 
-function defaultDailyRunKey() {
+function defaultDailyRunKey(runScope = "full") {
   const parts = new Intl.DateTimeFormat("en-CA", {
     timeZone: "Asia/Bangkok",
     year: "numeric",
@@ -2446,7 +2846,10 @@ function defaultDailyRunKey() {
   const value = Object.fromEntries(
     parts.map((part) => [part.type, part.value]),
   );
-  return `daily:${value.year}-${value.month}-${value.day}`;
+  const day = `${value.year}-${value.month}-${value.day}`;
+  return runScope === "full"
+    ? `daily:${day}`
+    : `scoped:${runScope}:${day}:${randomUUID()}`;
 }
 
 function cliValidationError(message) {
@@ -2524,6 +2927,48 @@ function printAdminMonthlyAiCosts(monthlyAiCosts) {
   }
 }
 
+function printAdminDailyAiCosts(dailyAiCosts) {
+  console.log(
+    `Application AI-cost ledger for ${dailyAiCosts.day.dayKey} (closed UTC day): ${formatAdminUsd(dailyAiCosts.summary?.estimatedCostUsd)} across ${Number(dailyAiCosts.summary?.requestCount || 0)} request(s).`,
+  );
+  for (const row of dailyAiCosts.byProviderModel || []) {
+    console.log(
+      `  ${row.provider || "unknown"}/${row.model || "unknown"}: ${formatAdminUsd(row.estimatedCostUsd)} · ${Number(row.totalTokens || 0)} token(s) · ${Number(row.requestCount || 0)} request(s).`,
+    );
+  }
+}
+
+function printAdminEnergyBudget(energyBudget) {
+  const headline = energyBudget.lastCompletedDay;
+  if (headline) {
+    console.log(
+      `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(
+    "day        | charged | overflow | users | rechg | runs | calls/run avg/p90 | $/run avg/p90 | stops chg/unchg | busy | telemetry rows",
+  );
+  for (const day of energyBudget.byDay || []) {
+    const m = day.telemetry.metrics;
+    const runs = day.runs.total;
+    console.log(
+      `${day.dayKey}${day.inProgress ? "*" : " "}| ${formatAdminUsd(day.chargedUsd).padStart(7)} | ${formatAdminUsd(day.overflowUsd).padStart(8)} | ${String(day.users).padStart(5)} | ${String(day.recharges).padStart(5)} | ${String(runs.runs).padStart(4)} | ${String(runs.callsPerRun.avg).padStart(7)}/${String(runs.callsPerRun.p90).padEnd(9)} | ${formatAdminUsd(runs.usdPerRun.avg).padStart(6)}/${formatAdminUsd(runs.usdPerRun.p90).padEnd(6)} | ${String(m.budget_stop_changed.count).padStart(7)}/${String(m.budget_stop_unchanged.count).padEnd(7)} | ${String(m.busy_refusal.count).padStart(4)} | ${day.telemetry.rowCount}`,
+    );
+  }
+  console.log("* = in-progress UTC day; never headline it.");
+  const flags = energyBudget.flags || [];
+  if (flags.length === 0) {
+    console.log("Flags: none.");
+    return;
+  }
+  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}`);
+  }
+}
+
 function formatAdminMediaUsd(value) {
   const amount = Number(value);
   if (!Number.isFinite(amount)) return "unavailable";
@@ -2650,10 +3095,16 @@ function printAdminMonthlyMediaCosts(monthlyMediaCosts) {
   );
 }
 
-async function printSpooledAdminResult({ result, storage }) {
+async function printSpooledAdminResult({ operation, result, storage }) {
   const data = result?.data || {};
   const count = Number(storage.candidateCount || 0);
-  if (storage.collectionKey === "subjects") {
+  if (operation.name === "featured.history") {
+    printFeaturedHistorySummary(data);
+    console.log(`${count} Featured history event(s):`);
+    await forEachPaginatedResultItem(result, async (event) => {
+      printFeaturedHistoryEvent(event);
+    });
+  } else if (storage.collectionKey === "subjects") {
     console.log(`${count} subject(s):`);
     await forEachPaginatedResultItem(result, async (subject) => {
       console.log(
@@ -2779,6 +3230,28 @@ function printAdminResult({ operation, result }) {
     );
     return;
   }
+  if (data.review && data.artifacts?.reviewSessionPath) {
+    console.log(
+      `Production-log review #${data.review.id}: ${data.completionStatus || data.review.status}.`,
+    );
+    console.log(`Review session: ${data.artifacts.reviewSessionPath}`);
+    if (data.artifacts.latestSnapshot?.snapshotPath) {
+      console.log(
+        `Latest captured bytes: ${data.artifacts.latestSnapshot.snapshotPath}`,
+      );
+    }
+    if (
+      data.completionStatus === "needs_review" ||
+      data.completionStatus === "post_clear_review_required"
+    ) {
+      console.log(
+        data.completionStatus === "post_clear_review_required"
+          ? "The API error log was cleared in place. Review the post-clear snapshot, then rerun finish with --reviewed to close the lease."
+          : "New bytes arrived at the final boundary. Review the latest snapshot, then rerun finish with --reviewed.",
+      );
+    }
+    return;
+  }
   if (data.review) {
     console.log(
       `Confirmed Build #${data.review.buildId} runtime at published artifact #${data.review.publishedArtifactVersionId}.`,
@@ -2791,6 +3264,14 @@ function printAdminResult({ operation, result }) {
     printAdminMonthlyAiCosts(data.monthlyAiCosts);
     return;
   }
+  if (data.dailyAiCosts) {
+    printAdminDailyAiCosts(data.dailyAiCosts);
+    return;
+  }
+  if (data.energyBudget) {
+    printAdminEnergyBudget(data.energyBudget);
+    return;
+  }
   if (data.monthlyMediaCosts) {
     printAdminMonthlyMediaCosts(data.monthlyMediaCosts);
     return;
@@ -2810,8 +3291,9 @@ function printAdminResult({ operation, result }) {
   }
   if (data.report) {
     const report = data.report;
+    const historical = report.basis?.kind === "historical_reconstruction";
     console.log(
-      `Run #${report.run.id}: ${report.mutations.successfulMutationCount} successful mutation(s), ${report.queueCoverage.length} queue coverage record(s), ${report.escalations.length} escalation(s), ${report.carryoverTodos?.count || 0} unfinished todo(s).`,
+      `${historical ? "Historical reconstruction for run" : "Run"} #${report.run.id}: ${report.mutations.successfulMutationCount} successful mutation(s), ${report.queueCoverage.length} queue coverage record(s), ${report.escalations.length} escalation(s)${historical ? "." : `, ${report.carryoverTodos?.count || 0} unfinished todo(s).`}`,
     );
     for (const coverage of report.queueCoverage) {
       console.log(
@@ -2826,10 +3308,21 @@ function printAdminResult({ operation, result }) {
         `  ${String(escalation.severity || "attention").toUpperCase()} ${target} — ${escalation.summary}`,
       );
     }
-    printTodoItems(report.carryoverTodos?.items || [], "Unfinished work");
+    if (historical) {
+      console.log(
+        "The live brief and carry-over todo state were not snapshotted for this completed run.",
+      );
+    } else {
+      printTodoItems(report.carryoverTodos?.items || [], "Unfinished work");
+    }
     if (report.sponsorIntegrity) {
+      const pendingApplications = Number.isSafeInteger(
+        report.sponsorIntegrity.pendingApplications,
+      )
+        ? `; ${report.sponsorIntegrity.pendingApplications} pending application(s)`
+        : "; historical pending-application count unavailable";
       console.log(
-        `Sponsor integrity: ${report.sponsorIntegrity.scan?.status || "not started"}; ${report.sponsorIntegrity.cases?.open || 0} open case(s); ${report.sponsorIntegrity.pendingApplications || 0} pending application(s).`,
+        `Sponsor integrity: ${report.sponsorIntegrity.scan?.status || "not started"}; ${report.sponsorIntegrity.cases?.open || 0} open case(s)${pendingApplications}.`,
       );
     }
     const surfaces = report.brief?.engagementPulse?.surfaces;
@@ -2849,10 +3342,12 @@ function printAdminResult({ operation, result }) {
       if (deltas.length)
         console.log(`Engagement deltas: ${deltas.join(", ")}.`);
     }
-    const notableCount = Array.isArray(report.brief?.notableCandidates)
-      ? report.brief.notableCandidates.length
-      : 0;
-    console.log(`Notable-user candidates in this brief: ${notableCount}.`);
+    if (!historical) {
+      const notableCount = Array.isArray(report.brief?.notableCandidates)
+        ? report.brief.notableCandidates.length
+        : 0;
+      console.log(`Notable-user candidates in this brief: ${notableCount}.`);
+    }
     return;
   }
   if (data.inspection) {
@@ -2916,6 +3411,15 @@ function printAdminResult({ operation, result }) {
     printTodoItems([data.todo], "Canonical todo");
     return;
   }
+  if (Object.hasOwn(data, "isNotable") && data.user) {
+    console.log(
+      `${data.user.username} (user #${data.user.id}) is${data.isNotable ? "" : " not"} currently in Notable Users.`,
+    );
+    if (data.notableUser?.reason) {
+      console.log(`Reason: ${data.notableUser.reason}`);
+    }
+    return;
+  }
   if (data.bucket && Array.isArray(data.memberUserIds)) {
     const added = Array.isArray(data.accounts)
       ? `; added ${data.accounts.length} explicit account(s)`
@@ -2930,13 +3434,13 @@ function printAdminResult({ operation, result }) {
       console.log("No active delegated administrator daily run.");
       if (data.lastRun) {
         console.log(
-          `Last run #${data.lastRun.id}: ${data.lastRun.status}; identity ${data.lastRun.identity.key}; comments ${data.lastRun.commentMode}.`,
+          `Last run #${data.lastRun.id}: ${data.lastRun.status}; scope ${canonicalAdminRunScope(data.lastRun)}; identity ${data.lastRun.identity.key}; comments ${data.lastRun.commentMode}.`,
         );
       }
       return;
     }
     console.log(
-      `Run #${data.run.id}: ${data.run.status}; identity ${data.run.identity.key}; comments ${data.run.commentMode}.`,
+      `Run #${data.run.id}: ${data.run.status}; scope ${canonicalAdminRunScope(data.run)}; identity ${data.run.identity.key}; comments ${data.run.commentMode}.`,
     );
     if (data.scheduledDay && data.scheduledIdentity) {
       console.log(
@@ -2967,11 +3471,20 @@ function printAdminResult({ operation, result }) {
     );
     console.log(
       data.activeRun
-        ? `Active run #${data.activeRun.id}: ${data.activeRun.identity.key}; comments ${data.activeRun.commentMode}.`
+        ? `Active run #${data.activeRun.id}: scope ${canonicalAdminRunScope(data.activeRun)}; identity ${data.activeRun.identity.key}; comments ${data.activeRun.commentMode}.`
         : "No active delegated administrator daily run.",
     );
     return;
   }
+  if (operation.name === "featured.history") {
+    printFeaturedHistorySummary(data);
+    console.log(`${(data.events || []).length} Featured history event(s):`);
+    for (const event of data.events || []) {
+      printFeaturedHistoryEvent(event);
+    }
+    printPagination(data.pagination);
+    return;
+  }
   if (Array.isArray(data.subjects)) {
     console.log(`${data.subjects.length} subject(s):`);
     for (const subject of data.subjects) {
@@ -3138,6 +3651,32 @@ function printAdminResult({ operation, result }) {
   );
 }
 
+function printFeaturedHistorySummary(data) {
+  const coverage = data.coverage || {};
+  console.log(
+    coverage.complete
+      ? `Featured history coverage begins at ${coverage.startedAt}.`
+      : "Featured history coverage is not complete.",
+  );
+  for (const subject of data.subjects || []) {
+    const lifetime = subject.knownFeatured
+      ? "previously Featured"
+      : subject.neverFeatured === true
+        ? "never Featured"
+        : "history unknown";
+    console.log(
+      `#${subject.id} ${subject.title || "(untitled)"} — ${lifetime}${subject.featured?.member ? ` — current position ${subject.featured.order}` : ""}`,
+    );
+    console.log(`  ${subject.url}`);
+  }
+}
+
+function printFeaturedHistoryEvent(event) {
+  console.log(
+    `#${event.id} subject:${event.subjectId} ${event.action} ${event.fromPosition ?? "-"}->${event.toPosition ?? "-"} — ${event.operation}`,
+  );
+}
+
 function printTodoItems(items, heading) {
   console.log(`${heading}: ${items.length} item(s).`);
   for (const todo of items) {