@stage5/lumine 0.2.49 → 0.2.51

package/README.md

@@ -267,7 +267,8 @@ lumine admin post recommend comment:456 --anyone-can-reward --reward-twinkles 3
 lumine admin post reward comment:456 --twinkles 3 --json
 lumine admin post skip-batch --target-file skipped.json --checkpoint skip-progress.json --json
 lumine admin comment draft build:884 --file comment.md \
-  --review-receipt /path/from-build-review/review.json --json
+  --review-receipt /path/from-build-review/review.json \
+  --review-context build-context.json --json
 lumine admin comment post --draft-id 77 --json
 lumine admin news claim --output claim.json --scaffold editorial.json --json
 lumine admin news validate --claim claim.json --file editorial.json --json
@@ -285,9 +286,9 @@ Numeric recommendation targets default to subjects. Use `comment:<id>`,
 `aiStory:<id>`, `dailyReflection:<id>`, a canonical URL, or the matching
 `--type` for another post kind. Commenting is always `off` for a new run unless
 `--comment-mode draft` or `--comment-mode post` is explicitly supplied. Drafts
-and posts use the selected bot's server-owned canonical persona; a later human
-reply is handled by Twinkle's existing autonomous Zero/Ciel responder without
-Lumine remaining active.
+and posts use the selected bot's server-owned canonical persona. Outside Build
+threads, a later human reply is handled by Twinkle's existing autonomous
+Zero/Ciel responder without Lumine remaining active.
 
 Management agents also inspect recent public Build candidates during each run.
 `builds review` opens one published app in an isolated temporary Chromium
@@ -297,8 +298,23 @@ subdirectory. A direct Build comment is never server-generated: review the
 runtime (or pull and read an
 open-source app), compose with `--file`, and attach the receipt. The server
 rejects missing or stale review evidence and any app/thread change before
-publication. Manual `--reviewed-version` / `--reviewed-via` evidence remains
-available for genuine code reviews.
+publication. Also pass `--review-context` with a private JSON file containing
+only an `understanding` string: the concrete app behavior and design the agent
+actually learned during that review. The server stamps the canonical Build,
+published version, review method, and review time around that understanding;
+none of it is exposed in the public comment payload. Manual
+`--reviewed-version` / `--reviewed-via` evidence remains available for genuine
+code reviews.
+
+When a human directly replies to that management comment, or to a later
+Zero/Ciel reply descended from it, the same bot may answer from the stored
+historical understanding. That answer uses the commenter's normal AI Energy
+path, including the usual reply-or-Like decision; if their battery is empty,
+the ordinary sponsor placeholder and button are shown. Build mentions and
+replies without this private management provenance remain disabled. A newer
+published Build version does not rewrite history: the bot is told that its
+understanding came from the older reviewed version and must not claim it
+rechecked the app.
 
 Every operation is noninteractive when its required arguments are present.
 `--json` prints exactly one uncolored JSON value and returns a nonzero status

package/lib/admin.js

