@bli-cockpit/log-digest 0.0.0-stage → 0.1.0

package/dist/merge.js

@@ -0,0 +1,65 @@
+/**
+ * Several digest results as one (port of Kaiben's `merge_results`): counts
+ * summed, times widened, instance sets united. The next slice, a fleet view of
+ * every machine's collector digest, merges per-machine results with this.
+ */
+import { SUBJECTS_TRACKED } from "./digest.js";
+function earliest(a, b) {
+    const values = [a, b].filter((value) => Boolean(value));
+    return values.length > 0 ? Math.min(...values) : null;
+}
+function latest(a, b) {
+    const value = Math.max(a ?? 0, b ?? 0);
+    return value || null;
+}
+export function mergeResults(results, registry = {}) {
+    const merged = {
+        lines: 0, noise: 0,
+        span: [null, null],
+        cursors: [null, null],
+        groups: new Map(),
+        routine: Object.create(null),
+    };
+    for (const result of results) {
+        merged.lines += result.lines ?? 0;
+        merged.noise += result.noise ?? 0;
+        const [start, end] = result.span ?? [null, null];
+        if (start && (merged.span[0] === null || start < merged.span[0]))
+            merged.span[0] = start;
+        if (end && (merged.span[1] === null || end > merged.span[1]))
+            merged.span[1] = end;
+        const [first, last] = result.cursors ?? [null, null];
+        merged.cursors[0] = merged.cursors[0] ?? first;
+        merged.cursors[1] = last ?? merged.cursors[1];
+        const groups = result.groups ?? [];
+        for (const record of Array.isArray(groups) ? groups : Object.values(groups)) {
+            const known = merged.groups.get(record.tid);
+            if (!known) {
+                merged.groups.set(record.tid, { ...registry[record.tid], ...record, instances: [...(record.instances ?? [])], tid: record.tid });
+                continue;
+            }
+            known.count += record.count;
+            known.first = earliest(known.first, record.first);
+            known.last = latest(known.last, record.last);
+            for (const instance of record.instances ?? []) {
+                if (!known.instances.includes(instance) && known.instances.length < 64)
+                    known.instances.push(instance);
+            }
+        }
+        for (const [group, events] of Object.entries(result.routine ?? {})) {
+            const into = (merged.routine[group] ??= Object.create(null));
+            for (const [event, [count, subjects]] of Object.entries(events)) {
+                const record = (into[event] ??= [0, Object.create(null)]);
+                record[0] += count;
+                for (const [subject, amount] of Object.entries(subjects)) {
+                    if (subject in record[1] || Object.keys(record[1]).length < SUBJECTS_TRACKED)
+                        record[1][subject] = (record[1][subject] ?? 0) + amount;
+                    else
+                        record[1]["…"] = (record[1]["…"] ?? 0) + amount;
+                }
+            }
+        }
+    }
+    const groups = [...merged.groups.values()].sort((a, b) => b.count - a.count || (a.tid < b.tid ? -1 : a.tid > b.tid ? 1 : 0));
+    return { lines: merged.lines, noise: merged.noise, span: merged.span, cursors: merged.cursors, groups, routine: merged.routine, breaker: {} };
+}

