@stage5/lumine 0.2.39 → 0.2.41

package/lib/commands.js

@@ -63,6 +63,9 @@ import { probeUrl, requestJson } from "./http.js";
 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,
@@ -102,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();
@@ -116,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;
@@ -156,6 +170,10 @@ export async function main() {
     await branches(options);
     return;
   }
+  if (options.command === "forum") {
+    await forum(options);
+    return;
+  }
   if (options.command === "suggest") {
     await sendSuggestion(options);
     return;
@@ -450,6 +468,28 @@ export async function branches(options) {
   printContributionBranches({ result, rootBuild, options });
 }
 
+export async function forum(options) {
+  const explicitAction = ["read", "listen"].includes(
+    String(options.positional?.[0] || ""),
+  );
+  const maximumPositionals = explicitAction ? 2 : 1;
+  if ((options.positional?.length || 0) > maximumPositionals) {
+    throw new Error(
+      "Usage: lumine forum [read|listen] [twinkle-build-url-or-id]",
+    );
+  }
+  if (options.forumCursor === null) {
+    throw new Error("--cursor must be a non-negative integer.");
+  }
+  if (options.forumPollMs === null) {
+    throw new Error("--poll-ms must be an integer from 1000 through 60000.");
+  }
+  const auth = await resolveAuth(options);
+  await assertAuthScope({ options, auth, scope: "build:read" });
+  const buildId = await resolveRequiredBuildIdOrSelected(options, auth);
+  await runBuildForumCommand({ options, auth, buildId });
+}
+
 export async function sendSuggestion(options) {
   const suggestionType = String(options.suggestionAction || "").trim();
   if (suggestionType !== "branch" && suggestionType !== "thumbnail") {
@@ -2182,6 +2222,11 @@ export function parseArgs(args) {
     "full",
     "unviewed",
     "viewed",
+    "all",
+    "resume",
+    "sinceRun",
+    "includeLegacy",
+    "noReviewLoop",
   ]);
 
   for (let i = 0; i < rest.length; i += 1) {
@@ -2233,10 +2278,39 @@ export function parseArgs(args) {
           positional[0] === "list" ? positional[1] || "" : positional[0] || "",
         )
       : "";
+  const forumAction =
+    command === "forum" && ["read", "listen"].includes(positional[0])
+      ? String(positional[0])
+      : "read";
+  const forumTarget =
+    command === "forum"
+      ? String(
+          forumAction === "read" && positional[0] !== "read"
+            ? positional[0] || ""
+            : positional[1] || "",
+        )
+      : "";
+  const forumCursor = Object.prototype.hasOwnProperty.call(raw, "cursor")
+    ? /^\d+$/.test(String(raw.cursor).trim()) &&
+      Number.isSafeInteger(Number(raw.cursor))
+      ? Number(raw.cursor)
+      : null
+    : 0;
+  const forumPollMs = Object.prototype.hasOwnProperty.call(raw, "pollMs")
+    ? /^\d+$/.test(String(raw.pollMs).trim()) &&
+      Number.isSafeInteger(Number(raw.pollMs)) &&
+      Number(raw.pollMs) >= 1000 &&
+      Number(raw.pollMs) <= 60_000
+      ? Number(raw.pollMs)
+      : null
+    : 3000;
 
   return {
     command,
     positional,
+    forumAction,
+    forumCursor,
+    forumPollMs,
     suggestionAction,
     suggestionId:
       command === "suggestions" && suggestionAction !== "list"
@@ -2252,7 +2326,33 @@ 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),
+    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) : "",
+    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)
@@ -2310,7 +2410,9 @@ export function parseArgs(args) {
         ? ""
         : command === "suggestions"
           ? suggestionListTarget
-          : positional[0] || ""),
+          : command === "forum"
+            ? forumTarget
+            : positional[0] || ""),
     title:
       String(
         raw.title ||
@@ -2562,12 +2664,15 @@ 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>]
   lumine upgrade [twinkle-build-url-or-id]
   lumine projects
   lumine branches [twinkle-build-url-or-id] [--limit <n>]
+  lumine forum [read] [twinkle-build-url-or-id] [--cursor <sequence>] [--json]
+  lumine forum listen [twinkle-build-url-or-id] [--cursor <sequence>] [--poll-ms <ms>] [--json]
   lumine suggest branch [message] [--target <twinkle-branch-url>]
   lumine suggest thumbnail [--target <twinkle-branch-url>]
   lumine suggestions [twinkle-build-url-or-id]
@@ -2607,23 +2712,26 @@ export function printHelp() {
   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 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]
@@ -2631,8 +2739,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
@@ -2645,6 +2756,8 @@ Examples:
   npx @stage5/lumine@latest upgrade https://www.twin-kle.com/app/123
   npx @stage5/lumine@latest new --title "Daily Reflection App" --description "Private journal with streaks"
   npx @stage5/lumine@latest branches 884
+  npx @stage5/lumine@latest forum 884 --json
+  npx @stage5/lumine@latest forum listen --json
   npx @stage5/lumine@latest suggest branch "Ready for review"
   npx @stage5/lumine@latest suggest thumbnail
   npx @stage5/lumine@latest suggestions 884
@@ -2661,6 +2774,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
@@ -2688,6 +2803,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>
@@ -2696,8 +2815,23 @@ Options:
   --no-description      Skip New description or clear with describe
   --summary <text>      Save summary
   --note <text>         Suggestion, notable-user, or AI-bucket context
-  --cursor <id>         Continue an owner suggestion inbox listing
-  --after <date>        Admin subjects: inclusive Unix/ISO creation boundary
+  --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
+  --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

@@ -168,6 +168,17 @@ lumine save --summary "Describe the change"
   need --allow-write and mutate real app data.
 - Owned canonical builds may be published only when the user explicitly asks.
 
+## Team Forum
+
+- Before starting team-project work, run \`lumine forum --json\` and read every
+  canonical post and reply returned for this workspace. Main owners receive
+  Main plus all branch activity; branch contributors receive their branch plus
+  every project-owner post and reply on Main.
+- During longer collaborative work, keep \`lumine forum listen --json\` open in
+  a separate terminal. It resumes only from server-confirmed cursors and emits
+  complete canonical update batches. Do not infer teammate intent from stale
+  files or local state when the Forum provides the current instruction.
+
 ## Team Suggestions
 
 - After saving contribution-branch work, use \`lumine suggest branch "Ready for review"\`
@@ -319,6 +330,7 @@ export const MAIN_CHECKOUT_READONLY_COMMANDS = new Set([
   "pull",
   "check",
   "branches",
+  "forum",
   "diff",
   "sdk",
   "select",
@@ -331,6 +343,8 @@ export const MAIN_CHECKOUT_READONLY_COMMANDS = new Set([
 ]);
 export const COMMANDS = new Set([
   "admin",
+  "agent",
+  "agent-mcp",
   "workspace",
   "login",
   "logout",
@@ -341,6 +355,7 @@ export const COMMANDS = new Set([
   "upgrade",
   "projects",
   "branches",
+  "forum",
   "suggest",
   "suggestions",
   "explore",