@stage5/lumine 0.2.60 → 0.2.61

package/README.md

@@ -276,6 +276,13 @@ heartbeat, supervisor, or provider-spawning daemon is not sponsor duty. The CLI
 rejects a provider name that differs from the agent session actually running
 the command.
 
+`duty watch` may return a `teamAccessRequest` instead of a job. Tell the
+sponsor which requester, owner, and project issued the invitation, then return
+to duty without waiting or accepting on the sponsor's behalf. The ordinary
+Twinkle team invitation is already waiting for the sponsor; no Workshop work
+starts unless they accept it there. This notice is invitation metadata only;
+it does not expose the unapproved Workshop plan or private chat.
+
 When a user approves a plan, `duty watch` returns the scoped assignment file and
 contribution workspace to that same session. It does not launch a fresh Codex
 or Claude process. The on-duty agent uses this explicit lifecycle while it

package/lib/admin.js

@@ -310,6 +310,9 @@ export async function adminCommand(options) {
         typeof operation.body.buildReviewUnderstanding === "string",
     });
   }
+  if (operation.name === "ai-email-policy.set") {
+    assertAiEmailPolicySetResult({ operation, result });
+  }
   if (operation.name === "daily-run.start") {
     assertAdminTodoHandoffResult(result);
   }
@@ -493,6 +496,55 @@ export function assertComposedCommentDraftResult({
   throw error;
 }
 
+export function assertAiEmailPolicySetResult({ operation, result }) {
+  const requestedEmail = String(operation?.body?.email || "");
+  const requestedMode = String(operation?.body?.mode || "");
+  const policy = result?.data?.policy;
+  const projection = result?.data?.projection;
+  const accountUserIds = Array.isArray(result?.data?.accountUserIds)
+    ? result.data.accountUserIds
+    : [];
+  const accountCount = Number(result?.data?.accountCount);
+  const expectedIdentityType =
+    requestedMode === "separate_accounts"
+      ? "separate_verified_email"
+      : "verified_email";
+  if (
+    policy?.exists === true &&
+    policy?.normalizedEmail === requestedEmail &&
+    policy?.mode === requestedMode &&
+    Number.isSafeInteger(accountCount) &&
+    accountCount >= 0 &&
+    accountUserIds.length === accountCount &&
+    projection?.expectedIdentityType === expectedIdentityType &&
+    projection?.accountCount === accountCount &&
+    projection?.matchingAccountCount === accountCount &&
+    Array.isArray(projection?.mismatchedAccountUserIds) &&
+    projection.mismatchedAccountUserIds.length === 0 &&
+    projection?.converged === true
+  ) {
+    return;
+  }
+  const error = new Error(
+    "The API did not confirm that every matching account converged to the requested AI email policy. Retry only after reviewing the canonical response and deployed API.",
+  );
+  error.code = "LUMINE_ADMIN_AI_EMAIL_POLICY_NOT_CONVERGED";
+  error.data = {
+    ok: false,
+    status: "partial_failure",
+    error: {
+      code: error.code,
+      message: error.message,
+      details: {
+        requestedEmail,
+        requestedMode,
+        canonical: result?.data || null,
+      },
+    },
+  };
+  throw error;
+}
+
 const RECOMMENDATION_CONTENT_TYPES = new Map([
   ["comment", "comment"],
   ["aistory", "aiStory"],
@@ -616,6 +668,7 @@ function adminOperationRequiresRun(operation) {
       "notable.add",
     ].includes(operation.name) &&
     !operation.name.startsWith("ai-bucket.") &&
+    !operation.name.startsWith("ai-email-policy.") &&
     !operation.name.startsWith("todo.")
   );
 }
@@ -774,6 +827,30 @@ export function parseAdminOperation(options) {
     }
   }
 