package/dist/render.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Text renderings of a digest (port of Kaiben's `render_local` and
+ * `render_fleet`, plus `renderCapped`, the 2 KB view `cockpit logs` prints).
+ *
+ * Every renderer is a pure function of its input: the same digest renders
+ * byte-identically.
+ */
+import type { Classify } from "./classify.js";
+import type { DigestResult, RoutineEvents } from "./digest.js";
+import type { MergedResult } from "./merge.js";
+export declare function numberText(value: number): string;
+export declare function clock(epoch: number | null | undefined): string;
+export declare function timeRange(first: number | null | undefined, last: number | null | undefined): string;
+/** Caveman's class-invariant enumeration: exact counts for a small value set, else nothing (never a partial list). */
+export declare function subjectsText(subjects: Record<string, number>): string;
+/** `stored=2,280(Volkswagen) retiredLocalCache=12,962 +3`: biggest event counts first. */
+export declare function routineText(routine: Record<string, RoutineEvents>, limit?: number): string;
+/** One machine's (or source's) digest as text. */
+export declare function renderLocal(result: DigestResult, server?: string, classify?: Classify, maxLines?: number): string;
+export interface FleetView {
+    window: [number, number];
+    servers: Record<string, MergedResult | DigestResult>;
+    classify: Classify;
+    newTids?: ReadonlySet<string>;
+    backTids?: ReadonlySet<string>;
+    machines?: string;
+    incidents?: string;
+    cursorFile?: string;
+}
+/** A fleet view straight from per-server results (no operator state): `--file` runs and tests. */
+export declare function fleetView(resultsByServer: Record<string, MergedResult | DigestResult>, classify: Classify, window?: [number, number]): FleetView;
+/** The fleet digest: every server's templates merged by tid, ERROR first, hiccups counted, WARNINGs one line. */
+export declare function renderFleet(view: FleetView): string;
+export interface CappedOptions {
+    /** `dashboard`, `railway:ladder`... */
+    source: string;
+    /** `last 1h`, `since 2026-10-07T03:00Z`. */
+    window: string;
+    classify: Classify;
+    /** Hard ceiling on the printed bytes. About 2 KB by default. */
+    maxBytes?: number;
+    /** Plain-words facts about the read itself (capped at N lines, no per-line timestamps...), printed as they are. */
+    notes?: readonly string[];
+}
+/**
+ * The view an agent or a person reads: ERROR classes first (unknown, our_bug,
+ * config_drift, capacity), then hiccups, then ONE line counting what is harmless,
+ * then the routine work counts. Whatever does not fit the byte budget becomes a
+ * `+N more` line naming the next template ids, so nothing is dropped silently.
+ */
+export declare function renderCapped(result: DigestResult, options: CappedOptions): string;

package/dist/render.js

