@quickchatai/quickreview 0.0.0-stage → 1.1.0

package/src/archive/prfiles.ts

@@ -0,0 +1,406 @@
+// The per-PR INVENTORY (docs/archiving.md §7.2): which live files
+// belong to a closed PR, found without a synchronous walk.
+//
+//   - One async `readdir` of each live directory the per-PR artifacts sit in,
+//     grouped by PR (`listLiveTree`) — never one listing per PR per directory,
+//     so a pass over N PRs costs the directories once plus each PR's own files.
+//   - A recursive async walk only inside one PR's own dirs (its pi session
+//     dir, its round pass dirs, its inject dir's `.done/` and `.terminal/`).
+//   - Session-command payloads come from the DATABASE (the PR's terminal
+//     command rows, `payload_path` under `state/session-commands/`), never
+//     from a listing of that directory (thousands of uuid files, none named
+//     by PR).
+//
+// The plan (`plan.ts`) tallies this inventory; an archive pass
+// (`prarchive.ts`) moves it. One definition of §7.2, two readers.
+import type { Dirent } from "node:fs";
+import { lstat, readdir } from "node:fs/promises";
+import { dirname, join, resolve, sep } from "node:path";
+import { performance } from "node:perf_hooks";
+import type { StateStore } from "../state.js";
+
+/** The per-PR artifact classes that LEAVE the live tree (§7.2). */
+export const ARTIFACT_CLASSES = [
+  "transcripts",
+  "round_prompts",
+  "session_commands",
+  "findings",
+  "posting_receipts",
+  "round_files",
+  "session_files",
+  "inject_done",
+  "stale_injects",
+  "verdicts",
+  "live_logs",
+  "lens_sessions",
+] as const;
+export type ArtifactClass = (typeof ARTIFACT_CLASSES)[number];
+
+/** The classes archived as one gzip per file whatever their size, so an
+ * extraction lays a worker round out whole under `files/state/<tree>/pr-<n>/r<k>/`
+ * (a lens JSONL is a pi session `qcr open` reads; it must not split between a
+ * bundle and a `files/` gzip by its size). Both trees are written by the
+ * per-round workers. */
+export const OWN_GZIP_CLASSES: ReadonlySet<ArtifactClass> = new Set(["live_logs", "lens_sessions"]);
+
+/** The non-transcript classes; most are bundled, `OWN_GZIP_CLASSES` get standalone gzips. */
+export type SmallClass = Exclude<ArtifactClass, "transcripts">;
+
+/** Measures the synchronous spans it is handed. */
+export class SpanMeter {
+  max = 0;
+  measure<T>(fn: () => T): T {
+    const t0 = performance.now();
+    try {
+      return fn();
+    } finally {
+      const d = performance.now() - t0;
+      if (d > this.max) this.max = d;
+    }
+  }
+}
+
+/** Directory entries, [] when the directory does not exist; any other
+ * failure is thrown — a listing that could not be read is not "empty". */
+export async function listDir(dir: string): Promise<Dirent[]> {
+  try {
+    return await readdir(dir, { withFileTypes: true });
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return [];
+    throw err;
+  }
+}
+
+/** A regular file's size; null when it is gone or not a regular file. */
+export async function fileSize(path: string): Promise<number | null> {
+  try {
+    const st = await lstat(path);
+    return st.isFile() ? st.size : null;
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw err;
+  }
+}
+
+/** Every regular file under `dir` (recursive, symlinks never followed); the
+ * directories met are pushed to `dirs` deepest-last (the caller reverses). */
+export async function walkFiles(
+  dir: string,
+  out: string[],
+  signal?: AbortSignal,
+  dirs?: string[],
+): Promise<void> {
+  signal?.throwIfAborted();
+  for (const e of await listDir(dir)) {
+    const p = join(dir, e.name);
+    if (e.isDirectory()) {
+      dirs?.push(p);
+      await walkFiles(p, out, signal, dirs);
+    } else if (e.isFile()) out.push(p);
+  }
+}
+
+export type Groups = Map<number, string[]>;
+const push = (g: Groups, pr: number, path: string): void => {
+  const list = g.get(pr);
+  if (list) list.push(path);
+  else g.set(pr, [path]);
+};
+
+/** Group a listing's entries by the PR number `re` captures — one pass over
+ * the listing, a map lookup per PR after (linear in the listing). */
+export function groupBy(
+  meter: SpanMeter,
+  dir: string,
+  entries: readonly Dirent[],
+  re: RegExp,
+  want: "file" | "dir" | "any" = "file",
+): Groups {
+  return meter.measure(() => {
+    const g: Groups = new Map();
+    for (const e of entries) {
+      if (want === "file" && !e.isFile()) continue;
+      if (want === "dir" && !e.isDirectory()) continue;
+      if (want === "any" && !e.isFile() && !e.isDirectory()) continue;
+      const m = re.exec(e.name);
+      if (m) push(g, Number(m[1]), join(dir, e.name));
+    }
+    return g;
+  });
+}
+
+export const PR_DIR = /^pr-(\d+)$/;
+const PR_PREFIX = /^pr-(\d+)-/;
+const ROUND_PROMPT = /^pr-(\d+)-round-\d+\.md$/;
+/** Every per-round entry at the top of `state/` — the daemon's (`-passes/`,
+ * `-review.md`, `-comments.json`) and any a session wrote beside them (e.g. a
+ * `pr-<n>-round-<k>-body.md`), so none is left live under an `archived` row. */
+const STATE_ROUND = /^pr-(\d+)-round-\d+-.+$/;
+/** Any top-level `state/` entry named for a PR. Those no class claims are
+ * reported by the plan (`unclassified`) and kept live — never moved on a
+ * guess, never invisible. */
+const STATE_PR = /^pr-(\d+)(?:[-.]|$)/;
+const SESSION_PROMPT = /^pr-(\d+)\.md$/;
+const SESSION_STATE = /^pr-(\d+)\.(?:json|bridge-.+\.json)$/;
+/** The round-progress snapshot and its append-only transition log
+ * (`.jsonl`, plus its one rotated generation `.jsonl.1`). */
+const PROGRESS = /^pr-(\d+)\.(?:json|jsonl|jsonl\.1)$/;
+const LEDGER = /^pr-(\d+)\.md$/;
+const VERDICT = /(?:^|-)pr-(\d+)-/;
+const INJECT_RECOVERY = /\.operator-recovery-/;
+
+/** Session-command statuses whose payload may leave (§7.2): terminal only. */
+export const TERMINAL_COMMAND_STATUSES = ["acked", "cancelled", "failed"] as const;
+
+/** The live directories, each listed ONCE and grouped by PR. */
+export interface LiveListing {
+  sessionDirs: Groups;
+  injectDirs: Groups;
+  archiveDirs: Groups;
+  /** The flat per-PR state files and dirs, by class (`ledger` = the live
+   * ledger, snapshotted and kept). */
+  flat: Array<[SmallClass | "ledger", Groups]>;
+  /** Top-level `state/` entries named for a PR that no class claims: kept
+   * live, reported by the plan. */
+  unclassified: Groups;
+}
+
+/** The per-round worker trees under `state/`, each holding one
+ * `pr-<n>/r<k>/` dir per PR round: the LiveEvent logs, and the lens passes'
+ * session JSONLs with their ledger. */
+export const LIVE_TREES = [
+  ["live_logs", "live"],
+  ["lens_sessions", "lens"],
+] as const satisfies ReadonlyArray<readonly [SmallClass, string]>;
+
+/** List every live directory once. Throws when one cannot be listed (an
+ * unreadable listing is never "nothing there"). */
+export async function listLiveTree(
+  root: string,
+  sessionsRoot: string,
+  meter: SpanMeter = new SpanMeter(),
+): Promise<LiveListing> {
+  const stateDir = join(root, "state");
+  const sessionDirs = groupBy(meter, sessionsRoot, await listDir(sessionsRoot), PR_DIR, "dir");
+  const injectRoot = dirname(injectDirOf(root, 0));
+  const injectDirs = groupBy(meter, injectRoot, await listDir(injectRoot), PR_DIR, "dir");
+  const archiveRoot = join(root, "archive");
+  const archiveDirs = groupBy(meter, archiveRoot, await listDir(archiveRoot), PR_DIR, "dir");
+  const flat: LiveListing["flat"] = [];
+  const listing = async (
+    cls: SmallClass | "ledger",
+    dir: string,
+    re: RegExp,
+    want: "file" | "dir" | "any" = "file",
+  ): Promise<void> => {
+    flat.push([cls, groupBy(meter, dir, await listDir(dir), re, want)]);
+  };
+  await listing("round_prompts", join(stateDir, "round-prompts"), ROUND_PROMPT);
+  await listing("findings", join(stateDir, "findings"), PR_PREFIX);
+  await listing("posting_receipts", join(stateDir, "posting-receipts"), PR_PREFIX);
+  // `state/` itself, listed once: the per-round entries, and what is left.
+  const stateEntries = await listDir(stateDir);
+  flat.push(["round_files", groupBy(meter, stateDir, stateEntries, STATE_ROUND, "any")]);
+  const unclassified = groupBy(
+    meter,
+    stateDir,
+    stateEntries.filter((e) => !STATE_ROUND.test(e.name)),
+    STATE_PR,
+    "any",
+  );
+  await listing("session_files", join(stateDir, "session-prompts"), SESSION_PROMPT);
+  await listing("session_files", join(stateDir, "sessions"), SESSION_STATE);
+  await listing("session_files", join(stateDir, "round-progress"), PROGRESS);
+  await listing("verdicts", join(root, "verdict", "processed"), VERDICT, "any");
+  await listing("verdicts", join(root, "verdict", "failed"), VERDICT, "any");
+  await listing("ledger", join(stateDir, "ledgers"), LEDGER);
+  for (const [cls, tree] of LIVE_TREES) await listing(cls, join(stateDir, tree), PR_DIR, "dir");
+  return { sessionDirs, injectDirs, archiveDirs, flat, unclassified };
+}
+
+/** `inject/pr-<n>/`, the PR session's drop-box. The archiver only LISTS it
+ * (an undelivered top-level wake holds the PR) and archives what was
+ * consumed; it never puts a wake there. */
+export const injectDirOf = (root: string, pr: number): string => join(root, "inject", `pr-${pr}`);
+
+/** The top-level `*.md` files of a PR's inject dir — its undelivered wakes
+ * (an eligibility input). [] when the dir is absent; throws when it cannot be
+ * listed. */
+export async function topLevelInjectFiles(injectDir: string | undefined): Promise<string[]> {
+  if (!injectDir) return [];
+  return (await listDir(injectDir))
+    .filter((e) => e.isFile() && e.name.endsWith(".md"))
+    .map((e) => join(injectDir, e.name));
+}
+
+/** A session-command row whose payload the bundle carries. */
+export interface PayloadCommand {
+  id: string;
+  kind: string;
+  round_no: number | null;
+  status: string;
+  payload_sha256: string;
+}
+
+export interface InventoryFile {
+  path: string;
+  size: number;
+}
+
+export interface SmallFile extends InventoryFile {
+  cls: SmallClass;
+  /** For a session-command payload: the row it belongs to. */
+  command?: PayloadCommand;
+}
+
+/** What one PR has in the live tree (§7.2). */
+export interface PrInventory {
+  pr: number;
+  /** Every `*.jsonl` under `<sessionsRoot>/pr-<n>/` (not only the newest). */
+  transcripts: InventoryFile[];
+  /** The bundled classes. */
+  small: SmallFile[];
+  /** `state/ledgers/pr-<n>.md` — snapshotted into the bundle, KEPT live. */
+  ledger: InventoryFile | null;
+  /** `archive/pr-<n>/session.jsonl`, the legacy uncompressed copy (§7.5). */
+  legacy: InventoryFile | null;
+  /** `archive/pr-<n>/` — where the PR's archive lives (absent until made). */
+  archiveDir: string;
+  /** Directories the pass may empty, deepest first (removed with a
+   * non-recursive rmdir only). */
+  dirs: string[];
+}
+
+/**
+ * One PR's live files, from the pass's listing. `staleInjects` are the
+ * top-level inject files the eligibility rule found TERMINAL (leftovers of a
+ * failed round command, §7.2). Throws when a dir of the PR cannot be walked.
+ */
+export async function prInventory(
+  listing: LiveListing,
+  pr: number,
+  opts: {
+    store: StateStore;
+    root: string;
+    staleInjects: readonly string[];
+    signal?: AbortSignal;
+    meter?: SpanMeter;
+  },
+): Promise<PrInventory> {
+  const { root, signal } = opts;
+  const meter = opts.meter ?? new SpanMeter();
+  const commandsDir = resolve(root, "state", "session-commands") + sep;
+  const inv: PrInventory = {
+    pr,
+    transcripts: [],
+    small: [],
+    ledger: null,
+    legacy: null,
+    archiveDir: listing.archiveDirs.get(pr)?.[0] ?? join(root, "archive", `pr-${pr}`),
+    dirs: [],
+  };
+  const seen = new Set<string>();
+  const addSmall = (f: SmallFile): void => {
+    if (seen.has(f.path)) return;
+    seen.add(f.path);
+    inv.small.push(f);
+  };
+  // Transcripts: every *.jsonl under pi-sessions/pr-<n>/, not just the newest.
+  for (const dir of listing.sessionDirs.get(pr) ?? []) {
+    const files: string[] = [];
+    const dirs: string[] = [];
+    await walkFiles(dir, files, signal, dirs);
+    for (const f of files) {
+      if (!f.endsWith(".jsonl")) continue;
+      const size = await fileSize(f);
+      if (size !== null) inv.transcripts.push({ path: f, size });
+    }
+    inv.dirs.push(...dirs.reverse(), dir);
+  }
+  // The flat per-PR state files (and the passes dirs, walked).
+  for (const [cls, groups] of listing.flat) {
+    for (const p of groups.get(pr) ?? []) {
+      const expanded = await inventoryFiles(p, signal);
+      for (const f of expanded.files) {
+        if (cls === "ledger") {
+          if (f.path === p) inv.ledger = f;
+        } else addSmall({ ...f, cls });
+      }
+      inv.dirs.push(...expanded.dirs);
+    }
+  }
+  // Session-command payloads: the PR's terminal command rows, under
+  // state/session-commands/ only.
+  const rows = meter.measure(
+    () =>
+      opts.store.db
+        .prepare(
+          `SELECT id, kind, round_no, status, payload_path, payload_sha256 FROM session_commands
+            WHERE pr = ? AND status IN (${TERMINAL_COMMAND_STATUSES.map((s) => `'${s}'`).join(", ")})
+            ORDER BY created_at, id`,
+        )
+        .all(pr) as Array<PayloadCommand & { payload_path: string }>,
+  );
+  for (const { payload_path, ...command } of rows) {
+    if (!resolve(payload_path).startsWith(commandsDir)) continue;
+    const size = await fileSize(payload_path);
+    if (size !== null)
+      addSmall({ path: resolve(payload_path), size, cls: "session_commands", command });
+  }
+  // inject/pr-<n>/: delivered wakes (.done/, .terminal/), quarantines, and the
+  // top-level leftovers whose command row is terminal.
+  const injectDir = listing.injectDirs.get(pr)?.[0];
+  if (injectDir) {
+    for (const e of await listDir(injectDir)) {
+      const p = join(injectDir, e.name);
+      if (e.isDirectory() && (e.name === ".done" || e.name === ".terminal")) {
+        const walked = await inventoryFiles(p, signal);
+        for (const f of walked.files) addSmall({ path: f.path, size: f.size, cls: "inject_done" });
+        inv.dirs.push(...walked.dirs);
+      } else if (e.isFile() && INJECT_RECOVERY.test(e.name)) {
+        const s = await fileSize(p);
+        if (s !== null) addSmall({ path: p, size: s, cls: "inject_done" });
+      }
+    }
+    for (const f of opts.staleInjects) {
+      const s = await fileSize(f);
+      if (s !== null) addSmall({ path: f, size: s, cls: "stale_injects" });
+    }
+    inv.dirs.push(injectDir);
+  }
+  // The legacy uncompressed copy in archive/pr-<n>/.
+  const archiveDir = listing.archiveDirs.get(pr)?.[0];
+  if (archiveDir) {
+    const legacy = join(archiveDir, "session.jsonl");
+    const s = await fileSize(legacy);
+    if (s !== null) inv.legacy = { path: legacy, size: s };
+  }
+  return inv;
+}
+
+/** An unreadable inject listing is unknown, never an empty list. */
+export async function knownInjectFiles(dir: string | undefined): Promise<string[] | null> {
+  try {
+    return await topLevelInjectFiles(dir);
+  } catch {
+    return null;
+  }
+}
+
+/** Expand one inventory candidate with the same plain-file admission everywhere. */
+export async function inventoryFiles(
+  path: string,
+  signal?: AbortSignal,
+): Promise<{ files: Array<{ path: string; size: number }>; dirs: string[] }> {
+  const size = await fileSize(path);
+  if (size !== null) return { files: [{ path, size }], dirs: [] };
+  const paths: string[] = [],
+    dirs: string[] = [];
+  await walkFiles(path, paths, signal, dirs);
+  const files: Array<{ path: string; size: number }> = [];
+  for (const child of paths) {
+    const bytes = await fileSize(child);
+    if (bytes !== null) files.push({ path: child, size: bytes });
+  }
+  return { files, dirs: [...dirs.reverse(), path] };
+}

