@stage5/lumine 0.3.6 → 0.3.10

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("; ")}`,
@@ -5146,7 +5264,7 @@ function printMeetupCrew(crew) {
   const plan = crew.plan || {};
   if (plan.status && plan.status !== "none") {
     console.log(
-      `  Plan (${plan.status}): ${plan.date} in ${plan.area}: ${plan.activity}${plan.note ? ` · note: ${plan.note}` : ""}`,
+      `  Plan (${plan.status}): ${plan.date}${plan.time ? ` at ${plan.time}` : ""} in ${plan.area}: ${plan.activity}${plan.note ? ` · note: ${plan.note}` : ""}`,
     );
   }
   if (crew.planApprovedBy?.username) {
@@ -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"}):`);
@@ -5224,12 +5390,12 @@ function printMeetupResult({ operation, data, result }) {
     }
     if (crews.some((crew) => crew.waitingFor)) {
       console.log(
-        "Review: lumine admin meetup show <crewId>, then approve-plan | send-back --note | approve --attended <ids>.",
+        "Review: lumine admin meetup show <crewId>, then approve-crew | approve-plan | approve-grownup | send-back --note | approve --attended <ids> (classroom plans: approve at the headmaster desk with a room and times).",
       );
     }
     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/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.6",
+  "version": "0.3.10",
   "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-10-03T04:47:01.454Z
+Generated: 2026-10-03T09:02:05.836Z
 
 ## Notes
 - This SDK is injected into Build iframes via the Build preview/runtime.
@@ -552,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.
@@ -1498,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.