@@ -0,0 +1,214 @@
+import { CLASS_ORDER } from "./classify.js";
+import { cut } from "./mask.js";
+export function numberText(value) {
+    return value.toLocaleString("en-US");
+}
+export function clock(epoch) {
+    if (!epoch)
+        return "?";
+    const date = new Date(epoch * 1000);
+    return `${String(date.getUTCHours()).padStart(2, "0")}:${String(date.getUTCMinutes()).padStart(2, "0")}`;
+}
+export function timeRange(first, last) {
+    return clock(first) === clock(last) ? clock(first) : `${clock(first)}-${clock(last)}`;
+}
+function short(text, limit) {
+    return Array.from(text).length <= limit ? text : `${cut(text, limit - 1)}…`;
+}
+/** Caveman's class-invariant enumeration: exact counts for a small value set, else nothing (never a partial list). */
+export function subjectsText(subjects) {
+    const names = Object.keys(subjects);
+    if (names.length === 0 || "…" in subjects || names.length > 4)
+        return "";
+    if (names.length === 1)
+        return `(${names[0]})`;
+    const ranked = names.sort((a, b) => subjects[b] - subjects[a] || (a < b ? -1 : a > b ? 1 : 0));
+    return `(${ranked.map((name) => `${name}×${numberText(subjects[name])}`).join(" ")})`;
+}
+/** `stored=2,280(Volkswagen) retiredLocalCache=12,962 +3`: biggest event counts first. */
+export function routineText(routine, limit = 2) {
+    const items = [];
+    for (const [group, events] of Object.entries(routine)) {
+        for (const [event, [count, subjects]] of Object.entries(events)) {
+            if (event === "text" || event === "long_line" || event === "relay" || event.startsWith("systemd "))
+                continue;
+            items.push([count, group, event, subjects]);
+        }
+    }
+    items.sort((a, b) => b[0] - a[0] || (a[1] < b[1] ? -1 : a[1] > b[1] ? 1 : 0) || (a[2] < b[2] ? -1 : a[2] > b[2] ? 1 : 0));
+    const parts = items.slice(0, limit).map(([count, , event, subjects]) => `${event}=${numberText(count)}${subjectsText(subjects)}`);
+    if (items.length > limit)
+        parts.push(`+${items.length - limit}`);
+    return parts.join(" ") || "-";
+}
+const NONE = {};
+/** One machine's (or source's) digest as text. */
+export function renderLocal(result, server = "this machine", classify, maxLines) {
+    const span = result.span;
+    const cursor = result.cursors[1];
+    const lines = [
+        `DIGEST ${server} ${timeRange(span[0], span[1])}Z | ${numberText(result.lines)} lines kept, ${numberText(result.noise)} noise | `
+            + `${result.groups.length} templates | cursor ${cursor ?? "-"}`,
+    ];
+    const verdicts = new Map(result.groups.map((record) => [record.tid, classify ? classify(record.unit, record.template, server) : NONE]));
+    const order = (record) => CLASS_ORDER[verdicts.get(record.tid)?.class ?? ""] ?? 0;
+    const groups = [...result.groups].sort((a, b) => order(a) - order(b) || b.count - a.count || (a.tid < b.tid ? -1 : a.tid > b.tid ? 1 : 0));
+    for (const record of groups) {
+        const verdict = verdicts.get(record.tid);
+        const word = [verdict.severity, verdict.class].filter(Boolean).join(" ");
+        const units = record.instances.length > 1 ? `(${record.instances.length}u)` : "";
+        lines.push(` ${record.tid} ${record.unit}${units} ${word} x${numberText(record.count)} ${timeRange(record.first, record.last)} ${short(record.template, 140)}`);
+    }
+    lines.push(` WORK ${routineText(result.routine, 8)}`);
+    if (maxLines && lines.length > maxLines) {
+        const hidden = lines.length - maxLines;
+        const last = lines[lines.length - 1];
+        return [...lines.slice(0, maxLines - 2), ` … ${hidden + 1} more templates (raise --max-lines)`, last].join("\n");
+    }
+    return lines.join("\n");
+}
+/** A fleet view straight from per-server results (no operator state): `--file` runs and tests. */
+export function fleetView(resultsByServer, classify, window) {
+    const spans = Object.values(resultsByServer).flatMap((result) => result.span).filter((value) => Boolean(value));
+    return { window: window ?? [Math.min(...(spans.length ? spans : [0])), Math.max(...(spans.length ? spans : [0]))], servers: resultsByServer, classify };
+}
+const compareTid = (a, b) => (a.tid < b.tid ? -1 : a.tid > b.tid ? 1 : 0);
+/** The fleet digest: every server's templates merged by tid, ERROR first, hiccups counted, WARNINGs one line. */
+export function renderFleet(view) {
+    const [start, end] = view.window;
+    const names = Object.keys(view.servers).sort();
+    const kept = names.reduce((sum, name) => sum + view.servers[name].lines, 0);
+    const noise = names.reduce((sum, name) => sum + view.servers[name].noise, 0);
+    const byTid = new Map();
+    for (const name of names) {
+        for (const record of view.servers[name].groups) {
+            const entry = byTid.get(record.tid)
+                ?? { ...record, servers: [], count: 0, instances: [], first: record.first, last: record.last, class: "unknown", severity: "ERROR" };
+            byTid.set(record.tid, entry);
+            entry.servers.push(name);
+            entry.count += record.count;
+            const firsts = [entry.first, record.first].filter((value) => Boolean(value));
+            entry.first = firsts.length ? Math.min(...firsts) : null;
+            entry.last = Math.max(entry.last ?? 0, record.last ?? 0) || null;
+            entry.instances = [...new Set([...entry.instances, ...record.instances])].sort();
+        }
+    }
+    const sections = { ERROR: [], hiccup: [], WARNING: [] };
+    for (const entry of byTid.values()) {
+        const verdict = view.classify(entry.unit, entry.template, entry.servers[0]);
+        entry.class = verdict.class;
+        entry.severity = verdict.severity;
+        (sections[entry.severity] ??= []).push(entry);
+    }
+    const fresh = view.newTids ?? new Set();
+    const back = view.backTids ?? new Set();
+    const total = (name) => (sections[name] ?? []).reduce((sum, entry) => sum + entry.count, 0);
+    const day = new Date(end * 1000).toISOString().slice(0, 10);
+    const newHere = [...fresh].filter((tid) => byTid.has(tid)).length;
+    const out = [
+        `FLEET DIGEST ${day} ${clock(start)}-${clock(end)}Z | ${names.length} servers | ${numberText(kept + noise)} lines (${numberText(noise)} noise) | `
+            + `ERROR ${numberText(total("ERROR"))}, hiccup ${numberText(total("hiccup"))}, WARNING ${numberText(total("WARNING"))} in ${byTid.size} templates, ${newHere} NEW`,
+    ];
+    if (view.cursorFile)
+        out.push(`raw: cockpit logs <source> --raw <tid> | cursors+range: ${view.cursorFile}`);
+    const line = (entry, templateChars) => {
+        const mark = fresh.has(entry.tid) ? "NEW " : back.has(entry.tid) ? "BACK " : "";
+        const units = entry.instances.length > 1 ? `(${entry.instances.length}u)` : "";
+        return ` ${mark}${entry.tid} ${entry.servers.join(",")} ${entry.unit}${units} ${entry.class} x${numberText(entry.count)} ${timeRange(entry.first, entry.last)} ${short(entry.template, templateChars)}`;
+    };
+    const ranked = (entries) => [...entries].sort((a, b) => Number(!fresh.has(a.tid)) - Number(!fresh.has(b.tid))
+        || (CLASS_ORDER[a.class] ?? 0) - (CLASS_ORDER[b.class] ?? 0)
+        || b.count - a.count
+        || compareTid(a, b));
+    for (const [key, title, limit, chars] of [["ERROR", "ERROR (must fix, alerts)", 14, 120], ["hiccup", "hiccup (retried with back-off)", 6, 100]]) {
+        const entries = ranked(sections[key] ?? []);
+        out.push(`${title}: ${entries.length}`);
+        out.push(...entries.slice(0, limit).map((entry) => line(entry, chars)));
+        if (entries.length > limit)
+            out.push(` +${entries.length - limit} more: ${entries.slice(limit, limit + 12).map((entry) => entry.tid).join(" ")}`);
+    }
+    const counted = [...(sections["WARNING"] ?? [])].sort((a, b) => b.count - a.count);
+    if (counted.length > 0) {
+        const parts = counted.slice(0, 6).map((entry) => `${entry.servers.join(",")} ${short(entry.template, 48)} x${numberText(entry.count)}`);
+        const more = counted.length > 6 ? ` +${counted.length - 6}` : "";
+        out.push(`WARNING (nothing to fix, counted, no alert): ${counted.length}: ${parts.join("; ")}${more}`);
+    }
+    out.push(`WORK ${names.map((name) => `${name} ${routineText(view.servers[name].routine)}`).join(" | ")}`);
+    if (view.machines)
+        out.push(`MACHINES ${view.machines}`);
+    if (view.incidents)
+        out.push(`INCIDENTS ${view.incidents}`);
+    return out.join("\n");
+}
+/**
+ * The view an agent or a person reads: ERROR classes first (unknown, our_bug,
+ * config_drift, capacity), then hiccups, then ONE line counting what is harmless,
+ * then the routine work counts. Whatever does not fit the byte budget becomes a
+ * `+N more` line naming the next template ids, so nothing is dropped silently.
+ */
+export function renderCapped(result, options) {
+    const maxBytes = options.maxBytes ?? 2048;
+    const entries = result.groups.map((record) => ({ record, verdict: options.classify(record.unit, record.template, options.source) }));
+    const rank = (a, b) => (CLASS_ORDER[a.verdict.class] ?? 0) - (CLASS_ORDER[b.verdict.class] ?? 0) || b.record.count - a.record.count || compareTid(a.record, b.record);
+    const bySeverity = (severity) => entries.filter((entry) => entry.verdict.severity === severity).sort(rank);
+    const errors = bySeverity("ERROR");
+    const hiccups = bySeverity("hiccup");
+    const counted = bySeverity("WARNING").sort((a, b) => b.record.count - a.record.count || compareTid(a.record, b.record));
+    const sum = (list) => list.reduce((total, entry) => total + entry.record.count, 0);
+    const head = `LOGS ${options.source} ${options.window}${result.span[0] ? ` ${timeRange(result.span[0], result.span[1])}Z` : ""} | ${numberText(result.lines + result.noise)} lines | `
+        + `${entries.length} templates | ERROR ${numberText(sum(errors))}, hiccup ${numberText(sum(hiccups))}, counted ${numberText(sum(counted))}`;
+    const required = [head, ...(options.notes ?? []), `WORK ${routineText(result.routine, 6)}`];
+    const row = ({ record, verdict }, chars) => {
+        const units = record.instances.length > 1 ? `(${record.instances.length}u)` : "";
+        const when = record.first ? ` ${timeRange(record.first, record.last)}` : "";
+        return ` ${record.tid} ${record.unit}${units} ${verdict.class} x${numberText(record.count)}${when} ${short(record.template, chars)}`;
+    };
+    const countedLine = counted.length
+        ? `COUNTED (harmless, no alert): ${counted.length}: ${counted.slice(0, 4).map((e) => `${short(e.record.template, 40)} x${numberText(e.record.count)}`).join("; ")}${counted.length > 4 ? ` +${counted.length - 4}` : ""}`
+        : null;
+    const flex = [];
+    const flexIds = [];
+    if (errors.length) {
+        flex.push(`ERROR (must fix): ${errors.length}`);
+        flexIds.push("");
+    }
+    for (const entry of errors) {
+        flex.push(row(entry, 110));
+        flexIds.push(entry.record.tid);
+    }
+    if (hiccups.length) {
+        flex.push(`hiccup (retried): ${hiccups.length}`);
+        flexIds.push("");
+    }
+    for (const entry of hiccups) {
+        flex.push(row(entry, 90));
+        flexIds.push(entry.record.tid);
+    }
+    const reserve = 90; // room for the `+N more` line
+    const bytes = (lines) => Buffer.byteLength(lines.join("\n") + "\n", "utf8");
+    const kept = [];
+    const keptTail = countedLine ? [countedLine] : [];
+    let used = bytes([...required, ...keptTail]) + reserve;
+    let cutAt = flex.length;
+    for (let index = 0; index < flex.length; index += 1) {
+        const size = Buffer.byteLength(flex[index] + "\n", "utf8");
+        if (used + size > maxBytes) {
+            cutAt = index;
+            break;
+        }
+        kept.push(flex[index]);
+        used += size;
+    }
+    const lost = flexIds.slice(cutAt).filter(Boolean);
+    const lines = [head, ...(options.notes ?? []), ...kept];
+    if (lost.length)
+        lines.push(` +${lost.length} more templates: ${lost.slice(0, 6).join(" ")} (cockpit logs ${options.source} --json for all)`);
+    if (countedLine)
+        lines.push(countedLine);
+    lines.push(required[required.length - 1]);
+    // A final guard: a single over-long note must never break the ceiling.
+    let text = lines.join("\n");
+    if (Buffer.byteLength(text, "utf8") > maxBytes)
+        text = `${Buffer.from(text, "utf8").subarray(0, maxBytes - 4).toString("utf8")}\n…`;
+    return text;
+}

