@stage5/lumine 0.2.50 → 0.2.52

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/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/lib/constants.js

@@ -115,6 +115,8 @@ export const BUNDLED_SDK_REFERENCE_URL = new URL(
   import.meta.url,
 );
 export const PACKAGE_METADATA_URL = new URL("../package.json", import.meta.url);
+export const LUMINE_WORLD_UPDATE_GUIDANCE = `- For Twinkle.world realtime presence, keep render/input loops local. Queue an update only when relevant state changes, replace any queued snapshot with the newest one, and flush on a fixed 5-15 updates-per-second schedule with at most one updatePresence request in flight. Never call or await updatePresence every animation frame, resend unchanged snapshots, overlap requests, or build a backlog.
+- Send Twinkle.world actions only when the discrete action happens; do not poll or automatically retry them. On WORLD_EVENT_RATE_LIMITED or another recoverable non-session-ended error, drop that attempted presence/action update without an immediate retry and keep the session. Reconnect with backoff only after session.ended or Twinkle.world.isSessionEndedError(error).`;
 export const SDK_REFERENCE_FALLBACK = `${LUMINE_SDK_REFERENCE_MARKER}
 # Twinkle Build SDK Reference
 
@@ -131,6 +133,7 @@ Use these current source-of-truth rules:
 - Use Twinkle.aiStories.list/search/get for existing AI Story passage text, story media, and questions.
 - Use Twinkle.ai.chat with history entries shaped as { role, content }, not { text }. Live web search is enabled by default; pass webSearch: false to disable it for the app.
 - Use Twinkle.preview for canvas, WebGL, Three.js, fullscreen, and game layout.
+${LUMINE_WORLD_UPDATE_GUIDANCE}
 - Prefer existing documented Twinkle.* methods over guessing names from old code.
 `;
 export const LUMINE_THREE_VENDOR_GUIDANCE = `- For Three.js, use the first-party core module: import * as THREE from '${BUILD_VENDOR_THREE_MODULE_IMPORT}';
@@ -285,6 +288,7 @@ lumine save --summary "Describe the change"
 ${LUMINE_THREE_VENDOR_GUIDANCE}
 - Do not invent or guess Twinkle.* SDK method names. Use ${SDK_REFERENCE_FILE} as the local SDK reference and prefer Twinkle.capabilities checks for gated features.
 - Match storage to update frequency. Twinkle.privateDb and Twinkle.sharedDb are for LOW-frequency durable state only — things that change on a user action (settings, inventory checkpoints, completed quests, saved progress; comments, votes, room settings, submitted records). NEVER write high-frequency or per-frame/per-tick state to them (camera or cursor position, animation state, live movement, presence, autosave every frame/tick). Keep live state in client memory, broadcast realtime/presence via Twinkle.world, and for durable per-user state flush an occasional snapshot on an interval or on exit (never per frame) — e.g. the viewer/user DB or a single latest-snapshot key. The server rate-limits these writes per key and returns 429 on excess; never retry-loop a 429.
+${LUMINE_WORLD_UPDATE_GUIDANCE}
 
 ## Local Testing (Playwright / browser probes)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage5/lumine",
-  "version": "0.2.50",
+  "version": "0.2.52",
   "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.2
+Updated: 2026-08-26
+Generated: 2026-08-26T15:17:11.027Z
 
 ## Notes
 - This SDK is injected into Build iframes via the Build preview/runtime.
@@ -341,25 +341,26 @@ renderBattery(policy?.energyPercent, policy?.energySegmentsRemaining);
   - Use this for in-app AI replies instead of creating or fetching app-local endpoints such as /api/chat.
   - Example: const chatHistory = conversation.slice(-12).map((entry) => ({ role: entry.role === 'assistant' ? 'assistant' : 'user', content: entry.text }));
 const result = await Twinkle.ai.chat({ message, history: chatHistory, systemPrompt: 'You are a cheerful pirate helper who answers in one sentence.', onText: (text, meta) => renderReply(text), onStatus: (status) => setThinking(status === 'thinking') });
-- async generateObject({ prompt, expectedStructure, thinkingMode, mode, model, instructions, systemPrompt, webSearch, requestId, onText, onStatus } = {}) | scopes: none
+- async generateObject({ prompt, expectedStructure, thinkingMode, mode, model, instructions, systemPrompt, webSearch, requestId, onText, onStatus, onReasoning } = {}) | scopes: none
   - Returns: { object, result, model, provider, thinkingMode, requestedThinkingMode, requestedModel, webSearch, aiUsagePolicy }
   - Generate a validated structured JSON object for app decisions, routing, grading, and game-state logic, with optional live output/status callbacks and web search.
   - Signed-in viewers only.
   - 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.
+  - Pass onStatus, onReasoning, 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.
+  - onReasoning receives accumulated provider-supplied, app-visible reasoning summaries plus { done, delta, requestId, status }. A provider retry may replace the accumulated summary; treat each callback's first argument as the current source of truth. This callback never exposes hidden/private model chain-of-thought.
   - 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.
-  - Streaming exposes app-visible structured output and high-level phases, not private model chain-of-thought. Put a user-facing field such as producerNotes in expectedStructure when the app should display model-authored commentary from the same generation.
+  - Put a user-facing field such as producerNotes in expectedStructure when commentary must be part of the validated final object rather than transient reasoning progress.
   - When AI Energy is empty, every automatic or named model choice rejects before new provider work; there is no free fallback mode.
   - Live web search is enabled by default in Medium and High modes. Pass webSearch: false to disable it for the app. Low/Lite Mode remains tool-free; explicitly forcing webSearch: true in Low Mode returns an error.
-  - The server validates the final shape; automatic OpenAI/xAI routes can retry malformed output, while explicit Anthropic routes use native JSON Schema output. App code should still validate business-specific enum values.
-  - Example: const { object } = await Twinkle.ai.generateObject({ thinkingMode: 'high', model: 'claude-opus-5', prompt: 'Plan the next section from: ' + currentState, expectedStructure: { producerNotes: 'string', action: 'string', confidence: 0 }, onStatus: (phase) => showPhase(phase), onText: (partialJson, meta) => showStructuredProgress(partialJson, meta) });
+  - The server validates the final shape; automatic OpenAI/xAI routes can retry malformed output, while explicit Anthropic routes use native JSON Schema output and retry one malformed or shape-invalid result. App code should still validate business-specific enum values.
+  - Example: const { object } = await Twinkle.ai.generateObject({ thinkingMode: 'high', model: 'claude-opus-5', prompt: 'Plan the next section from: ' + currentState, expectedStructure: { producerNotes: 'string', action: 'string', confidence: 0 }, onStatus: (phase) => showPhase(phase), onReasoning: (summary, meta) => showReasoningProgress(summary, meta), onText: (partialJson, meta) => showStructuredProgress(partialJson, meta) });
 - onChatStatus(listener) | scopes: none
   - Returns: unsubscribe function
   - Listen to shared runtime AI chat stream events.
@@ -742,7 +743,8 @@ const result = await Twinkle.characters.chat({ character: 'zero', thinkingMode:
   - Signed-in player identity comes from the canonical Twinkle user record; player.profilePicUrl is only used for guests and is returned only when it is a valid absolute HTTPS URL.
   - Subscribe to session.ended and catch updatePresence/send errors. Stop using stale handles and reconnect only when Twinkle.world.isSessionEndedError(error) is true; for other Twinkle.world.isRecoverableSessionError(error) cases, drop the transient presence/action and keep the handle.
   - Use updatePresence for live avatar snapshots and send for lightweight actions such as emotes, interactions, and chat bubbles.
-  - Throttle movement updates in app code, usually 5-15 updates per second. Do not call updatePresence from every animation frame.
+  - Treat the render/input loop as local-only. Queue presence only after relevant fields change, replace any queued snapshot with the newest one, and flush on a fixed 5-15 updates-per-second schedule with at most one updatePresence request in flight. Never call or await updatePresence every animation frame, resend unchanged snapshots, overlap requests, or build a backlog.
+  - Send discrete actions only when they happen; do not poll or automatically retry them. The parent limits updatePresence and send together to protect the website connection. WORLD_EVENT_RATE_LIMITED is recoverable: drop that attempted update without an immediate retry and keep the current session.
   - Rooms are addressed by worldKey, roomKey, and instanceId so the contract can later move to sharded or dedicated game backends.
   - Example: const world = await Twinkle.world.join({ roomKey: 'town-square', presence: { x: 0, y: 0, z: 0, facing: 'south' }, player: { name: avatarName } });
 world.subscribe((event) => updateRemotePlayers(event.players));
@@ -750,8 +752,8 @@ world.updatePresence({ x, y, z, facing });
 - isRecoverableSessionError(error) | scopes: none
   - Returns: boolean
   - Return true when a world request error is expected to be handled by app code instead of crashing.
-  - Recoverable session errors include ended, missing, socket-disconnected, socket-not-ready, room-missing, preview-updating, and timed-out world session requests.
-  - Only session-ended errors prove that the current handle should be discarded. Timed-out or preview-updating presence requests can be dropped without reconnecting.
+  - Recoverable session errors include ended, missing, socket-disconnected, socket-not-ready, room-missing, rate-limited, preview-updating, and timed-out world session requests.
+  - Only session-ended errors prove that the current handle should be discarded. WORLD_EVENT_RATE_LIMITED, timed-out, or preview-updating presence/action requests must be dropped without reconnecting and without an immediate retry.
   - For durable game state, write through sharedDb/privateDb instead of relying on world presence — but LOW-frequency only (on a user action or an occasional snapshot, never per frame/tick).
   - Example: try {
   await world.updatePresence({ x, y, z, facing });
@@ -1028,59 +1030,104 @@ Keywords: multiplayer, mmo, town, presence, avatars, movement, three.js, realtim
 
 ```js
 let world = null;
