@stage5/lumine 0.3.5 → 0.3.9

package/lib/admin.js

@@ -2112,11 +2112,74 @@ export function parseAdminOperation(options) {
     // reviews as the admin controls on the website quest page. Mikey's own
     // decision, any time, never in a daily run.
     const usage =
-      "Usage: lumine admin meetup list [--status review|active|completed|all] | show <crewId> | approve-plan <crewId> [--note <text>] | send-back <crewId> --note <text> | approve <crewId> --attended <userId,userId,...> [--note <text>] | slot <crewId> --confirm <slotIndex> | resend-email <crewId>.";
+      "Usage: lumine admin meetup list [--status review|active|completed|all] | approve-crew <crewId> | approve-grownup <crewId> | emails [list|send <id>|discard <id>|review on|off] | friends [status|on|off] | parent-reply <crewId> <memberUserId> --note <text> | funnel [--days <1-90>] | branches [list|show|approve|reject|merge] | show <crewId> | approve-plan <crewId> [--note <text>] | send-back <crewId> --note <text> | approve <crewId> --attended <userId,userId,...> [--note <text>] | slot <crewId> --confirm <slotIndex> | resend-email <crewId>.";
     const note = String(options.note || "").trim();
     if (note.length > 1000) {
       throw cliValidationError("--note must be at most 1000 characters.");
     }
+    if (action === "parent-reply") {
+      // Answer a parent's question: shown on their page, and they are emailed.
+      const crewId = parseRequiredInteger(target, "Crew ID", 1);
+      const memberId = parseRequiredInteger(extra, "Member (child) user ID", 1);
+      if (!note) throw cliValidationError("parent-reply needs --note <your answer>.");
+      return writeOperation(
+        "meetup.parent-reply",
+        "POST",
+        `/cli/admin/meetup-quest/crews/${crewId}/parents/${memberId}/reply`,
+        { reply: note },
+        { requiresRun: false },
+      );
+    }
+    if (action === "branches" || action === "branch") {
+      // Every branch name a member types is registered; the first sighting alerts
+      // Mikey (a Zero DM card). Approve = a real branch, reject = not real (the
+      // members' branch text is cleared and their crew chat is told), merge =
+      // same as an official branch (members are rewritten to its name).
+      const branchUsage =
+        "Usage: lumine admin meetup branches [list [--status pending|official|rejected|all]] | show <id> | approve <id> [--note <text>] | reject <id> [--note <text>] | merge <id> --into <officialId> [--note <text>].";
+      const branchAction = target || "list";
+      if (branchAction === "list") {
+        return readOperation(
+          "meetup.branches",
+          withQuery("/cli/admin/meetup-quest/branches", {
+            status: parseChoice(options.adminStatus || "pending", "--status", [
+              "pending",
+              "official",
+              "rejected",
+              "all",
+            ]),
+          }),
+          { requiresRun: false },
+        );
+      }
+      if (!["show", "approve", "reject", "merge"].includes(branchAction)) {
+        throw cliValidationError(branchUsage);
+      }
+      const branchId = parseRequiredInteger(extra, "Branch ID", 1);
+      if (branchAction === "show") {
+        return readOperation(
+          "meetup.branch.show",
+          `/cli/admin/meetup-quest/branches/${branchId}`,
+          { requiresRun: false },
+        );
+      }
+      if (branchAction === "merge" && !options.adminInto) {
+        throw cliValidationError(
+          "lumine admin meetup branches merge <id> needs --into <officialBranchId> (see `branches list --status official`).",
+        );
+      }
+      return writeOperation(
+        `meetup.branch.${branchAction}`,
+        "POST",
+        `/cli/admin/meetup-quest/branches/${branchId}/review`,
+        {
+          action: branchAction === "approve" ? "official" : branchAction,
+          mergeIntoId: branchAction === "merge" ? parseRequiredInteger(options.adminInto, "--into", 1) : 0,
+          note,
+        },
+        { requiresRun: false },
+      );
+    }
     if (action === "story" || action === "stories") {
       // A crew's Bridge Builder story page: Mikey's final approval (the
       // admin bar on the story page does the same). Publishing copies only
@@ -2155,6 +2218,44 @@ export function parseAdminOperation(options) {
         { requiresRun: false },
       );
     }
+    if (action === "emails") {
+      // Parent emails held for the owner's review: list | send <id> | discard <id> | review on|off
+      const sub = target || "list";
+      if (sub === "list") {
+        return readOperation("meetup.emails", "/cli/admin/meetup-quest/emails", { requiresRun: false });
+      }
+      if (sub === "review") {
+        const on = extra === "on" ? true : extra === "off" ? false : null;
+        if (on === null) throw cliValidationError("lumine admin meetup emails review on|off");
+        return writeOperation("meetup.emails", "POST", "/cli/admin/meetup-quest/emails/review", { on }, { requiresRun: false });
+      }
+      if (sub === "send" || sub === "discard") {
+        const id = parseRequiredInteger(extra, "Email ID", 1);
+        return writeOperation("meetup.emails", "POST", `/cli/admin/meetup-quest/emails/${id}/${sub}`, {}, { requiresRun: false });
+      }
+      throw cliValidationError("lumine admin meetup emails [list | send <id> | discard <id> | review on|off]");
+    }
+    if (action === "friends") {
+      const sub = target || "status";
+      if (sub === "status") {
+        return readOperation("meetup.friends", "/cli/admin/meetup-quest/friends-switch", { requiresRun: false });
+      }
+      if (sub === "on" || sub === "off") {
+        return writeOperation("meetup.friends", "POST", "/cli/admin/meetup-quest/friends-switch", { on: sub === "on" }, { requiresRun: false });
+      }
+      throw cliValidationError("lumine admin meetup friends [status | on | off]");
+    }
+    if (action === "funnel") {
+      // Early-funnel views + where active crews are stuck (for Claude's own
+      // analysis; no owner view).
+      return readOperation(
+        "meetup.funnel",
+        withQuery("/cli/admin/meetup-quest/funnel", {
+          days: parseRequiredInteger(options.adminDays || "14", "--days", 1, 90),
+        }),
+        { requiresRun: false },
+      );
+    }
     if (!action || action === "list") {
       return readOperation(
         "meetup.list",
@@ -2176,6 +2277,18 @@ export function parseAdminOperation(options) {
         { requiresRun: false },
       );
     }
+    if (action === "approve-crew" || action === "approve-grownup") {
+      // Every step passes through the owner: the crew (members + branches) and
+      // the grown-up step (parents' yes + the named adult).
+      const crewId = parseRequiredInteger(target, "Crew ID", 1);
+      return writeOperation(
+        action === "approve-crew" ? "meetup.approve-crew" : "meetup.approve-grownup",
+        "POST",
+        `/cli/admin/meetup-quest/crews/${crewId}/${action}`,
+        {},
+        { requiresRun: false },
+      );
+    }
     if (action === "approve-plan") {
       const crewId = parseRequiredInteger(target, "Crew ID", 1);
       return writeOperation(
@@ -5133,6 +5246,11 @@ function printMeetupCrew(crew) {
     console.log(`  ${step.number}. ${step.label} [${step.state}] ${step.detail}`);
   }
   console.log(`  Members: ${formatMeetupMembers(crew.members)}`);
+  for (const parent of crew.parentContacts || []) {
+    console.log(
+      `  Parent of ${parent.childUsername}: ${parent.status}${parent.verifiedGuardian ? " (guardian on file)" : parent.staffVerified ? " (staff verified)" : " (child-typed address: NOT verified)"} · ${parent.email}${parent.question ? ` · asks: "${parent.question}"` : ""}`,
+    );
+  }
   if (Array.isArray(crew.invites) && crew.invites.length) {
     console.log(
       `  Pending invites: ${crew.invites.map((invite) => `${invite.username} (${invite.userId}, invite ${invite.inviteId})`).join("; ")}`,
@@ -5214,6 +5332,54 @@ function printMeetupResult({ operation, data, result }) {
     }
     return;
   }
+  if (operation.name === "meetup.branches") {
+    const branches = Array.isArray(data.branches) ? data.branches : [];
+    console.log(`${branches.length} branch name(s) (${data.filter || "pending"}):`);
+    for (const branch of branches) {
+      console.log(
+        `  #${branch.id} · ${branch.status}${branch.mergedIntoId ? ` → #${branch.mergedIntoId}` : ""} · "${branch.name}" · ${branch.members} member(s) · first entered by ${branch.firstUsername || "?"}${branch.firstCrewId ? ` in crew #${branch.firstCrewId}` : ""}`,
+      );
+    }
+    if (branches.some((branch) => branch.status === "pending")) {
+      console.log("Decide: lumine admin meetup branches approve <id> | reject <id> | merge <id> --into <officialId>.");
+    }
+    return;
+  }
+  if (operation.name === "meetup.branch.show" || String(operation.name).startsWith("meetup.branch.")) {
+    const branch = data.branch || {};
+    console.log(
+      `Branch #${branch.id} "${branch.name}" is now ${branch.status}${branch.mergedIntoName ? ` (merged into "${branch.mergedIntoName}")` : ""} · ${branch.members} member(s) use it · first entered by ${branch.firstUsername || "?"}.`,
+    );
+    return;
+  }
+  if (operation.name === "meetup.emails") {
+    console.log(`Parent email review: ${data.review ? "ON (emails wait for you)" : "OFF (emails go out at once)"}`);
+    const open = (data.drafts || []).filter((d) => d.status === "held" || d.status === "failed");
+    if (!open.length) console.log("Nothing is waiting.");
+    for (const d of open) {
+      console.log(`\n#${d.id} [${d.status}] crew #${d.crewId} ${d.kind === "brief" ? "meetup request" : "reply"} -> ${d.to}`);
+      console.log(`  Subject: ${d.subject}`);
+      console.log(`  ${String(d.body).split("\n").join("\n  ")}`);
+    }
+    return;
+  }
+  if (operation.name === "meetup.friends") {
+    console.log(`Friend buttons are ${data.on ? "ON" : "OFF"}.`);
+    return;
+  }
+  if (operation.name === "meetup.funnel") {
+    console.log(`Bridge Builder funnel, last ${data.windowDays} day(s)${data.trackingLive ? "" : " (view tracking NOT live yet)"}:`);
+    for (const [kind, v] of Object.entries(data.views || {})) {
+      console.log(`  ${kind}: ${v.users} people, ${v.hits} visits`);
+    }
+    console.log(`  quest page viewers: ${data.questPage?.viewers ?? 0}, of whom ever in a crew: ${data.questPage?.viewersEverInCrew ?? 0}`);
+    console.log(`  crews by status: ${JSON.stringify(data.crews?.byStatus || {})}; active by step: ${JSON.stringify(data.crews?.activeByStep || {})}; active by size: ${JSON.stringify(data.crews?.activeBySize || {})}`);
+    if (data.branches) console.log(`  branch names: ${JSON.stringify(data.branches.byStatus)}${data.branches.oldestPendingHours ? `; oldest pending ${data.branches.oldestPendingHours}h` : ""}`);
+    for (const crew of data.activeCrews || []) {
+      console.log(`  #${crew.crewId} step ${crew.step} · ${crew.members} member(s) · idle ${crew.daysIdle}d · ${crew.unverifiedBranches ? `${crew.unverifiedBranches} branch(es) to verify · ` : ""}${crew.parents && crew.parents.asked ? `parents ${crew.parents.approved}/${crew.parents.asked} · ` : ""}chat7d ${crew.chat7d ? `${crew.chat7d.messages} msg/${crew.chat7d.speakers} people` : "n/a"} · ${crew.blocking}`);
+    }
+    return;
+  }
   if (operation.name === "meetup.list") {
     const crews = Array.isArray(data.crews) ? data.crews : [];
     console.log(`${crews.length} meetup crew(s) (${data.filter || "review"}):`);
@@ -5229,7 +5395,7 @@ function printMeetupResult({ operation, data, result }) {
     }
     return;
   }
-  if (operation.name === "meetup.show") {
+  if (operation.name === "meetup.show" || operation.name === "meetup.parent-reply") {
     printMeetupCrew(data.crew || {});
     return;
   }
@@ -5250,11 +5416,15 @@ function printMeetupResult({ operation, data, result }) {
     return;
   }
   const stage = data.result?.stage === "video" ? "video" : "plan";
-  if (operation.name === "meetup.approve-plan") {
+  if (operation.name === "meetup.approve-crew" || operation.name === "meetup.approve-grownup") {
+    console.log(
+      `${result?.changed === false ? "Already approved" : "Approved"} crew #${data.result?.crewId}'s ${operation.name === "meetup.approve-crew" ? "crew step" : "grown-up step"}.`,
+    );
+  } else if (operation.name === "meetup.approve-plan") {
     console.log(
       result?.changed === false
         ? `Crew #${data.result?.crewId}'s plan was already approved.`
-        : `Approved crew #${data.result?.crewId}'s plan. They can meet up and film it now.`,
+        : `Approved crew #${data.result?.crewId}'s plan. Next the crew gets its parents' yes and names a grown-up.`,
     );
   } else if (operation.name === "meetup.send-back") {
     console.log(`Sent crew #${data.result?.crewId}'s ${stage} back with your note.`);
@@ -5262,7 +5432,7 @@ function printMeetupResult({ operation, data, result }) {
     const unlocked = data.unlocks?.unlockedUserIds || [];
     const failed = data.unlocks?.failed || [];
     console.log(
-      `${result?.changed === false ? "Already approved" : "Approved"} crew #${data.result?.crewId}: unlocked for user(s) ${unlocked.join(", ") || "none"}.${failed.length ? ` Unlock FAILED for ${failed.join(", ")}; run the same command again.` : ""}`,
+      `${result?.changed === false ? "Already approved" : "Approved"} crew #${data.result?.crewId}${data.result?.tier ? ` at ${data.result.tier} tier` : ""}: unlocked for user(s) ${unlocked.join(", ") || "none"}.${failed.length ? ` Unlock FAILED for ${failed.join(", ")}; run the same command again.` : ""}`,
     );
   }
   if (data.crew) printMeetupCrew(data.crew);

package/lib/commands.js

@@ -2609,6 +2609,7 @@ export function parseArgs(args) {
     storageSize: raw.size ? String(raw.size) : "",
     adminAttended: raw.attended ? String(raw.attended) : "",
     adminConfirm: raw.confirm === undefined ? "" : String(raw.confirm),
+    adminInto: raw.into === undefined ? "" : String(raw.into),
     adminNoAnnounce: Boolean(raw.noAnnounce),
     adminContextLimit: raw.limit === undefined ? 20 : Number(raw.limit),
     adminRun: raw.run ? String(raw.run) : "",
@@ -3015,7 +3016,7 @@ export function printHelp() {
   lumine admin reward-review list [--status pending|approved|all] [--cursor <id>] [--json]
   lumine admin cardcraft-review list [--status pending|approved|all] [--cursor <id>] | show <id> | approve|reject|revoke <id> [--reason <text>]
   lumine admin storage list [--status pending|approved|rejected|all] [--cursor <id>] | show <user-id-or-username> | approve <request-id> [--size <500MB|1GB|2GB|n MB>] [--reason <text>] | reject <request-id> [--reason <text>] | grant <user-id-or-username> --size <500MB|1GB|2GB|n MB> [--reason <text>]
-  lumine admin meetup list [--status review|active|completed|all] | show <crewId> | approve-plan <crewId> [--note <text>] | send-back <crewId> --note <text> | approve <crewId> --attended <userId,userId,...> [--note <text>] | slot <crewId> --confirm <slotIndex> | resend-email <crewId>   (Bridge Builder meetup quest)
+  lumine admin meetup list [--status review|active|completed|all] | approve-crew <crewId> | approve-grownup <crewId> | emails [list|send <id>|discard <id>|review on|off] | friends [status|on|off] | parent-reply <crewId> <memberUserId> --note <text> | funnel [--days <1-90>] | branches [list [--status pending|official|rejected|all] | show <id> | approve <id> | reject <id> [--note <text>] | merge <id> --into <officialId>] | show <crewId> | approve-plan <crewId> [--note <text>] | send-back <crewId> --note <text> | approve <crewId> --attended <userId,userId,...> [--note <text>] | slot <crewId> --confirm <slotIndex> | resend-email <crewId>   (Bridge Builder meetup quest)
   lumine admin meetup story list | show <crewId> | approve <crewId> [--note <text>] [--no-announce] | send-back <crewId> --note <text> | unpublish <crewId> --note <text>   (Bridge Builder story pages: publishes only what every tagged member's parent allowed)
   lumine admin reward-activity [--date YYYY-MM-DD] [--days <1..31>] [--build <id>] [--json]
   lumine admin chat-reports list [--status pending|open|reviewing|resolved|dismissed|all] [--cursor <id>] [--json]

package/lib/sdk.js

@@ -214,6 +214,16 @@ export const SDK_CLI_METHODS = {
     scopes: ["rewards:claim"], readOnly: true,
     mapArgs: (args) => ({ ruleId: args.ruleId, cursor: args.cursor, limit: args.limit }),
   },
+  "rewards.interpretAnswer": {
+    path: "api/rewards/interpret-answer", special: "rewards", operation: "interpret-answer",
+    scopes: ["rewards:claim"], readOnly: true,
+    mapArgs: (args) => ({ challengeId: args.challengeId, text: args.text }),
+  },
+  "rewards.getChallengeBoard": {
+    path: "api/rewards/challenge-board", special: "rewards", operation: "challenge-board",
+    scopes: ["rewards:claim"], readOnly: true,
+    mapArgs: () => ({}),
+  },
   "rewards.getArchivedProblem": {
     path: "api/rewards/archived-problem", special: "rewards", operation: "archived-problem",
     scopes: ["rewards:claim"], readOnly: true,

package/lib/sponsor-duty.js

@@ -60,8 +60,10 @@ export async function sponsorDutyCommand(options, args, commandServices) {
     return;
   }
   if (action === "watch") {
-    await withSponsorStateLock(options, () =>
-      watchDuty(options, commandServices),
+    await withSponsorStateLock(
+      options,
+      () => watchDuty(options, commandServices),
+      "watch",
     );
     return;
   }
@@ -162,6 +164,17 @@ export async function sponsorJobCommand(options, args, commandServices) {
     );
     return;
   }
+  if (action === "release") {
+    const positionalReason = args.slice(2).join(" ").trim();
+    await withSponsorStateLock(options, () =>
+      releaseJob(
+        options,
+        jobId,
+        options.sponsorFailureReason || positionalReason,
+      ),
+    );
+    return;
+  }
   if (action === "fail") {
     const positionalReason = args.slice(2).join(" ").trim();
     await withSponsorStateLock(options, () =>
@@ -1396,6 +1409,35 @@ async function completeJob(options, jobId, commandServices) {
   ]);
 }
 
+// Hands the job back to the pool instead of failing the user's request:
+// another live session picks it up. Use it when this session should not
+// (or cannot) do the job; `fail` is only for work that genuinely cannot be done.
+async function releaseJob(options, jobId, rawReason) {
+  const reason = String(rawReason || "").trim();
+  if (!reason) {
+    throw new Error("Say why this session is handing the job back with --reason <text>.");
+  }
+  const auth = await ensureSponsorAuth(options);
+  let state = await loadOwnedState({ options, auth });
+  ({ state } = await heartbeatJob({ options, auth, state, jobId }));
+  const jobState = requireJobState(state, jobId);
+  const result = await retrySponsorTransport(() =>
+    sponsorJobRequest({
+      options,
+      auth,
+      state,
+      jobState,
+      path: "/release",
+      body: { reason: reason.slice(0, 1000) },
+    }),
+  );
+  await removeCompletedJob({ options, state, jobId });
+  printJsonOrLines(options, result, [
+    `Workshop job #${jobId} is back in the queue for another on-duty session. The user's request is still open.`,
+    "This session will not claim it again.",
+  ]);
+}
+
 async function failJob(options, jobId, rawReason) {
   const reason = String(rawReason || "").trim();
   if (!reason) {
@@ -1539,8 +1581,10 @@ async function recordClaim({ options, state, claim }) {
       "Twinkle returned a Workshop runtime that does not match this live agent session.",
     );
   }
+  const jobRoot = sponsorJobRoot(options);
+  await fs.mkdir(jobRoot, { recursive: true, mode: 0o700 });
   const tempDir = await fs.mkdtemp(
-    path.join(os.tmpdir(), `lumine-${persona}-job-${jobId}-`),
+    path.join(jobRoot, `lumine-${persona}-job-${jobId}-`),
   );
   await fs.chmod(tempDir, 0o700);
   const jobState = {
@@ -2127,14 +2171,24 @@ async function tryArchiveInvalidSponsorStateForStop(options) {
   }
 }
 
-async function withSponsorStateLock(options, operation) {
+// A session's own `duty watch` holds this lock for up to a full watch window,
+// so job commands wait that long instead of failing mid-job; a second watch
+// still fails fast.
+function sponsorLockWaitMs(kind) {
+  return kind === "watch"
+    ? SPONSOR_LOCK_WAIT_MS
+    : MAX_DUTY_WATCH_MS + DUTY_WATCH_DEADLINE_GRACE_MS + 5_000;
+}
+
+async function withSponsorStateLock(options, operation, kind = "command") {
   const lockPath = `${sponsorDutyStatePath(options)}.lock`;
   const lockDirectory = path.dirname(lockPath);
   await fs.mkdir(lockDirectory, { recursive: true, mode: 0o700 });
   let handle;
   // Short check-ins (the lease keeper, a pulse) hold the lock for well under
   // a second, so a colliding command waits briefly instead of failing.
-  const waitUntil = Date.now() + SPONSOR_LOCK_WAIT_MS;
+  const waitUntil = Date.now() + sponsorLockWaitMs(kind);
+  let toldWaiting = false;
   for (;;) {
     try {
       handle = await fs.open(lockPath, "wx", 0o600);
@@ -2151,6 +2205,12 @@ async function withSponsorStateLock(options, operation) {
           "Another sponsor duty command is still running for this login. Wait for it to finish instead of starting overlapping watchers or job mutations.",
         );
       }
+      if (!toldWaiting && kind !== "watch") {
+        toldWaiting = true;
+        console.error(
+          "lumine: waiting for this session's duty watch to finish its check-in…",
+        );
+      }
       await new Promise((resolve) => setTimeout(resolve, 250));
     }
   }
@@ -2305,11 +2365,26 @@ async function scrubPreservedWorkspaceCredential(preserved) {
   preserved.credentialsRemovedAt = credentialState.credentialsRemovedAt;
 }
 
+// Job workspaces live next to the CLI's auth file, not in the OS temp
+// directory: a reboot or crash there wipes unsaved Workshop work, and agents
+// on duty may be barred from writing to temp directories at all.
+const SPONSOR_JOB_ROOT_NAME = "lumine-sponsor-jobs";
+
+function sponsorJobRoot(options) {
+  return path.join(
+    path.dirname(path.resolve(options.authFile)),
+    SPONSOR_JOB_ROOT_NAME,
+  );
+}
+
 function resolveJobTempDir(jobState) {
   const tempRoot = path.resolve(os.tmpdir());
   const tempDir = path.resolve(String(jobState?.tempDir || ""));
+  // Jobs claimed by older CLI versions still sit in the OS temp directory.
+  const parent = path.dirname(tempDir);
   if (
-    !tempDir.startsWith(`${tempRoot}${path.sep}`) ||
+    (path.basename(parent) !== SPONSOR_JOB_ROOT_NAME &&
+      !tempDir.startsWith(`${tempRoot}${path.sep}`)) ||
     !path.basename(tempDir).startsWith("lumine-") ||
     !path.basename(tempDir).includes("-job-")
   ) {
@@ -2657,6 +2732,7 @@ function sponsorJobUsage() {
     "  lumine sponsor job rename <job-id> <title>",
     "  lumine sponsor job describe <job-id> <text>",
     "  lumine sponsor job complete <job-id> --summary <text> [--resolved-model <name>] [--resolved-effort <level>] [--resolved-service-tier <tier>]",
-    "  lumine sponsor job fail <job-id> --reason <text>",
+    "  lumine sponsor job release <job-id> --reason <text>   (hand back to the pool; the request stays open)",
+    "  lumine sponsor job fail <job-id> --reason <text>      (ends the user's request)",
   ].join("\n");
 }

package/lib/sponsor.js

@@ -1,9 +1,11 @@
+import { readFileSync } from "node:fs";
 import readline from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
 
 import { ensureAuth } from "./auth.js";
 import {
   sponsorDutyCommand,
+  sponsorDutyStatePath,
   sponsorJobCommand,
 } from "./sponsor-duty.js";
 import { requestJson } from "./http.js";
@@ -59,7 +61,7 @@ export async function sponsorCommand(options, commandServices) {
       auth,
       path: `/jobs?limit=${encodeURIComponent(String(options.limit || 20))}`,
     });
-    printSponsorJobs(result, options);
+    printSponsorJobs(result, options, localDutyId(options));
     return;
   }
   if (area === "status") {
@@ -308,9 +310,37 @@ function printSponsorAgreement(agreement, options) {
   for (const line of agreement.disclosure || []) console.log(`- ${line}`);
 }
 
-function printSponsorJobs(jobs, options) {
+// This session's own duty, so the list can say which jobs are its own.
+function localDutyId(options) {
+  try {
+    const state = JSON.parse(readFileSync(sponsorDutyStatePath(options), "utf8"));
+    return Number(state?.duty?.id || 0) || null;
+  } catch {
+    return null;
+  }
+}
+
+function describeJobHolder(job, ownDutyId) {
+  const holder = Number(job.heldByDutySessionId || 0) || null;
+  if (!holder) return null;
+  return holder === ownDutyId
+    ? `held by duty #${holder} (this session)`
+    : `held by duty #${holder} (another session; not yours)`;
+}
+
+function printSponsorJobs(jobs, options, ownDutyId = null) {
   if (options.json) {
-    console.log(JSON.stringify(jobs, null, 2));
+    console.log(
+      JSON.stringify(
+        (Array.isArray(jobs) ? jobs : []).map((job) => ({
+          ...job,
+          heldByThisSession:
+            !!ownDutyId && Number(job.heldByDutySessionId) === ownDutyId,
+        })),
+        null,
+        2,
+      ),
+    );
     return;
   }
   if (!Array.isArray(jobs) || jobs.length === 0) {
@@ -318,8 +348,10 @@ function printSponsorJobs(jobs, options) {
     return;
   }
   for (const job of jobs) {
+    const target = job.targetBuild || job.contributionBuild;
+    const holder = describeJobHolder(job, ownDutyId);
     console.log(
-      `#${job.id} ${job.status} · ${displayPersona(job.persona)} · ${job.requester?.username || `user ${job.requester?.userId}`} · ${job.contributionBuild?.title || `Build ${job.contributionBuild?.id}`}`,
+      `#${job.id} ${job.status}${holder ? ` (${holder})` : ""} · ${displayPersona(job.persona)} · ${job.requester?.username || `user ${job.requester?.userId}`} · ${target?.title || `Build ${target?.id}`}`,
     );
   }
 }

package/package.json

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

package/sdk/BUILD_SDK_INDEX.md

@@ -2,7 +2,7 @@
 
 Version: 1.63.0
 Updated: 2026-09-28
-Generated: 2026-09-30T09:55:20.738Z
+Generated: 2026-10-03T09:02:05.836Z
 
 ## Notes
 - This SDK is injected into Build iframes via the Build preview/runtime.
@@ -81,8 +81,9 @@ files:read, media:read, media:write, live:read, live:write, user:read, users:rea
 
 ### Twinkle.viewer
 - async get() | scopes: none
-  - Returns: { id, username, profilePicUrl, isLoggedIn, isOwner, isGuest }
+  - Returns: { id, username, profilePicUrl, isLoggedIn, isOwner, isGuest, ageTier }
   - Cached; use refresh() to re-fetch.
+  - ageTier is 'kid', 'teen' or 'adult', taken from the viewer's Teenager and Adult achievements (granted once an admin approves their birthdate). Guests and viewers without either achievement are 'kid'. It is a display and default-selection hint computed by the Twinkle page; do not treat it as a server-side permission.
 - async refresh() | scopes: none
   - Returns: Viewer info
   - Forces a fresh fetch from the parent.
@@ -551,16 +552,18 @@ const result = await Twinkle.ai.chat({ message, history: chatHistory, systemProm
   - Only one music generation per viewer may run at a time (code ai_music_generation_in_progress). A retry with the same requestId returns the finished result without paying again (replayed: true), or code music_in_progress while it is still being made.
   - Generation usually takes one to three minutes; the SDK timeout defaults to 600000ms. Show progress UI while waiting.
   - Example: const song = await Twinkle.ai.generateMusic({ prompt: 'Warm lo-fi hip hop with dusty drums, a mellow Rhodes and rain in the background', instrumental: true }); audio.src = song.url;
-- async generateSpeech({ text, voice, language, requestId, timeoutMs } = {}) | scopes: none
+- async generateSpeech({ text, voice, style, language, requestId, timeoutMs } = {}) | scopes: none
   - Returns: { success, asset, url, mimeType, durationSeconds, alignment, text, voice, model, requestId, replayed?, aiUsagePolicy }
-  - Generate spoken audio with Eleven v4 and save it in the viewer's Twinkle.files. New generations use AI Battery.
+  - Generate spoken audio (OpenAI realtime voices or ElevenLabs presets) and save it in the viewer's Twinkle.files. New generations use AI Battery.
   - Signed-in viewers only. Each new generation uses AI Battery; show this before the viewer starts voice interaction.
-  - text: 1–2,000 characters. voice: warm (default), bright, or calm. language: optional ISO language code such as en.
+  - text: 1–2,000 characters. language: optional ISO language code such as en.
+  - voice: an OpenAI realtime voice (alloy, ash, ballad, coral, echo, sage, shimmer, verse, marin, cedar) or an ElevenLabs preset (warm, bright, calm; warm is the default). For a recurring character, pick one voice and keep it everywhere, including any pre-recorded lines, so the character always sounds the same.
+  - style (OpenAI voices only): up to 300 characters of performance direction such as age, mood, pace and clarity. The voice reads the text word for word in that style.
   - The MP3 is saved in the viewer's Twinkle.files and counts toward storage. Replay the saved URL to listen again without another AI request.
-  - alignment contains provider character timing for subtitles or animation. Respect Twinkle tab mute and browser playback controls.
+  - alignment contains provider character timing for subtitles or animation (ElevenLabs presets only; null for OpenAI voices). Respect Twinkle tab mute and browser playback controls.
   - Reuse requestId after a lost response. Completed audio replays the saved asset and settles the same billing receipt without regeneration or duplicate charges.
   - Only one speech or transcription request per viewer runs at a time. SDK timeout defaults to 180000ms.
-  - Example: const speech = await Twinkle.ai.generateSpeech({ text: 'Welcome to our club!', voice: 'warm', language: 'en' }); audio.src = speech.url;
+  - Example: const speech = await Twinkle.ai.generateSpeech({ text: 'Welcome to our club!', voice: 'shimmer', style: 'Cheerful, curious thirteen-year-old girl; bright and warm.', language: 'en' }); audio.src = speech.url;
 - async transcribeAudio({ audioBase64, language, requestId, timeoutMs } = {}) | scopes: none
   - Returns: { success, text, words: [{ text, start, end }], language, durationSeconds, model, requestId, replayed?, aiUsagePolicy }
   - Recognize a short recording with ElevenLabs Scribe v2. New recognition requests use AI Battery.
@@ -1497,7 +1500,7 @@ world.updatePresence({ x, y, z, facing });
 - await Twinkle.rewards.progress({ challengeId, completionToken?, frames?, record?, requestId? }) | scopes: rewards:claim
   - Returns: { mode: "live" | "preview", completion: { profile, token?, completed, failed?, decision?, message?, maxFrames? }, aiUsagePolicy? }
   - Verify a bounded batch of inputs for an approved server-simulated climb.
-  - Only for completionProof: classic-tower-v1. Send 1 to 600 chronological physics frames, each [dt, moveX, moveY, cameraForwardX, cameraForwardZ, jumpPressed, jumpHeld, speedMultiplier]. dt is in seconds, at most 0.05; movement axes are -1 through 1; the camera values are the horizontal components before normalization; jump flags are 0 or 1; speedMultiplier is an existing Classic Tower trail speed (1, 1.1, 1.2, 1.3, 1.35 or 1.4). Geometry and player state are owned by the registered server simulation.
+  - Only for completionProof: classic-tower-v1. Send 1 to 600 chronological physics frames, each [dt, moveX, moveY, cameraForwardX, cameraForwardZ, jumpPressed, jumpHeld, speedMultiplier]. dt is in seconds, at most 0.05; movement axes are -1 through 1; the camera values are the horizontal components before normalization; jump flags are 0 or 1; speedMultiplier is an existing Classic Tower trail speed (1, 1.1, 1.2, 1.3, 1.35, 1.4, 1.6 or 2.2). Geometry and player state are owned by the registered server simulation.
   - Send occasional batches with at most one request in flight. Keep the previous token and the exact batch until a response confirms it; an identical retry is safe. Use the returned token for the next batch. Simulation time cannot outrun wall time. A completed token is evidence of a legal simulated run, not proof that a human played or that inputs were not automated.
   - On respawn or a return from another world, begin a fresh run at the canonical spawn via start. Preserve other worlds and gameplay. Do not submit positions, scores, secret keys, or a client completion flag. Preview tokens can never be redeemed in the published app.
   - For breadface-v1, breadface-v2 and breadface-v3, send 1–1,000 chronological [dt, inputBits] frames (dt > 0 and <= 0.033). Bits are left=1, right=2, jumpHeld=4, jumpQueued=8, fireHeld=16. The server replays the registered frozen game; only a legitimate goal and any rule-specific bonus qualify. Honor maxFrames and retain unacknowledged inputs for a bounded retry.
@@ -1515,6 +1518,21 @@ world.updatePresence({ x, y, z, facing });
   - Standings of who earned the most XP or Coins in THIS app, computed by Twinkle from its own receipts (never from anything the app submits). period 'day' is today (site day, UTC), 'week' the last 7 site days, 'all' (default) every day since approval. limit defaults to 20, max 100.
   - available says which boards this app's approved rules can pay: show a Coins board only when available.coins is true (an app whose rules pay XP only has no Coins standings). me is the signed-in viewer's own standing even when they fall outside the page, or null when they earned nothing in the period.
   - Drafts and previews return mode 'preview' with no entries. Use Twinkle.leaderboards for app-defined scores; use this for real XP and Coins earned.
+- await Twinkle.rewards.interpretAnswer({ challengeId, text }) | scopes: rewards:claim
+  - Returns: { mode: "live" | "preview", understood: boolean, value: number | null, source: "plain" | "model" }
+  - Read a learner's free-form answer text into the single number they meant, so they can answer in any format.
+  - For numeric-quiz bounties. Call it only when the typed text is not already a plain number or fraction (check that locally); a plain number returns source 'plain' with no model call. Then pass the returned value to claim({ challengeId, answers: [value] }). A small model reads the text and the platform pays for it, so the learner's AI Energy is never charged.
+  - understood: false means the text had no single clear number (several alternatives, no number, or a calculation). Tell the learner in friendly words to type just the number. This is not a wrong answer and does not use a try.
+  - The reader is given the puzzle text only to learn the requested answer format (unit, fraction/decimal/percent, which of several numbers answers the question), never the answer key, and never calculates or converts units: it only reads what was written, and the number it returns must be one the learner actually typed. Typed expressions like 5+8 are intentionally not evaluated.
+  - Requires an open challenge of the learner's own (build_reward_challenge_not_open, HTTP 409 otherwise). Limit: 120 characters (build_reward_answer_text_invalid, 400), rate limited to a burst of 4 then one read every 5 seconds (build_reward_throttled, 429). build_reward_answer_reader_unavailable (503) means the reader is down: ask the learner to type just the number.
+  - Drafts and owner previews return mode 'preview' and need no open challenge.
+- await Twinkle.rewards.getChallengeBoard() | scopes: rewards:claim
+  - Returns: { mode: "live", dayKey, puzzles: [{ ruleId, title, setKey, rating, solvers, failers, failures, daysStanding, status: "untouched" | "undefeated" | "defeated" }], topSolvers: [{ rank, userId, username, profilePicUrl, rating, solves, hardestSolve: { ruleId, setKey, rating } | null }], recentSolves: [{ id, userId, username, ruleId, setKey, tier: "solved" | "first-solve" | "hard-won" | "legendary", attempt, firstSolve, failersBefore, failuresBefore, daysStanding, puzzleRating, at }], me: { rating, solves, rank } | null } | { mode: "preview", puzzles: [], topSolvers: [], recentSolves: [], me: null, message }
+  - Front-page difficulty board for until-earned quiz bounties: what is being tried and failed, who is rated highest, and the latest defeats.
+  - Computed by Twinkle from its own receipts and attempts, never from anything the app submits. Puzzles are Elo-rated against players: a player's first miss on a puzzle is a win for the puzzle, a solve is a win for the player, and repeat misses by one player never stack.
+  - puzzles lists today's set for each until-earned rule. status 'undefeated' means someone tried and nobody has solved it yet; show it as a standing challenge. failers is how many different players missed it; failures is total wrong answers.
+  - tier on a recent solve says how loudly to celebrate: 'legendary' (first solve of a long-undefeated puzzle), 'hard-won', 'first-solve', or plain 'solved'. It is fixed at solve time, so it never changes later.
+  - No questions, answers, guides or private work are ever returned. Names are the same public names the XP leaderboard shows; other players who missed a puzzle are counted, never named. Drafts and previews return mode 'preview' with empty lists.
 - await Twinkle.rewards.getTimeline({ ruleId?, cursor?, limit? } = {}) | scopes: rewards:claim
   - Returns: { mode: "live", dayKey, entries: [{ receiptId, ruleId, ruleTitle, setKey, title, promptPreview, dayKey, closedAt, solvedAt, solver: { userId, username }, firstSolver, xp, coins, attempt }], nextCursor } | { mode: "preview", entries: [], nextCursor: null, message }
   - Browse confirmed solves of retired until-earned quiz bounties, newest first.