@stage5/lumine 0.3.54 → 0.3.58

package/lib/admin-daily.js

@@ -7,6 +7,7 @@ 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";
+import { summarizeOwnerViewport, formatOwnerViewportReport } from "./admin-owner-viewport.js";
 export { dailyRunProgress };
 
 // Multi-step conveniences for the full daily management run. Each one runs
@@ -66,12 +67,15 @@ export function runAdmin(
     result.status === 0 && parsed?.ok === true && !error && !result.error;
   const reads = {
     "energy-budget": [null],
+    "owner-trace": [null],
     news: [null],
     brief: [null],
     "ai-costs": ["monthly", "day"],
     "media-costs": ["monthly"],
     "reward-activity": [null],
+    "reward-diagnostics": [null],
     "reward-review": ["list"],
+    review: ["list"],
     approvals: ["list"],
     todo: ["list"],
     followup: ["list"],
@@ -162,7 +166,7 @@ export function renderBotOutput({ chatMessages, comments }, file) {
   fs.writeFileSync(file, lines.join("\n") + "\n", { mode: 0o600 });
 }
 
-export async function dailyRunGather(options) {
+export async function dailyRunGather(options, { run = runAdmin } = {}) {
   const startedAt = performance.now();
   const dir = ensureDir(
     path.resolve(options.adminOutputDir || options.adminDir || "."),
@@ -171,7 +175,7 @@ export async function dailyRunGather(options) {
   const steps = [];
   const step = (name, args, file) => {
     const outputFile = path.join(dir, file);
-    const res = runAdmin(args, { outputFile, retryRead: true });
+    const res = run(args, { outputFile, retryRead: true });
     steps.push({
       name,
       file,
@@ -195,13 +199,75 @@ export async function dailyRunGather(options) {
     ["reward-activity", "--date", yesterday, "--days", "7"],
     "reward-activity.json",
   );
-  step("reward-review-pending", ["reward-review", "list"], "rr-pending.json");
+  step("reward-diagnostics", ["reward-diagnostics", "--days", "1"], "reward-diagnostics.json");
+  // One pending queue covers every Build approval type. Exhaust its cursor;
+  // an empty/malformed receipt must not look like an empty queue.
+  const buildReviews = { complete: false, pages: 0, items: 0 };
+  let reviewCursor = null;
+  const reviewCursors = new Set();
+  for (;;) {
+    buildReviews.pages += 1;
+    const args = ["review", "list", "--status", "pending"];
+    if (reviewCursor) args.push("--cursor", reviewCursor);
+    const res = step(
+      `build-reviews-page-${buildReviews.pages}`,
+      args,
+      `build-reviews-${buildReviews.pages}.json`,
+    );
+    if (!res.ok) break;
+    const data = res.json?.data;
+    if (
+      data?.filter !== "pending" ||
+      !Array.isArray(data?.items) ||
+      !(data.nextCursor === null ||
+        (typeof data.nextCursor === "string" && /^\d+(\.\d\.\d+)?$/.test(data.nextCursor)))
+    ) {
+      Object.assign(steps[steps.length - 1], {
+        ok: false,
+        error: "Invalid pending Build review page: expected filter, items and nextCursor.",
+      });
+      break;
+    }
+    buildReviews.items += data.items.length;
+    if (data.nextCursor === null) {
+      buildReviews.complete = true;
+      break;
+    }
+    if (reviewCursors.has(data.nextCursor) || buildReviews.pages >= 100) {
+      steps.push({
+        name: "build-reviews-pagination",
+        ok: false,
+        error: reviewCursors.has(data.nextCursor)
+          ? "Build review cursor repeated before exhaustion."
+          : "Build review pagination reached the 100-page limit before exhaustion.",
+      });
+      break;
+    }
+    reviewCursors.add(data.nextCursor);
+    reviewCursor = data.nextCursor;
+  }
   // management approvals (birthdates, teacher signups, meetups) with their
   // flags: a required report section (agent-guides/lumine-admin.md)
   step("approvals-pending", ["approvals", "list", "--status", "pending"], "approvals-pending.json");
   step("todos", ["todo", "list"], "todos.json");
   step("personal-followups", ["followup", "list"], "personal-followups.json");
   step("escalations", ["escalation", "list"], "escalations.json");
+  const wake = step("owner-wake", ["owner-trace", "--since", "24h", "--wake", "--limit", "2000"], "owner-wake.json");
+  // A phone tab can live longer than the daily window. Retain its version,
+  // browser and device context instead of silently calling it unknown.
+  const wakeSessions = step("owner-wake-sessions", ["owner-trace", "--since", "30d", "--type", "session", "--limit", "2000"], "owner-wake-sessions.json");
+  const ownerWake = summarizeOwnerViewport(
+    wake.ok ? wake.json.data : null,
+    wakeSessions.ok ? wakeSessions.json.data : null,
+  );
+  ownerWake.collectionFailures = [
+    ...(!wake.ok ? ["owner-wake"] : []),
+    ...(!wakeSessions.ok ? ["owner-wake-sessions"] : []),
+  ];
+  if (ownerWake.collectionFailures.length) ownerWake.coverage = ownerWake.usableSamples ? "partial" : "unavailable";
+  writeAdminJsonFile(path.join(dir, "owner-wake-summary.json"), ownerWake, { privateFile: true });
+  fs.writeFileSync(path.join(dir, "owner-wake-summary.md"), formatOwnerViewportReport(ownerWake), { mode: 0o600 });
+  steps.push({ name: "owner-wake-summary", file: "owner-wake-summary.json", ok: true });
   step("featured-list", ["featured", "list"], "featured-start.json");
   step(
     "sponsor-applications",
@@ -250,6 +316,13 @@ export async function dailyRunGather(options) {
     durationMs: Math.round(performance.now() - startedAt),
     dir,
     yesterdayUtc: yesterday,
+    buildReviews,
+    ownerWake: {
+      coverage: ownerWake.coverage,
+      truncated: ownerWake.truncated,
+      largeGapCycles: ownerWake.largeGapCycles,
+      reportFile: path.join(dir, "owner-wake-summary.md"),
+    },
     botOutput: {
       complete: botOk,
       pages,

package/lib/admin-duties.js

@@ -37,12 +37,18 @@ export function createDailyReviewState(dir, gather, previous = {}) {
       read: false,
     });
   for (const source of previous.sources || []) {
+    // Keep prior receipts on disk as history, not as current queue evidence or
+    // duplicate reading duties after a new (possibly partial) collection.
+    if (gather.buildReviews && (
+      source.file === "rr-pending.json" || /^build-reviews-\d+\.json$/.test(source.file)
+    )) continue;
     if (!sources.some((current) => current.file === source.file)) sources.push({ ...source, retained: true, read: false });
   }
   return {
     protocol: 1,
     scope: previous.scope || "collection",
     sources,
+    collectionFailures: gather.failed || [],
     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.",
   };
@@ -150,14 +156,16 @@ export function summarizeDailyProgress(dir, state, evidence = {}) {
   const incomplete = duties
     .filter((item) => item.status !== "completed")
     .map((item) => item.id);
+  const collectionFailures = state.collectionFailures || [];
   const complete =
-    sources.every((item) => item.read) && incomplete.length === 0;
+    collectionFailures.length === 0 && sources.every((item) => item.read) && incomplete.length === 0;
   return {
     scope: state.scope || "declared-duties",
     coverageBasis: "declared sources and duties only",
     canonicalRun,
     effortAssignments,
     sources,
+    collectionFailures,
     duties,
     complete,
     reading: {

package/lib/admin-owner-trace.js

@@ -16,12 +16,13 @@ export const OWNER_TRACE_PERF_TYPES = [
   "scroll-perf",
   "scroll-frame",
   "wake",
+  "wake-viewport",
 ];
 
 // --wake: the session headers and the wake profiles (what the site did in the
 // 20 s after each load or return to the tab), to compare Wi-Fi and cellular
-// wakes (the server tags both with the network).
-export const OWNER_TRACE_WAKE_TYPES = ["session", "wake"];
+// wakes. Server network tags describe the upload, which can follow a switch.
+export const OWNER_TRACE_WAKE_TYPES = ["session", "wake", "wake-viewport", "trace-dropped"];
 
 const MAX_LIMIT = 2000;
 
@@ -159,6 +160,8 @@ export function describeOwnerTraceEvent(event) {
       return describeScrollFrame(data);
     case "wake":
       return describeWake(data);
+    case "wake-viewport":
+      return describeViewport(data);
     case "stall":
       return `main thread blocked ${data.ms}ms${data.n > 1 ? ` (${data.n} stalls, ${data.total}ms blocked over ${data.span}ms)` : ""}`;
     case "page-load": {
@@ -179,13 +182,29 @@ export function describeOwnerTraceEvent(event) {
   }
 }
 
-// The network an upload came from: v4/v6 plus an opaque prefix hash. The same
-// tag = the same network (home Wi-Fi vs the carrier).
+// The network an upload came from: v4/v6 plus an opaque prefix hash. This does
+// not establish whether the device used Wi-Fi or cellular when it captured.
 function describeNet(net) {
   if (!net?.id) return "";
   return `net v${net.v}:${net.id}`;
 }
 
+function describeViewport(data) {
+  if (data.error) return `geometry unavailable (${data.error})`;
+  const visual = isPlainObject(data.visual) ? data.visual : {};
+  const nav = isPlainObject(data.nav) ? data.nav : {};
+  const focus = isPlainObject(data.focus) ? data.focus : {};
+  return [
+    `v${data.version || "?"} cycle ${data.cycle ?? "?"} ${data.phase || "?"} +${data.elapsedMs ?? "?"}ms`,
+    `window ${data.window?.height ?? "?"} root ${data.root?.height ?? "?"}`,
+    `visual ${visual.height ?? "?"} top ${visual.offsetTop ?? "?"} scale ${visual.scale ?? "?"}`,
+    `nav bottom ${nav.bottom ?? "?"} (${nav.position || "absent"})`,
+    `inset ${data.inset ?? "?"} focus ${focus.tag || "none"}${focus.type ? `:${focus.type}` : ""}`,
+    `scroll ${data.root?.scrollTop ?? "?"}`,
+    data._trimmed ? `trimmed ${JSON.stringify(data._trimmed)}` : "",
+  ].filter(Boolean).join(" · ");
+}
+
 // What the site did in the window after a load or a return to the tab.
 // A field the server cut to "[cut N chars]" arrives as a string: every list or
 // object is checked before use, so one trimmed row never breaks the output.

package/lib/admin-owner-viewport.js

@@ -0,0 +1,113 @@
+// Read-only interpretation of bounded wake geometry. Large gaps are leads,
+// never a diagnosis or evidence that a browser workaround is safe.
+export function summarizeOwnerViewport(data, sessionData = data) {
+  const events = Array.isArray(data?.events) ? data.events : [];
+  const sessions = new Map(
+    [...(sessionData?.events || []), ...events].filter(e => e.type === "session").map(e => [e.sessionId, e.data || {}]),
+  );
+  const cycles = new Map();
+  const usableBySession = new Map();
+  let unavailable = 0;
+  let dropped = 0;
+  for (const event of events) {
+    if (event.type === "trace-dropped") dropped += Number(event.data?.count) || 0;
+    if (event.type !== "wake-viewport") continue;
+    const d = event.data || {};
+    if (d.error || d.v !== 1 || d._trimmed || !d.window || !d.root || !d.focus) {
+      unavailable += 1;
+      continue;
+    }
+    usableBySession.set(event.sessionId, (usableBySession.get(event.sessionId) || 0) + 1);
+    const key = `${event.sessionId}:${d.cycle}`;
+    const header = sessions.get(event.sessionId);
+    let cycle = cycles.get(key);
+    if (!cycle) {
+      cycle = {
+        sessionId: event.sessionId, cycle: d.cycle, version: d.version || header?.version || "unknown",
+        platform: header?.platform || "unknown", ua: header?.ua || null,
+        sessionHeaderAvailable: Boolean(header), samples: 0, settledSamples: 0,
+        largeGapSamples: 0, backgroundSamples: 0, lastScheduledMs: 0,
+        maxRootGap: null, maxVisualGap: null, firstLargeGapMs: null, lastLargeGapMs: null, examples: [],
+      };
+      cycles.set(key, cycle);
+    }
+    cycle.samples += 1;
+    if (d.phase === "background") cycle.backgroundSamples += 1;
+    cycle.lastScheduledMs = Math.max(cycle.lastScheduledMs, Number(d.scheduledMs) || 0);
+    if (d.phase !== "settle" || d.scheduledMs < 1000 || d.visibility !== "visible") continue;
+    cycle.settledSamples += 1;
+    const nav = d.nav;
+    // The desktop header is fixed at the TOP. Only a nav anchored to bottom:0
+    // can support this candidate. Keyboard/zoom/hidden states stay in raw data.
+    if (!nav || nav.position !== "fixed" || parseFloat(nav.bottomStyle) !== 0 || nav.height <= 0 || nav.display === "none" ||
+        nav.visibility === "hidden" || nav.transform !== "none" ||
+        !d.visual || !Number.isFinite(d.visual.scale) || Math.abs(d.visual.scale - 1) > 0.01 ||
+        d.focus.editable || ["input", "textarea", "iframe"].includes(d.focus.tag) || d.inset !== 0) continue;
+    if (![nav.bottom, d.root.height, d.visual.height, d.visual.offsetTop, d.elapsedMs].every(Number.isFinite)) continue;
+    const rootGap = Math.round(d.root.height - nav.bottom);
+    const visualGap = Math.round(d.visual.height + d.visual.offsetTop - nav.bottom);
+    cycle.maxRootGap = Math.max(cycle.maxRootGap ?? -Infinity, rootGap);
+    cycle.maxVisualGap = Math.max(cycle.maxVisualGap ?? -Infinity, visualGap);
+    if (Math.max(rootGap, visualGap) >= 100) {
+      cycle.largeGapSamples += 1;
+      cycle.firstLargeGapMs = Math.min(cycle.firstLargeGapMs ?? Infinity, d.elapsedMs);
+      cycle.lastLargeGapMs = Math.max(cycle.lastLargeGapMs ?? -Infinity, d.elapsedMs);
+      if (cycle.examples.length < 3) cycle.examples.push({
+        seq: event.seq, clientTime: event.clientTime, path: event.path,
+        elapsedMs: d.elapsedMs, rootGap, visualGap,
+      });
+    }
+  }
+  const rows = [...cycles.values()];
+  const viewportEvents = events.filter(e => e.type === "wake-viewport").length;
+  const clients = [...new Set(events.map(e => e.sessionId))].map(sessionId => {
+    const own = events.filter(e => e.sessionId === sessionId);
+    const header = sessions.get(sessionId);
+    return {
+      sessionId, version: header?.version || own.find(e => e.type === "wake-viewport")?.data?.version || "unknown",
+      platform: header?.platform || "unknown",
+      viewportSupport: header ? header.viewportTrace === 1 : null,
+      geometrySamples: own.filter(e => e.type === "wake-viewport").length,
+      usableSamples: usableBySession.get(sessionId) || 0,
+    };
+  });
+  const missingHeaders = rows.filter(c => !c.sessionHeaderAvailable).length;
+  const clientsWithoutGeometry = clients.filter(c => !c.usableSamples).length;
+  const usableSamples = viewportEvents - unavailable;
+  const partial = Boolean(data?.truncated || sessionData?.truncated || unavailable || dropped || missingHeaders || clientsWithoutGeometry);
+  return {
+    schema: 1, since: data?.since ?? null,
+    coverage: !usableSamples ? "unavailable" : partial ? "partial" : "observed",
+    truncated: Boolean(data?.truncated), sessionHeadersTruncated: Boolean(sessionData?.truncated),
+    viewportEvents, usableSamples, unavailableSamples: unavailable, droppedEvents: dropped,
+    wakeProfiles: events.filter(e => e.type === "wake").length,
+    clients, clientsWithoutGeometry,
+    cycles: rows, cyclesMissingHeaders: missingHeaders,
+    cyclesReaching20s: rows.filter(c => c.lastScheduledMs >= 20_000).length,
+    largeGapCycles: rows.filter(c => c.largeGapSamples > 0).length,
+    // Timers can all be released together after a stall. Scheduled times alone
+    // do not establish separate observations; require actual time separation.
+    repeatedLargeGapCycles: rows.filter(c => c.largeGapSamples >= 2 && c.lastLargeGapMs - c.firstLargeGapMs >= 500).length,
+    note: "A >=100px settled gap is an investigation lead, not a proven defect. Normal browser chrome, viewport offsets and rendering state still require comparison. No samples means unavailable, not healthy. Wake network tags identify the upload network, not necessarily the network at capture.",
+  };
+}
+
+export function formatOwnerViewportReport(summary) {
+  const lines = [
+    "# Owner wake viewport follow-up", "",
+    `Coverage: **${summary.coverage}**. ${summary.usableSamples} usable geometry samples (${summary.viewportEvents} raw events) across ${summary.cycles.length} load/return cycles; ${summary.cyclesReaching20s} reached the 20-second sample.`, "",
+    `Observed clients: ${[...new Set(summary.clients.map(c => `${c.version} (${c.platform}; geometry support ${c.viewportSupport === null ? "unknown" : c.viewportSupport ? "yes" : "no"})`))].join(", ") || "none"}.`, "",
+    `Collection failures: ${summary.collectionFailures?.join(", ") || "none"}.`, "",
+    `Large-gap candidates: ${summary.largeGapCycles} cycles; ${summary.repeatedLargeGapCycles} had settled bottom-nav gaps >=100px at least 500ms apart in actual time, no focused input, no app keyboard inset and scale 1.`, "",
+    `Missing/trimmed geometry: ${summary.unavailableSamples}; clients without usable geometry: ${summary.clientsWithoutGeometry}; reported dropped events: ${summary.droppedEvents}; cycles without session context: ${summary.cyclesMissingHeaders}; truncated trace: ${summary.truncated}; truncated session history: ${summary.sessionHeadersTruncated}.`, "",
+    summary.note, "",
+    "Read owner-wake.json and owner-wake-sessions.json alongside this summary. Compare affected and ordinary cycles within the same client/browser version. Distinguish viewport height changes, viewport panning and nav displacement; correlate the wake performance profile and its upload network tag. Record the evidence and next action in the daily report even when coverage is unavailable.", "",
+    "| Client | Platform | Cycle | Samples | Settled | Large gap | Max root gap | Max visual gap |",
+    "| --- | --- | --- | ---: | ---: | ---: | ---: | ---: |",
+  ];
+  for (const c of summary.cycles) {
+    const safe = v => String(v).replace(/[|\r\n]/g, " ");
+    lines.push(`| ${safe(c.version)} | ${safe(c.platform)} | ${safe(c.sessionId).slice(0, 8)}:${c.cycle} | ${c.samples} | ${c.settledSamples} | ${c.largeGapSamples} | ${c.maxRootGap ?? "unavailable"} | ${c.maxVisualGap ?? "unavailable"} |`);
+  }
+  return lines.join("\n") + "\n";
+}