@cohortapp/agent-sdk 2.3.0

package/lib/fs-atomic.test.mjs

@@ -0,0 +1,72 @@
+/**
+ * Tests for lib/fs-atomic.mjs — durable atomic write primitives.
+ * @module lib/fs-atomic.test
+ */
+
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, readFileSync, writeFileSync, existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { writeFileAtomic, writeJsonAtomic, appendJsonl } from "./fs-atomic.mjs";
+
+let dir;
+beforeEach(() => { dir = mkdtempSync(join(tmpdir(), "fs-atomic-")); });
+afterEach(() => { rmSync(dir, { recursive: true, force: true }); });
+
+describe("writeFileAtomic", () => {
+  it("writes contents and creates missing parent dirs", () => {
+    const p = join(dir, "a", "b", "c.txt");
+    writeFileAtomic(p, "hello");
+    assert.equal(readFileSync(p, "utf8"), "hello");
+  });
+
+  it("overwrites an existing file atomically (final contents only)", () => {
+    const p = join(dir, "x.txt");
+    writeFileAtomic(p, "first");
+    writeFileAtomic(p, "second");
+    assert.equal(readFileSync(p, "utf8"), "second");
+  });
+
+  it("leaves no .tmp sibling behind on success", () => {
+    const p = join(dir, "y.txt");
+    writeFileAtomic(p, "data");
+    const strays = readdirSync(dir).filter((f) => f.includes(".tmp."));
+    assert.equal(strays.length, 0);
+  });
+
+  it("accepts a Buffer payload", () => {
+    const p = join(dir, "buf.bin");
+    writeFileAtomic(p, Buffer.from([1, 2, 3]));
+    assert.deepEqual([...readFileSync(p)], [1, 2, 3]);
+  });
+});
+
+describe("writeJsonAtomic", () => {
+  it("round-trips an object as pretty JSON with trailing newline", () => {
+    const p = join(dir, "obj.json");
+    writeJsonAtomic(p, { a: 1, b: [2, 3] });
+    const raw = readFileSync(p, "utf8");
+    assert.ok(raw.endsWith("\n"));
+    assert.deepEqual(JSON.parse(raw), { a: 1, b: [2, 3] });
+  });
+});
+
+describe("appendJsonl", () => {
+  it("appends whole JSON lines, preserving prior content", () => {
+    const p = join(dir, "log.jsonl");
+    assert.equal(appendJsonl(p, { n: 1 }), true);
+    assert.equal(appendJsonl(p, { n: 2 }), true);
+    const lines = readFileSync(p, "utf8").trim().split("\n");
+    assert.equal(lines.length, 2);
+    assert.deepEqual(JSON.parse(lines[0]), { n: 1 });
+    assert.deepEqual(JSON.parse(lines[1]), { n: 2 });
+  });
+
+  it("returns false instead of throwing when the path is unwritable", () => {
+    // A path whose parent is an existing *file* cannot be mkdir'd → IO error.
+    const blocker = join(dir, "blocker");
+    writeFileSync(blocker, "x");
+    assert.equal(appendJsonl(join(blocker, "nope.jsonl"), { n: 1 }), false);
+  });
+});

package/lib/fs-ownership.mjs

