@stage5/lumine 0.3.4 → 0.3.6

package/bin/lumine.js

@@ -2,11 +2,15 @@
 import { main } from "../lib/commands.js";
 import { formatAdminJsonError, isAdminJsonInvocation } from "../lib/admin.js";
 
-main().catch((error) => {
+try {
+  // Node exits nonzero when top-level await cannot finish, instead of silently
+  // treating an unfinished command with no remaining handles as exit 0.
+  await main();
+} catch (error) {
   if (isAdminJsonInvocation(process.argv.slice(2))) {
     console.log(JSON.stringify(formatAdminJsonError(error)));
   } else {
     console.error(`lumine: ${error?.message || error}`);
   }
   process.exitCode = 1;
-});
+}

package/lib/admin-daily.js

@@ -3,6 +3,11 @@ import path from "path";
 import http from "http";
 import { spawn, spawnSync } from "child_process";
 import { fileURLToPath } from "url";
+import { randomUUID } from "node:crypto";
+import { adminWorkDirectory } from "./admin-work-directory.js";
+import { readAdminJsonFile, writeAdminJsonFile } from "./admin-news.js";
+import { createDailyReviewState, dailyRunProgress } from "./admin-duties.js";
+export { dailyRunProgress };
 
 // Multi-step conveniences for the full daily management run. Each one runs
 // the ordinary `lumine admin` commands as child processes, so pagination,
@@ -14,10 +19,16 @@ const MARKED_ASSET = fileURLToPath(
   new URL("./report-assets/marked.min.js", import.meta.url),
 );
 
