@stage5/lumine 0.2.43 → 0.2.46

package/README.md

@@ -113,6 +113,21 @@ Reference folders are marked `readOnly` in `.twinkle/lumine-project.json`.
 Running `lumine save` from a reference folder is blocked; fork the source Build
 first if you want an editable workspace.
 
+## Using a published app over MCP
+
+`lumine app-mcp <published-app-url-or-id>` turns an opted-in published Build
+app into a standard stdio MCP server. Lumine pins the current published
+artifact, reads its `/app-tools.json` manifest, and opens a dedicated signed-in
+app tab. Tool calls run serially in that visible iframe through handlers the app
+registered with `Twinkle.appTools.register({ handlers })`, so the agent and
+viewer operate the same live UI and state. Keep that tab open while the MCP
+client is connected. Pass `--no-open` only when you will open the URL printed on
+stderr yourself.
+
+Discovery is static and fail-closed: runtime code cannot add tools that were
+not declared in the pinned manifest, and a session refuses to connect if any
+declared handler is missing.
+
 ## Inspecting Build SDK data
 
 `lumine sdk call <namespace.method> '<jsonArgs>'` calls a build's data SDK
@@ -217,6 +232,12 @@ lumine admin identity list --json
 lumine admin identity inspect Jay1216 \
   --reason "Confirm account family before a quota-bucket change" --json
 lumine admin daily-run start --identity auto --comment-mode off --json
+lumine admin todo list --json
+lumine admin todo add --kind experiment --status in_progress \
+  --title "Validate Zero/Ciel cost optimization" \
+  --note "Complete only after old-vs-new response-quality parity." --json
+lumine admin todo update 12 --status blocked \
+  --note "Waiting for a complete cost bucket and parity replay." --json
 lumine admin recommendations list --all --checkpoint recommendations.json --json
 lumine admin recommendations list --after 2026-08-14T00:00:00Z --all --json
 lumine admin recommendations list --include-legacy --all --json
@@ -295,14 +316,19 @@ cursors are bound to the original date and effort filters.
 `news claim` can write both the canonical leased digest and an editable
 editorial scaffold. `news validate` is local and checks every citation and
 quote before submission; `news submit --claim` reads the lease identity from
-the claim file. `daily-run report` summarizes confirmed mutations, completed
-queue coverage, explicitly recorded escalations, and the run brief before the
-run is completed.
+the claim file. Every `daily-run start` response includes writer-confirmed
+unfinished private todos, with once-per-run surfacing telemetry, so an agent
+can resume earlier work without relying on conversation memory. Record progress
+with `todo update`; completing a run does not complete its todos. Experiments
+must meet their stated acceptance criteria—lower AI cost with weaker user
+responses is not a successful optimization. `daily-run report` summarizes
+confirmed mutations, completed queue coverage, explicitly recorded escalations,
+unfinished todos, and the run brief before the run is completed.
 
 Identity inspection, escalation dispositions, AI-bucket maintenance, and
-approved Notable User additions are private operator bookkeeping and do not
-require a delegated daily run. Identity inspection always requires an audited
-`--reason`; raw email/DOB evidence additionally requires
+approved Notable User additions and todos are private operator bookkeeping and
+do not require a delegated daily run. Identity inspection always requires an
+audited `--reason`; raw email/DOB evidence additionally requires
 `--include-private-evidence`. Routine briefs omit raw email identities.
 
 The complete run lifecycle, command contracts, nullable fields, Karma approval

package/lib/admin.js

@@ -23,6 +23,8 @@ const MAX_COMPOSED_TEXT_LENGTH = 10_000;
 const MAX_NOTABLE_NOTE_LENGTH = 2_000;
 const MAX_IDENTITY_INSPECTION_REASON_LENGTH = 500;
 const MAX_ESCALATION_DECISION_NOTE_LENGTH = 2_000;
+const MAX_TODO_TITLE_LENGTH = 200;
+const MAX_TODO_NOTE_LENGTH = 4_000;
 
 // Operator-composed persona text (plain UTF-8, not JSON). The agent writes
 // the content in the bot's persona itself; the server never invokes
@@ -246,6 +248,9 @@ export async function adminCommand(options) {
       expectedContent: operation.body.content,
     });
   }
+  if (operation.name === "daily-run.start") {
+    assertAdminTodoHandoffResult(result);
+  }
   if (operation.name === "news.claim") {
     const artifacts = writeNewsClaimArtifacts({
       result,
@@ -506,7 +511,9 @@ function adminOperationRequiresRun(operation) {
       "escalation.list",
       "escalation.set",
       "notable.add",
-    ].includes(operation.name) && !operation.name.startsWith("ai-bucket.")
+    ].includes(operation.name) &&
+    !operation.name.startsWith("ai-bucket.") &&
+    !operation.name.startsWith("todo.")
   );
 }
 
@@ -621,6 +628,69 @@ export function parseAdminOperation(options) {
     }
   }
 
