catherd-cli 0.2.1 → 1.1.0

package/src/domain/ids.ts

@@ -0,0 +1,97 @@
+import { CatherdError } from "./errors.ts";
+
+/** Run, role, lane and dispatch ids end up in file names: no separator, no leading dot or dash. */
+export const ID_PATTERN = /^[A-Za-z0-9][\w.-]{0,127}$/;
+
+export function assertId(kind: string, value: string): string {
+  if (!ID_PATTERN.test(value) || value.includes(".."))
+    throw new CatherdError("E_ADMIT_ID", `bad ${kind} id "${value}"`, {
+      fix: "use letters, digits, '.', '_' and '-', starting with a letter or digit",
+    });
+  return value;
+}
+
+/** The backends that run as a process through a `BackendAdapter` (cursor and grok: plan 8). */
+export const ADAPTER_IDS = ["codex", "claude-code", "opencode", "cursor", "grok"] as const;
+
+/** `claude` is the native Claude Code subagent path (no process); the rest are adapters. */
+const RUNG_BACKENDS = [...ADAPTER_IDS, "claude"] as const;
+type RungBackend = (typeof RUNG_BACKENDS)[number];
+
+export interface Rung {
+  backend: RungBackend;
+  model: string;
+  effort: string;
+}
+
+/** A model id or effort starts with a letter or digit and holds no space, so it can never read as a flag. */
+const MODEL = /^[A-Za-z0-9][^\s#]*$/;
+const EFFORT = /^[A-Za-z0-9][\w-]*$/;
+
+export function parseRung(s: string): Rung {
+  const colon = s.indexOf(":");
+  const hash = s.lastIndexOf("#");
+  const backend = s.slice(0, Math.max(colon, 0));
+  const model = s.slice(colon + 1, hash);
+  const effort = s.slice(hash + 1);
+  if (
+    colon < 1 ||
+    hash <= colon + 1 ||
+    !MODEL.test(model) ||
+    !EFFORT.test(effort) ||
+    !(RUNG_BACKENDS as readonly string[]).includes(backend)
+  )
+    throw new CatherdError("E_ADMIT_RUNG", `bad rung "${s}"`, {
+      fix: "write it as <backend>:<model>#<effort>",
+    });
+  return { backend: backend as RungBackend, model, effort };
+}
+
+/** `parseRung`, or null for a malformed rung (profile validation is what reports it). */
+export function tryParseRung(s: string): Rung | null {
+  try {
+    return parseRung(s);
+  } catch {
+    return null;
+  }
+}
+
+export const formatRung = (r: Rung): string => `${r.backend}:${r.model}#${r.effort}`;
+
+const B32 = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+
+let lastTime = -1;
+let lastRand: number[] = [];
+
+/**
+ * A monotonic ULID: 10 chars of millisecond time, then 16 random, so ids sort by creation.
+ * Within one millisecond (or when the clock steps back) the previous time is reused and
+ * the random part is incremented, so ids made in one process are strictly increasing.
+ */
+export function newDispatchId(now: number = Date.now()): string {
+  if (now <= lastTime && increment(lastRand)) now = lastTime;
+  else {
+    if (now <= lastTime) now = lastTime + 1;
+    lastRand = Array.from(crypto.getRandomValues(new Uint8Array(16)), (b) => b % 32);
+  }
+  lastTime = now;
+  let t = now;
+  let time = "";
+  for (let i = 0; i < 10; i++) {
+    time = B32.charAt(t % 32) + time;
+    t = Math.floor(t / 32);
+  }
+  return time + lastRand.map((d) => B32.charAt(d)).join("");
+}
+
+/** Adds one to base32 digits in place; false when all 16 digits overflow. */
+function increment(digits: number[]): boolean {
+  for (let i = digits.length - 1; i >= 0; i--) {
+    if ((digits[i] as number) < 31) {
+      digits[i] = (digits[i] as number) + 1;
+      return true;
+    }
+    digits[i] = 0;
+  }
+  return false;
+}

package/src/domain/jev.ts

@@ -0,0 +1,283 @@
+import { z } from "zod";
+import { type Difficulty, KINDS, type Kind, parseLaneHeader } from "./lane.ts";
+import { scrubKeyShapes, scrubSecretAssignments } from "./secrets.ts";
+
+// Spec §5.5 and research 2026-09-25-jev.md: Jev's three question types, catherd's question sets as
+// versioned data (catalog/jev.json), the trimmed lane state, and the decision rules.
+
+const ChoiceQ = z.object({
+  type: z.literal("choice"),
+  instructions: z.string(),
+  criteria: z.record(z.string(), z.string()),
+});
+const ScoreQ = z.object({
+  type: z.literal("score"),
+  instructions: z.string(),
+  criteria: z.array(z.string()).min(2).max(10),
+});
+const NoulQ = z.object({
+  type: z.literal("noul"),
+  instructions: z.string(),
+  criteria: z.object({ true: z.string(), false: z.string() }).optional(),
+});
+const QuestionSchema = z.discriminatedUnion("type", [ChoiceQ, ScoreQ, NoulQ]);
+export type JevQuestion = z.infer<typeof QuestionSchema>;
+
+const RouteRuleSchema = z.object({
+  kindMin: z.number().min(0).max(1),
+  trackMin: z.number().gt(0.5).max(1),
+  /** exactly two levels each, in order: copy then build, logic then hard */
+  trackA: z.array(z.string()).length(2),
+  trackB: z.array(z.string()).length(2),
+});
+export type RouteRule = z.infer<typeof RouteRuleSchema>;
+const VerdictRuleSchema = z.object({ min: z.number().min(0).max(1), fallback: z.string() });
+export type VerdictRule = z.infer<typeof VerdictRuleSchema>;
+
+export const JevFileSchema = z.looseObject({
+  schema: z.literal(1),
+  model: z.string(),
+  sets: z.object({
+    "route-v2": z.object({ questions: z.record(z.string(), QuestionSchema), rule: RouteRuleSchema }),
+    finding: z.object({ questions: z.record(z.string(), QuestionSchema), rule: VerdictRuleSchema }),
+    "same-defect": z.object({ questions: z.record(z.string(), QuestionSchema), rule: VerdictRuleSchema }),
+  }),
+});
+export type JevFile = z.infer<typeof JevFileSchema>;
+export type SetName = keyof JevFile["sets"];
+
+/** The answers each verdict set's caller accepts; a set's `fallback` must be one of them. */
+export const VERDICT_OPTIONS = {
+  finding: ["design", "code", "unclear"],
+  "same-defect": ["yes", "no"],
+} as const;
+
+/** JSON with object keys sorted at every depth, so equal data always hashes the same. */
+export function canonicalJson(v: unknown): string {
+  if (Array.isArray(v)) return `[${v.map(canonicalJson).join(",")}]`;
+  if (v !== null && typeof v === "object")
+    return `{${Object.keys(v)
+      .filter((k) => (v as Record<string, unknown>)[k] !== undefined)
+      .sort()
+      .map((k) => `${JSON.stringify(k)}:${canonicalJson((v as Record<string, unknown>)[k])}`)
+      .join(",")}}`;
+  return JSON.stringify(v) ?? "null";
+}
+
+export const sha256 = (s: string): string => new Bun.CryptoHasher("sha256").update(s).digest("hex");
+
+/** `<set>#<8 hex>` over the model, questions and rule: any change to one names a new question set. */
+export function questionSetId(f: JevFile, name: SetName): string {
+  const set = f.sets[name];
+  return `${name}#${sha256(canonicalJson({ model: f.model, questions: set.questions, rule: set.rule })).slice(0, 8)}`;
+}
+
+/** The per-run cache key of one request. */
+export const requestKey = (model: string, state: unknown, questions: unknown): string =>
+  sha256(canonicalJson({ model, state, questions }));
+
+/**
+ * Key-shaped strings (domain/secrets.ts) and `key = value` secrets replaced by [secret]; the pair, a
+ * bearer and a URL's user keep their names.
+ */
+export const scrubSecrets = (text: string): string =>
+  scrubSecretAssignments(scrubKeyShapes(text, "[secret]"), "[secret]");
+
+/** Research §5.3: code is not what Jev judges, and long state rots its answers. */
+export const BODY_MAX = 6000;
+const HEADER = /^\s*[*_]*(owns|fast check|kind|difficulty)[*_]*\s*:/i;
+
+export interface LaneState {
+  title: string | null;
+  owns: string[];
+  fast_check: string | null;
+  body: string;
+}
+
+/**
+ * Spec §5.5: `{ title, owns, fast_check, body }`. The body drops the header lines (so Jev never echoes
+ * the architect's own Kind/Difficulty), fenced code, and secrets, and is capped at BODY_MAX characters.
+ * Every field is scrubbed of secrets.
+ */
+export function laneState(text: string): LaneState {
+  const h = parseLaneHeader(text);
+  const body = dropFences(text)
+    .split("\n")
+    .filter((l) => !/^#\s/.test(l) && !HEADER.test(l))
+    .join("\n")
+    .trim();
+  return {
+    title: h.title === null ? null : scrubSecrets(h.title),
+    owns: h.owns.map(scrubSecrets).filter(Boolean),
+    fast_check: h.fastCheck === null ? null : scrubSecrets(h.fastCheck),
+    body: capBody(scrubSecrets(body)),
+  };
+}
+
+/** Fenced code, indented or not, becomes "[code omitted]"; a fence left open runs to the end of the text, as Markdown renders it. */
+const dropFences = (text: string): string =>
+  text.replace(/^[ \t]*(`{3,}|~{3,})[^\n]*(?:\n[\s\S]*?^[ \t]*\1[^\n]*$|[\s\S]*$)/gm, "[code omitted]");
+
+/** Capped at BODY_MAX characters, never ending the cut on half a surrogate pair. */
+const capBody = (text: string): string =>
+  text.length > BODY_MAX ? `${text.slice(0, BODY_MAX).replace(/[\uD800-\uDBFF]$/, "")}…` : text;
+
+/** Free text sent to Jev (a finding, a defect): no fenced code, no secrets, capped like a lane's body. */
+export function scrubFree(text: string): string {
+  return capBody(scrubSecrets(dropFences(text).trim()));
+}
+
+const Prob = z.record(z.string(), z.number().min(0).max(1));
+const AnswerSchema = z.discriminatedUnion("type", [
+  z.object({ type: z.literal("choice"), choice: z.string(), probabilities: Prob, confidence: z.number() }),
+  z.object({
+    type: z.literal("score"),
+    score: z.number(),
+    probabilities: Prob,
+    confidence: z.number(),
+  }),
+  z.object({ type: z.literal("noul"), noul: z.number().min(0).max(1) }),
+]);
+type JevAnswer = z.infer<typeof AnswerSchema>;
+export type JevAnswers = Record<string, JevAnswer>;
+
+const ReplySchema = z.object({
+  model: z.string(),
+  answers: z.record(z.string(), z.unknown()),
+  usage: z.object({ input_tokens: z.number(), output_tokens: z.number() }).optional(),
+});
+
+export type ParsedReply =
+  | {
+      ok: true;
+      model: string;
+      usage: { input_tokens: number; output_tokens: number } | null;
+      answers: JevAnswers;
+    }
+  | { ok: false; error: string };
+
+/** Every question answered, each in its own type and within its options, or an error naming the first. */
+export function parseReply(questions: Record<string, JevQuestion>, body: unknown): ParsedReply {
+  const r = ReplySchema.safeParse(body);
+  if (!r.success) return { ok: false, error: "unexpected response" };
+  const answers: JevAnswers = {};
+  for (const [id, q] of Object.entries(questions)) {
+    const a = AnswerSchema.safeParse(r.data.answers[id]);
+    if (!a.success || a.data.type !== q.type) return { ok: false, error: `no valid answer to ${id}` };
+    if (a.data.type === "choice" && q.type === "choice" && !Object.hasOwn(q.criteria, a.data.choice))
+      return { ok: false, error: `no valid answer to ${id}` };
+    if (
+      a.data.type === "score" &&
+      q.type === "score" &&
+      Object.keys(a.data.probabilities).some((l) => !/^\d+$/.test(l) || Number(l) >= q.criteria.length)
+    )
+      return { ok: false, error: `no valid answer to ${id}` };
+    answers[id] = a.data;
+  }
+  return { ok: true, model: r.data.model, usage: r.data.usage ?? null, answers };
+}
+
+const pOf = (a: JevAnswer | undefined, option: string): number =>
+  a && a.type !== "noul" ? (a.probabilities[option] ?? 0) : 0;
+
+export interface RouteJudgement {
+  /** the kind, when p_max ≥ kindMin and it is one of catherd's kinds */
+  kind: Kind | null;
+  pKind: number | null;
+  /** "A" (copy/build) or "B" (logic/hard) on summed probabilities, null in the dead band */
+  track: "A" | "B" | null;
+  difficulty: Difficulty | null;
+  pA: number | null;
+  pB: number | null;
+  /** the atomic questions, logged for calibration only */
+  nouls: Record<string, number>;
+  rule: string;
+}
+
+/**
+ * Spec §5.5's decision rule. Confidence is `(n·p_max − 1)/(n − 1)`, so it means different things for
+ * different option counts; the rule reads probabilities instead: the kind at p_max ≥ kindMin, the track
+ * when the summed probability of its levels reaches trackMin, and neither in between (the dead band).
+ */
+export function judgeRoute(rule: RouteRule, answers: JevAnswers): RouteJudgement {
+  const k = answers.kind;
+  const d = answers.difficulty;
+  const nouls: Record<string, number> = {};
+  for (const [id, a] of Object.entries(answers)) if (a.type === "noul") nouls[id] = a.noul;
+  let kind: Kind | null = null;
+  let pKind: number | null = null;
+  if (k && k.type === "choice") {
+    const [top, p] = Object.entries(k.probabilities).reduce((m, e) => (e[1] > m[1] ? e : m), ["", -1]);
+    pKind = p < 0 ? null : p;
+    if (p >= rule.kindMin && (KINDS as readonly string[]).includes(top)) kind = top as Kind;
+  }
+  if (!d || d.type !== "score")
+    return { kind, pKind, track: null, difficulty: null, pA: null, pB: null, nouls, rule: "no difficulty" };
+  // Rounded before comparing: 0.1 + 0.7 is 0.7999999999999999 in floating point, and must reach 0.8.
+  const round = (x: number) => Math.round(x * 1e6) / 1e6;
+  const sum = (levels: string[]) => round(levels.reduce((s, l) => s + pOf(d, l), 0));
+  const pA = sum(rule.trackA);
+  const pB = sum(rule.trackB);
+  if (pA >= rule.trackMin)
+    return {
+      kind,
+      pKind,
+      track: "A",
+      difficulty: pOf(d, rule.trackA[0] ?? "") > pOf(d, rule.trackA[1] ?? "") ? "copy" : "build",
+      pA,
+      pB,
+      nouls,
+      rule: `P(A) ${pA} ≥ ${rule.trackMin}`,
+    };
+  if (pB >= rule.trackMin)
+    return {
+      kind,
+      pKind,
+      track: "B",
+      difficulty: pOf(d, rule.trackB[1] ?? "") > pOf(d, rule.trackB[0] ?? "") ? "hard" : "logic",
+      pA,
+      pB,
+      nouls,
+      rule: `P(B) ${pB} ≥ ${rule.trackMin}`,
+    };
+  return {
+    kind,
+    pKind,
+    track: null,
+    difficulty: null,
+    pA,
+    pB,
+    nouls,
+    rule: `P(A) ${pA}, P(B) ${pB}: both below ${rule.trackMin}`,
+  };
+}
+
+export interface Verdict<T extends string> {
+  value: T;
+  /** the chosen answer's probability, when Jev answered */
+  probability: number | null;
+  /** Jev's own confidence statistic, when it answered */
+  confidence: number | null;
+  source: "jev" | "default";
+}
+
+/** Spec §5.5: `finding` and `same-defect` keep their 0.x meaning, with thresholds on probability. */
+export function judgeVerdict<T extends string>(
+  rule: VerdictRule,
+  id: string,
+  options: readonly T[],
+  answers: JevAnswers | null,
+): Verdict<T> {
+  const a = answers?.[id];
+  const fallback = rule.fallback as T;
+  if (!a || a.type !== "choice" || !(options as readonly string[]).includes(a.choice))
+    return { value: fallback, probability: null, confidence: null, source: "default" };
+  const p = a.probabilities[a.choice] ?? 0;
+  const sure = p >= rule.min;
+  return {
+    value: sure ? (a.choice as T) : fallback,
+    probability: p,
+    confidence: a.confidence,
+    source: sure ? "jev" : "default",
+  };
+}

package/src/domain/lane.ts

@@ -0,0 +1,92 @@
+import { CatherdError } from "./errors.ts";
+
+export const KINDS = ["repo_code", "terminal", "ui", "prose", "research"] as const;
+export type Kind = (typeof KINDS)[number];
+export const DIFFICULTIES = ["copy", "build", "logic", "hard"] as const;
+export type Difficulty = (typeof DIFFICULTIES)[number];
+
+export interface LaneHeader {
+  title: string | null;
+  owns: string[];
+  fastCheck: string | null;
+  kind: Kind | null;
+  difficulty: Difficulty | null;
+}
+
+const unquote = (s: string) =>
+  s
+    .trim()
+    .replace(/^`+|`+$/g, "")
+    .trim();
+
+/** The value of the first `Label:` line, allowing `**Label:**` and `_Label_:` emphasis. */
+function field(text: string, label: string): string | null {
+  const re = new RegExp(`^\\s*[*_]*${label}[*_]*\\s*:[*_]*\\s*(.*)$`, "i");
+  for (const line of text.split("\n")) {
+    const m = re.exec(line);
+    if (m) return (m[1] ?? "").trim();
+  }
+  return null;
+}
+
+const oneOf = <T extends string>(v: string | null, options: readonly T[]): T | null =>
+  v !== null && (options as readonly string[]).includes(unquote(v)) ? (unquote(v) as T) : null;
+
+/** Canonical form: no "." or empty segments, a trailing "/" kept as a directory marker. */
+export function normalizeOwned(p: string): string {
+  const s = unquote(p);
+  const parts = s.split("/").filter((seg) => seg !== "" && seg !== ".");
+  if (s.startsWith("/") || parts.length === 0 || parts.includes(".."))
+    throw new CatherdError(
+      "E_LANE_INVALID",
+      `owned path "${p}" must be relative to the repo and stay inside it`,
+      {
+        fix: "write Owns: paths like src/foo/ or src/bar.ts",
+      },
+    );
+  return parts.join("/") + (s.endsWith("/") ? "/" : "");
+}
+
+export function parseLaneHeader(text: string): LaneHeader {
+  const title = /^#\s+(.+)$/m.exec(text)?.[1]?.trim() ?? null;
+  const owns = (field(text, "owns") ?? "").split(",").map(unquote).filter(Boolean).map(normalizeOwned);
+  const check = field(text, "fast check");
+  return {
+    title,
+    owns,
+    fastCheck: check ? unquote(check) || null : null,
+    kind: oneOf(field(text, "kind"), KINDS),
+    difficulty: oneOf(field(text, "difficulty"), DIFFICULTIES),
+  };
+}
+
+/** The fix every lane-header refusal carries: the values the catalog knows. */
+export const LANE_HEADER_FIX = `write the lane's header lines as Kind: ${KINDS.join("|")} and Difficulty: ${DIFFICULTIES.join("|")}`;
+
+/**
+ * Spec 1.1 §6: a lane's `Kind:` and `Difficulty:` must be values the catalog knows, so routing never falls
+ * back on a typo. `where` names the lane file in the message. Throws E_LANE_INVALID; returns the header.
+ */
+export function assertLaneHeader(text: string, where: string): LaneHeader {
+  const h = parseLaneHeader(text);
+  const problems: string[] = [];
+  const check = (label: string, value: string | null, ok: boolean) => {
+    if (ok) return;
+    problems.push(
+      value === null ? `no ${label}: line` : `${label} "${unquote(value)}" is not one the catalog knows`,
+    );
+  };
+  check("Kind", field(text, "kind"), h.kind !== null);
+  check("Difficulty", field(text, "difficulty"), h.difficulty !== null);
+  if (problems.length)
+    throw new CatherdError("E_LANE_INVALID", `${where}: ${problems.join("; ")}`, { fix: LANE_HEADER_FIX });
+  return h;
+}
+
+const bare = (p: string) => p.replace(/\/+$/, "");
+const covers = (outer: string, inner: string) => inner === outer || inner.startsWith(`${outer}/`);
+
+/** The entries of `a` that overlap any entry of `b`; a path covers everything under it. */
+export function overlaps(a: string[], b: string[]): string[] {
+  return a.filter((x) => b.some((y) => covers(bare(x), bare(y)) || covers(bare(y), bare(x))));
+}

package/src/domain/notice.ts

@@ -0,0 +1,95 @@
+/**
+ * Spec §3.5: the message catherd pushes to the main thread when roles finish or need attention. Pure text; the
+ * notifier (services/notifier.ts) gathers the facts and infra/peer-inbox.ts sends the result.
+ */
+
+/** Spec §3.6: `later` waits for the receiver's turn to end, `next` drains at its next tool round. Never `now`. */
+export type NoticePriority = "later" | "next";
+
+/** One role's news: it finished (`record`), or an event while it runs (`stall`). */
+export interface Notice {
+  kind: "finished" | "stalled";
+  runId: string;
+  runTitle: string;
+  dispatchId: string;
+  name: string;
+  role: string;
+  /** the lane it worked, when it had one: the multi-role preview names it */
+  lane: string | null;
+  rung: string;
+  /** the record's status, or for a limit what failover did ("limit on X; failed over to Y"), or the event */
+  status: string;
+  /** the reply's STATUS word, null without a STATUS line */
+  replyStatus: string | null;
+  secs: number;
+  changedOwned: number;
+  /** the worker's reply (finished notices), capped when the message is written */
+  reply: string;
+  priority: NoticePriority;
+}
+
+/** The body of a reply a message carries at most (spec §3.5). */
+export const REPLY_CAP = 2_000;
+
+const plural = (n: number, one: string, many: string) => `${n} ${n === 1 ? one : many}`;
+
+/** The first line of one role's block: it must stand alone, since the Desktop preview shows only it. */
+export function noticeHeader(n: Notice): string {
+  const head = `catherd · ${n.runTitle} · ${n.name} ${n.role} · ${n.rung} · ${n.status}`;
+  if (n.kind === "stalled") return `${head} · running ${n.secs}s`;
+  return [
+    head,
+    n.replyStatus ? `STATUS: ${n.replyStatus}` : "no STATUS",
+    `${n.secs}s`,
+    plural(n.changedOwned, "owned file changed", "owned files changed"),
+  ].join(" · ");
+}
+
+/** The reply, at most `cap` characters, cut on a line boundary, saying where the rest is. */
+export function capNoticeReply(reply: string, cap = REPLY_CAP): string {
+  const text = reply.trimEnd();
+  if (text.length <= cap) return text;
+  const cut = text.slice(0, cap);
+  const at = cut.lastIndexOf("\n");
+  return `${at > 0 ? cut.slice(0, at) : cut}\n…(cut; result(run, name) has the rest)`;
+}
+
+/**
+ * The envelope's own tags are neutralised in a body, in any case (a parser may not care), so a reply can never
+ * close the envelope early.
+ */
+const neutral = (s: string) => s.replace(/(cross)-(session)-(message)/gi, "$1 $2 $3");
+
+function block(n: Notice): string {
+  const call = `run: "${n.runId}", name: "${n.name}"`;
+  if (n.kind === "stalled") return `${noticeHeader(n)}\nPeek: peek(${call})`;
+  const reply = capNoticeReply(n.reply);
+  return [noticeHeader(n), ...(reply ? [reply] : []), `Record: result(${call})`].join("\n");
+}
+
+/** The preview line of a message that carries several roles: `catherd · <title> · 3 roles finished: …`. */
+function previewOf(ns: Notice[]): string {
+  const titles = [...new Set(ns.map((n) => n.runTitle))];
+  const where = titles.length === 1 ? titles[0] : plural(titles.length, "run", "runs");
+  const what = ns.every((n) => n.kind === "finished")
+    ? `${ns.length} roles finished`
+    : `${plural(ns.length, "role", "roles")} to look at`;
+  const each = ns.map(
+    (n) => `${n.lane ?? n.name} ${n.kind === "stalled" ? "stalled" : n.status.split(";")[0]}`,
+  );
+  return `catherd · ${where} · ${what}: ${each.join(", ")}`;
+}
+
+/** The message body for one or more notices: one block per role, a preview line first when there are several. */
+export function formatNotices(ns: Notice[]): string {
+  if (ns.length === 1) return neutral(block(ns[0] as Notice));
+  return neutral([previewOf(ns), ...ns.map(block)].join("\n\n"));
+}
+
+/** The message's priority: the most urgent of its notices. */
+export const priorityOf = (ns: Notice[]): NoticePriority =>
+  ns.some((n) => n.priority === "next") ? "next" : "later";
+
+/** The envelope catherd sends: from-name only, no `from` (the MCP server has no reply address). */
+export const envelope = (body: string): string =>
+  `<cross-session-message from-name="catherd">\n${body}\n</cross-session-message>`;