@cohortapp/agent-sdk 2.3.0

package/lib/diagnostics/counters.mjs

@@ -0,0 +1,269 @@
+/**
+ * lib/diagnostics/counters.mjs — loud, durable counters for guard fail-opens.
+ *
+ * The audit's silent-failure epidemic (gaps-product-quality P0-6) is not that
+ * the guards fail open — failing open is the deliberate, correct policy ("a
+ * duplicate is cheaper than a missed cadence"; "a breaker we can't persist
+ * degrades to in-memory only"). The bug is that they fail open *silently*: a
+ * rate-guard whose state dir is unwritable never opens for anyone, a budget-guard
+ * that reads a stale ledger as $0 spends forever, and NOTHING anywhere counts it,
+ * so doctor and a human stay blind to the exact failure that matters.
+ *
+ * This module gives every fail-open a place to be *counted somewhere a human or
+ * doctor looks*. `bump(name, attrs)` increments an in-memory tally AND appends a
+ * JSON line to `logs/diagnostics/counters/<YYYY-MM-DD>.jsonl` (via the shared
+ * atomic appender), so the count survives a restart and a crash mid-write can
+ * never corrupt the stream. `snapshot()` reads back today's totals for doctor.
+ *
+ * Invariant: NEITHER `bump` NOR `snapshot` EVER throws. A counter that can take
+ * down the path it observes is worse than no counter at all — so a bad name, an
+ * un-serializable attr, an unwritable disk all degrade to a return value, never
+ * an exception. (This mirrors lib/diagnostics/events.mjs and the fail-open idiom
+ * in lib/cadence-bus.mjs.)
+ *
+ * The in-memory tally is process-local and is the fast path doctor/tests read
+ * when they share the process; the JSONL stream is the cross-process / cross-
+ * restart source of truth that `snapshot()` reconstructs from disk when asked.
+ *
+ * Constraints (CLAUDE.md): ESM, Node built-ins + lib/fs-atomic only, injectable
+ * clock + log dir + append + read so tests are hermetic and need no real disk.
+ *
+ * @module lib/diagnostics/counters
+ */
+
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+import { appendJsonl } from "../fs-atomic.mjs";
+
+/**
+ * Process-local running tally, keyed by counter name. This is a best-effort
+ * accelerator: it lets a long-lived daemon (and same-process tests) read totals
+ * without re-parsing the JSONL, but it is NOT the source of truth — `snapshot()`
+ * reconstructs from disk so counts survive a restart and span processes.
+ * @type {Map<string, number>}
+ */
+const MEM = new Map();
+
+/**
+ * Resolve the counters log directory: `<agentRoot>/logs/diagnostics/counters`.
+ * An explicit `deps.dir` wins (tests point it at a tmp dir); otherwise we derive
+ * it from the agent root the same way every other maestro module does.
+ * @param {object} [deps]
+ * @returns {string}
+ */
+function countersDir(deps = {}) {
+  if (deps.dir) return resolve(deps.dir);
+  const root = resolve(
+    deps.agentRoot ||
+      process.env.AGENT_ROOT ||
+      process.env.AGENT_DIR ||
+      process.cwd()
+  );
+  return join(root, "logs", "diagnostics", "counters");
+}
+
+/**
+ * UTC date stamp (YYYY-MM-DD) for an epoch-ms value. The stream rotates by UTC
+ * day to match the diagnostics events / cost ledger / budget files, so "today"
+ * means the same thing across every accounting and observability path.
+ * @param {number} ms
+ * @returns {string}
+ */
+function dateStamp(ms) {
+  return new Date(ms).toISOString().slice(0, 10);
+}
+
+/**
+ * Coerce a counter name to a stable, non-empty string. A nameless bump would
+ * make the stream un-queryable, so we fold the empty/odd cases to "unknown"
+ * rather than dropping the row (a dropped fail-open is the bug we're fixing).
+ * @param {unknown} name
+ * @returns {string}
+ */
+function safeName(name) {
+  if (typeof name === "string") {
+    const trimmed = name.trim();
+    if (trimmed) return trimmed;
+  }
+  if (name != null) {
+    const s = String(name).trim();
+    if (s) return s;
+  }
+  return "unknown";
+}
+
+/**
+ * Best-effort plain-object coercion of `attrs` — never let a caller's odd value
+ * (a BigInt, a circular object, a function) make the append throw and violate
+ * the never-throw contract. Non-objects are wrapped under `{value}`.
+ * @param {unknown} attrs
+ * @returns {Record<string, unknown>}
+ */
+function safeAttrs(attrs) {
+  if (attrs == null) return {};
+  if (typeof attrs !== "object" || Array.isArray(attrs)) {
+    return { value: typeof attrs === "bigint" ? attrs.toString() : attrs };
+  }
+  return attrs;
+}
+
+/**
+ * Increment counter `name` by `by` (default 1), recording the bump both in the
+ * in-memory tally and on the date-stamped JSONL stream so a fail-open is counted
+ * somewhere durable. Returns the new in-memory total, or `null` if anything went
+ * wrong (this function NEVER throws).
+ *
+ * The persisted row is `{ ts, name, by, attrs }`; `snapshot()` sums `by` per
+ * name. We persist each bump as its own row rather than a rolling total so two
+ * processes appending concurrently can never clobber each other's count — whole
+ * lines interleave (the appendJsonl atomic-append contract) and the read side
+ * sums them.
+ *
+ * @param {string} name  counter name (e.g. "rate_guard.persist_failed")
+ * @param {Record<string, unknown>} [attrs]  structured context (provider, reason)
+ * @param {object} [deps]
+ * @param {number} [deps.by]  increment amount (default 1; non-finite → 1)
+ * @param {() => number} [deps.now]  clock (default Date.now)
+ * @param {string} [deps.dir]  explicit counters dir (overrides agentRoot)
+ * @param {string} [deps.agentRoot]  agent root used to derive the counters dir
+ * @param {(path: string, record: unknown) => boolean} [deps.append]  writer
+ *        (default lib/fs-atomic appendJsonl) — injectable for tests
+ * @returns {number|null}  new in-memory total for `name`, or null on failure
+ */
+export function bump(name, attrs = {}, deps = {}) {
+  try {
+    const key = safeName(name);
+    const byRaw = Number(deps.by);
+    const by = Number.isFinite(byRaw) && byRaw !== 0 ? byRaw : 1;
+
+    // In-memory tally first — cheap, can't fail, and is the fast path for a
+    // same-process reader even if the disk append below degrades.
+    const total = (MEM.get(key) || 0) + by;
+    MEM.set(key, total);
+
+    // Persist as its own JSONL row. The append is best-effort and INDEPENDENTLY
+    // guarded: even if an injected/odd writer throws (not just returns false),
+    // the in-memory tally has already moved, so the count isn't lost within this
+    // process and we still return the durable-intent total.
+    try {
+      const now = typeof deps.now === "function" ? deps.now : Date.now;
+      const append = typeof deps.append === "function" ? deps.append : appendJsonl;
+      const ms = now();
+      const row = {
+        ts: new Date(ms).toISOString(),
+        name: key,
+        by,
+        attrs: safeAttrs(attrs),
+      };
+      const path = join(countersDir(deps), `${dateStamp(ms)}.jsonl`);
+      append(path, row);
+    } catch {
+      /* disk/append failure must not lose the in-memory count or throw */
+    }
+    return total;
+  } catch {
+    // A counter must never crash the observed path.
+    return null;
+  }
+}
+
+/**
+ * Read today's persisted counter totals, summed per name from the date-stamped
+ * JSONL stream. This is the cross-process / cross-restart view doctor reports;
+ * it does NOT read the in-memory tally so it reflects what actually landed on
+ * disk (the durable record a second process or a fresh boot can see).
+ *
+ * NEVER throws: a missing dir, an unreadable file, or a malformed line all
+ * degrade — a bad line is skipped, a bad file yields {} — so doctor can always
+ * call it.
+ *
+ * @param {object} [deps]
+ * @param {() => number} [deps.now]  clock (default Date.now) — selects the day
+ * @param {string} [deps.dir]  explicit counters dir (overrides agentRoot)
+ * @param {string} [deps.agentRoot]  agent root used to derive the counters dir
+ * @param {(path: string) => string} [deps.read]  reader (default readFileSync)
+ * @returns {Record<string, number>}  { [name]: total } for today; {} if none
+ */
+export function snapshot(deps = {}) {
+  const totals = {};
+  try {
+    const now = typeof deps.now === "function" ? deps.now : Date.now;
+    const path = join(countersDir(deps), `${dateStamp(now())}.jsonl`);
+    const read =
+      typeof deps.read === "function"
+        ? deps.read
+        : (p) => readFileSync(p, "utf-8");
+    if (typeof deps.read !== "function" && !existsSync(path)) return totals;
+    let raw;
+    try {
+      raw = read(path);
+    } catch {
+      return totals; // file vanished / unreadable → no counts, never throw
+    }
+    if (typeof raw !== "string" || raw.length === 0) return totals;
+    for (const line of raw.split("\n")) {
+      if (!line) continue;
+      let rec;
+      try {
+        rec = JSON.parse(line);
+      } catch {
+        continue; // skip a corrupt/partial line, keep summing the rest
+      }
+      if (!rec || typeof rec.name !== "string") continue;
+      const by = Number(rec.by);
+      totals[rec.name] = (totals[rec.name] || 0) + (Number.isFinite(by) ? by : 1);
+    }
+    return totals;
+  } catch {
+    return totals;
+  }
+}
+
+/**
+ * Read the process-local in-memory tally — the fast, exact view for a reader
+ * that shares this process (doctor running in the daemon, a test). Returns a
+ * copy so callers can't mutate the live map. Never throws.
+ * @returns {Record<string, number>}
+ */
+export function memSnapshot() {
+  try {
+    return Object.fromEntries(MEM.entries());
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Reset the in-memory tally. For tests only — the durable JSONL stream is the
+ * cross-restart source of truth and is never touched here. Never throws.
+ * @returns {void}
+ */
+export function resetMem() {
+  try {
+    MEM.clear();
+  } catch {
+    /* never throws */
+  }
+}
+
+/**
+ * List the JSONL stream paths under the counters dir (most-recent day last),
+ * for doctor / retention to enumerate. Best-effort: returns [] on any error.
+ * @param {object} [deps] @param {string} [deps.dir] @param {string} [deps.agentRoot]
+ * @returns {string[]}  absolute file paths
+ */
+export function listStreams(deps = {}) {
+  try {
+    const dir = countersDir(deps);
+    if (!existsSync(dir)) return [];
+    return readdirSync(dir)
+      .filter((n) => /^\d{4}-\d{2}-\d{2}\.jsonl$/.test(n))
+      .sort()
+      .map((n) => join(dir, n));
+  } catch {
+    return [];
+  }
+}
+
+export default { bump, snapshot, memSnapshot, resetMem, listStreams };

package/lib/diagnostics/counters.test.mjs

@@ -0,0 +1,206 @@
+/**
+ * lib/diagnostics/counters.test.mjs
+ *
+ * node:test coverage for the loud guard-fail-open counters:
+ *  - bump increments the in-memory tally and persists a JSONL row
+ *  - bump persists to the date-stamped path under the counters dir
+ *  - snapshot sums today's rows per name from disk (cross-restart view)
+ *  - snapshot is isolated to "today" by the injected clock
+ *  - bump never throws on an un-serializable attr / bad name / failing append
+ *  - snapshot never throws on a missing dir / corrupt line / unreadable file
+ *  - concurrent-style appends (multiple rows) sum correctly
+ *
+ * Run: cd /Users/layla/maestro && node --test lib/diagnostics/counters.test.mjs
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, readdirSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  bump,
+  snapshot,
+  memSnapshot,
+  resetMem,
+  listStreams,
+} from "./counters.mjs";
+
+function tmpDir() {
+  return mkdtempSync(join(tmpdir(), "maestro-counters-"));
+}
+
+/** Fixed clock at 2026-06-11T12:00:00Z. */
+const FIXED = Date.parse("2026-06-11T12:00:00.000Z");
+const fixedNow = () => FIXED;
+
+test("bump increments the in-memory tally and returns the new total", () => {
+  resetMem();
+  const captured = [];
+  const append = (p, row) => { captured.push({ p, row }); return true; };
+
+  const t1 = bump("rate_guard.persist_failed", { provider: "anthropic" }, { append, now: fixedNow });
+  const t2 = bump("rate_guard.persist_failed", { provider: "anthropic" }, { append, now: fixedNow });
+  assert.equal(t1, 1);
+  assert.equal(t2, 2);
+  assert.equal(memSnapshot()["rate_guard.persist_failed"], 2);
+  assert.equal(captured.length, 2);
+  assert.equal(captured[0].row.name, "rate_guard.persist_failed");
+  assert.equal(captured[0].row.by, 1);
+  assert.equal(captured[0].row.attrs.provider, "anthropic");
+  assert.equal(typeof captured[0].row.ts, "string");
+});
+
+test("bump honours an explicit increment amount", () => {
+  resetMem();
+  const append = () => true;
+  assert.equal(bump("budget.stale_ledger", {}, { append, by: 5, now: fixedNow }), 5);
+  assert.equal(bump("budget.stale_ledger", {}, { append, by: 3, now: fixedNow }), 8);
+});
+
+test("bump persists to a date-stamped path under the counters dir", () => {
+  resetMem();
+  const dir = tmpDir();
+  try {
+    bump("g.fail", { reason: "x" }, { dir, now: fixedNow });
+    const files = readdirSync(dir);
+    assert.deepEqual(files, ["2026-06-11.jsonl"]);
+    const raw = readFileSync(join(dir, "2026-06-11.jsonl"), "utf-8").trim();
+    const row = JSON.parse(raw);
+    assert.equal(row.name, "g.fail");
+    assert.equal(row.by, 1);
+    assert.equal(row.attrs.reason, "x");
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("snapshot sums today's rows per name from disk", () => {
+  resetMem();
+  const dir = tmpDir();
+  try {
+    bump("a", {}, { dir, now: fixedNow });
+    bump("a", {}, { dir, now: fixedNow });
+    bump("b", {}, { dir, now: fixedNow, by: 4 });
+    const snap = snapshot({ dir, now: fixedNow });
+    assert.equal(snap.a, 2);
+    assert.equal(snap.b, 4);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("snapshot is isolated to the clock's day", () => {
+  resetMem();
+  const dir = tmpDir();
+  try {
+    const day1 = () => Date.parse("2026-06-11T01:00:00.000Z");
+    const day2 = () => Date.parse("2026-06-12T01:00:00.000Z");
+    bump("x", {}, { dir, now: day1 });
+    bump("x", {}, { dir, now: day1 });
+    bump("x", {}, { dir, now: day2 });
+    // Two distinct day files exist.
+    assert.deepEqual(readdirSync(dir).sort(), ["2026-06-11.jsonl", "2026-06-12.jsonl"]);
+    // Each day's snapshot only sees its own rows.
+    assert.equal(snapshot({ dir, now: day1 }).x, 2);
+    assert.equal(snapshot({ dir, now: day2 }).x, 1);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("snapshot survives across a simulated restart (reads disk, not memory)", () => {
+  resetMem();
+  const dir = tmpDir();
+  try {
+    bump("survives", {}, { dir, now: fixedNow });
+    bump("survives", {}, { dir, now: fixedNow });
+    // Simulate a process restart: the in-memory tally is gone, the disk isn't.
+    resetMem();
+    assert.deepEqual(memSnapshot(), {});
+    assert.equal(snapshot({ dir, now: fixedNow }).survives, 2);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("bump never throws and still moves the in-memory tally when append fails", () => {
+  resetMem();
+  const failingAppend = () => { throw new Error("disk full"); };
+  // append throwing must NOT propagate; the in-memory tally must still advance.
+  const total = bump("resilient", {}, { append: failingAppend, now: fixedNow });
+  // append threw before returning, but the in-memory bump happened first.
+  assert.equal(total, 1);
+  assert.equal(memSnapshot().resilient, 1);
+});
+
+test("bump tolerates an un-serializable attr and a non-string name", () => {
+  resetMem();
+  const captured = [];
+  const append = (p, row) => { captured.push(row); return true; };
+  const circular = {};
+  circular.self = circular;
+  // A circular attrs object would break naive JSON.stringify; bump must not throw.
+  assert.doesNotThrow(() => bump("circ", circular, { append, now: fixedNow }));
+  // A non-string name folds to a stable string rather than dropping the row.
+  const total = bump(12345, {}, { append, now: fixedNow });
+  assert.equal(total, 1);
+  assert.equal(captured.at(-1).name, "12345");
+});
+
+test("an empty/whitespace name folds to 'unknown'", () => {
+  resetMem();
+  const captured = [];
+  const append = (p, row) => { captured.push(row); return true; };
+  bump("   ", {}, { append, now: fixedNow });
+  assert.equal(captured.at(-1).name, "unknown");
+});
+
+test("snapshot returns {} for a missing dir and never throws", () => {
+  resetMem();
+  const dir = join(tmpDir(), "does-not-exist");
+  assert.deepEqual(snapshot({ dir, now: fixedNow }), {});
+});
+
+test("snapshot skips corrupt lines but sums the valid ones", () => {
+  resetMem();
+  const good = JSON.stringify({ name: "ok", by: 2 });
+  const good2 = JSON.stringify({ name: "ok", by: 3 });
+  const raw = `${good}\nnot json at all\n${good2}\n{"name":123}\n`;
+  const read = () => raw;
+  const snap = snapshot({ now: fixedNow, read });
+  assert.equal(snap.ok, 5); // 2 + 3; the garbage line and the bad-name line skip
+});
+
+test("snapshot treats a row with a missing/NaN by as 1", () => {
+  resetMem();
+  const raw = `${JSON.stringify({ name: "n" })}\n${JSON.stringify({ name: "n", by: "x" })}\n`;
+  const snap = snapshot({ now: fixedNow, read: () => raw });
+  assert.equal(snap.n, 2); // both default to +1
+});
+
+test("snapshot returns {} when the reader throws (unreadable file)", () => {
+  resetMem();
+  const read = () => { throw new Error("EACCES"); };
+  assert.deepEqual(snapshot({ now: fixedNow, read }), {});
+});
+
+test("listStreams enumerates the date-stamped streams in order", () => {
+  resetMem();
+  const dir = tmpDir();
+  try {
+    bump("s", {}, { dir, now: () => Date.parse("2026-06-11T00:00:00Z") });
+    bump("s", {}, { dir, now: () => Date.parse("2026-06-09T00:00:00Z") });
+    const streams = listStreams({ dir });
+    assert.equal(streams.length, 2);
+    assert.ok(streams[0].endsWith("2026-06-09.jsonl"));
+    assert.ok(streams[1].endsWith("2026-06-11.jsonl"));
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("listStreams returns [] for a missing dir", () => {
+  assert.deepEqual(listStreams({ dir: join(tmpdir(), "nope-counters-xyz") }), []);
+});

package/lib/diagnostics/events.mjs

@@ -0,0 +1,188 @@
+/**
+ * lib/diagnostics/events.mjs — the typed diagnostic-event spine.
+ *
+ * One in-process event contract that every hot path can emit onto, so a single
+ * user interaction is reconstructable end-to-end (gaps-enterprise-ops G7). Each
+ * event is appended as one JSON line to a date-stamped stream at
+ * `logs/diagnostics/<YYYY-MM-DD>.jsonl` via the shared atomic appender
+ * (lib/fs-atomic `appendJsonl`), matching maestro's logging idiom (date-stamped
+ * JSONL, fail-open append that can never crash the daemon).
+ *
+ * The event-type set is CLOSED — an unknown type is coerced to `error` (with the
+ * offending type preserved under `attrs._invalid_type`) rather than silently
+ * widening the schema. The eight types trace the canonical interaction hops:
+ *
+ *   item_received   inbound message/tick admitted (interaction start)
+ *   classified      classifier verdict produced
+ *   dispatched      session spawn decided/launched
+ *   session_opened  claude sub-session started
+ *   session_closed  claude sub-session ended
+ *   sent            an outbound message left the agent (interaction end)
+ *   guard_fail      a governor/breaker/budget/permission gate refused work
+ *   error           an unexpected failure on the path
+ *
+ * Every row carries `{ts, type, trace_id, span, attrs}`. The `trace_id` is the
+ * correlation key (mint with lib/diagnostics/trace.mjs); when omitted, the
+ * ambient `withTrace` context fills it in, so an instrumented call site need not
+ * thread the id by hand.
+ *
+ * Invariant: `emitEvent` NEVER throws. A bad directory, an unwritable disk, a
+ * non-serializable attr — all degrade to a `false` return, never an exception.
+ * Diagnostics must not be able to take down the path they observe.
+ *
+ * Constraints (CLAUDE.md): ESM, Node built-ins + lib/fs-atomic only, injectable
+ * clock + log dir so tests are hermetic.
+ *
+ * @module lib/diagnostics/events
+ */
+
+import { join, resolve } from "node:path";
+
+import { appendJsonl } from "../fs-atomic.mjs";
+import { currentTrace } from "./trace.mjs";
+
+/**
+ * The closed set of diagnostic event types. Frozen so callers can reference it
+ * (e.g. a dashboard legend) without being able to mutate the contract.
+ * @type {Readonly<Record<string, string>>}
+ */
+export const EVENT_TYPES = Object.freeze({
+  ITEM_RECEIVED: "item_received",
+  CLASSIFIED: "classified",
+  DISPATCHED: "dispatched",
+  SESSION_OPENED: "session_opened",
+  SESSION_CLOSED: "session_closed",
+  SENT: "sent",
+  GUARD_FAIL: "guard_fail",
+  ERROR: "error",
+});
+
+/** Fast membership set over the closed type vocabulary. */
+const VALID_TYPES = new Set(Object.values(EVENT_TYPES));
+
+/**
+ * True if `type` is one of the eight contract event types.
+ * @param {unknown} type
+ * @returns {boolean}
+ */
+export function isValidEventType(type) {
+  return typeof type === "string" && VALID_TYPES.has(type);
+}
+
+/**
+ * Resolve the diagnostics log directory for the current agent.
+ * @param {object} deps
+ * @returns {string}
+ */
+function diagnosticsDir(deps = {}) {
+  if (deps.logDir) return resolve(deps.logDir);
+  const root = resolve(
+    deps.agentRoot ||
+      process.env.AGENT_ROOT ||
+      process.env.AGENT_DIR ||
+      process.cwd()
+  );
+  return join(root, "logs", "diagnostics");
+}
+
+/**
+ * UTC date stamp (YYYY-MM-DD) for the given epoch ms — the stream is rotated by
+ * UTC day, matching the cost ledger and budget files so "today" is consistent
+ * across the diagnostics and accounting paths.
+ * @param {number} ms
+ * @returns {string}
+ */
+function dateStamp(ms) {
+  return new Date(ms).toISOString().slice(0, 10);
+}
+
+/**
+ * Best-effort plain-object coercion of `attrs`. We never let a caller's odd
+ * value (a BigInt, a circular object, a function) make the append throw — that
+ * would violate the never-throw contract. Non-objects are wrapped under
+ * `{value}`; an un-serializable object is replaced by a marker.
+ * @param {unknown} attrs
+ * @returns {Record<string, unknown>}
+ */
+function safeAttrs(attrs) {
+  if (attrs == null) return {};
+  if (typeof attrs !== "object" || Array.isArray(attrs)) {
+    return { value: stringifySafe(attrs) };
+  }
+  return attrs;
+}
+
+/**
+ * Stringify a scalar defensively (BigInt → string, etc.). Used only for the
+ * wrapped-value fallback above; the row as a whole is serialized by appendJsonl.
+ * @param {unknown} v
+ * @returns {unknown}
+ */
+function stringifySafe(v) {
+  if (typeof v === "bigint") return v.toString();
+  return v;
+}
+
+/**
+ * Emit one diagnostic event onto the date-stamped JSONL stream.
+ *
+ * The row shape is `{ ts, type, trace_id, span, attrs }`:
+ *   - `ts`        ISO-8601 timestamp (from the injected/default clock)
+ *   - `type`      one of EVENT_TYPES; an unknown type is coerced to `error`
+ *                 and the original preserved at `attrs._invalid_type`
+ *   - `trace_id`  the supplied id, else the ambient `withTrace` id, else null
+ *   - `span`      the supplied span, else the ambient span, else "root"
+ *   - `attrs`     caller payload (defensively coerced to a plain object)
+ *
+ * @param {object} event
+ * @param {string} event.type one of EVENT_TYPES
+ * @param {string} [event.trace_id] correlation id (defaults to ambient trace)
+ * @param {string} [event.span] span path (defaults to ambient span / "root")
+ * @param {Record<string, unknown>} [event.attrs] structured payload
+ * @param {object} [deps]
+ * @param {() => number} [deps.now] clock (default Date.now)
+ * @param {string} [deps.logDir] explicit diagnostics dir (overrides agentRoot)
+ * @param {string} [deps.agentRoot] agent root used to derive logs/diagnostics
+ * @param {(path: string, record: unknown) => boolean} [deps.append] writer
+ *        (default lib/fs-atomic appendJsonl) — injectable for tests
+ * @returns {boolean} true if the line was written, false on any failure
+ */
+export function emitEvent(event, deps = {}) {
+  try {
+    const now = typeof deps.now === "function" ? deps.now : Date.now;
+    const append = typeof deps.append === "function" ? deps.append : appendJsonl;
+
+    const ev = event && typeof event === "object" ? event : {};
+    const ambient = currentTrace();
+
+    const validType = isValidEventType(ev.type);
+    const type = validType ? ev.type : EVENT_TYPES.ERROR;
+
+    const trace_id =
+      (typeof ev.trace_id === "string" && ev.trace_id) ||
+      (ambient && ambient.trace_id) ||
+      null;
+    const span =
+      (typeof ev.span === "string" && ev.span) ||
+      (ambient && ambient.span) ||
+      "root";
+
+    const attrs = { ...safeAttrs(ev.attrs) };
+    if (!validType) attrs._invalid_type = ev.type === undefined ? null : ev.type;
+
+    const ms = now();
+    const row = {
+      ts: new Date(ms).toISOString(),
+      type,
+      trace_id,
+      span,
+      attrs,
+    };
+
+    const path = join(diagnosticsDir(deps), `${dateStamp(ms)}.jsonl`);
+    return append(path, row) === true;
+  } catch {
+    // Diagnostics must never crash the observed path.
+    return false;
+  }
+}