@stage5/lumine 0.3.3 → 0.3.5

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage5/lumine",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "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-30T02:34:09.690Z
+Generated: 2026-09-30T09:55:20.738Z
 
 ## Notes
 - This SDK is injected into Build iframes via the Build preview/runtime.
@@ -551,6 +551,26 @@ const result = await Twinkle.ai.chat({ message, history: chatHistory, systemProm
   - Only one music generation per viewer may run at a time (code ai_music_generation_in_progress). A retry with the same requestId returns the finished result without paying again (replayed: true), or code music_in_progress while it is still being made.
   - Generation usually takes one to three minutes; the SDK timeout defaults to 600000ms. Show progress UI while waiting.
   - Example: const song = await Twinkle.ai.generateMusic({ prompt: 'Warm lo-fi hip hop with dusty drums, a mellow Rhodes and rain in the background', instrumental: true }); audio.src = song.url;
+- async generateSpeech({ text, voice, language, requestId, timeoutMs } = {}) | scopes: none
+  - Returns: { success, asset, url, mimeType, durationSeconds, alignment, text, voice, model, requestId, replayed?, aiUsagePolicy }
+  - Generate spoken audio with Eleven v4 and save it in the viewer's Twinkle.files. New generations use AI Battery.
+  - Signed-in viewers only. Each new generation uses AI Battery; show this before the viewer starts voice interaction.
+  - text: 1–2,000 characters. voice: warm (default), bright, or calm. language: optional ISO language code such as en.
+  - The MP3 is saved in the viewer's Twinkle.files and counts toward storage. Replay the saved URL to listen again without another AI request.
+  - alignment contains provider character timing for subtitles or animation. Respect Twinkle tab mute and browser playback controls.
+  - Reuse requestId after a lost response. Completed audio replays the saved asset and settles the same billing receipt without regeneration or duplicate charges.
+  - Only one speech or transcription request per viewer runs at a time. SDK timeout defaults to 180000ms.
+  - Example: const speech = await Twinkle.ai.generateSpeech({ text: 'Welcome to our club!', voice: 'warm', language: 'en' }); audio.src = speech.url;
+- async transcribeAudio({ audioBase64, language, requestId, timeoutMs } = {}) | scopes: none
+  - Returns: { success, text, words: [{ text, start, end }], language, durationSeconds, model, requestId, replayed?, aiUsagePolicy }
+  - Recognize a short recording with ElevenLabs Scribe v2. New recognition requests use AI Battery.
+  - Signed-in viewers only. New recognition requests use AI Battery. Each successful response includes the canonical aiUsagePolicy.
+  - audioBase64 is plain base64 of a mono 16-bit PCM WAV at 8–48 kHz, between 0.2 and 30 seconds. The server validates the actual duration.
+  - Request microphone permission only after a viewer action, show a recording indicator, and stop microphone tracks when recording ends or the app closes.
+  - Audio is sent to the recognition provider without saving a Twinkle recording asset. Let the viewer review or correct the transcript before using it as their message.
+  - Reuse requestId after a lost response. Completed transcripts replay without recognition or duplicate charges. Word recognition is not a pronunciation score.
+  - Only one speech or transcription request per viewer runs at a time. SDK timeout defaults to 180000ms.
+  - Example: const transcript = await Twinkle.ai.transcribeAudio({ audioBase64: wavBase64, language: 'en' }); input.value = transcript.text;
 - onImageGenerationStatus(listener) | scopes: none
   - Returns: unsubscribe function
   - Subscribe to real-time image generation status events forwarded into the build iframe.

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,