@cohortapp/agent-sdk 2.4.0 → 2.5.0

package/scripts/ci/check-subagent-frontmatter.test.mjs

@@ -0,0 +1,124 @@
+/**
+ * Tests for check-subagent-frontmatter.mjs — the sub-agent definition guard.
+ *
+ * Runs against throwaway trees under os.tmpdir() rather than the repo's own
+ * agents/, so the tests still describe the guard's behaviour when the repo is
+ * clean (a guard that can only be tested by breaking the repo is a guard nobody
+ * tests).
+ *
+ * Run: node --test scripts/ci/check-subagent-frontmatter.test.mjs
+ * @module scripts/ci/check-subagent-frontmatter.test
+ */
+
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { findInvalidAgents } from "./check-subagent-frontmatter.mjs";
+
+/** Build a temp repo root containing `agents/<slug>/agent.md` for each entry. */
+function makeTree(agents) {
+  const root = mkdtempSync(join(tmpdir(), "subagent-guard-"));
+  for (const [slug, text] of Object.entries(agents)) {
+    mkdirSync(join(root, "agents", slug), { recursive: true });
+    if (text !== null)
+      writeFileSync(join(root, "agents", slug, "agent.md"), text);
+  }
+  return root;
+}
+
+const VALID = [
+  "---",
+  "name: alpha",
+  "description: Does the alpha work.",
+  "model: claude-sonnet-4-6",
+  'tools: ["Read", "Grep"]',
+  "---",
+  "",
+  "You are the alpha sub-agent.",
+  "",
+].join("\n");
+
+describe("findInvalidAgents", () => {
+  it("passes a well-formed definition", () => {
+    const { offenders, checked } = findInvalidAgents(
+      makeTree({ alpha: VALID }),
+    );
+    assert.deepEqual(offenders, []);
+    assert.equal(checked, 1);
+  });
+
+  it("catches the exact defect that shipped: frontmatter with no tools key", () => {
+    // This is the whole reason the guard exists — 57 of 70 agents in this repo
+    // were generated in precisely this shape and every one failed at dispatch.
+    const noTools = VALID.split("\n")
+      .filter((l) => !l.startsWith("tools:"))
+      .join("\n");
+    const { offenders } = findInvalidAgents(makeTree({ alpha: noTools }));
+    assert.equal(offenders.length, 1);
+    assert.equal(offenders[0].slug, "alpha");
+    assert.ok(
+      offenders[0].errors.some((e) => e.includes("tools")),
+      `expected a tools error, got: ${offenders[0].errors.join("; ")}`,
+    );
+  });
+
+  it("fails an EMPTY agents/<slug>/ directory rather than passing it", () => {
+    // doctor used to accept this, which is how an agent could be referenced
+    // everywhere and defined nowhere.
+    const { offenders } = findInvalidAgents(makeTree({ ghost: null }));
+    assert.equal(offenders.length, 1);
+    assert.equal(offenders[0].slug, "ghost");
+    assert.match(offenders[0].errors[0], /no agent\.md/);
+  });
+
+  it("fails when frontmatter.name disagrees with the directory name", () => {
+    const renamed = VALID.replace("name: alpha", "name: beta");
+    const { offenders } = findInvalidAgents(makeTree({ alpha: renamed }));
+    assert.equal(offenders.length, 1);
+    assert.ok(offenders[0].errors.some((e) => e.includes("must equal")));
+  });
+
+  it("fails a body that uses a token its tokens list does not declare", () => {
+    const undeclared = VALID.replace(
+      "You are the alpha sub-agent.",
+      "You are {{agent.fullName}}'s alpha sub-agent.",
+    ).replace('tools: ["Read", "Grep"]', 'tools: ["Read"]\ntokens: []');
+    const { offenders } = findInvalidAgents(makeTree({ alpha: undeclared }));
+    assert.equal(offenders.length, 1);
+    assert.ok(offenders[0].errors.some((e) => e.includes("undeclared token")));
+  });
+
+  it("reports an unknown declared token as a WARNING, not a build failure", () => {
+    // Advisory by design: hq does not vendor KNOWN_TOKENS, so a body authored
+    // against a newer vocabulary must not hard-fail an older agent's build.
+    const odd = VALID.replace(
+      'tools: ["Read", "Grep"]',
+      'tools: ["Read"]\ntokens: ["agent.notAThing"]',
+    );
+    const { offenders, warned } = findInvalidAgents(makeTree({ alpha: odd }));
+    assert.deepEqual(offenders, []);
+    assert.equal(warned.length, 1);
+    assert.ok(warned[0].warnings.some((w) => w.includes("agent.notAThing")));
+  });
+
+  it("reports every offender, not just the first", () => {
+    const noTools = VALID.split("\n")
+      .filter((l) => !l.startsWith("tools:"))
+      .join("\n");
+    const { offenders, checked } = findInvalidAgents(
+      makeTree({ alpha: VALID, beta: noTools, gamma: noTools }),
+    );
+    assert.equal(checked, 3);
+    assert.deepEqual(offenders.map((o) => o.slug).sort(), ["beta", "gamma"]);
+  });
+
+  it("treats a missing agents/ directory as nothing to check, not an error", () => {
+    const root = mkdtempSync(join(tmpdir(), "subagent-guard-empty-"));
+    const { offenders, checked } = findInvalidAgents(root);
+    assert.deepEqual(offenders, []);
+    assert.equal(checked, 0);
+  });
+});

