@stage5/lumine 0.2.40 → 0.2.42

package/lib/build-review.js

@@ -0,0 +1,493 @@
+import { spawn } from "node:child_process";
+import {
+  existsSync,
+  mkdtempSync,
+  mkdirSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { requestJson } from "./http.js";
+import { writeAdminJsonFile } from "./admin-news.js";
+
+const DEFAULT_REVIEW_WAIT_MS = 10_000;
+const MAX_REVIEW_WAIT_MS = 45_000;
+const MAX_CAPTURED_LOG_LINES = 500;
+const CDP_COMMAND_TIMEOUT_MS = 10_000;
+
+function validationError(message, code = "CLI_ADMIN_CLI_VALIDATION") {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+export function parseBuildReviewReceipt(filePath) {
+  let receipt;
+  try {
+    receipt = JSON.parse(readFileSync(String(filePath || ""), "utf8"));
+  } catch {
+    throw validationError(`Could not read Build review receipt ${filePath}.`);
+  }
+  const buildId = Number(receipt?.buildId || 0);
+  const publishedArtifactVersionId = Number(
+    receipt?.publishedArtifactVersionId || 0,
+  );
+  const versionAfterReview = Number(receipt?.versionAfterReview || 0);
+  const screenshotPath = String(receipt?.screenshot?.path || "");
+  const screenshotBytes =
+    screenshotPath && existsSync(screenshotPath)
+      ? Number(statSync(screenshotPath).size || 0)
+      : 0;
+  if (
+    receipt?.schemaVersion !== 2 ||
+    receipt?.reviewMethod !== "runtime" ||
+    receipt?.status !== "confirmed" ||
+    !Number.isSafeInteger(buildId) ||
+    buildId <= 0 ||
+    !Number.isSafeInteger(publishedArtifactVersionId) ||
+    publishedArtifactVersionId <= 0 ||
+    versionAfterReview !== publishedArtifactVersionId ||
+    receipt?.versionStable !== true ||
+    receipt?.browser?.runtimeReadiness?.ready !== true ||
+    screenshotBytes <= 0 ||
+    screenshotBytes !== Number(receipt?.screenshot?.bytes || 0)
+  ) {
+    throw validationError(
+      "The Build review receipt is not a confirmed managed-runtime review.",
+    );
+  }
+  return receipt;
+}
+
+function findChromeExecutable(explicitPath = "") {
+  const candidates = [
+    explicitPath,
+    process.env.CHROME_PATH,
+    "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+    "/Applications/Chromium.app/Contents/MacOS/Chromium",
+    "/usr/bin/google-chrome",
+    "/usr/bin/google-chrome-stable",
+    "/usr/bin/chromium",
+    "/usr/bin/chromium-browser",
+  ].filter(Boolean);
+  const match = candidates.find((candidate) => existsSync(candidate));
+  if (!match) {
+    throw validationError(
+      "A Chrome/Chromium executable was not found. Pass --browser-path <path>.",
+      "CLI_ADMIN_BUILD_REVIEW_BROWSER_MISSING",
+    );
+  }
+  return match;
+}
+
+function boundedWaitMs(value) {
+  if (value === undefined || value === null || value === "") {
+    return DEFAULT_REVIEW_WAIT_MS;
+  }
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 1000 || parsed > MAX_REVIEW_WAIT_MS) {
+    throw validationError(
+      `--wait-ms must be an integer between 1000 and ${MAX_REVIEW_WAIT_MS}.`,
+    );
+  }
+  return parsed;
+}
+
+async function loadPublishedVersion({ apiUrl, buildId, timeoutMs }) {
+  const result = await requestJson({
+    url: `${String(apiUrl).replace(/\/$/, "")}/build/${buildId}/published-version`,
+    timeoutMs,
+  });
+  const versionId = Number(result?.publishedArtifactVersionId || 0);
+  if (!Number.isSafeInteger(versionId) || versionId <= 0) {
+    throw validationError(
+      `Build #${buildId} has no canonical published artifact to review.`,
+      "CLI_ADMIN_BUILD_REVIEW_NOT_PUBLISHED",
+    );
+  }
+  return versionId;
+}
+
+function delay(milliseconds) {
+  return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+
+function createCdpPipe(child) {
+  const commandPipe = child.stdio[3];
+  const eventPipe = child.stdio[4];
+  if (!commandPipe || !eventPipe) {
+    throw validationError(
+      "Chrome did not expose its managed review channel.",
+      "CLI_ADMIN_BUILD_REVIEW_BROWSER_CHANNEL_FAILED",
+    );
+  }
+  let nextId = 1;
+  let buffer = Buffer.alloc(0);
+  const pending = new Map();
+  const listeners = new Set();
+  eventPipe.on("data", (chunk) => {
+    buffer = Buffer.concat([buffer, chunk]);
+    for (let delimiter = buffer.indexOf(0); delimiter >= 0; delimiter = buffer.indexOf(0)) {
+      const payload = buffer.subarray(0, delimiter).toString("utf8");
+      buffer = buffer.subarray(delimiter + 1);
+      if (!payload) continue;
+      let message;
+      try {
+        message = JSON.parse(payload);
+      } catch {
+        continue;
+      }
+      if (message.id && pending.has(message.id)) {
+        const entry = pending.get(message.id);
+        pending.delete(message.id);
+        clearTimeout(entry.timer);
+        if (message.error) {
+          entry.reject(new Error(message.error.message || "Chrome command failed."));
+        } else {
+          entry.resolve(message.result || {});
+        }
+        continue;
+      }
+      for (const listener of [...listeners]) listener(message);
+    }
+  });
+  const rejectPending = () => {
+    for (const entry of pending.values()) {
+      clearTimeout(entry.timer);
+      entry.reject(new Error("Chrome closed its managed review channel."));
+    }
+    pending.clear();
+  };
+  child.once("close", rejectPending);
+  child.once("error", rejectPending);
+  return {
+    onEvent(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    send(method, params = {}, sessionId = "") {
+      const id = nextId++;
+      return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+          pending.delete(id);
+          reject(new Error(`Chrome timed out while running ${method}.`));
+        }, CDP_COMMAND_TIMEOUT_MS);
+        pending.set(id, { resolve, reject, timer });
+        const message = { id, method, params };
+        if (sessionId) message.sessionId = sessionId;
+        commandPipe.write(`${JSON.stringify(message)}\0`);
+      });
+    },
+  };
+}
+
+async function waitForPageTarget(cdp, expectedUrl) {
+  const deadline = Date.now() + CDP_COMMAND_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    const result = await cdp.send("Target.getTargets");
+    const targets = Array.isArray(result.targetInfos) ? result.targetInfos : [];
+    const exact = targets.find(
+      (target) => target.type === "page" && target.url === expectedUrl,
+    );
+    const fallback = targets.find(
+      (target) =>
+        target.type === "page" &&
+        /^https?:/i.test(String(target.url || "")) &&
+        !String(target.url).startsWith("chrome://"),
+    );
+    if (exact || fallback) return exact || fallback;
+    await delay(100);
+  }
+  throw new Error("Chrome did not open the requested Build page.");
+}
+
+const RUNTIME_READINESS_EXPRESSION = `(() => {
+  const visible = (element) => {
+    if (!element) return false;
+    const style = getComputedStyle(element);
+    const rect = element.getBoundingClientRect();
+    return style.display !== 'none' && style.visibility !== 'hidden' &&
+      Number(style.opacity || 1) > 0 && rect.width > 1 && rect.height > 1;
+  };
+  const preview = document.querySelector('iframe[title="App preview"]');
+  const progress = document.querySelector('[role="progressbar"]');
+  const runtimeError = document.querySelector('[data-agent-status="preview-error"]');
+  return {
+    documentReady: document.readyState === 'complete',
+    previewPresent: Boolean(preview),
+    previewVisible: visible(preview),
+    progressVisible: visible(progress),
+    runtimeErrorVisible: visible(runtimeError),
+    title: document.title || ''
+  };
+})()`;
+
+function isRuntimeReady(state) {
+  return Boolean(
+    state?.documentReady &&
+      state?.previewPresent &&
+      state?.previewVisible &&
+      !state?.progressVisible &&
+      !state?.runtimeErrorVisible,
+  );
+}
+
+function remoteArgumentText(argument) {
+  if (Object.hasOwn(argument || {}, "value")) {
+    const value = argument.value;
+    return typeof value === "string" ? value : JSON.stringify(value);
+  }
+  return String(argument?.description || argument?.type || "");
+}
+
+async function runChromeReview({ executable, url, screenshotPath, profileDir, waitMs }) {
+  const args = [
+    "--headless=new",
+    "--no-first-run",
+    "--no-default-browser-check",
+    "--disable-background-networking",
+    "--disable-component-update",
+    "--disable-sync",
+    "--hide-scrollbars",
+    "--enable-logging=stderr",
+    "--remote-debugging-pipe",
+    `--user-data-dir=${profileDir}`,
+    "--window-size=1440,1100",
+    url,
+  ];
+  const child = spawn(executable, args, {
+    stdio: ["ignore", "pipe", "pipe", "pipe", "pipe"],
+  });
+  let stdout = "";
+  let stderr = "";
+  const consoleLines = [];
+  const append = (current, chunk) => `${current}${chunk}`.slice(-2_000_000);
+  child.stdout.on("data", (chunk) => {
+    stdout = append(stdout, chunk);
+  });
+  child.stderr.on("data", (chunk) => {
+    stderr = append(stderr, chunk);
+  });
+  const closed = new Promise((resolve, reject) => {
+    child.once("error", reject);
+    child.once("close", (code, signal) => {
+      resolve({ code: Number(code ?? -1), signal: signal || null });
+    });
+  });
+  const timer = setTimeout(() => child.kill("SIGTERM"), Math.min(waitMs + 30_000, 58_000));
+  try {
+    const cdp = createCdpPipe(child);
+    cdp.onEvent((message) => {
+      if (message.method === "Runtime.consoleAPICalled") {
+        const values = Array.isArray(message.params?.args)
+          ? message.params.args.map(remoteArgumentText).filter(Boolean)
+          : [];
+        consoleLines.push(
+          `[console.${message.params?.type || "log"}] ${values.join(" ")}`,
+        );
+      } else if (message.method === "Runtime.exceptionThrown") {
+        consoleLines.push(
+          `[exception] ${message.params?.exceptionDetails?.exception?.description || message.params?.exceptionDetails?.text || "Uncaught exception"}`,
+        );
+      } else if (message.method === "Log.entryAdded") {
+        const entry = message.params?.entry;
+        consoleLines.push(
+          `[${entry?.level || "log"}] ${entry?.text || ""}${entry?.url ? ` (${entry.url})` : ""}`,
+        );
+      } else if (message.method === "Target.attachedToTarget") {
+        const childSessionId = String(message.params?.sessionId || "");
+        if (childSessionId) {
+          Promise.all([
+            cdp.send("Runtime.enable", {}, childSessionId),
+            cdp.send("Log.enable", {}, childSessionId),
+          ]).catch(() => {});
+        }
+      }
+    });
+    const target = await waitForPageTarget(cdp, url);
+    const attached = await cdp.send("Target.attachToTarget", {
+      targetId: target.targetId,
+      flatten: true,
+    });
+    const sessionId = String(attached.sessionId || "");
+    if (!sessionId) throw new Error("Chrome did not attach to the Build page.");
+    await Promise.all([
+      cdp.send("Page.enable", {}, sessionId),
+      cdp.send("Runtime.enable", {}, sessionId),
+      cdp.send("Log.enable", {}, sessionId),
+    ]);
+    await cdp.send(
+      "Target.setAutoAttach",
+      {
+        autoAttach: true,
+        waitForDebuggerOnStart: false,
+        flatten: true,
+      },
+      sessionId,
+    );
+    const deadline = Date.now() + waitMs;
+    let firstReadyAt = null;
+    let readiness = null;
+    do {
+      const evaluated = await cdp.send(
+        "Runtime.evaluate",
+        { expression: RUNTIME_READINESS_EXPRESSION, returnByValue: true },
+        sessionId,
+      );
+      readiness = evaluated.result?.value || null;
+      if (!firstReadyAt && isRuntimeReady(readiness)) {
+        firstReadyAt = new Date().toISOString();
+      }
+      const remaining = deadline - Date.now();
+      if (remaining > 0) await delay(Math.min(250, remaining));
+    } while (Date.now() < deadline);
+    const screenshot = await cdp.send(
+      "Page.captureScreenshot",
+      { format: "png", fromSurface: true, captureBeyondViewport: false },
+      sessionId,
+    );
+    if (screenshot.data) {
+      writeFileSync(screenshotPath, Buffer.from(screenshot.data, "base64"));
+    }
+    await cdp.send("Browser.close").catch(() => {});
+    const closeResult = await Promise.race([
+      closed,
+      delay(5_000).then(() => {
+        child.kill("SIGTERM");
+        return closed;
+      }),
+    ]);
+    return {
+      ...closeResult,
+      stdout,
+      stderr,
+      consoleLines: consoleLines.slice(-MAX_CAPTURED_LOG_LINES),
+      runtimeReadiness: {
+        ...(readiness || {}),
+        ready: isRuntimeReady(readiness),
+        firstReadyAt,
+      },
+    };
+  } finally {
+    clearTimeout(timer);
+    if (child.exitCode === null && child.signalCode === null) child.kill("SIGTERM");
+  }
+}
+
+function captureConsoleEvidence(stderr, cdpLines = []) {
+  const chromeLines = String(stderr || "")
+    .split(/\r?\n/)
+    .filter((line) =>
+      /(?:INFO:CONSOLE|Uncaught|Failed to load resource)/i.test(line),
+    )
+    .slice(-MAX_CAPTURED_LOG_LINES);
+  return [...new Set([...cdpLines, ...chromeLines])].slice(
+    -MAX_CAPTURED_LOG_LINES,
+  );
+}
+
+export async function runManagedBuildReview({ options, authToken, buildId }) {
+  const waitMs = boundedWaitMs(options.adminWaitMs);
+  const executable = findChromeExecutable(options.adminBrowserPath);
+  let outputDir;
+  if (options.adminOutputDir) {
+    const outputRoot = path.resolve(options.adminOutputDir);
+    mkdirSync(outputRoot, { recursive: true });
+    outputDir = mkdtempSync(path.join(outputRoot, `build-${buildId}-review-`));
+  } else {
+    outputDir = mkdtempSync(
+      path.join(os.tmpdir(), `lumine-build-${buildId}-review-`),
+    );
+  }
+  const profileDir = mkdtempSync(path.join(os.tmpdir(), "lumine-chrome-profile-"));
+  const screenshotPath = path.join(outputDir, "runtime.png");
+  const receiptPath = path.join(outputDir, "review.json");
+  const appUrl = `${String(options.siteUrl).replace(/\/$/, "")}/app/${buildId}`;
+  const beforeVersion = await loadPublishedVersion({
+    apiUrl: options.apiUrl,
+    buildId,
+    timeoutMs: options.timeoutMs,
+    authToken,
+  });
+  const startedAt = new Date().toISOString();
+  let browser;
+  try {
+    browser = await runChromeReview({
+      executable,
+      url: appUrl,
+      screenshotPath,
+      profileDir,
+      waitMs,
+    });
+  } finally {
+    rmSync(profileDir, { recursive: true, force: true });
+  }
+  const afterVersion = await loadPublishedVersion({
+    apiUrl: options.apiUrl,
+    buildId,
+    timeoutMs: options.timeoutMs,
+    authToken,
+  });
+  const screenshotBytes = existsSync(screenshotPath)
+    ? Number(statSync(screenshotPath).size || 0)
+    : 0;
+  const confirmed =
+    browser.code === 0 &&
+    screenshotBytes > 0 &&
+    browser.runtimeReadiness?.ready === true &&
+    beforeVersion === afterVersion;
+  const receipt = {
+    schemaVersion: 2,
+    status: confirmed ? "confirmed" : "failed",
+    reviewMethod: "runtime",
+    buildId,
+    appUrl,
+    publishedArtifactVersionId: beforeVersion,
+    versionAfterReview: afterVersion,
+    versionStable: beforeVersion === afterVersion,
+    startedAt,
+    completedAt: new Date().toISOString(),
+    waitMs,
+    browser: {
+      executable,
+      exitCode: browser.code,
+      signal: browser.signal,
+      runtimeReadiness: browser.runtimeReadiness,
+    },
+    screenshot: {
+      path: screenshotPath,
+      bytes: screenshotBytes,
+    },
+    console: captureConsoleEvidence(browser.stderr, browser.consoleLines),
+  };
+  writeAdminJsonFile(receiptPath, receipt);
+  if (!confirmed) {
+    const error = validationError(
+      beforeVersion !== afterVersion
+        ? "The Build was republished during review; review the new artifact before commenting."
+        : browser.runtimeReadiness?.runtimeErrorVisible
+          ? "The isolated Build runtime exposed a runtime error instead of a reviewable app."
+          : "The isolated Build runtime did not become visibly reviewable before the observation window ended.",
+      "CLI_ADMIN_BUILD_REVIEW_FAILED",
+    );
+    error.data = {
+      ok: false,
+      status: "validation_error",
+      error: {
+        code: error.code,
+        message: error.message,
+        details: { receiptPath, screenshotPath },
+      },
+    };
+    throw error;
+  }
+  return {
+    ok: true,
+    status: "success",
+    data: { review: receipt, receiptPath, screenshotPath },
+  };
+}

