@stage5/lumine 0.2.99 → 0.3.1

package/lib/admin.js

@@ -640,6 +640,8 @@ export async function adminCommand(options) {
   let runScope = null;
   let correctionSessionId = 0;
   let correctionSession = null;
+  let commentSessionId = 0;
+  let commentSession = null;
   if (adminOperationRequiresRun(operation)) {
     if (operation.correctionEligible) {
       const correctionStatus = await requestJson({
@@ -657,6 +659,15 @@ export async function adminCommand(options) {
         correctionSession = correction;
       }
     }
+    if (!correctionSessionId && adminOperationUsesCommentSession(operation)) {
+      commentSession = await loadActiveCommentSession({
+        options,
+        authToken: auth.token,
+      });
+      commentSessionId = Number(commentSession?.id || 0);
+    }
+    // Look up the daily run too: when both are active the caller must choose
+    // one (--via), and exactly one authority is sent.
     const runStatus = correctionSessionId
       ? null
       : await requestJson({
@@ -671,9 +682,39 @@ export async function adminCommand(options) {
     ].includes(operation.name)
       ? runStatus?.data?.lastRun || null
       : null;
-    const selectedRun = activeRun || retryableFinishedRun;
+    let selectedRun = activeRun || retryableFinishedRun;
+    const via = parseAdminVia(options.adminVia, operation);
+    if (via && correctionSessionId) {
+      throw cliValidationError(
+        `Correction session #${correctionSessionId} is active for this comment and handles it; drop --via or complete the correction first.`,
+      );
+    }
+    if (commentSessionId && selectedRun) {
+      let choice = via;
+      if (!choice) {
+        if (COMMENT_SESSION_WRITE_OPERATIONS.has(operation.name)) {
+          throw cliValidationError(
+            `Both comment session #${commentSessionId} (${commentSession.identity?.key || "unknown"}) and daily run #${selectedRun.id} (${selectedRun.identity?.key || "unknown"}) are active. Choose which one this ${operation.name} uses with --via session or --via run.`,
+          );
+        }
+        // Reads create nothing; without --via they keep using the daily run.
+        choice = "run";
+      }
+      if (choice === "session") {
+        selectedRun = null;
+      } else {
+        commentSessionId = 0;
+        commentSession = null;
+      }
+    } else if (via === "session" && !commentSessionId) {
+      throw cliValidationError(
+        "--via session: no comment session is active. Start one with lumine admin comment session start.",
+      );
+    } else if (via === "run" && !selectedRun && !correctionSessionId) {
+      throw noActiveRunError();
+    }
     runId = Number(selectedRun?.id || 0);
-    if (!runId && !correctionSessionId) {
+    if (!runId && !correctionSessionId && !commentSessionId) {
       if (operation.correctionEligible) {
         const error = new Error(
           `Start a correction session first: lumine admin correction start ${operation.correctionCommentId}.`,
@@ -687,7 +728,17 @@ export async function adminCommand(options) {
       runScope = canonicalAdminRunScope(selectedRun);
       assertAdminOperationAllowedForRunScope({ operation, runScope });
     }
-    if (options.adminIdentity && (selectedRun || correctionSession)) {
+    if (options.adminIdentity && commentSession) {
+      const requestedIdentity = parseIdentity(options.adminIdentity);
+      if (
+        requestedIdentity !== "auto" &&
+        requestedIdentity !== commentSession.identity?.key
+      ) {
+        throw cliValidationError(
+          `--identity ${requestedIdentity} does not match comment session #${commentSessionId} (${commentSession.identity?.key || "unknown"}).`,
+        );
+      }
+    } else if (options.adminIdentity && (selectedRun || correctionSession)) {
       const requestedIdentity = parseIdentity(options.adminIdentity);
       const canonicalIdentity = correctionSession
         ? correctionSession.identity?.key
@@ -722,6 +773,11 @@ export async function adminCommand(options) {
                   String(correctionSessionId),
               }
             : {}),
+          ...(commentSessionId
+            ? {
+                "x-lumine-admin-comment-session-id": String(commentSessionId),
+              }
+            : {}),
           ...(requestId ? { "x-lumine-idempotency-key": requestId } : {}),
         },
         // Long operations (reward-bank seed) carry their own timeout.
@@ -1529,6 +1585,81 @@ export function assertAdminOperationAllowedForRunScope({
   );
 }
 
+// Commands a standalone comment session can serve: drafting, replying,
+// publishing and editing its own comments, plus the reads needed to compose
+// on its targets. The API still enforces the session's target lock on each.
+const COMMENT_SESSION_WRITE_OPERATIONS = new Set([
+  "comment.draft",
+  "comment.post",
+  "comment.edit",
+]);
+const COMMENT_SESSION_OPERATIONS = new Set([
+  ...COMMENT_SESSION_WRITE_OPERATIONS,
+  "subject.get",
+  "subject.comments",
+  "post.get",
+  "post.comments",
+]);
+
+export function adminOperationUsesCommentSession(operation) {
+  return COMMENT_SESSION_OPERATIONS.has(operation?.name);
+}
+
+export function parseAdminVia(value, operation) {
+  const via = String(value || "").trim().toLowerCase();
+  if (!via) return "";
+  if (via !== "session" && via !== "run") {
+    throw cliValidationError("--via must be session or run.");
+  }
+  if (!adminOperationUsesCommentSession(operation)) {
+    throw cliValidationError(
+      "--via applies only to comment draft/reply/post/edit and the subject/post/comment reads.",
+    );
+  }
+  return via;
+}
+
+async function loadActiveCommentSession({ options, authToken }) {
+  let status;
+  try {
+    status = await requestJson({
+      url: `${options.apiUrl}/cli/admin/comment-sessions/status`,
+      authToken,
+      timeoutMs: options.timeoutMs,
+    });
+  } catch (error) {
+    // An API without comment sessions yet: keep daily runs working.
+    if (error?.status === 404) return null;
+    throw error;
+  }
+  const session = status?.data?.commentSession || null;
+  return session?.status === "active" && Number(session.id) > 0
+    ? session
+    : null;
+}
+
+export function parseCommentSessionTargets(values) {
+  const raw = values
+    .flatMap((value) => String(value || "").split(","))
+    .map((value) => value.trim())
+    .filter(Boolean);
+  if (!raw.length) {
+    throw cliValidationError(
+      "Name the targets with --target <subject:ID|comment:ID|build:ID|aiStory:ID|dailyReflection:ID>[,...].",
+    );
+  }
+  const seen = new Set();
+  const targets = [];
+  for (const value of raw) {
+    const target = parseAdminCommentTarget({ target: value });
+    const key = `${target.type}:${target.id}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    targets.push(target);
+  }
+  return targets;
+}
+
 function adminOperationRequiresRun(operation) {
   if (typeof operation.requiresRun === "boolean") {
     return operation.requiresRun;
@@ -1547,6 +1678,9 @@ function adminOperationRequiresRun(operation) {
       "correction.start",
       "correction.status",
       "correction.complete",
+      "comment-session.start",
+      "comment-session.status",
+      "comment-session.close",
       "escalation.list",
       "escalation.set",
       "notable.add",
@@ -2283,7 +2417,7 @@ export function parseAdminOperation(options) {
     // long as two GPT-6 Sol calls, so it gets its own timeout. The daily
     // website management run calls it in a bounded loop (Mikey, 2026-09-28).
     const usage =
-      "Usage: lumine admin reward-bank coverage <buildId> [--max-step 3] | seed <buildId> [--max-step 3].";
+      "Usage: lumine admin reward-bank coverage <buildId> [--max-step 3] | seed <buildId> [--max-step 3] | report <buildId> [--days 1].";
     const buildId = parseRequiredInteger(
       target || options.adminBuild,
       "Build ID",
@@ -2293,6 +2427,20 @@ export function parseAdminOperation(options) {
       ? parseRequiredInteger(options.adminMaxStep, "--max-step", 1)
       : 3;
     if (maxStep > 10) throw cliValidationError("--max-step must be at most 10.");
+    if (action === "report") {
+      const days = options.adminDays
+        ? parseRequiredInteger(options.adminDays, "--days", 1)
+        : 1;
+      if (days > 31) throw cliValidationError("--days must be at most 31.");
+      return readOperation(
+        "reward-bank.report",
+        withQuery("/cli/admin/reward-bank/report", {
+          buildId: String(buildId),
+          days: String(days),
+        }),
+        { requiresRun: false },
+      );
+    }
     if (action === "coverage" || action === "status") {
       return readOperation(
         "reward-bank.coverage",
@@ -3361,6 +3509,51 @@ export function parseAdminOperation(options) {
   }
 
   if (namespace === "comment") {
+    if (action === "session") {
+      const sessionAction = target || "status";
+      if (sessionAction === "status") {
+        return readOperation(
+          "comment-session.status",
+          "/cli/admin/comment-sessions/status",
+        );
+      }
+      if (sessionAction === "start") {
+        const identity = String(options.adminIdentity || "")
+          .trim()
+          .toLowerCase();
+        if (identity !== "zero" && identity !== "ciel") {
+          throw cliValidationError(
+            "comment session start needs --identity zero|ciel.",
+          );
+        }
+        const targets = parseCommentSessionTargets([
+          options.adminTarget,
+          ...(options.positional || []).slice(3),
+        ]);
+        const reason = String(options.adminReason || "").trim();
+        return writeOperation(
+          "comment-session.start",
+          "POST",
+          "/cli/admin/comment-sessions",
+          {
+            identity,
+            targets,
+            ...(reason ? { reason } : {}),
+          },
+        );
+      }
+      if (sessionAction === "close") {
+        return writeOperation(
+          "comment-session.close",
+          "POST",
+          "/cli/admin/comment-sessions/close",
+          {},
+        );
+      }
+      throw cliValidationError(
+        "Usage: lumine admin comment session start --identity zero|ciel --target <type:id>[,<type:id>...] [--reason <text>] | comment session status | comment session close.",
+      );
+    }
     if (action === "draft" || action === "reply") {
       const parsedTarget = parseAdminCommentTarget({
         target,
@@ -5211,6 +5404,70 @@ function printReviewRequestResult({ operation, data, result }) {
   printReviewEvents(data.events);
 }
 
+// Human view of `lumine admin reward-bank report`; --json has everything.
+function printRewardBankReport(data) {
+  const pct = (value) =>
+    value === null || value === undefined ? "–" : `${Math.round(value * 100)}%`;
+  console.log(`Question bank report · build #${data.buildId} · last ${data.days} day(s)`);
+  if (data.coverage) {
+    console.log(
+      `Seeding coverage (steps 1-3): ${data.coverage.filled} / ${data.coverage.total}`,
+    );
+  }
+  if (!data.generation) {
+    console.log("Generation: no telemetry table yet.");
+  } else {
+    for (const row of data.generation.bySource) {
+      if (!row.rounds) continue;
+      console.log(
+        `Generation (${row.source}): ${row.rounds} rounds · ${row.accepted} accepted (${pct(row.acceptRate)}) · off-brief ${row.offBrief} · answer mismatch ${row.answerMismatch} · malformed ${row.malformed} · errors ${row.errors} · $${row.costUsd} · avg ${row.avgSeconds ?? "–"}s (max ${row.maxSeconds ?? "–"}s)`,
+      );
+    }
+    for (const row of data.generation.recentRejections.slice(0, 5)) {
+      console.log(
+        `  rejected ${row.outcome} ${row.ruleId}/${row.topicKey} step ${row.step}: ${row.problems || "(no reason given)"}`,
+      );
+    }
+  }
+  console.log(`Learners: ${data.learners.total}`);
+  for (const row of data.learners.byRuleStep) {
+    console.log(
+      `  ${row.ruleId} step ${row.step}: served ${row.served} · answered ${row.answered} · first-try ${pct(row.firstTryRate)} · solved ${row.solved} · skipped ${row.skipped}`,
+    );
+  }
+  const paid = data.payouts.reduce(
+    (sum, row) => ({ xp: sum.xp + row.xp, coins: sum.coins + row.coins, receipts: sum.receipts + row.receipts }),
+    { xp: 0, coins: 0, receipts: 0 },
+  );
+  console.log(
+    `Payouts: ${paid.receipts} receipts · ${paid.xp.toLocaleString()} XP · ${paid.coins.toLocaleString()} Coins`,
+  );
+  for (const row of data.payouts) {
+    console.log(
+      `  ${row.ruleId} step ${row.step}: ${row.receipts} (${row.firstTry} first try) · ${row.earners} earners · ${row.xp.toLocaleString()} XP · ${row.coins.toLocaleString()} Coins`,
+    );
+  }
+  if (data.ladder.length) {
+    console.log(
+      `Ladder now: ${data.ladder.map((row) => `${row.ruleId} s${row.step}:${row.topicLadders}`).join(", ")}`,
+    );
+  }
+  const hidden = data.bank.filter((row) => row.status === "hidden");
+  console.log(
+    `Bank: ${data.bank.filter((row) => row.status === "active").reduce((n, row) => n + row.questions, 0)} active · ${hidden.reduce((n, row) => n + row.questions, 0)} hidden${hidden.length ? ` (${hidden.map((row) => `${row.hiddenReason}: ${row.questions}`).join(", ")})` : ""} · ${data.bank.reduce((n, row) => n + row.createdInWindow, 0)} new in window`,
+  );
+  for (const row of data.questionsToReview.reported) {
+    console.log(
+      `  reported #${row.id} (${row.reports}, ${row.status}) ${row.ruleId}/${row.topicKey} s${row.step}: ${row.reasons}`,
+    );
+  }
+  for (const row of data.questionsToReview.hardest) {
+    console.log(
+      `  hardest #${row.id} ${row.ruleId}/${row.topicKey} s${row.step}: solved ${pct(row.solveRate)} of ${row.learners}`,
+    );
+  }
+}
+
 function printAdminResult({ operation, result }) {
   const data = result?.data || {};
   if (printChatSafetyResult({ operation, data })) return;
@@ -5218,6 +5475,10 @@ function printAdminResult({ operation, result }) {
     printRewardActivity(data);
     return;
   }
+  if (operation.name === "reward-bank.report") {
+    printRewardBankReport(data);
+    return;
+  }
   if (operation.name.startsWith("reward-bank.")) {
     if (operation.name === "reward-bank.seed") {
       console.log(

package/lib/commands.js

@@ -2597,6 +2597,7 @@ export function parseArgs(args) {
     adminUnviewed: Boolean(raw.unviewed),
     adminViewed: Boolean(raw.viewed),
     adminIdentity: raw.identity ? String(raw.identity) : "",
+    adminVia: raw.via ? String(raw.via) : "",
     adminScope: raw.scope ? String(raw.scope) : "",
     commentMode: raw.commentMode ? String(raw.commentMode) : "",
     runKey: raw.runKey ? String(raw.runKey) : "",
@@ -3059,9 +3060,13 @@ export function printHelp() {
   lumine admin post reward <target> [--type subject|comment|aiStory|dailyReflection] --twinkles 3 [--json]
   lumine admin reward-bank coverage <buildId> [--max-step 3] [--json]
   lumine admin reward-bank seed <buildId> [--max-step 3] [--json]   (daily run: writes ONE missing seed question, lowest step first, billed to Zero/Ciel's AI Energy)
+  lumine admin reward-bank report <buildId> [--days 1] [--json]   (question-bank telemetry: generation outcomes, learners, payouts, ladder, questions to review)
   lumine admin comment draft <target> [--type subject|comment|build|aiStory|dailyReflection] [--file <comment.md>] [--review-receipt <review.json>|--reviewed-version <id> --reviewed-via runtime|code] [--review-context <context.json>] [--identity zero|ciel|auto] [--json]
   lumine admin comment reply comment:<id> [--file <reply.md>] [--reviewed-version <id> --reviewed-via runtime|code] [--review-context <context.json>] [--identity zero|ciel|auto] [--json]
   lumine admin comment post --draft-id <id> [--json]
+  lumine admin comment session start --identity zero|ciel --target <subject:ID|comment:ID|build:ID|aiStory:ID>[,...] [--reason <text>] [--json]
+  lumine admin comment session status|close [--json]
+    (with both a comment session and a daily run active, comment draft/reply/post/edit need --via session|run)
   lumine admin comment edit <comment-id> --file <comment.md> [--review-receipt <review.json> | --reviewed-version <id> --reviewed-via runtime|code] [--review-context <context.json>] [--json]
   lumine admin brief [--days <1..30>] [--json]
   lumine admin ai-costs monthly [--output <file.json>] [--json] (no active run required)

package/package.json

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

package/sdk/LUMINE_ADMIN.md

@@ -1304,8 +1304,18 @@ them so the first learner on a unit never waits or pays.
 ```bash
 lumine admin reward-bank coverage <buildId> [--max-step 3] [--json]   # read-only, no run
 lumine admin reward-bank seed <buildId> [--max-step 3] [--json]       # delegated full run
+lumine admin reward-bank report <buildId> [--days 1] [--json]         # read-only telemetry
 ```
 
+`report` covers the last `--days` (1-31): generation rounds by source
+(learner or seed) with outcomes (`accepted`, `off_brief`: the checker judged
+the question outside the brief's language, level or LaTeX rule;
+`answer_mismatch`; `malformed`; `error`), cost and time, and recent rejection
+reasons; learners served/answered/first-try/solved/skipped per rule and step;
+payouts; the current ladder distribution; active/hidden questions; the
+hardest questions (3+ learners) and every reported question with reasons;
+and seeding coverage for steps 1-3 once the app is approved.
+
 - `seed` writes ONE question per call into the first missing slot, lowest
   step first across every topic of every generated-quiz rule, up to
   `--max-step` (default 3, at most 10). A slot is a (rule, topic, step) with
@@ -4171,6 +4181,74 @@ canonical review record ID before claiming success. Older APIs that still block
 Build edits must be deployed first; do not silently substitute a duplicate reply
 when Mikey requested an edit.
 
+### Standalone comment sessions
+
+Posting a few new comments or replies as Zero or Ciel does not require a full
+daily run. An approved operator names the identity and the exact targets:
+
+```bash
+lumine admin comment session start --identity ciel \
+  --target subject:123,comment:456 --reason "Mikey asked for a reply" --json
+lumine admin subject get 123 --include-comments --json
+lumine admin comment draft subject:123 --file comment.md --json
+lumine admin comment reply comment:456 --file reply.md --json
+lumine admin comment post --draft-id <id> --json
+lumine admin comment edit <commentId> --file corrected.md --json
+lumine admin comment session status --json
+lumine admin comment session close --json
+```
+
+`--target` takes a comma-separated list (extra space-separated targets after
+it also count); each is `subject:ID`, `comment:ID`, `build:ID`, `aiStory:ID` or
+`dailyReflection:ID`, at most ten. Pass them in one `--target`: a repeated
+`--target` flag keeps only its last value. The server checks every target when
+the session starts and refuses one the draft path would refuse later.
+
+What the session authorizes:
+
+- **Scopes:** only `content:read`, `comment:draft` and `comment:post`. No chat,
+  Featured, reward, recommendation, subject, newspaper or run-completion
+  command works through it; those still need a daily run.
+- **Target lock:** drafts, replies and the reads above work only on the named
+  targets. A reply target counts when it is a named `comment:ID`, or a comment
+  sitting directly in a named subject, Build, AI Story or Daily Reflection.
+  Anything else fails with `CLI_ADMIN_COMMENT_SESSION_TARGET_FORBIDDEN` and
+  the allowed list. `comment post` accepts only drafts created in the session.
+- **Edits:** `comment edit <commentId>` works under the session only for a
+  comment this session itself posted, as the same identity
+  (`CLI_ADMIN_COMMENT_SESSION_EDIT_FORBIDDEN` otherwise). The usual edit rules
+  apply unchanged, including fresh Build review evidence for a Build comment.
+  Edits do not count toward the post cap.
+- **Limits:** 30 minutes, at most five published comments
+  (`CLI_ADMIN_COMMENT_SESSION_POST_CAP`), one active session per operator.
+  `close` or the TTL ends it; start a new session for more.
+- **Same bar as a daily run:** drafting and publishing use the exact daily-run
+  draft/publish path. Build comments still require composed text, a review
+  receipt or `--reviewed-version/--reviewed-via` evidence of the current
+  published version, and `--review-context`; context and persona revisions
+  are checked at publish time as usual.
+- **Identity:** the operator must be an approved delegated administrator, and
+  the session posts only as the identity named at start (`--identity auto` is
+  not accepted). It does not change the Bangkok calendar assignment or the
+  identity preference.
+
+A comment session and a daily run can be active together, but every request
+carries exactly one authority. The session never claims the daily-run slot.
+
+- When only one of them is active, the CLI uses it.
+- When both are active, `comment draft`, `comment reply`, `comment post` and
+  `comment edit` refuse to run until you choose with `--via session` or
+  `--via run`. Target reads (`subject get`, `post get`, `comments get`, their
+  comment lists) default to the daily run and take `--via session` to read
+  through the session instead.
+- The API refuses a request that names a comment session together with a
+  daily run or correction session (`CLI_ADMIN_AMBIGUOUS_AUTHORITY`); a session
+  request outside the session is refused, never handed to the run.
+- A draft records the authority that created it, and only that authority can
+  publish it (`CLI_ADMIN_DRAFT_AUTHORITY_MISMATCH`).
+- A correction session still takes precedence for its one comment; `--via` is
+  refused while it is active for that comment.
+
 **Editing the bot's own comments.** `comment edit <commentId> --file
 <comment.md>` replaces the text of a comment the acting bot itself authored —
 for correcting a factual error, an unfulfillable claim, or outdated guidance