package/scripts/ci/check.mjs

@@ -19,6 +19,7 @@
  *   - check-no-residual-identity: de-Robin'd paths stay persona-agnostic
  *   - check-no-build-artifacts  : no tracked .pyc/symlinks reach the tarball
  *   - check-docs-accuracy       : README links resolve; counts/agent-refs WARN
+ *   - check-subagent-frontmatter: every agents/*.md passes the registry validator
  *
  * Usage: `node scripts/ci/check.mjs`
  *   exit 0 → all checks passed; exit 1 → one or more failed.
@@ -36,6 +37,7 @@ import { run as runUnresolvedTokens } from "./check-unresolved-tokens.mjs";
 import { run as runNoResidualIdentity } from "./check-no-residual-identity.mjs";
 import { run as runNoBuildArtifacts } from "./check-no-build-artifacts.mjs";
 import { run as runDocsAccuracy } from "./check-docs-accuracy.mjs";
+import { run as runSubagentFrontmatter } from "./check-subagent-frontmatter.mjs";
 
 /**
  * The ordered list of guards this aggregator runs.
@@ -51,6 +53,7 @@ export const CHECKS = [
   { name: "check-no-residual-identity", run: runNoResidualIdentity },
   { name: "check-no-build-artifacts", run: runNoBuildArtifacts },
   { name: "check-docs-accuracy", run: runDocsAccuracy },
+  { name: "check-subagent-frontmatter", run: runSubagentFrontmatter },
 ];
 
 /**

package/scripts/ci/conformance-org-api.mjs

@@ -441,6 +441,22 @@ export function buildProbes() {
       guard: "ghost",
       why: "the task target 404s before the Escalation row",
     },
+    {
+      // The OpenQuestion sibling. Two DISTINCT options are mandatory server-side
+      // (one option is a notification, none is prose), and `context` is a STRING
+      // — the exact shape the contract row asserts, so the probe tests it rather
+      // than restating it. Ghost-guarded on the task target like its sibling.
+      method: "escalation.ask",
+      params: {
+        question: "conformance probe — which option?",
+        options: ["probe-option-a", "probe-option-b"],
+        context: "raised by the org-api conformance probe",
+        taskId: ghostTask,
+      },
+      writes: false,
+      guard: "ghost",
+      why: "the task target 404s before any OpenQuestion row is created",
+    },
     {
       method: "knowledge.invalidate",
       params: { id: ghostId("epi"), reason: "conformance probe" },

package/scripts/ci/journey-approval-escalation.mjs

@@ -0,0 +1,341 @@
+#!/usr/bin/env node
+/**
+ * scripts/ci/journey-approval-escalation.mjs — ONE JOURNEY, END TO END, LIVE.
+ *
+ * ── WHY THIS EXISTS ──
+ * Every layer of the inbound → execution stack has unit tests and every one of
+ * them passes with fakes on both sides of the joint. That proves the layers, not
+ * the seams. This script drives ONE real journey against a REAL org and prints
+ * what happened at every hop, so "the units connect" is a thing you can read
+ * rather than a thing you assert:
+ *
+ *   hop 1  hq  approval.request                 → an Approval row
+ *   hop 2  hq  ctx.appendEvent                  → an `approval.requested` frame
+ *   hop 3  SDK pullWideInbound                  → the frame off /v1/events
+ *   hop 4  SDK directedness.resolveDirected     → "mine, because <reason>"
+ *   hop 5  SDK match.matchObligation            → the plan obligation it binds to
+ *   hop 6  SDK route.routeRung                  → rung + mechanism + gates
+ *   hop 7  SDK drive → effects.escalate         → escalation.ask (an OpenQuestion)
+ *   hop 8  SDK journal.recordOutcome            → state/execution/journal.jsonl
+ *   hop 9  SDK kpi-sensors                      → is this lane measurable at all?
+ *
+ * ── WHAT IS REAL AND WHAT IS NOT ──
+ * REAL: the org, the credentials, the `/v1/events` ledger page, the board read,
+ * the channel roster, the directedness resolver, the whole execution ladder, the
+ * journal write, and the exact JSON body the escalation write would put on the
+ * wire.
+ *
+ * NOT REAL, and deliberately so: the Approval row itself. Creating one means
+ * writing to a production org, so the row and its ledger frame are synthesised —
+ * the frame BYTE-FOR-BYTE as `hq src/server/methods/approval/request.ts`
+ * appends it, the row byte-for-byte as `hq methods/approval/_shared.ts
+ * #projectApproval` returns it. Everything downstream of the frame is the
+ * shipping code path with nothing stubbed.
+ *
+ * EVERY SIDE-EFFECTING POST IS BLOCKED. The guard consults the vendored protocol
+ * table and refuses anything `sideEffecting:true`, printing the body instead. So
+ * this script can be run against production without writing to it — which is the
+ * only way it is useful, because a journey you can only run against an empty
+ * fixture org is a journey you have not tested.
+ *
+ * ── USAGE ──
+ *   AGENT_DIR=/path/to/agent \
+ *   COHORT_BASE=… COHORT_ORG_ID=… COHORT_AGENT_ID=… COHORT_API_KEY=… \
+ *   node scripts/ci/journey-approval-escalation.mjs
+ *
+ *   --allow-writes   actually send the escalation write (NOT the default)
+ *   --json           machine-readable hop report on stdout
+ *
+ * Exit 0 when every hop moved; exit 1 naming the first hop that did not.
+ */
+
+"use strict";
+
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+
+import { METHODS } from "../../lib/org/protocol.mjs";
+import { loadOrgConfig } from "../../lib/org/client.mjs";
+
+const ARGV = new Set(process.argv.slice(2));
+const ALLOW_WRITES = ARGV.has("--allow-writes");
+const AS_JSON = ARGV.has("--json");
+
+const AGENT_DIR = process.env.AGENT_DIR || process.env.AGENT_ROOT || process.cwd();
+const BASE = process.env.COHORT_BASE || "";
+const KEY = process.env.COHORT_API_KEY || process.env.COHORT_API_TOKEN || "";
+const ME = process.env.COHORT_AGENT_ID || "";
+
+const hops = [];
+const writes = [];
+
+function hop(n, name, ok, detail) {
+  hops.push({ n, name, ok, detail });
+  const mark = ok ? "✓" : "✗";
+  if (!AS_JSON) console.log(`\n${mark} HOP ${n}  ${name}`);
+  if (!AS_JSON && detail) console.log(String(detail).replace(/^/gm, "     "));
+  return ok;
+}
+
+function die(n, name, why) {
+  hop(n, name, false, why);
+  report();
+  process.exit(1);
+}
+
+function report() {
+  if (AS_JSON) {
+    console.log(JSON.stringify({ hops, writes }, null, 2));
+    return;
+  }
+  console.log("\n──────────────────────────────────────────────────────────────");
+  for (const h of hops) console.log(`  ${h.ok ? "✓" : "✗"}  hop ${h.n}  ${h.name}`);
+  console.log("──────────────────────────────────────────────────────────────");
+}
+
+// ---------------------------------------------------------------------------
+// the fetch guard: live reads, blocked writes, one synthesised row
+// ---------------------------------------------------------------------------
+
+/**
+ * Wrap `globalThis.fetch` so that:
+ *   - `GET /v1/events` is served live and the synthetic frame is appended;
+ *   - `approval.get` for the synthetic id returns the synthetic row;
+ *   - any POST to a `sideEffecting` protocol method is RECORDED, not sent.
+ *
+ * @param {{seq:number, approvalId:string, frame:object, row:object}} synth
+ */
+function installGuard(synth) {
+  const real = globalThis.fetch;
+  const json = (o) => new Response(JSON.stringify(o), { status: 200, headers: { "content-type": "application/json" } });
+
+  globalThis.fetch = async (input, init = {}) => {
+    const url = String(typeof input === "string" ? input : (input && input.url) || input);
+    const method = String(init.method || "GET").toUpperCase();
+    const m = url.match(/\/api\/v1\/([^?]+)/);
+    const rpc = m ? m[1] : "";
+
+    if (rpc === "approval.get") {
+      const body = init.body ? JSON.parse(init.body) : {};
+      if (String(body.id) === synth.approvalId) return json({ ok: true, result: synth.row });
+    }
+
+    if (rpc === "events" && method === "GET") {
+      const r = await real(input, init);
+      const j = await r.json();
+      const events = Array.isArray(j.events) ? j.events : [];
+      events.push(synth.frame);
+      return json({ events });
+    }
+
+    const d = METHODS[rpc];
+    if (method === "POST" && d && d.sideEffecting && !ALLOW_WRITES) {
+      const params = init.body ? JSON.parse(init.body) : {};
+      writes.push({ method: rpc, params });
+      return json({ ok: true, result: { id: `blocked_${writes.length}`, __blocked: true } });
+    }
+
+    if (method === "POST" && d && d.sideEffecting) writes.push({ method: rpc, params: init.body ? JSON.parse(init.body) : {} });
+    return real(input, init);
+  };
+}
+
+// ---------------------------------------------------------------------------
+
+async function main() {
+  if (!BASE || !KEY || !ME) {
+    console.error("set COHORT_BASE, COHORT_API_KEY and COHORT_AGENT_ID");
+    process.exit(2);
+  }
+
+  // agent cfg exactly as `cadence-handlers.loadAgentCfg` assembles it
+  let cfg = {};
+  try {
+    const p = join(AGENT_DIR, "config", "agent.json");
+    if (existsSync(p)) cfg = JSON.parse(readFileSync(p, "utf8"));
+  } catch { /* fail-open */ }
+  const orgCfg = loadOrgConfig(AGENT_DIR);
+  if (orgCfg && orgCfg.org) cfg.org = orgCfg.org;
+  if (!cfg.org || !cfg.org.cohort) die(0, "agent config", "no `org.cohort` in config/org.yaml — nothing to talk to");
+
+  const auth = { authorization: `Bearer ${KEY}` };
+
+  // ── the ledger head, so the synthetic frame is the ONLY new row ──────────
+  let head = 0;
+  {
+    let c = 0;
+    for (let page = 0; page < 200; page += 1) {
+      const r = await fetch(`${BASE}/api/v1/events?cursor=${c}&limit=500`, { headers: auth });
+      const j = await r.json();
+      const e = Array.isArray(j.events) ? j.events : [];
+      if (!e.length) break;
+      c = e[e.length - 1].seq;
+      if (e.length < 500) break;
+    }
+    head = c;
+  }
+
+  // ── a REAL board item this seat owns or reviews: the thing the approval blocks
+  const { collectTasks } = await import("../../lib/org/inbound/facts.mjs");
+  const board = await (await fetch(`${BASE}/api/v1/board.context`, { headers: auth })).json();
+  const tasks = collectTasks(board);
+  const mine = tasks.filter(
+    (t) => String(t.assigneeId || t.assignee || "") === ME || String(t.reviewerId || t.reviewer || "") === ME,
+  );
+  if (!mine.length) die(0, "fixture", `no live board item names ${ME} as assignee or reviewer — nothing to hang an approval on`);
+  const task = mine.find((t) => String(t.reviewerId || "") === ME) || mine[0];
+  const requester = String(task.assigneeId || task.assignee || "") || "unknown";
+
+  // ── hop 1 + 2: the hq write and its chain append, synthesised to hq's shape
+  const approvalId = `aprv_journey_${Date.now().toString(36)}`;
+  const payloadHash = "0".repeat(64);
+  const row = {
+    id: approvalId,
+    requester,
+    approver: null, // hq: NULL until resolved (G5)
+    actionClass: "exec",
+    payloadHash,
+    status: "pending",
+    itemId: task.id,
+    reason: null,
+    subject: { note: "journey harness — synthetic, never written to the org" },
+    createdAt: new Date().toISOString(),
+    expiresAt: null,
+    decidedAt: null,
+  };
+  const frame = {
+    seq: head + 1,
+    family: "approval",
+    kind: "approval.requested",
+    entity_id: approvalId,
+    actor: requester,
+    at: new Date().toISOString(),
+    payload: { requester, actionClass: "exec", payloadHash, itemId: task.id },
+    prev_hash: "",
+    row_hash: "",
+  };
+  hop(1, "hq approval.request → Approval row", true,
+    `hq src/server/methods/approval/request.ts\n` +
+    `approval ${approvalId} blocks task ${task.id} (${task.title})\nrequester ${requester}, approver NULL (G5), status pending`);
+  hop(2, "hq ctx.appendEvent → approval.requested", true,
+    `family=approval kind=approval.requested seq=${frame.seq}\n${JSON.stringify(frame.payload)}`);
+
+  installGuard({ seq: frame.seq, approvalId, frame, row });
+
+  // ── hop 3: delivery ──────────────────────────────────────────────────────
+  const { pullWideInbound } = await import("../../lib/org/inbound/index.mjs");
+  const seen = [];
+  const log = (lvl, msg) => { seen.push(`[${lvl}] ${msg}`); };
+  const pulled = await pullWideInbound({ cfg, agentId: ME, cursor: head, log });
+  const ok3 = pulled.events.length > 0;
+  hop(3, "SDK pullWideInbound → the frame off /v1/events", ok3,
+    `scanned=${pulled.stats.scanned} classified=${pulled.stats.classified} directed=${pulled.stats.directed} delivered=${pulled.stats.delivered}\n` +
+    `dropped=${JSON.stringify(pulled.stats.dropped)}\ndegraded=${JSON.stringify(pulled.stats.degraded)}\n` +
+    seen.join("\n"));
+  if (!ok3) die(3, "SDK pullWideInbound", `nothing was delivered — dropped: ${JSON.stringify(pulled.stats.dropped)}`);
+
+  let roundTrip = "not attempted";
+  const ev = pulled.events.find((e) => e.cohort && e.cohort.surface === "approval") || pulled.events[0];
+
+  // ── hop 4: directedness ─────────────────────────────────────────────────
+  hop(4, "directedness → mine, and why", !!(ev.cohort && ev.cohort.reason),
+    `surface=${ev.cohort.surface} reason=${ev.cohort.reason} family=${ev.cohort.family} kind=${ev.cohort.event_kind}\n` +
+    `subject: ${ev.subject}\ntext: ${ev.text}`);
+
+  // ── hops 5-8: the execution ladder ──────────────────────────────────────
+  process.env.MAESTRO_DAEMON_NO_AUTOSTART = "1";
+  const { eventToInboxItem } = await import("../../lib/channels/inbox-item.mjs");
+  const daemon = await import("../daemon/agent-daemon.mjs");
+
+  // THE REAL POLL LANE, not a shortcut past it. `guardMessagingInbound` writes
+  // the flattened item to `state/inbox/cohort/*.yaml` and the daemon's scan
+  // poller reads it back; anything the writer does not enumerate dies in
+  // between. Going straight from MessageEvent to the ladder would hide exactly
+  // that class of bug — which is how the chain kind, the directedness reason and
+  // the subject id all came to be dropped at this boundary.
+  const flat = eventToInboxItem(ev);
+  const { writeInboxItem } = await import("../poller/utils.mjs");
+  const { parseInboxItemYaml } = await import("../poller/inbox-scan-poller.mjs");
+  let item = flat;
+  try {
+    writeInboxItem("cohort", flat, AGENT_DIR);
+    const dir = join(AGENT_DIR, "state", "inbox", "cohort");
+    const { readdirSync } = await import("node:fs");
+    const file = readdirSync(dir).filter((f) => f.includes(String(flat.id))).pop();
+    if (file && typeof parseInboxItemYaml === "function") {
+      item = parseInboxItemYaml(readFileSync(join(dir, file), "utf8"));
+      roundTrip = `wrote + re-read ${file}`;
+    } else {
+      roundTrip = `WROTE but could not re-read (parseInboxItemYaml exported? ${typeof parseInboxItemYaml}) — using the in-memory item`;
+    }
+  } catch (err) {
+    roundTrip = `YAML round-trip skipped: ${err.message}`;
+  }
+  daemon.enrichItem(item, "cohort");
+  const gate = await daemon.runExecutionLadder(item, "cohort", item.raw_ref || item.id, "journey", {
+    answerItem: async () => ({ ok: true, path: "journey-stub" }),
+  });
+  hop(3.5, "poll-lane YAML round-trip", !/skipped|could not/.test(roundTrip), roundTrip);
+
+  const d = gate.decision;
+  if (!d) die(5, "execution ladder", "the ladder produced no decision at all");
+
+  hop(5, "obligation match", true,
+    d.obligationKey ? `bound to ${d.obligationKey}` : "UNCOVERED — no compiled REACT obligation matched (config/plan.yaml)");
+  hop(6, "rung decision", Number.isFinite(d.rung),
+    `disposition=${d.disposition} reason=${d.reason} rung=${d.rung} mechanism=${d.mechanism}\n` +
+    `gates=${JSON.stringify(d.gates)}\nwhy:\n` + (d.why || []).map((w) => `  - ${w}`).join("\n"));
+
+  const escalation = writes.find((w) => w.method === "escalation.ask" || w.method === "escalation.create");
+  hop(7, "the action taken", !!escalation,
+    escalation
+      ? `${escalation.method}\n${JSON.stringify(escalation.params, null, 2)}`
+      : `NO escalation write was attempted. writes=${JSON.stringify(writes.map((w) => w.method))}`);
+
+  // ── hop 8: the journal ──────────────────────────────────────────────────
+  const { journalPath } = await import("../../lib/execution/journal.mjs");
+  const jp = journalPath(AGENT_DIR);
+  let tail = [];
+  try {
+    tail = readFileSync(jp, "utf8").trim().split("\n").map((l) => JSON.parse(l))
+      .filter((r) => String(r.key || "").includes(String(frame.seq)));
+  } catch (err) {
+    hop(8, "outcome journalled", false, `${jp} unreadable: ${err.message}`);
+  }
+  hop(8, "outcome journalled", tail.length > 0,
+    tail.length ? `${jp}\n` + tail.map((r) => JSON.stringify(r)).join("\n")
+                : `no row in ${jp} carries this event's key`);
+
+  // ── hop 9: the KPI ──────────────────────────────────────────────────────
+  // The goal loop measures against the CAPABILITY SENSORS, so the honest check
+  // is whether the surface this journey exercised is reachable by one at all.
+  let kpiDetail = "";
+  let kpiOk = false;
+  try {
+    const { buildSensorRegistry, reachableCapabilities } = await import("../../lib/kpi-sensors.mjs");
+    const reg = buildSensorRegistry({ agentRoot: AGENT_DIR, memberId: ME });
+    const reach = reachableCapabilities(AGENT_DIR);
+    const names = Object.keys(reg || {});
+    const escalationSensors = names.filter((n) => /escal|approv|decision/i.test(n));
+    kpiOk = escalationSensors.length > 0;
+    kpiDetail =
+      `${names.length} sensor(s) registered, ${reach ? reach.size : "n/a"} reachable capabilities\n` +
+      (escalationSensors.length
+        ? `governance sensors: ${escalationSensors.join(", ")}`
+        : "NO sensor measures the escalation/approval/decision lane — this journey moves no KPI");
+  } catch (err) {
+    kpiDetail = `kpi-sensors unavailable: ${err.message}`;
+  }
+  hop(9, "KPI — is this lane measurable at all?", kpiOk, kpiDetail +
+    "\n(NOTE: this journey moved no KPI number. `escalate` is journalled, not scored — " +
+    "the goal loop measures obligations, and this event bound to none.)");
+
+  report();
+  const failed = hops.find((h) => !h.ok);
+  process.exit(failed ? 1 : 0);
+}
+
+main().catch((err) => {
+  console.error("[journey] fatal:", err && err.stack ? err.stack : err);
+  process.exit(1);
+});