-function runAdmin(args, { outputFile, extraEnv } = {}) {
-  const full = ["admin", ...args, "--json"];
-  if (outputFile) full.push("--output", outputFile);
-  const result = spawnSync(process.execPath, [LUMINE_BIN, ...full], {
+export function runAdmin(
+  args,
+  { outputFile, extraEnv, retryRead = false, spawnImpl = spawnSync } = {},
+) {
+  const attemptFile = outputFile
+    ? `${outputFile}.attempt-${randomUUID()}.json`
+    : null;
+  const full = ["admin", ...args, "--json", "--no-update-check"];
+  if (attemptFile) full.push("--output", attemptFile);
+  const result = spawnImpl(process.execPath, [LUMINE_BIN, ...full], {
     encoding: "utf8",
     maxBuffer: 256 * 1024 * 1024,
     env: { ...process.env, ...(extraEnv || {}) },
@@ -28,10 +39,72 @@ function runAdmin(args, { outputFile, extraEnv } = {}) {
   } catch {
     parsed = null;
   }
+  let error = null;
+  if (!parsed || typeof parsed !== "object" || typeof parsed.ok !== "boolean" || typeof parsed.status !== "string") {
+    error = {
+      code: "CLI_ADMIN_OUTPUT_INVALID",
+      message: "The child did not return a valid admin JSON receipt.",
+    };
+  } else if (attemptFile && result.status === 0 && parsed.ok === true) {
+    try {
+      const saved = JSON.parse(fs.readFileSync(attemptFile, "utf8"));
+      if (JSON.stringify(saved) !== JSON.stringify(parsed))
+        throw new Error("mismatch");
+      if (parsed.data?.scan?.outputPath === attemptFile)
+        parsed.data.scan.outputPath = outputFile;
+      writeAdminJsonFile(outputFile, parsed, { privateFile: true });
+      fs.unlinkSync(attemptFile);
+    } catch {
+      error = {
+        code: "CLI_ADMIN_OUTPUT_MISSING",
+        message: "The child did not save the matching JSON receipt.",
+      };
+    }
+  }
+  const ok =
+    result.status === 0 && parsed?.ok === true && !error && !result.error;
+  const reads = {
+    "energy-budget": [null],
+    news: [null],
+    brief: [null],
+    "ai-costs": ["monthly", "day"],
+    "media-costs": ["monthly"],
+    "reward-activity": [null],
+    "reward-review": ["list"],
+    todo: ["list"],
+    escalation: ["list"],
+    featured: ["list", "history"],
+    sponsor: ["applications"],
+    "bot-output": [null],
+    subjects: ["candidates"],
+    subject: ["get"],
+  };
+  const subcommand = args[1]?.startsWith("--") ? null : (args[1] ?? null);
+  const readOnly =
+    reads[args[0]]?.includes(subcommand) &&
+    (args[0] !== "sponsor" || args[2] === "list");
+  // Only explicitly opted-in read collections retry an unconfirmed result.
+  // Mutation recovery keeps its original idempotency key and lease instead.
+  const transient =
+    error ||
+    result.error ||
+    result.signal ||
+    parsed?.error?.code === "lumine_http_invalid_response";
+  if (!ok && retryRead && readOnly && transient) {
+    const retried = runAdmin(args, { outputFile, extraEnv, spawnImpl });
+    return {
+      ...retried,
+      attempts: 2,
+      recovered: retried.ok,
+      firstError:
+        error || parsed?.error || String(result.error || result.signal),
+    };
+  }
   return {
-    ok: result.status === 0 && parsed?.ok !== false,
+    ok,
+    attempts: 1,
     status: result.status,
-    json: parsed,
+    json: error ? { ok: false, status: "unconfirmed", error } : parsed,
     stderr: String(result.stderr || "").slice(-2000),
   };
 }
@@ -91,11 +164,13 @@ export async function dailyRunGather(options) {
   const steps = [];
   const step = (name, args, file) => {
     const outputFile = path.join(dir, file);
-    const res = runAdmin(args, { outputFile });
+    const res = runAdmin(args, { outputFile, retryRead: true });
     steps.push({
       name,
       file,
       ok: res.ok,
+      attempts: res.attempts,
+      recovered: Boolean(res.recovered),
       ...(res.ok ? {} : { error: res.json?.error || res.stderr }),
     });
     return res;
@@ -175,6 +250,15 @@ export async function dailyRunGather(options) {
     JSON.stringify(summary, null, 2),
     { mode: 0o600 },
   );
+  // Collection never acknowledges reading or completes an editorial duty.
+  const reviewStateFile = path.join(dir, "review-state.json");
+  const previousReviewState = fs.existsSync(reviewStateFile)
+    ? readAdminJsonFile(reviewStateFile, "the previous review state") : {};
+  writeAdminJsonFile(
+    reviewStateFile,
+    createDailyReviewState(dir, summary, previousReviewState),
+    { privateFile: true },
+  );
   return {
     ok: summary.failed.length === 0,
     status: summary.failed.length ? "partial_failure" : "success",
@@ -188,20 +272,26 @@ export async function featuredCandidates(options) {
   const days = Math.max(1, Math.min(30, Number(options.adminDays || 7)));
   const after = options.adminAfter || bangkokCutoff(days);
   const scratch = ensureDir(
-    path.resolve(options.adminOutputDir || fs.mkdtempSync(path.join(process.env.TMPDIR || "/tmp", "lumine-featured-"))),
+    path.resolve(
+      options.adminOutputDir ||
+        fs.mkdtempSync(path.join(adminWorkDirectory(), "featured-")),
+    ),
   );
   const subjects = runAdmin(
     ["subjects", "candidates", "--after", after, "--all"],
-    { outputFile: path.join(scratch, "subjects.json") },
+    { outputFile: path.join(scratch, "subjects.json"), retryRead: true },
   );
   if (!subjects.ok) throw new Error(`subjects candidates failed: ${JSON.stringify(subjects.json?.error || subjects.stderr)}`);
-  const board = runAdmin(["featured", "list"]);
+  const board = runAdmin(["featured", "list"], { retryRead: true });
   if (!board.ok) throw new Error("featured list failed");
   const onBoard = new Set((board.json.data.subjects || []).map((s) => s.id));
   const recent = (subjects.json.data.subjects || []).filter((s) => !onBoard.has(s.id));
   const ids = recent.map((s) => s.id);
   const history = ids.length
-    ? runAdmin(["featured", "history", "--subject-ids", ids.join(","), "--all"])
+    ? runAdmin(
+        ["featured", "history", "--subject-ids", ids.join(","), "--all"],
+        { retryRead: true },
+      )
     : { ok: true, json: { data: { subjects: [], coverage: {} } } };
   if (!history.ok) throw new Error("featured history failed");
   const never = new Map(
@@ -209,7 +299,14 @@ export async function featuredCandidates(options) {
   );
   const candidates = [];
   for (const s of recent) {
-    const detail = runAdmin(["subject", "get", String(s.id), "--include-comments"]);
+    const detail = runAdmin(
+      ["subject", "get", String(s.id), "--include-comments"],
+      { retryRead: true },
+    );
+    if (!detail.ok)
+      throw new Error(
+        `Subject ${s.id} context is unavailable; candidate review is incomplete.`,
+      );
     const subject = detail.json?.data?.subject || {};
     const humanComments = (subject.comments || []).filter(
       (c) => !c.isNotification && ![7587, 8411].includes(Number(c.author?.id)),
@@ -226,6 +323,9 @@ export async function featuredCandidates(options) {
       hasAttachment: Boolean(s.attachment),
       description: String(s.description || "").slice(0, 300),
       commentsIncluded: Boolean(subject.commentsIncluded),
+      commentsTruncated: Boolean(subject.commentsTruncated),
+      commentCountsComplete:
+        Boolean(subject.commentsIncluded) && !subject.commentsTruncated,
       humanComments: humanComments.length,
       botComments: (subject.comments || []).filter((c) =>
         [7587, 8411].includes(Number(c.author?.id)),
@@ -262,13 +362,68 @@ code{background:var(--code);padding:1px 5px;border-radius:4px;font-size:.9em}pre
 @media (max-width:760px){nav{position:static;width:auto;height:auto;border-right:0;border-bottom:1px solid var(--line)}main{margin-left:0;padding:16px}}
 </style></head><body><nav><h4>Sections</h4><div id="toc"></div><h4 style="margin-top:18px">Source</h4><a href="source.html">Markdown</a></nav><main id="content">Loading…</main>
 <script src="marked.min.js"></script><script>
-fetch('daily-management-report.md',{cache:'no-store'}).then(r=>r.text()).then(md=>{const el=document.getElementById('content');el.innerHTML=marked.parse(md);const toc=document.getElementById('toc');let i=0;el.querySelectorAll('h1,h2').forEach(h=>{h.id='s'+(i++);if(h.tagName==='H2'){const a=document.createElement('a');a.href='#'+h.id;a.textContent=h.textContent;toc.appendChild(a)}})});
+fetch('daily-management-report.md',{cache:'no-store'}).then(r=>{if(!r.ok)throw new Error('Report source unavailable');return r.text()}).then(md=>{const el=document.getElementById('content');el.innerHTML=marked.parse(md);const toc=document.getElementById('toc');let i=0;el.querySelectorAll('h1,h2').forEach(h=>{h.id='s'+(i++);if(h.tagName==='H2'){const a=document.createElement('a');a.href='#'+h.id;a.textContent=h.textContent;toc.appendChild(a)}})}).catch(()=>{document.getElementById('content').textContent='The report could not load. Open Markdown under Source, or reload this page.'});
 </script></body></html>`;
 }
 
 // Serves the report Markdown as a browsable page on loopback. Only the page,
 // its script and the Markdown are reachable; the evidence folder is not.
-export async function reportServe(options) {
+export function waitForReportServer(child, timeoutMs = 10000) {
+  return new Promise((resolve, reject) => {
+    let buf = "";
+    let settled = false;
+    const finish = (error, url) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      child.stdout.removeListener("data", onData);
+      child.removeListener("exit", onExit);
+      child.removeListener("error", onError);
+      if (error) {
+        child.kill();
+        reject(error);
+      } else resolve(url);
+    };
+    const onData = (chunk) => {
+      buf += chunk;
+      if (buf.length > 65536)
+        return finish(
+          new Error("Report server returned an invalid startup receipt."),
+        );
+      if (!buf.includes("\n")) return;
+      try {
+        const parsed = JSON.parse(buf.split("\n")[0]);
+        const url = new URL(parsed.data?.url);
+        if (
+          parsed.ok !== true ||
+          parsed.status !== "success" ||
+          url.protocol !== "http:" ||
+          url.hostname !== "127.0.0.1"
+        )
+          throw new Error("invalid receipt");
+        finish(null, url.href);
+      } catch {
+        finish(new Error("Report server returned an invalid startup receipt."));
+      }
+    };
+    const onExit = (code) =>
+      finish(new Error(`Report server exited (${code}) before it was ready.`));
+    const onError = (error) => finish(error);
+    const timer = setTimeout(
+      () =>
+        finish(new Error("Report server did not start before its deadline.")),
+      timeoutMs,
+    );
+    child.stdout.on("data", onData);
+    child.once("exit", onExit);
+    child.once("error", onError);
+  });
+}
+
+export async function reportServe(
+  options,
+  { spawnImpl = spawn, openImpl = spawnSync } = {},
+) {
   const file = path.resolve(options.adminFile || "daily-management-report.md");
   if (!fs.existsSync(file)) throw new Error(`Report not found: ${file}`);
   const title =
@@ -295,48 +450,65 @@ export async function reportServe(options) {
         res.writeHead(404).end("not found");
         return;
       }
-      const { type, body } = route();
-      res.writeHead(200, { "content-type": type, "cache-control": "no-store" });
-      res.end(body);
+      try {
+        const { type, body } = route();
+        res.writeHead(200, { "content-type": type, "cache-control": "no-store" });
+        res.end(body);
+      } catch {
+        res.writeHead(503).end("report source unavailable");
+      }
+    });
+    await new Promise((resolve, reject) => {
+      server.once("error", reject);
+      server.listen(port, "127.0.0.1", resolve);
     });
-    await new Promise((resolve) => server.listen(port, "127.0.0.1", resolve));
     const url = `http://127.0.0.1:${server.address().port}/`;
     console.log(JSON.stringify({ ok: true, status: "success", data: { url, file } }));
     return new Promise(() => {});
   }
   // Detach a foreground copy of this command so the page outlives the CLI.
-  const child = spawn(
+  const child = spawnImpl(
     process.execPath,
-    [LUMINE_BIN, "admin", "report", "serve", "--file", file, "--port", String(port), "--foreground"],
+    [
+      LUMINE_BIN,
+      "admin",
+      "report",
+      "serve",
+      "--file",
+      file,
+      "--port",
+      String(port),
+      "--foreground",
+      "--json",
+      "--no-update-check",
+    ],
     { detached: true, stdio: ["ignore", "pipe", "ignore"] },
   );
-  const url = await new Promise((resolve, reject) => {
-    let buf = "";
-    const timer = setTimeout(() => reject(new Error("report server did not start")), 10000);
-    child.stdout.on("data", (chunk) => {
-      buf += chunk;
-      const line = buf.split("\n")[0];
-      try {
-        const parsed = JSON.parse(line);
-        clearTimeout(timer);
-        resolve(parsed.data.url);
-      } catch {
-        /* wait for the full line */
-      }
-    });
-    child.on("exit", (code) => {
-      clearTimeout(timer);
-      reject(new Error(`report server exited (${code})`));
-    });
-  });
+  const url = await waitForReportServer(child);
   child.stdout.destroy();
   child.unref();
-  if (options.adminOpen) {
-    spawnSync("open", ["-a", "Google Chrome", url]);
-  }
+  const opened = options.adminOpen
+    ? openImpl("open", ["-a", "Google Chrome", url])
+    : null;
   return {
     ok: true,
     status: "success",
-    data: { url, file, pid: child.pid, opened: Boolean(options.adminOpen) },
+    data: {
+      url,
+      file,
+      pid: child.pid,
+      opened: opened?.status === 0,
+      ...(opened && opened.status !== 0
+        ? {
+            openError:
+              "Chrome did not accept the open request; the report server is available.",
+          }
+        : {}),
+      browserVerification: {
+        render: "pending",
+        navigation: "pending",
+        source: "pending",
+      },
+    },
   };
 }

package/lib/admin-duties.js

@@ -0,0 +1,191 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { readAdminJsonFile, writeAdminJsonFile } from "./admin-news.js";
+
+function fingerprint(dir, file) {
+  const absolute = path.resolve(dir, file);
+  const relative = path.relative(dir, absolute);
+  if (
+    !relative ||
+    relative.startsWith(`..${path.sep}`) ||
+    path.isAbsolute(relative)
+  ) {
+    throw new Error("Duty evidence must name a file inside the run directory.");
+  }
+  const bytes = fs.readFileSync(absolute);
+  return {
+    file: relative,
+    bytes: bytes.length,
+    sha256: createHash("sha256").update(bytes).digest("hex"),
+  };
+}
+
+export function createDailyReviewState(dir, gather, previous = {}) {
+  if (previous.protocol != null && previous.protocol !== 1) throw new Error("Unsupported previous duty evidence protocol.");
+  const sources = gather.steps
+    .filter((step) => step.file)
+    .map((step) => ({
+      ...(step.ok ? fingerprint(dir, step.file) : { file: step.file }),
+      fetched: step.ok,
+      read: false,
+    }));
+  if (gather.botOutput.complete)
+    sources.push({
+      ...fingerprint(dir, "bot-chats.txt"),
+      fetched: true,
+      read: false,
+    });
+  for (const source of previous.sources || []) {
+    if (!sources.some((current) => current.file === source.file)) sources.push({ ...source, retained: true, read: false });
+  }
+  return {
+    protocol: 1,
+    scope: previous.scope || "collection",
+    sources,
+    requiredDuties: [...new Set(["effort-levels", "report-browser", ...(previous.requiredDuties || [])])],
+    note: "Collection is not a full review. Add every duty required by the run scope and its carryovers. Reading and browser checks require explicit evidence acknowledgments.",
+  };
+}
+
+// Local operator acknowledgments are separate from canonical server mutations.
+// Hashes bind an acknowledgment to the bytes read; they cannot prove reading.
+export function summarizeDailyProgress(dir, state, evidence = {}) {
+  if (
+    state.protocol !== 1 ||
+    (evidence.protocol != null && evidence.protocol !== 1)
+  )
+    throw new Error("Unsupported duty evidence protocol.");
+  const acknowledgments = evidence.reading || [];
+  const sources = (state.sources || []).map((source) => {
+    if (!source.fetched)
+      return { ...source, read: false, status: "unavailable" };
+    let current;
+    try {
+      current = fingerprint(dir, source.file);
+    } catch {
+      return { ...source, read: false, status: "unavailable" };
+    }
+    const acknowledgment = acknowledgments.find(
+      (item) =>
+        item.file === source.file &&
+        item.sha256 === current.sha256 &&
+        item.bytes === current.bytes &&
+        Number.isFinite(Date.parse(item.readAt)) &&
+        item.complete === true,
+    );
+    return {
+      ...source,
+      ...current,
+      read: Boolean(acknowledgment),
+      status: acknowledgment ? "read" : "fetched",
+      readAt: acknowledgment?.readAt || null,
+    };
+  });
+  const verifyReference = (reference) => {
+    if (!reference?.file || !reference.sha256) return false;
+    try {
+      const current = fingerprint(dir, reference.file);
+      return (
+        current.sha256 === reference.sha256 && current.bytes === reference.bytes
+      );
+    } catch {
+      return false;
+    }
+  };
+  let canonicalRun = null;
+  let effortAssignments = null;
+  if (verifyReference(evidence.runReport)) {
+    const receipt = readAdminJsonFile(
+      path.resolve(dir, evidence.runReport.file),
+      "the run report",
+    );
+    const report =
+      receipt.ok === true && receipt.status === "success"
+        ? receipt.data?.report
+        : null;
+    if (
+      report &&
+      Number(report.run?.id) === Number(evidence.runId) &&
+      Array.isArray(report.mutations?.byAction)
+    ) {
+      canonicalRun = { id: report.run.id, status: report.run.status };
+      // Absence is zero only in a confirmed complete report, never in a failed fetch.
+      const row = report.mutations.byAction.find(
+        (item) => item.action === "subject.effort.set",
+      );
+      effortAssignments = row || {
+        action: "subject.effort.set",
+        attempts: 0,
+        completed: 0,
+        changed: 0,
+        failed: 0,
+        pending: 0,
+      };
+    }
+  }
+  const required = [
+    ...new Set([
+      ...(state.requiredDuties || []),
+      ...(evidence.requiredDuties || []),
+    ]),
+  ];
+  const duties = required.map((id) => {
+    const duty = (evidence.duties || []).find((item) => item.id === id);
+    const confirmed =
+      duty?.status === "completed" &&
+      duty.evidence?.length &&
+      duty.evidence.every(verifyReference) &&
+      (id !== "effort-levels" || effortAssignments !== null);
+    return {
+      id,
+      status: confirmed
+        ? "completed"
+        : duty?.status === "unavailable"
+          ? "unavailable"
+          : "pending",
+      note: duty?.note || null,
+    };
+  });
+  const incomplete = duties
+    .filter((item) => item.status !== "completed")
+    .map((item) => item.id);
+  const complete =
+    sources.every((item) => item.read) && incomplete.length === 0;
+  return {
+    scope: state.scope || "declared-duties",
+    coverageBasis: "declared sources and duties only",
+    canonicalRun,
+    effortAssignments,
+    sources,
+    duties,
+    complete,
+    reading: {
+      fetched: sources.filter((item) => item.fetched).length,
+      read: sources.filter((item) => item.read).length,
+      pending: sources.filter((item) => !item.read).map((item) => item.file),
+    },
+    incompleteDuties: incomplete,
+    note: "Run lease completion, reading acknowledgments, effort mutations, and browser verification are independent. A completed lease does not close pending review duties.",
+  };
+}
+
+export async function dailyRunProgress(options) {
+  const dir = path.resolve(options.adminDir || options.adminOutputDir || ".");
+  const state = readAdminJsonFile(
+    path.join(dir, "review-state.json"),
+    "the review state",
+  );
+  const evidence = options.adminFile
+    ? readAdminJsonFile(path.resolve(options.adminFile), "the duty evidence")
+    : {};
+  const progress = summarizeDailyProgress(dir, state, evidence);
+  writeAdminJsonFile(path.join(dir, "progress.json"), progress, {
+    privateFile: true,
+  });
+  return {
+    ok: true,
+    status: progress.complete ? "success" : "pending",
+    data: progress,
+  };
+}

package/lib/admin-request-intents.js

@@ -0,0 +1,83 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { adminWorkDirectory } from "./admin-work-directory.js";
+import { readAdminJsonFile, writeAdminJsonFile } from "./admin-news.js";
+
+const digest = (value) => createHash("sha256").update(value).digest("hex");
+
+// Persist before sending. A killed process or missing HTTP receipt reuses the
+// same request key in the same API/account/run/session and exact operation.
+// Only a canonical receipt closes it; there is no automatic write retry.
+export function prepareAdminMutationIntent({
+  operation,
+  apiUrl,
+  authority,
+  idempotencyKey,
+  directory = path.join(adminWorkDirectory(), "requests"),
+}) {
+  fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+  fs.chmodSync(directory, 0o700);
+  const fingerprint = digest(
+    JSON.stringify({
+      apiUrl: String(apiUrl).replace(/\/$/, ""),
+      authority,
+      method: operation.method,
+      path: operation.path,
+      body: operation.body,
+    }),
+  );
+  const suffix = idempotencyKey ? `-${digest(idempotencyKey)}` : "";
+  const file = path.join(directory, `${fingerprint}${suffix}.pending.json`);
+  let intent;
+  try {
+    const fd = fs.openSync(file, "wx", 0o600);
+    try {
+      intent = {
+        kind: "lumine-admin-mutation-intent",
+        fingerprint,
+        operation: operation.name,
+        requestId: idempotencyKey || `cli:${randomUUID()}`,
+        createdAt: new Date().toISOString(),
+      };
+      fs.writeFileSync(fd, JSON.stringify(intent));
+      fs.fsyncSync(fd);
+    } finally {
+      fs.closeSync(fd);
+    }
+  } catch (error) {
+    if (error.code !== "EEXIST") throw error;
+    intent = readAdminJsonFile(file, "the pending mutation intent");
+    if (
+      intent.kind !== "lumine-admin-mutation-intent" ||
+      intent.fingerprint !== fingerprint ||
+      !/^[A-Za-z0-9._:-]{8,80}$/.test(intent.requestId || "")
+    ) {
+      throw new Error(
+        `The pending mutation intent is unconfirmed: ${file}. Inspect its original request key before retrying.`,
+      );
+    }
+  }
+  const receiptPath = path.join(
+    directory,
+    `${digest(intent.requestId)}.receipt.json`,
+  );
+  return {
+    requestId: intent.requestId,
+    confirm(receipt) {
+      if (receipt?.ok !== true || typeof receipt.status !== "string") {
+        const error = new Error(
+          "The API did not return a canonical admin receipt. The mutation outcome is unconfirmed.",
+        );
+        error.code = "CLI_ADMIN_RECEIPT_INVALID";
+        throw error;
+      }
+      writeAdminJsonFile(receiptPath, receipt, { privateFile: true });
+    },
+    delivered() {
+      fs.rmSync(file, { force: true });
+    },
+    file,
+    receiptPath,
+  };
+}

package/lib/admin-runtime-logs.js

@@ -19,6 +19,7 @@ import path from "node:path";
 
 import { readAdminJsonFile, writeAdminJsonFile } from "./admin-news.js";
 import { requestJson } from "./http.js";
+import { adminWorkDirectory } from "./admin-work-directory.js";
 
 const SESSION_SCHEMA_VERSION = 1;
 const MAX_SESSION_BYTES = 2 * 1024 * 1024;
@@ -127,7 +128,7 @@ function startIntentPath(options) {
       "runtime-log-review-start-intent.json",
     );
   }
-  // Shared temp directories are per host, not per operator login; key the
+  // Persistent fallback files are also keyed by operator account; key the
   // fallback to this account so two operator accounts never replay each
   // other's start key. Two shells of the same account still share it, which
   // is why a replayed start rotates the lease server-side.
@@ -136,7 +137,7 @@ function startIntentPath(options) {
     .digest("hex")
     .slice(0, 16);
   return path.join(
-    os.tmpdir(),
+    adminWorkDirectory(),
     `lumine-admin-runtime-log-review-start-intent-${account}.json`,
   );
 }
@@ -178,7 +179,10 @@ function createSession({ options, apiUrl, review }) {
         ),
       )
     : mkdtempSync(
-        path.join(os.tmpdir(), `lumine-admin-runtime-log-review-${review.id}-`),
+        path.join(
+          adminWorkDirectory(),
+          `lumine-admin-runtime-log-review-${review.id}-`,
+        ),
       );
   chmodSync(outputDirectory, 0o700);
   const sessionPath = path.resolve(

package/lib/admin-work-directory.js

@@ -0,0 +1,11 @@
+import fs from "node:fs";
+import path from "node:path";
+
+// Recovery keys, leases and evidence survive OS temp cleanup. Explicit output
+// directories, checkpoints and review-session paths still take priority.
+export function adminWorkDirectory() {
+  const directory = path.resolve(process.cwd(), "work", "lumine-admin");
+  fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+  fs.chmodSync(directory, 0o700);
+  return directory;
+}

package/lib/admin-workflows.js

@@ -1,6 +1,8 @@
 import { createHash, randomUUID } from "node:crypto";
 import {
   chmodSync,
+  constants,
+  copyFileSync,
   closeSync,
   createReadStream,
   fchmodSync,
@@ -12,6 +14,7 @@ import {
   readFileSync,
   readSync,
   renameSync,
+  statSync,
   truncateSync,
   unlinkSync,
   writeFileSync,
@@ -22,6 +25,7 @@ import readline from "node:readline";
 
 import { writeAdminJsonFile, readAdminJsonFile } from "./admin-news.js";
 import { requestJson } from "./http.js";
+import { adminWorkDirectory } from "./admin-work-directory.js";
 
 const MAX_BATCH_TARGET_FILE_BYTES = 2 * 1024 * 1024;
 const MAX_BATCH_TARGETS = 20_000;
@@ -80,13 +84,14 @@ function defaultCheckpointPath({
   runId,
   operationName,
   operationFingerprint = "",
+  directory = adminWorkDirectory(),
 }) {
   const safeName = String(operationName).replace(/[^a-z0-9_.-]+/gi, "-");
   const fingerprintSuffix = operationFingerprint
     ? `-${operationFingerprint}`
     : "";
   return path.join(
-    os.tmpdir(),
+    directory,
     `lumine-admin-run-${runId}-${safeName}${fingerprintSuffix}.json`,
   );
 }
@@ -116,10 +121,91 @@ function resolveAutomaticCheckpointPath({
       operationName: operation.name,
     });
     if (pathEntryExists(legacyPath)) return legacyPath;
+    // Read old OS-temp checkpoints once, then resume only from durable files.
+    // The normal scan validates the saved scope and spool hash before use.
+    for (const fingerprint of [operationFingerprint, ""]) {
+      const old = defaultCheckpointPath({
+        runId,
+        operationName: operation.name,
+        operationFingerprint: fingerprint,
+        directory: os.tmpdir(),
+      });
+      if (pathEntryExists(old)) {
+        migrateLegacyCheckpoint({ old, keyedPath, operationFingerprint });
+        return keyedPath;
+      }
+    }
   }
   return keyedPath;
 }
 
+export function migrateLegacyCheckpoint({
+  old,
+  keyedPath,
+  operationFingerprint,
+}) {
+  const lock = acquireCheckpointLock(keyedPath, operationFingerprint);
+  let copiedSpool = null;
+  let savedCheckpoint = false;
+  const assertSourceIdle = () => {
+    if (
+      (pathEntryExists(`${old}.lock`) &&
+        !checkpointLockOwnerIsDead(`${old}.lock`)) ||
+      pathEntryExists(`${old}.lock.reclaim`)
+    ) {
+      throw validationError(
+        "The legacy checkpoint still has a scan lock. Finish its owner before migrating it.",
+      );
+    }
+  };
+  try {
+    // A concurrent resumer may already have completed this migration.
+    if (pathEntryExists(keyedPath)) return;
+    assertSourceIdle();
+    const before = statSync(old);
+    const saved = readAdminJsonFile(old, "the legacy checkpoint", {
+      maxBytes: MAX_LEGACY_ADMIN_CHECKPOINT_BYTES,
+    });
+    if (saved.spoolPath) {
+      if (
+        !candidateSpoolBelongsToCheckpoint({
+          checkpointPath: old,
+          spoolPath: saved.spoolPath,
+        })
+      )
+        throw validationError(
+          "The legacy candidate spool does not belong to its checkpoint.",
+        );
+      copiedSpool = candidateSpoolPath(keyedPath);
+      copyFileSync(saved.spoolPath, copiedSpool, constants.COPYFILE_EXCL);
+      chmodSync(copiedSpool, 0o600);
+      saved.spoolPath = copiedSpool;
+    }
+    assertSourceIdle();
+    const after = statSync(old);
+    if (
+      before.ino !== after.ino ||
+      before.size !== after.size ||
+      before.mtimeMs !== after.mtimeMs
+    ) {
+      throw validationError(
+        "The legacy checkpoint changed during migration. Retry after its owner finishes.",
+      );
+    }
+    writeAdminJsonFile(keyedPath, saved, { privateFile: true });
+    savedCheckpoint = true;
+  } finally {
+    if (copiedSpool && !savedCheckpoint) {
+      try {
+        unlinkSync(copiedSpool);
+      } catch {
+        /* preserve the original migration error */
+      }
+    }
+    releaseCheckpointLock(lock);
+  }
+}
+
 function pathEntryExists(filePath) {
   try {
     lstatSync(filePath);
@@ -209,27 +295,7 @@ function removeDeadCheckpointLock(lockPath) {
     // 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;
-    }
+    if (!checkpointLockOwnerIsDead(reclaimPath)) return false;
     const claimedState = lstatSync(reclaimPath);
     const currentState = lstatSync(lockPath);
     if (
@@ -253,6 +319,34 @@ function removeDeadCheckpointLock(lockPath) {
   }
 }
 
+// Read-only liveness proof also permits migration from a crashed legacy owner
+// without editing its old temporary files. Unknown/live owners still stop it.
+function checkpointLockOwnerIsDead(lockPath) {
+  try {
+    const fileState = lstatSync(lockPath);
+    if (!fileState.isFile() || fileState.isSymbolicLink() || fileState.size > 16 * 1024)
+      return false;
+    const state = JSON.parse(readFileSync(lockPath, "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) {
+      return error?.code === "ESRCH";
+    }
+  } catch {
+    return false;
+  }
+}
+
 export function releaseCheckpointLock(lock) {
   try {
     const fileState = lstatSync(lock.lockPath);

package/lib/admin.js

@@ -12,6 +12,7 @@ import {
 import path from "node:path";
 import { assertAuthScope, resolveAuth } from "./auth.js";
 import { requestJson } from "./http.js";
+import { prepareAdminMutationIntent } from "./admin-request-intents.js";
 import { formatBytes, parseStorageSizeBytes } from "./util.js";
 import {
   extractNewsClaim,
@@ -34,6 +35,7 @@ import {
 import { runAdminRuntimeLogWorkflow } from "./admin-runtime-logs.js";
 import {
   dailyRunGather,
+  dailyRunProgress,
   featuredCandidates,
   reportServe,
 } from "./admin-daily.js";
@@ -591,11 +593,13 @@ export async function adminCommand(options) {
   const composite =
     namespace === "daily-run" && action === "gather"
       ? dailyRunGather
-      : namespace === "featured" && action === "candidates"
-        ? featuredCandidates
-        : namespace === "report" && action === "serve"
-          ? reportServe
-          : null;
+      : namespace === "daily-run" && action === "progress"
+        ? dailyRunProgress
+        : namespace === "featured" && action === "candidates"
+          ? featuredCandidates
+          : namespace === "report" && action === "serve"
+            ? reportServe
+            : null;
   if (composite) {
     const result = await composite(options);
     if (options.adminOutput) {
@@ -631,7 +635,7 @@ export async function adminCommand(options) {
       ? parseRecommendationContentTypes(options.adminContentTypes)
       : null;
   const auth = await resolveAuth(options);
-  await assertAuthScope({
+  const authSession = await assertAuthScope({
     options,
     auth,
     scope: operation.mutates ? "build:write" : "build:read",
@@ -755,12 +759,31 @@ export async function adminCommand(options) {
       }
     }
   }
+  const mutationIntent =
+    operation.mutates &&
+    !operation.featuredWorkflow &&
+    operation.name !== "post.skip-batch" &&
+    !operation.name.startsWith("runtime-logs.")
+      ? prepareAdminMutationIntent({
+          operation,
+          apiUrl: options.apiUrl,
+          authority: {
+            account: canonicalAdminAccount(authSession),
+            runId,
+            correctionSessionId,
+            commentSessionId,
+          },
+          idempotencyKey: options.idempotencyKey,
+        })
+      : null;
   const requestId =
-    options.idempotencyKey || (operation.mutates ? `cli:${randomUUID()}` : "");
+    mutationIntent?.requestId ||
+    options.idempotencyKey ||
+    (operation.mutates ? `cli:${randomUUID()}` : "");
   let result;
   try {
-    const fetchOperation = async (requestPath = operation.path, signal) =>
-      requestJson({
+    const fetchOperation = async (requestPath = operation.path, signal) => {
+      const receipt = await requestJson({
         method: operation.method,
         url: `${options.apiUrl}${requestPath}`,
         authToken: auth.token,
@@ -784,6 +807,18 @@ export async function adminCommand(options) {
         timeoutMs: operation.timeoutMs || options.timeoutMs,
         signal,
       });
+      if (
+        typeof receipt.ok !== "boolean" ||
+        typeof receipt.status !== "string"
+      ) {
+        const error = new Error(
+          "The API did not return a valid admin receipt. The request outcome is unconfirmed.",
+        );
+        error.code = "CLI_ADMIN_RECEIPT_INVALID";
+        throw error;
+      }
+      return receipt;
+    };
     const transformResult = (rawResult) =>
       transformAdminResult({
         operation,
@@ -859,6 +894,7 @@ export async function adminCommand(options) {
       }
       result = transformResult(await fetchOperation());
     }
+    mutationIntent?.confirm(result);
   } catch (error) {
     if (operation.name === "runtime.evidence" && error.status === 404) {
       error.code = "CLI_ADMIN_RUNTIME_EVIDENCE_NOT_DEPLOYED";
@@ -1003,7 +1039,19 @@ export async function adminCommand(options) {
       data: { ...(result.data || {}), artifacts },
     };
   }
-  return finishAdminOutput({ options, operation, result });
+  const output = await finishAdminOutput({ options, operation, result });
+  mutationIntent?.delivered();
+  return output;
+}
+
+function canonicalAdminAccount(session) {
+  const userId = Number(session?.userId);
+  if (!Number.isSafeInteger(userId) || userId <= 0) {
+    throw cliValidationError(
+      "The API did not confirm the signed-in account. The mutation was not sent.",
+    );
+  }
+  return userId;
 }
 
 function transformAdminResult({

package/lib/auth.js

@@ -198,6 +198,7 @@ export async function assertAuthScope({ options, auth, scope }) {
       `Saved login is missing ${scope}. Run \`lumine login\` again to grant it.`,
     );
   }
+  return session;
 }
 
 export function isMissingLoginError(error) {

package/lib/build-review.js

@@ -8,11 +8,11 @@ import {
   statSync,
   writeFileSync,
 } from "node:fs";
-import os from "node:os";
 import path from "node:path";
 
 import { requestJson } from "./http.js";
 import { readAdminJsonFile, writeAdminJsonFile } from "./admin-news.js";
+import { adminWorkDirectory } from "./admin-work-directory.js";
 
 const DEFAULT_REVIEW_WAIT_MS = 10_000;
 const MAX_REVIEW_WAIT_MS = 45_000;
@@ -961,10 +961,10 @@ export async function runManagedBuildReview({ options, authToken, buildId }) {
     outputDir = mkdtempSync(path.join(outputRoot, `build-${buildId}-review-`));
   } else {
     outputDir = mkdtempSync(
-      path.join(os.tmpdir(), `lumine-build-${buildId}-review-`),
+      path.join(adminWorkDirectory(), `build-${buildId}-review-`),
     );
   }
-  const profileDir = mkdtempSync(path.join(os.tmpdir(), "lumine-chrome-profile-"));
+  const profileDir = mkdtempSync(path.join(outputDir, "browser-profile-"));
   const screenshotPath = path.join(outputDir, "runtime.png");
   const receiptPath = path.join(outputDir, "review.json");
   const appUrl = `${String(options.siteUrl).replace(/\/$/, "")}/app/${buildId}`;

package/lib/commands.js

@@ -2503,6 +2503,7 @@ export function parseArgs(args) {
     adminCheckpoint: raw.checkpoint ? String(raw.checkpoint) : "",
     adminOutput: raw.output ? String(raw.output) : "",
     adminOutputDir: raw.outputDir ? String(raw.outputDir) : "",
+    adminDir: raw.dir ? String(raw.dir) : "",
     adminClaimFile: raw.claim ? String(raw.claim) : "",
     adminScaffoldFile: raw.scaffold ? String(raw.scaffold) : "",
     adminTargetFile: raw.targetFile ? String(raw.targetFile) : "",
@@ -3032,6 +3033,7 @@ export function printHelp() {
   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 [--since-run|--after <date>|--include-legacy] [--all --checkpoint <file> [--resume]] [--cursor <cursor>] [--limit <number>] [--json]
   lumine admin daily-run gather --output-dir <dir> [--date YYYY-MM-DD] [--json]   (all read-only daily reports + bot-output pages + bot-chats.txt)
+  lumine admin daily-run progress --dir <dir> [--file <duty-evidence.json>] [--json]   (reading, canonical effort counts, pending duties)
   lumine admin featured candidates [--days 7] [--after <iso>] [--json]   (recent, provably never-Featured Subjects with comment counts)
   lumine admin report serve --file <report.md> [--port <n>] [--open] [--json]   (loopback report page with section nav)
   lumine admin builds review <build-url-or-id> [--output-dir <dir>] [--wait-ms <ms>] [--interact <steps.json>] [--browser-path <path>] [--json]

package/lib/http.js

@@ -18,7 +18,7 @@ export async function requestJson({
     headers,
     signal,
   });
-  const data = parseJson(text);
+  let data = parseJson(text);
   if (!response.ok) {
     const error = new Error(
       data?.error?.message ||
@@ -30,7 +30,22 @@ export async function requestJson({
     error.data = data;
     throw error;
   }
-  return data || {};
+  // parseJson intentionally wraps non-JSON error text for HTTP failures.
+  // A successful response must contain actual JSON, never that fallback.
+  try {
+    data = JSON.parse(text);
+  } catch {
+    data = null;
+  }
+  if (!data || typeof data !== "object") {
+    const error = new Error(
+      "The API returned no valid JSON response. The request outcome is unconfirmed.",
+    );
+    error.code = "lumine_http_invalid_response";
+    error.status = response.status;
+    throw error;
+  }
+  return data;
 }
 
 export async function probeUrl({ url, authToken, timeoutMs, signal }) {

package/lib/sdk.js

@@ -214,6 +214,16 @@ export const SDK_CLI_METHODS = {
     scopes: ["rewards:claim"], readOnly: true,
     mapArgs: (args) => ({ ruleId: args.ruleId, cursor: args.cursor, limit: args.limit }),
   },
+  "rewards.interpretAnswer": {
+    path: "api/rewards/interpret-answer", special: "rewards", operation: "interpret-answer",
+    scopes: ["rewards:claim"], readOnly: true,
+    mapArgs: (args) => ({ challengeId: args.challengeId, text: args.text }),
+  },
+  "rewards.getChallengeBoard": {
+    path: "api/rewards/challenge-board", special: "rewards", operation: "challenge-board",
+    scopes: ["rewards:claim"], readOnly: true,
+    mapArgs: () => ({}),
+  },
   "rewards.getArchivedProblem": {
     path: "api/rewards/archived-problem", special: "rewards", operation: "archived-problem",
     scopes: ["rewards:claim"], readOnly: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage5/lumine",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "description": "Command line tools for launching Lumine builds on Twinkle.",
   "type": "module",
   "bin": {

package/sdk/BUILD_SDK_INDEX.md

@@ -2,7 +2,7 @@
 
 Version: 1.63.0
 Updated: 2026-09-28
-Generated: 2026-09-30T09:55:20.738Z
+Generated: 2026-10-03T04:47:01.454Z
 
 ## Notes
 - This SDK is injected into Build iframes via the Build preview/runtime.
@@ -81,8 +81,9 @@ files:read, media:read, media:write, live:read, live:write, user:read, users:rea
 
 ### Twinkle.viewer
 - async get() | scopes: none
-  - Returns: { id, username, profilePicUrl, isLoggedIn, isOwner, isGuest }
+  - Returns: { id, username, profilePicUrl, isLoggedIn, isOwner, isGuest, ageTier }
   - Cached; use refresh() to re-fetch.
+  - ageTier is 'kid', 'teen' or 'adult', taken from the viewer's Teenager and Adult achievements (granted once an admin approves their birthdate). Guests and viewers without either achievement are 'kid'. It is a display and default-selection hint computed by the Twinkle page; do not treat it as a server-side permission.
 - async refresh() | scopes: none
   - Returns: Viewer info
   - Forces a fresh fetch from the parent.
@@ -1515,6 +1516,21 @@ world.updatePresence({ x, y, z, facing });
   - Standings of who earned the most XP or Coins in THIS app, computed by Twinkle from its own receipts (never from anything the app submits). period 'day' is today (site day, UTC), 'week' the last 7 site days, 'all' (default) every day since approval. limit defaults to 20, max 100.
   - available says which boards this app's approved rules can pay: show a Coins board only when available.coins is true (an app whose rules pay XP only has no Coins standings). me is the signed-in viewer's own standing even when they fall outside the page, or null when they earned nothing in the period.
   - Drafts and previews return mode 'preview' with no entries. Use Twinkle.leaderboards for app-defined scores; use this for real XP and Coins earned.
+- await Twinkle.rewards.interpretAnswer({ challengeId, text }) | scopes: rewards:claim
+  - Returns: { mode: "live" | "preview", understood: boolean, value: number | null, source: "plain" | "model" }
+  - Read a learner's free-form answer text into the single number they meant, so they can answer in any format.
+  - For numeric-quiz bounties. Call it only when the typed text is not already a plain number or fraction (check that locally); a plain number returns source 'plain' with no model call. Then pass the returned value to claim({ challengeId, answers: [value] }). A small model reads the text and the platform pays for it, so the learner's AI Energy is never charged.
+  - understood: false means the text had no single clear number (several alternatives, no number, or a calculation). Tell the learner in friendly words to type just the number. This is not a wrong answer and does not use a try.
+  - The reader is given the puzzle text only to learn the requested answer format (unit, fraction/decimal/percent, which of several numbers answers the question), never the answer key, and never calculates or converts units: it only reads what was written, and the number it returns must be one the learner actually typed. Typed expressions like 5+8 are intentionally not evaluated.
+  - Requires an open challenge of the learner's own (build_reward_challenge_not_open, HTTP 409 otherwise). Limit: 120 characters (build_reward_answer_text_invalid, 400), rate limited to a burst of 4 then one read every 5 seconds (build_reward_throttled, 429). build_reward_answer_reader_unavailable (503) means the reader is down: ask the learner to type just the number.
+  - Drafts and owner previews return mode 'preview' and need no open challenge.
+- await Twinkle.rewards.getChallengeBoard() | scopes: rewards:claim
+  - Returns: { mode: "live", dayKey, puzzles: [{ ruleId, title, setKey, rating, solvers, failers, failures, daysStanding, status: "untouched" | "undefeated" | "defeated" }], topSolvers: [{ rank, userId, username, profilePicUrl, rating, solves, hardestSolve: { ruleId, setKey, rating } | null }], recentSolves: [{ id, userId, username, ruleId, setKey, tier: "solved" | "first-solve" | "hard-won" | "legendary", attempt, firstSolve, failersBefore, failuresBefore, daysStanding, puzzleRating, at }], me: { rating, solves, rank } | null } | { mode: "preview", puzzles: [], topSolvers: [], recentSolves: [], me: null, message }
+  - Front-page difficulty board for until-earned quiz bounties: what is being tried and failed, who is rated highest, and the latest defeats.
+  - Computed by Twinkle from its own receipts and attempts, never from anything the app submits. Puzzles are Elo-rated against players: a player's first miss on a puzzle is a win for the puzzle, a solve is a win for the player, and repeat misses by one player never stack.
+  - puzzles lists today's set for each until-earned rule. status 'undefeated' means someone tried and nobody has solved it yet; show it as a standing challenge. failers is how many different players missed it; failures is total wrong answers.
+  - tier on a recent solve says how loudly to celebrate: 'legendary' (first solve of a long-undefeated puzzle), 'hard-won', 'first-solve', or plain 'solved'. It is fixed at solve time, so it never changes later.
+  - No questions, answers, guides or private work are ever returned. Names are the same public names the XP leaderboard shows; other players who missed a puzzle are counted, never named. Drafts and previews return mode 'preview' with empty lists.
 - await Twinkle.rewards.getTimeline({ ruleId?, cursor?, limit? } = {}) | scopes: rewards:claim
   - Returns: { mode: "live", dayKey, entries: [{ receiptId, ruleId, ruleTitle, setKey, title, promptPreview, dayKey, closedAt, solvedAt, solver: { userId, username }, firstSolver, xp, coins, attempt }], nextCursor } | { mode: "preview", entries: [], nextCursor: null, message }
   - Browse confirmed solves of retired until-earned quiz bounties, newest first.

package/sdk/LUMINE_ADMIN.md

@@ -1022,14 +1022,50 @@ each swap again. Never omit this section from a full-run report.
 
 ```bash
 lumine admin daily-run gather --output-dir <dir> [--date YYYY-MM-DD] --json
+lumine admin daily-run progress --dir <dir> [--file <duty-evidence.json>] --json
 lumine admin featured candidates [--days 7] [--after <iso>] --json
 lumine admin report serve --file <dir>/daily-management-report.md [--port <n>] [--open] --json
 ```
 
 These compose the documented commands in this contract, running them as child processes, so every scope check, audit and pagination rule applies unchanged.
-- **`gather`** saves each read-only report into `<dir>`. It follows `bot-output` to exhaustion and renders `bot-chats.txt`, then lists any failed step in `gather.json`. It needs the active run for run-scoped reads.
-- **`featured candidates`** returns Subjects posted after the Bangkok-midnight cutoff that are off the board and provably never Featured. Each one comes with its human/bot comment counts and whether Mikey has viewed it. Eligibility only: ranking stays editorial.
-- **`report serve`** detaches a loopback server that answers only `/`, `marked.min.js` and the report Markdown. `--open` opens Chrome.
+- **`gather`** saves each read-only report into `<dir>`. It follows `bot-output` to exhaustion and renders `bot-chats.txt`, then lists any failed step in `gather.json`. It also creates `review-state.json`: every source is fetched, not read. Children bypass update checks, require matching fresh stdout/file receipts, and retry an unconfirmed opted-in read at most once. Mutations never auto-retry. It needs the active run for run-scoped reads.
+- **`progress`** reads local review state and explicit operator acknowledgments, writes private `progress.json`, and keeps reading, canonical effort mutations, the run lease, and browser checks separate. Add all required duties for the actual run scope and its carryovers; collection alone is not a full review. A completed run lease cannot complete a pending duty. Reading acknowledgments bind to the current file bytes and are operator attestations, not proof of comprehension.
+- **`featured candidates`** returns Subjects posted after the Bangkok-midnight cutoff that are off the board and provably never Featured. Each one comes with its human/bot comment counts, explicit comment truncation/completeness, and whether Mikey has viewed it. Counts from truncated context are partial. An unavailable Subject context fails the collection. Eligibility only: ranking stays editorial.
+- **`report serve`** detaches a loopback server that answers only `/`, `marked.min.js` and the report Markdown. `--open` opens Chrome and reports whether the OS accepted the request. Render, navigation and original-source verification remain pending until actually checked. Startup failures stop only the child this command started.
+
+### Durable recovery and explicit duty evidence (CLI 0.3.5)
+
+Default checkpoints, mutation intents, runtime-log evidence and Build reviews live
+under `work/lumine-admin` in the invocation directory, with private permissions.
+Explicit persistent output/checkpoint paths take priority. Older automatic
+checkpoints in OS temp storage are copied with their candidate spools to persistent
+storage before resuming; the existing scope/hash checks still apply.
+
+Generic mutations persist their exact operation/account/run/session key before
+sending. A missing receipt leaves that key pending; rerunning the exact command
+reuses it instead of issuing a fresh mutation. Changed bodies or authorities get
+different keys. A canonical receipt is archived privately before printing, and
+the pending pointer closes only after successful output. Existing Featured,
+batch-skip and runtime-log workflows retain their own recovery contracts.
+
+`duty-evidence.json` is local operator evidence, for example:
+
+```json
+{
+  "protocol": 1,
+  "runId": 107,
+  "runReport": { "file": "run-report.json", "bytes": 123, "sha256": "<full digest>" },
+  "requiredDuties": ["effort-levels", "report-browser", "football-coach"],
+  "reading": [{ "file": "bot-chats.txt", "bytes": 456, "sha256": "<full digest>", "complete": true, "readAt": "2026-10-01T00:00:00Z" }],
+  "duties": [{ "id": "effort-levels", "status": "completed", "evidence": [{ "file": "run-report.json", "bytes": 123, "sha256": "<full digest>" }], "note": "All candidates considered; preserve higher-authority levels." }]
+}
+```
+
+Use actual byte counts/digests and only acknowledge work performed. Every evidence
+reference stays inside the run directory. Changed files invalidate reading
+acknowledgments. Effort totals use the canonical report's `subject.effort.set`
+audit counts, including failed attempts separately; unavailable receipts remain
+unknown. Pending browser duties need genuine version-bound interaction evidence.
 
 ### Full management report in Chrome
 
@@ -1039,7 +1075,7 @@ Do this as part of finishing the authorized run; a Markdown path in chat alone
 is insufficient, and no additional confirmation is needed to open the report.
 
 1. Save the complete report as
-   `/private/tmp/twinkle-daily-YYYY-MM-DD/daily-management-report.md`, using the
+   `/Users/mikey/Developer/twinkle/work/daily-management-YYYY-MM-DD/daily-management-report.md`, using the
    run's Bangkok date. Include every required reporting section, coverage gap,
    pending decision and carryover. Reflect later owner decisions accurately.
 2. Render the entire Markdown into a readable HTML page with section links,