@@ -0,0 +1,111 @@
+/**
+ * lib/fs-ownership.mjs — Pure ownership / permission hygiene checks.
+ *
+ * Audit M3: the framework ships `state/` and `logs/` and then runs as the
+ * unprivileged user. If those trees were created (or chown'd) root — a common
+ * side effect of running an installer step under `sudo` — the daemon's writes
+ * fail silently, or someone "fixes" it with a 0777 chmod that leaves the agent's
+ * private state world-writable. Neither is acceptable.
+ *
+ * This module is intentionally side-effect free and dependency free so it can be
+ * unit-tested against synthetic stat-like inputs without needing real
+ * root-owned directories. The `maestro doctor` command wires it up against the
+ * live filesystem; nothing here ever performs a chown/chmod — fixing ownership
+ * is an explicit operator action.
+ */
+
+/**
+ * Evaluate a single path's ownership + permission posture.
+ *
+ * @param {object} input
+ * @param {string} input.path            Display path (used only in messages).
+ * @param {number} input.mode            st_mode (as from fs.stat().mode).
+ * @param {number} input.uid             Owning uid of the path (st_uid).
+ * @param {number} input.runtimeUid      uid the framework runs as (process.getuid()).
+ * @param {boolean} [input.exists=true]  Whether the path exists. Missing paths
+ *                                       are reported as ok:true, exists:false so
+ *                                       the caller can decide (a missing optional
+ *                                       subdir is not an ownership violation).
+ * @returns {{ ok: boolean, exists: boolean, path: string,
+ *             ownedByRuntime: boolean, groupWritable: boolean,
+ *             worldWritable: boolean, reasons: string[] }}
+ */
+export function checkPathOwnership({ path, mode, uid, runtimeUid, exists = true }) {
+  if (!exists) {
+    return {
+      ok: true,
+      exists: false,
+      path,
+      ownedByRuntime: false,
+      groupWritable: false,
+      worldWritable: false,
+      reasons: [],
+    };
+  }
+
+  const reasons = [];
+
+  // Ownership: the runtime uid must own the path so it can always write,
+  // rename, and chmod within it. root-owned (uid 0) state is the classic
+  // failure mode this guards against.
+  const ownedByRuntime = uid === runtimeUid;
+  if (!ownedByRuntime) {
+    reasons.push(
+      `owned by uid ${uid}, but the framework runs as uid ${runtimeUid}`,
+    );
+  }
+
+  // Permission hygiene: agent state is private. Group- or world-writable
+  // directories let any local account tamper with queues, dashboards, and
+  // logs, and are usually the residue of a `chmod -R 0777` workaround.
+  const groupWritable = (mode & 0o020) !== 0;
+  const worldWritable = (mode & 0o002) !== 0;
+  if (groupWritable) reasons.push("group-writable (g+w)");
+  if (worldWritable) reasons.push("world-writable (o+w)");
+
+  return {
+    ok: reasons.length === 0,
+    exists: true,
+    path,
+    ownedByRuntime,
+    groupWritable,
+    worldWritable,
+    reasons,
+  };
+}
+
+/**
+ * Evaluate a set of paths and produce an aggregate verdict plus a single,
+ * copy-pasteable remediation command rooted at the agent directory.
+ *
+ * @param {Array<{path:string, mode:number, uid:number, exists?:boolean}>} entries
+ * @param {object} opts
+ * @param {number} opts.runtimeUid                 process.getuid().
+ * @param {string} [opts.whoami="$(whoami)"]       Username for the chown hint.
+ * @param {string[]} [opts.roots=["state","logs"]] Top-level dirs for the fix cmd.
+ * @returns {{ ok: boolean, violations: object[], fixCommand: string|null }}
+ */
+export function checkOwnershipSet(entries, { runtimeUid, whoami = "$(whoami)", roots = ["state", "logs"] } = {}) {
+  const results = entries.map((e) =>
+    checkPathOwnership({ ...e, runtimeUid }),
+  );
+  const violations = results.filter((r) => r.exists && !r.ok);
+  const fixCommand =
+    violations.length > 0 ? buildFixCommand(roots, whoami) : null;
+  return { ok: violations.length === 0, violations, fixCommand };
+}
+
+/**
+ * The exact remediation the operator should run. chown restores ownership to
+ * the runtime user; `chmod -R u+rwX,go-w` restores write access for the owner
+ * and strips group/world write — without clobbering the execute bit on dirs
+ * (capital X only sets +x where it already applies or on directories).
+ *
+ * @param {string[]} roots
+ * @param {string} whoami
+ * @returns {string}
+ */
+export function buildFixCommand(roots = ["state", "logs"], whoami = "$(whoami)") {
+  const joined = roots.join(" ");
+  return `sudo chown -R ${whoami} ${joined} && chmod -R u+rwX,go-w ${joined}`;
+}

package/lib/fs-ownership.test.mjs

