@frontera-sdk/cli 1.53.20 → 1.53.22

package/src/telemetry/events.ts

@@ -0,0 +1,294 @@
+import { agentAttributes, isAgentService, type AgentService } from './agent-events'
+
+/**
+ * The telemetry event catalog, version 1 (design: docs/superpowers/specs/2026-11-02-frontera-telemetry-design.md).
+ *
+ * One table lists every event and the attributes it may carry. The event types,
+ * the attribute allowlist the collector is checked against, and the parse of an
+ * outbox line all read it, so adding an attribute is one change here and one to
+ * the collector's allowlist.
+ */
+
+type Kind = 'string' | 'int' | 'bool' | readonly string[]
+
+type ValueOf<K> = K extends 'string' ? string : K extends 'int' ? number : K extends 'bool' ? boolean : K extends readonly (infer V)[] ? V : never
+
+type Fields<S> = { -readonly [K in keyof S]: ValueOf<S[K]> }
+
+interface EventSpec {
+  readonly required: Readonly<Record<string, Kind>>
+  readonly optional: Readonly<Record<string, Kind>>
+  /** Whether a failure of this event carries `error.code`, `error.template` and `error.fingerprint`. */
+  readonly error: boolean
+}
+
+export const HARNESSES = ['claude', 'codex', 'grok', 'opencode'] as const
+export type Harness = (typeof HARNESSES)[number]
+
+export const VIA = ['forge', 'agent', 'terminal', 'ci'] as const
+export type Via = (typeof VIA)[number]
+
+export const APPLY_OUTCOMES = ['applied', 'failed', 'runtime_down', 'stopped'] as const
+export type ApplyOutcome = (typeof APPLY_OUTCOMES)[number]
+
+/** What started a round of applies in `local dev`. */
+export const APPLY_TRIGGERS = ['files_changed', 'runtime_started', 'dev_started', 'once', 'runtime_answering', 'restore'] as const
+export type ApplyTrigger = (typeof APPLY_TRIGGERS)[number]
+
+/** What ended, for `frontera.cli.process_exit`: the watcher, an App's dev server, the runtime, or one of its components. */
+export const EXIT_WHAT = ['local_dev', 'app_dev', 'runtime', 'postgres', 'storage', 'service', 'jobs', 'runner', 'studio'] as const
+export type ExitWhat = (typeof EXIT_WHAT)[number]
+
+export const SEVERITIES = { INFO: 9, WARN: 13, ERROR: 17 } as const
+/** `INFO` for success, `WARN` for refused or stopped, `ERROR` for failure. */
+export type Severity = keyof typeof SEVERITIES
+
+/** Attributes any event may carry, set from the process that records it. */
+export const RECORD_ATTRIBUTES = {
+  'frontera.user.id': 'string',
+  'frontera.session.id': 'string',
+  'frontera.harness': HARNESSES,
+  'frontera.invocation.id': 'string',
+  'frontera.project.hash': 'string',
+} as const satisfies Record<string, Kind>
+
+export const ERROR_ATTRIBUTES = ['error.code', 'error.template', 'error.fingerprint'] as const
+
+export const CATALOG = {
+  'frontera.cli.command': {
+    required: { 'frontera.noun': 'string', 'frontera.verb': 'string', 'frontera.flags': 'string', 'frontera.exit_code': 'int', 'frontera.via': VIA, duration_ms: 'int' },
+    optional: {},
+    error: true,
+  },
+  'frontera.cli.mcp_tool': {
+    required: { 'frontera.tool': 'string', 'frontera.ok': 'bool', duration_ms: 'int' },
+    optional: {},
+    error: true,
+  },
+  'frontera.cli.apply': {
+    required: { 'frontera.item_kind': 'string', 'frontera.item_hash': 'string', 'frontera.outcome': APPLY_OUTCOMES, 'frontera.attempt': 'int', 'frontera.trigger': APPLY_TRIGGERS, duration_ms: 'int' },
+    optional: { 'frontera.recovered_after_attempts': 'int', 'frontera.recovered_after_ms': 'int' },
+    error: true,
+  },
+  'frontera.cli.apply_round': {
+    required: { 'frontera.trigger': APPLY_TRIGGERS, 'frontera.queued': 'int', 'frontera.applied': 'int', 'frontera.failed': 'int', duration_ms: 'int' },
+    optional: {},
+    error: false,
+  },
+  'frontera.cli.process_exit': {
+    required: { 'frontera.what': EXIT_WHAT, 'frontera.expected': 'bool', duration_ms: 'int' },
+    optional: { 'frontera.exit_code': 'int', 'frontera.signal': 'string' },
+    error: false,
+  },
+  'frontera.forge.start': {
+    required: { 'frontera.projects': 'int', 'frontera.sessions': 'int', 'frontera.harnesses_found': 'string' },
+    optional: {},
+    error: false,
+  },
+  'frontera.forge.session_open': {
+    required: { 'frontera.kind': ['agent', 'terminal'], 'frontera.mode': 'string' },
+    // Absent for a plain shell.
+    optional: { 'frontera.harness': HARNESSES },
+    error: false,
+  },
+  'frontera.forge.agent_turn': {
+    required: {
+      'frontera.harness': HARNESSES,
+      'frontera.status': 'string',
+      'frontera.tokens_in': 'int',
+      'frontera.tokens_out': 'int',
+      'frontera.commands': 'int',
+      'frontera.failed_commands': 'int',
+      'frontera.frontera_failed': 'int',
+      'frontera.repeat_failures': 'int',
+      duration_ms: 'int',
+    },
+    optional: {},
+    error: true,
+  },
+  'frontera.forge.request': {
+    required: { 'frontera.route': 'string', 'frontera.method': 'string', 'frontera.status': 'int', duration_ms: 'int' },
+    optional: {},
+    error: false,
+  },
+  'frontera.forge.crash': {
+    required: { 'frontera.process': ['window', 'server', 'main'] },
+    optional: { 'frontera.page': 'string' },
+    error: true,
+  },
+} as const satisfies Record<`frontera.${string}`, EventSpec>
+
+type Catalog = typeof CATALOG
+export type EventName = keyof Catalog
+
+export const EVENT_NAMES = Object.keys(CATALOG) as EventName[]
+
+export type RecordAttributes = Partial<Fields<typeof RECORD_ATTRIBUTES>>
+
+export type AttributesOf<N extends EventName> = Fields<Catalog[N]['required']> & Partial<Fields<Catalog[N]['optional']>> & RecordAttributes
+
+/** A failure, as `redact.ts` makes it: never the raw message. */
+export interface ErrorFields {
+  code: string
+  template: string
+  fingerprint: string
+}
+
+/** One event as code records it. An event name outside the catalog, or an attribute its entry does not list, does not compile. */
+export type TelemetryEvent = {
+  [N in EventName]: { name: N; severity: Severity; attributes: AttributesOf<N> } & (Catalog[N]['error'] extends true ? { error?: ErrorFields } : { error?: never })
+}[EventName]
+
+export type AttributeValue = string | number | boolean
+
+/** Set once per batch. A type, not an interface, so it reads as a plain attribute map. */
+export type Resource = {
+  'service.name': 'frontera-cli' | 'frontera-forge'
+  'service.version': string
+  'deployment.environment': 'release' | 'dev'
+  'os.type': string
+  'host.arch': string
+  'frontera.device.id': string
+  'frontera.wsl': boolean
+}
+
+/** A coding agent's resource as Forge's relay writes it: the agent's name and version, the Forge session, and this machine's fields as Forge's own. */
+export type AgentResource = Omit<Resource, 'service.name' | 'deployment.environment'> & {
+  'service.name': AgentService
+  'frontera.session.id': string
+}
+
+/** One line of an outbox file: the event with its attributes flattened, and the resource of the process that wrote it. */
+export interface FronteraRecord {
+  resource: Resource
+  name: EventName
+  severity: Severity
+  /** Unix milliseconds. */
+  time: number
+  attributes: Record<string, AttributeValue>
+}
+
+/** A coding agent's own event, kept by its relay (agent-events.ts). */
+export interface AgentRecord {
+  resource: AgentResource
+  name: string
+  severity: Severity
+  time: number
+  attributes: Record<string, AttributeValue>
+}
+
+export type OutboxRecord = FronteraRecord | AgentRecord
+
+/** Every log record attribute key the catalog allows, for checking the collector's allowlist against. */
+export const ATTRIBUTE_KEYS: readonly string[] = [
+  ...new Set([
+    'event.name',
+    ...ERROR_ATTRIBUTES,
+    ...Object.keys(RECORD_ATTRIBUTES),
+    ...Object.values(CATALOG as Record<string, EventSpec>).flatMap((spec) => [...Object.keys(spec.required), ...Object.keys(spec.optional)]),
+  ]),
+].sort()
+
+function kindOf(name: EventName, key: string): Kind | undefined {
+  const spec = CATALOG[name] as EventSpec
+  if (spec.error && (ERROR_ATTRIBUTES as readonly string[]).includes(key)) return 'string'
+  const table = [spec.required, spec.optional, RECORD_ATTRIBUTES as Record<string, Kind>].find((t) => Object.hasOwn(t, key))
+  return table?.[key]
+}
+
+function fits(kind: Kind, value: unknown): value is AttributeValue {
+  if (kind === 'string') return typeof value === 'string'
+  if (kind === 'int') return typeof value === 'number' && Number.isInteger(value)
+  if (kind === 'bool') return typeof value === 'boolean'
+  return typeof value === 'string' && kind.includes(value)
+}
+
+/** The flat attributes of an event: its own, the process's context under them, and its error fields. */
+export function flatAttributes(event: TelemetryEvent, context: RecordAttributes = {}): Record<string, AttributeValue> {
+  const flat: Record<string, AttributeValue> = {}
+  for (const [key, value] of Object.entries({ ...context, ...event.attributes })) if (value !== undefined) flat[key] = value as AttributeValue
+  if (event.error) {
+    flat['error.code'] = event.error.code
+    flat['error.template'] = event.error.template
+    flat['error.fingerprint'] = event.error.fingerprint
+  }
+  return flat
+}
+
+/**
+ * Values that leave are short: an error template keeps its own 300
+ * characters, any other string 128. A key or an email address that slipped
+ * into one is masked, as the collector masks it (its `redaction` processor).
+ */
+const MAX_STRING: Readonly<Record<string, number>> = { 'error.template': 300 }
+export const BLOCKED_VALUES: readonly RegExp[] = [/sk-[A-Za-z0-9_-]{16,}/g, /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g]
+
+function clean<V extends AttributeValue>(key: string, value: V): V {
+  if (typeof value !== 'string') return value
+  const max = MAX_STRING[key] ?? 128
+  // Cut before masking: the email pattern backtracks quadratically on a long run of word characters.
+  const masked = BLOCKED_VALUES.reduce((text, rule) => text.replace(rule, '****'), value.slice(0, max + 64))
+  return masked.slice(0, max) as V
+}
+
+const HOST_KEYS = ['service.version', 'os.type', 'host.arch', 'frontera.device.id'] as const
+
+function parseResource(raw: unknown): Resource | AgentResource | null {
+  if (!raw || typeof raw !== 'object') return null
+  const r = raw as Record<string, unknown>
+  if (!HOST_KEYS.every((k) => typeof r[k] === 'string') || typeof r['frontera.wsl'] !== 'boolean') return null
+  const [version, os, arch, device] = HOST_KEYS.map((k) => clean(k, r[k] as string))
+  const host = { 'service.version': version!, 'os.type': os!, 'host.arch': arch!, 'frontera.device.id': device!, 'frontera.wsl': r['frontera.wsl'] }
+  const service = r['service.name']
+  if (isAgentService(service)) {
+    const session = r['frontera.session.id']
+    return typeof session === 'string' && session ? { 'service.name': service, ...host, 'frontera.session.id': clean('frontera.session.id', session) } : null
+  }
+  const environment = r['deployment.environment']
+  if ((service !== 'frontera-cli' && service !== 'frontera-forge') || (environment !== 'release' && environment !== 'dev')) return null
+  return { 'service.name': service, 'service.version': version!, 'deployment.environment': environment, 'os.type': os!, 'host.arch': arch!, 'frontera.device.id': device!, 'frontera.wsl': host['frontera.wsl'] }
+}
+
+/** A Frontera event's attributes: those its catalog entry lists, of the right type. Null for a name outside the catalog. */
+function catalogAttributes(name: string, attributes: Readonly<Record<string, unknown>>): Record<string, AttributeValue> | null {
+  if (!Object.hasOwn(CATALOG, name)) return null
+  const kept: Record<string, AttributeValue> = {}
+  for (const [key, value] of Object.entries(attributes)) {
+    const kind = kindOf(name as EventName, key)
+    if (kind && fits(kind, value)) kept[key] = value
+  }
+  return kept
+}
+
+/**
+ * An outbox line, parsed. Files on disk may be cut short by a crash or written
+ * by another release, or by hand: a line that is not a catalog event or a
+ * kept agent event is dropped, an attribute its event does not list, or of
+ * the wrong type, is left out, and every string is cut short and masked.
+ */
+export function parseRecord(line: string): OutboxRecord | null {
+  let raw: unknown
+  try {
+    raw = JSON.parse(line)
+  } catch {
+    return null
+  }
+  return recordOf(raw)
+}
+
+/** A record as it may leave the laptop, or null; what parseRecord reads and the agents' relay writes. */
+export function recordOf(raw: unknown): OutboxRecord | null {
+  if (!raw || typeof raw !== 'object') return null
+  const { resource: rawResource, name, severity, time, attributes } = raw as Record<string, unknown>
+  if (typeof name !== 'string') return null
+  if (typeof severity !== 'string' || !Object.hasOwn(SEVERITIES, severity)) return null
+  if (typeof time !== 'number' || !Number.isFinite(time)) return null
+  const resource = parseResource(rawResource)
+  if (!resource) return null
+  const given = attributes && typeof attributes === 'object' ? (attributes as Record<string, unknown>) : {}
+  const service = resource['service.name']
+  const kept = isAgentService(service) ? agentAttributes(service, name, given) : catalogAttributes(name, given)
+  if (!kept) return null
+  for (const [key, value] of Object.entries(kept)) kept[key] = clean(key, value)
+  return { resource, name, severity: severity as Severity, time, attributes: kept } as OutboxRecord
+}

