@stage5/lumine 0.2.48 → 0.2.49

package/README.md

@@ -150,8 +150,9 @@ which can differ from a method's `Twinkle.*` SDK return shape — check
 ## Assets and AI image generation
 
 Binary media never lives in the workspace — assets are uploaded to Twinkle and
-referenced from code by URL. `lumine assets upload <file...>` uploads images or
-audio; `lumine assets list` prints your uploads and refreshes
+referenced from code by URL. `lumine assets upload <file...>` uploads images,
+audio, and MIDI data (`.mid`/`.midi`; playback still needs an app-side parser
+or synth); `lumine assets list` prints your uploads and refreshes
 `.twinkle/assets.json`.
 
 `lumine assets generate "<prompt>" --model <gpt-image-2|nano-banana>` creates
@@ -231,6 +232,10 @@ events.
 lumine admin identity list --json
 lumine admin identity inspect Jay1216 \
   --reason "Confirm account family before a quota-bucket change" --json
+lumine admin economy trace lock --days 3 \
+  --reason "Investigate the anomalous coin gain" --json
+lumine admin rescue wordle-audit --days 30 \
+  --reason "Identify recorded Wordle breaks and rescue status" --json
 lumine admin daily-run start --identity auto --comment-mode off --json
 lumine admin todo list --json
 lumine admin todo add --kind experiment --status in_progress \

package/lib/admin.js

@@ -8,10 +8,7 @@ import {
   validateNewsEditorial,
   writeNewsClaimArtifacts,
 } from "./admin-news.js";
