@stage5/lumine 0.3.23 → 0.3.24

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(
@@ -6814,6 +6849,7 @@ function printAdminResult({ operation, result }) {
       );
     } else {
       printTodoItems(report.carryoverTodos?.items || [], "Unfinished work");
+      printPersonalFollowups(report.personalFollowups);
     }
     if (report.sponsorIntegrity) {
       const pendingApplications = Number.isSafeInteger(
@@ -6870,6 +6906,7 @@ function printAdminResult({ operation, result }) {
         );
       }
     }
+    for (const line of formatIdentityDeviceUsage(inspection)) console.log(line);
     return;
   }
   if (Array.isArray(data.escalations)) {
@@ -6912,6 +6949,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 +7230,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) {

package/lib/commands.js

@@ -2592,6 +2592,7 @@ 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) : "",
     adminDecision: raw.decision ? String(raw.decision) : "",
     adminWaitMs: raw.waitMs ? String(raw.waitMs) : "",
     adminBrowserPath: raw.browserPath ? String(raw.browserPath) : "",
@@ -2673,6 +2674,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) : "",
@@ -3104,6 +3106,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]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage5/lumine",
-  "version": "0.3.23",
+  "version": "0.3.24",
   "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