toolroll 0.5.0

package/dist/monitoring-settings.js

@@ -0,0 +1,173 @@
+/**
+ * Settings → Monitoring (v104): where Toolroll sends what it does, for
+ * the tools a company already watches. Kept in `monitoring.json` beside the
+ * database (0600, the agent fence keeps agents out), never in the database:
+ * the webhook's signing secret and a collector's header value are secrets.
+ *
+ * - The audit stream: every sealed ledger entry, in order, to a webhook
+ *   (each request signed) and/or a folder of JSON Lines files.
+ * - Traces: each finished run as an OpenTelemetry span, to a collector.
+ */
+import { randomBytes } from "node:crypto";
+import { closeSync, constants, existsSync, fsyncSync, openSync, readFileSync, realpathSync, renameSync, rmSync, writeSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+const FILE = "monitoring.json";
+/** Where an address points, without its path or query (a webhook may carry a key in either). */
+export const origin = (address) => { try {
+    return new URL(address).origin;
+}
+catch {
+    return "?";
+} };
+export const NO_MONITORING = { webhook: null, folder: null, traces: null };
+/** An address Toolroll may send to: https anywhere, http only to this machine (a collector beside it). */
+export function sendableAddress(value) {
+    let url;
+    try {
+        url = new URL(value.trim());
+    }
+    catch {
+        return null;
+    }
+    if (url.username !== "" || url.password !== "" || url.hash !== "")
+        return null;
+    const local = ["127.0.0.1", "localhost", "[::1]"].includes(url.hostname);
+    if (url.protocol !== "https:" && !(url.protocol === "http:" && local))
+        return null;
+    return url.toString().replace(/\/+$/, "");
+}
+/** A header name a collector asks for (x-honeycomb-team, DD-API-KEY, Authorization); never one HTTP itself owns. */
+const HEADER_NAME = /^[A-Za-z0-9][A-Za-z0-9-]{0,63}$/;
+const RESERVED_HEADERS = new Set(["host", "content-length", "content-type", "transfer-encoding", "connection", "cookie", "user-agent"]);
+export function readMonitoring(dir) {
+    if (!dir)
+        return NO_MONITORING;
+    const file = join(dir, FILE);
+    if (!existsSync(file))
+        return NO_MONITORING;
+    try {
+        const value = JSON.parse(readFileSync(file, "utf8"));
+        const webhook = value.webhook != null && typeof value.webhook.url === "string" && typeof value.webhook.secret === "string" && sendableAddress(value.webhook.url) !== null && value.webhook.secret.length >= 32
+            ? { url: sendableAddress(value.webhook.url), secret: value.webhook.secret } : null;
+        const folder = value.folder != null && typeof value.folder.path === "string" && isAbsolute(value.folder.path) ? { path: value.folder.path } : null;
+        const header = value.traces?.header != null && typeof value.traces.header.name === "string" && typeof value.traces.header.value === "string" && HEADER_NAME.test(value.traces.header.name)
+            ? { name: value.traces.header.name, value: value.traces.header.value } : null;
+        const traces = value.traces != null && typeof value.traces.endpoint === "string" && sendableAddress(value.traces.endpoint) !== null
+            ? { endpoint: sendableAddress(value.traces.endpoint), header } : null;
+        return { webhook, folder, traces };
+    }
+    catch {
+        return NO_MONITORING;
+    }
+}
+function write(dir, settings) {
+    const file = join(dir, FILE);
+    // A fresh name, made here (never a file or link already there), readable by its owner only, then swapped in.
+    const next = `${file}.${randomBytes(8).toString("hex")}.tmp`;
+    const handle = openSync(next, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+    try {
+        try {
+            writeSync(handle, `${JSON.stringify(settings, null, 2)}\n`);
+            fsyncSync(handle);
+        }
+        finally {
+            closeSync(handle);
+        }
+        renameSync(next, file);
+    }
+    catch (error) {
+        rmSync(next, { force: true });
+        throw error;
+    }
+}
+/** A fresh signing secret for the webhook (shown once; the receiver keeps it to check each request). */
+export function newSigningSecret() {
+    return `whsec_${randomBytes(32).toString("base64url")}`;
+}
+/**
+ * Save what the form sent. A blank field turns that destination off; a header value left blank keeps the one
+ * saved. A new webhook address, or `rotate`, makes a new signing secret, handed back once as `secret`.
+ */
+/** A path as it really is: its nearest existing folder resolved (so /tmp and /private/tmp are one), in one case
+ * (macOS folders ignore it). */
+function realish(path) {
+    let at = resolve(path), rest = "";
+    while (!existsSync(at) && dirname(at) !== at) {
+        rest = join(at.slice(dirname(at).length + 1), rest);
+        at = dirname(at);
+    }
+    try {
+        return join(realpathSync.native(at), rest).toLowerCase();
+    }
+    catch {
+        return resolve(path).toLowerCase();
+    }
+}
+const within = (path, folder) => path === folder || path.startsWith(`${folder}/`);
+export function saveMonitoring(dir, form, previous, forbidden = []) {
+    let webhook = null, secret = null;
+    if (form.webhook.trim() !== "") {
+        const url = sendableAddress(form.webhook);
+        if (url === null)
+            return { ok: false, said: "The webhook is an https address (http only for this machine), with no user name or password in it." };
+        const keep = previous.webhook !== null && previous.webhook.url === url && !form.rotate;
+        if (!keep)
+            secret = newSigningSecret();
+        webhook = { url, secret: keep ? previous.webhook.secret : secret };
+    }
+    let folder = null;
+    if (form.folder.trim() !== "") {
+        const path = form.folder.trim();
+        if (!isAbsolute(path) || path.length > 500 || /[\u0000-\u001f]/.test(path))
+            return { ok: false, said: "The folder is a full path, like /var/log/standing-orders." };
+        // Never where an agent works or Toolroll keeps its own state: an agent could read the whole stream there.
+        const real = realish(path);
+        if ([dir, ...forbidden].some(one => within(real, realish(one)) || within(realish(one), real)))
+            return { ok: false, said: "Choose a folder outside Toolroll's own folder and your projects, like /var/log/standing-orders." };
+        folder = { path };
+    }
+    let traces = null;
+    if (form.tracesEndpoint.trim() !== "") {
+        const endpoint = sendableAddress(form.tracesEndpoint);
+        if (endpoint === null)
+            return { ok: false, said: "The collector is an https address (http only for this machine), like https://otel.example.com:4318." };
+        const name = form.headerName.trim();
+        let header = null;
+        if (name !== "") {
+            if (!HEADER_NAME.test(name) || RESERVED_HEADERS.has(name.toLowerCase()))
+                return { ok: false, said: "The header name is letters, digits and dashes, like x-honeycomb-team." };
+            // A saved key stays only with the same collector (origin) and header: it never follows the address elsewhere.
+            const sameCollector = previous.traces !== null && origin(previous.traces.endpoint) === origin(endpoint) && previous.traces.header?.name === name;
+            const value = form.headerValue.trim() !== "" ? form.headerValue.trim() : sameCollector ? previous.traces.header.value : "";
+            if (value === "" || value.length > 2000 || /[\u0000-\u001f]/.test(value))
+                return { ok: false, said: "Enter the header's value (the collector's API key)." };
+            header = { name, value };
+        }
+        traces = { endpoint, header };
+    }
+    const settings = { webhook, folder, traces };
+    write(dir, settings);
+    return { ok: true, settings, secret };
+}
+/** The change in words for the ledger: where things go and header names, never a secret or a full address. */
+export function monitoringWords(settings) {
+    const parts = [
+        settings.webhook === null ? null : `webhook ${origin(settings.webhook.url)}`,
+        settings.folder === null ? null : `folder ${settings.folder.path}`,
+        settings.traces === null ? null : `traces ${origin(settings.traces.endpoint)}${settings.traces.header === null ? "" : ` (${settings.traces.header.name})`}`,
+    ].filter((one) => one !== null);
+    return parts.length === 0 ? "off" : parts.join("; ");
+}
+/** A change for the ledger: before → after, and what changed that the words alone don't show (never the values). */
+export function monitoringChange(before, after, newSecret) {
+    const notes = [
+        before.webhook !== null && after.webhook !== null && before.webhook.url !== after.webhook.url && origin(before.webhook.url) === origin(after.webhook.url) ? "webhook address changed" : null,
+        newSecret && before.webhook !== null && after.webhook !== null && before.webhook.url === after.webhook.url ? "new signing secret" : null,
+        before.traces !== null && after.traces !== null && before.traces.endpoint !== after.traces.endpoint && origin(before.traces.endpoint) === origin(after.traces.endpoint) ? "collector address changed" : null,
+        before.traces?.header != null && after.traces?.header != null && before.traces.header.name === after.traces.header.name && before.traces.header.value !== after.traces.header.value ? "new header value" : null,
+    ].filter((one) => one !== null);
+    const words = { before: monitoringWords(before), after: monitoringWords(after) };
+    if (words.before === words.after && notes.length === 0)
+        return null;
+    return `${words.before} → ${words.after}${notes.length === 0 ? "" : ` (${notes.join(", ")})`}`;
+}

package/dist/monitoring-ui.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Settings → Monitoring (v104): an instance operator points Toolroll at
+ * the company's tools. One form, the status of each destination beside it,
+ * and how Prometheus reads `/metrics`. The signing secret is shown once.
+ */
+import type { MonitoringStatus } from "./store.js";
+import type { MonitoringSettings } from "./monitoring-settings.js";
+export declare const MONITORING_CSS: string;
+export type MonitoringView = {
+    settings: MonitoringSettings;
+    status: MonitoringStatus[];
+    head: number;
+    origin: string | null;
+};
+export declare function monitoringHtml(view: MonitoringView, csrf: string, notice: {
+    said?: string | null;
+    problem?: string | null;
+}): string;
+/** The webhook's signing secret, once: a focused page with no script. */
+export declare function signingSecretHtml(url: string, secret: string): string;

package/dist/monitoring-ui.js

@@ -0,0 +1,51 @@
+import { targetOf } from "./monitoring.js";
+const e = (value) => String(value ?? "").replace(/[&<>"']/g, c => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
+const when = (at) => `${e(at.slice(0, 16).replace("T", " "))} UTC`;
+export const MONITORING_CSS = `.monitoring{max-width:720px;min-width:0}.monitoring fieldset{border:0;padding:0;margin:20px 0 0;min-width:0}` +
+    `.monitoring legend{font-weight:600;font-size:.9375rem;margin-bottom:6px}.monitoring label{display:grid;gap:4px;margin:10px 0 0;font-size:.875rem}` +
+    `.monitoring input[type=text],.monitoring input[type=url],.monitoring input[type=password]{width:100%;box-sizing:border-box}.monitoring .choice{display:flex;gap:8px;align-items:center}` +
+    `.monitoring .status{margin:4px 0 0;font-size:.8125rem}.monitoring .status.problem{color:var(--danger)}.monitoring .step-up{margin-top:18px}.monitoring button[type=submit]{margin-top:14px}` +
+    `.monitoring pre{white-space:pre-wrap;overflow-wrap:anywhere;font-size:.75rem}.monitoring details{margin-top:6px}`;
+/** How a destination is doing, in one line. */
+function statusLine(view, sink, address) {
+    // An empty field already says it's off.
+    if (address === null)
+        return "";
+    // A status for another address (it just changed) says nothing about this one yet.
+    const one = view.status.find(row => row.sink === sink && row.target === targetOf(address));
+    if (one === undefined || (one.lastOkAt === null && one.lastError === null))
+        return `<p class="status meta" data-monitoring="${sink}" data-state="starting">Starting: the first delivery goes out within a few seconds.</p>`;
+    if (one.failures > 0 && one.lastError !== null) {
+        return `<p class="status problem" role="alert" data-monitoring="${sink}" data-state="failing">Failing: ${e(one.lastError)}${one.nextTryAt === null ? "" : ` · trying again ${when(one.nextTryAt)}`}</p>`;
+    }
+    const behind = Math.max(0, view.head - one.through);
+    return `<p class="status meta" data-monitoring="${sink}" data-state="ok">${sink === "traces" ? "Sending" : `Sent through entry #${one.through}`}${one.lastOkAt === null ? "" : ` · last ${when(one.lastOkAt)}`}${behind > 0 && sink !== "traces" ? ` · ${behind} to go` : ""}</p>`;
+}
+export function monitoringHtml(view, csrf, notice) {
+    const s = view.settings;
+    const note = notice.problem ? `<p class="problem" role="alert">${e(notice.problem)}</p>` : notice.said ? `<p role="status">${e(notice.said)}</p>` : "";
+    const metrics = view.origin === null ? "/metrics" : `${view.origin}/metrics`;
+    return `<section class="monitoring">${note}` +
+        `<form method="post" action="/settings/monitoring"><input type="hidden" name="csrf" value="${e(csrf)}">` +
+        `<fieldset><legend>Audit stream</legend><p class="meta">Every ledger entry with its seal, as it happens, to your log system.</p>` +
+        `<label>Webhook<input type="url" name="webhook" value="${e(s.webhook?.url ?? "")}" placeholder="https://logs.example.com/standing-orders" spellcheck="false"></label>` +
+        statusLine(view, "webhook", s.webhook?.url ?? null) +
+        (s.webhook === null ? "" : `<label class="choice"><input type="checkbox" name="rotate" value="1"> Make a new signing secret</label>`) +
+        `<label>Folder (JSON Lines, a file per day)<input type="text" name="folder" value="${e(s.folder?.path ?? "")}" placeholder="/var/log/standing-orders" spellcheck="false"></label>` +
+        statusLine(view, "folder", s.folder?.path ?? null) + `</fieldset>` +
+        `<fieldset><legend>Traces</legend><p class="meta">Each run as an OpenTelemetry span: timings, model, tokens and cost. Never a prompt or code.</p>` +
+        `<label>Collector (OTLP over HTTP)<input type="url" name="traces" value="${e(s.traces?.endpoint ?? "")}" placeholder="https://otel.example.com:4318" spellcheck="false"></label>` +
+        statusLine(view, "traces", s.traces?.endpoint ?? null) +
+        `<label>Header name (optional)<input type="text" name="header-name" value="${e(s.traces?.header?.name ?? "")}" placeholder="x-honeycomb-team" spellcheck="false"></label>` +
+        `<label>Header value<input type="password" name="header-value" autocomplete="off" placeholder="${s.traces?.header ? "Saved; leave blank to keep" : "API key"}"></label></fieldset>` +
+        `<div class="step-up"><label>Your Toolroll password<input type="password" name="password" autocomplete="current-password"></label></div>` +
+        `<button type="submit">Save</button></form>` +
+        `<fieldset><legend>Metrics</legend><p class="meta">Prometheus reads <code>${e(metrics)}</code> with an instance operator's API token (<a href="/settings/sessions">Sessions &amp; tokens</a>).</p>` +
+        `<details><summary>Example</summary><pre>curl -H "Authorization: Bearer so_…" ${e(metrics)}</pre></details></fieldset></section>`;
+}
+/** The webhook's signing secret, once: a focused page with no script. */
+export function signingSecretHtml(url, secret) {
+    return `<h1>Signing secret</h1><div class="card"><p>Give this to the receiver at <span class="mono">${e(url)}</span>. It's shown once.</p><p class="mono secret-value">${e(secret)}</p>` +
+        `<p class="meta">Each request carries <code>x-standing-orders-signature: t=&lt;time&gt;,v1=&lt;HMAC-SHA256 of "time.body"&gt;</code>. Check it, and that the time is recent.</p></div>` +
+        `<p class="meta"><a href="/settings/monitoring">Back to Monitoring</a></p>`;
+}

package/dist/monitoring.d.ts

@@ -0,0 +1,34 @@
+import type { SealedLedgerEntry, Store } from "./store.js";
+import type { MonitoringSettings } from "./monitoring-settings.js";
+export type Sink = "webhook" | "folder" | "traces";
+export declare const SIGNATURE_HEADER = "x-standing-orders-signature";
+/** An audit event: the ledger entry and its seal, as the stream sends it. */
+export declare function auditEvent(entry: SealedLedgerEntry, instance: string): Record<string, unknown>;
+/** The signature a receiver recomputes: HMAC-SHA256(secret, "<t>.<body>"), hex. */
+export declare function signature(secret: string, timestamp: number, body: string): string;
+export type MonitoringDeps = {
+    fetch?: typeof fetch;
+    now?: () => Date;
+    holder: string;
+    instance: string;
+    version: string;
+};
+/** One pass over every destination that's set up. Returns what it sent, per destination. */
+export declare function monitoringPass(store: Store, settings: MonitoringSettings, deps: MonitoringDeps): Promise<Partial<Record<Sink, number>>>;
+/** A destination's name in its status row: a digest of its address (the address itself may carry a key). */
+export declare const targetOf: (address: string) => string;
+/** Spans for the batch's finished runs and completed tasks (the rest of the ledger isn't traced; the cursor passes it). */
+export declare function spansFor(store: Store, entries: SealedLedgerEntry[]): Record<string, unknown>[];
+/** This build's version, from its package.json ("unknown" when it can't be read). */
+export declare function packageVersion(): string;
+/** Who this process is, for the lease: host, pid and a random part (a restarted pid is a new holder). */
+export declare function monitoringHolder(): string;
+/** The loop `up` runs: a pass every `everyMs`, settings read afresh each time (a change applies at the next pass). */
+export declare function startMonitoring(options: {
+    store: Store;
+    settings: () => MonitoringSettings;
+    instance: string;
+    version: string;
+    everyMs?: number;
+    progress?: (line: string) => void;
+}): () => void;

package/dist/monitoring.js

@@ -0,0 +1,221 @@
+/**
+ * Monitoring (v104): what Toolroll does, sent to the tools a company
+ * already watches. One loop in `up` makes a pass every few seconds; each
+ * destination is sent to by one process at a time (a lease in
+ * `monitoring_status`), in ledger order, at least once: its cursor moves only
+ * after a delivery lands, so a failure is retried (backing off to five
+ * minutes) and nothing is skipped or reordered.
+ *
+ * - `webhook`: sealed ledger entries, POSTed in batches, each request signed
+ *   (`x-standing-orders-signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of
+ *   "<t>.<body>" with the signing secret>`). Each batch carries the chain
+ *   head, so the receiver keeps its own copy of the checkpoints.
+ * - `folder`: the same events as JSON Lines, a file per day.
+ * - `traces`: each finished run as an OpenTelemetry span (OTLP/HTTP JSON),
+ *   and each completed task as the root span its runs hang under. Model,
+ *   tokens, cost and timings; never a prompt, a diff or a file.
+ */
+import { createHash, createHmac, randomUUID } from "node:crypto";
+import { closeSync, constants, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, writeSync } from "node:fs";
+import { hostname } from "node:os";
+import { basename, join } from "node:path";
+import { COMPLETION_ACTION } from "./result-completion.js";
+export const SIGNATURE_HEADER = "x-standing-orders-signature";
+const BATCH = 200;
+const LEASE_MS = 60_000;
+const TIMEOUT_MS = 10_000;
+/** An audit event: the ledger entry and its seal, as the stream sends it. */
+export function auditEvent(entry, instance) {
+    return {
+        type: "standing-orders.audit", instance, id: entry.id, at: entry.at, actor: entry.actor, project: entry.repo, task: entry.taskId, run: entry.runId,
+        action: entry.action, outcome: entry.outcome, source: entry.source, detail: entry.detail, seal: entry.seal,
+    };
+}
+/** The signature a receiver recomputes: HMAC-SHA256(secret, "<t>.<body>"), hex. */
+export function signature(secret, timestamp, body) {
+    return `t=${timestamp},v1=${createHmac("sha256", secret).update(`${timestamp}.${body}`, "utf8").digest("hex")}`;
+}
+const backoff = (failures) => Math.min(5 * 60_000, 5_000 * 2 ** Math.min(failures, 10));
+const hex = (text, length) => createHash("sha256").update(text, "utf8").digest("hex").slice(0, length);
+const nanos = (at) => `${BigInt(Date.parse(at)) * 1000000n}`;
+/** One pass over every destination that's set up. Returns what it sent, per destination. */
+export async function monitoringPass(store, settings, deps) {
+    const sent = {};
+    // A new destination gets the whole audit history; traces start from now.
+    if (settings.webhook !== null)
+        sent.webhook = await deliver(store, "webhook", targetOf(settings.webhook.url), () => 0, deps, entries => postSigned(settings.webhook, entries, store, deps));
+    if (settings.folder !== null)
+        sent.folder = await deliver(store, "folder", targetOf(settings.folder.path), () => 0, deps, async (entries) => { appendFolder(settings.folder.path, entries, deps.instance); return entries.length; });
+    if (settings.traces !== null)
+        sent.traces = await deliver(store, "traces", targetOf(settings.traces.endpoint), () => store.ledgerHeadId(), deps, entries => postTraces(settings.traces, entries, store, deps));
+    return sent;
+}
+/** A destination's name in its status row: a digest of its address (the address itself may carry a key). */
+export const targetOf = (address) => hex(`standing-orders/monitoring/${address}`, 16);
+/** Send what's due to one destination: hold it, start it over if it now points elsewhere, read after its cursor,
+ * hand the batch over, and move the cursor only when it landed and nothing changed meanwhile. */
+async function deliver(store, sink, target, start, deps, send) {
+    const now = deps.now ?? (() => new Date());
+    const at = now();
+    if (!store.holdMonitoring(sink, deps.holder, at, new Date(at.getTime() + LEASE_MS)))
+        return 0;
+    let status = store.monitoringStatus(sink)[0];
+    if (status === undefined || status.target !== target) {
+        store.resetMonitoring(sink, target, start());
+        status = store.monitoringStatus(sink)[0];
+    }
+    if (status.nextTryAt != null && Date.parse(status.nextTryAt) > at.getTime())
+        return 0;
+    const from = status.through;
+    const entries = store.sealedAfter(from, BATCH);
+    if (entries.length === 0)
+        return 0;
+    try {
+        const count = await send(entries);
+        return store.monitoringDelivered(sink, deps.holder, target, from, entries[entries.length - 1].id, count, now()) ? count : 0;
+    }
+    catch (error) {
+        store.monitoringFailed(sink, deps.holder, target, error instanceof Error ? error.message : String(error), now(), new Date(now().getTime() + backoff(status.failures + 1)));
+        return 0;
+    }
+}
+async function post(url, body, headers, deps) {
+    const response = await (deps.fetch ?? fetch)(url, {
+        method: "POST", body, redirect: "manual", signal: AbortSignal.timeout(TIMEOUT_MS),
+        headers: { "content-type": "application/json", "user-agent": `toolroll/${deps.version}`, ...headers },
+    });
+    await response.body?.cancel().catch(() => { });
+    if (response.status < 200 || response.status > 299)
+        throw new Error(`${new URL(url).host} answered ${response.status}`);
+}
+async function postSigned(webhook, entries, store, deps) {
+    const last = entries[entries.length - 1];
+    const body = JSON.stringify({ events: entries.map(one => auditEvent(one, deps.instance)), chain: { through: last.id, head: last.seal?.hash ?? null } });
+    const timestamp = Math.floor((deps.now ?? (() => new Date()))().getTime() / 1000);
+    await post(webhook.url, body, { [SIGNATURE_HEADER]: signature(webhook.secret, timestamp, body), "x-standing-orders-delivery": `${entries[0].id}-${last.id}` }, deps);
+    return entries.length;
+}
+/** Append events to the day's file (by each entry's own day), made readable by its owner only. The folder must be
+ * a real folder of this user's that nobody else can write to (a link, or a shared folder, could send the stream
+ * somewhere else). */
+function appendFolder(folder, entries, instance) {
+    mkdirSync(folder, { recursive: true, mode: 0o700 });
+    const stat = lstatSync(folder);
+    if (stat.isSymbolicLink() || !stat.isDirectory())
+        throw new Error("the folder is a link, not a folder");
+    if (typeof process.getuid === "function" && stat.uid !== process.getuid())
+        throw new Error("the folder belongs to someone else");
+    if ((stat.mode & 0o022) !== 0)
+        throw new Error("others can write to the folder");
+    const byDay = new Map();
+    for (const entry of entries) {
+        const day = /^\d{4}-\d{2}-\d{2}/.test(entry.at) ? entry.at.slice(0, 10) : "undated";
+        byDay.set(day, [...(byDay.get(day) ?? []), JSON.stringify(auditEvent(entry, instance))]);
+    }
+    for (const [day, lines] of byDay) {
+        // Never through a link someone left where the day's file goes: it would append to wherever it points.
+        const handle = openSync(join(folder, `standing-orders-audit-${day}.jsonl`), constants.O_WRONLY | constants.O_APPEND | constants.O_CREAT | constants.O_NOFOLLOW, 0o600);
+        try {
+            writeSync(handle, `${lines.join("\n")}\n`);
+            fsyncSync(handle);
+        }
+        finally {
+            closeSync(handle);
+        }
+    }
+}
+const money = (key, value) => value === null ? [] : [{ key, value: { doubleValue: value } }];
+const attr = (key, value) => value === null || value === undefined ? [] : [{ key, value: typeof value === "string" ? { stringValue: value } : Number.isInteger(value) ? { intValue: String(value) } : { doubleValue: value } }];
+/** Spans for the batch's finished runs and completed tasks (the rest of the ledger isn't traced; the cursor passes it). */
+export function spansFor(store, entries) {
+    const spans = [];
+    const rootOf = (taskId) => store.revisionAncestryStatus(taskId).chain[0] ?? taskId;
+    for (const entry of entries) {
+        if (entry.source !== "work")
+            continue;
+        if (entry.action === "run finished" && entry.runId !== null) {
+            const run = store.getRun(entry.runId);
+            const taskId = run === null ? null : store.externalIdFor(run.taskRef);
+            if (run === null || taskId === null || run.finishedAt === null)
+                continue;
+            const root = rootOf(taskId);
+            const ref = store.refForId(run.taskRef);
+            const failed = run.outcome === "failed" || run.outcome === "refused" || run.outcome === "interrupted";
+            spans.push({
+                traceId: hex(`standing-orders/trace/${root}`, 32), spanId: hex(`standing-orders/run/${run.id}`, 16), parentSpanId: hex(`standing-orders/task/${root}`, 16),
+                name: `${run.role} · ${run.provider}`, kind: 1, startTimeUnixNano: nanos(run.startedAt), endTimeUnixNano: nanos(run.finishedAt),
+                attributes: [
+                    ...attr("standing_orders.task.id", taskId), ...attr("standing_orders.task.root", root), ...attr("standing_orders.project", ref?.repo == null ? null : basename(ref.repo)),
+                    ...attr("standing_orders.run.id", run.id), ...attr("standing_orders.run.role", run.role), ...attr("standing_orders.run.outcome", run.outcome),
+                    ...attr("gen_ai.system", run.provider), ...attr("gen_ai.request.model", run.model), ...attr("gen_ai.usage.input_tokens", run.tokensIn),
+                    ...attr("gen_ai.usage.output_tokens", run.tokensOut), ...money("standing_orders.cost_usd", run.costUsd),
+                ],
+                // The outcome's word only: a run's reason is free text (a path, a provider's message).
+                status: failed ? { code: 2, message: run.outcome ?? "failed" } : { code: 1 },
+            });
+        }
+        else if (entry.action === COMPLETION_ACTION && entry.taskId !== null) {
+            const root = rootOf(entry.taskId);
+            const task = store.getTask(root);
+            if (task === null)
+                continue;
+            const ref = store.lookupRef(root);
+            spans.push({
+                traceId: hex(`standing-orders/trace/${root}`, 32), spanId: hex(`standing-orders/task/${root}`, 16),
+                name: `task · ${ref?.repo == null ? "unplaced" : basename(ref.repo)}`, kind: 1, startTimeUnixNano: nanos(task.createdAt), endTimeUnixNano: nanos(entry.at),
+                attributes: [...attr("standing_orders.task.id", root), ...attr("standing_orders.project", ref?.repo == null ? null : basename(ref.repo)), ...attr("standing_orders.completed_by", entry.actor)],
+                status: { code: 1 },
+            });
+        }
+    }
+    return spans;
+}
+async function postTraces(traces, entries, store, deps) {
+    const spans = spansFor(store, entries);
+    if (spans.length === 0)
+        return 0;
+    const body = JSON.stringify({ resourceSpans: [{
+                resource: { attributes: [...attr("service.name", "toolroll"), ...attr("service.version", deps.version), ...attr("service.instance.id", deps.instance)] },
+                scopeSpans: [{ scope: { name: "toolroll", version: deps.version }, spans }],
+            }] });
+    const url = traces.endpoint.endsWith("/v1/traces") ? traces.endpoint : `${traces.endpoint}/v1/traces`;
+    await post(url, body, traces.header === null ? {} : { [traces.header.name]: traces.header.value }, deps);
+    return spans.length;
+}
+/** This build's version, from its package.json ("unknown" when it can't be read). */
+export function packageVersion() {
+    try {
+        const parsed = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+        return typeof parsed.version === "string" ? parsed.version : "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+/** Who this process is, for the lease: host, pid and a random part (a restarted pid is a new holder). */
+export function monitoringHolder() {
+    return `${hostname()}:${process.pid}:${randomUUID().slice(0, 8)}`;
+}
+/** The loop `up` runs: a pass every `everyMs`, settings read afresh each time (a change applies at the next pass). */
+export function startMonitoring(options) {
+    const holder = monitoringHolder();
+    let stopped = false, timer = null;
+    const pass = async () => {
+        if (stopped)
+            return;
+        try {
+            const settings = options.settings();
+            if (settings.webhook !== null || settings.folder !== null || settings.traces !== null) {
+                await monitoringPass(options.store, settings, { holder, instance: options.instance, version: options.version });
+            }
+        }
+        catch (error) {
+            options.progress?.(`monitoring: a pass failed (${error instanceof Error ? error.message : String(error)})`);
+        }
+        if (!stopped)
+            timer = setTimeout(() => void pass(), options.everyMs ?? 5_000);
+    };
+    timer = setTimeout(() => void pass(), 1_000);
+    return () => { stopped = true; if (timer !== null)
+        clearTimeout(timer); };
+}

package/dist/names.d.ts

@@ -0,0 +1,67 @@
+/**
+ * The product's internal name, and every older one it still answers to.
+ *
+ * Toolroll was Standing Orders, which was nightorders. A rename must never
+ * orphan an installation: new things use the new name, while a folder,
+ * variable, branch, launchd job or skill that already exists under an older
+ * name keeps being found. Nothing is moved; the old one is used until one
+ * exists under the new name. Strings that feed a hash, a digest or a stored
+ * format id are not names in this sense and stay byte-identical.
+ */
+export declare const NAME = "toolroll";
+/** Older names, newest first. */
+export declare const LEGACY_NAMES: readonly ["standing-orders", "nightorders"];
+export declare const NAMES: readonly string[];
+/**
+ * A file inside the product's folder under `base` (~/.config, ~/.cache, or a
+ * home dotfolder when `dot` is set). The first name that already holds the
+ * file wins; otherwise the file goes into the folder that holds the database,
+ * else the first folder that exists, else a new-name folder — so one install
+ * keeps one folder, and a fresh one gets ~/.config/toolroll.
+ */
+export declare function namedPath(base: string, rest: readonly string[], options?: {
+    dot?: boolean;
+    names?: readonly string[];
+}): string;
+/** The product's folder under `base`: see namedPath. */
+export declare function namedFolder(base: string, options?: {
+    dot?: boolean;
+    names?: readonly string[];
+}): string;
+/** Every folder under `base` that any name has made, for fencing and cleanup. */
+export declare function existingFolders(base: string, options?: {
+    dot?: boolean;
+}): string[];
+/** ~/.config (or $XDG_CONFIG_HOME). */
+export declare function configBase(env: Record<string, string | undefined>, home: string): string;
+export declare const ENV_PREFIX = "TOOLROLL_";
+export declare const LEGACY_ENV_PREFIX = "STANDING_ORDERS_";
+/**
+ * An environment setting by its suffix ("DB" → TOOLROLL_DB). The new name
+ * wins whenever it is set; the old STANDING_ORDERS_ one is the fallback.
+ */
+export declare function envValue(env: Record<string, string | undefined>, suffix: string): string | undefined;
+/** The Telegram bot token's variable, and the name it had before the rename: agents never see either.
+ * Kept here, in a module with no imports of its own, so builder.ts can read it at load time. */
+export declare const TELEGRAM_TOKEN_ENV = "TOOLROLL_TELEGRAM_TOKEN";
+export declare const TELEGRAM_TOKEN_ENVS: readonly string[];
+/** Both names of a setting, for a child the plane starts: older tools read the old one. */
+export declare function envTwins(suffix: string, value: string): Record<string, string>;
+/** True for a variable of either name ("TOOLROLL_DB", "STANDING_ORDERS_DB"). */
+export declare function isOwnEnv(key: string): boolean;
+/** New task branches are toolroll/<id>; the plane's older ones stay its own. */
+export declare const BRANCH_PREFIX = "toolroll/";
+export declare const BRANCH_PREFIXES: readonly string[];
+export declare function taskBranch(id: string): string;
+/** A branch the plane made, under either name. */
+export declare function isOwnBranch(branch: string): boolean;
+/**
+ * Whether a head branch is inside a publication grant's prefix. A grant made
+ * for the plane's own branches under one name covers the same branches under
+ * the other: a standing-orders/ grant still publishes toolroll/<id> work.
+ */
+export declare function headWithin(head: string, prefix: string): boolean;
+/** Every name a task's own branch may have, newest first. */
+export declare function taskBranches(id: string): string[];
+/** The first candidate branch that already exists (a retry reuses its branch), else the first — the new name. */
+export declare function existingOrFirst(candidates: readonly string[], exists: (branch: string) => Promise<boolean>): Promise<string>;