-import {
-  runAutomaticPagination,
-  runBatchSkips,
-} from "./admin-workflows.js";
+import { runAutomaticPagination, runBatchSkips } from "./admin-workflows.js";
 import {
   parseBuildReviewReceipt,
   runManagedBuildReview,
@@ -506,6 +503,8 @@ function adminOperationRequiresRun(operation) {
       "identity.status",
       "identity.use",
       "identity.inspect",
+      "economy.trace",
+      "rescue.wordle.audit",
       "daily-run.start",
       "daily-run.status",
       "escalation.list",
@@ -584,6 +583,49 @@ export function parseAdminOperation(options) {
     }
   }
 
+  if (namespace === "economy" && action === "trace") {
+    const traceTarget = String(target || "").trim();
+    const reason = String(options.adminReason || "").trim();
+    if (!traceTarget || !reason) {
+      throw cliValidationError(
+        "Usage: lumine admin economy trace <userId|username> --reason <management reason> [--days <1..30>].",
+      );
+    }
+    if (reason.length > MAX_IDENTITY_INSPECTION_REASON_LENGTH) {
+      throw cliValidationError(
+        `An investigation reason must be at most ${MAX_IDENTITY_INSPECTION_REASON_LENGTH} characters.`,
+      );
+    }
+    return writeOperation("economy.trace", "POST", "/cli/admin/economy/trace", {
+      target: traceTarget,
+      reason,
+      days: parseRequiredInteger(options.adminDays || "3", "--days", 1, 30),
+    });
+  }
+
+  if (namespace === "rescue" && action === "wordle-audit") {
+    const reason = String(options.adminReason || "").trim();
+    if (!reason) {
+      throw cliValidationError(
+        "Usage: lumine admin rescue wordle-audit --reason <management reason> [--days <1..30>].",
+      );
+    }
+    if (reason.length > MAX_IDENTITY_INSPECTION_REASON_LENGTH) {
+      throw cliValidationError(
+        `An investigation reason must be at most ${MAX_IDENTITY_INSPECTION_REASON_LENGTH} characters.`,
+      );
+    }
+    return writeOperation(
+      "rescue.wordle.audit",
+      "POST",
+      "/cli/admin/rescues/wordle/audit",
+      {
+        reason,
+        days: parseRequiredInteger(options.adminDays || "30", "--days", 1, 30),
+      },
+    );
+  }
+
   if (namespace === "ai-bucket" || namespace === "ai-buckets") {
     if (action === "create") {
       return writeOperation(
@@ -806,8 +848,7 @@ export function parseAdminOperation(options) {
           recommendationWindow.mode === "after"
             ? recommendationWindow.after
             : "",
-        includeLegacy:
-          recommendationWindow.mode === "legacy" ? "true" : "",
+        includeLegacy: recommendationWindow.mode === "legacy" ? "true" : "",
       }),
       {
         pagination: {
@@ -1214,10 +1255,7 @@ export function parseAdminOperation(options) {
       const reviewReceipt = options.adminReviewReceipt
         ? parseBuildReviewReceipt(options.adminReviewReceipt)
         : null;
-      if (
-        reviewReceipt &&
-        (reviewedBuildVersionId || buildReviewMethod)
-      ) {
+      if (reviewReceipt && (reviewedBuildVersionId || buildReviewMethod)) {
         throw cliValidationError(
           "Pass either --review-receipt or manual --reviewed-version/--reviewed-via evidence, not both.",
         );
@@ -1318,7 +1356,7 @@ export function parseAdminOperation(options) {
   }
 
   throw cliValidationError(
-    "Usage: lumine admin identity|daily-run|escalation|todo|recommendations|builds|post|subjects|subject|featured|comment|announcement|chat|news|audit|brief|bot-output|notable ...",
+    "Usage: lumine admin identity|economy|rescue|daily-run|escalation|todo|recommendations|builds|post|subjects|subject|featured|comment|announcement|chat|news|audit|brief|bot-output|notable ...",
   );
 }
 
@@ -1579,7 +1617,11 @@ export function parseAdminEscalationTarget(value) {
   if (genericTarget) {
     return {
       targetType: genericTarget[1],
-      targetId: parseRequiredInteger(genericTarget[2], "escalation target ID", 1),
+      targetId: parseRequiredInteger(
+        genericTarget[2],
+        "escalation target ID",
+        1,
+      ),
       url: null,
     };
   }
@@ -1770,13 +1812,9 @@ function parseTodoStatus(value) {
     .trim()
     .toLowerCase();
   if (
-    ![
-      "open",
-      "in_progress",
-      "blocked",
-      "completed",
-      "cancelled",
-    ].includes(status)
+    !["open", "in_progress", "blocked", "completed", "cancelled"].includes(
+      status,
+    )
   ) {
     throw cliValidationError(
       "--status must be open, in_progress, blocked, completed, or cancelled.",
@@ -1816,7 +1854,9 @@ function parseAiBucketLabel(value) {
     throw cliValidationError("Pass the bucket name with --label <name>.");
   }
   if (label.length > 120) {
-    throw cliValidationError("An AI bucket name can be at most 120 characters.");
+    throw cliValidationError(
+      "An AI bucket name can be at most 120 characters.",
+    );
   }
   return label;
 }
@@ -1824,9 +1864,7 @@ function parseAiBucketLabel(value) {
 function parseAiBucketNote(value) {
   const note = String(value || "").trim();
   if (!note) {
-    throw cliValidationError(
-      "Pass the quota-only context with --note <text>.",
-    );
+    throw cliValidationError("Pass the quota-only context with --note <text>.");
   }
   if (note.length > 255) {
     throw cliValidationError(
@@ -1956,7 +1994,8 @@ function printAdminResult({ operation, result }) {
           ([name, value]) =>
             `${name} ${Number(value.delta) > 0 ? "+" : ""}${Number(value.delta)}`,
         );
-      if (deltas.length) console.log(`Engagement deltas: ${deltas.join(", ")}.`);
+      if (deltas.length)
+        console.log(`Engagement deltas: ${deltas.join(", ")}.`);
     }
     const notableCount = Array.isArray(report.brief?.notableCandidates)
       ? report.brief.notableCandidates.length

package/lib/assets.js

@@ -284,7 +284,7 @@ export async function assetsUpload(options) {
   const filePaths = options.positional.slice(1);
   if (!filePaths.length) {
     throw new Error(
-      "Usage: lumine assets upload <file...> (runtime media: images, audio, GLB/self-contained glTF, KTX2, HDR, EXR, BIN, DRC)",
+      "Usage: lumine assets upload <file...> (runtime media: images, audio/MIDI, GLB/self-contained glTF, KTX2, HDR, EXR, BIN, DRC)",
     );
   }
   const buildId = await resolveSdkBuildId(options);

package/lib/commands.js

@@ -2350,7 +2350,10 @@ export function parseArgs(args) {
     adminAfter: raw.after ? String(raw.after) : "",
     adminSinceRun: Boolean(raw.sinceRun),
     adminIncludeLegacy: Boolean(raw.includeLegacy),
-    adminIncludePrivateEvidence: parseBoolean(raw.includePrivateEvidence, false),
+    adminIncludePrivateEvidence: parseBoolean(
+      raw.includePrivateEvidence,
+      false,
+    ),
     adminAll: Boolean(raw.all),
     adminResume: Boolean(raw.resume),
     adminCheckpoint: raw.checkpoint ? String(raw.checkpoint) : "",
@@ -2365,8 +2368,7 @@ export function parseArgs(args) {
     adminWaitMs: raw.waitMs ? String(raw.waitMs) : "",
     adminBrowserPath: raw.browserPath ? String(raw.browserPath) : "",
     adminEffort: raw.effort ? String(raw.effort) : "",
-    agentEffort:
-      command === "agent" && raw.effort ? String(raw.effort) : "",
+    agentEffort: command === "agent" && raw.effort ? String(raw.effort) : "",
     provider: raw.provider ? String(raw.provider) : "",
     providerPath: raw.providerPath ? String(raw.providerPath) : "",
     agentPrompt:
@@ -2733,6 +2735,8 @@ export function printHelp() {
   lumine doctor runtime-assets
   lumine admin identity list|status|use <zero|ciel|auto> [--json]
   lumine admin identity inspect <user-id|username> --reason <management-reason> [--include-private-evidence] [--json]
+  lumine admin economy trace <user-id|username> --reason <management-reason> [--days <1..30>] [--json]
+  lumine admin rescue wordle-audit --reason <management-reason> [--days <1..30>] [--json]
   lumine admin ai-bucket create --label <name> --note <text> [--json]
   lumine admin ai-bucket get --bucket-id <id> [--json]
   lumine admin ai-bucket accounts add --bucket-id <id> --user-ids <id,id,...> [--note <text>] [--json]

package/lib/constants.js

@@ -33,16 +33,11 @@ export const UPDATE_CHECK_TIMEOUT_MS = 1500;
 export const DEFAULT_PROJECT_LIMIT = 50;
 export const BUILD_VENDOR_THREE_VERSION = "0.184.0";
 export const BUILD_VENDOR_THREE_LEGACY_VERSION = "0.160.0";
-export const BUILD_VENDOR_THREE_PREFIX =
-  `/build/vendor/three/${BUILD_VENDOR_THREE_VERSION}/`;
-export const BUILD_VENDOR_THREE_MODULE_IMPORT =
-  `${BUILD_VENDOR_THREE_PREFIX}three.module.min.js`;
-export const BUILD_VENDOR_THREE_WEBGPU_MODULE_IMPORT =
-  `${BUILD_VENDOR_THREE_PREFIX}three.webgpu.min.js`;
-export const BUILD_VENDOR_THREE_TSL_MODULE_IMPORT =
-  `${BUILD_VENDOR_THREE_PREFIX}three.tsl.min.js`;
-export const BUILD_VENDOR_THREE_ADDONS_IMPORT_PREFIX =
-  `${BUILD_VENDOR_THREE_PREFIX}addons/`;
+export const BUILD_VENDOR_THREE_PREFIX = `/build/vendor/three/${BUILD_VENDOR_THREE_VERSION}/`;
+export const BUILD_VENDOR_THREE_MODULE_IMPORT = `${BUILD_VENDOR_THREE_PREFIX}three.module.min.js`;
+export const BUILD_VENDOR_THREE_WEBGPU_MODULE_IMPORT = `${BUILD_VENDOR_THREE_PREFIX}three.webgpu.min.js`;
+export const BUILD_VENDOR_THREE_TSL_MODULE_IMPORT = `${BUILD_VENDOR_THREE_PREFIX}three.tsl.min.js`;
+export const BUILD_VENDOR_THREE_ADDONS_IMPORT_PREFIX = `${BUILD_VENDOR_THREE_PREFIX}addons/`;
 export const PROJECT_METADATA_DIR = ".twinkle";
 export const PROJECT_METADATA_FILE = "lumine-project.json";
 export const ASSETS_METADATA_FILE = "assets.json";
@@ -66,6 +61,8 @@ export const ASSET_MIME_BY_EXTENSION = {
   ".heif": "image/heif",
   ".avif": "image/avif",
   ".mp3": "audio/mpeg",
+  ".mid": "audio/midi",
+  ".midi": "audio/midi",
   ".wav": "audio/wav",
   ".ogg": "audio/ogg",
   ".m4a": "audio/mp4",
@@ -92,7 +89,11 @@ export const PROJECT_MAX_TOTAL_BYTES_DEFAULT = 1024 * 1024;
 export const RUNTIME_ASSET_REFERENCE_PATTERN =
   /(?:https?:\/\/[^\s"'`)\\]+)?\/attachments\/(?:build-runtime|optimized)\/[^\s"'`)\\]+/g;
 export const DEFAULT_SAVE_SUMMARY = "Saved from Lumine CLI.";
-export const EXCLUDED_UPLOAD_DIRS = new Set([".git", ".twinkle", "node_modules"]);
+export const EXCLUDED_UPLOAD_DIRS = new Set([
+  ".git",
+  ".twinkle",
+  "node_modules",
+]);
 export const SDK_REFERENCE_FILE = "TWINKLE_BUILD_SDK.md";
 export const EXCLUDED_UPLOAD_FILES = new Set([
   ".DS_Store",
@@ -217,7 +218,8 @@ lumine save --summary "Describe the change"
 - .twinkle/${ASSETS_METADATA_FILE} lists this build's uploaded assets (the current
   CLI user's uploads) with their URLs. Reference an asset by its \`url\` value.
 - \`lumine assets upload <file...>\` uploads supported runtime assets (images,
-  audio, GLB/self-contained glTF models, texture maps, HDR/EXR files, and glTF
+  audio and MIDI data (which needs an app-side parser/synth for playback),
+  GLB/self-contained glTF models, texture maps, HDR/EXR files, and glTF
   companion files) from disk and prints the URL to use in code. Raw .gltf files
   with relative companion URIs must be converted to .glb or rewritten to
   absolute uploaded asset URLs first. Reference every uploaded asset that must

package/package.json

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

package/sdk/LUMINE_ADMIN.md

@@ -125,6 +125,44 @@ is run-independent and has no public actor. Results are **candidate accounts
 for human judgment**, not an automatic ownership finding and never automatic
 grounds for moderation, bans, or bucket changes.
 
+### Audited private investigations
+
+Use reason-required, bounded drill-downs when an aggregate management signal
+needs causal evidence:
+
+```bash
+lumine admin economy trace lock --days 3 \
+  --reason "Investigate the anomalous three-day coin gain" --json
+lumine admin rescue wordle-audit --days 30 \
+  --reason "Identify recorded Wordle breaks, streak lengths, and rescue status" --json
+```
+
+`economy trace` reads the canonical append-only coin ledger for one exact
+account. It returns an exact action/target breakdown for the window, the largest
+ledger entries, direct transfer counterparties, AI Card sale/offer provenance,
+and whether a counterparty is already in the same effective exact-account AI
+bucket. It never reads or returns chat messages, bucket labels, verified
+addresses, device evidence, or private identity values. Same-bucket transfers and concentration are
+investigation signals, not automatic abuse findings.
+
+`rescue wordle-audit` separates expired unredeemed Wordle/strict-Wordle rescue
+offers from offers still inside their seven-day promise and from redeemed
+offers. Each row identifies the account and labels the cause: regular Wordle is
+an uncovered dodge, while strict Wordle is a completed but non-strict game. The
+stored offer-time streak snapshot is reported as the broken streak length.
+`claim_ready` requires a durable first user exchange in Lumine history; a
+reservation claim is reported separately and is not treated as completion. An
+open offer is never labelled a refusal, and non-redemption does not establish
+intent. The underlying rescue table stores one current row per account; an
+expired row may be replaced by a later offer, so the command reports exact
+current-row evidence and explicitly marks that it is not a complete immutable
+history of every offer ever shown.
+
+Both commands are run-independent private operator actions. Each requires a
+concrete reason and commits a minimized private access receipt before loading
+the evidence. Windows are limited to 1-30 days, and neither command mutates
+coins, streaks, buckets, messages, or public content.
+
 ## Editorial priorities
 
 The CLI enforces none of this — it is the standing instruction for the operator
@@ -1480,6 +1518,82 @@ right after the brief, and **read every row** — the tool deliberately does no
 filtering, scoring, or keyword matching, because the judgment is the reviewing
 agent's.
 
+### API runtime-log review (same phase, every run)
+
+The bot-conduct review also owns a bounded production API log review. Bot
+responses, community-management reads, and delegated mutations can succeed at
+the HTTP layer while stdout records a degraded fallback/retry loop or stderr
+records a side-effect failure. Reviewing only `bot-output` can therefore miss
+the other half of what happened.
+
+The current API-side files are:
+
+- `/home/ec2-user/server/logs/twinkle-api.err.log`
+- `/home/ec2-user/server/logs/twinkle-api.out.log`
+- `/home/ec2-user/server/logs/twinkle-image-optimizer.err.log`
+- `/home/ec2-user/server/logs/twinkle-image-optimizer.out.log`
+
+Treat every current `/home/ec2-user/server/logs/*.err.log` and `*.out.log` as
+in scope so a later API-side worker is not silently omitted. Use the production
+SSH endpoint and key from the repository agent guide; all inspection commands
+are read-only.
+
+1. Immediately after `daily-run start`, record each matching file's inode and
+   byte size, inspect its current tail to establish service health, and read
+   every non-empty error log before accepting that position as the run
+   baseline. The prior run is supposed to leave the live API error log empty,
+   so unexplained pre-existing stderr is evidence, not a reason to skip ahead.
+2. Run and fully paginate `bot-output`, reading every row as required above.
+   In this same phase, read every byte appended to both error and normal-output
+   files since the recorded baseline. Refresh the offsets after inspection.
+   Do not rely on a fixed-line `tail`: a busy or multiline failure can begin
+   before that arbitrary window.
+3. Immediately before `daily-run report` and `daily-run complete`, inspect the
+   delta again. This catches failures caused by the curation actions performed
+   after the first conduct/log review. If a file's inode changed or its size
+   shrank, do not assume the missing range was clean: inspect the replacement
+   from byte zero, check the relevant `twinkle-api.service` or
+   `twinkle-image-optimizer.service` journal interval, and report the lost
+   boundary.
+
+For each warning, fallback, retry loop, or failure, correlate timestamps and
+request/target IDs with the canonical CLI response and private audit event.
+Distinguish an expected, handled condition from a real user-visible,
+reliability, security, or performance defect. A defensible defect is an
+in-scope bug report: trace its complete producer-to-consumer pipeline, fix the
+root cause in the canonical repository, add focused regression coverage, run
+the repository's normal validation ceiling, and verify the fix in production
+when deployment is authorized. Re-read the affected log boundary after live
+verification. Do not declare the run clean merely because a retry eventually
+succeeded if the underlying failure remains repeatable.
+
+Never silently complete a run with an unresolved log finding. If the fix needs
+new commit/deployment authority, external coordination, or more time than the
+active run safely permits, preserve the evidence, add or update a private
+carry-over todo with the exact finding and acceptance criteria, and tell Mikey
+in the run report. Do not mark that todo complete until the fix is verified
+live.
+
+Preserve all log evidence while any finding remains. Once every issue found in
+`/home/ec2-user/server/logs/twinkle-api.err.log` has been fixed and verified
+live, or conclusively classified as expected/non-defective, clear that exact
+live API stderr log through the only safe path:
+
+```bash
+ssh -i /Users/mikey/twinkle-api.pem -o IdentitiesOnly=yes \
+  ec2-user@api.twinkle.network \
+  'cd /home/ec2-user/server && npm run logs:clear-errors'
+```
+
+That command truncates the file through the service's inode-safe lifecycle; it
+does not restart the API. Never delete, recreate, editor-save, or manually
+truncate any log. Do not clear normal stdout or the optimizer logs. After the
+safe clear, inspect the error file and all bytes appended to the normal logs
+once more, and include the reviewed file set, boundaries, findings/fixes,
+live-verification result, clear result, and any remaining todo in the final run
+report. If any error-log issue remains unresolved or unverified, do not clear
+the error log.
+
 **Purpose and privacy boundary:** this audits how Twinkle's bots treated
 members; it is not thought-policing or a moderation queue for members' private
 use of the tool. The question is whether Zero or Ciel inflicted, encouraged,
@@ -1592,8 +1706,8 @@ end every run report with an **"Insights for Mikey"** section carrying only
 the deltas and anomalies worth his time, next to the escalation list. Never
 dump raw sections at him.
 
-Nine sections (Mikey's chosen cut 2026-08-10; behavioral-insight and
-farm-signal sections added the same day):
+Ten sections (Mikey's chosen cut 2026-08-10; behavioral-insight and
+farm-signal sections added that day; AI Card summon watch added 2026-08-24):
 
 - `economy` — `topGainers` (coin-ledger aggregation over the window: gained,
   spent, net, current balance per user, Zero/Ciel excluded) and `topBalances`
@@ -1633,6 +1747,26 @@ farm-signal sections added the same day):
   an account is young or empty. A run that reads the spending report without
   asking "could any of this be one person with many accounts?" has skipped a
   duty.
+- `aiCardSummoning` — the standing multi-alt Summoner watch for every website-
+  management run. It counts the authoritative `ai_card_summons` daily quota counters
+  over the whole-day `dayWindow`, so Mystery Cards and successful fallback
+  cards are included, then lists the most active summoning accounts. It groups
+  summons when the same exact-device hash was observed for more than one
+  summoning user within the bounded `deviceEvidenceLookbackDays`; that evidence
+  is correlated with the account/window, not asserted to be the device used for
+  every individual summon. Each group reports its maximum same-day account and
+  charged-summon totals, the multi-account days, and days above the shared
+  three-card limit. Review every `requiresIdentityInspection` group,
+  prioritizing `daysAboveSharedLimit > 0`, with reason-required `identity
+  inspect`. If
+  `riskGroupsTruncated` is true, report that the bounded watch has more groups
+  than it returned rather than calling the review exhaustive. Add only
+  operator-confirmed exact accounts to an unbanned quota bucket with
+  `ai-bucket accounts add`; never infer or auto-bucket a family from a device,
+  IP prefix, user agent, shared inbox, or anomaly alone. After a bucket update,
+  re-read its canonical members. This duty applies even when no group crossed
+  three cards, because the new enforcement prevents already-bucketed siblings
+  from producing an over-limit row.
 - `notableCandidates` — kids (never bots, staff `userType`s, or users already
   on the Notable Users list) ranked by authored activity in the window, with
   `isNewUser` marking window-new signups. Use it to find the overlooked and
@@ -1830,6 +1964,49 @@ type InsightsBrief = Success<{
         topRiskGroups: unknown[];
       }
     | InsightUnavailable;
+  aiCardSummoning:
+    | {
+        dayWindow: { startDayIndex: number; endDayIndex: number };
+        deviceEvidenceLookbackDays: number;
+        sharedDailyLimit: number;
+        summonsCharged: number;
+        summoningAccounts: number;
+        riskGroupsTruncated: boolean;
+        topAccounts: Array<{
+          userId: number;
+          username: string | null;
+          joinedAt: number | null;
+          summonsCharged: number;
+          activeDays: number;
+          lastSummonDayIndex: number | null;
+        }>;
+        multiAccountRiskGroups: Array<{
+          riskKeyType: string;
+          riskKeyHash: string;
+          accountCount: number;
+          summonsChargedOnMultiAccountDays: number;
+          multiAccountDays: number;
+          maxDailySummons: number;
+          maxDailyAccounts: number;
+          daysAboveSharedLimit: number;
+          requiresIdentityInspection: true;
+          dailyActivity: Array<{
+            dayIndex: number;
+            accountCount: number;
+            summonsCharged: number;
+          }>;
+          accounts: Array<{
+            userId: number;
+            username: string | null;
+            joinedAt: number | null;
+            summonsCharged: number;
+            activeDays: number;
+            lastSummonDayIndex: number | null;
+          }>;
+        }>;
+        notes: string;
+      }
+    | InsightUnavailable;
   engagementPulse:
     | {
         windowDays: number;