+  if (namespace === "ai-email-policy" || namespace === "ai-email-policies") {
+    const email = parseAiEmailPolicyEmail(options.adminEmail);
+    if (action === "get" || action === "status") {
+      return bodyReadOperation(
+        "ai-email-policy.get",
+        "POST",
+        "/cli/admin/ai-email-policies/lookup",
+        { email },
+      );
+    }
+    if (action === "set") {
+      return writeOperation(
+        "ai-email-policy.set",
+        "PUT",
+        "/cli/admin/ai-email-policies",
+        {
+          email,
+          mode: parseAiEmailPolicyMode(options.adminMode),
+          note: parseAiEmailPolicyNote(options.note),
+        },
+      );
+    }
+  }
+
   if (namespace === "todo" || namespace === "todos") {
     if (!action || action === "list") {
       return readOperation(
@@ -1985,6 +2062,10 @@ function readOperation(name, path, extra = {}) {
   };
 }
 
+function bodyReadOperation(name, method, path, body) {
+  return { name, method, path, body, mutates: false };
+}
+
 function writeOperation(name, method, path, body) {
   return { name, method, path, body, mutates: true };
 }
@@ -2156,6 +2237,49 @@ function parseAiBucketUserIds(value) {
   return ids;
 }
 
+function parseAiEmailPolicyEmail(value) {
+  const email = String(value || "")
+    .trim()
+    .toLowerCase();
+  const at = email.indexOf("@");
+  if (
+    !email ||
+    email.length > 320 ||
+    /\s/.test(email) ||
+    at <= 0 ||
+    at !== email.lastIndexOf("@") ||
+    at === email.length - 1
+  ) {
+    throw cliValidationError(
+      "Pass a valid verified email with --email <address>.",
+    );
+  }
+  return email;
+}
+
+function parseAiEmailPolicyMode(value) {
+  const mode = String(value || "")
+    .trim()
+    .toLowerCase();
+  if (mode !== "automatic" && mode !== "separate_accounts") {
+    throw cliValidationError("--mode must be automatic or separate_accounts.");
+  }
+  return mode;
+}
+
+function parseAiEmailPolicyNote(value) {
+  const note = String(value || "").trim();
+  if (!note) {
+    throw cliValidationError("Pass the policy reason with --note <text>.");
+  }
+  if (note.length > 255) {
+    throw cliValidationError(
+      "An AI email-policy note can be at most 255 characters.",
+    );
+  }
+  return note;
+}
+
 function parseRequiredInteger(
   value,
   label,
@@ -2421,7 +2545,9 @@ async function printSpooledAdminResult({ result, storage }) {
       );
     });
   } else if (storage.collectionKey === "comments") {
-    console.log(`${count} comment(s) for ${data.subject?.url || "this target"}:`);
+    console.log(
+      `${count} comment(s) for ${data.subject?.url || "this target"}:`,
+    );
     await forEachPaginatedResultItem(result, async (comment) => {
       console.log(
         `#${comment.id} ${comment.author?.username || "unknown"}: ${comment.content || "(empty)"}`,
@@ -2502,11 +2628,12 @@ function printAdminResult({ operation, result }) {
     console.log(
       `Sponsor-integrity case #${item.id}: ${String(item.status).toUpperCase()} · job #${item.job?.id} · ${item.sponsorUsername || `sponsor ${item.sponsorUserId}`}.`,
     );
-    const relays = Array.isArray(item.relays) && item.relays.length > 0
-      ? item.relays
-      : item.relay
-        ? [item.relay]
-        : [];
+    const relays =
+      Array.isArray(item.relays) && item.relays.length > 0
+        ? item.relays
+        : item.relay
+          ? [item.relay]
+          : [];
     console.log(
       `Relays: ${relays.map((relay) => `${relay.kind || "initial_request"}: ${relay.summary || "(missing)"}`).join(" | ") || "(missing)"}`,
     );

package/lib/commands.js

@@ -2411,12 +2411,8 @@ export function parseArgs(args) {
     sponsorFailureReason: raw.reason ? String(raw.reason) : "",
     sponsorUpdateFile: raw.file ? String(raw.file) : "",
     sponsorUpdatePhase: raw.phase ? String(raw.phase) : "",
-    sponsorResolvedModel: raw.resolvedModel
-      ? String(raw.resolvedModel)
-      : "",
-    sponsorResolvedEffort: raw.resolvedEffort
-      ? String(raw.resolvedEffort)
-      : "",
+    sponsorResolvedModel: raw.resolvedModel ? String(raw.resolvedModel) : "",
+    sponsorResolvedEffort: raw.resolvedEffort ? String(raw.resolvedEffort) : "",
     sponsorResolvedServiceTier: raw.resolvedServiceTier
       ? String(raw.resolvedServiceTier)
       : "",
@@ -2442,6 +2438,8 @@ export function parseArgs(args) {
     adminBucketId: raw.bucketId ? String(raw.bucketId) : "",
     adminLabel: raw.label ? String(raw.label) : "",
     adminUserIds: raw.userIds ? String(raw.userIds) : "",
+    adminEmail: raw.email ? String(raw.email) : "",
+    adminMode: raw.mode ? String(raw.mode) : "",
     adminType: raw.type ? String(raw.type) : "",
     adminKind: raw.kind ? String(raw.kind) : "",
     adminContentTypes: raw.contentTypes ? String(raw.contentTypes) : "",
@@ -2807,6 +2805,8 @@ export function printHelp() {
   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 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]
   lumine admin daily-run start [--identity zero|ciel|auto] [--comment-mode off|draft|post] [--run-key <key>] [--json]
   lumine admin daily-run status|report|complete|fail [--reason <text>] [--json]
   lumine admin daily-run escalation add --target <target> --note <summary> [--severity attention|urgent] [--json]

package/lib/sponsor-duty.js

@@ -21,6 +21,18 @@ const DEFAULT_DUTY_WATCH_MS = 20_000;
 const MAX_DUTY_WATCH_MS = 60_000;
 const MAX_FORUM_CONTEXT_CHARS = 8_000;
 
+function sanitizeSponsorTerminalLabel(value, fallback) {
+  const label = String(value || "")
+    .replace(
+      /[\u0000-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/g,
+      " ",
+    )
+    .replace(/\s+/g, " ")
+    .trim()
+    .slice(0, 200);
+  return label || fallback;
+}
+
 export async function sponsorDutyCommand(options, args, commandServices) {
   const action = String(args[0] || "status")
     .trim()
@@ -350,6 +362,40 @@ async function watchDuty(options, commandServices) {
       );
       continue;
     }
+    if (claim.teamAccessRequest) {
+      const request = claim.teamAccessRequest;
+      const requester = request.requesterUsername
+        ? `@${sanitizeSponsorTerminalLabel(
+            request.requesterUsername,
+            `user-${request.requesterUserId}`,
+          )}`
+        : `user #${request.requesterUserId}`;
+      const owner = request.ownerUsername
+        ? `@${sanitizeSponsorTerminalLabel(
+            request.ownerUsername,
+            `user-${request.ownerUserId}`,
+          )}`
+        : `user #${request.ownerUserId}`;
+      const buildTitle = sanitizeSponsorTerminalLabel(
+        request.buildTitle,
+        `Build #${request.buildId}`,
+      );
+      printJsonOrLines(
+        options,
+        {
+          duty: publicDuty(state.duty),
+          teamAccessRequest: request,
+          assignment: null,
+          nextCommand: "lumine sponsor duty watch --json",
+        },
+        [
+          `${requester} asked to invite this sponsor account to ${buildTitle}, owned by ${owner}.`,
+          "Ask the sponsor whether they want to join. Their usual Twinkle team invitation is already waiting; no Workshop work starts unless they accept it.",
+          "Do not hold the Workshop queue open for a reply. Return to duty after sharing this notice.",
+        ],
+      );
+      return;
+    }
     if (claim.job) {
       state = await recordClaim({ options, state, claim });
       const prepared = await prepareClaimedJob({

package/package.json

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

package/sdk/LUMINE_ADMIN.md

@@ -93,6 +93,41 @@ 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.
 
+### Shared verified-email policies
+
+A verified address proves that an account can use that mailbox; it does not
+always prove that every account using the mailbox is one person. When a teacher,
+school, or other provisioning owner intentionally verifies separate people's
+accounts with one address, record that confirmed operational fact explicitly:
+
+```bash
+lumine admin ai-email-policy get --email teacher@example.com --json
+lumine admin ai-email-policy set --email teacher@example.com \
+  --mode separate_accounts \
+  --note "Teacher-confirmed classroom provisioning address" --json
+```
+
+`separate_accounts` preserves ordinary email verification and recovery while
+giving every current and future account whose stable verified address matches
+its own AI Energy and AI Card quota identity. The mutation re-attributes the
+current day's per-account usage, updates all affected live quota projections
+from canonical server state, and records the real operator in the private
+Lumine audit log. It is a provisioning policy, not an alternate-account finding
+or moderation flag, and must never be inferred from account count, usernames,
+devices, IPs, or email-provider heuristics.
+
+The CLI accepts a successful `set` only when the writer response confirms the
+requested policy and reports every matching account on its exact expected
+durable projection. A missing or mismatched projection fails closed instead of
+letting an operator mistake a stored policy row for completed account repair.
+
+Use `--mode automatic` with a new explanatory `--note` to restore Twinkle's
+default verified-email grouping. Both modes are durable and apply to later
+signups and later verifications without another code change. An active
+email-wide manual identity rule conflicts with `separate_accounts`, so the API
+rejects either operation until the operator explicitly resolves the conflict.
+Exact per-user manual bucket rules remain authoritative in both modes.
+
 ### Audited identity inspection
 
 Account-family evidence is private operator work, never a Zero/Ciel public