@stage5/lumine 0.2.65 → 0.2.66

package/README.md

@@ -350,6 +350,7 @@ lumine admin economy trace lock --days 3 \
 lumine admin rescue wordle-audit --days 30 \
   --reason "Identify recorded Wordle breaks and rescue status" --json
 lumine admin daily-run start --identity auto --comment-mode off --json
+lumine admin daily-run start --scope featured --identity auto --json
 lumine admin sponsor applications list --status pending --json
 lumine admin sponsor applications review 12 --decision approve \
   --note "Approved for probationary duty" --json
@@ -378,6 +379,9 @@ lumine admin subject reveal 123 --json
 lumine admin subject effort set 123 --level 3 --json
 lumine admin subject creator set-made-by-poster 123 --json
 lumine admin featured list --json
+lumine admin featured history --subject-ids 50,40 --all --json
+lumine admin featured add --subject-ids 50,40 \
+  --posted-after 2026-08-27T00:00:00+07:00 --json
 lumine admin subject feature 123 --json
 lumine admin subject unfeature 123 --json
 lumine admin featured reorder --subject-ids 30,20,10 --json
@@ -412,7 +416,19 @@ and posts use the selected bot's server-owned canonical persona. Outside Build
 threads, a later human reply is handled by Twinkle's existing autonomous
 Zero/Ciel responder without Lumine remaining active.
 
-Management agents also inspect recent public Build candidates during each run.
+`--scope full` is the default and authorizes the complete daily-management
+workflow. `--scope featured` is a deliberately narrow run for a requested
+Featured-only slice: it cannot comment, does not surface carry-over todos, does
+not write full-run queue coverage, does not require sponsor review, and never
+advances full-run review windows. Its dedicated start endpoint also prevents an
+older API from silently interpreting it as a full run. The
+atomic `featured add` verb preserves the supplied relevance order and requires
+the server to prove both a strict posting-date boundary and complete
+never-Featured history. `featured history` returns that evidence without the
+large repeated board snapshots in the general audit trail.
+
+Management agents also inspect recent public Build candidates during each full
+daily review.
 `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
@@ -451,6 +467,9 @@ follows them automatically, fsyncs each confirmed page to a private NDJSON
 candidate spool, saves only bounded cursor/boundary/count metadata in the
 checkpoint, and records completed queue coverage in the run audit; `--resume`
 verifies the confirmed spool prefix and continues the exact same request. The
+automatic checkpoint name includes the exact request fingerprint (including
+client-side view filters and result-transform inputs), and an
+exclusive adjacent lock prevents concurrent processes from sharing it. The
 final JSON contract still contains the complete collection, streamed from the
 spool instead of accumulated in memory. With `--all --json`, bounded progress
 goes to stderr so stdout remains one pipe-safe JSON value. Recommendation scans default to the previous completed
@@ -462,7 +481,7 @@ 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. Every `daily-run start` response includes writer-confirmed
+the claim file. Every full `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
@@ -470,7 +489,7 @@ 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, sponsor-integrity state, and the run brief before the run is
-completed. A run cannot complete until its bounded sponsor-integrity snapshot
+completed. A full run cannot complete until its bounded sponsor-integrity snapshot
 has been scanned and every selected case is cleared or disqualified. `hold` and
 `flag` deliberately keep the run open for human judgment; scans never suspend,
 revoke, or disqualify a sponsor automatically.

package/lib/admin-workflows.js

