@stage5/lumine 0.3.54 → 0.3.58

package/lib/admin-spending.js

@@ -0,0 +1,472 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+const round = (value) => {
+  if (!Number.isFinite(value))
+    throw new Error("Invalid computed spending amount.");
+  return Number(value.toFixed(8));
+};
+const USAGE =
+  "lumine admin spending [--month YYYY-MM | --from YYYY-MM --to YYYY-MM] [--aws-profile <profile>] [--json]";
+
+function invalid(message) {
+  return Object.assign(new Error(message), {
+    code: "CLI_ADMIN_CLI_VALIDATION",
+  });
+}
+
+export function buildSpendingOperation(options) {
+  if (
+    (options.positional || []).length !== 1 ||
+    options.adminDays ||
+    options.adminDate ||
+    options.adminAll ||
+    options.adminResume
+  ) {
+    throw invalid(`Usage: ${USAGE}.`);
+  }
+  const query = new URLSearchParams();
+  const values = {
+    month: options.adminSpendingMonth,
+    from: options.adminSpendingFrom,
+    to: options.adminSpendingTo,
+  };
+  for (const [key, value] of Object.entries(values)) {
+    if (value === undefined) continue;
+    if (typeof value !== "string" || !/^20\d{2}-(0[1-9]|1[0-2])$/.test(value))
+      throw invalid(`--${key} must use YYYY-MM format.`);
+    query.set(key, value);
+  }
+  if (query.has("month") && (query.has("from") || query.has("to")))
+    throw invalid("Use --month or --from/--to, not both.");
+  if (query.has("from") !== query.has("to"))
+    throw invalid("Provide both --from and --to.");
+  if (query.has("from") && query.get("from") > query.get("to"))
+    throw invalid("--from must not follow --to.");
+  const qs = query.toString();
+  return {
+    name: "spending.report",
+    method: "GET",
+    path: `/cli/admin/spending${qs ? `?${qs}` : ""}`,
+    mutates: false,
+    requiresRun: false,
+    timeoutMs: 60000,
+  };
+}
+
+async function runAws(args, { profile, region, timeoutMs }) {
+  try {
+    const { stdout } = await execFileAsync(
+      "aws",
+      [
+        ...args,
+        "--profile",
+        profile,
+        "--region",
+        region,
+        "--output",
+        "json",
+        "--no-cli-pager",
+      ],
+      {
+        encoding: "utf8",
+        timeout: timeoutMs,
+        maxBuffer: 8 * 1024 * 1024,
+        env: { ...process.env, AWS_PAGER: "", AWS_CLI_AUTO_PROMPT: "off" },
+      },
+    );
+    return JSON.parse(stdout);
+  } catch (error) {
+    // Do not expose subprocess stdout, credentials or arbitrary provider error
+    // payloads in a saved financial report.
+    throw new Error(
+      error.code === "ENOENT"
+        ? "AWS CLI is not installed. Install it and configure the requested profile."
+        : `AWS billing could not be read with profile ${profile}; check its authentication and Cost Explorer access.`,
+    );
+  }
+}
+
+function amount(metric) {
+  if (
+    metric?.Unit !== "USD" ||
+    metric.Amount === "" ||
+    metric.Amount == null ||
+    !Number.isFinite(Number(metric.Amount))
+  ) {
+    throw new Error(
+      "AWS returned an invalid amount or a currency other than USD.",
+    );
+  }
+  return Number(metric.Amount);
+}
+
+export function normalizeAwsSpending(pages, months) {
+  const expected = new Map(
+    months
+      .filter((m) => m.startDayKey < m.endDayKeyExclusive)
+      .map((m) => [m.startDayKey, m]),
+  );
+  const found = new Map();
+  for (const page of pages) {
+    if (!Array.isArray(page?.ResultsByTime))
+      throw new Error("AWS returned no billing periods.");
+    for (const period of page.ResultsByTime) {
+      const start = period.TimePeriod?.Start;
+      const requested = expected.get(start);
+      if (
+        !requested ||
+        period.TimePeriod?.End !== requested.endDayKeyExclusive ||
+        typeof period.Estimated !== "boolean"
+      ) {
+        throw new Error(
+          "AWS billing periods do not match the requested UTC months.",
+        );
+      }
+      let target = found.get(start);
+      if (!target) {
+        target = {
+          status: "available",
+          costUsd: 0,
+          estimated: period.Estimated,
+          services: [],
+          startDayKey: start,
+          endDayKeyExclusive: period.TimePeriod.End,
+        };
+        found.set(start, target);
+      }
+      if (
+        target.estimated !== period.Estimated ||
+        !Array.isArray(period.Groups)
+      )
+        throw new Error("Inconsistent AWS billing page.");
+      if (
+        period.Groups.length === 0 &&
+        period.Total?.UnblendedCost &&
+        amount(period.Total.UnblendedCost) !== 0
+      ) {
+        throw new Error("AWS omitted the requested service breakdown.");
+      }
+      for (const group of period.Groups) {
+        if (
+          !Array.isArray(group.Keys) ||
+          group.Keys.length !== 1 ||
+          typeof group.Keys[0] !== "string" ||
+          target.services.some((s) => s.service === group.Keys[0])
+        )
+          throw new Error("Duplicate or invalid AWS service row.");
+        const costUsd = amount(group.Metrics?.UnblendedCost);
+        target.services.push({ service: group.Keys[0], costUsd });
+        target.costUsd += costUsd;
+      }
+    }
+  }
+  if (found.size !== expected.size)
+    throw new Error("AWS billing is missing a requested month.");
+  return months.map((month) => {
+    if (month.startDayKey === month.endDayKeyExclusive)
+      return {
+        status: "no_completed_days",
+        costUsd: 0,
+        estimated: true,
+        services: [],
+        startDayKey: month.startDayKey,
+        endDayKeyExclusive: month.endDayKeyExclusive,
+      };
+    const value = found.get(month.startDayKey);
+    return {
+      ...value,
+      costUsd: round(value.costUsd),
+      services: value.services.sort((a, b) => b.costUsd - a.costUsd),
+    };
+  });
+}
+
+function validateReport(report) {
+  if (
+    report?.schemaVersion !== 1 ||
+    report.currency !== "USD" ||
+    report.timezone !== "UTC" ||
+    !Array.isArray(report.months) ||
+    !report.months.length ||
+    report.months.length > 12 ||
+    !report.sources?.aws ||
+    report.range?.includesInProgressDay !== false
+  ) {
+    throw new Error(
+      "The API did not return a supported spending report; deploy the matching API release.",
+    );
+  }
+  let expectedStart = report.range.startDayKey;
+  for (const month of report.months) {
+    const nextMonth = new Date(
+      Date.UTC(
+        Number(month.monthKey?.slice(0, 4)),
+        Number(month.monthKey?.slice(5, 7)),
+        1,
+      ),
+    )
+      .toISOString()
+      .slice(0, 10);
+    if (
+      !/^20\d{2}-(0[1-9]|1[0-2])$/.test(month.monthKey) ||
+      month.startDayKey !== `${month.monthKey}-01` ||
+      month.startDayKey !== expectedStart ||
+      !/^20\d{2}-\d{2}-\d{2}$/.test(month.endDayKeyExclusive) ||
+      month.endDayKeyExclusive < month.startDayKey ||
+      month.endDayKeyExclusive > nextMonth ||
+      (month.status === "closed" && month.endDayKeyExclusive !== nextMonth) ||
+      (month !== report.months.at(-1) &&
+        month.endDayKeyExclusive !== nextMonth) ||
+      new Date(`${month.endDayKeyExclusive}T00:00:00Z`)
+        .toISOString()
+        .slice(0, 10) !== month.endDayKeyExclusive
+    ) {
+      throw new Error("The API spending report has invalid month boundaries.");
+    }
+    expectedStart = nextMonth;
+    // An available source must supply its amounts. In particular, null paid
+    // totals must never be coerced to zero when combined with operating costs.
+    const required = [
+      ...(month.ai ? [month.ai.grossUsd] : []),
+      ...(month.reimbursements
+        ? [
+            month.reimbursements.aiServiceUsd,
+            month.reimbursements.infrastructureUsd,
+            month.reimbursements.totalUsd,
+          ]
+        : []),
+    ];
+    if (
+      required.some(
+        (value) => typeof value !== "number" || !Number.isFinite(value),
+      )
+    )
+      throw new Error("The API spending report has incomplete source amounts.");
+    for (const value of [
+      month.ai?.grossUsd,
+      month.ai?.creditUsd,
+      month.ai?.estimatedCashUsd,
+      month.reimbursements?.aiServiceUsd,
+      month.reimbursements?.infrastructureUsd,
+      month.reimbursements?.totalUsd,
+    ]) {
+      if (
+        value != null &&
+        (typeof value !== "number" || !Number.isFinite(value) || value < 0)
+      )
+        throw new Error("Invalid spending source amount.");
+    }
+  }
+  if (
+    report.months.at(-1).endDayKeyExclusive !== report.range.endDayKeyExclusive
+  )
+    throw new Error("The API spending report has incomplete month coverage.");
+}
+
+export async function completeSpendingReport(receipt, options, aws = runAws) {
+  if (receipt?.ok !== true) return receipt;
+  const report = receipt.data?.spending;
+  validateReport(report);
+  const warnings = [...(report.warnings || [])];
+  const source = report.sources.aws;
+  const profile = options.adminAwsProfile || source.defaultProfile;
+  if (typeof profile !== "string" || !profile.trim())
+    throw invalid("--aws-profile must name an AWS CLI profile.");
+  let awsMonths = null;
+  let awsError = null;
+  try {
+    const settings = {
+      profile,
+      region: source.region,
+      timeoutMs: Math.max(
+        1000,
+        Math.min(60000, Number(options.timeoutMs) || 30000),
+      ),
+    };
+    const hasCompletedDays =
+      report.range.startDayKey < report.range.endDayKeyExclusive;
+    const pages = [];
+    if (hasCompletedDays) {
+      const identity = await aws(["sts", "get-caller-identity"], settings);
+      if (
+        identity?.Account !== source.accountId ||
+        identity?.Arn !== source.principalArn
+      ) {
+        throw new Error(
+          "AWS identity does not match the Twinkle billing principal. No Cost Explorer query was sent.",
+        );
+      }
+      let token;
+      const seen = new Set();
+      do {
+        if (pages.length >= 100)
+          throw new Error("AWS billing exceeded the pagination limit.");
+        const page = await aws(
+          [
+            "ce",
+            "get-cost-and-usage",
+            "--time-period",
+            `Start=${report.range.startDayKey},End=${report.range.endDayKeyExclusive}`,
+            "--granularity",
+            "MONTHLY",
+            "--metrics",
+            "UnblendedCost",
+            "--group-by",
+            "Type=DIMENSION,Key=SERVICE",
+            "--no-paginate",
+            ...(token ? ["--next-page-token", token] : []),
+          ],
+          settings,
+        );
+        pages.push(page);
+        token = page.NextPageToken;
+        if (token && (typeof token !== "string" || seen.has(token)))
+          throw new Error("AWS billing pagination did not advance.");
+        if (token) seen.add(token);
+      } while (token);
+    }
+    awsMonths = normalizeAwsSpending(pages, report.months);
+  } catch (error) {
+    awsError = error.message;
+    warnings.push(awsError);
+  }
+  const months = report.months.map((month, i) => {
+    const billing = awsMonths?.[i] ?? null;
+    const overlap = month.ai?.awsOverlapDetected === true;
+    if (overlap)
+      warnings.push(
+        `${month.monthKey}: AWS-billed AI detected; combined totals require overlap reconciliation.`,
+      );
+    const operating =
+      month.ai?.estimatedCashUsd != null && billing && !overlap
+        ? round(month.ai.estimatedCashUsd + billing.costUsd)
+        : null;
+    return {
+      ...month,
+      aws: billing,
+      providerOperatingCostUsd: operating,
+      totalIncludingReimbursementsUsd:
+        operating !== null && month.reimbursements
+          ? round(operating + month.reimbursements.totalUsd)
+          : null,
+    };
+  });
+  const complete = months.every(
+    (m) => m.totalIncludingReimbursementsUsd !== null,
+  );
+  const sum = (select) =>
+    months.every((m) => select(m) != null)
+      ? round(months.reduce((n, m) => n + select(m), 0))
+      : null;
+  return {
+    ...receipt,
+    status: complete ? "success" : "partial",
+    data: {
+      ...receipt.data,
+      spending: {
+        ...report,
+        complete,
+        months,
+        warnings,
+        sources: {
+          ...report.sources,
+          aws: {
+            ...source,
+            profile,
+            status: awsMonths ? "available" : "unavailable",
+            error: awsError,
+          },
+        },
+        totals: {
+          aiEstimatedCashUsd: sum((m) => m.ai?.estimatedCashUsd),
+          awsUsd: sum((m) => m.aws?.costUsd),
+          reimbursementsUsd: sum((m) => m.reimbursements?.totalUsd),
+          totalIncludingReimbursementsUsd: sum(
+            (m) => m.totalIncludingReimbursementsUsd,
+          ),
+        },
+      },
+    },
+  };
+}
+
+export function formatSpending(report) {
+  const money = (value) =>
+    value == null
+      ? "Unavailable"
+      : `$${value.toLocaleString("en-US", { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`;
+  const lines = [
+    `Twinkle spending · USD · UTC · ${report.complete ? "complete sources" : "INCOMPLETE SOURCES"}`,
+  ];
+  const rows = [
+    ["Category", ...report.months.map((m) => m.monthKey)],
+    [
+      "AI after credits",
+      ...report.months.map((m) => money(m.ai?.estimatedCashUsd)),
+    ],
+    ["AWS (including tax)", ...report.months.map((m) => money(m.aws?.costUsd))],
+    [
+      "Reimbursements",
+      ...report.months.map((m) => money(m.reimbursements?.totalUsd)),
+    ],
+    [
+      "TOTAL incl. reimbursements",
+      ...report.months.map((m) => money(m.totalIncludingReimbursementsUsd)),
+    ],
+    ["", ...report.months.map(() => "")],
+    ["AI before credits", ...report.months.map((m) => money(m.ai?.grossUsd))],
+    ["Promotional credit", ...report.months.map((m) => money(m.ai?.creditUsd))],
+    [
+      "Reimbursement: AI service",
+      ...report.months.map((m) => money(m.reimbursements?.aiServiceUsd)),
+    ],
+    [
+      "Reimbursement: infrastructure",
+      ...report.months.map((m) => money(m.reimbursements?.infrastructureUsd)),
+    ],
+  ];
+  const widths = rows[0].map((_, i) =>
+    Math.max(...rows.map((row) => row[i].length)),
+  );
+  lines.push(
+    ...rows.map((row) =>
+      row
+        .map((cell, i) =>
+          i ? cell.padStart(widths[i]) : cell.padEnd(widths[i]),
+        )
+        .join(" | "),
+    ),
+  );
+  for (const month of report.months) {
+    if (month.status === "in_progress")
+      lines.push(
+        `${month.monthKey} AI/AWS: ${month.throughDayKey ? `through ${month.throughDayKey} UTC` : "no completed UTC days"}; current usage day excluded.`,
+      );
+    if (month.aws?.estimated)
+      lines.push(
+        `${month.monthKey} AWS is provisional and may change with billing updates.`,
+      );
+  }
+  lines.push(
+    `Selected-period total: ${money(report.totals.totalIncludingReimbursementsUsd)}`,
+  );
+  lines.push(
+    "AI is a usage-based estimate after credits. AWS estimated flags and service details are in JSON.",
+  );
+  lines.push(
+    "Reimbursements are gross paid amounts by payment date, before refunds/fees; included once in the total above.",
+  );
+  if (report.sources.reimbursements?.includesCurrentDay)
+    lines.push(
+      `Reimbursements include today's settled payments through ${new Date((report.sources.reimbursements.endAtExclusive - 1) * 1000).toISOString()}.`,
+    );
+  if (report.inProgressDay)
+    lines.push(
+      `${report.inProgressDay.dayKey} partial AI usage: ${money(report.inProgressDay.ai?.grossUsd)} before credits, excluded.`,
+    );
+  for (const warning of report.warnings || [])
+    lines.push(`Unavailable: ${warning}`);
+  return lines.join("\n");
+}

