@stage5/lumine 0.2.39 → 0.2.41

package/README.md

@@ -14,6 +14,8 @@ npx @stage5/lumine@latest describe --no-description --target 123
 npx @stage5/lumine@latest upgrade https://www.twin-kle.com/app/123
 npx @stage5/lumine@latest projects
 npx @stage5/lumine@latest branches 884
+npx @stage5/lumine@latest forum 884 --json
+npx @stage5/lumine@latest forum listen 884 --json
 npx @stage5/lumine@latest suggestions 884
 npx @stage5/lumine@latest explore --sort forks
 npx @stage5/lumine@latest reference https://www.twin-kle.com/app/123
@@ -58,6 +60,16 @@ Use `lumine branches <build-url-or-id>` to list the contribution branches you
 can review, including each contributor, branch number, status, and URL. Then use
 `lumine diff <branch-url>` to inspect one branch.
 
+Use `lumine forum [build-url-or-id]` to read the complete canonical Team Forum
+history visible to the current workspace. A project owner reading Main receives
+Main plus every branch's posts and replies. A branch contributor receives that
+branch plus every project-owner post and reply on Main, including older Main
+threads that were not separately broadcast. `--json` returns one complete
+snapshot. `lumine forum listen --json` then polls from the last server-confirmed
+sequence and emits newline-delimited update batches without advancing through a
+partial or failed read. Pass `--cursor <sequence>` only when intentionally
+resuming a previously confirmed cursor; the default starts at the beginning.
+
 Branch contributors can nudge the project owner from their pulled branch with
 `lumine suggest branch [message]` or `lumine suggest thumbnail`. The thumbnail
 command offers the thumbnail currently saved on that branch. Project owners can
@@ -152,7 +164,35 @@ version state in `.twinkle/lumine-project.json` so local agents can tell when
 they should rerun with `npx @stage5/lumine@latest`. Use `--no-update-check` to
 skip that advisory network check.
 
-After pulling a project, run an agent from the pulled folder:
+## Subscription agents through the Lumine loop
+
+After pulling a project, a signed-in Codex or Claude Code subscription can
+power Lumine's workspace loop without spending Twinkle AI Energy:
+
+```bash
+lumine agent --provider codex "Add keyboard controls"
+lumine agent --provider claude-code "Fix the mobile layout"
+```
+
+The external model cannot write project files directly. Lumine supplies the
+same core workspace prompt/tool contract, read-before-edit behavior, bounded
+scope checks, and validation-repair passes used by the hosted Build agent. A save happens only
+after validation passes and still uses the workspace's server-issued
+`filesHash`, so a concurrent server change stops the run instead of being
+overwritten. Provider login and model usage stay inside the selected local CLI;
+Twinkle never receives a provider credential and does not reserve AI Energy.
+
+Every run writes a sanitized observable tool trace under
+`.twinkle/agent-runs/`. By default, the selected subscription agent reviews
+that trace after the pass and records evidence-based loop feedback without
+collecting hidden chain-of-thought; use `--no-review-loop` to skip that extra
+provider turn. Provider support is adapter-based rather than Codex-specific.
+Codex uses its local app-server protocol and Claude Code uses the same Lumine
+tools over MCP. Both adapters disable inherited model-side project tooling and
+launch with a credential-minimized environment, so project access remains at
+the Lumine tool boundary.
+
+You can still use a coding agent directly for a manual edit-and-save workflow:
 
 ```bash
 codex "Read AGENTS.md, then make the requested change."
@@ -175,10 +215,13 @@ events.
 ```bash
 lumine admin identity list --json
 lumine admin daily-run start --identity auto --comment-mode off --json
-lumine admin recommendations list --cursor '<cursor>' --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
 lumine admin subjects candidates --after 2026-08-01T00:00:00Z --json
 lumine admin subjects candidates --effort unassigned --json
-lumine admin builds candidates --cursor '<cursor>' --json
+lumine admin builds candidates --all --json
+lumine admin builds review build:884 --output-dir ./build-review --json
 lumine admin subject get 123 --include-comments --json
 lumine admin post get https://www.twin-kle.com/ai-stories/88 --json
 lumine admin post comments dailyReflection:99 --json
