@expitc/termad 0.0.0-stage → 0.1.0

package/dist/core/config.js

@@ -0,0 +1,33 @@
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { paths, termadHome } from "./paths.js";
+export const ALL_SURFACES = ["claude", "codex", "opencode", "gemini"];
+function defaultConfig() {
+    return {
+        endpoint: null,
+        uid: crypto.randomUUID(),
+        pollSeconds: 900,
+        surfaces: { claude: false, codex: false, opencode: false, gemini: false },
+        style: "line",
+    };
+}
+export function loadConfig() {
+    try {
+        const raw = JSON.parse(readFileSync(paths.config(), "utf8"));
+        return { ...defaultConfig(), ...raw, surfaces: { ...defaultConfig().surfaces, ...raw.surfaces } };
+    }
+    catch {
+        return defaultConfig();
+    }
+}
+export function saveConfig(cfg) {
+    mkdirSync(termadHome(), { recursive: true });
+    writeFileSync(paths.config(), JSON.stringify(cfg, null, 2) + "\n");
+}
+/** Atomic-ish write so wrappers never read a half-written cache. */
+export function writeFileAtomic(path, data) {
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = path + ".tmp";
+    writeFileSync(tmp, data);
+    renameSync(tmp, path);
+}

package/dist/core/manifest.d.ts

@@ -0,0 +1,20 @@
+export interface ManifestEntry {
+    surface: string;
+    target: string;
+    mechanism: "wrapper" | "statusline";
+    /** Backup holding the pristine original (null if none was needed). */
+    backup: string | null;
+    sha256Original: string | null;
+    sha256Installed: string | null;
+    at: string;
+}
+export interface Manifest {
+    version: 1;
+    entries: ManifestEntry[];
+}
+export declare function sha256File(p: string): string | null;
+export declare function loadManifest(): Manifest;
+export declare function saveManifest(m: Manifest): void;
+/** Record (or replace) the entry for one surface+target pair. */
+export declare function recordEntry(e: Omit<ManifestEntry, "at">): void;
+export declare function removeEntries(surface: string): void;

package/dist/core/manifest.js

@@ -0,0 +1,42 @@
+/**
+ * Tamper-evident audit manifest: every change termad makes is recorded with
+ * sha256 fingerprints of the original and the installed file. `termad audit`
+ * re-verifies the chain, so any modification — by termad, the user, the CLI
+ * itself, or a third party — is attributable.
+ */
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { paths } from "./paths.js";
+import { writeFileAtomic } from "./config.js";
+export function sha256File(p) {
+    try {
+        return createHash("sha256").update(readFileSync(p)).digest("hex");
+    }
+    catch {
+        return null;
+    }
+}
+export function loadManifest() {
+    try {
+        const m = JSON.parse(readFileSync(paths.manifest(), "utf8"));
+        if (m?.version === 1 && Array.isArray(m.entries))
+            return m;
+    }
+    catch { }
+    return { version: 1, entries: [] };
+}
+export function saveManifest(m) {
+    writeFileAtomic(paths.manifest(), JSON.stringify(m, null, 2) + "\n");
+}
+/** Record (or replace) the entry for one surface+target pair. */
+export function recordEntry(e) {
+    const m = loadManifest();
+    m.entries = m.entries.filter((x) => !(x.surface === e.surface && x.target === e.target));
+    m.entries.push({ ...e, at: new Date().toISOString() });
+    saveManifest(m);
+}
+export function removeEntries(surface) {
+    const m = loadManifest();
+    m.entries = m.entries.filter((x) => x.surface !== surface);
+    saveManifest(m);
+}

package/dist/core/paths.d.ts