package/dist/sources/collector.d.ts

@@ -0,0 +1,15 @@
+import { type SourceContext, type SourceLine, type SourceRead } from "./types.js";
+/** The share of a file (0..1) that falls inside the window, by time, given when it started and ended. */
+export declare function windowShare(fromEpoch: number, start: number | null, end: number): number;
+/** The one line a tick receipt is judged as. */
+export declare function receiptLine(report: Record<string, unknown>): string;
+/**
+ * Splits the stream into digest lines, folding each column-0 `{ ... }` receipt
+ * into one line. Body lines of a receipt whose start is not in the read are
+ * counted, not judged: they are JSON syntax, not log lines.
+ */
+export declare function streamLines(text: string, stream: string): {
+    lines: SourceLine[];
+    bodySkipped: number;
+};
+export declare function readCollector(context: SourceContext): Promise<SourceRead>;

package/dist/sources/collector.js

@@ -0,0 +1,166 @@
+/**
+ * `collector`: this machine's collector logs (`sync.log`, `sync.err.log`, their
+ * rotated archives; the BLI Memory hooks write to `sync.err.log` too).
+ *
+ * The state directory is the caller's to compute (it differs per platform and
+ * `--home`); on macOS and Windows alike it is `<home>/.local/state/bli-cockpit`
+ * and the scheduled tick appends to `sync.log` (stdout) and, on macOS,
+ * `sync.err.log` (stderr). Rotation is a rename, so an archive keeps the time of
+ * its last write and the next-newer file starts where it ended.
+ *
+ * These logs carry NO per-line time. The window is therefore the share of each
+ * file that falls inside it, taken from the end of the file, assuming lines were
+ * written evenly between the file's first and last write; the digest says so.
+ *
+ * `sync.log` is mostly the tick's `--json` receipt printed over hundreds of
+ * indented lines. Each receipt is folded into one line (status, mode and the
+ * failure reasons it names) before judging, so a failed tick is one template and
+ * a healthy one is one routine count.
+ */
+import { open, readdir, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { SourceRefusal } from "./types.js";
+const LOG_FILE = /^(sync(?:\.err)?\.log)(?:\.(\d+))?$/;
+const MAX_BYTES_PER_STREAM = 64 * 1024 * 1024;
+/** The share of a file (0..1) that falls inside the window, by time, given when it started and ended. */
+export function windowShare(fromEpoch, start, end) {
+    if (end <= fromEpoch)
+        return 0;
+    if (start === null || start >= end)
+        return 1;
+    return Math.min(1, Math.max(0, (end - fromEpoch) / (end - start)));
+}
+async function readTail(path, bytes, size) {
+    const handle = await open(path, "r");
+    try {
+        const length = Math.min(bytes, size);
+        const buffer = Buffer.alloc(length);
+        await handle.read(buffer, 0, length, size - length);
+        let text = buffer.toString("utf8");
+        if (length < size)
+            text = text.slice(text.indexOf("\n") + 1); // drop the cut-off first line
+        return text;
+    }
+    finally {
+        await handle.close();
+    }
+}
+const TAG = /^\[([a-z][a-z0-9 _-]{0,40})\]/i;
+function reasonsOf(report) {
+    const raw = report["failure_reasons"];
+    if (!Array.isArray(raw))
+        return "";
+    return raw
+        .map((item) => (typeof item === "string" ? item : typeof item === "object" && item !== null ? String(item["reason"] ?? item["code"] ?? "object") : String(item)))
+        .slice(0, 3)
+        .join(",");
+}
+/** The one line a tick receipt is judged as. */
+export function receiptLine(report) {
+    const summary = { event: "sync_report", kind: String(report["mode"] ?? "tick").slice(0, 24) };
+    if (typeof report["status"] === "string")
+        summary["status"] = report["status"];
+    const reasons = reasonsOf(report);
+    if (reasons)
+        summary["error"] = reasons;
+    return JSON.stringify(summary);
+}
+// A line of a pretty-printed receipt whose opening brace is not in this read (rotation cut it, or the window did).
+const RECEIPT_BODY = /^\s{2,}["{}[\]]|^[}\]],?$/;
+/**
+ * Splits the stream into digest lines, folding each column-0 `{ ... }` receipt
+ * into one line. Body lines of a receipt whose start is not in the read are
+ * counted, not judged: they are JSON syntax, not log lines.
+ */
+export function streamLines(text, stream) {
+    const out = [];
+    let bodySkipped = 0;
+    const unitOf = (line) => TAG.exec(line)?.[1] ?? (stream === "sync.err.log" ? "sync.err" : "sync");
+    const rows = text.split("\n");
+    for (let index = 0; index < rows.length; index += 1) {
+        const row = rows[index];
+        if (row === "{") {
+            let end = index + 1;
+            while (end < rows.length && rows[end] !== "}")
+                end += 1;
+            if (end < rows.length) {
+                try {
+                    const report = JSON.parse(rows.slice(index, end + 1).join("\n"));
+                    out.push({ unit: "sync", message: receiptLine(report), ts: 0 });
+                    index = end;
+                    continue;
+                }
+                catch {
+                    // not a receipt after all: fall through and judge its lines one by one
+                }
+            }
+        }
+        if (RECEIPT_BODY.test(row) || row === "{")
+            bodySkipped += 1;
+        else if (row.trim())
+            out.push({ unit: unitOf(row), message: row, ts: 0 });
+    }
+    return { lines: out, bodySkipped };
+}
+export async function readCollector(context) {
+    const { stateDir, window, log } = context;
+    if (!stateDir)
+        throw new SourceRefusal("collector_state_unknown", "the caller did not say where the collector keeps its state");
+    let names;
+    try {
+        names = await readdir(stateDir);
+    }
+    catch {
+        throw new SourceRefusal("collector_state_missing", "there is no bli-cockpit state directory here: the collector has never run on this machine (`cockpit doctor` sets it up)");
+    }
+    const files = [];
+    for (const name of names) {
+        const match = LOG_FILE.exec(name);
+        if (!match)
+            continue;
+        try {
+            const info = await stat(join(stateDir, name));
+            files.push({ name, stream: match[1], index: match[2] ? Number(match[2]) : 0, size: info.size, mtime: info.mtimeMs / 1000, birth: info.birthtimeMs > 0 ? info.birthtimeMs / 1000 : null });
+        }
+        catch {
+            log("[logs collector] a log file vanished between listing and reading", { file: name });
+        }
+    }
+    if (files.length === 0)
+        throw new SourceRefusal("collector_logs_missing", "no sync.log or sync.err.log in the state directory: the scheduled tick has not written anything on this machine");
+    const lines = [];
+    const read = [];
+    let skipped = 0;
+    let bytesRead = 0;
+    for (const stream of [...new Set(files.map((file) => file.stream))].sort()) {
+        const chain = files.filter((file) => file.stream === stream).sort((a, b) => a.index - b.index);
+        let budget = MAX_BYTES_PER_STREAM;
+        for (let position = 0; position < chain.length; position += 1) {
+            const file = chain[position];
+            const end = position === 0 ? window.toEpoch : file.mtime;
+            const older = chain[position + 1];
+            const start = older ? older.mtime : file.birth;
+            const share = windowShare(window.fromEpoch, start, end);
+            if (share === 0 || file.size === 0)
+                continue;
+            const want = Math.min(budget, Math.ceil(file.size * share));
+            budget -= want;
+            const text = await readTail(join(stateDir, file.name), want, file.size);
+            const parsed = streamLines(text, stream);
+            lines.push(...parsed.lines);
+            skipped += parsed.bodySkipped;
+            bytesRead += want;
+            read.push(`${file.name} ${Math.round(share * 100)}%`);
+            log("[logs collector] file read", { file: file.name, share_percent: Math.round(share * 100), bytes: want, lines: parsed.lines.length, receipt_body_lines_skipped: parsed.bodySkipped });
+            if (budget <= 0)
+                break;
+        }
+    }
+    const notes = [
+        "no per-line times in these logs: the window is each file's share by time, read from its end (approximate)",
+        `read ${read.length > 0 ? read.join(", ") : "nothing: every log file ends before the window"}`,
+    ];
+    if (skipped > 0)
+        notes.push(`${skipped.toLocaleString("en-US")} lines of tick receipts cut by log rotation (indented JSON) were counted, not judged`);
+    return { lines, notes, rawChars: bytesRead };
+}

package/dist/sources/process.d.ts

@@ -0,0 +1,2 @@
+import type { RunCli } from "./types.js";
+export declare const nodeRunCli: RunCli;

package/dist/sources/process.js

@@ -0,0 +1,78 @@
+/**
+ * Runs a read-only helper program (`vercel`, `railway`) and returns what it
+ * said. Never throws: a missing program, a timeout and a byte ceiling are all
+ * answers the caller names (`vercel_cli_missing`, ...), not stack traces.
+ */
+import { spawn } from "node:child_process";
+export const nodeRunCli = (command, args, options) => new Promise((resolve) => {
+    const out = [];
+    const err = [];
+    let size = 0;
+    let failure;
+    let truncated = false;
+    let settled = false;
+    let child;
+    try {
+        // Windows installs `vercel` and `railway` as .cmd shims, which spawn only runs through a shell. Every argument
+        // is built from fixed words, ISO times we format and a service name that digestSource and readService both
+        // matched against ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$ BEFORE this runs; nothing caller-supplied is quoted or escaped.
+        child = spawn(command, [...args], { stdio: ["ignore", "pipe", "pipe"], windowsHide: true, shell: process.platform === "win32" });
+    }
+    catch (error) {
+        resolve({ status: null, stdout: "", stderr: "", failure: error.code ?? "spawn_failed" });
+        return;
+    }
+    const finish = (status) => {
+        if (settled)
+            return;
+        settled = true;
+        clearTimeout(timer);
+        const stdout = Buffer.concat(out).toString("utf8");
+        const stderr = Buffer.concat(err).toString("utf8").slice(-4000);
+        // cmd.exe answers a program it cannot find with exit 1 and this sentence, where POSIX gives ENOENT.
+        if (!failure && process.platform === "win32" && status !== 0 && /is not recognized as an internal or external command/i.test(stderr))
+            failure = "ENOENT";
+        resolve({
+            status,
+            stdout,
+            stderr,
+            ...(failure ? { failure } : {}),
+            ...(truncated ? { truncated } : {}),
+        });
+    };
+    const timer = setTimeout(() => {
+        failure = "timeout";
+        truncated = true;
+        child.kill("SIGTERM");
+        setTimeout(() => finish(null), 2000).unref();
+    }, options.timeoutMs);
+    const abortIfMatched = (chunk) => {
+        if (options.abortOn && !failure && chunk.toString("utf8").split("\n").some((line) => !line.startsWith("{") && options.abortOn.test(line))) {
+            failure = "aborted";
+            truncated = true;
+            child.kill("SIGTERM");
+        }
+    };
+    child.stdout?.on("data", (chunk) => {
+        abortIfMatched(chunk);
+        if (truncated && failure !== "timeout" && failure !== "aborted")
+            return;
+        size += chunk.length;
+        if (size > options.maxBytes) {
+            truncated = true;
+            child.kill("SIGTERM");
+            return;
+        }
+        out.push(chunk);
+    });
+    child.stderr?.on("data", (chunk) => {
+        abortIfMatched(chunk);
+        if (Buffer.concat(err).length < 16_000)
+            err.push(chunk);
+    });
+    child.on("error", (error) => {
+        failure = error.code ?? "spawn_failed";
+        finish(null);
+    });
+    child.on("close", (code) => finish(code));
+});

package/dist/sources/railway.d.ts

@@ -0,0 +1,6 @@
+import { SourceRefusal, type CliRun, type SourceContext, type SourceRead } from "./types.js";
+export declare const RAILWAY_PROJECT_ID = "868238ce-d8fe-4629-8e05-fb7492baff1f";
+export declare const RAILWAY_ENVIRONMENT = "production";
+/** Which named refusal a failed `railway` run is, or null when the run is not a refusal. */
+export declare function railwayRefusal(run: CliRun, service?: string): SourceRefusal | null;
+export declare function readRailway(context: SourceContext, service?: string): Promise<SourceRead>;