@stage5/lumine 0.3.23 → 0.3.25

package/README.md

@@ -81,6 +81,17 @@ pulling the owner's main project creates or reuses your contribution branch and
 checks out that branch locally. Saves go to your branch, so the project owner
 can merge or replace main from Twinkle.
 
+For an exact source review of the live app, use `lumine pull <build-id>
+--published` in a persistent review folder. This checks out the requested
+build's published artifact read-only; `--main` explicitly selects its root
+project. It never substitutes the latest draft or creates a contribution
+branch. The CLI checks the publication pointer again before writing and
+refuses a concurrent publication; modified local files are stashed before a
+successful checkout. It requires the API's published-version selector to be
+deployed first. `--published` and `--version <n>` are mutually exclusive.
+`lumine admin builds review` already reviews the published app; unsupported
+selectors such as `--mode` or `--review-mode` fail instead of being ignored.
+
 Use `lumine branches <build-url-or-id>` to list the contribution branches you
 can review, including each contributor, branch number, status, and URL. Then use
 `lumine diff <branch-url>` to inspect one branch.

package/lib/admin-daily.js

@@ -73,6 +73,7 @@ export function runAdmin(
     "reward-review": ["list"],
     approvals: ["list"],
     todo: ["list"],
+    followup: ["list"],
     escalation: ["list"],
     featured: ["list", "history"],
     sponsor: ["applications"],
@@ -192,6 +193,7 @@ export async function dailyRunGather(options) {
   // flags: a required report section (agent-guides/lumine-admin.md)
   step("approvals-pending", ["approvals", "list", "--status", "pending"], "approvals-pending.json");
   step("todos", ["todo", "list"], "todos.json");
+  step("personal-followups", ["followup", "list"], "personal-followups.json");
   step("escalations", ["escalation", "list"], "escalations.json");
   step("featured-list", ["featured", "list"], "featured-start.json");
   step(

package/lib/admin-identity-inspection.js

@@ -0,0 +1,66 @@
+function seenAt(value) {
+  if (value == null || !Number.isFinite(Number(value)) || Number(value) <= 0)
+    return "unknown";
+  const date = new Date(Number(value) * 1000);
+  return Number.isNaN(date.getTime()) ? "unknown" : date.toISOString();
+}
+
+function eventTypes(counts) {
+  const entries = Object.entries(counts || {}).sort(([a], [b]) =>
+    a.localeCompare(b),
+  );
+  return entries.length
+    ? `; ${entries.map(([type, count]) => `${type}: ${count}`).join(", ")}`
+    : "";
+}
+
+/** Display observed device events separately from accounts and physical visits. */
+export function formatIdentityDeviceUsage(inspection) {
+  const devices = inspection.sharedDevices || [];
+  const coverage = inspection.evidenceCoverage || {};
+  const lines = [];
+  if (devices.length) {
+    lines.push(
+      `Device history (${coverage.deviceLookbackDays || "unknown"} days): recorded account events, not visits or unique sessions.`,
+    );
+    for (const device of devices) {
+      const usage = device.usage;
+      if (!usage) {
+        lines.push(
+          `  Device ${device.key}: usage counts unavailable from this API; ${device.accountCount ?? "unknown"} observed account(s).`,
+        );
+        continue;
+      }
+      if (usage.status === "not_read" || usage.eventCount == null) {
+        lines.push(
+          `  Device ${device.key}: usage and sharing not read (${usage.truncatedBy?.join(", ") || "incomplete evidence"}).`,
+        );
+        continue;
+      }
+      const partial = usage.status !== "complete";
+      const prefix = partial ? "at least " : "";
+      lines.push(
+        `  Device ${device.key}: ${prefix}${usage.eventCount} recorded event(s), ${prefix}${device.accountCount} account(s)${eventTypes(usage.eventsByType)}.`,
+        `    First observed ${seenAt(usage.firstSeenAt)}; last observed ${seenAt(usage.lastSeenAt)}.`,
+      );
+      if (partial) {
+        lines.push(
+          `    Partial history (${usage.truncatedBy?.join(", ") || "incomplete evidence"}); older events and other accounts may be missing.`,
+        );
+      }
+      for (const account of usage.accounts || []) {
+        lines.push(
+          `    #${account.userId} ${account.username || "(unknown account)"}: ${prefix}${account.eventCount} recorded event(s)${eventTypes(account.eventsByType)}; first ${seenAt(account.firstSeenAt)}, last ${seenAt(account.lastSeenAt)}.`,
+        );
+      }
+      if (usage.accountsTruncated)
+        lines.push("    Account detail list capped; totals include omitted accounts.");
+    }
+  }
+  if (coverage.truncated) {
+    lines.push(
+      `Device discovery/evidence is incomplete (${coverage.truncatedBy?.join(", ") || "history limit"}); additional devices or accounts may exist.`,
+    );
+  }
+  return lines;
+}

package/lib/admin.js

@@ -39,6 +39,7 @@ import {
   printOwnerTrace,
 } from "./admin-owner-trace.js";
 import { formatChatReportResult } from "./admin-chat-reports.js";
+import { formatIdentityDeviceUsage } from "./admin-identity-inspection.js";
 import {
   buildTeacherBranchOperation,
   printTeacherBranchResult,
@@ -2478,6 +2479,21 @@ export function parseAdminOperation(options) {
         },
       );
     }
+    if (action === "device" && target === "block-signup") {
+      if (!/^[a-f0-9]{16}$/.test(options.adminDeviceKey || "")) {
+        throw cliValidationError("Pass --device-key with the exact key from identity inspect.");
+      }
+      return writeOperation(
+        "ai-bucket.device.signup.block", "POST",
+        `/cli/admin/ai-buckets/${bucketId}/signup-devices`,
+        {
+          sourceUserId: parseRequiredInteger(options.adminUser, "--user", 1),
+          deviceKey: options.adminDeviceKey,
+          expectedUserIds: parseAiBucketUserIds(options.adminUserIds),
+          note: parseAiBucketNote(options.note),
+        },
+      );
+    }
     if (action === "note" && target === "set") {
       return writeOperation(
         "ai-bucket.note.set",
@@ -3174,6 +3190,25 @@ export function parseAdminOperation(options) {
     );
   }
 
+  if (namespace === "followup" || namespace === "followups") {
+    if (!action || action === "list") {
+      return readOperation("followup.list", withQuery("/cli/admin/personal-followups", {
+        cursor: options.cursor || undefined,
+        status: options.adminStatus === "all" ? "all" : "pending",
+      }));
+    }
+    if (action === "update") {
+      const id = parseRequiredInteger(target, "Follow-up ID", 1);
+      const revision = parseRequiredInteger(options.followupRevision, "--revision", 1);
+      const note = String(options.note || "").trim();
+      if (!note || note.length > MAX_TODO_NOTE_LENGTH) throw cliValidationError("Record the actual work, evidence and reply outcome (or blocker) in --note, up to 4000 characters.");
+      return writeOperation("followup.update", "PUT", `/cli/admin/personal-followups/${id}`, {
+        revision, status: parseTodoStatus(options.adminStatus), note,
+      });
+    }
+    throw cliValidationError("Usage: lumine admin followup list [--cursor <id>] [--status all] | followup update <id> --revision <n> --status <status> --note <evidence and outcome>.");
+  }
+
   if (namespace === "todo" || namespace === "todos") {
     if (!action || action === "list") {
       return readOperation(
@@ -3229,6 +3264,16 @@ export function parseAdminOperation(options) {
         {
           status: parseTodoStatus(options.adminStatus),
           note,
+          ...(options.todoWorkflowFile
+            ? {
+                workflow: readAdminJsonFile(options.todoWorkflowFile),
+                expectedRevision: parseRequiredInteger(
+                  options.followupRevision,
+                  "--revision",
+                  1,
+                ),
+              }
+            : {}),
         },
       );
     }
@@ -6814,6 +6859,7 @@ function printAdminResult({ operation, result }) {
       );
     } else {
       printTodoItems(report.carryoverTodos?.items || [], "Unfinished work");
+      printPersonalFollowups(report.personalFollowups);
     }
     if (report.sponsorIntegrity) {
       const pendingApplications = Number.isSafeInteger(
@@ -6870,6 +6916,7 @@ function printAdminResult({ operation, result }) {
         );
       }
     }
+    for (const line of formatIdentityDeviceUsage(inspection)) console.log(line);
     return;
   }
   if (Array.isArray(data.escalations)) {
@@ -6912,6 +6959,8 @@ function printAdminResult({ operation, result }) {
     }
     return;
   }
+  if (data.personalFollowups) printPersonalFollowups(data.personalFollowups);
+  if (data.personalFollowup) printPersonalFollowups({ items: [data.personalFollowup], nextCursor: null });
   if (Array.isArray(data.todos)) {
     printTodoItems(data.todos, "Private carry-over work");
     if (data.truncated) {
@@ -7191,6 +7240,18 @@ function printFeaturedHistoryEvent(event) {
   );
 }
 
+function printPersonalFollowups(handoff) {
+  if (!handoff) return;
+  console.log(`Personal follow-ups: ${handoff.items.length}${handoff.nextCursor ? "+" : ""}`);
+  for (const item of handoff.items) {
+    console.log(`  #${item.id} r${item.revision} ${item.status} — ${item.title}`);
+    console.log(`    ${item.details}`);
+    console.log(`    Source: ${item.source.type} ${item.source.id}, ${item.source.rootType} ${item.source.rootId}; member ${item.requesterUserId}`);
+    if (item.lastProgressNote) console.log(`    Progress: ${item.lastProgressNote}`);
+  }
+  if (handoff.nextCursor) console.log(`  Continue: lumine admin followup list --cursor ${handoff.nextCursor}`);
+}
+
 function printTodoItems(items, heading) {
   console.log(`${heading}: ${items.length} item(s).`);
   for (const todo of items) {
@@ -7198,6 +7259,14 @@ function printTodoItems(items, heading) {
       `  #${todo.id} ${String(todo.status || "open").toUpperCase()} ${todo.kind || "task"} — ${todo.title || "(untitled)"}`,
     );
     if (todo.details) console.log(`    ${todo.details}`);
+    if (todo.workflow) {
+      const w = todo.workflow;
+      console.log(`    Implementation: ${w.implementation}; release: ${w.release}; verification: ${w.verification}`);
+      if (w.fixRef) console.log(`    Fix: ${w.fixRef}`);
+      if (w.releaseRef) console.log(`    Release: ${w.releaseRef}`);
+      if (w.evidence) console.log(`    Evidence: ${w.evidence}`);
+      if (w.nextAction) console.log(`    Next: ${w.nextAction}`);
+    }
     if (todo.lastProgressNote) {
       console.log(`    Latest progress: ${todo.lastProgressNote}`);
     }

package/lib/commands.js

@@ -943,6 +943,8 @@ export async function selectProject(options) {
 }
 
 export async function pull(options) {
+  if (options.pullPublished && options.versionProvided)
+    throw new Error("Choose --published or --version, not both.");
   if (options.versionProvided && !(options.pullVersion > 0)) {
     throw new Error(
       "Pass a save number: `lumine pull --version <n>` (run `lumine versions` to see save numbers).",
@@ -962,7 +964,7 @@ export async function pull(options) {
     auth,
     buildId: requestedBuildId,
   });
-  if (options.pullVersion > 0) {
+  if (options.pullPublished || options.pullVersion > 0) {
     await pullVersionBuildFiles({ options, auth, build: selectedBuild });
     return;
   }
@@ -1830,10 +1832,10 @@ export async function pullMainBuildFiles({ options, auth, build }) {
 }
 
 // Read-only checkout of ONE previous save (`lumine pull --version <n>`).
-// Without --main it targets the build the workspace edits (your branch on team
-// projects); with --main it targets the team project's main history.
+// Numeric saves target the editable workspace branch unless --main is given.
+// --published reads the named Build directly; --main selects the project root.
 export async function pullVersionBuildFiles({ options, auth, build }) {
-  const versionNumber = options.pullVersion;
+  const versionNumber = options.pullPublished ? "published" : options.pullVersion;
   let targetBuild = build;
   if (options.pullMain) {
     const rootBuildId =
@@ -1842,7 +1844,7 @@ export async function pullVersionBuildFiles({ options, auth, build }) {
       rootBuildId === Number(build?.id || 0)
         ? build
         : await loadBuildMetadata({ options, auth, buildId: rootBuildId });
-  } else {
+  } else if (!options.pullPublished) {
     targetBuild = await resolveEditableWorkspaceBuild({
       options,
       auth,
@@ -1856,6 +1858,27 @@ export async function pullVersionBuildFiles({ options, auth, build }) {
     buildId,
     versionNumber,
   });
+  if (options.pullPublished) {
+    const expected = Number(result.build?.publishedArtifactVersionId || 0);
+    if (
+      !expected ||
+      Number(result.version?.versionId) !== expected ||
+      !result.build?.isPublic
+    ) {
+      throw new Error(
+        "The API did not return the exact published artifact; update the API before using --published.",
+      );
+    }
+    const current = await loadBuildMetadata({ options, auth, buildId });
+    if (
+      !current.isPublic ||
+      Number(current.publishedArtifactVersionId) !== expected
+    ) {
+      throw new Error(
+        "The published version changed during checkout. Retry; no local files were changed.",
+      );
+    }
+  }
   const resolvedBuild = result.build || targetBuild;
   const version = result.version || { version: versionNumber };
   const files = Array.isArray(result.projectFiles) ? result.projectFiles : [];
@@ -1879,6 +1902,7 @@ export async function pullVersionBuildFiles({ options, auth, build }) {
           ? path.join(path.dirname(enclosing.rootDir), dirName)
           : dirName),
   );
+  await stashLocalProjectFilesBeforePull({ dir, files });
   await writeProjectFiles({ dir, files });
   if (files.some((file) => isIndexHtmlPath(String(file.path)))) {
     await removeLocalProjectFilesNotIn({ dir, files });
@@ -2422,6 +2446,7 @@ export function parseArgs(args) {
     "open",
     "noDescription",
     "publish",
+    "published",
     "save",
     "force",
     "noUpdateCheck",
@@ -2491,6 +2516,35 @@ export function parseArgs(args) {
     }
   }
 
+  if (
+    command === "admin" &&
+    positional[0] === "builds" &&
+    positional[1] === "review"
+  ) {
+    const allowed = new Set([
+      "help",
+      "output",
+      "outputDir",
+      "dir",
+      "waitMs",
+      "interact",
+      "browserPath",
+      "json",
+      "apiUrl",
+      "siteUrl",
+      "authFile",
+      "authToken",
+      "clientName",
+      "timeoutMs",
+      "noUpdateCheck",
+    ]);
+    for (const key of Object.keys(raw)) {
+      if (!allowed.has(key))
+        throw new Error(
+          `Unsupported Build review option --${key.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)}. Runtime review already uses the published app; use pull --published for its source.`,
+        );
+    }
+  }
   const suggestionInboxActions = new Set([
     "list",
     "merge",
@@ -2592,6 +2646,8 @@ export function parseArgs(args) {
     adminReviewed: Boolean(raw.reviewed),
     adminSeverity: raw.severity ? String(raw.severity) : "",
     adminStatus: raw.status ? String(raw.status) : "",
+    followupRevision: raw.revision ? String(raw.revision) : "",
+    todoWorkflowFile: raw.workflow ? String(raw.workflow) : "",
     adminDecision: raw.decision ? String(raw.decision) : "",
     adminWaitMs: raw.waitMs ? String(raw.waitMs) : "",
     adminBrowserPath: raw.browserPath ? String(raw.browserPath) : "",
@@ -2673,6 +2729,7 @@ export function parseArgs(args) {
         ? String(raw.addIds)
         : "",
     adminBucketId: raw.bucketId ? String(raw.bucketId) : "",
+    adminDeviceKey: raw.deviceKey ? String(raw.deviceKey) : "",
     adminLabel: raw.label ? String(raw.label) : "",
     adminUserIds: raw.userIds ? String(raw.userIds) : "",
     adminUser: raw.user ? String(raw.user) : "",
@@ -2806,6 +2863,7 @@ export function parseArgs(args) {
     clientName: String(raw.clientName || "Lumine CLI").slice(0, 120),
     dir: raw.dir ? String(raw.dir) : "",
     pullMain: parseBoolean(raw.main, false),
+    pullPublished: parseBoolean(raw.published, false),
     // Strict: only a plain positive integer counts. Anything else (missing
     // value, "foo", a swallowed flag like "--main", "2.5") stays 0 and the
     // consuming command must reject it via versionProvided instead of
@@ -3065,6 +3123,7 @@ export function printHelp() {
   lumine pull [twinkle-build-url]
   lumine pull [twinkle-build-url] --main
   lumine pull [twinkle-build-url] --version <n> [--main]
+  lumine pull [twinkle-build-url] --published [--main]
   lumine versions [twinkle-build-url] [--main] [--limit <n>]
   lumine restore <n> [--main]
   lumine reference <twinkle-build-url>
@@ -3104,6 +3163,7 @@ export function printHelp() {
   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]
+  lumine admin ai-bucket device block-signup --bucket-id <id> --user <source-user-id> --device-key <inspection-key> --user-ids <reviewed-device-users> --note <reason> [--json]
   lumine admin ai-bucket note set --bucket-id <id> --note <text> [--json]
   lumine admin ai-email-policy get --email <address> [--json]
   lumine admin ai-email-policy set --email <address> --mode <automatic|separate_accounts> --note <text> [--json]
@@ -3114,7 +3174,7 @@ export function printHelp() {
   lumine admin escalation set <audit-id> --status open|acknowledged|resolved --note <decision> [--json]
   lumine admin todo list [--status pending|open|in_progress|blocked|completed|cancelled|all] [--limit <number>] [--json]
   lumine admin todo add --title <title> --note <handoff-and-acceptance-criteria> [--kind task|experiment] [--status open|in_progress|blocked] [--json]
-  lumine admin todo update <todo-id> --status open|in_progress|blocked|completed|cancelled --note <progress-or-evidence> [--json]
+  lumine admin todo update <todo-id> --status open|in_progress|blocked|completed|cancelled --note <progress-or-evidence> [--workflow <file.json> --revision <n>] [--json]
   lumine admin sponsor applications list [--status pending|approved|rejected|withdrawn] [--json]
   lumine admin sponsor applications review <application-id> --decision approve|reject [--note <text>] [--json]
   lumine admin sponsor status set <user-id> --status probationary|trusted|suspended|revoked [--note <text>] [--json]
@@ -3277,6 +3337,7 @@ Options:
   --no-review-loop      Skip the evidence-based post-run loop retrospective
   --target <build>      Explicit Build URL or ID for rename/describe/upgrade
   --main                With pull/versions/restore: target the team project's main
+  --published           With pull: exact currently published artifact, read-only
   --version <n>         With pull: read-only checkout of previous save v<n>
   --title <text>        Build title for new/rename, or private todo title
   --description <text>  Build description for new/describe

package/lib/math-lab-build-sheet.js

@@ -0,0 +1,133 @@
+// Merges parts/<level>.json into the private question sheet the Math Lab
+// uploads with `lumine rewards sheet`, then validates the sheet against the
+// workspace's rewards.json exactly the way the server will (same code).
+// Usage: node --import tsx build-sheet.mjs --approved-review <live review id>
+// Reads that review afresh and preserves its questions before writing output.
+import fs from "node:fs";
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import {
+  LEVELS,
+  verifyApprovedPrefix,
+  verifyRewardEconomy,
+} from "./math-lab-preservation.js";
+
+export async function buildMathLabSheet({
+  contentDir,
+  args = process.argv.slice(2),
+}) {
+  const here = path.resolve(contentDir);
+  const parts = path.join(here, "parts");
+  if (
+    args.length !== 2 ||
+    args[0] !== "--approved-review" ||
+    !/^[1-9]\d*$/.test(args[1])
+  ) {
+    throw new Error(
+      "Usage: node --import tsx build-sheet.mjs --approved-review <current live review id>. No sheet was written.",
+    );
+  }
+  const cli = fileURLToPath(new URL("../bin/lumine.js", import.meta.url));
+  const approved = JSON.parse(
+    execFileSync(
+      process.execPath,
+      [
+        cli,
+        "admin",
+        "reward-review",
+        "show",
+        args[1],
+        "--json",
+        "--no-update-check",
+      ],
+      {
+        encoding: "utf8",
+        timeout: 60000,
+        maxBuffer: 16 * 1024 * 1024,
+      },
+    ),
+  );
+  const sheet = { rules: {} };
+  const missing = [];
+  for (const level of LEVELS) {
+    const file = path.join(parts, `${level}.json`);
+    if (!fs.existsSync(file)) {
+      missing.push(level);
+      continue;
+    }
+    const data = JSON.parse(fs.readFileSync(file, "utf8"));
+    sheet.rules[`${level}-daily`] = {
+      sets: data.sets.map((set) => ({
+        key: set.key,
+        questions: set.questions.map((q) => ({
+          prompt: q.prompt,
+          answer: q.answer,
+          ...(q.hint ? { hint: q.hint } : {}),
+          ...(q.guide ? { guide: q.guide } : {}),
+        })),
+      })),
+    };
+  }
+  const out = path.resolve(here, "..", "math-lab-sheet.json");
+  if (missing.length)
+    throw new Error(
+      `Missing grade parts: ${missing.join(", ")}. No sheet was written.`,
+    );
+  const preservation = verifyApprovedPrefix(sheet, approved);
+
+  // Server-identical validation: rewards.json + sheet → approved-shape config.
+  const policy = await import(
+    pathToFileURL(
+      path.resolve(
+        here,
+        "..",
+        "..",
+        "twinkle-api",
+        "helpers",
+        "build",
+        "rewardsPolicy.ts",
+      ),
+    ).href
+  );
+  const declared = JSON.parse(
+    fs.readFileSync(
+      path.resolve(here, "..", "math-lab", "rewards.json"),
+      "utf8",
+    ),
+  );
+  const composed = policy.composeRewardConfig({ declared, sheet });
+  if (composed.errors.length) {
+    for (const error of composed.errors) console.log(`- ${error}`);
+    process.exit(1);
+  }
+  verifyRewardEconomy(composed.config, approved);
+  const total = composed.config.rules.reduce(
+    (sum, rule) => sum + (rule.sets || []).length,
+    0,
+  );
+  // Nothing replaces the prior usable sheet until every check succeeds.
+  const output = JSON.stringify(sheet, null, 1) + "\n";
+  fs.writeFileSync(`${out}.next`, output, { mode: 0o600 });
+  fs.renameSync(`${out}.next`, out);
+  fs.writeFileSync(
+    `${out}.preservation.json`,
+    JSON.stringify(
+      {
+        ...preservation,
+        checkedAt: new Date().toISOString(),
+        sha256: createHash("sha256").update(output).digest("hex"),
+      },
+      null,
+      2,
+    ) + "\n",
+    { mode: 0o600 },
+  );
+  console.log(
+    `wrote ${out}; preserved ${preservation.rules.reduce((n, r) => n + r.preserved, 0)} published questions from review ${preservation.liveReview}`,
+  );
+  console.log(
+    `composed OK: ${composed.config.rules.length} rules, ${total} sets, ${Buffer.byteLength(JSON.stringify(sheet))} bytes`,
+  );
+}

package/lib/math-lab-preservation.js

@@ -0,0 +1,105 @@
+import { isDeepStrictEqual } from "node:util";
+
+export const LEVELS = [
+  "e1",
+  "e2",
+  "e3",
+  "e4",
+  "e5",
+  "e6",
+  "m1",
+  "m2",
+  "m3",
+  "h1",
+  "h2",
+  "h3",
+];
+
+export function verifyRewardEconomy(config, response) {
+  const withoutRefillSets = (value) => ({
+    ...value,
+    rules: value.rules.map((rule) => {
+      if (!LEVELS.some((level) => rule.id === `${level}-daily`)) return rule;
+      const { sets: _sets, ...economy } = rule;
+      return economy;
+    }),
+  });
+  if (
+    !isDeepStrictEqual(
+      withoutRefillSets(config),
+      withoutRefillSets(response.data.review.config),
+    )
+  ) {
+    throw new Error(
+      "A refill must preserve the approved reward rules and budgets. Review any economy change separately.",
+    );
+  }
+}
+
+// Refill-only: edits/removals to existing questions need a separate content review.
+export function verifyApprovedPrefix(sheet, response) {
+  const review = response?.data?.review;
+  const artifact = Number(review?.publishedArtifactVersionId);
+  if (
+    response?.ok !== true ||
+    Number(review?.buildId) !== 2460 ||
+    review?.status !== "approved" ||
+    review?.isLive !== true ||
+    !Number.isSafeInteger(artifact) ||
+    artifact <= 0 ||
+    Number(review?.publishedVersionId) !== artifact
+  ) {
+    throw new Error(
+      "A fresh, live, approved Math Lab review is required. Re-read the current reward review.",
+    );
+  }
+  const rules = review.config?.rules;
+  if (!Array.isArray(rules))
+    throw new Error("The approved review has no question rules.");
+  const result = [];
+  for (const level of LEVELS) {
+    const id = `${level}-daily`;
+    const matches = rules.filter((rule) => rule.id === id);
+    const before = matches[0]?.sets;
+    const after = sheet?.rules?.[id]?.sets;
+    if (
+      matches.length !== 1 ||
+      !Array.isArray(before) ||
+      !before.length ||
+      !Array.isArray(after)
+    ) {
+      throw new Error(
+        `${id}: missing or ambiguous approved questions or candidate grade.`,
+      );
+    }
+    if (after.length < before.length)
+      throw new Error(
+        `${id}: candidate loses ${before.length - after.length} approved questions.`,
+      );
+    for (let i = 0; i < before.length; i++) {
+      if (!isDeepStrictEqual(after[i], before[i])) {
+        throw new Error(
+          `${id}: approved question ${before[i].key || i + 1} changed or moved. Sync the canonical sheet before refilling.`,
+        );
+      }
+    }
+    const keys = after.map((set) => set.key);
+    if (
+      keys.some((key) => typeof key !== "string" || !key.trim()) ||
+      new Set(keys).size !== keys.length
+    ) {
+      throw new Error(`${id}: question keys must be present and unique.`);
+    }
+    result.push({
+      rule: id,
+      preserved: before.length,
+      added: after.length - before.length,
+    });
+  }
+  return {
+    liveReview: Number(review.id),
+    artifactVersionId: artifact,
+    preservedExact: true,
+    rules: result,
+  };
+}

package/lib/workspace.js

@@ -738,6 +738,8 @@ export async function writeVersionCheckoutMetadata({
         readOnly: true,
         versionCheckout: true,
         checkoutVersion: Number(version?.version || 0) || null,
+        checkoutArtifactVersionId: Number(version?.versionId || 0) || null,
+        publishedCheckout: options.pullPublished === true,
         checkoutVersionSummary: version?.summary || null,
         checkoutVersionCreatedAt: Number(version?.createdAt || 0) || null,
         build: {

package/package.json

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

package/sdk/BUILD_SDK_INDEX.md

@@ -502,9 +502,9 @@ const result = await Twinkle.ai.chat({ message, history: chatHistory, systemProm
   - Template values describe types, not answers to copy. All object keys are required and extra keys are rejected, including inside nested objects; {} means an exactly empty object, not a free-form dictionary. A non-empty array uses only its first item as the template for every returned item, with no fixed length; mixed examples do not declare a union. [] allows arbitrary JSON items. A null template accepts any JSON primitive (string, number, boolean or null), but the key is still required. Use 'number' for fractional numbers; 0 and other integer examples require integers. State content requirements in prompt or instructions. GPT routes retain descriptive string examples as field guidance, not enforced enum values.
   - GPT models prefer native JSON Schema output for compatible shapes. Shapes outside the strict provider subset, such as [] with arbitrary items or deeply nested structures, use prompt-based JSON generation with the same final validation. A provider rejection specifically of the native schema triggers one prompt-based fallback; auth, quota, safety and unrelated request failures do not trigger that fallback. Validation retries preserve the original task and instructions. The returned object/result shape and streaming callbacks are unchanged.
   - mode is accepted as an alias for thinkingMode, and mid is accepted as an alias for medium.
-  - Omit model to use the normal Lite/Medium/High routing. model accepts claude-sonnet-5-5, gpt-6.1-sol or claude-opus-5-5, and every explicit model must be paired with thinkingMode: 'high'; unknown model IDs reject instead of silently falling back. Retired IDs still work and run on their replacement: claude-sonnet-5 runs claude-sonnet-5-5; gpt-6-sol and gpt-5.6-sol run gpt-6.1-sol; gpt-6-astra, claude-opus-5 and claude-fable-5-1 run claude-opus-5-5.
-  - thinkingMode low uses GPT-6 Luna and consumes the viewer's AI Energy from confirmed provider usage; its smaller model is usually cheaper than Medium or High.
-  - thinkingMode medium uses GPT-6 Luna with medium reasoning and consumes normal AI Energy.
+  - Omit model to use the normal Lite/Medium/High routing. Lumine Light defaults to claude-haiku-5-5; gpt-6-luna remains its second choice. Both model IDs accept Low, Medium or High thinking. Explicit claude-sonnet-5-5, gpt-6.1-sol or claude-opus-5-5 still require thinkingMode: 'high'; unknown model IDs reject instead of silently falling back. Retired IDs still work and run on their replacement: claude-sonnet-5 runs claude-sonnet-5-5; gpt-6-sol and gpt-5.6-sol run gpt-6.1-sol; gpt-6-astra, claude-opus-5 and claude-fable-5-1 run claude-opus-5-5.
+  - thinkingMode low uses Claude Haiku 5.5 with low adaptive thinking and consumes the viewer's AI Energy from confirmed provider usage. Set model: 'gpt-6-luna' to choose Luna instead.
+  - thinkingMode medium is Lumine Light: it uses Claude Haiku 5.5 with medium adaptive thinking and consumes normal AI Energy. Set model: 'gpt-6-luna' to keep Luna as the second choice.
   - thinkingMode high without model uses Claude Sonnet 5.5 with high adaptive thinking and consumes high AI Energy. Explicit model: 'gpt-6.1-sol' selects GPT-6.1 Sol with xhigh reasoning at the same High AI Energy tier; model: 'claude-sonnet-5-5' names Sonnet 5.5 directly.
   - claude-sonnet-5-5 and claude-opus-5-5 use Anthropic adaptive High thinking and debit confirmed provider usage at the High tier.
   - Pass onStatus, onReasoning, and/or onText to stream progress from the same structured generation. onStatus receives high-level phases such as thinking, searching_web, responding, validating, and completed.
@@ -513,7 +513,7 @@ const result = await Twinkle.ai.chat({ message, history: chatHistory, systemProm
   - Put a user-facing field such as producerNotes in expectedStructure when commentary must be part of the validated final object rather than transient reasoning progress.
   - When AI Energy is empty, every automatic or named model choice rejects before new provider work; there is no free fallback mode.
   - Live web search is enabled by default in Medium and High modes. Pass webSearch: false to disable it for the app. Low/Lite Mode remains tool-free; explicitly forcing webSearch: true in Low Mode returns an error.
-  - The server validates the final shape; automatic OpenAI/xAI routes can retry malformed output, while Anthropic routes (High without a model, claude-sonnet-5-5 and claude-opus-5-5) use native JSON Schema output and retry one malformed or shape-invalid result. App code should still validate business-specific enum values.
+  - The server validates the final shape; OpenAI/xAI routes can retry malformed output, while Anthropic routes (claude-haiku-5-5, claude-sonnet-5-5 and claude-opus-5-5) use native JSON Schema output and retry one malformed or shape-invalid result. App code should still validate business-specific enum values.
   - Example: const { object } = await Twinkle.ai.generateObject({ thinkingMode: 'high', model: 'claude-opus-5-5', prompt: 'Plan the next section from: ' + currentState, expectedStructure: { producerNotes: 'string', action: 'string', confidence: 'number' }, onStatus: (phase) => showPhase(phase), onReasoning: (summary, meta) => showReasoningProgress(summary, meta), onText: (partialJson, meta) => showStructuredProgress(partialJson, meta) });
 - onChatStatus(listener) | scopes: none
   - Returns: unsubscribe function

package/sdk/LUMINE_ADMIN.md

@@ -130,13 +130,35 @@ private Lumine audit log; no public bot identity is involved.
 canonical bucket. Use it to distinguish quota bookkeeping from moderation;
 the note itself changes no access, ban, or identity rules.
 
-This surface is quota bookkeeping only. It cannot ban accounts, block signup,
+The commands above are quota bookkeeping only. They cannot ban accounts, block signup,
 add IP/device/risk-key rules, or infer an account family. Identification
 remains a human/LLM evidence judgment and must be explicitly requested by
 Mikey; routine administrator runs still escalate suspected alternate accounts
 and never auto-enforce. `accounts add` and `note set` still accept only an
 existing **unbanned** bucket.
 
+For an exact device Mikey explicitly authorizes blocking, use the separate
+signup-only action after reviewing `identity inspect`:
+
+```bash
+lumine admin ai-bucket device block-signup --bucket-id 10 --user 3127 \
+  --device-key 0123456789abcdef --user-ids 3127 \
+  --note "Mikey approved this reviewed device for the household signup block" --json
+```
+
+`--user` is the source account ID; `--user-ids` is the complete reviewed list
+of accounts observed on that device, not every member of the household.
+The API resolves the inspection handle internally, rechecks bounded 365-day
+device evidence, requires the exact expected account set, and rejects devices
+used by anyone outside the existing bucket. Incomplete history, unresolved
+handles and a rule belonging to another bucket stop the action. The bucket
+must already have an active **signup-only** restriction. This cannot turn on
+a bucket ban, change full-site bans, add network rules or infer membership.
+The response confirms the canonical rule and restriction without returning the
+raw device ID. The private audit records the request before evidence is read
+and records successful completion separately. Routine reviews still never
+auto-enforce; this action requires Mikey's explicit instruction for the device.
+
 ### Shared verified-email policies
 
 A verified address proves that an account can use that mailbox; it does not
@@ -198,6 +220,22 @@ IP evidence, private messages, or unrelated activity. `--include-private-evidenc
 adds DOB values and verified email addresses only; exact device IDs are never
 returned.
 
+`sharedDevices[].usage` reports recorded event counts, first/last observed Unix
+timestamps, an `eventsByType` breakdown, and the same details per account. These
+come from `ai_usage_session_evidence`, which records the exact device identifier;
+`users_actions` has account/IP activity but no device identifier. Counts include
+events such as login, logout, socket binding and AI use, **not unique visits or
+physical-device sessions**. Only events attached to an account are counted.
+
+Usage `status: complete` means the queried device's records fit inside the
+365-day lookback and read limit. `partial` counts are lower bounds, with observed
+dates and `truncatedBy` explaining the gap. `not_read` has a null event count,
+never zero. `accountsTruncated` separately marks a capped account-detail list;
+its totals still include omitted accounts. Device discovery can be truncated
+even when an individual device's usage is complete: always check the overall
+`evidenceCoverage` too. Human-readable CLI output includes these distinctions;
+older APIs explicitly report that usage counts are unavailable.
+
 The CLI sends `identity inspect` and `identity network` as reads, so it keeps
 no copy of the result on disk; the server still records who looked, when and
 why, one audit row per call. When a case needs a kept copy (a bullying or police
@@ -1647,6 +1685,39 @@ to a child):
 
 ## Private carry-over todos
 
+### Zero and Ciel's personal follow-ups
+
+Each bot has a separate persistent list of commitments made to members. The
+API reply tools save a concrete task before saying it is on the bot's list;
+they link the real source comment/chat and keep the requesting member and bot
+server-owned. Retries of the same message return the same task. Members can
+ask that bot to read or cancel their own tasks. This does not approve any
+administrative action, deployment, reward, or publication.
+
+Full `daily-run start` returns `personalFollowups` for the assigned bot;
+`daily-run gather` saves its first page in `personal-followups.json`. Follow
+`nextCursor` to exhaustion. Other bots' tasks wait for their own turns, and
+scoped sessions do not surface or modify the list.
+
+```bash
+lumine admin followup list --json
+lumine admin followup list --cursor 100 --json
+lumine admin followup update 17 --revision 2 --status completed --note "Played the requested path on published version 400; observed ...; replied in original comment 91 (reply 103)." --json
+```
+
+Read the original context, do the promised work, keep evidence, and report the
+real result to the member in the original context under the existing reply
+rules. Do not move a private request into a public post. Build replies still
+require exact-version review evidence. Record `blocked` with a concrete next
+step when access, the creator, or Mikey's decision is needed. A completed
+daily run never completes promises automatically. Update requires the current
+revision and the assigned bot's active full run; stale or sibling updates are
+refused. Daily reports include pending follow-ups and their latest progress.
+
+Apply `add-ai-daily-followups.sql` before deploying this API/CLI capability.
+
+### Operator carryovers
+
 ```bash
 lumine admin todo list --json
 lumine admin todo list --status all --json
@@ -1666,6 +1737,35 @@ audit path: canonical todo state and its private `todo.create` / `todo.update`
 audit response commit together, and no public bot, public mutation count, or
 rotation signal is involved.
 
+Track implementation, release and verification separately when a carryover
+involves a fix. After `add-admin-todo-workflow.sql` and the matching API are
+deployed, save a local JSON file such as:
+
+```json
+{
+  "implementation": "ready",
+  "release": "pending",
+  "verification": "pending",
+  "fixRef": "work/topic/release-review.md",
+  "releaseRef": "",
+  "evidence": "Focused regression passed; production is unchanged.",
+  "nextAction": "Deployer releases the reviewed fix, then check the live result."
+}
+```
+
+Use `lumine admin todo update 12 --revision <current-revision> --workflow
+work/topic/workflow.json --status in_progress --note "Ready for the deployer."
+--json`. The revision comes from the canonical list/update response; stale
+updates are rejected. Implementation values are `needed`, `in_progress`,
+`ready`, `not_needed`; release is `pending`, `live`, `not_needed`; verification
+is `pending` or `passed`. Any unfinished phase needs a concrete `nextAction`;
+passed verification needs `evidence`. Completion requires implementation ready
+(or unnecessary), release live (or unnecessary), and verification passed.
+Keep physical-device checks and observation windows pending until they happen.
+Legacy todos have `workflow: null`, which means unknown, never verified. An
+update without `--workflow` preserves an existing workflow and cannot bypass
+its completion requirements.
+
 Every successful full `daily-run start` response automatically includes all
 unfinished items under `data.carryoverTodos`. The same run ID increments an
 item's surfacing telemetry at most once, even when start is retried. This is the