@@ -0,0 +1,23 @@
+/** All termad state lives under ~/.termad (override with TERMAD_HOME). */
+export declare function termadHome(): string;
+export declare const paths: {
+    config: () => string;
+    /** Cache file the wrappers read: line 1 = text, line 2 = url, line 3 = sub. */
+    adCache: () => string;
+    /** Claude statusline launcher installed into ~/.claude/settings.json. */
+    statuslineScript: () => string;
+    /** Captured pre-install statusLine (chain capture, like claude does natively). */
+    prevStatusline: () => string;
+    log: () => string;
+    /** Tamper-evident record of every change (`termad audit` re-verifies it). */
+    manifest: () => string;
+    /**
+     * Display counter: one line of ad id per render, appended by the wrapper,
+     * reported in batches by `termad sync` (never per-render — no network on
+     * the CLI hot path, no per-view beacon).
+     */
+    displayLog: () => string;
+};
+/** Wrapper backup for a binary/shim lives next to it: <bin>.termad-orig. */
+export declare function backupPath(target: string): string;
+export declare const WRAPPER_MARKER = "===== TERMAD-CLI =====";

package/dist/core/paths.js

@@ -0,0 +1,29 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+/** All termad state lives under ~/.termad (override with TERMAD_HOME). */
+export function termadHome() {
+    return process.env.TERMAD_HOME || join(homedir(), ".termad");
+}
+export const paths = {
+    config: () => join(termadHome(), "config.json"),
+    /** Cache file the wrappers read: line 1 = text, line 2 = url, line 3 = sub. */
+    adCache: () => join(termadHome(), "ad.txt"),
+    /** Claude statusline launcher installed into ~/.claude/settings.json. */
+    statuslineScript: () => join(termadHome(), "statusline.mjs"),
+    /** Captured pre-install statusLine (chain capture, like claude does natively). */
+    prevStatusline: () => join(termadHome(), "prev-statusline.json"),
+    log: () => join(termadHome(), "termad.log"),
+    /** Tamper-evident record of every change (`termad audit` re-verifies it). */
+    manifest: () => join(termadHome(), "manifest.json"),
+    /**
+     * Display counter: one line of ad id per render, appended by the wrapper,
+     * reported in batches by `termad sync` (never per-render — no network on
+     * the CLI hot path, no per-view beacon).
+     */
+    displayLog: () => join(termadHome(), "display.log"),
+};
+/** Wrapper backup for a binary/shim lives next to it: <bin>.termad-orig. */
+export function backupPath(target) {
+    return target + ".termad-orig";
+}
+export const WRAPPER_MARKER = "===== TERMAD-CLI =====";

package/dist/core/source.d.ts

@@ -0,0 +1,18 @@
+import { Ad } from "./ad.js";
+import { type SurfaceId } from "./config.js";
+/** Last-good ad survives endpoint outages (write-through cache). */
+export declare function fetchAd(surface: SurfaceId): Promise<Ad>;
+/**
+ * Write the ad cache the wrappers read:
+ *   line 1 = wording, line 2 = click URL, line 3 = sub, line 4 = ad id.
+ * Lines 2/3 are padded with "-" when absent so line-numbered readers
+ * (including cmd's `for /f`, which skips blank lines) stay positional.
+ * Wrappers only ever read this file — zero network in the hot path.
+ * Line 4 (ad id) is what the wrapper appends to the display counter.
+ */
+export declare function writeAdCache(ad: Ad): void;
+export declare function readAdCache(): {
+    text: string;
+    url?: string;
+    sub?: string;
+} | null;

package/dist/core/source.js

