@stage5/lumine 0.2.59 → 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
@@ -283,13 +290,18 @@ works:
 
 ```bash
 lumine sponsor job begin 42
+lumine sponsor job update 42 --file /path/to/lumine-update.txt --phase building
 lumine sponsor job pulse 42
 lumine sponsor job relay-applied 42 101
 lumine sponsor job complete 42 --summary "Implemented and tested the approved change"
 ```
 
 `pulse` renews the duty/job leases and returns any newly approved follow-up.
-Run it between substantial work steps. `relay-applied` is an explicit receipt;
+`update` sends the exact file text back to Zero or Ciel as a user-visible
+message from Lumine, their added brain. Use it for concise, deliberate
+milestones only; never send hidden reasoning, raw terminal output, credentials,
+tokens, private paths, or unrelated data. Run `pulse` between substantial work
+steps. `relay-applied` is an explicit receipt;
 completion is rejected until every delivered relay has actually been applied
 and acknowledged. Use `helper-start` and `helper-complete` to record native
 same-session subagents within the configured helper limit—the CLI records them

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

@@ -2409,12 +2409,10 @@ export function parseArgs(args) {
     sponsorAgentOrdinal: raw.ordinal,
     sponsorOutcome: raw.outcome ? String(raw.outcome) : "",
     sponsorFailureReason: raw.reason ? String(raw.reason) : "",
-    sponsorResolvedModel: raw.resolvedModel
-      ? String(raw.resolvedModel)
-      : "",
-    sponsorResolvedEffort: raw.resolvedEffort
-      ? String(raw.resolvedEffort)
-      : "",
+    sponsorUpdateFile: raw.file ? String(raw.file) : "",
+    sponsorUpdatePhase: raw.phase ? String(raw.phase) : "",
+    sponsorResolvedModel: raw.resolvedModel ? String(raw.resolvedModel) : "",
+    sponsorResolvedEffort: raw.resolvedEffort ? String(raw.resolvedEffort) : "",
     sponsorResolvedServiceTier: raw.resolvedServiceTier
       ? String(raw.resolvedServiceTier)
       : "",
@@ -2440,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) : "",
@@ -2749,6 +2749,7 @@ export function printHelp() {
   lumine sponsor duty watch [--wait-ms <ms>] [--json]
   lumine sponsor duty pause|resume|stop
   lumine sponsor job status|pulse|begin <job-id>
+  lumine sponsor job update <job-id> --file <path> [--phase <name>]
   lumine sponsor job relay-applied <job-id> <relay-id...>
   lumine sponsor job helper-start|helper-complete <job-id> [options]
   lumine sponsor job complete <job-id> --summary <text>
@@ -2804,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()
@@ -66,6 +78,13 @@ export async function sponsorJobCommand(options, args, commandServices) {
     await withSponsorStateLock(options, () => beginJob(options, jobId));
     return;
   }
+  if (action === "update") {
+    assertNoExtraArgs(args, 2);
+    await withSponsorStateLock(options, () =>
+      publishDialogueUpdate(options, jobId),
+    );
+    return;
+  }
   if (action === "relay-applied") {
     const relayIds = args
       .slice(2)
@@ -343,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({
@@ -539,10 +592,61 @@ async function beginJob(options, jobId) {
   printJsonOrLines(options, { job: canonicalJobState.job, coordinator: agent }, [
     `Workshop job #${jobId} is now being handled by this same on-duty agent session.`,
     `Apply the approved plan in ${jobState.workspaceDir}.`,
+    `Introduce yourself to ${displayPersona(jobState.job.persona)} as Lumine with: lumine sponsor job update ${jobId} --file <message-file> --phase starting`,
     `Check in with: lumine sponsor job pulse ${jobId}`,
   ]);
 }
 
+async function publishDialogueUpdate(options, jobId) {
+  const messageFile = String(options.sponsorUpdateFile || "").trim();
+  if (!messageFile) {
+    throw new Error(
+      "Write the deliberate user-facing Lumine update to a file and pass --file <path>.",
+    );
+  }
+  const phase = String(options.sponsorUpdatePhase || "").trim();
+  if (phase.length > 40) {
+    throw new Error("--phase must be at most 40 characters.");
+  }
+  const messagePath = path.resolve(messageFile);
+  const messageStat = await fs.stat(messagePath);
+  if (!messageStat.isFile() || messageStat.size > 8_000) {
+    throw new Error("The Lumine update file must be a text file under 8 KB.");
+  }
+  const message = String(await fs.readFile(messagePath, "utf8")).trim();
+  if (!message) throw new Error("The Lumine update file is empty.");
+  if (message.length > 2_000) {
+    throw new Error("The Lumine update must be at most 2,000 characters.");
+  }
+
+  const auth = await ensureSponsorAuth(options);
+  let state = await loadOwnedState({ options, auth });
+  ({ state } = await heartbeatJob({ options, auth, state, jobId }));
+  const jobState = requireJobState(state, jobId);
+  const clientUpdateKey = randomBytes(18).toString("base64url");
+  const result = await retrySponsorCheckIn(() =>
+    sponsorJobRequest({
+      options,
+      auth,
+      state,
+      jobState,
+      path: "/dialogue",
+      body: {
+        clientUpdateKey,
+        phase: phase || null,
+        message,
+      },
+    }),
+  );
+  if (!result?.update?.message) {
+    throw new Error("Twinkle did not confirm the canonical Lumine update.");
+  }
+  printJsonOrLines(options, result, [
+    `Lumine → ${displayPersona(jobState.job.persona)}:`,
+    result.update.message,
+  ]);
+}
+
 async function startHelper(options, jobId) {
   const auth = await ensureSponsorAuth(options);
   let state = await loadOwnedState({ options, auth });
@@ -1177,25 +1281,36 @@ async function writeAssignment(jobState, state) {
   const unapplied = new Set(unappliedRelayIds(jobState));
   const relays = (jobState.relays || [])
     .map((relay) => {
-      const details = [
-        relay.summary,
-        relay.requestedOutcome ? `What to deliver: ${relay.requestedOutcome}` : "",
-        relay.constraints?.length
-          ? `Constraints: ${relay.constraints.join("; ")}`
-          : "",
-        relay.acceptanceCriteria?.length
-          ? `Done means: ${relay.acceptanceCriteria.join("; ")}`
-          : "",
-      ].filter(Boolean);
-      return `## Relay #${relay.id}${unapplied.has(Number(relay.id)) ? " (not yet acknowledged as applied)" : " (applied receipt confirmed)"}\n\n${details.join("\n\n")}`;
+      const dialogueText =
+        String(relay.dialogueText || "").trim() ||
+        [
+          relay.summary,
+          relay.projectTitleHint
+            ? `Project: ${relay.projectTitleHint}`
+            : "",
+          relay.requestedOutcome
+            ? `What to build: ${relay.requestedOutcome}`
+            : "",
+          relay.constraints?.length
+            ? `Keeping in mind:\n${relay.constraints.map((item) => `• ${item}`).join("\n")}`
+            : "",
+          relay.acceptanceCriteria?.length
+            ? `Done means:\n${relay.acceptanceCriteria.map((item) => `• ${item}`).join("\n")}`
+            : "",
+        ]
+          .filter(Boolean)
+          .join("\n\n");
+      return `## Relay #${relay.id}${unapplied.has(Number(relay.id)) ? " (not yet acknowledged as applied)" : " (applied receipt confirmed)"}\n\n${dialogueText}`;
     })
     .join("\n\n");
   const content = `# Lumine Build Workshop assignment #${jobState.job.id}
 
-You are the same live ${displayProvider(state.operatorSession.provider)} agent session that opened sponsor duty. Zero or Ciel is the user's visible teammate; you are lending that teammate an added brain. Perform this work in this session. Do not launch a replacement coding provider or leave an unattended heartbeat process standing in for you.
+You are the same live ${displayProvider(state.operatorSession.provider)} agent session that opened sponsor duty. Zero or Ciel is the user's visible teammate; you are lending that teammate an added brain. In every user-facing Workshop update, you are Lumine: the added brain talking with that teammate. Perform this work in this session. Do not launch a replacement coding provider or leave an unattended heartbeat process standing in for you.
 
 The user approved sharing only this structured plan, active-job follow-ups, the assigned Build project, and its scoped Forum. Never inspect or infer from their private Zero/Ciel chat. Edit only contribution Build #${jobState.job.contributionBuild.id}; never merge Main, publish, or contact the user directly.
 
+Lumine updates are a deliberate public channel. Write concise messages about what you are checking, what you found, or what happens next. Never publish hidden chain-of-thought, raw terminal output, credentials, tokens, private paths, or unrelated data. The exact file text you submit is shown in Twinkle and echoed back by the CLI.
+
 - User: @${jobState.job.requester.username}
 - Visible teammate: ${displayPersona(jobState.job.persona)}
 - Main project: ${jobState.job.rootBuild.title} (#${jobState.job.rootBuild.id})
@@ -1208,10 +1323,11 @@ ${jobState.forumContext ? `## Scoped Build Forum snapshot\n\n${jobState.forumCon
 ## Duty protocol
 
 1. Run \`lumine sponsor job begin ${jobState.job.id}\` before editing.
-2. Work only in the workspace above. Use your native same-session subagents only after registering each with \`helper-start\`. The coordinator alone runs sponsor CLI commands; helpers report their results back to it.
-3. Run \`lumine sponsor job pulse ${jobState.job.id}\` between substantial work steps to keep the lease alive and receive approved follow-ups.
-4. After applying a relay, record its exact ID with \`lumine sponsor job relay-applied ${jobState.job.id} <relay-id...>\`.
-5. Finish with \`lumine sponsor job complete ${jobState.job.id} --summary "..."\`.
+2. Introduce yourself and publish meaningful milestones with \`lumine sponsor job update ${jobState.job.id} --file <message-file> --phase <name>\`. Speak as Lumine, never as the underlying provider.
+3. Work only in the workspace above. Use your native same-session subagents only after registering each with \`helper-start\`. The coordinator alone runs sponsor CLI commands; helpers report their results back to it.
+4. Run \`lumine sponsor job pulse ${jobState.job.id}\` between substantial work steps to keep the lease alive and receive approved follow-ups.
+5. After applying a relay, record its exact ID with \`lumine sponsor job relay-applied ${jobState.job.id} <relay-id...>\`.
+6. Finish with \`lumine sponsor job complete ${jobState.job.id} --summary "..."\`.
 `;
   await fs.writeFile(jobState.assignmentPath, content, {
     encoding: "utf8",
@@ -1865,6 +1981,7 @@ function sponsorJobUsage() {
     "Usage:",
     "  lumine sponsor job status|pulse <job-id>",
     "  lumine sponsor job begin <job-id>",
+    "  lumine sponsor job update <job-id> --file <path> [--phase <name>]",
     "  lumine sponsor job relay-applied <job-id> <relay-id...>",
     "  lumine sponsor job helper-start <job-id> [--ordinal <n>]",
     "  lumine sponsor job helper-complete <job-id> --ordinal <n> --outcome <text> [--resolved-model <name>] [--resolved-effort <level>]",

package/lib/sponsor.js

@@ -391,6 +391,7 @@ function sponsorUsage() {
     "  lumine sponsor duty watch [--wait-ms <ms>] [--json]",
     "  lumine sponsor duty status|pause|resume|stop",
     "  lumine sponsor job status|pulse|begin <job-id>",
+    "  lumine sponsor job update <job-id> --file <path> [--phase <name>]",
     "  lumine sponsor job relay-applied <job-id> <relay-id...>",
     "  lumine sponsor job helper-start|helper-complete <job-id> [options]",
     "  lumine sponsor job complete <job-id> --summary <text>",

package/package.json

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