@@ -3,7 +3,9 @@ import {
   chmodSync,
   closeSync,
   createReadStream,
+  fchmodSync,
   fsyncSync,
+  linkSync,
   lstatSync,
   mkdirSync,
   openSync,
@@ -74,9 +76,198 @@ function pathWithCursor(requestPath, cursor) {
   return `${url.pathname}${url.search}`;
 }
 
-function defaultCheckpointPath({ runId, operationName }) {
+function defaultCheckpointPath({
+  runId,
+  operationName,
+  operationFingerprint = "",
+}) {
   const safeName = String(operationName).replace(/[^a-z0-9_.-]+/gi, "-");
-  return path.join(os.tmpdir(), `lumine-admin-run-${runId}-${safeName}.json`);
+  const fingerprintSuffix = operationFingerprint
+    ? `-${operationFingerprint}`
+    : "";
+  return path.join(
+    os.tmpdir(),
+    `lumine-admin-run-${runId}-${safeName}${fingerprintSuffix}.json`,
+  );
+}
+
+function resolveAutomaticCheckpointPath({
+  options,
+  operation,
+  runId,
+  operationFingerprint,
+}) {
+  if (String(options.adminCheckpoint || "").trim()) {
+    return path.resolve(options.adminCheckpoint);
+  }
+  const keyedPath = defaultCheckpointPath({
+    runId,
+    operationName: operation.name,
+    operationFingerprint,
+  });
+  if (
+    options.adminResume &&
+    !pathEntryExists(keyedPath) &&
+    !pathEntryExists(`${keyedPath}.lock`) &&
+    !pathEntryExists(`${keyedPath}.lock.reclaim`)
+  ) {
+    const legacyPath = defaultCheckpointPath({
+      runId,
+      operationName: operation.name,
+    });
+    if (pathEntryExists(legacyPath)) return legacyPath;
+  }
+  return keyedPath;
+}
+
+function pathEntryExists(filePath) {
+  try {
+    lstatSync(filePath);
+    return true;
+  } catch (error) {
+    if (error?.code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+function acquireCheckpointLock(checkpointPath, operationFingerprint) {
+  const lockPath = `${checkpointPath}.lock`;
+  const reclaimPath = `${lockPath}.reclaim`;
+  mkdirSync(path.dirname(lockPath), { recursive: true });
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    if (pathEntryExists(reclaimPath)) {
+      throw validationError(
+        `Another Lumine admin scan is recovering checkpoint ${checkpointPath}. Wait for it to finish or choose a different --checkpoint.`,
+      );
+    }
+    const token = randomUUID();
+    let descriptor;
+    let ownsLock = false;
+    try {
+      descriptor = openSync(lockPath, "wx", 0o600);
+      ownsLock = true;
+      fchmodSync(descriptor, 0o600);
+      writeFileSync(
+        descriptor,
+        `${JSON.stringify({
+          kind: "admin-pagination-lock",
+          pid: process.pid,
+          token,
+          operationFingerprint,
+          createdAt: new Date().toISOString(),
+        })}\n`,
+      );
+      fsyncSync(descriptor);
+      closeSync(descriptor);
+      descriptor = undefined;
+      // A stale-lock reclaimer can begin after the check above but before this
+      // O_EXCL create. It hard-links the exact old inode before removal. If
+      // that claim still exists, relinquish our new lock rather than allowing
+      // two owners to cross during the handoff.
+      if (pathEntryExists(reclaimPath)) {
+        releaseCheckpointLock({ lockPath, token });
+        ownsLock = false;
+        throw validationError(
+          `Another Lumine admin scan is recovering checkpoint ${checkpointPath}. Retry after it finishes.`,
+        );
+      }
+      return { lockPath, token };
+    } catch (error) {
+      if (descriptor !== undefined) {
+        try {
+          closeSync(descriptor);
+        } catch {
+          // The failed lock initialization may already have closed it.
+        }
+      }
+      if (ownsLock) {
+        try {
+          unlinkSync(lockPath);
+        } catch {
+          // A failed initialization may leave no owned lock to remove.
+        }
+      }
+      if (error?.code !== "EEXIST") throw error;
+      if (attempt > 0 || !removeDeadCheckpointLock(lockPath)) {
+        throw validationError(
+          `Another Lumine admin scan owns checkpoint ${checkpointPath}. Wait for it to finish or choose a different --checkpoint.`,
+        );
+      }
+    }
+  }
+  throw validationError(
+    `Could not acquire the pagination checkpoint lock for ${checkpointPath}.`,
+  );
+}
+
+function removeDeadCheckpointLock(lockPath) {
+  const reclaimPath = `${lockPath}.reclaim`;
+  let ownsReclaim = false;
+  try {
+    // Creating a fixed-name hard link is an atomic claim on the exact lock
+    // inode. It serializes reclaimers and lets us prove we are not unlinking a
+    // replacement lock created after another process removed the stale one.
+    linkSync(lockPath, reclaimPath);
+    ownsReclaim = true;
+    const fileState = lstatSync(reclaimPath);
+    if (!fileState.isFile() || fileState.isSymbolicLink()) return false;
+    if (fileState.size > 16 * 1024) return false;
+    const state = JSON.parse(readFileSync(reclaimPath, "utf8"));
+    if (
+      state?.kind !== "admin-pagination-lock" ||
+      !/^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/i.test(
+        String(state?.token || ""),
+      ) ||
+      !/^[a-f0-9]{64}$/i.test(String(state?.operationFingerprint || ""))
+    ) {
+      return false;
+    }
+    const pid = Number(state?.pid);
+    if (!Number.isSafeInteger(pid) || pid <= 0) return false;
+    try {
+      process.kill(pid, 0);
+      return false;
+    } catch (error) {
+      if (error?.code !== "ESRCH") return false;
+    }
+    const claimedState = lstatSync(reclaimPath);
+    const currentState = lstatSync(lockPath);
+    if (
+      claimedState.dev !== currentState.dev ||
+      claimedState.ino !== currentState.ino
+    ) {
+      return false;
+    }
+    unlinkSync(lockPath);
+    return true;
+  } catch {
+    return false;
+  } finally {
+    if (ownsReclaim) {
+      try {
+        unlinkSync(reclaimPath);
+      } catch {
+        // A failed or completed reclaim leaves the current lock untouched.
+      }
+    }
+  }
+}
+
+function releaseCheckpointLock(lock) {
+  try {
+    const fileState = lstatSync(lock.lockPath);
+    if (!fileState.isFile() || fileState.isSymbolicLink()) return;
+    const saved = JSON.parse(readFileSync(lock.lockPath, "utf8"));
+    if (saved?.token === lock.token && Number(saved?.pid) === process.pid) {
+      unlinkSync(lock.lockPath);
+    }
+  } catch (error) {
+    if (error?.code !== "ENOENT") {
+      process.stderr.write(
+        `Lumine admin: could not release pagination lock ${lock.lockPath} (${error?.message || error}).\n`,
+      );
+    }
+  }
 }
 
 function operationFingerprintValue({
@@ -91,6 +282,13 @@ function operationFingerprintValue({
     apiUrl: String(options.apiUrl || "").replace(/\/$/, ""),
     name: operation.name,
     path: pathWithCursor(operation.path, ""),
+    ...(operation.name === "builds.candidates"
+      ? {
+          resultTransform: {
+            siteUrl: String(options.siteUrl || "").replace(/\/$/, ""),
+          },
+        }
+      : {}),
     pagination: {
       collectionKey: operation.pagination.collectionKey,
       coverageQueue: operation.pagination.coverageQueue || null,
@@ -604,22 +802,46 @@ function aggregatePageResult({ operation, lastPage, checkpointPath, state }) {
   });
 }
 
-export async function runAutomaticPagination({
+export async function runAutomaticPagination(args) {
+  const { options, operation, runId } = args;
+  if (!operation.pagination) {
+    throw validationError("--all is supported only by paginated admin listings.");
+  }
+  const operationFingerprint = operationFingerprintValue({
+    schemaVersion: ADMIN_PAGINATION_SCHEMA_VERSION,
+    options,
+    operation,
+    runId,
+  });
+  const checkpointPath = resolveAutomaticCheckpointPath({
+    options,
+    operation,
+    runId,
+    operationFingerprint,
+  });
+  const lock = acquireCheckpointLock(checkpointPath, operationFingerprint);
+  try {
+    return await runAutomaticPaginationWithLock({
+      ...args,
+      checkpointPath,
+      operationFingerprint,
+    });
+  } finally {
+    releaseCheckpointLock(lock);
+  }
+}
+
+async function runAutomaticPaginationWithLock({
   options,
   operation,
   runId,
+  checkpointPath,
+  operationFingerprint,
   fetchPage,
   transformPage,
   recordCoverage,
   reportProgress = (message) => process.stderr.write(`${message}\n`),
 }) {
-  if (!operation.pagination) {
-    throw validationError("--all is supported only by paginated admin listings.");
-  }
-  const checkpointPath = path.resolve(
-    options.adminCheckpoint ||
-      defaultCheckpointPath({ runId, operationName: operation.name }),
-  );
   const requestedOutputPath = String(options.adminOutput || "").trim();
   if (options.adminOutput && !requestedOutputPath) {
     throw validationError("An output file path is required.");
@@ -632,12 +854,6 @@ export async function runAutomaticPagination({
       "The pagination checkpoint and result output must use different files.",
     );
   }
-  const operationFingerprint = operationFingerprintValue({
-    schemaVersion: ADMIN_PAGINATION_SCHEMA_VERSION,
-    options,
-    operation,
-    runId,
-  });
   const legacyOperationFingerprint = operationFingerprintValue({
     schemaVersion: LEGACY_ADMIN_PAGINATION_SCHEMA_VERSION,
     options,