@@ -0,0 +1,78 @@
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { isValidAd } from "./ad.js";
+import { loadConfig, writeFileAtomic } from "./config.js";
+import { paths, termadHome } from "./paths.js";
+const FETCH_TIMEOUT_MS = 4000;
+/** Fallback ad if nothing is configured or the endpoint is down. */
+const HOUSE_AD = { id: "house:default", text: "termad — ads for your terminal" };
+/** Last-good ad survives endpoint outages (write-through cache). */
+export async function fetchAd(surface) {
+    const cfg = loadConfig();
+    if (cfg.endpoint) {
+        try {
+            const url = `${cfg.endpoint.replace(/\/+$/, "")}/v1/ad?surface=${surface}&uid=${cfg.uid}`;
+            const res = await fetch(url, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+            if (res.ok) {
+                const body = (await res.json());
+                if (isValidAd(body.ad)) {
+                    writeLastGood(body.ad);
+                    return body.ad;
+                }
+            }
+        }
+        catch {
+            // fall through to cache / house ad — never break the CLI over an ad
+        }
+    }
+    return lastGood() ?? HOUSE_AD;
+}
+function lastGoodPath() {
+    return paths.adCache() + ".json";
+}
+function writeLastGood(ad) {
+    try {
+        mkdirSync(termadHome(), { recursive: true });
+        writeFileSync(lastGoodPath(), JSON.stringify(ad));
+    }
+    catch { }
+}
+function lastGood() {
+    try {
+        const ad = JSON.parse(readFileSync(lastGoodPath(), "utf8"));
+        return isValidAd(ad) ? ad : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Write the ad cache the wrappers read:
+ *   line 1 = wording, line 2 = click URL, line 3 = sub, line 4 = ad id.
+ * Lines 2/3 are padded with "-" when absent so line-numbered readers
+ * (including cmd's `for /f`, which skips blank lines) stay positional.
+ * Wrappers only ever read this file — zero network in the hot path.
+ * Line 4 (ad id) is what the wrapper appends to the display counter.
+ */
+export function writeAdCache(ad) {
+    const lines = [
+        ad.text.replace(/[\r\n]+/g, " ").trim(),
+        ad.url ?? "-",
+        ad.sub ? ad.sub.replace(/[\r\n]+/g, " ").trim() : "-",
+        ad.id || "-",
+    ];
+    writeFileAtomic(paths.adCache(), lines.join("\n") + "\n");
+}
+export function readAdCache() {
+    try {
+        const raw = readFileSync(paths.adCache(), "utf8").split("\n");
+        const text = (raw[0] ?? "").trim();
+        if (!text)
+            return null;
+        const url = (raw[1] ?? "").trim();
+        const sub = (raw[2] ?? "").trim();
+        return { text, url: url && url !== "-" ? url : undefined, sub: sub && sub !== "-" ? sub : undefined };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { type Ad, isValidAd } from "./core/ad.js";
+export { fetchAd, writeAdCache, readAdCache } from "./core/source.js";
+export { loadConfig, saveConfig, type SurfaceId, type TermadConfig } from "./core/config.js";
+export { install, uninstall, sync } from "./install.js";
+export { render, renderLine, renderBanner } from "./render/render.js";
+export { installWrapper, uninstallWrapper, isWrapped, locateCli } from "./surfaces/wrap.js";
+export { installStatusline, uninstallStatusline, isStatuslineInstalled } from "./surfaces/statusline.js";
+export { surfaces, getSurface, type Surface } from "./surfaces/surfaces.js";
+export { paths, termadHome, backupPath } from "./core/paths.js";

package/dist/index.js

@@ -0,0 +1,9 @@
+export { isValidAd } from "./core/ad.js";
+export { fetchAd, writeAdCache, readAdCache } from "./core/source.js";
+export { loadConfig, saveConfig } from "./core/config.js";
+export { install, uninstall, sync } from "./install.js";
+export { render, renderLine, renderBanner } from "./render/render.js";
+export { installWrapper, uninstallWrapper, isWrapped, locateCli } from "./surfaces/wrap.js";
+export { installStatusline, uninstallStatusline, isStatuslineInstalled } from "./surfaces/statusline.js";
+export { surfaces, getSurface } from "./surfaces/surfaces.js";
+export { paths, termadHome, backupPath } from "./core/paths.js";

package/dist/install.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Install / uninstall orchestration across all opted-in surfaces.
+ *
+ * Every change is recorded in the sha256 audit manifest BEFORE the user
+ * consents (the plan is shown) and re-verified by `termad audit`.
+ */
+import { type SurfaceId } from "./core/config.js";
+export interface SurfaceOutcome {
+    surface: SurfaceId;
+    ok: boolean;
+    detail: string;
+}
+export interface PlanItem {
+    surface: SurfaceId;
+    target: string;
+    action: string;
+}
+/** What `termad install` would change — shown to the user before consent. */
+export declare function planInstall(surfaces?: SurfaceId[], force?: boolean): PlanItem[];
+/** Fetch the ad, write the cache, then install the opted-in surfaces. */
+export declare function install(surfaces?: SurfaceId[], opts?: {
+    force?: boolean;
+}): Promise<SurfaceOutcome[]>;
+export declare function uninstall(surfaces?: SurfaceId[]): SurfaceOutcome[];
+/** Refresh the ad cache (used by `termad watch` and cron). */
+export declare function sync(): Promise<string>;

package/dist/install.js

@@ -0,0 +1,182 @@
+/**
+ * Install / uninstall orchestration across all opted-in surfaces.
+ *
+ * Every change is recorded in the sha256 audit manifest BEFORE the user
+ * consents (the plan is shown) and re-verified by `termad audit`.
+ */
+import { loadConfig, saveConfig, writeFileAtomic } from "./core/config.js";
+import { paths, termadHome, backupPath } from "./core/paths.js";
+import { fetchAd, writeAdCache } from "./core/source.js";
+import { existsSync, mkdirSync } from "node:fs";
+import { getSurface } from "./surfaces/surfaces.js";
+import { installWrapper, uninstallWrapper, isWrapped } from "./surfaces/wrap.js";
+import { installStatusline, uninstallStatusline, settingsPath, isStatuslineInstalled } from "./surfaces/statusline.js";
+import { loadManifest, recordEntry, removeEntries, sha256File } from "./core/manifest.js";
+/** What `termad install` would change — shown to the user before consent. */
+export function planInstall(surfaces, force = false) {
+    const cfg = loadConfig();
+    const wanted = surfaces ?? Object.entries(cfg.surfaces).filter(([, v]) => v).map(([k]) => k);
+    const items = [];
+    for (const id of wanted) {
+        if (id === "claude") {
+            items.push({
+                surface: id,
+                target: settingsPath(),
+                action: isStatuslineInstalled()
+                    ? "already chained — no change"
+                    : "chain statusLine (your current statusLine captured, restored on uninstall)",
+            });
+            continue;
+        }
+        const s = getSurface(id);
+        const bin = s?.locate();
+        if (!bin) {
+            items.push({ surface: id, target: "(not found)", action: `skip — CLI not found (set TERMAD_${id.toUpperCase()}_BIN)` });
+            continue;
+        }
+        items.push({
+            surface: id,
+            target: bin,
+            action: isWrapped(bin)
+                ? force
+                    ? "re-bake wrapper (pristine backup kept)"
+                    : "already wrapped — no change"
+                : `wrap binary; pristine original → ${backupPath(bin)}`,
+        });
+    }
+    return items;
+}
+/** Fetch the ad, write the cache, then install the opted-in surfaces. */
+export async function install(surfaces, opts = {}) {
+    const force = opts.force ?? false;
+    const cfg = loadConfig();
+    mkdirSync(termadHome(), { recursive: true });
+    const ad = await fetchAd(surfaces?.[0] ?? "claude");
+    writeAdCache(ad);
+    const wanted = surfaces ?? Object.entries(cfg.surfaces).filter(([, v]) => v).map(([k]) => k);
+    const out = [];
+    for (const id of wanted) {
+        const s = getSurface(id);
+        if (!s)
+            continue;
+        if (id === "claude") {
+            const target = settingsPath();
+            const shaBefore = sha256File(target);
+            const hadEntry = manifestHas(id, target);
+            const r = installStatusline();
+            if (r.ok && !hadEntry) {
+                recordEntry({
+                    surface: id,
+                    target,
+                    mechanism: "statusline",
+                    backup: existsSync(paths.prevStatusline()) ? paths.prevStatusline() : null,
+                    sha256Original: shaBefore,
+                    sha256Installed: sha256File(target),
+                });
+            }
+            out.push({ surface: id, ok: r.ok, detail: r.alreadyInstalled ? "already installed" : r.ok ? "statusline chained" : (r.reason ?? "failed") });
+        }
+        else {
+            const bin = s.locate();
+            if (!bin) {
+                out.push({ surface: id, ok: false, detail: "CLI not found (set TERMAD_" + id.toUpperCase() + "_BIN)" });
+                continue;
+            }
+            const wasWrapped = isWrapped(bin);
+            const shaBefore = sha256File(bin);
+            const r = installWrapper(bin, paths.adCache(), force);
+            if (r.ok) {
+                const entry = loadManifest().entries.find((e) => e.surface === id && e.target === bin);
+                if (!entry) {
+                    if (wasWrapped) {
+                        // Legacy install (no manifest yet): original = the backup's bytes.
+                        recordEntry({
+                            surface: id,
+                            target: bin,
+                            mechanism: "wrapper",
+                            backup: backupPath(bin),
+                            sha256Original: sha256File(backupPath(bin)),
+                            sha256Installed: shaBefore,
+                        });
+                    }
+                    else {
+                        recordEntry({
+                            surface: id,
+                            target: bin,
+                            mechanism: "wrapper",
+                            backup: backupPath(bin),
+                            sha256Original: shaBefore,
+                            sha256Installed: sha256File(bin),
+                        });
+                    }
+                }
+                else if (force && wasWrapped) {
+                    // Re-bake: original stays, installed fingerprint follows the new wrapper.
+                    recordEntry({
+                        surface: entry.surface,
+                        target: entry.target,
+                        mechanism: entry.mechanism,
+                        backup: entry.backup,
+                        sha256Original: entry.sha256Original,
+                        sha256Installed: sha256File(bin),
+                    });
+                }
+            }
+            out.push({ surface: id, ok: r.ok, detail: r.alreadyInstalled ? "already wrapped" : r.ok ? `wrapped ${bin}` : (r.reason ?? "failed") });
+        }
+        cfg.surfaces[id] = true;
+    }
+    saveConfig(cfg);
+    return out;
+}
+function manifestHas(surface, target) {
+    return loadManifest().entries.some((e) => e.surface === surface && e.target === target);
+}
+export function uninstall(surfaces) {
+    const cfg = loadConfig();
+    const wanted = surfaces ?? Object.keys(cfg.surfaces).filter((k) => cfg.surfaces[k]);
+    const out = [];
+    for (const id of wanted) {
+        const s = getSurface(id);
+        if (!s)
+            continue;
+        if (id === "claude") {
+            const r = uninstallStatusline();
+            if (r.ok && r.alreadyInstalled)
+                removeEntries(id);
+            out.push({ surface: id, ok: r.ok, detail: r.reason ?? (r.alreadyInstalled ? "restored" : "nothing to do") });
+        }
+        else {
+            const bin = s.locate();
+            if (!bin) {
+                out.push({ surface: id, ok: false, detail: "CLI not found" });
+                continue;
+            }
+            // Integrity gate: never restore from a backup that fails its sha256 check.
+            const entry = loadManifest().entries.find((e) => e.surface === id && e.target === bin);
+            if (entry?.backup && entry.sha256Original && sha256File(entry.backup) !== entry.sha256Original) {
+                out.push({
+                    surface: id,
+                    ok: false,
+                    detail: "REFUSED: backup fails sha256 check (tampered) — run `termad audit`; restore manually if needed",
+                });
+                continue;
+            }
+            const r = uninstallWrapper(bin, paths.adCache());
+            if (r.ok && r.alreadyInstalled)
+                removeEntries(id);
+            out.push({ surface: id, ok: r.ok, detail: r.reason ?? (r.alreadyInstalled ? `restored ${bin}` : "nothing to do") });
+        }
+        cfg.surfaces[id] = false;
+    }
+    saveConfig(cfg);
+    return out;
+}
+/** Refresh the ad cache (used by `termad watch` and cron). */
+export async function sync() {
+    const cfg = loadConfig();
+    const ad = await fetchAd("claude");
+    writeAdCache(ad);
+    writeFileAtomic(paths.adCache() + ".meta", JSON.stringify({ at: Date.now(), endpoint: cfg.endpoint }));
+    return ad.text;
+}

package/dist/render/render.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Terminal renderers — the "reservation space".
+ *
+ * line:    one line of wording (+ optional auto-linked URL)
+ * banner:  small ANSI box — a "selected banner" that catches the eye
+ *
+ * All output is plain text + ANSI color. No images, no escape-sequence
+ * hyperlinks (OSC 8) — bare URLs let the terminal's own link detection
+ * do the clicking, which is the most portable path.
+ */
+declare const BOLD = "\u001B[1m";
+export interface AdLines {
+    text: string;
+    url?: string;
+    sub?: string;
+}
+export declare function renderLine(ad: AdLines): string;
+export declare function renderBanner(ad: AdLines): string;
+export declare function render(ad: AdLines, style: "line" | "banner"): string;
+export { BOLD };

package/dist/render/render.js

@@ -0,0 +1,47 @@
+/**
+ * Terminal renderers — the "reservation space".
+ *
+ * line:    one line of wording (+ optional auto-linked URL)
+ * banner:  small ANSI box — a "selected banner" that catches the eye
+ *
+ * All output is plain text + ANSI color. No images, no escape-sequence
+ * hyperlinks (OSC 8) — bare URLs let the terminal's own link detection
+ * do the clicking, which is the most portable path.
+ */
+const RESET = "\x1b[0m";
+const DIM = "\x1b[2m";
+const BOLD = "\x1b[1m";
+const CYAN = "\x1b[36m";
+const YELLOW = "\x1b[33m";
+export function renderLine(ad) {
+    const out = [`${DIM}  [ad]${RESET} ${YELLOW}${ad.text}${RESET}`];
+    if (ad.url)
+        out.push(`  ${CYAN}${ad.url}${RESET}`);
+    if (ad.sub)
+        out.push(`  ${DIM}${ad.sub}${RESET}`);
+    return out.join("\n");
+}
+export function renderBanner(ad) {
+    const content = [ad.text, ...(ad.url ? [ad.url] : []), ...(ad.sub ? [ad.sub] : [])];
+    const width = Math.min(Math.max(...content.map((l) => visibleLen(l))), 56);
+    const bar = "─".repeat(width + 2);
+    const row = (s) => `  ${DIM}│${RESET} ${YELLOW}${pad(s, width)}${RESET} ${DIM}│${RESET}\n`;
+    let out = `  ${DIM}╭${bar}╮${RESET}\n`;
+    out += `  ${DIM}│${RESET} ${DIM}${pad("ad", width)}${RESET} ${DIM}│${RESET}\n`;
+    out += `  ${DIM}├${bar}┤${RESET}\n`;
+    for (const line of content)
+        out += row(line);
+    out += `  ${DIM}╰${bar}╯${RESET}`;
+    return out;
+}
+export function render(ad, style) {
+    return style === "banner" ? renderBanner(ad) : renderLine(ad);
+}
+/** Width ignoring ANSI codes. */
+function visibleLen(s) {
+    return s.replace(/\x1b\[[0-9;]*m/g, "").length;
+}
+function pad(s, width) {
+    return s + " ".repeat(Math.max(0, width - visibleLen(s)));
+}
+export { BOLD };

package/dist/report.d.ts

@@ -0,0 +1,7 @@
+/** Counts from the live log (used by tests / `termad status`). */
+export declare function pendingDisplayCount(): number;
+/**
+ * Report accumulated displays. Returns a human summary, or null when there
+ * is nothing to report or the endpoint is unreachable (counts are kept).
+ */
+export declare function reportDisplays(): Promise<string | null>;

package/dist/report.js

@@ -0,0 +1,91 @@
+/**
+ * Batch impression reporting: the wrapper appends one line of ad id to the
+ * display log per render; this reports the accumulated counts to the
+ * endpoint and credits the runner's 50% share in the ledger.
+ *
+ * No per-render network activity exists anywhere — the only "measurement"
+ * is counting what was actually printed to a terminal.
+ */
+import { appendFileSync, readFileSync, renameSync, rmSync } from "node:fs";
+import { loadConfig } from "./core/config.js";
+import { paths } from "./core/paths.js";
+const PENDING = () => paths.displayLog() + ".sending";
+const REPORT_TIMEOUT_MS = 5000;
+/** Counts from the live log (used by tests / `termad status`). */
+export function pendingDisplayCount() {
+    let raw = "";
+    try {
+        raw = readFileSync(paths.displayLog(), "utf8");
+    }
+    catch {
+        return 0;
+    }
+    return raw.split("\n").filter((l) => l.trim()).length;
+}
+/**
+ * Report accumulated displays. Returns a human summary, or null when there
+ * is nothing to report or the endpoint is unreachable (counts are kept).
+ */
+export async function reportDisplays() {
+    const cfg = loadConfig();
+    if (!cfg.endpoint)
+        return null;
+    // Recover a previous attempt that failed mid-flight (counts are never
+    // dropped silently; worst case a crash re-reports one batch once).
+    try {
+        const prev = readFileSync(PENDING(), "utf8");
+        if (prev)
+            appendFileSync(paths.displayLog(), prev);
+        rmSync(PENDING(), { force: true });
+    }
+    catch { }
+    let raw;
+    try {
+        raw = readFileSync(paths.displayLog(), "utf8");
+    }
+    catch {
+        return null;
+    }
+    const counts = {};
+    for (const line of raw.split("\n")) {
+        const id = line.trim();
+        if (id)
+            counts[id] = (counts[id] ?? 0) + 1;
+    }
+    const total = Object.values(counts).reduce((a, b) => a + b, 0);
+    if (!total)
+        return null;
+    // Snapshot before the POST so renders that happen mid-flight stay counted.
+    try {
+        renameSync(paths.displayLog(), PENDING());
+    }
+    catch {
+        return null;
+    }
+    try {
+        const res = await fetch(`${cfg.endpoint.replace(/\/+$/, "")}/v1/report`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ uid: cfg.uid, counts }),
+            signal: AbortSignal.timeout(REPORT_TIMEOUT_MS),
+        });
+        if (!res.ok)
+            return null;
+        const body = (await res.json());
+        rmSync(PENDING(), { force: true });
+        const share = typeof body.runnerEarnedMilliCents === "number"
+            ? `, runner share +$${(body.runnerEarnedMilliCents / 1000 / 100).toFixed(4)}`
+            : "";
+        return `${total} display(s) reported${share}`;
+    }
+    catch {
+        // Endpoint down → restore the snapshot so nothing is lost.
+        try {
+            const snap = readFileSync(PENDING(), "utf8");
+            appendFileSync(paths.displayLog(), snap);
+            rmSync(PENDING(), { force: true });
+        }
+        catch { }
+        return null;
+    }
+}

package/dist/surfaces/statusline.d.ts

@@ -0,0 +1,9 @@
+export declare function settingsPath(): string;
+export interface StatuslineInstallResult {
+    ok: boolean;
+    alreadyInstalled?: boolean;
+    reason?: string;
+}
+export declare function installStatusline(): StatuslineInstallResult;
+export declare function uninstallStatusline(): StatuslineInstallResult;
+export declare function isStatuslineInstalled(): boolean;