+let worldConnection = null;
 let reconnectTimer = 0;
+let reconnectDelayMs = 1000;
+let latestPresence = { x: 0, y: 0, z: 0, facing: 'south', animation: 'idle' };
+let latestPresenceKey = JSON.stringify(latestPresence);
+let queuedPresence = null;
+let presenceInFlight = false;
 
 async function connectWorld() {
   if (world) return world;
-  world = await Twinkle.world.join({
-    worldKey: 'town',
-    roomKey: 'square',
-    presence: { x: 0, y: 0, z: 0, facing: 'south', animation: 'idle' },
+  if (worldConnection) return worldConnection;
+  const presenceAtJoin = latestPresence;
+  const presenceKeyAtJoin = latestPresenceKey;
+  worldConnection = Twinkle.world.join({
+    worldKey: 'town', roomKey: 'square', presence: presenceAtJoin,
     player: { name: avatarName }
   });
+  try {
+    const session = await worldConnection;
+    world = session;
+    reconnectDelayMs = 1000;
+    session.subscribe((event) => {
+      renderPlayers(event.players);
+      if (event.type === 'session.ended') handleWorldDrop(session);
+      if (event.type === 'action.received' && event.action?.type === 'emote') {
+        showEmote(event.sessionId, event.action.data.emote);
+      }
+    });
+    if (latestPresenceKey !== presenceKeyAtJoin) queuedPresence = latestPresence;
+    return session;
+  } finally {
+    worldConnection = null;
+  }
+}
 
-  world.subscribe((event) => {
-    renderPlayers(event.players);
-    if (event.type === 'session.ended') {
-      handleWorldDrop();
-    }
-    if (event.type === 'action.received' && event.action?.type === 'emote') {
-      showEmote(event.sessionId, event.action.data.emote);
-    }
-  });
-  return world;
+function handleWorldConnectError(error) {
+  if (Twinkle.world.isRecoverableSessionError(error)) {
+    scheduleReconnect();
+  } else {
+    console.error('World connection failed', error);
+  }
+}
+
+function scheduleReconnect() {
+  if (reconnectTimer || world || worldConnection) return;
+  const delay = reconnectDelayMs;
+  reconnectDelayMs = Math.min(30000, reconnectDelayMs * 2);
+  reconnectTimer = setTimeout(() => {
+    reconnectTimer = 0;
+    connectWorld().catch(handleWorldConnectError);
+  }, delay);
 }
 
-function handleWorldDrop() {
+function handleWorldDrop(session = world) {
+  if (session && world && world !== session) return;
   world = null;
-  if (!reconnectTimer) {
-    reconnectTimer = setTimeout(() => {
-      reconnectTimer = 0;
-      connectWorld().catch(handleWorldDrop);
-    }, 1000);
-  }
+  queuedPresence = null;
+  scheduleReconnect();
+}
+
+function queuePresence(next) {
+  const key = JSON.stringify(next);
+  if (key === latestPresenceKey) return;
+  latestPresenceKey = key;
+  latestPresence = next;
+  if (world) queuedPresence = next; // Coalesce to the newest unsent snapshot.
 }
 
-async function syncPresence() {
+async function flushPresence() {
+  if (presenceInFlight || !queuedPresence || !world) return;
+  const session = world;
+  const next = queuedPresence;
+  queuedPresence = null;
+  presenceInFlight = true;
   try {
-    const session = await connectWorld();
-    // Throttle this in the game loop, for example 5-15 times per second.
-    await session.updatePresence({ x: player.x, y: player.y, z: player.z, facing });
+    await session.updatePresence(next);
   } catch (error) {
     if (Twinkle.world.isSessionEndedError(error)) {
-      handleWorldDrop();
-      return;
+      handleWorldDrop(session);
+    } else if (!Twinkle.world.isRecoverableSessionError(error)) {
+      console.error('World update failed', error);
     }
-    if (Twinkle.world.isRecoverableSessionError(error)) {
-      // Drop this transient presence update and keep the current handle.
-      return;
-    }
-    throw error;
+    // Recoverable errors drop this transient snapshot without an immediate retry.
+  } finally {
+    presenceInFlight = false;
   }
 }
 
-await connectWorld();
-await syncPresence();
+// The render/input loop only queues changed local state.
+function onPlayerStateChanged() {
+  queuePresence({
+    x: player.x, y: player.y, z: player.z,
+    facing, animation: player.animation
+  });
+}
+
+connectWorld().catch(handleWorldConnectError);
+setInterval(() => { void flushPresence(); }, 100); // Fixed 10 Hz cap.
 ```
 
 ### Play chess against the computer

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;