@@ -17,6 +17,8 @@ import {
 const MAX_EDITORIAL_FILE_BYTES = 256 * 1024;
 const MAX_COMPOSED_TEXT_FILE_BYTES = 64 * 1024;
 const MAX_COMPOSED_TEXT_LENGTH = 10_000;
+const MAX_BUILD_REVIEW_CONTEXT_FILE_BYTES = 64 * 1024;
+const MAX_BUILD_REVIEW_UNDERSTANDING_LENGTH = 12_000;
 const MAX_NOTABLE_NOTE_LENGTH = 2_000;
 const MAX_IDENTITY_INSPECTION_REASON_LENGTH = 500;
 const MAX_ESCALATION_DECISION_NOTE_LENGTH = 2_000;
@@ -54,6 +56,62 @@ function readComposedTextFile(filePath) {
   return normalized;
 }
 
+function readBuildReviewContextFile(filePath) {
+  const normalizedPath = String(filePath || "").trim();
+  if (!normalizedPath) {
+    throw cliValidationError(
+      "Pass the private reviewed understanding with --review-context <context.json>.",
+    );
+  }
+  let contents;
+  try {
+    contents = readFileSync(normalizedPath, "utf8");
+  } catch {
+    throw cliValidationError(`Could not read ${normalizedPath}.`);
+  }
+  if (
+    Buffer.byteLength(contents, "utf8") > MAX_BUILD_REVIEW_CONTEXT_FILE_BYTES
+  ) {
+    throw cliValidationError(
+      "The Build review context file must be under 64KB.",
+    );
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(contents);
+  } catch {
+    throw cliValidationError(`${normalizedPath} is not valid JSON.`);
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw cliValidationError(
+      "The Build review context must be a JSON object with an understanding string.",
+    );
+  }
+  const unexpectedKeys = Object.keys(parsed).filter(
+    (key) => key !== "understanding",
+  );
+  if (unexpectedKeys.length > 0) {
+    throw cliValidationError(
+      "The Build review context JSON may contain only the understanding field; version and provenance are server-owned.",
+    );
+  }
+  const understanding =
+    typeof parsed.understanding === "string"
+      ? parsed.understanding.trim()
+      : "";
+  if (!understanding) {
+    throw cliValidationError(
+      "The Build review context understanding must be a non-empty string.",
+    );
+  }
+  if (understanding.length > MAX_BUILD_REVIEW_UNDERSTANDING_LENGTH) {
+    throw cliValidationError(
+      `The Build review context understanding must be at most ${MAX_BUILD_REVIEW_UNDERSTANDING_LENGTH} characters.`,
+    );
+  }
+  return understanding;
+}
+
 function readEditorialFile(filePath) {
   const normalizedPath = String(filePath || "").trim();
   if (!normalizedPath) {
@@ -243,6 +301,8 @@ export async function adminCommand(options) {
     assertComposedCommentDraftResult({
       result,
       expectedContent: operation.body.content,
+      requiresBuildReviewContext:
+        typeof operation.body.buildReviewUnderstanding === "string",
     });
   }
   if (operation.name === "daily-run.start") {
@@ -363,7 +423,11 @@ export function normalizeAdminBuildCandidatesResult({ result, siteUrl }) {
   };
 }
 
-export function assertComposedCommentDraftResult({ result, expectedContent }) {
+export function assertComposedCommentDraftResult({
+  result,
+  expectedContent,
+  requiresBuildReviewContext = false,
+}) {
   const draft = result?.data?.draft;
   if (
     draft?.decision === "draft" &&
@@ -371,6 +435,25 @@ export function assertComposedCommentDraftResult({ result, expectedContent }) {
     draft?.content === expectedContent &&
     draft?.status === "ready"
   ) {
+    if (
+      requiresBuildReviewContext &&
+      draft?.buildReviewContextStored !== true
+    ) {
+      const error = new Error(
+        "The API did not confirm that it stored the private Build review context. Stop without publishing this draft and deploy the context-aware API first, then retry with a new idempotency key.",
+      );
+      error.code = "LUMINE_ADMIN_BUILD_REVIEW_CONTEXT_UNSUPPORTED";
+      error.data = {
+        ok: false,
+        status: "validation_error",
+        error: {
+          code: error.code,
+          message: error.message,
+          details: null,
+        },
+      };
+      throw error;
+    }
     return;
   }
   const error = new Error(
@@ -1255,6 +1338,9 @@ export function parseAdminOperation(options) {
       const reviewReceipt = options.adminReviewReceipt
         ? parseBuildReviewReceipt(options.adminReviewReceipt)
         : null;
+      const buildReviewUnderstanding = options.adminReviewContext
+        ? readBuildReviewContextFile(options.adminReviewContext)
+        : undefined;
       if (reviewReceipt && (reviewedBuildVersionId || buildReviewMethod)) {
         throw cliValidationError(
           "Pass either --review-receipt or manual --reviewed-version/--reviewed-via evidence, not both.",
@@ -1266,6 +1352,22 @@ export function parseAdminOperation(options) {
       const confirmedBuildReviewMethod = reviewReceipt
         ? "runtime"
         : buildReviewMethod;
+      if (
+        buildReviewUnderstanding &&
+        (!confirmedBuildVersionId || !confirmedBuildReviewMethod)
+      ) {
+        throw cliValidationError(
+          "--review-context requires confirmed Build review evidence.",
+        );
+      }
+      if (
+        (confirmedBuildVersionId || confirmedBuildReviewMethod) &&
+        !buildReviewUnderstanding
+      ) {
+        throw cliValidationError(
+          "Build review evidence requires --review-context <context.json>.",
+        );
+      }
       if (
         reviewReceipt &&
         parsedTarget.type === "build" &&
@@ -1281,9 +1383,13 @@ export function parseAdminOperation(options) {
             "Build comments are management-agent composed only; pass --file <comment.md> after reviewing the project.",
           );
         }
-        if (!confirmedBuildVersionId || !confirmedBuildReviewMethod) {
+        if (
+          !confirmedBuildVersionId ||
+          !confirmedBuildReviewMethod ||
+          !buildReviewUnderstanding
+        ) {
           throw cliValidationError(
-            "After reviewing the project, pass both --reviewed-version <published-artifact-id> and --reviewed-via runtime|code.",
+            "After reviewing the project, pass review evidence and --review-context <context.json>.",
           );
         }
       } else if (
@@ -1313,6 +1419,9 @@ export function parseAdminOperation(options) {
           ...(confirmedBuildReviewMethod
             ? { buildReviewMethod: confirmedBuildReviewMethod }
             : {}),
+          ...(buildReviewUnderstanding
+            ? { buildReviewUnderstanding }
+            : {}),
         },
       );
     }

package/lib/app-mcp/server.js

@@ -18,6 +18,22 @@ function delay(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
+function rethrowAppMcpSessionError(error) {
+  const message = String(error?.message || error);
+  if (
+    Number(error?.status || 0) === 404 &&
+    /MCP session not found/i.test(message) &&
+    !/restart the Lumine app-mcp driver/i.test(message)
+  ) {
+    const guided = new Error(
+      `${message}. Restart the Lumine app-mcp driver and reopen its new appUrl.`,
+    );
+    guided.status = error.status;
+    throw guided;
+  }
+  throw error;
+}
+
 function openApp(url) {
   const command =
     process.platform === "darwin"
@@ -144,7 +160,7 @@ async function callAppTool({
     sessionId,
     name,
     arguments: toolArguments,
-  });
+  }).catch(rethrowAppMcpSessionError);
   const callId = created?.call?.id;
   if (!callId) throw new Error("Twinkle did not create the app tool call.");
   const deadline = Date.now() + CALL_TIMEOUT_MS;
@@ -155,7 +171,7 @@ async function callAppTool({
       buildId,
       sessionId,
       callId,
-    });
+    }).catch(rethrowAppMcpSessionError);
     const call = payload?.call;
     if (call?.status === "completed") return call.result;
     if (call?.status === "failed") {
@@ -169,14 +185,16 @@ async function callAppTool({
     buildId,
     sessionId,
     callId,
-  });
+  }).catch(rethrowAppMcpSessionError);
   if (finalPayload?.call?.status === "completed") {
     return finalPayload.call.result;
   }
   if (finalPayload?.call?.status === "failed") {
     throw new Error(finalPayload.call.errorMessage || "App tool failed.");
   }
-  throw new Error("App tool call timed out. Keep the MCP app tab open.");
+  throw new Error(
+    "App tool call timed out. Reload the appUrl tab, or restart the Lumine app-mcp driver and reopen its new appUrl.",
+  );
 }
 
 async function handleMcpMessage({ line, options, auth, buildId, session, tools }) {

package/lib/commands.js

@@ -2363,6 +2363,7 @@ export function parseArgs(args) {
     adminScaffoldFile: raw.scaffold ? String(raw.scaffold) : "",
     adminTargetFile: raw.targetFile ? String(raw.targetFile) : "",
     adminReviewReceipt: raw.reviewReceipt ? String(raw.reviewReceipt) : "",
+    adminReviewContext: raw.reviewContext ? String(raw.reviewContext) : "",
     adminSeverity: raw.severity ? String(raw.severity) : "",
     adminStatus: raw.status ? String(raw.status) : "",
     adminWaitMs: raw.waitMs ? String(raw.waitMs) : "",
@@ -2766,8 +2767,8 @@ export function printHelp() {
   lumine admin post skip <target> [--type comment|aiStory|dailyReflection] [--reason <text>] [--json]
   lumine admin post skip-batch --target-file <json-or-lines> [--reason <text>] [--checkpoint <file> [--resume]] [--json]
   lumine admin post reward <target> [--type subject|comment|aiStory|dailyReflection] --twinkles 3 [--json]
-  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] [--identity zero|ciel|auto] [--json]
-  lumine admin comment reply comment:<id> [--file <reply.md>] [--reviewed-version <id> --reviewed-via runtime|code] [--identity zero|ciel|auto] [--json]
+  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 edit <comment-id> --file <comment.md> [--json]
   lumine admin brief [--days <1..30>] [--json]
@@ -2864,6 +2865,7 @@ Options:
   --scaffold <file>     Write an editable newspaper editorial scaffold
   --target-file <file>  JSON array or newline list for audited batch skips
   --review-receipt <f>  Confirmed managed Build runtime review receipt
+  --review-context <f>  Private JSON understanding from the reviewed Build
   --severity <level>    Run escalation severity: attention or urgent
   --status <state>      Private escalation or todo lifecycle filter/state
   --wait-ms <ms>        Managed Build runtime observation time (1000-45000)

package/package.json

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

package/sdk/BUILD_SDK_INDEX.md

@@ -1,8 +1,8 @@
 # Build SDK Index
 
-Version: 1.36.0
-Updated: 2026-08-19
-Generated: 2026-08-19T05:45:14.858Z
+Version: 1.37.0
+Updated: 2026-08-25
+Generated: 2026-08-25T02:01:15.207Z
 
 ## Notes
 - This SDK is injected into Build iframes via the Build preview/runtime.
@@ -348,10 +348,10 @@ const result = await Twinkle.ai.chat({ message, history: chatHistory, systemProm
   - Use this instead of asking Twinkle.ai.chat to return JSON.
   - expectedStructure must be a JSON object that describes the exact returned object shape.
   - mode is accepted as an alias for thinkingMode, and mid is accepted as an alias for medium.
-  - Omit model to use the normal Lite/Medium/High routing. model accepts only claude-opus-5 or claude-fable-5, and either explicit model must be paired with thinkingMode: 'high'; unknown model IDs reject instead of silently falling back.
+  - Omit model to use the normal Lite/Medium/High routing. model accepts gpt-5.6-sol, claude-opus-5, or claude-fable-5, and every explicit model must be paired with thinkingMode: 'high'; unknown model IDs reject instead of silently falling back.
   - thinkingMode low uses GPT-5.6 Luna and consumes the viewer's AI Energy from confirmed provider usage; its smaller model is usually cheaper than Medium or High.
   - thinkingMode medium uses Grok 4.6 with medium reasoning and consumes normal AI Energy.
-  - thinkingMode high uses GPT-5.6 Sol with high reasoning and consumes high AI Energy.
+  - thinkingMode high without model uses GPT-5.6 Sol with high reasoning and consumes high AI Energy. Explicit model: 'gpt-5.6-sol' selects Sol with xhigh reasoning at the same High AI Energy tier.
   - claude-opus-5 uses Anthropic adaptive High thinking. claude-fable-5 uses Anthropic xhigh thinking and normally consumes more AI Energy for comparable token use. Both debit confirmed provider usage at the High tier.
   - Pass onStatus and/or onText to stream progress from the same structured generation. onStatus receives high-level phases such as thinking, searching_web, responding, validating, and completed.
   - onText receives accumulated structured-output text plus { done, delta, requestId, status }. Partial output is intentionally incomplete and may include provider formatting; parse only when done is true, when the callback receives the canonical object serialized as JSON, and use the resolved object as the source of truth.

package/sdk/LUMINE_ADMIN.md

@@ -34,8 +34,10 @@ canonical structured data.
   ordering key for the People directory, so the bots now surface there after a
   run; that is the intended consequence of the timestamp being truthful.
 - A later human reply to a delegated Zero/Ciel comment enters the existing
-  server-side autonomous comment-assistant pipeline. Lumine does not need to
-  remain running.
+  server-side autonomous comment-assistant pipeline. For Build threads this is
+  limited to comments carrying the private reviewed-management provenance
+  described below. The human's normal AI Energy and sponsor path applies;
+  Lumine does not need to remain running.
 
 `auto` selects Zero first when no completed rotation exists, then alternates
 after a successfully completed run that performed a mutation. Failed,
@@ -887,8 +889,11 @@ captures a screenshot and bounded console evidence, then fetches the identity
 again. It writes `review.json` in a unique per-review subdirectory only when
 the browser completed, the screenshot exists, and the artifact did not change
 mid-review. Attach the returned `receiptPath` with
-`comment draft ... --review-receipt review.json`; this binds the draft to the
-exact reviewed artifact without copying a version number by hand.
+`comment draft ... --review-receipt review.json`, and pass a separate private
+`--review-context context.json` containing only the concrete `understanding`
+learned during that review. The receipt binds the draft to the exact reviewed
+artifact without copying a version number by hand; the server owns the Build,
+version, method, and review-time fields around that understanding.
 
 During every management run, scan recent Build candidates back through the
 run's review window alongside Subjects and the recommendation queue. An app
@@ -2315,10 +2320,17 @@ to the exact published artifact you saw:
 
 ```bash
 lumine admin comment draft build:884 --file comment.md \
-  --reviewed-version 4512 --reviewed-via runtime --json
+  --reviewed-version 4512 --reviewed-via runtime \
+  --review-context context.json --json
 lumine admin comment post --draft-id 77 --json
 ```
 
+```json
+{
+  "understanding": "The start screen pairs a green zombie with a sci-fi soldier, and the first interaction teaches the player to select a zombie before firing the railgun."
+}
+```
+
 Use `--reviewed-via code` only when you actually pulled and read the project;
 `runtime` means you opened and tried the published app. Replies to human
 comments inside a Build use `comment:<id>` plus the same review flags. The API
@@ -2327,9 +2339,20 @@ published version, a private/noncanonical Build, or any Build/comment-context
 change between draft and publication. A changed version means review the new
 project state and compose again. The flags are an auditable statement of what
 the management agent did, not permission to infer experience from metadata.
-Autonomous mention/reply generation and sponsored AI replies are disabled in
-Build threads. The generic `comment edit` shortcut is also disabled there;
-review the current version and post a version-bound correction reply instead.
+The review-context JSON is private server-owned conversation provenance; it is
+not included in the public comment, draft response, socket payload, or audit
+metadata. A direct human reply to the resulting Zero/Ciel management comment,
+or to a later reply by that same bot descended from it, may enter the ordinary
+comment-assistant pipeline using this stored historical understanding. It uses
+the human commenter's normal AI Energy and reply-or-Like gate. If that user has
+no remaining AI Energy, the normal sponsor placeholder/button is shown and a
+sponsor pays from their own battery. Mentions elsewhere in a Build, replies to
+unlinked or legacy bot comments, replies to humans, and the other bot remain
+ineligible. If the published version has changed, the responder is told the
+stored understanding belongs to the reviewed older version and must say it has
+not checked behavior that could have changed. The generic `comment edit`
+shortcut is also disabled there; review the current version and post a
+version-bound correction reply instead.
 
 **Offer a Lumine prompt when the moment invites it (Mikey's direction,
 2026-08-10).** Zero and Ciel may include one concrete, copy-pasteable Lumine
@@ -2362,6 +2385,11 @@ silently ignores `content` and generates with the server's model instead. The
 CLI therefore requires the ready draft response to echo the exact submitted
 text with `reason: "operator-composed"`; otherwise it stops with
 `LUMINE_ADMIN_COMPOSED_COMMENT_UNSUPPORTED`. Never publish that rejected draft.
+For Build drafts it additionally requires
+`buildReviewContextStored: true`; an older API that ignores the private context
+fails closed with `LUMINE_ADMIN_BUILD_REVIEW_CONTEXT_UNSUPPORTED`. Deploy the
+context-aware API, then retry with a new idempotency key rather than publishing
+the unconfirmed draft.
 Placement stays on the requested target: compose replies via `comment:<id>`
 targets (the generated path's model-chosen
 `replyTargetCommentId` does not apply). Everything below about targets,
@@ -2379,14 +2407,17 @@ A draft targets one of:
 
 A reply's container resolves canonically from the target comment: its subject,
 Build, or AI Story / Daily Reflection root. Comments under any other root are
-rejected with `CLI_ADMIN_UNSUPPORTED_REPLY_ROOT`. Build replies require the
-same exact-version review evidence as top-level Build comments. Replies to
+rejected with `CLI_ADMIN_UNSUPPORTED_REPLY_ROOT`. Build replies authored by the
+management agent require the same exact-version review evidence and private
+review context as top-level Build comments. Replies to
 Zero/Ciel comments and to notification comments are rejected with
 `CLI_ADMIN_INVALID_REPLY_TARGET` — the bots never thread with themselves or
-each other, and a human's later reply to a delegated comment still enters the
-existing autonomous comment-assistant pipeline. Published replies carry the
-ordinary thread linkage (thread root and reply-to), and notification fan-out
-uses the normal canonical path.
+each other through the delegated CLI. A human's later direct reply to a
+context-backed Build management comment may enter the energy-gated autonomous
+pipeline described above; ordinary human replies elsewhere follow the existing
+comment-assistant rules. Published replies carry the ordinary thread linkage
+(thread root and reply-to), and notification fan-out uses the normal canonical
+path.
 
 ```ts
 type CommentDraft = Success<{
@@ -2402,6 +2433,7 @@ type CommentDraft = Success<{
     commentMode: "draft" | "post";
     personaRevision: string; // SHA-256; raw prompt is never returned
     contextRevision: string; // SHA-256 of canonical container/comments/target
+    buildReviewContextStored: boolean; // true before a Build draft may publish
     decision: "draft" | "skip";
     reason: string | null;
     content: string | null;