package/src/telemetry/fail-open.ts

@@ -0,0 +1,44 @@
+import type { Recorder } from './recorder'
+
+const OFF: Recorder = { mode: { mode: 'off', reason: 'switched_off' }, deviceId: '', record() {}, write() {}, roll() {}, close() {}, hash: () => '' }
+
+/**
+ * The recorder an app records through, made where the app makes it (Forge's
+ * server, the `frontera` process): if making it or any call on it throws,
+ * the event is lost and the work goes on. A recorder that cannot be made
+ * records nothing.
+ */
+export function failOpen(make: () => Recorder): Recorder {
+  let made: Recorder
+  let deviceId: string
+  try {
+    made = make()
+    deviceId = made.deviceId
+  } catch {
+    return OFF
+  }
+  const quiet =
+    <A extends unknown[]>(call: (...args: A) => void) =>
+    (...args: A) => {
+      try {
+        call(...args)
+      } catch {
+        // Telemetry never fails the work it records.
+      }
+    }
+  return {
+    mode: made.mode,
+    deviceId,
+    record: quiet((event) => made.record(event)),
+    write: quiet((record) => made.write(record)),
+    roll: quiet(() => made.roll()),
+    close: quiet(() => made.close()),
+    hash: (...parts) => {
+      try {
+        return made.hash(...parts)
+      } catch {
+        return ''
+      }
+    },
+  }
+}