package/src/archive/report.ts

@@ -0,0 +1,252 @@
+import { STORE_LABELS, storeEntries } from "./status.js";
+import { archivedEventTotal } from "./rows.js";
+// `qcr archive status [--plan]` (docs/archiving.md §11): the
+// archiver's block as the daemon published it, the archive ledger, the
+// policy every `[archive]` knob sets — and, with --plan, the plan detail:
+// per-artifact counts and bytes, every held PR with its reason, the orphans.
+// Read-only: it renders, it moves nothing.
+import { readFileSync } from "node:fs";
+import type { StateStore } from "../state.js";
+import type { ArchivePolicy } from "./archiver.js";
+import { ARTIFACT_CLASSES, type ArchivePlan } from "./plan.js";
+import {
+  archiveStatusLine,
+  fmtBytes,
+  fmtCount,
+  readArchiveStatus,
+  storePhrase,
+  type ArchiveStatusRead,
+} from "./status.js";
+
+export interface ArchiveLedgerSummary {
+  /** `archive_prs` rows by state. */
+  by_state: Record<string, number>;
+  /** Event rows moved to the archive DB, all time. */
+  archived_event_rows: number;
+  /** The mover's watermarks, as recorded (absent = nothing moved). */
+  marks: Record<string, unknown>;
+}
+
+/** The archive ledger in live state.db — small tables, read whole. */
+export function archiveLedgerSummary(store: StateStore): ArchiveLedgerSummary {
+  const by_state: Record<string, number> = {};
+  for (const r of store.db
+    .prepare("SELECT state, COUNT(*) AS n FROM archive_prs GROUP BY state")
+    .all() as Array<{ state: string; n: number }>)
+    by_state[r.state] = r.n;
+  const marks: Record<string, unknown> = {};
+  for (const r of store.db
+    .prepare("SELECT name, value FROM archive_marks ORDER BY name")
+    .all() as Array<{
+    name: string;
+    value: unknown;
+  }>)
+    marks[r.name] = r.value;
+  return { by_state, archived_event_rows: archivedEventTotal(store), marks };
+}
+
+const pad = (s: string, n: number): string => (s.length >= n ? s : s + " ".repeat(n - s.length));
+
+export function policyLine(p: ArchivePolicy): string {
+  return (
+    `policy: mode ${p.mode} · files and deliveries after ${p.afterDays} d · events after ${p.eventsAfterDays} d · ` +
+    `every ${p.intervalMs / 1000} s · start delay ${p.startDelayMs / 60_000} min · tick budget ${p.tickBudgetMs / 1000} s · ` +
+    `≤ ${p.maxPrsPerTick} PR(s)/tick · ≤ ${fmtBytes(p.maxBytesPerS)}/s · headroom ${fmtBytes(p.diskHeadroomBytes)} · ` +
+    `DB batch ${p.dbBatchRows} rows · gzip ${p.gzipLevel} · ` +
+    `worker logs kept ${p.liveRetentionMs / 86_400_000} d · ` +
+    `worker-log cap ${p.liveCapBytes > 0 ? fmtBytes(p.liveCapBytes) : "off"}`
+  );
+}
+
+function planLines(plan: ArchivePlan): string[] {
+  const out: string[] = [];
+  const r = plan.registry;
+  out.push(
+    `plan (computed here at ${plan.computed_at}, took ${plan.took_ms} ms, longest synchronous span ${plan.max_sync_span_ms} ms):`,
+  );
+  out.push(
+    `  registry: ${r.prs} PR(s) — ${r.open} open, ${r.closed} closed: ${r.waiting} inside the ${plan.after_days}-day window, ` +
+      `${r.eligible} eligible, ${r.held} held${r.archived ? `, ${r.archived} archived already` : ""}`,
+  );
+  out.push(
+    `  backlog: ${plan.backlog.prs} PR(s) · ${fmtBytes(plan.backlog.bytes)} · ` +
+      `${fmtCount(plan.backlog.event_rows)} event row(s) older than ${plan.events.cutoff} · ` +
+      `${fmtCount(plan.backlog.delivery_rows)} delivery row(s) older than ${plan.deliveries.cutoff}`,
+  );
+  out.push(`  artifacts over ${plan.candidates.length} PR(s) with live files:`);
+  for (const cls of ARTIFACT_CLASSES) {
+    const t = plan.artifacts[cls];
+    out.push(`    ${pad(cls, 18)} ${pad(String(t.files), 8)} file(s)  ${fmtBytes(t.bytes)}`);
+  }
+  out.push(
+    `  kept live, snapshotted: ${plan.ledger_snapshots.files} ledger(s), ${fmtBytes(plan.ledger_snapshots.bytes)}`,
+  );
+  out.push(
+    `  legacy archive/pr-<n>/session.jsonl copies to check as duplicates: ${plan.legacy_copies.files}, ${fmtBytes(plan.legacy_copies.bytes)}`,
+  );
+  if (plan.unclassified && plan.unclassified.files > 0)
+    out.push(
+      `  KEPT LIVE, no class claims them: ${plan.unclassified.files} state/pr-<n>-* file(s) of eligible PRs, ${fmtBytes(plan.unclassified.bytes)} — ` +
+        `${plan.unclassified.first.join(", ")}${plan.unclassified.files > plan.unclassified.first.length ? ", …" : ""}`,
+    );
+  if (plan.empty.length > 0)
+    out.push(
+      `  ${plan.empty.length} eligible PR(s) with nothing live to move (a zero-file archived row each)`,
+    );
+  const kinds = Object.entries(plan.events.by_kind ?? {}).sort((a, b) => b[1] - a[1]);
+  out.push(
+    `  events by kind: ${kinds.length > 0 ? kinds.map(([k, n]) => `${k} ${n}`).join(" · ") : "none"} ` +
+      `(examined ${plan.events.examined} row(s) in ${plan.events.windows} window(s) after id ${plan.events.from_id})`,
+  );
+  out.push(
+    `  deliveries: examined ${plan.deliveries.examined} row(s) in ${plan.deliveries.windows} window(s) after rowid ${plan.deliveries.from_id}`,
+  );
+  out.push(
+    `  held (${plan.held.length}): ${plan.held.length > 0 ? plan.held.map((h) => `#${h.pr} ${h.reasons.join("+")}${h.detail ? ` (${h.detail})` : ""}`).join(", ") : "none"}`,
+  );
+  out.push(
+    `  orphans — pi-sessions dirs with no registry row, never touched (${plan.orphans.length}): ${plan.orphans.length > 0 ? plan.orphans.join(", ") : "none"}`,
+  );
+  out.push(
+    `  workers: ${plan.workers === "answered" ? "answered" : "UNKNOWN — could not be asked; every candidate is held worker_unknown"}`,
+  );
+  if (!plan.births_observed)
+    out.push(
+      "  session births: not visible from a CLI process — the daemon re-checks them before anything moves",
+    );
+  out.push(
+    `  archive/ and state/ on one device: ${plan.same_device === null ? "UNKNOWN" : plan.same_device ? "yes" : "no"}`,
+  );
+  if (plan.stores) {
+    out.push(
+      `  ${STORE_LABELS.overseer}: ${storeTallyPhrase(plan.stores.overseer, "the overseer's birth is not visible from a CLI process")}`,
+    );
+    out.push(
+      `  ${STORE_LABELS.pi_global}: ${plan.stores.pi_global ? storeTallyPhrase(plan.stores.pi_global, "unknown") : "not measured"}`,
+    );
+  }
+  return out;
+}
+
+/** A store's tally as the plan reports it; never a guessed 0. */
+function storeTallyPhrase(t: import("./storepass.js").StoreTally, movableUnknown: string): string {
+  if (t.state === "unreadable") return `UNREADABLE (${t.error})`;
+  const movable =
+    t.movable_files === null || t.movable_bytes === null
+      ? `movable UNKNOWN (${movableUnknown})`
+      : `${t.movable_files} movable, ${fmtBytes(t.movable_bytes)}`;
+  const legacy =
+    t.legacy_copies > 0
+      ? `; legacy rotation copies to check: ${t.legacy_copies}, ${fmtBytes(t.legacy_bytes)}`
+      : "";
+  return `${t.files} file(s), ${fmtBytes(t.bytes)} live — ${movable}${legacy}`;
+}
+
+/** The whole report, as `qcr archive status` prints it. */
+export function renderArchiveReport(input: {
+  block: unknown;
+  statusNote: string | null;
+  ledger: ArchiveLedgerSummary;
+  policy: ArchivePolicy;
+  plan: ArchivePlan | null;
+}): string {
+  const lines: string[] = [];
+  lines.push(input.statusNote ? `archive: ${input.statusNote}` : archiveStatusLine(input.block));
+  const read = readArchiveStatus(input.block);
+  if (read.kind === "read") {
+    const s = read.view;
+    if (s.last_tick_at)
+      lines.push(`last tick ${s.last_tick_at}; last success ${s.last_success_at ?? "never"}`);
+    lines.push(
+      s.disk
+        ? `disk: archive free ${fmtBytes(s.disk.archive_free)}, state free ${fmtBytes(s.disk.state_free)}, headroom ${fmtBytes(s.disk.headroom)}`
+        : "disk: UNKNOWN (not checked yet, or statfs failed)",
+    );
+    if (s.held_prs && s.held_prs.count > 0)
+      lines.push(
+        `held PRs (${s.held_prs.count}): ${s.held_prs.first.map((h) => `#${h.pr} ${h.reason}`).join(", ")}${s.held_prs.count > s.held_prs.first.length ? ", …" : ""}`,
+      );
+    if (s.max_sync_span_ms !== null)
+      lines.push(`longest synchronous span: ${s.max_sync_span_ms} ms`);
+    if (s.freelist_pages !== null) lines.push(`state.db free pages: ${s.freelist_pages}`);
+    // The stores that belong to no PR: each one's last pass, or that it
+    // has not run (plan mode, not wired, or an older daemon).
+    for (const [label, st] of storeEntries(s.stores))
+      lines.push(storePhrase(label, st) || `${label}: no pass yet`);
+  }
+  lines.push(policyLine(input.policy));
+  const states = Object.entries(input.ledger.by_state);
+  lines.push(
+    `ledger: archive_prs ${states.length > 0 ? states.map(([k, n]) => `${k} ${n}`).join(", ") : "empty"}; ` +
+      `archived event rows ${input.ledger.archived_event_rows}`,
+  );
+  if (input.plan) lines.push(...planLines(input.plan));
+  return lines.join("\n");
+}
+
+/** The note `qcr archive status` gives a status.json with no `archive` key. */
+export const NO_ARCHIVE_BLOCK_NOTE =
+  "status.json carries no archive block — the daemon predates it";
+
+/**
+ * status.json's `archive` block as `qcr archive status` reads it — total:
+ * the raw block (undefined when there is none), a note saying why when there
+ * is no file or it cannot be parsed, and the reader's own verdict (no file =
+ * `absent`, an unparsable file = `unreadable`, else `readArchiveStatus`).
+ */
+export function readArchiveBlockFile(statusPath: string): {
+  block: unknown;
+  statusNote: string | null;
+  archiveRead: ArchiveStatusRead;
+} {
+  const unreadable = (cause: string) => {
+    const why = `status.json is unreadable: ${cause}`;
+    return { block: undefined, statusNote: why, archiveRead: { kind: "unreadable", why } as const };
+  };
+  let text: string;
+  try {
+    text = readFileSync(statusPath, "utf8");
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== "ENOENT") return unreadable(String(err));
+    return {
+      block: undefined,
+      statusNote: "no status.json yet — is the daemon running?",
+      archiveRead: { kind: "absent" },
+    };
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch (err) {
+    return unreadable(String(err));
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+    return unreadable("not a JSON object");
+  const block = (parsed as { archive?: unknown }).archive;
+  return { block, statusNote: null, archiveRead: readArchiveStatus(block) };
+}
+
+/**
+ * `qcr archive status --json`. `archive` is the block as published (null when
+ * there is none); `archive_read` is the reader's verdict — `absent`,
+ * `unreadable` (with why) or `read` — so a consumer never has to guess what a
+ * null stood for, and `status_note` says why when the block is absent.
+ */
+export function archiveStatusJson(input: {
+  block: unknown;
+  archiveRead: ArchiveStatusRead;
+  statusNote: string | null;
+  ledger: ArchiveLedgerSummary;
+  policy: ArchivePolicy;
+  plan: ArchivePlan | null;
+}): Record<string, unknown> {
+  const r = input.archiveRead;
+  return {
+    archive: input.block === undefined ? null : input.block,
+    archive_read: r.kind === "unreadable" ? { kind: r.kind, why: r.why } : { kind: r.kind },
+    status_note: input.statusNote ?? (r.kind === "absent" ? NO_ARCHIVE_BLOCK_NOTE : null),
+    ledger: input.ledger,
+    policy: input.policy,
+    plan: input.plan,
+  };
+}