package/lib/admin.js

@@ -44,6 +44,7 @@ import {
   printOwnerTrace,
 } from "./admin-owner-trace.js";
 import { buildRolesOperation, printRoles } from "./admin-roles.js";
+import { buildSpendingOperation, completeSpendingReport, formatSpending } from "./admin-spending.js";
 import { buildCraftOperation, formatCraftResult } from "./admin-craft.js";
 import { buildNonogramOperation, formatNonogramResult } from './admin-nonogram.js';
 import {
@@ -380,7 +381,7 @@ function buildApprovalOperation({ action, target, options }) {
       "approvals.decide",
       "POST",
       `/cli/admin/approvals/${id}`,
-      { decision: action, reason },
+      { decision: action, reason, ...(options.adminFingerprint ? { fingerprint: String(options.adminFingerprint) } : {}) },
       { requiresRun: false },
     );
   }
@@ -1545,7 +1546,10 @@ export async function adminCommand(options) {
         recommendationContentTypes,
         viewFilter,
       });
-    if (operation.featuredWorkflow) {
+    if (operation.name === "spending.report") {
+      result = await completeSpendingReport(await fetchOperation(), options);
+      if (result.status === "partial") process.exitCode = 1;
+    } else if (operation.featuredWorkflow) {
       result = await runFeaturedWorkflow({
         options,
         operation,
@@ -1624,6 +1628,11 @@ export async function adminCommand(options) {
     // private evidence is printed, never kept in the receipt file
     mutationIntent?.confirm(receiptToKeep(operation, result));
   } catch (error) {
+    if (operation.name === "spending.report" && error.status === 404) {
+      error.message = "The spending report API is not deployed yet. Deploy the matching API before using this CLI command.";
+      error.code = "CLI_ADMIN_SPENDING_NOT_DEPLOYED";
+      error.data = { ok: false, status: "unavailable", error: { code: error.code, message: error.message, details: null } };
+    }
     if (operation.name === "runtime.evidence" && error.status === 404) {
       error.code = "CLI_ADMIN_RUNTIME_EVIDENCE_NOT_DEPLOYED";
       error.message =
@@ -3077,11 +3086,11 @@ export function parseAdminOperation(options) {
   }
 
   if (MEETUP_NAMESPACES.has(namespace)) {
-    // Bridge Builder crews (achievement type 'meetup'): the same admin tools as
-    // the website. Crews no longer wait for staff approvals (check-ins are the
-    // proof, 2026-10-17). Mikey's own decision, any time, never in a daily run.
+    // Bridge Builder crews (achievement type 'meetup'): the same owner tools
+    // as the website. Check-ins provide evidence; every meetup completion
+    // waits for Mikey's decision (2026-10-22).
     const usage =
-      "Usage: lumine admin meetup list [--status review|active|completed|all] | show <crewId> | info <crewId> <userId> --decision ask|accept|ask-again|withdraw [--note <text>] | set-branch <crewId> <userId> --branch <name> [--note <text>] | branches [list|show|approve|reject|merge] | emails [list|send <id>|discard <id>|review on|off] | friends [status|on|off] | funnel [--days <1-90>] | story ... | announce-checkins [--send] [--as zero|ciel].";
+      "Usage: lumine admin meetup list [--status review|active|completed|all] | show <crewId> | review-completion <crewId> --decision approve|reject --fingerprint <review fingerprint> | info <crewId> <userId> --decision ask|accept|ask-again|withdraw [--note <text>] | set-branch <crewId> <userId> --branch <name> [--note <text>] | branches [list|show|approve|reject|merge] | emails [list|send <id>|discard <id>|review on|off] | friends [status|on|off] | funnel [--days <1-90>] | story ... | announce-checkins [--send] [--as zero|ciel].";
     const note = String(options.note || "").trim();
     if (note.length > 1000) {
       throw cliValidationError("--note must be at most 1000 characters.");
@@ -3233,6 +3242,14 @@ export function parseAdminOperation(options) {
         { requiresRun: false },
       );
     }
+    if (action === "review-completion") {
+      const crewId = parseRequiredInteger(target, "Crew ID", 1);
+      const decision = parseChoice(options.adminDecision || "", "--decision", ["approve", "reject"]);
+      const fingerprint = String(options.adminFingerprint || "");
+      if (!/^[0-9a-f]{64}$/.test(fingerprint)) throw cliValidationError("Use --fingerprint from meetup show --json after reviewing every participant's evidence.");
+      return writeOperation("meetup.review-completion", "POST", `/cli/admin/meetup-quest/crews/${crewId}/checkin-review`,
+        { isApproved: decision === "approve", fingerprint }, { requiresRun: false });
+    }
     if (action === "info") {
       // Staff's "who are you" check on a member (ruled 2026-10-07): the member
       // gives their teacher's name and class name (or how they know the crew)
@@ -3629,6 +3646,17 @@ export function parseAdminOperation(options) {
     throw cliValidationError(usage);
   }
 
+  if (namespace === "reward-diagnostics") {
+    const buildId = options.buildIdFlag ? parseRequiredInteger(options.buildIdFlag, "--build", 1) : 0;
+    const userId = options.adminUser ? parseRequiredInteger(options.adminUser, "--user", 1) : 0;
+    const days = options.adminDays ? parseRequiredInteger(options.adminDays, "--days", 1) : 1;
+    if (days > 30 || userId && !buildId) throw cliValidationError("Use --build with --user; --days must be 1–30.");
+    return readOperation("reward-diagnostics.read", withQuery("/cli/admin/reward-diagnostics", {
+      buildId: buildId || undefined, userId: userId || undefined, days,
+      before: options.adminCursor ? parseRequiredInteger(options.adminCursor, "--cursor", 1) : undefined
+    }), { requiresRun: false });
+  }
+
   if (namespace === "reward-activity" || namespace === "reward-telemetry") {
     // Read-only claim telemetry for the daily run: no run lease, no mutation.
     const date = options.adminDate
@@ -4474,6 +4502,8 @@ export function parseAdminOperation(options) {
     );
   }
 
+  if (namespace === "spending") return buildSpendingOperation(options);
+
   if (namespace === "ai-costs") {
     if (action === "monthly" && !target && !extra) {
       if (options.adminDays) {
@@ -6620,8 +6650,10 @@ function printMeetupResult({ operation, data, result }) {
   }
   if (operation.name === "meetup.show") {
     printMeetupCrew(data.crew || {});
+    if (data.meetupEvidence) console.log(JSON.stringify(data.meetupEvidence, null, 2));
     return;
   }
+  if (operation.name === "meetup.review-completion") console.log(`Meetup completion ${data.status}.`);
   if (data.crew) printMeetupCrew(data.crew);
 }
 
@@ -6933,6 +6965,7 @@ function printApprovalResult({ operation, data }) {
       `${item.ref} · ${APPROVAL_LABELS[item.type] || item.type} · ${item.status} · ${item.requesterUsername} (#${item.requesterId})`,
     );
     printEvidence(data.evidence);
+    if (data.meetupEvidence) console.log(JSON.stringify(data.meetupEvidence, null, 2));
     return;
   }
   if (operation.name === "approvals.decide") {
@@ -7360,10 +7393,16 @@ function printAiBucketRuleResult({ operation, data }) {
 
 function printAdminResult({ operation, result }) {
   const data = result?.data || {};
+  if (operation.name === "spending.report" && data.spending) {
+    console.log(formatSpending(data.spending));
+    return;
+  }
   if (operation.name === "math-lab.queue") {
     console.log(`Math Lab: published artifact ${data.publishedArtifactVersionId}, review ${data.reviewId}, day ${data.dayKey} UTC.`);
     for (const grade of data.grades || []) console.log(grade.available
-      ? `${grade.ruleId}: ${grade.current || "exhausted"}${grade.clearedToday ? " (cleared today)" : ""}; ${grade.remaining} unearned of ${grade.sets}${grade.refillDue ? `; refill to ${data.refillTarget}` : ""}`
+      ? grade.progression === "collection"
+        ? `${grade.ruleId}: ${grade.sets} in collection; ${grade.remaining} fresh choices minimum (${grade.activeLearners} active learners; median ${grade.medianRemaining})${grade.refillDue ? `; refill to ${data.refillTarget}` : ""}`
+        : `${grade.ruleId}: ${grade.current || "exhausted"}${grade.clearedToday ? " (cleared today)" : ""}; ${grade.remaining} unearned of ${grade.sets}${grade.refillDue ? `; refill to ${data.refillTarget}` : ""}`
       : `${grade.ruleId}: queue unavailable`);
     if (!data.complete) console.log("Queue coverage is incomplete; unavailable grades are not empty queues.");
     return;

package/lib/commands.js

@@ -2562,6 +2562,13 @@ export function parseArgs(args) {
         );
     }
   }
+  if (command === "admin" && positional[0] === "spending") {
+    const allowed = new Set(["help", "month", "from", "to", "awsProfile", "output", "json",
+      "apiUrl", "siteUrl", "authFile", "authToken", "clientName", "timeoutMs", "noUpdateCheck"]);
+    for (const key of Object.keys(raw)) {
+      if (!allowed.has(key)) throw new Error(`Unsupported spending option --${key.replace(/[A-Z]/g, c => `-${c.toLowerCase()}`)}.`);
+    }
+  }
   const suggestionInboxActions = new Set([
     "list",
     "merge",
@@ -2805,6 +2812,10 @@ export function parseArgs(args) {
     adminActions: raw.actions ? String(raw.actions) : "",
     adminDate: raw.date ? String(raw.date) : "",
     adminDays: raw.days ? String(raw.days) : "",
+    adminSpendingMonth: raw.month,
+    adminSpendingFrom: raw.from,
+    adminSpendingTo: raw.to,
+    adminAwsProfile: raw.awsProfile,
     adminMaxStep: raw.maxStep ? String(raw.maxStep) : "",
     adminBuild: raw.build ? String(raw.build) : "",
     adminEditionId: raw.editionId ? String(raw.editionId) : "",
@@ -3269,6 +3280,7 @@ export function printHelp() {
   lumine admin meetup list [--status review|active|completed|all] | show <crewId> | info <crewId> <userId> --decision ask|accept|ask-again|withdraw [--note <text>] | set-branch <crewId> <userId> --branch "<name>" [--note <text>] | branches [list [--status pending|official|rejected|all] | show <id> | approve <id> | reject <id> [--note <text>] | merge <id> --into <officialId>] | emails [list|send <id>|discard <id>|review on|off] | friends [status|on|off] | funnel [--days <1-90>] | announce-checkins [--send] [--as zero|ciel]   (Bridge Builder crews and check-ins)
   lumine admin meetup story list | show <crewId> | approve <crewId> [--note <text>] [--no-announce] | send-back <crewId> --note <text> | unpublish <crewId> --note <text>   (Bridge Builder story pages: publishes only what every tagged member's parent allowed)
   lumine admin reward-activity [--date YYYY-MM-DD] [--days <1..31>] [--build <id>] [--json]
+  lumine admin reward-diagnostics [--build <id> --user <id>] [--days <1..30>] [--cursor <id>] [--json]
   lumine admin chat-reports list [--status pending|open|reviewing|resolved|dismissed|all] [--cursor <id>] [--json]
   lumine admin chat-reports show <report-id> [--json]   (reported message snapshot + surrounding context)
   lumine admin chat-reports set <report-id> --status reviewing|resolved|dismissed|open --note <what was decided> [--json]
@@ -3315,7 +3327,7 @@ export function printHelp() {
   lumine admin reward-bank coverage <buildId> [--max-step 3] [--json]
   lumine admin reward-bank seed <buildId> [--max-step 3] [--identity zero|ciel|auto] [--json]   (writes ONE missing seed question, lowest step first, billed to Zero/Ciel's AI Energy; inside a daily run or on its own, owner only)
   lumine admin reward-bank report <buildId> [--days 1] [--json]   (question-bank telemetry: generation outcomes, learners, payouts, ladder, questions to review)
-  lumine admin owner-trace [--since 2h|30m|3d|<iso>] [--type route,feed-open,scroll-anchor,content-scroll,error,rejection,session,nav-timing,slow-request,stall,page-load,scroll-perf,scroll-frame] [--perf] [--wake] [--path <substring>] [--limit 300] [--json]   (--wake: only sessions and the 20 s wake profiles after each load or return, with the network tag that separates Wi-Fi from cellular; what the website did on Mikey's own devices: routes with PUSH/POP/REPLACE, Home feed card opens, scroll-anchor restores, content scroll positions, window errors, and performance: tap-to-page timing, API requests over 1 s, main-thread stalls over 200 ms, page load, scroll frame pacing and slow-frame attribution (Long Animation Frame scripts on Chrome, feed card renders on Safari); --perf shows only those; kept 30 days)
+  lumine admin owner-trace [--since 2h|30m|3d|<iso>] [--type route,feed-open,scroll-anchor,content-scroll,error,rejection,session,nav-timing,slow-request,stall,page-load,scroll-perf,scroll-frame] [--perf] [--wake] [--path <substring>] [--limit 300] [--json]   (--wake: sessions, 20 s wake profiles, bounded viewport geometry and dropped-event counts after loads or returns; network tags identify the upload network; what the website did on Mikey's own devices: routes with PUSH/POP/REPLACE, Home feed card opens, scroll-anchor restores, content scroll positions, window errors, and performance: tap-to-page timing, API requests over 1 s, main-thread stalls over 200 ms, page load, scroll frame pacing and slow-frame attribution (Long Animation Frame scripts on Chrome, feed card renders on Safari); --perf shows only those; kept 30 days)
   lumine admin roles [--min-level 1] [--limit 50] [--json]   (every user type with its management level and who holds it; admin pages need level 3, achievement points never pass level 2)
   lumine admin comment draft <target> [--type subject|comment|build|aiStory|dailyReflection] [--file <comment.md>] [--review-receipt <review.json>|--reviewed-version <id> --reviewed-via runtime|code] [--review-context <context.json>] [--identity zero|ciel|auto] [--json]
   lumine admin comment reply comment:<id> [--file <reply.md>] [--reviewed-version <id> --reviewed-via runtime|code] [--review-context <context.json>] [--identity zero|ciel|auto] [--json]
@@ -3325,6 +3337,7 @@ export function printHelp() {
     (with both a comment session and a daily run active, comment draft/reply/post/edit need --via session|run)
   lumine admin comment edit <comment-id> --file <comment.md> [--review-receipt <review.json> | --reviewed-version <id> --reviewed-via runtime|code] [--review-context <context.json>] [--json]
   lumine admin brief [--days <1..30>] [--json]
+  lumine admin spending [--month YYYY-MM | --from YYYY-MM --to YYYY-MM] [--aws-profile <profile>] [--output <file.json>] [--json] (owner spending: AI, AWS, reimbursements; no active run required)
   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]

package/lib/sdk.js

@@ -303,7 +303,7 @@ export const SDK_CLI_METHODS = {
     path: "api/rewards/related-archive", special: "rewards", operation: "related-archive",
     scopes: ["rewards:claim"], readOnly: true,
     mapArgs: (args) =>
-      args.receiptId !== undefined ? { receiptId: args.receiptId } : { ruleId: args.ruleId },
+      args.receiptId !== undefined ? { receiptId: args.receiptId } : { ruleId: args.ruleId, ...(args.setKey !== undefined ? { setKey: args.setKey } : {}) },
   },
   "rewards.listExplanations": {
     path: "api/rewards/explanations", special: "rewards", operation: "explanations",
@@ -349,7 +349,7 @@ export const SDK_CLI_METHODS = {
     operation: "start",
     scopes: ["rewards:claim"],
     write: true,
-    mapArgs: (args) => ({ ruleId: args.ruleId }),
+    mapArgs: (args) => ({ ruleId: args.ruleId, ...(args.setKey !== undefined ? { setKey: args.setKey } : {}) }),
   },
   "rewards.claim": {
     path: "api/rewards/claim",

package/package.json

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