@@ -0,0 +1,158 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import {
+  checkPathOwnership,
+  checkOwnershipSet,
+  buildFixCommand,
+} from "./fs-ownership.mjs";
+
+// Octal modes are easier to read for these cases. We pass the directory mode
+// bits the way fs.stat().mode reports them (S_IFDIR | perms).
+const RUNTIME_UID = 501;
+
+test("checkPathOwnership: owned by runtime, 0700 -> ok", () => {
+  const r = checkPathOwnership({
+    path: "state",
+    mode: 0o40700,
+    uid: RUNTIME_UID,
+    runtimeUid: RUNTIME_UID,
+  });
+  assert.equal(r.ok, true);
+  assert.equal(r.exists, true);
+  assert.equal(r.ownedByRuntime, true);
+  assert.equal(r.groupWritable, false);
+  assert.equal(r.worldWritable, false);
+  assert.deepEqual(r.reasons, []);
+});
+
+test("checkPathOwnership: owned by runtime, 0755 -> ok (not group/world writable)", () => {
+  const r = checkPathOwnership({
+    path: "logs",
+    mode: 0o40755,
+    uid: RUNTIME_UID,
+    runtimeUid: RUNTIME_UID,
+  });
+  assert.equal(r.ok, true);
+  assert.deepEqual(r.reasons, []);
+});
+
+test("checkPathOwnership: root-owned -> violation with uid in reason", () => {
+  const r = checkPathOwnership({
+    path: "state",
+    mode: 0o40700,
+    uid: 0,
+    runtimeUid: RUNTIME_UID,
+  });
+  assert.equal(r.ok, false);
+  assert.equal(r.ownedByRuntime, false);
+  assert.equal(r.reasons.length, 1);
+  assert.match(r.reasons[0], /uid 0/);
+  assert.match(r.reasons[0], /uid 501/);
+});
+
+test("checkPathOwnership: group-writable -> violation", () => {
+  const r = checkPathOwnership({
+    path: "logs",
+    mode: 0o40770,
+    uid: RUNTIME_UID,
+    runtimeUid: RUNTIME_UID,
+  });
+  assert.equal(r.ok, false);
+  assert.equal(r.groupWritable, true);
+  assert.ok(r.reasons.some((x) => /group-writable/.test(x)));
+});
+
+test("checkPathOwnership: world-writable (0777 workaround) -> violation", () => {
+  const r = checkPathOwnership({
+    path: "state",
+    mode: 0o40777,
+    uid: RUNTIME_UID,
+    runtimeUid: RUNTIME_UID,
+  });
+  assert.equal(r.ok, false);
+  assert.equal(r.worldWritable, true);
+  assert.equal(r.groupWritable, true);
+  assert.ok(r.reasons.some((x) => /world-writable/.test(x)));
+  assert.ok(r.reasons.some((x) => /group-writable/.test(x)));
+});
+
+test("checkPathOwnership: root-owned AND world-writable -> three reasons", () => {
+  const r = checkPathOwnership({
+    path: "state",
+    mode: 0o40777,
+    uid: 0,
+    runtimeUid: RUNTIME_UID,
+  });
+  assert.equal(r.ok, false);
+  // ownership + group-writable + world-writable
+  assert.equal(r.reasons.length, 3);
+});
+
+test("checkPathOwnership: missing path -> ok:true exists:false, no reasons", () => {
+  const r = checkPathOwnership({
+    path: "state/cadence-bus",
+    mode: 0,
+    uid: 0,
+    runtimeUid: RUNTIME_UID,
+    exists: false,
+  });
+  assert.equal(r.ok, true);
+  assert.equal(r.exists, false);
+  assert.deepEqual(r.reasons, []);
+});
+
+test("checkOwnershipSet: all clean -> ok, no fixCommand", () => {
+  const res = checkOwnershipSet(
+    [
+      { path: "state", mode: 0o40700, uid: RUNTIME_UID },
+      { path: "logs", mode: 0o40755, uid: RUNTIME_UID },
+    ],
+    { runtimeUid: RUNTIME_UID },
+  );
+  assert.equal(res.ok, true);
+  assert.equal(res.violations.length, 0);
+  assert.equal(res.fixCommand, null);
+});
+
+test("checkOwnershipSet: one root-owned -> not ok, fixCommand present", () => {
+  const res = checkOwnershipSet(
+    [
+      { path: "state", mode: 0o40700, uid: 0 },
+      { path: "logs", mode: 0o40700, uid: RUNTIME_UID },
+    ],
+    { runtimeUid: RUNTIME_UID, whoami: "wong" },
+  );
+  assert.equal(res.ok, false);
+  assert.equal(res.violations.length, 1);
+  assert.equal(res.violations[0].path, "state");
+  assert.equal(
+    res.fixCommand,
+    "sudo chown -R wong state logs && chmod -R u+rwX,go-w state logs",
+  );
+});
+
+test("checkOwnershipSet: missing entries are ignored (not violations)", () => {
+  const res = checkOwnershipSet(
+    [
+      { path: "state", mode: 0o40700, uid: RUNTIME_UID },
+      { path: "state/cadence-bus", mode: 0, uid: 0, exists: false },
+    ],
+    { runtimeUid: RUNTIME_UID },
+  );
+  assert.equal(res.ok, true);
+  assert.equal(res.fixCommand, null);
+});
+
+test("buildFixCommand: default roots + $(whoami)", () => {
+  assert.equal(
+    buildFixCommand(),
+    "sudo chown -R $(whoami) state logs && chmod -R u+rwX,go-w state logs",
+  );
+});
+
+test("buildFixCommand: custom roots", () => {
+  assert.equal(
+    buildFixCommand(["state", "logs", "knowledge"], "alice"),
+    "sudo chown -R alice state logs knowledge && chmod -R u+rwX,go-w state logs knowledge",
+  );
+});