package/lib/commands.js

@@ -64,6 +64,8 @@ import { sdkCommand } from "./sdk.js";
 import { doctorCommand, normalizePreviewUrl } from "./doctor.js";
 import { adminCommand } from "./admin.js";
 import { runBuildForumCommand } from "./forum.js";
+import { agentCommand } from "./agent.js";
+import { agentMcpCommand } from "./agent/mcp-server.js";
 import {
   defaultMainCheckoutDir,
   defaultReferenceDir,
@@ -103,6 +105,12 @@ import {
 
 export async function main() {
   const options = parseArgs(process.argv.slice(2));
+  // MCP stdio must remain protocol-clean: no update checks, help text, or
+  // other stdout can run before the server takes ownership of the stream.
+  if (options.command === "agent-mcp") {
+    await agentMcpCommand(options);
+    return;
+  }
   options.lumineCli = await loadLumineCliVersionInfo({ options });
   if (options.help) {
     printHelp();
@@ -117,6 +125,11 @@ export async function main() {
     return;
   }
 
+  if (options.command === "agent") {
+    await agentCommand(options, { saveWorkspace: save });
+    return;
+  }
+
   if (options.command === "workspace") {
     await workspace(options);
     return;
@@ -2209,6 +2222,12 @@ export function parseArgs(args) {
     "full",
     "unviewed",
     "viewed",
+    "all",
+    "resume",
+    "sinceRun",
+    "includeLegacy",
+    "includePrivateEvidence",
+    "noReviewLoop",
   ]);
 
   for (let i = 0; i < rest.length; i += 1) {
@@ -2308,7 +2327,35 @@ export function parseArgs(args) {
     cursor: Math.max(0, Math.floor(Number(raw.cursor) || 0)),
     adminCursor: raw.cursor ? String(raw.cursor) : "",
     adminAfter: raw.after ? String(raw.after) : "",
+    adminSinceRun: Boolean(raw.sinceRun),
+    adminIncludeLegacy: Boolean(raw.includeLegacy),
+    adminIncludePrivateEvidence: parseBoolean(raw.includePrivateEvidence, false),
+    adminAll: Boolean(raw.all),
+    adminResume: Boolean(raw.resume),
+    adminCheckpoint: raw.checkpoint ? String(raw.checkpoint) : "",
+    adminOutput: raw.output ? String(raw.output) : "",
+    adminOutputDir: raw.outputDir ? String(raw.outputDir) : "",
+    adminClaimFile: raw.claim ? String(raw.claim) : "",
+    adminScaffoldFile: raw.scaffold ? String(raw.scaffold) : "",
+    adminTargetFile: raw.targetFile ? String(raw.targetFile) : "",
+    adminReviewReceipt: raw.reviewReceipt ? String(raw.reviewReceipt) : "",
+    adminSeverity: raw.severity ? String(raw.severity) : "",
+    adminStatus: raw.status ? String(raw.status) : "",
+    adminWaitMs: raw.waitMs ? String(raw.waitMs) : "",
+    adminBrowserPath: raw.browserPath ? String(raw.browserPath) : "",
     adminEffort: raw.effort ? String(raw.effort) : "",
+    agentEffort:
+      command === "agent" && raw.effort ? String(raw.effort) : "",
+    provider: raw.provider ? String(raw.provider) : "",
+    providerPath: raw.providerPath ? String(raw.providerPath) : "",
+    agentPrompt:
+      command === "agent"
+        ? String(raw.prompt || positional.join(" ")).trim()
+        : "",
+    runtimeFile: raw.runtimeFile ? String(raw.runtimeFile) : "",
+    traceFile: raw.traceFile ? String(raw.traceFile) : "",
+    baseFilesHash: raw.baseFilesHash ? String(raw.baseFilesHash) : "",
+    reviewLoop: parseBoolean(raw.noReviewLoop, false) ? false : true,
     adminLevel: raw.level ? String(raw.level) : "",
     adminIds: raw.subjectIds
       ? String(raw.subjectIds)
@@ -2620,6 +2667,7 @@ export function printHelp() {
   lumine login
   lumine whoami
   lumine logout
+  lumine agent --provider <codex|claude-code> "<build request>"
   lumine new [title]
   lumine rename [title] [--target <twinkle-build-url-or-id>]
   lumine describe [description] [--target <twinkle-build-url-or-id>]
@@ -2662,28 +2710,34 @@ export function printHelp() {
   lumine thumbnail generate ["<prompt>"] --model <gpt-image-2|nano-banana>
   lumine doctor runtime-assets
   lumine admin identity list|status|use <zero|ciel|auto> [--json]
+  lumine admin identity inspect <user-id|username> --reason <management-reason> [--include-private-evidence] [--json]
   lumine admin ai-bucket create --label <name> --note <text> [--json]
   lumine admin ai-bucket get --bucket-id <id> [--json]
   lumine admin ai-bucket accounts add --bucket-id <id> --user-ids <id,id,...> [--note <text>] [--json]
   lumine admin ai-bucket note set --bucket-id <id> --note <text> [--json]
   lumine admin daily-run start [--identity zero|ciel|auto] [--comment-mode off|draft|post] [--run-key <key>] [--json]
-  lumine admin daily-run status|complete|fail [--reason <text>] [--json]
-  lumine admin recommendations list [--content-types comment,dailyReflection] [--unviewed|--viewed] [--cursor <cursor>] [--json]
-  lumine admin builds candidates [--cursor <cursor>] [--limit <number>] [--json]
-  lumine admin subjects candidates [--after <date>] [--effort unassigned] [--unviewed|--viewed] [--cursor <cursor>] [--json]
+  lumine admin daily-run status|report|complete|fail [--reason <text>] [--json]
+  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 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]
+  lumine admin subjects candidates [--after <date>] [--effort unassigned] [--unviewed|--viewed] [--all --checkpoint <file> [--resume]] [--cursor <cursor>] [--json]
   lumine admin subject get|reveal <subject-url-or-id> [--json]
-  lumine admin subject comments <subject-url-or-id> [--unviewed|--viewed] [--cursor <cursor>] [--json]
+  lumine admin subject comments <subject-url-or-id> [--unviewed|--viewed] [--all --checkpoint <file> [--resume]] [--cursor <cursor>] [--json]
   lumine admin subject effort set <subject-id> --level <1|2|3> [--json]
   lumine admin subject creator set-made-by-poster <subject-id> [--json]
   lumine admin subject feature|unfeature <subject-id> [--json]
   lumine admin featured list [--unviewed|--viewed] [--json]
   lumine admin featured reorder --subject-ids <id,id,...> [--json]
   lumine admin post get <target> [--type subject|comment|aiStory|dailyReflection] [--json]
-  lumine admin post comments <target> [--type subject|aiStory|dailyReflection] [--unviewed|--viewed] [--cursor <cursor>] [--json]
+  lumine admin post comments <target> [--type subject|aiStory|dailyReflection] [--unviewed|--viewed] [--all --checkpoint <file> [--resume]] [--cursor <cursor>] [--json]
   lumine admin post recommend <target> [--type subject|comment|aiStory|dailyReflection] [--anyone-can-reward] [--reward-twinkles 3] [--json]
   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>] [--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] [--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 post --draft-id <id> [--json]
   lumine admin comment edit <comment-id> --file <comment.md> [--json]
@@ -2691,8 +2745,11 @@ export function printHelp() {
   lumine admin bot-output [--days <1..30>] [--json]
   lumine admin announcement post --file <announcement.md> [--json]
   lumine admin chat send <user-id|username> --file <message.md> [--json]
+  lumine admin news claim [--date YYYY-MM-DD] [--output <claim.json>] [--scaffold <editorial.json>] [--json]
+  lumine admin news validate --claim <claim.json> --file <editorial.json> [--json]
+  lumine admin news submit --claim <claim.json> --file <editorial.json> [--model <name>] [--json]
   lumine admin notable add <user-id|username> --note <text> [--json]
-  lumine admin audit [list] [--run current|last|<run-id>] [--target <target>] [--actions <a,b>] [--full] [--cursor <cursor>] [--json]
+  lumine admin audit [list] [--run current|last|<run-id>] [--target <target>] [--actions <a,b>] [--full] [--all --checkpoint <file> [--resume]] [--cursor <cursor>] [--json]
 
 Examples:
   npx @stage5/lumine@latest
@@ -2723,6 +2780,8 @@ Examples:
   npx @stage5/lumine@latest restore 41 --main
   npx @stage5/lumine@latest update-from-main
   npx @stage5/lumine@latest pull
+  npx @stage5/lumine@latest agent --provider codex "Add keyboard controls"
+  npx @stage5/lumine@latest agent --provider claude-code "Fix the mobile layout"
   npx @stage5/lumine@latest save
   npx @stage5/lumine@latest save --publish
   npx @stage5/lumine@latest launch --save
@@ -2750,6 +2809,10 @@ Options:
   --auth-file <path>    Saved login path
   --auth-token <token>  Override saved login
   --dir <path>          Directory for pulled project files
+  --provider <agent>    Subscription agent for lumine agent: codex or claude-code
+  --provider-path <p>   Override the selected agent CLI executable
+  --effort <level>      Optional provider reasoning effort
+  --no-review-loop      Skip the evidence-based post-run loop retrospective
   --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>
@@ -2760,7 +2823,21 @@ Options:
   --note <text>         Suggestion, notable-user, or AI-bucket context
   --cursor <id>         Continue suggestions, Forum activity, or admin listing
   --poll-ms <ms>        Forum listener interval (1000-60000; default 3000)
-  --after <date>        Admin subjects: inclusive Unix/ISO creation boundary
+  --after <date>        Admin listing: inclusive Unix/ISO creation boundary
+  --since-run           Recommendations since the previous completed run (default)
+  --include-legacy      Explicitly include the full historical recommendation queue
+  --all                 Automatically read every page in the canonical snapshot
+  --checkpoint <file>   Persist automatic pagination or batch progress
+  --resume              Resume the exact request recorded by --checkpoint
+  --output <file>       Save an admin result or newspaper claim as JSON
+  --output-dir <dir>    Directory for managed Build review evidence
+  --claim <file>        Newspaper claim JSON used for validation/submission
+  --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
+  --severity <level>    Run escalation severity: attention or urgent
+  --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
   --unviewed           Admin content lists: retain unviewed and unknown items
   --viewed             Admin content lists: retain viewed and unknown items

package/lib/constants.js

@@ -343,6 +343,8 @@ export const MAIN_CHECKOUT_READONLY_COMMANDS = new Set([
 ]);
 export const COMMANDS = new Set([
   "admin",
+  "agent",
+  "agent-mcp",
   "workspace",
   "login",
   "logout",