+  if (namespace === "todo" || namespace === "todos") {
+    if (!action || action === "list") {
+      return readOperation(
+        "todo.list",
+        withQuery("/cli/admin/todos", {
+          status: parseTodoListStatus(options.adminStatus || "pending"),
+          limit: options.limit,
+        }),
+      );
+    }
+    if (action === "add" || action === "create") {
+      const title = String(options.title || "").trim();
+      const details = String(options.note || "").trim();
+      if (!title || !details) {
+        throw cliValidationError(
+          "Usage: lumine admin todo add --title <title> --note <handoff and acceptance criteria> [--kind task|experiment] [--status open|in_progress|blocked].",
+        );
+      }
+      if (title.length > MAX_TODO_TITLE_LENGTH) {
+        throw cliValidationError(
+          `A todo title must be at most ${MAX_TODO_TITLE_LENGTH} characters.`,
+        );
+      }
+      if (details.length > MAX_TODO_NOTE_LENGTH) {
+        throw cliValidationError(
+          `Todo details must be at most ${MAX_TODO_NOTE_LENGTH} characters.`,
+        );
+      }
+      return writeOperation("todo.add", "POST", "/cli/admin/todos", {
+        kind: parseTodoKind(options.adminKind || "task"),
+        title,
+        details,
+        status: parseTodoInitialStatus(options.adminStatus || "open"),
+      });
+    }
+    if (action === "update") {
+      const todoId = parseRequiredInteger(target, "Todo ID", 1);
+      const note = String(options.note || "").trim();
+      if (!note) {
+        throw cliValidationError(
+          "Record concrete progress, evidence, or the reason for the state change with --note <text>.",
+        );
+      }
+      if (note.length > MAX_TODO_NOTE_LENGTH) {
+        throw cliValidationError(
+          `A todo progress note must be at most ${MAX_TODO_NOTE_LENGTH} characters.`,
+        );
+      }
+      return writeOperation(
+        "todo.update",
+        "PUT",
+        `/cli/admin/todos/${todoId}`,
+        {
+          status: parseTodoStatus(options.adminStatus),
+          note,
+        },
+      );
+    }
+    throw cliValidationError(
+      "Usage: lumine admin todo list [--status pending|open|in_progress|blocked|completed|cancelled|all] | todo add --title <title> --note <details> | todo update <id> --status <status> --note <progress>.",
+    );
+  }
+
   if (namespace === "daily-run") {
     if (action === "start") {
       return writeOperation(
@@ -1240,7 +1310,7 @@ export function parseAdminOperation(options) {
   }
 
   throw cliValidationError(
-    "Usage: lumine admin identity|daily-run|escalation|recommendations|builds|post|subjects|subject|featured|comment|announcement|chat|news|audit|brief|bot-output|notable ...",
+    "Usage: lumine admin identity|daily-run|escalation|todo|recommendations|builds|post|subjects|subject|featured|comment|announcement|chat|news|audit|brief|bot-output|notable ...",
   );
 }
 
@@ -1573,6 +1643,28 @@ export function formatAdminJsonError(error) {
   };
 }
 
+export function assertAdminTodoHandoffResult(result) {
+  const runId = Number(result?.data?.run?.id || 0);
+  const handoff = result?.data?.carryoverTodos;
+  if (
+    !runId ||
+    !handoff ||
+    !Array.isArray(handoff.items) ||
+    Number(handoff.count) !== handoff.items.length ||
+    Number(handoff.surfacedForRunId) !== runId ||
+    !Number.isSafeInteger(Number(handoff.newlySurfacedCount)) ||
+    Number(handoff.newlySurfacedCount) < 0 ||
+    Number(handoff.newlySurfacedCount) > handoff.items.length
+  ) {
+    const error = cliValidationError(
+      "The API did not confirm the canonical carry-over todo handoff. Deploy the todo migration/API before using this Lumine CLI for community management.",
+    );
+    error.code = "LUMINE_ADMIN_TODO_HANDOFF_UNSUPPORTED";
+    throw error;
+  }
+  return handoff;
+}
+
 function readOperation(name, path, extra = {}) {
   return {
     name,
@@ -1643,6 +1735,56 @@ function parseEscalationListStatus(value) {
   return status;
 }
 
+function parseTodoKind(value) {
+  const kind = String(value || "task")
+    .trim()
+    .toLowerCase();
+  if (!["task", "experiment"].includes(kind)) {
+    throw cliValidationError("--kind must be task or experiment.");
+  }
+  return kind;
+}
+
+function parseTodoInitialStatus(value) {
+  const status = String(value || "open")
+    .trim()
+    .toLowerCase();
+  if (!["open", "in_progress", "blocked"].includes(status)) {
+    throw cliValidationError(
+      "A new todo --status must be open, in_progress, or blocked.",
+    );
+  }
+  return status;
+}
+
+function parseTodoStatus(value) {
+  const status = String(value || "")
+    .trim()
+    .toLowerCase();
+  if (
+    ![
+      "open",
+      "in_progress",
+      "blocked",
+      "completed",
+      "cancelled",
+    ].includes(status)
+  ) {
+    throw cliValidationError(
+      "--status must be open, in_progress, blocked, completed, or cancelled.",
+    );
+  }
+  return status;
+}
+
+function parseTodoListStatus(value) {
+  const status = String(value || "pending")
+    .trim()
+    .toLowerCase();
+  if (status === "pending" || status === "all") return status;
+  return parseTodoStatus(status);
+}
+
 function parseOrderedIds(value) {
   const ids = String(value || "")
     .split(",")
@@ -1776,7 +1918,7 @@ function printAdminResult({ operation, result }) {
   if (data.report) {
     const report = data.report;
     console.log(
-      `Run #${report.run.id}: ${report.mutations.successfulMutationCount} successful mutation(s), ${report.queueCoverage.length} queue coverage record(s), ${report.escalations.length} escalation(s).`,
+      `Run #${report.run.id}: ${report.mutations.successfulMutationCount} successful mutation(s), ${report.queueCoverage.length} queue coverage record(s), ${report.escalations.length} escalation(s), ${report.carryoverTodos?.count || 0} unfinished todo(s).`,
     );
     for (const coverage of report.queueCoverage) {
       console.log(
@@ -1791,6 +1933,7 @@ function printAdminResult({ operation, result }) {
         `  ${String(escalation.severity || "attention").toUpperCase()} ${target} — ${escalation.summary}`,
       );
     }
+    printTodoItems(report.carryoverTodos?.items || [], "Unfinished work");
     const surfaces = report.brief?.engagementPulse?.surfaces;
     if (surfaces && typeof surfaces === "object") {
       const deltas = Object.entries(surfaces)
@@ -1861,6 +2004,19 @@ function printAdminResult({ operation, result }) {
     );
     return;
   }
+  if (Array.isArray(data.todos)) {
+    printTodoItems(data.todos, "Private carry-over work");
+    if (data.truncated) {
+      console.log(
+        "More matching todos exist than the requested limit; raise --limit or narrow --status.",
+      );
+    }
+    return;
+  }
+  if (data.todo) {
+    printTodoItems([data.todo], "Canonical todo");
+    return;
+  }
   if (data.bucket && Array.isArray(data.memberUserIds)) {
     const added = Array.isArray(data.accounts)
       ? `; added ${data.accounts.length} explicit account(s)`
@@ -1883,6 +2039,9 @@ function printAdminResult({ operation, result }) {
     console.log(
       `Run #${data.run.id}: ${data.run.status}; identity ${data.run.identity.key}; comments ${data.run.commentMode}.`,
     );
+    if (data.carryoverTodos) {
+      printTodoItems(data.carryoverTodos.items || [], "Carry-over work");
+    }
     return;
   }
   if (Array.isArray(data.identities)) {
@@ -2070,6 +2229,19 @@ function printAdminResult({ operation, result }) {
   );
 }
 
+function printTodoItems(items, heading) {
+  console.log(`${heading}: ${items.length} item(s).`);
+  for (const todo of items) {
+    console.log(
+      `  #${todo.id} ${String(todo.status || "open").toUpperCase()} ${todo.kind || "task"} — ${todo.title || "(untitled)"}`,
+    );
+    if (todo.details) console.log(`    ${todo.details}`);
+    if (todo.lastProgressNote) {
+      console.log(`    Latest progress: ${todo.lastProgressNote}`);
+    }
+  }
+}
+
 function printPagination(pagination) {
   if (!pagination) return;
   console.log(

package/lib/api.js

@@ -83,6 +83,63 @@ export async function loadBuildFiles({ options, auth, buildId, includeContent })
   });
 }
 
+export async function createAppMcpSession({ options, auth, buildId }) {
+  return await requestJson({
+    method: "POST",
+    url: `${options.apiUrl}/cli/build/${buildId}/app-mcp/sessions`,
+    authToken: auth.token,
+    body: {},
+    timeoutMs: options.timeoutMs,
+  });
+}
+
+export async function createAppMcpCall({
+  options,
+  auth,
+  buildId,
+  sessionId,
+  name,
+  arguments: toolArguments,
+}) {
+  return await requestJson({
+    method: "POST",
+    url: `${options.apiUrl}/cli/build/${buildId}/app-mcp/sessions/${sessionId}/calls`,
+    authToken: auth.token,
+    body: { name, arguments: toolArguments ?? {} },
+    timeoutMs: options.timeoutMs,
+  });
+}
+
+export async function loadAppMcpCall({
+  options,
+  auth,
+  buildId,
+  sessionId,
+  callId,
+}) {
+  return await requestJson({
+    method: "POST",
+    url: `${options.apiUrl}/cli/build/${buildId}/app-mcp/sessions/${sessionId}/calls/${callId}/status`,
+    authToken: auth.token,
+    body: {},
+    timeoutMs: options.timeoutMs,
+  });
+}
+
+export async function closeAppMcpSession({
+  options,
+  auth,
+  buildId,
+  sessionId,
+}) {
+  return await requestJson({
+    method: "DELETE",
+    url: `${options.apiUrl}/cli/build/${buildId}/app-mcp/sessions/${sessionId}`,
+    authToken: auth.token,
+    timeoutMs: options.timeoutMs,
+  });
+}
+
 export async function loadExternalAgentRuntime({
   options,
   auth,
@@ -412,9 +469,6 @@ export async function replaceMainWithContribution({
 }
 
 export async function publishBuild({ options, buildId, auth }) {
-  if (auth.releaseStatus?.state === "up_to_date") {
-    return { skipped: true };
-  }
   try {
     const result = await requestJson({
       method: "POST",

package/lib/app-mcp/server.js

@@ -0,0 +1,255 @@
+import { spawn } from "node:child_process";
+import readline from "node:readline";
+
+import {
+  closeAppMcpSession,
+  createAppMcpCall,
+  createAppMcpSession,
+  loadAppMcpCall,
+} from "../api.js";
+import { assertAuthScope, resolveAuth } from "../auth.js";
+import { resolveRequiredBuildId } from "../util.js";
+
+const MCP_PROTOCOL_VERSION = "2025-06-18";
+const CALL_POLL_MS = 250;
+const CALL_TIMEOUT_MS = 5 * 60 * 1000;
+
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function openApp(url) {
+  const command =
+    process.platform === "darwin"
+      ? ["open", [url]]
+      : process.platform === "win32"
+        ? ["cmd", ["/c", "start", "", url]]
+        : ["xdg-open", [url]];
+  const child = spawn(command[0], command[1], {
+    detached: true,
+    stdio: "ignore",
+  });
+  child.unref();
+  child.on("error", () => {
+    process.stderr.write(
+      `lumine app-mcp: open this signed-in app tab: ${url}\n`,
+    );
+  });
+}
+
+export async function appMcpCommand(options) {
+  const buildId = resolveRequiredBuildId(options.target || options.buildIdFlag);
+  if (!buildId) {
+    throw new Error("Usage: lumine app-mcp <published-app-url-or-id>");
+  }
+  const auth = await resolveAuth(options);
+  await assertAuthScope({ options, auth, scope: "build:read" });
+  await assertAuthScope({ options, auth, scope: "build:write" });
+  const created = await createAppMcpSession({ options, auth, buildId });
+  const session = created?.session;
+  if (!session?.id || !session?.manifest?.tools?.length) {
+    if (session?.id) {
+      await closeAppMcpSession({
+        options,
+        auth,
+        buildId,
+        sessionId: session.id,
+      }).catch(() => {});
+    }
+    throw new Error("Twinkle did not return an app MCP session.");
+  }
+  try {
+    if (options.openBrowser !== false) {
+      openApp(session.appUrl);
+    } else {
+      process.stderr.write(
+        `lumine app-mcp: open this signed-in app tab: ${session.appUrl}\n`,
+      );
+    }
+    process.stderr.write(
+      `lumine app-mcp: ${session.buildTitle} is pinned to artifact ${session.artifactVersionId}. ` +
+        `Keep the opened Twinkle tab running.\n`,
+    );
+
+    const tools = session.manifest.tools.map((tool) => ({
+      name: tool.name,
+      description: tool.description || "",
+      inputSchema: tool.inputSchema || {
+        type: "object",
+        additionalProperties: false,
+      },
+    }));
+    const input = readline.createInterface({
+      input: process.stdin,
+      crlfDelay: Infinity,
+      terminal: false,
+    });
+    const pending = new Set();
+    let toolCallQueue = Promise.resolve();
+    input.on("line", (line) => {
+      if (!line.trim()) return;
+      const execute = () =>
+        handleMcpMessage({
+          line,
+          options,
+          auth,
+          buildId,
+          session,
+          tools,
+        });
+      let isToolCall = false;
+      try {
+        isToolCall = JSON.parse(line)?.method === "tools/call";
+      } catch {
+        // The normal handler returns the canonical JSON-RPC parse error.
+      }
+      // App mutations are stateful and the browser runtime can execute only one
+      // canonical call at a time. Preserve the MCP client's receive order so a
+      // burst never depends on UUID or second-resolution database ordering.
+      const operation = isToolCall
+        ? (toolCallQueue = toolCallQueue.then(execute, execute))
+        : execute();
+      const observed = operation.catch((error) => {
+        process.stderr.write(
+          `lumine app-mcp: ${String(error?.message || error)}\n`,
+        );
+      });
+      pending.add(observed);
+      observed.finally(() => pending.delete(observed));
+    });
+    await new Promise((resolve) => input.once("close", resolve));
+    await Promise.allSettled(Array.from(pending));
+  } finally {
+    await closeAppMcpSession({
+      options,
+      auth,
+      buildId,
+      sessionId: session.id,
+    }).catch(() => {});
+  }
+}
+
+async function callAppTool({
+  options,
+  auth,
+  buildId,
+  sessionId,
+  name,
+  arguments: toolArguments,
+}) {
+  const created = await createAppMcpCall({
+    options,
+    auth,
+    buildId,
+    sessionId,
+    name,
+    arguments: toolArguments,
+  });
+  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;
+  while (Date.now() < deadline) {
+    const payload = await loadAppMcpCall({
+      options,
+      auth,
+      buildId,
+      sessionId,
+      callId,
+    });
+    const call = payload?.call;
+    if (call?.status === "completed") return call.result;
+    if (call?.status === "failed") {
+      throw new Error(call.errorMessage || "App tool failed.");
+    }
+    await delay(CALL_POLL_MS);
+  }
+  const finalPayload = await loadAppMcpCall({
+    options,
+    auth,
+    buildId,
+    sessionId,
+    callId,
+  });
+  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.");
+}
+
+async function handleMcpMessage({ line, options, auth, buildId, session, tools }) {
+  let message;
+  try {
+    message = JSON.parse(line);
+  } catch {
+    return writeMcpError(null, -32700, "Parse error");
+  }
+  const id = message?.id;
+  const method = String(message?.method || "");
+  if (id === undefined || id === null) return;
+  if (method === "initialize") {
+    return writeMcpResult(id, {
+      protocolVersion: MCP_PROTOCOL_VERSION,
+      capabilities: { tools: { listChanged: false } },
+      serverInfo: {
+        name: `lumine-app-${buildId}`,
+        version: "1.0.0",
+      },
+      instructions:
+        session.manifest.description ||
+        `Use the semantic tools exposed by ${session.buildTitle}.`,
+    });
+  }
+  if (method === "ping") return writeMcpResult(id, {});
+  if (method === "tools/list") return writeMcpResult(id, { tools });
+  if (method === "tools/call") {
+    const name = String(message?.params?.name || "");
+    if (!tools.some((tool) => tool.name === name)) {
+      return writeMcpError(id, -32602, `Unknown tool: ${name}`);
+    }
+    try {
+      const result = await callAppTool({
+        options,
+        auth,
+        buildId,
+        sessionId: session.id,
+        name,
+        arguments: message?.params?.arguments || {},
+      });
+      return writeMcpResult(id, {
+        content: [{ type: "text", text: JSON.stringify(result) }],
+        structuredContent:
+          result && typeof result === "object" && !Array.isArray(result)
+            ? result
+            : { result },
+        isError: false,
+      });
+    } catch (error) {
+      return writeMcpResult(id, {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({
+              ok: false,
+              error: String(error?.message || error),
+            }),
+          },
+        ],
+        isError: true,
+      });
+    }
+  }
+  return writeMcpError(id, -32601, `Method not found: ${method}`);
+}
+
+function writeMcpResult(id, result) {
+  process.stdout.write(`${JSON.stringify({ jsonrpc: "2.0", id, result })}\n`);
+}
+
+function writeMcpError(id, code, message) {
+  process.stdout.write(
+    `${JSON.stringify({ jsonrpc: "2.0", id, error: { code, message } })}\n`,
+  );
+}

package/lib/commands.js

@@ -66,6 +66,7 @@ import { adminCommand } from "./admin.js";
 import { runBuildForumCommand } from "./forum.js";
 import { agentCommand } from "./agent.js";
 import { agentMcpCommand } from "./agent/mcp-server.js";
+import { appMcpCommand } from "./app-mcp/server.js";
 import {
   defaultMainCheckoutDir,
   defaultReferenceDir,
@@ -111,6 +112,10 @@ export async function main() {
     await agentMcpCommand(options);
     return;
   }
+  if (options.command === "app-mcp") {
+    await appMcpCommand(options);
+    return;
+  }
   options.lumineCli = await loadLumineCliVersionInfo({ options });
   if (options.help) {
     printHelp();
@@ -1104,7 +1109,13 @@ export async function save(options) {
     lastSavedAt: new Date().toISOString(),
     filesHash: typeof result.filesHash === "string" ? result.filesHash : null,
   });
-  printSaveResult({ result, build, dir, files });
+  printSaveResult({
+    result,
+    build,
+    dir,
+    files,
+    publishRequested: Boolean(options.publish),
+  });
 
   if (options.publish) {
     if (build?.canPublish === false) {
@@ -1119,6 +1130,9 @@ export async function save(options) {
     } else {
       console.log("Publish complete.");
     }
+    console.log(
+      `Release status: ${publish.build?.releaseStatus?.state || "unknown"}`,
+    );
     console.log(`App: ${options.siteUrl}/app/${buildId}`);
   }
 }
@@ -2043,7 +2057,13 @@ export function printForkResult({ forkResult, pullResult }) {
   printPullResult(pullResult);
 }
 
-export function printSaveResult({ result, build, dir, files }) {
+export function printSaveResult({
+  result,
+  build,
+  dir,
+  files,
+  publishRequested = false,
+}) {
   const entryPath = result.projectManifest?.entryPath || "unknown";
   const version = result.artifactVersion?.versionNumber
     ? ` v${result.artifactVersion.versionNumber}`
@@ -2054,7 +2074,8 @@ export function printSaveResult({ result, build, dir, files }) {
     `Uploaded ${files.length} file${files.length === 1 ? "" : "s"} from ${dir}`,
   );
   console.log(`Entry: ${entryPath}`);
-  console.log(`Release status: ${releaseState}`);
+  const willPublish = publishRequested && build?.canPublish !== false;
+  if (!willPublish) console.log(`Release status: ${releaseState}`);
   if (isContributionBranch(build) && build.canPublish === false) {
     console.log(
       'Next: notify the project owner with `lumine suggest branch "Ready for review"`.',
@@ -2062,7 +2083,7 @@ export function printSaveResult({ result, build, dir, files }) {
     console.log(
       "To offer this branch's thumbnail, run `lumine suggest thumbnail`.",
     );
-  } else {
+  } else if (!willPublish) {
     console.log(
       "Next: run `lumine launch` to publish, or `lumine save --publish` next time.",
     );
@@ -2668,6 +2689,7 @@ export function printHelp() {
   lumine whoami
   lumine logout
   lumine agent --provider <codex|claude-code> "<build request>"
+  lumine app-mcp <published-app-url-or-id> [--no-open]
   lumine new [title]
   lumine rename [title] [--target <twinkle-build-url-or-id>]
   lumine describe [description] [--target <twinkle-build-url-or-id>]
@@ -2720,6 +2742,9 @@ export function printHelp() {
   lumine admin daily-run escalation add --target <target> --note <summary> [--severity attention|urgent] [--json]
   lumine admin escalation list [--status open|acknowledged|resolved|all] [--limit <number>] [--json]
   lumine admin escalation set <audit-id> --status open|acknowledged|resolved --note <decision> [--json]
+  lumine admin todo list [--status pending|open|in_progress|blocked|completed|cancelled|all] [--limit <number>] [--json]
+  lumine admin todo add --title <title> --note <handoff-and-acceptance-criteria> [--kind task|experiment] [--status open|in_progress|blocked] [--json]
+  lumine admin todo update <todo-id> --status open|in_progress|blocked|completed|cancelled --note <progress-or-evidence> [--json]
   lumine admin recommendations list [--since-run|--after <date>|--include-legacy] [--all --checkpoint <file> [--resume]] [--content-types comment,dailyReflection] [--unviewed|--viewed] [--cursor <cursor>] [--json]
   lumine admin builds candidates [--all --checkpoint <file> [--resume]] [--cursor <cursor>] [--limit <number>] [--json]
   lumine admin builds review <build-url-or-id> [--output-dir <dir>] [--wait-ms <ms>] [--browser-path <path>] [--json]
@@ -2816,11 +2841,11 @@ Options:
   --target <build>      Explicit Build URL or ID for rename/describe/upgrade
   --main                With pull/versions/restore: target the team project's main
   --version <n>         With pull: read-only checkout of previous save v<n>
-  --title <text>        Build title for new/rename
+  --title <text>        Build title for new/rename, or private todo title
   --description <text>  Build description for new/describe
   --no-description      Skip New description or clear with describe
   --summary <text>      Save summary
-  --note <text>         Suggestion, notable-user, or AI-bucket context
+  --note <text>         Suggestion, notable-user, AI-bucket, or todo context
   --cursor <id>         Continue suggestions, Forum activity, or admin listing
   --poll-ms <ms>        Forum listener interval (1000-60000; default 3000)
   --after <date>        Admin listing: inclusive Unix/ISO creation boundary
@@ -2836,6 +2861,7 @@ Options:
   --target-file <file>  JSON array or newline list for audited batch skips
   --review-receipt <f>  Confirmed managed Build runtime review receipt
   --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)
   --browser-path <path> Chrome/Chromium executable for managed Build review
   --effort unassigned  Admin subjects: show only unassigned effort
@@ -2851,7 +2877,7 @@ Options:
   --label <name>        Name for a new unbanned AI identity bucket
   --user-ids <ids>      Explicit user IDs for an AI bucket batch (up to 500)
   --type <type>         Admin target: subject, comment, build, aiStory, or dailyReflection
-  --kind recommend      Admin recommendation queue kind
+  --kind <kind>         Admin recommendation kind or todo task/experiment kind
   --anyone-can-reward   Enable canonical reward eligibility
   --reward-twinkles 3   Pair a recommendation with exactly 3 Twinkles
   --twinkles 3          Give exactly 3 Twinkles through the normal economy

package/lib/constants.js

@@ -31,6 +31,18 @@ export const THUMBNAIL_CONTENT_TYPE_BY_EXTENSION = {
 export const THUMBNAIL_MAX_FILE_SIZE_BYTES = 8 * 1024 * 1024;
 export const UPDATE_CHECK_TIMEOUT_MS = 1500;
 export const DEFAULT_PROJECT_LIMIT = 50;
+export const BUILD_VENDOR_THREE_VERSION = "0.184.0";
+export const BUILD_VENDOR_THREE_LEGACY_VERSION = "0.160.0";
+export const BUILD_VENDOR_THREE_PREFIX =
+  `/build/vendor/three/${BUILD_VENDOR_THREE_VERSION}/`;
+export const BUILD_VENDOR_THREE_MODULE_IMPORT =
+  `${BUILD_VENDOR_THREE_PREFIX}three.module.min.js`;
+export const BUILD_VENDOR_THREE_WEBGPU_MODULE_IMPORT =
+  `${BUILD_VENDOR_THREE_PREFIX}three.webgpu.min.js`;
+export const BUILD_VENDOR_THREE_TSL_MODULE_IMPORT =
+  `${BUILD_VENDOR_THREE_PREFIX}three.tsl.min.js`;
+export const BUILD_VENDOR_THREE_ADDONS_IMPORT_PREFIX =
+  `${BUILD_VENDOR_THREE_PREFIX}addons/`;
 export const PROJECT_METADATA_DIR = ".twinkle";
 export const PROJECT_METADATA_FILE = "lumine-project.json";
 export const ASSETS_METADATA_FILE = "assets.json";
@@ -120,6 +132,14 @@ Use these current source-of-truth rules:
 - Use Twinkle.preview for canvas, WebGL, Three.js, fullscreen, and game layout.
 - 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}';
+- Twinkle serves the supported official Three.js ${BUILD_VENDOR_THREE_VERSION} addon tree under ${BUILD_VENDOR_THREE_ADDONS_IMPORT_PREFIX}, including controls, loaders, CSS renderers, shaders, physics and WebXR helpers, and WebGLRenderer post-processing modules such as EffectComposer, RenderPass, SSAOPass/GTAOPass, UnrealBloomPass, and OutputPass. Example: import { EffectComposer } from '${BUILD_VENDOR_THREE_ADDONS_IMPORT_PREFIX}postprocessing/EffectComposer.js';
+- The workspace file tree does not enumerate vendor modules, so absence there is not evidence that an official addon is unavailable. Use its documented addon subpath and run lumine check; validation checks the exact file and its transitive imports.
+- WebGPU and TSL entry modules are also vendored at ${BUILD_VENDOR_THREE_WEBGPU_MODULE_IMPORT} and ${BUILD_VENDOR_THREE_TSL_MODULE_IMPORT}, but WebGL EffectComposer passes do not work with WebGPURenderer and runtime GPU support varies.
+- Treat addons as available tools, not defaults. Use them when they materially serve the requested experience; for continuously animated mobile builds, include a performance profile that targets about 30 FPS, caps render pixel ratio around 1-1.25, and lowers expensive post-processing resolution or quality only when that preserves the requested visual behavior. Do not remove or disable a requested visual effect as a performance tradeoff without the user's explicit approval.
+- Keep one Three.js version throughout a project. If a project using ${BUILD_VENDOR_THREE_LEGACY_VERSION} needs current addons, migrate every Three.js import to ${BUILD_VENDOR_THREE_VERSION} in one coherent change; never mix the legacy core with current addons.
+- This vendor surface covers supported official Three.js modules, not arbitrary third-party Three.js packages. Do not paste library source into project files or use npm/CDN copies. Loader runtime assets are served too: point decoder/transcoder paths at the addon prefix (example: dracoLoader.setDecoderPath('${BUILD_VENDOR_THREE_ADDONS_IMPORT_PREFIX}libs/draco/');).
+- Size both WebGLRenderer and EffectComposer from Twinkle.preview layout dimensions, coalesce resize work, and render with composer.render() when a composer owns the pass chain.`;
 export const LUMINE_AGENT_INSTRUCTIONS = `${LUMINE_AGENT_INSTRUCTIONS_MARKER}
 # Lumine Project Agent Guide
 
@@ -260,14 +280,15 @@ lumine save --summary "Describe the change"
 - Interface text must not be selectable on touch devices: long-pressing UI on mobile must not highlight it. Apply user-select: none plus -webkit-user-select: none and -webkit-touch-callout: none to interface text (HUD, buttons, labels, menus, scores, game controls). Keep text inputs and genuinely user-copyable content (story text, chat messages, user-written text) selectable. lumine check flags projects whose reachable files have clickable UI but no user-select: none rule.
 - CAUTION: the preview runtime AUTO-DETECTS "game apps" — any <canvas> in the body (even a decorative background canvas) or game-y words in visible text switch the app to viewport-app mode: html/body get overflow:hidden !important and body becomes a centering flexbox, so tall document-flow pages clip and stop scrolling. Document-style apps that use a canvas must call Twinkle.preview.subscribe (or getLayout/reserveInsets) early at boot — any of those opts out of auto game mode — then pad by layout.safeInsets and scroll within layout.viewport.height.
 - For canvas, WebGL, Three.js, fullscreen, or game builds, use Twinkle.preview for layout. Do not size roots from 100vh, 100vw, 100dvh, 100dvw, window.innerWidth, window.innerHeight, visualViewport, or document viewport dimensions.
-- For Three.js, use import * as THREE from '/build/vendor/three/0.184.0/three.module.min.js';. Addons (OrbitControls, GLTFLoader, ...) live under /build/vendor/three/0.184.0/addons/, e.g. import { OrbitControls } from '/build/vendor/three/0.184.0/addons/controls/OrbitControls.js';. Builds saved with the older /build/vendor/three/0.160.0/ path keep working.
+${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.
 
 ## Local Testing (Playwright / browser probes)
 
 - Serve the workspace with a tiny local HTTP server and drive it with Playwright. NEVER copy probe/vendor files into the workspace dir — lumine save uploads everything here (and binary files fail validation). Build a sibling probe dir that symlinks the workspace files instead.
-- Vendored imports like /build/vendor/three/0.184.0/... are absolute paths: mirror that directory under your probe dir's root and fetch the files from the LIVE SITE (e.g. https://www.twin-kle.com/build/vendor/three/0.184.0/three.webgpu.min.js). three 0.184 splits into three.module.min.js + three.core.min.js — mirror BOTH or imports fail. Do NOT use npm/CDN copies — the platform's vendored builds have rewritten import specifiers (npm three.tsl.min.js still imports bare "three/webgpu" and breaks the module graph).
+- Vendored imports like ${BUILD_VENDOR_THREE_PREFIX}... are absolute paths: mirror that directory under your probe dir's root and fetch the files from the LIVE SITE (e.g. ${DEFAULT_SITE_URL}${BUILD_VENDOR_THREE_WEBGPU_MODULE_IMPORT}). Three.js ${BUILD_VENDOR_THREE_VERSION} splits into three.module.min.js + three.core.min.js — mirror BOTH plus every addon's relative import closure or imports fail. Do NOT use npm/CDN copies — the platform's vendored builds have rewritten import specifiers (npm three.tsl.min.js still imports bare "three/webgpu" and breaks the module graph).
+- A local 404 caused by an incomplete vendor mirror is a probe setup failure, not evidence that the addon is unavailable on Twinkle. Check the live same-origin vendor URL or the saved Twinkle preview before reporting a platform limitation.
 - The three WebGPU renderer falls back to WebGL2 in headless Chromium automatically. Headless software rendering runs at ~2-5fps, so anything time-based (walking a character, timers) takes ~10-20x longer than real time — loop with generous waits instead of fixed short sleeps, and bump navigation timeouts.
 - To inspect module-scope game state, append debug getters when SERVING main.js (e.g. body += "window.__dbg = () => ({...})") rather than editing workspace files.
 - SDK calls are absent when serving locally; well-written builds optional-chain window.Twinkle and fall back to localStorage. Seed localStorage in the probe to fake saves.
@@ -345,6 +366,7 @@ export const COMMANDS = new Set([
   "admin",
   "agent",
   "agent-mcp",
+  "app-mcp",
   "workspace",
   "login",
   "logout",

package/lib/doctor.js

@@ -3,6 +3,7 @@ import { createRequire } from "module";
 import { buildApiJson, mintBuildApiToken } from "./api.js";
 import { ensureAuth, assertAuthScope } from "./auth.js";
 import { uploadRuntimeAsset } from "./assets.js";
+import { BUILD_VENDOR_THREE_ADDONS_IMPORT_PREFIX } from "./constants.js";
 import { requestJson } from "./http.js";
 import { resolveSdkBuildId } from "./sdk.js";
 import { formatBytes, trimTrailingSlash } from "./util.js";
@@ -389,7 +390,7 @@ async function createRuntimeAssetsPreviewSession({
   };
 }
 
-function buildRuntimeAssetsProbeHtml({ hdrUrl, glbUrl }) {
+export function buildRuntimeAssetsProbeHtml({ hdrUrl, glbUrl }) {
   return `<!doctype html>
 <html>
 <head>
@@ -429,7 +430,7 @@ function buildRuntimeAssetsProbeHtml({ hdrUrl, glbUrl }) {
     }
 
     async function loadHdr(url) {
-      const { RGBELoader } = await import('/build/vendor/three/0.184.0/addons/loaders/RGBELoader.js');
+      const { RGBELoader } = await import('${BUILD_VENDOR_THREE_ADDONS_IMPORT_PREFIX}loaders/RGBELoader.js');
       const texture = await new Promise((resolve, reject) => {
         new RGBELoader().load(url, resolve, undefined, reject);
       });
@@ -442,7 +443,7 @@ function buildRuntimeAssetsProbeHtml({ hdrUrl, glbUrl }) {
     }
 
     async function loadGlb(url) {
-      const { GLTFLoader } = await import('/build/vendor/three/0.184.0/addons/loaders/GLTFLoader.js');
+      const { GLTFLoader } = await import('${BUILD_VENDOR_THREE_ADDONS_IMPORT_PREFIX}loaders/GLTFLoader.js');
       const gltf = await new Promise((resolve, reject) => {
         new GLTFLoader().load(url, resolve, undefined, reject);
       });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage5/lumine",
-  "version": "0.2.43",
+  "version": "0.2.46",
   "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.33.0
-Updated: 2026-08-15
-Generated: 2026-08-15T03:00:24.685Z
+Version: 1.35.0
+Updated: 2026-08-18
+Generated: 2026-08-18T06:06:02.345Z
 
 ## Notes
 - This SDK is injected into Build iframes via the Build preview/runtime.
@@ -113,6 +113,16 @@ files:read, user:read, users:read, dailyReflections:read, content:read, content:
   - Use navigate() for routes inside the current Build and openContent() for Twinkle subjects, comments, apps, profiles, and other content pages.
   - Example: await Twinkle.app.openContent('https://www.twin-kle.com/subjects/432');
 
+### Twinkle.appTools
+- async register({ handlers }) | scopes: none
+  - Returns: { success, session } when opened by lumine app-mcp
+  - Register the live iframe handlers for the published app's static MCP tool manifest.
+  - Tool discovery comes only from /app-tools.json in the pinned published artifact; runtime code cannot add or rename tools.
+  - Every declared tool needs a same-named handler. Outside an app-mcp session, registration stores the handlers and resolves with active:false without starting a relay.
+  - Handlers run serially inside the visible app iframe and should return the confirmed post-action state.
+  - Do not synthesize server-owned state; await Twinkle SDK mutations before returning.
+  - Example: await Twinkle.appTools.register({ handlers: { get_state: () => ({ view, data }), open_view: ({ view }) => navigateTo(view) } });
+
 ### Twinkle.preview
 - getLayout() | scopes: none
   - Returns: { mode, viewport, stage, safeInsets, playfield }
@@ -302,6 +312,16 @@ console.log(analysis.bestMove, analysis.evaluation, analysis.mate);
   - Example: await Twinkle.files.delete(assetId);
 
 ### Twinkle.ai
+- async getUsagePolicy() | scopes: none
+  - Returns: BuildAiUsagePolicy | null
+  - Load the signed-in viewer's canonical current AI Energy battery policy.
+  - Signed-in viewers only.
+  - Returns canonical server state and does not consume AI Energy.
+  - Use energyPercent for a percentage meter and energySegments plus energySegmentsRemaining for segmented battery UI.
+  - The Build-safe response includes battery/day/usage fields only; account identity, email, risk, and recharge-eligibility metadata are not exposed to the app iframe.
+  - Successful AI calls return a newer aiUsagePolicy snapshot. Energy-related SDK errors expose the confirmed snapshot as error.aiUsagePolicy. Replace displayed state only from those confirmed values; do not decrement or synthesize battery state locally.
+  - Example: const policy = await Twinkle.ai.getUsagePolicy();
+renderBattery(policy?.energyPercent, policy?.energySegmentsRemaining);
 - async listPrompts() | scopes: none
   - Returns: Array<{ id, title, description }>
   - Legacy helper. Twinkle.ai.chat does not require promptId for default runtime text generation.
@@ -321,20 +341,25 @@ console.log(analysis.bestMove, analysis.evaluation, analysis.mate);
   - 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, instructions, systemPrompt, webSearch } = {}) | scopes: none
-  - Returns: { object, result, model, provider, thinkingMode, requestedThinkingMode, webSearch, aiUsagePolicy }
-  - Generate a validated structured JSON object for app decisions, routing, grading, and game-state logic, optionally using live web search.
+- async generateObject({ prompt, expectedStructure, thinkingMode, mode, model, instructions, systemPrompt, webSearch, requestId, onText, onStatus } = {}) | 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.
   - 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.
-  - When AI Energy is empty, Low, Medium, and High all reject before new provider work; there is no free fallback mode.
+  - 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.
+  - 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.
+  - 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 SDK validates shape and retries malformed JSON, but app code should still validate business-specific enum values.
-  - Example: const { object } = await Twinkle.ai.generateObject({ thinkingMode: 'medium', prompt: 'Classify the player intent from: ' + playerText, expectedStructure: { action: 'string', targetCharacter: 'string', confidence: 0, shouldAskFollowUp: false } });
+  - 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) });
 - onChatStatus(listener) | scopes: none
   - Returns: unsubscribe function
   - Listen to shared runtime AI chat stream events.

package/sdk/LUMINE_ADMIN.md

@@ -73,10 +73,12 @@ members. The response returns the canonical bucket, including its id for
 later `get` / `accounts add` / `note set` calls.
 
 `accounts add` accepts 1-500 unique positive user IDs, preflights the complete
-batch before writing, adds the canonical user and durable verified-email rules,
+batch before writing, adds one exact canonical user rule per requested account,
 re-attributes current-day AI usage, and returns the canonical bucket members.
-It is idempotent to retry. The API records the real operator in the private
-Lumine audit log; no public bot identity is involved.
+It never infers or adds email aliases: shared verified addresses can belong to
+unrelated accounts, so email rules require a separate explicit operator action.
+The command is idempotent to retry. The API records the real operator in the
+private Lumine audit log; no public bot identity is involved.
 
 `note set` records up to 255 characters of private operational context on the
 canonical bucket. Use it to distinguish quota bookkeeping from moderation;
@@ -579,7 +581,10 @@ lumine admin escalation set 123 --status resolved \
 Schemas:
 
 ```ts
-type DailyRunStart = Success<{ run: DailyRun }>;
+type DailyRunStart = Success<{
+  run: DailyRun;
+  carryoverTodos: CarryoverTodos;
+}>;
 type DailyRunStatus = Success<{
   run: DailyRun | null;
   lastRun: DailyRun | null;
@@ -632,6 +637,86 @@ mutation when a caller needs the same retry identity across processes. The CLI
 generates a fresh key for every mutation invocation; if a mutation fails, its
 JSON error includes `details.retryIdempotencyKey` for a safe exact retry.
 
+## Private carry-over todos
+
+```bash
+lumine admin todo list --json
+lumine admin todo list --status all --json
+lumine admin todo add --kind experiment --status in_progress \
+  --title "Validate Zero/Ciel cost optimization" \
+  --note "Replay baseline and optimized conversations. Complete only after response-quality parity; lower cost with a weaker reply fails." --json
+lumine admin todo update 12 --status blocked \
+  --note "Implementation is ready; waiting for a complete cost bucket and old-vs-new quality replay." --json
+lumine admin todo update 12 --status completed \
+  --note "Blind parity comparison passed every required dimension; measured cost and latency evidence attached in this note." --json
+```
+
+Todos are private operator work, not Zero/Ciel public actions. They persist
+independently of daily runs and are therefore available before a run starts and
+after it closes. Creating or updating one uses the run-independent transactional
+audit path: canonical todo state and its private `todo.create` / `todo.update`
+audit response commit together, and no public bot, public mutation count, or
+rotation signal is involved.
+
+Every successful `daily-run start` response automatically includes all
+unfinished items under `data.carryoverTodos`. The same run ID increments an
+item's surfacing telemetry at most once, even when start is retried. This is the
+canonical handoff: read it before discretionary new work, resume what can safely
+progress after the run's mandatory newspaper/brief/conduct duties, and record a
+concrete progress note before the run closes. The daily-run report includes the
+still-unfinished set again. Completing a daily run never silently completes its
+todos. A CLI carrying this contract rejects a start response that does not echo
+the canonical handoff, so a newer CLI against an API deployed before the todo
+migration cannot quietly treat unsupported telemetry as an empty list.
+
+`kind` is `task` or `experiment`. New items may start `open`, `in_progress`, or
+`blocked`; updates may also use `completed` or `cancelled`. A progress note is
+required for every update. For experiments, put the acceptance criteria in the
+initial details and use evidence—not implementation status—as the completion
+boundary. In particular, an AI-cost experiment is not complete until old-vs-new
+response-quality parity is demonstrated; a cheaper but weaker user response is
+a failed experiment. Up to 50 unfinished items may be carried so the automatic
+start payload remains complete and bounded.
+
+```ts
+type AdminTodo = {
+  id: number;
+  kind: "task" | "experiment";
+  title: string;
+  details: string;
+  status: "open" | "in_progress" | "blocked" | "completed" | "cancelled";
+  revision: number;
+  createdRunId: number | null;
+  lastWorkedRunId: number | null;
+  lastSurfacedRunId: number | null;
+  surfaceCount: number;
+  lastProgressNote: string | null;
+  createdAt: number;
+  updatedAt: number;
+  lastSurfacedAt: number | null;
+  completedAt: number | null;
+  cancelledAt: number | null;
+};
+
+type AdminTodoList = Success<{
+  todos: AdminTodo[];
+  statusFilter:
+    | "pending"
+    | "all"
+    | AdminTodo["status"];
+  truncated: boolean;
+}>;
+
+type AdminTodoMutation = Success<{ todo: AdminTodo }>;
+
+type CarryoverTodos = {
+  items: AdminTodo[];
+  count: number;
+  surfacedForRunId: number;
+  newlySurfacedCount: number;
+};
+```
+
 ## Canonical lists and inspection
 
 ```bash
@@ -2176,9 +2261,12 @@ Public content actions use ordinary Twinkle fan-out:
 - effort/creator changes emit `edit_content`;
 - Featured changes emit a canonical `home_outdated` refresh.
 
-Apply `twinkle-api/scripts/migrations/add-lumine-admin-delegation.sql` and
-then `add-lumine-admin-comment-targets.sql` before deploying the API. They add
-only focused daily-run, rotation, draft, and audit tables/columns and indexes;
+Apply `twinkle-api/scripts/migrations/add-lumine-admin-delegation.sql`, then
+`add-lumine-admin-comment-targets.sql`, and apply
+`add-lumine-admin-todos.sql` before deploying an API that exposes carry-over
+todos. They add
+only focused daily-run, rotation, draft, audit, and private-todo tables/columns
+and indexes;
 there are no runtime schema checks. The comment-targets migration backfills
 existing subject drafts into the generalized target columns. The local CLI changes
 are not available to users until a separately authorized npm publication.