package/lib/hooks/bus.mjs

@@ -0,0 +1,347 @@
+/**
+ * lib/hooks/bus.mjs — typed lifecycle hook bus.
+ *
+ * Why this exists
+ * ---------------
+ * Maestro grew a handful of cross-cutting controls that each wired themselves
+ * directly into the paths they guard: the pre-send audit gates exactly one
+ * tool, guard telemetry is bespoke per call site, audit logging is scattered,
+ * and the learning loop's governance is hardwired. The audit's single
+ * highest-leverage P1 enabler (gaps-product-quality P1-8) is a *typed lifecycle
+ * hook bus* — once it exists, the send-gate, ownership backstop, disclosure
+ * assessment, guard telemetry, audit logging and learning governance all become
+ * SUBSCRIBERS to well-known lifecycle events instead of bespoke wiring scattered
+ * across the daemon, the channel adapters and the senders.
+ *
+ * Design
+ * ------
+ * The bus is purely in-process (no filesystem — that's what the underlying
+ * audit logs are for). It exposes a CLOSED set of typed lifecycle events; an
+ * unknown event name is rejected at subscribe/emit time so a typo can never
+ * silently register a dead subscriber. Subscribers run in priority order
+ * (higher priority first; ties broken by registration order for determinism).
+ *
+ * Cancellable vs observe-only
+ * ---------------------------
+ * `beforeSend` is the one CANCELLABLE chain: any subscriber may veto the send
+ * by returning (or resolving to) `{ cancel: true, reason }`. The first veto
+ * short-circuits the remaining subscribers and `emit` resolves with the
+ * decision so the caller can refuse to send and surface the reason. This is the
+ * seam the send-gate, ownership backstop and disclosure assessment plug into.
+ * Every other event is OBSERVE-ONLY: subscriber return values are ignored, the
+ * chain always runs to completion, and `emit` resolves to the standard
+ * not-cancelled decision.
+ *
+ * Fail-open isolation (house idiom)
+ * ---------------------------------
+ * One throwing (or rejecting) subscriber is caught, reported, and SKIPPED — it
+ * never breaks the chain or starves the subscribers after it. A thrown error in
+ * a cancellable chain is treated as "no opinion" (it does NOT cancel the send),
+ * so a buggy gate can never silently drop traffic. Errors are surfaced two ways:
+ * via the pluggable `logger` (defaults to the audit JSONL) and by re-emitting an
+ * `onError` event — but the `onError` chain is itself isolated and never
+ * re-enters recursively, so a throwing error-handler can't loop the bus.
+ *
+ * Sync + async
+ * ------------
+ * Subscribers may be synchronous or return a promise; `emit` awaits each one in
+ * priority order before moving to the next, so ordering holds across async work.
+ *
+ * @module lib/hooks/bus
+ */
+
+import { appendJsonl } from "../fs-atomic.mjs";
+import { resolveAgentRoot } from "../agent-root.mjs";
+import { join } from "node:path";
+
+// ---------------------------------------------------------------------------
+// Closed event set
+// ---------------------------------------------------------------------------
+
+/**
+ * The CLOSED set of typed lifecycle events. Cancellable events let a subscriber
+ * veto the operation; observe-only events ignore return values. Adding a new
+ * event is a deliberate edit here — the closed set is what makes a mistyped
+ * event name a loud error instead of a dead subscriber.
+ */
+export const HOOK_EVENTS = Object.freeze({
+  /** Before an outbound message is sent. CANCELLABLE — send-gate / ownership / disclosure. */
+  beforeSend: { cancellable: true },
+  /** After an outbound message is sent (delivery receipt / audit). Observe-only. */
+  afterSend: { cancellable: false },
+  /** An inbound message has been classified (kind/priority/privilege). Observe-only. */
+  onClassify: { cancellable: false },
+  /** An inbound event has been dispatched to a session. Observe-only. */
+  onDispatch: { cancellable: false },
+  /** A (sub-)session has closed (learning capture / reflect). Observe-only. */
+  onSessionClose: { cancellable: false },
+  /** A guard (budget/rate/governor) failed open or tripped. Observe-only telemetry. */
+  onGuardFail: { cancellable: false },
+  /** The learning loop authored or landed a skill. Observe-only governance. */
+  onSkillAuthored: { cancellable: false },
+  /** A subscriber threw, or a caller reports an error onto the bus. Observe-only. */
+  onError: { cancellable: false },
+});
+
+/** Names of the closed event set, for validation + iteration. */
+export const HOOK_EVENT_NAMES = Object.freeze(Object.keys(HOOK_EVENTS));
+
+/** @returns {boolean} whether `event` is a known lifecycle event. */
+export function isHookEvent(event) {
+  return Object.prototype.hasOwnProperty.call(HOOK_EVENTS, event);
+}
+
+/** @returns {boolean} whether `event` is a cancellable chain. */
+export function isCancellableEvent(event) {
+  return isHookEvent(event) && HOOK_EVENTS[event].cancellable === true;
+}
+
+function assertKnownEvent(event, op) {
+  if (!isHookEvent(event)) {
+    throw new Error(
+      `HookBus.${op}: unknown event "${String(event)}". ` +
+        `Known events: ${HOOK_EVENT_NAMES.join(", ")}.`
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Default logger
+// ---------------------------------------------------------------------------
+
+/**
+ * Default subscriber-error logger. Best-effort append to logs/audit/hooks.jsonl
+ * via the shared atomic JSONL appender (which never throws). Returns nothing.
+ * Callers can inject their own logger via the factory for tests / alt sinks.
+ *
+ * @param {object} entry
+ */
+function defaultLogger(entry) {
+  try {
+    const file = join(resolveAgentRoot(), "logs", "audit", "hooks.jsonl");
+    appendJsonl(file, { ts: new Date().toISOString(), ...entry });
+  } catch {
+    /* fail-open: a logger failure must never break the bus */
+  }
+}
+
+// ---------------------------------------------------------------------------
+// HookBus
+// ---------------------------------------------------------------------------
+
+/**
+ * A typed lifecycle hook bus. Construct via {@link createHookBus} (tests) or
+ * read the process-wide instance via {@link getHookBus} (production wiring).
+ */
+export class HookBus {
+  /**
+   * @param {object} [opts]
+   * @param {(entry: object) => void} [opts.logger] sink for subscriber errors
+   *   and dropped-cancellation diagnostics. Defaults to the audit JSONL.
+   * @param {number} [opts.defaultPriority] priority for subscribers that don't
+   *   specify one (default 0). Higher runs first.
+   */
+  constructor(opts = {}) {
+    /** @type {Map<string, Array<{fn: Function, priority: number, seq: number}>>} */
+    this._subs = new Map();
+    for (const name of HOOK_EVENT_NAMES) this._subs.set(name, []);
+    this._logger = typeof opts.logger === "function" ? opts.logger : defaultLogger;
+    this._defaultPriority = Number.isFinite(opts.defaultPriority) ? opts.defaultPriority : 0;
+    this._seq = 0; // monotonic registration counter for stable tie-breaking
+    this._inError = false; // re-entrancy guard for the onError chain
+  }
+
+  /**
+   * Register a subscriber for a lifecycle event.
+   *
+   * Subscribers run in DESCENDING priority order; subscribers registered with
+   * the same priority run in registration order (FIFO). For a cancellable
+   * event a subscriber may return (or resolve to) `{ cancel: true, reason }`
+   * to veto the operation and short-circuit the chain.
+   *
+   * @param {string} event one of {@link HOOK_EVENT_NAMES}
+   * @param {(ctx: object) => (void | object | Promise<void|object>)} fn
+   * @param {object} [opts]
+   * @param {number} [opts.priority] higher runs first (default 0)
+   * @returns {() => void} an unsubscribe handle (idempotent)
+   */
+  subscribe(event, fn, opts = {}) {
+    assertKnownEvent(event, "subscribe");
+    if (typeof fn !== "function") {
+      throw new TypeError(`HookBus.subscribe: handler for "${event}" must be a function`);
+    }
+    const priority = Number.isFinite(opts.priority) ? opts.priority : this._defaultPriority;
+    const entry = { fn, priority, seq: this._seq++ };
+    const list = this._subs.get(event);
+    list.push(entry);
+    // Keep the list sorted so emit() is a straight walk. Descending priority,
+    // ascending seq for stable FIFO within a priority band.
+    list.sort((a, b) => (b.priority - a.priority) || (a.seq - b.seq));
+    let active = true;
+    return () => {
+      if (!active) return;
+      active = false;
+      this._removeEntry(event, entry);
+    };
+  }
+
+  /**
+   * Remove a previously-registered subscriber by reference. Removes the FIRST
+   * matching (event, fn) registration. Returns true if one was removed.
+   *
+   * @param {string} event
+   * @param {Function} fn
+   * @returns {boolean}
+   */
+  unsubscribe(event, fn) {
+    assertKnownEvent(event, "unsubscribe");
+    const list = this._subs.get(event);
+    const i = list.findIndex((e) => e.fn === fn);
+    if (i === -1) return false;
+    list.splice(i, 1);
+    return true;
+  }
+
+  _removeEntry(event, entry) {
+    const list = this._subs.get(event);
+    if (!list) return;
+    const i = list.indexOf(entry);
+    if (i !== -1) list.splice(i, 1);
+  }
+
+  /** @returns {number} live subscriber count for an event. */
+  count(event) {
+    assertKnownEvent(event, "count");
+    return this._subs.get(event).length;
+  }
+
+  /** Remove all subscribers (all events, or just one). Mostly for tests. */
+  clear(event) {
+    if (event === undefined) {
+      for (const name of HOOK_EVENT_NAMES) this._subs.set(name, []);
+      return;
+    }
+    assertKnownEvent(event, "clear");
+    this._subs.set(event, []);
+  }
+
+  /**
+   * Emit a lifecycle event. Runs every live subscriber in priority order,
+   * awaiting each (sync or async) before the next, so ordering holds across
+   * async work.
+   *
+   * Isolation: a throwing/rejecting subscriber is caught, reported (via the
+   * injected logger and a non-recursive `onError` re-emit) and SKIPPED — it
+   * never aborts the chain or starves later subscribers.
+   *
+   * Cancellation (cancellable events only): if a subscriber returns
+   * `{ cancel: true, reason }` the chain short-circuits and the returned
+   * decision carries `{ cancelled: true, reason, by }`. A subscriber that
+   * throws is treated as "no opinion" — it does NOT cancel.
+   *
+   * @param {string} event one of {@link HOOK_EVENT_NAMES}
+   * @param {object} [ctx] context object passed to every subscriber
+   * @returns {Promise<{cancelled: boolean, reason: (string|null), by: (number|null), errors: number}>}
+   */
+  async emit(event, ctx = {}) {
+    assertKnownEvent(event, "emit");
+    const cancellable = HOOK_EVENTS[event].cancellable === true;
+    // Snapshot the subscriber list so subscribe/unsubscribe during emit does
+    // not mutate the in-flight walk (and a subscriber added mid-emit doesn't
+    // run for the event already in flight).
+    const list = this._subs.get(event).slice();
+    let errors = 0;
+
+    for (let i = 0; i < list.length; i++) {
+      const { fn } = list[i];
+      let outcome;
+      try {
+        outcome = await fn(ctx);
+      } catch (err) {
+        errors++;
+        this._reportSubscriberError(event, i, err);
+        continue; // isolate: a throw is "no opinion", never cancels
+      }
+      if (cancellable && outcome && typeof outcome === "object" && outcome.cancel === true) {
+        return {
+          cancelled: true,
+          reason: typeof outcome.reason === "string" ? outcome.reason : "cancelled",
+          by: i,
+          errors,
+        };
+      }
+    }
+    return { cancelled: false, reason: null, by: null, errors };
+  }
+
+  /**
+   * Report a subscriber error to the logger and (unless we're already inside
+   * the onError chain) re-emit `onError`. The re-entrancy guard makes a
+   * throwing onError subscriber safe — its own throw is logged but does not
+   * recurse.
+   */
+  _reportSubscriberError(event, index, err) {
+    const entry = {
+      level: "error",
+      stage: "hook_subscriber_error",
+      event,
+      index,
+      error: err && err.message ? err.message : String(err),
+    };
+    try {
+      this._logger(entry);
+    } catch {
+      /* a broken logger must never break the bus */
+    }
+    if (event === "onError" || this._inError) return;
+    this._inError = true;
+    // Fire-and-forget: surface the error onto the bus for any onError
+    // subscribers, but never await it from inside another emit's hot loop and
+    // never let it reject upward. emit() already isolates each subscriber.
+    Promise.resolve()
+      .then(() => this.emit("onError", { sourceEvent: event, index, error: entry.error }))
+      .catch(() => { /* fully isolated */ })
+      .finally(() => { this._inError = false; });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Factory + singleton accessor
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a fresh, isolated HookBus. Tests should use this so registrations
+ * don't leak between cases. Production wiring uses {@link getHookBus}.
+ *
+ * @param {object} [opts] see {@link HookBus}
+ * @returns {HookBus}
+ */
+export function createHookBus(opts) {
+  return new HookBus(opts);
+}
+
+/** @type {HookBus|null} */
+let _singleton = null;
+
+/**
+ * Return the process-wide HookBus, creating it on first use. This is the
+ * instance the send scripts, BaseAdapter, daemon and learning loop subscribe
+ * to so they all observe the same lifecycle.
+ *
+ * @param {object} [opts] applied ONLY when the singleton is first created
+ * @returns {HookBus}
+ */
+export function getHookBus(opts) {
+  if (_singleton === null) _singleton = new HookBus(opts);
+  return _singleton;
+}
+
+/**
+ * Reset the process-wide singleton. Test-only escape hatch so a suite that
+ * touches the global bus can isolate itself.
+ */
+export function resetHookBus() {
+  _singleton = null;
+}
+
+export default { HookBus, createHookBus, getHookBus, resetHookBus, HOOK_EVENTS, HOOK_EVENT_NAMES };