package/src/telemetry/otlp.ts

@@ -0,0 +1,112 @@
+import { SEVERITIES, type AttributeValue, type OutboxRecord, type Severity } from './events'
+
+/** OTLP/JSON `AnyValue`. int64 is a decimal string, as the protobuf JSON mapping writes it. */
+type AnyValue = { stringValue: string } | { intValue: string } | { doubleValue: number } | { boolValue: boolean }
+interface KeyValue {
+  key: string
+  value: AnyValue
+}
+
+export interface OtlpLogsBody {
+  resourceLogs: Array<{
+    resource: { attributes: KeyValue[] }
+    scopeLogs: Array<{
+      scope: { name: string; version: string }
+      logRecords: Array<{
+        timeUnixNano: string
+        observedTimeUnixNano: string
+        severityNumber: number
+        severityText: string
+        body: { stringValue: string }
+        attributes: KeyValue[]
+      }>
+    }>
+  }>
+}
+
+export const SCOPE = { name: 'frontera-telemetry', version: '1' } as const
+
+function anyValue(value: AttributeValue): AnyValue {
+  if (typeof value === 'boolean') return { boolValue: value }
+  if (typeof value === 'number') return Number.isInteger(value) ? { intValue: String(value) } : { doubleValue: value }
+  return { stringValue: value }
+}
+
+const keyValues = (attributes: Readonly<Record<string, AttributeValue>>): KeyValue[] => Object.entries(attributes).map(([key, value]) => ({ key, value: anyValue(value) }))
+
+const nanos = (ms: number) => `${BigInt(Math.round(ms)) * 1_000_000n}`
+
+/**
+ * Records as an OTLP/HTTP JSON logs request: one `resourceLogs` entry per
+ * distinct resource, in the order first seen; one log record per event, its
+ * body and `event.name` attribute the event name.
+ */
+export function toOtlpLogs(records: readonly OutboxRecord[], observedAt: number = Date.now()): OtlpLogsBody {
+  const byResource = new Map<string, OtlpLogsBody['resourceLogs'][number]>()
+  for (const record of records) {
+    const key = JSON.stringify(Object.entries(record.resource).sort(([a], [b]) => a.localeCompare(b)))
+    let entry = byResource.get(key)
+    if (!entry) {
+      entry = { resource: { attributes: keyValues(record.resource) }, scopeLogs: [{ scope: { ...SCOPE }, logRecords: [] }] }
+      byResource.set(key, entry)
+    }
+    entry.scopeLogs[0]!.logRecords.push({
+      timeUnixNano: nanos(record.time),
+      observedTimeUnixNano: nanos(observedAt),
+      severityNumber: SEVERITIES[record.severity],
+      severityText: record.severity,
+      body: { stringValue: record.name },
+      attributes: keyValues({ 'event.name': record.name, ...record.attributes }),
+    })
+  }
+  return { resourceLogs: [...byResource.values()] }
+}
+
+/** One log record of an OTLP/HTTP JSON request, its attributes as plain values (nested and byte values left out). */
+export interface OtlpLogRecord {
+  resource: Record<string, AttributeValue>
+  /** Unix ms: when it happened, else when it was seen, else now. */
+  time: number
+  severity: Severity
+  attributes: Record<string, AttributeValue>
+}
+
+type Json = Record<string, unknown>
+const list = (value: unknown): Json[] => (Array.isArray(value) ? value.filter((v): v is Json => !!v && typeof v === 'object') : [])
+
+function plain(value: unknown): AttributeValue | undefined {
+  if (!value || typeof value !== 'object') return undefined
+  const v = value as Json
+  if (typeof v.stringValue === 'string') return v.stringValue
+  if (typeof v.boolValue === 'boolean') return v.boolValue
+  if (typeof v.doubleValue === 'number') return v.doubleValue
+  const int = typeof v.intValue === 'string' || typeof v.intValue === 'number' ? Number(v.intValue) : Number.NaN
+  return Number.isSafeInteger(int) ? int : undefined
+}
+
+function attributesOf(value: unknown): Record<string, AttributeValue> {
+  const out: Record<string, AttributeValue> = {}
+  for (const kv of list(value)) {
+    const v = plain(kv.value)
+    if (typeof kv.key === 'string' && v !== undefined) out[kv.key] = v
+  }
+  return out
+}
+
+const millis = (nanos: unknown): number | null => {
+  const n = typeof nanos === 'string' || typeof nanos === 'number' ? Number(nanos) : 0
+  return Number.isFinite(n) && n > 0 ? Math.round(n / 1_000_000) : null
+}
+
+/** An OTLP severity number as the catalog's three: 17 and above ERROR, 13 and above WARN, else INFO. */
+const severityOf = (n: unknown): Severity => (typeof n !== 'number' ? 'INFO' : n >= SEVERITIES.ERROR ? 'ERROR' : n >= SEVERITIES.WARN ? 'WARN' : 'INFO')
+
+/** The log records of an OTLP/HTTP JSON logs request (what toOtlpLogs writes, and what other programs' exporters send). */
+export function fromOtlpLogs(body: unknown, now: number = Date.now()): OtlpLogRecord[] {
+  return list((body as Json | null)?.resourceLogs).flatMap((logs) => {
+    const resource = attributesOf((logs.resource as Json | undefined)?.attributes)
+    return list(logs.scopeLogs).flatMap((scope) =>
+      list(scope.logRecords).map((r) => ({ resource, time: millis(r.timeUnixNano) ?? millis(r.observedTimeUnixNano) ?? now, severity: severityOf(r.severityNumber), attributes: attributesOf(r.attributes) })),
+    )
+  })
+}