@@ -194,9 +237,16 @@ lumine admin brief --days 3 --json
 lumine admin notable add Minecrarft_guy --note "Created 8 thoughtful subjects and helped peers in 23 comments this window." --json
 lumine admin post recommend comment:456 --anyone-can-reward --reward-twinkles 3 --json
 lumine admin post reward comment:456 --twinkles 3 --json
+lumine admin post skip-batch --target-file skipped.json --checkpoint skip-progress.json --json
 lumine admin comment draft build:884 --file comment.md \
-  --reviewed-version 4512 --reviewed-via runtime --json
+  --review-receipt /path/from-build-review/review.json --json
 lumine admin comment post --draft-id 77 --json
+lumine admin news claim --output claim.json --scaffold editorial.json --json
+lumine admin news validate --claim claim.json --file editorial.json --json
+lumine admin news submit --claim claim.json --file editorial.json --json
+lumine admin daily-run escalation add --target subject:123 \
+  --note "Concrete privacy issue requiring owner review" --json
+lumine admin daily-run report --json
 lumine admin daily-run complete --json
 ```
 
@@ -209,11 +259,15 @@ reply is handled by Twinkle's existing autonomous Zero/Ciel responder without
 Lumine remaining active.
 
 Management agents also inspect recent public Build candidates during each run.
-A direct Build comment is never server-generated: first open and try the
-published app or pull and read its code, then compose with `--file` and bind
-the draft to the exact `publishedArtifactVersionId` using
-`--reviewed-version` and `--reviewed-via runtime|code`. The server rejects
-missing or stale review evidence and any app/thread change before publication.
+`builds review` opens one published app in an isolated temporary Chromium
+profile, captures a screenshot and console evidence, verifies that the
+published version stayed fixed, and writes a review receipt in a unique output
+subdirectory. A direct Build comment is never server-generated: review the
+runtime (or pull and read an
+open-source app), compose with `--file`, and attach the receipt. The server
+rejects missing or stale review evidence and any app/thread change before
+publication. Manual `--reviewed-version` / `--reviewed-via` evidence remains
+available for genuine code reviews.
 
 Every operation is noninteractive when its required arguments are present.
 `--json` prints exactly one uncolored JSON value and returns a nonzero status
@@ -223,10 +277,21 @@ server also enforces canonical no-duplicate invariants. Failed mutation JSON
 includes `error.details.retryIdempotencyKey` so a partial attempt can be
 resumed with the exact generated key.
 
-Subject and recommendation-queue listings use opaque, stable snapshot cursors.
-Pass the returned `data.pagination.nextCursor` back through `--cursor` until
-`data.pagination.exhausted` is true. Subject `--after` is inclusive and cursors
-are bound to the original date and effort filters.
+Subject and queue listings use opaque, stable snapshot cursors. `--all`
+follows them automatically, saves a checkpoint after every canonical page,
+and records completed queue coverage in the run audit; `--resume` continues
+the exact same request. Recommendation scans default to the previous completed
+run's start boundary for at-least-once coverage. Use `--after` for an explicit
+timestamp or `--include-legacy`
+for an intentional all-history scan. Subject `--after` is inclusive and
+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 complete run lifecycle, command contracts, nullable fields, Karma approval
 behavior, pagination semantics, secret-subject behavior, presence isolation,

package/lib/admin-news.js

@@ -0,0 +1,236 @@
+import {
+  chmodSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  writeFileSync,
+} from "node:fs";
+import path from "node:path";
+
+const MAX_ADMIN_JSON_BYTES = 2 * 1024 * 1024;
+
+function validationError(message) {
+  const error = new Error(message);
+  error.code = "CLI_ADMIN_CLI_VALIDATION";
+  return error;
+}
+
+function formatByteLimit(maxBytes) {
+  const megabytes = maxBytes / (1024 * 1024);
+  return Number.isInteger(megabytes)
+    ? `${megabytes} MB`
+    : `${maxBytes} bytes`;
+}
+
+export function readAdminJsonFile(
+  filePath,
+  label = "JSON file",
+  { maxBytes = MAX_ADMIN_JSON_BYTES } = {},
+) {
+  const normalizedPath = String(filePath || "").trim();
+  if (!normalizedPath) throw validationError(`Pass ${label}.`);
+  let contents;
+  try {
+    contents = readFileSync(normalizedPath, "utf8");
+  } catch {
+    throw validationError(`Could not read ${normalizedPath}.`);
+  }
+  if (Buffer.byteLength(contents, "utf8") > maxBytes) {
+    throw validationError(`${label} must be under ${formatByteLimit(maxBytes)}.`);
+  }
+  try {
+    return JSON.parse(contents);
+  } catch {
+    throw validationError(`${normalizedPath} is not valid JSON.`);
+  }
+}
+
+export function writeAdminJsonFile(
+  filePath,
+  value,
+  { privateFile = false, maxBytes = null } = {},
+) {
+  const resolved = path.resolve(String(filePath || "").trim());
+  if (!String(filePath || "").trim()) {
+    throw validationError("An output file path is required.");
+  }
+  mkdirSync(path.dirname(resolved), { recursive: true });
+  const temporary = `${resolved}.tmp-${process.pid}`;
+  const contents = `${JSON.stringify(value, null, 2)}\n`;
+  if (
+    Number.isSafeInteger(maxBytes) &&
+    maxBytes > 0 &&
+    Buffer.byteLength(contents, "utf8") > maxBytes
+  ) {
+    throw validationError(
+      `The output exceeds the ${formatByteLimit(maxBytes)} safety limit. Narrow the request before retrying.`,
+    );
+  }
+  writeFileSync(temporary, contents, {
+    encoding: "utf8",
+    mode: privateFile ? 0o600 : 0o644,
+  });
+  renameSync(temporary, resolved);
+  if (privateFile) chmodSync(resolved, 0o600);
+  return resolved;
+}
+
+export function extractNewsClaim(value) {
+  const claim = value?.claim || value?.data?.claim || value;
+  if (!claim || typeof claim !== "object" || Array.isArray(claim)) {
+    throw validationError("The claim file does not contain a newspaper claim.");
+  }
+  const editionId = Number(claim.editionId || 0);
+  const leaseToken = String(claim.leaseToken || "").trim();
+  const events = Array.isArray(claim.events) ? claim.events : null;
+  if (!Number.isSafeInteger(editionId) || editionId <= 0 || !leaseToken || !events) {
+    throw validationError(
+      "The claim file is missing editionId, leaseToken, or canonical events.",
+    );
+  }
+  return { ...claim, editionId, leaseToken, events };
+}
+
+function exactQuoteFromSummary(summary, maximum) {
+  return String(summary || "").slice(0, Math.max(0, maximum));
+}
+
+function scaffoldStory(event, maximum) {
+  return {
+    eventKey: String(event.eventKey || ""),
+    headline: "",
+    summary: "",
+    sourceQuote:
+      String(event.section || "") === "front"
+        ? exactQuoteFromSummary(event.summary, maximum)
+        : "",
+    coveredEventKeys: [],
+  };
+}
+
+export function createNewsEditorialScaffold(claimValue) {
+  const claim = extractNewsClaim(claimValue);
+  const maximum = Math.max(0, Number(claim.maxSourceQuoteLength || 360));
+  const frontIndex = claim.events.findIndex(
+    (event) => String(event?.section || "") === "front",
+  );
+  const lead = frontIndex >= 0 ? scaffoldStory(claim.events[frontIndex], maximum) : null;
+  const stories = claim.events
+    .filter((_event, index) => index !== frontIndex)
+    .map((event) => scaffoldStory(event, maximum));
+  return {
+    mastheadHeadline: "",
+    mastheadDeck: "",
+    ...(lead ? { lead } : {}),
+    stories,
+    editorsNote: "",
+  };
+}
+
+function requireEditorialText(value, label) {
+  if (typeof value !== "string" || !value.trim()) {
+    throw validationError(`${label} must be non-empty text.`);
+  }
+}
+
+export function validateNewsEditorial({ claim: claimValue, editorial }) {
+  const claim = extractNewsClaim(claimValue);
+  if (!editorial || typeof editorial !== "object" || Array.isArray(editorial)) {
+    throw validationError("The editorial must be a JSON object.");
+  }
+  requireEditorialText(editorial.mastheadHeadline, "mastheadHeadline");
+  requireEditorialText(editorial.mastheadDeck, "mastheadDeck");
+  requireEditorialText(editorial.editorsNote, "editorsNote");
+  if (!Array.isArray(editorial.stories)) {
+    throw validationError("stories must be an array.");
+  }
+  const eventByKey = new Map(
+    claim.events.map((event) => [String(event?.eventKey || ""), event]),
+  );
+  const usedKeys = new Set();
+  const maximum = Math.max(0, Number(claim.maxSourceQuoteLength || 360));
+  const entries = [
+    ...(editorial.lead ? [{ label: "lead", story: editorial.lead, lead: true }] : []),
+    ...editorial.stories.map((story, index) => ({
+      label: `stories[${index}]`,
+      story,
+      lead: false,
+    })),
+  ];
+  for (const entry of entries) {
+    const story = entry.story;
+    if (!story || typeof story !== "object" || Array.isArray(story)) {
+      throw validationError(`${entry.label} must be an object.`);
+    }
+    const eventKey = String(story.eventKey || "").trim();
+    const event = eventByKey.get(eventKey);
+    if (!event) throw validationError(`${entry.label}.eventKey is not in the claim.`);
+    if (usedKeys.has(eventKey)) {
+      throw validationError(`${eventKey} is cited or covered more than once.`);
+    }
+    usedKeys.add(eventKey);
+    if (entry.lead && String(event.section || "") !== "front") {
+      throw validationError("The lead must cite a front-section event.");
+    }
+    requireEditorialText(story.headline, `${entry.label}.headline`);
+    requireEditorialText(story.summary, `${entry.label}.summary`);
+    const quote = typeof story.sourceQuote === "string" ? story.sourceQuote : "";
+    if (String(event.section || "") === "front") {
+      const canonicalSummary = String(event.summary || "");
+      const quoteIsValid = canonicalSummary
+        ? Boolean(
+            quote &&
+              quote.length <= maximum &&
+              canonicalSummary.includes(quote),
+          )
+        : quote === "";
+      if (!quoteIsValid) {
+        throw validationError(
+          `${entry.label}.sourceQuote must be an exact contiguous claim-summary passage no longer than ${maximum} characters.`,
+        );
+      }
+    } else if (quote !== "") {
+      throw validationError(`${entry.label}.sourceQuote must be empty outside the front section.`);
+    }
+    const covered = story.coveredEventKeys ?? [];
+    if (!Array.isArray(covered)) {
+      throw validationError(`${entry.label}.coveredEventKeys must be an array.`);
+    }
+    for (const rawCoveredKey of covered) {
+      const coveredKey = String(rawCoveredKey || "").trim();
+      if (!eventByKey.has(coveredKey)) {
+        throw validationError(`${entry.label} covers an eventKey not in the claim.`);
+      }
+      if (coveredKey === eventKey || usedKeys.has(coveredKey)) {
+        throw validationError(`${coveredKey} is cited or covered more than once.`);
+      }
+      usedKeys.add(coveredKey);
+    }
+  }
+  return {
+    valid: true,
+    editionId: claim.editionId,
+    citedEventCount: entries.length,
+    coveredEventCount: usedKeys.size - entries.length,
+    availableEventCount: claim.events.length,
+  };
+}
+
+export function writeNewsClaimArtifacts({ result, outputPath, scaffoldPath }) {
+  const claim = result?.data?.claim || null;
+  const artifacts = { claimFile: null, scaffoldFile: null };
+  if (outputPath) {
+    artifacts.claimFile = writeAdminJsonFile(
+      outputPath,
+      { schemaVersion: 1, savedAt: new Date().toISOString(), claim },
+      { privateFile: true },
+    );
+  }
+  if (scaffoldPath && claim) {
+    artifacts.scaffoldFile = writeAdminJsonFile(
+      scaffoldPath,
+      createNewsEditorialScaffold(claim),
+    );
+  }
+  return artifacts;
+}