package/src/telemetry/outbox.ts

@@ -0,0 +1,175 @@
+import { randomUUID } from 'node:crypto'
+import { appendFileSync, readdirSync, renameSync, statSync, unlinkSync, utimesSync } from 'node:fs'
+import { join } from 'node:path'
+
+/**
+ * The outbox: a folder of JSON-lines files, one event per line.
+ *
+ * Each writer owns its own file, so concurrent CLI runs never share one and
+ * need no lock. A file's state is its suffix: written to as `<id>.jsonl.open`,
+ * closed as `<id>.jsonl` (the only state the sender reads), and claimed by the
+ * sender as `<id>.jsonl.sending` until the collector takes it. Every step is a
+ * rename, so a crash at any point leaves each file in one whole state.
+ *
+ * The folder is Forge's: it makes it while telemetry is on and removes it when
+ * the switch goes off. No writer ever makes it, so removing it stops every
+ * writer at once, including processes started while it was on.
+ */
+
+const SUFFIX = { open: '.jsonl.open', closed: '.jsonl', sending: '.jsonl.sending' } as const
+export type FileState = keyof typeof SUFFIX
+
+export interface OutboxFile {
+  /** `<unix ms>-<uuid>`: unique per file, oldest first when sorted by `time`. */
+  id: string
+  state: FileState
+  bytes: number
+  /** Unix ms the file was made (from its id). */
+  time: number
+  mtimeMs: number
+}
+
+export const OUTBOX_LIMITS = {
+  /** Past this, the oldest closed files are dropped. */
+  maxBytes: 50 * 1024 * 1024,
+  /** Closed files older than this are dropped. */
+  maxAgeMs: 14 * 24 * 60 * 60_000,
+  /** A `.sending` file this old belongs to a sender that crashed between the post and the delete: put back. */
+  staleSendingMs: 10 * 60_000,
+  /** A `.open` file untouched this long belongs to a writer that died without closing it: closed for it. */
+  staleOpenMs: 10 * 60_000,
+  /** A writer closes its file at this size and starts another, so one file always fits one request. */
+  rollBytes: 256 * 1024,
+  /** A long-lived writer closes its file this often, so the sender sees its events while it runs. */
+  rollMs: 60_000,
+} as const
+
+const pathOf = (dir: string, id: string, state: FileState) => join(dir, `${id}${SUFFIX[state]}`)
+
+function stateOf(name: string): { id: string; state: FileState } | null {
+  for (const state of ['sending', 'open', 'closed'] as const) {
+    if (name.endsWith(SUFFIX[state])) return { id: name.slice(0, -SUFFIX[state].length), state }
+  }
+  return null
+}
+
+/** Every outbox file, oldest first. A missing folder is an empty outbox. */
+export function listOutbox(dir: string): OutboxFile[] {
+  let names: string[]
+  try {
+    names = readdirSync(dir)
+  } catch {
+    return []
+  }
+  const files: OutboxFile[] = []
+  for (const name of names) {
+    const parsed = stateOf(name)
+    if (!parsed) continue
+    try {
+      const stat = statSync(join(dir, name))
+      const time = Number.parseInt(parsed.id, 10)
+      files.push({ ...parsed, bytes: stat.size, mtimeMs: stat.mtimeMs, time: Number.isFinite(time) ? time : stat.mtimeMs })
+    } catch {
+      // Claimed or deleted since the listing.
+    }
+  }
+  return files.sort((a, b) => a.time - b.time || a.id.localeCompare(b.id))
+}
+
+function move(dir: string, id: string, from: FileState, to: FileState, toId = id): boolean {
+  try {
+    renameSync(pathOf(dir, id, from), pathOf(dir, toId, to))
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Claim a closed file for sending. False when it is gone (another sender took
+ * it). Touched, so the 10 minutes after which a claim counts as left by a
+ * crashed sender run from the claim, not from the file's last write.
+ */
+export function claim(dir: string, id: string, now: number = Date.now()): boolean {
+  if (!move(dir, id, 'closed', 'sending')) return false
+  try {
+    utimesSync(pathOf(dir, id, 'sending'), now / 1000, now / 1000)
+  } catch {
+    // Taken back since; the claim still holds or is gone, either way nothing to touch.
+  }
+  return true
+}
+
+/** Give a claimed file back after a failed send. */
+export const putBack = (dir: string, id: string) => move(dir, id, 'sending', 'closed')
+
+/** Delete a file the collector took, or one that can never be sent. */
+export function remove(dir: string, id: string, state: FileState = 'sending'): void {
+  try {
+    unlinkSync(pathOf(dir, id, state))
+  } catch {
+    // Already gone.
+  }
+}
+
+export function readPath(dir: string, file: Pick<OutboxFile, 'id' | 'state'>): string {
+  return pathOf(dir, file.id, file.state)
+}
+
+/**
+ * Converge after crashes: a `.sending` file older than 10 minutes goes back
+ * (its sender died between the post and the delete, so it is sent again), and
+ * a `.open` file untouched for 10 minutes is closed for the writer that died.
+ * It is closed under a new id: a writer that was only slow, and appends again,
+ * then starts a new file of the old name instead of overwriting this one.
+ */
+export function recoverStale(dir: string, now: number): void {
+  for (const file of listOutbox(dir)) {
+    if (now - file.mtimeMs < (file.state === 'open' ? OUTBOX_LIMITS.staleOpenMs : OUTBOX_LIMITS.staleSendingMs)) continue
+    if (file.state === 'sending') putBack(dir, file.id)
+    if (file.state === 'open') move(dir, file.id, 'open', 'closed', `${file.id}-r${randomUUID().slice(0, 8)}`)
+  }
+}
+
+/** Drop closed files older than 14 days, then the oldest until the closed files hold 50 MiB or less. Returns how many were dropped. */
+export function prune(dir: string, now: number, limits: { maxBytes: number; maxAgeMs: number } = OUTBOX_LIMITS): number {
+  const closed = listOutbox(dir).filter((f) => f.state === 'closed')
+  let total = closed.reduce((sum, f) => sum + f.bytes, 0)
+  let dropped = 0
+  for (const file of closed) {
+    if (now - file.mtimeMs <= limits.maxAgeMs && total <= limits.maxBytes) continue
+    remove(dir, file.id, 'closed')
+    total -= file.bytes
+    dropped += 1
+  }
+  return dropped
+}
+
+export interface OutboxWriter {
+  /** Append one line to this writer's open file, starting one when there is none. Throws when the folder is gone. */
+  append(line: string): void
+  /** Close the open file, if any, so the sender can take it. The next append starts a new one. */
+  roll(): void
+}
+
+export function outboxWriter(dir: string, opts: { now?: () => number; rollBytes?: number } = {}): OutboxWriter {
+  const now = opts.now ?? Date.now
+  const rollBytes = opts.rollBytes ?? OUTBOX_LIMITS.rollBytes
+  let current: { id: string; bytes: number } | null = null
+  const roll = () => {
+    if (!current) return
+    const { id } = current
+    current = null
+    move(dir, id, 'open', 'closed')
+  }
+  return {
+    append(line) {
+      current ??= { id: `${now()}-${randomUUID()}`, bytes: 0 }
+      const text = `${line}\n`
+      appendFileSync(pathOf(dir, current.id, 'open'), text)
+      current.bytes += Buffer.byteLength(text)
+      if (current.bytes >= rollBytes) roll()
+    },
+    roll,
+  }
+}