@mutagent/helix 0.1.0-alpha.14

package/mutagent-orchestrator/scripts/render-roster.ts

@@ -0,0 +1,308 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { parse as parseYaml } from "yaml";
+
+// ---------------------------------------------------------------------------
+// render-roster — dashboard *command roster generator for mutagent-system.
+//
+// §9.4.6 (LOCKED 2026-06-24): `routing.yaml` is the SINGLE SOURCE OF TRUTH for
+// command visibility. Each command carries `visibility: shown | glimpse |
+// internal`; this script READS those flags and DETERMINISTICALLY renders the
+// dashboard roster blocks — exactly like scripts/sync-index.ts renders the
+// SYSTEM panel from the on-disk topology. The orchestrator drops the rendered
+// text into the `{command_roster}` placeholder of `help-display-template`.
+//
+//   - shown    → rendered in the visible roster (Lifecycle / State & Setup).
+//   - glimpse  → rendered under the "=== Evaluator ===" section (evaluator
+//                branches — "what the evaluator can also do", NOT standalone ADL
+//                stages). NB: the enum value "glimpse" is an implementation-only
+//                visibility directive; it is NEVER rendered as operator UI text.
+//   - internal → HIDDEN from the roster, but STILL invocable by name. Visibility
+//                is DISPLAY-ONLY; routing resolution (scripts/dispatch.ts +
+//                routing.yaml route targets) is untouched.
+//
+// A companion test (tests/render-roster.test.ts) asserts roster ==
+// routing-visibility, so `*spec`-style drift ("in routing, 0× in the roster")
+// cannot recur. Parsing logic is EXPORTED + pure (routing path injected) so it
+// is unit-testable; main() only parses args + prints.
+//
+// No clock, no network, no env reads — same routing.yaml in, same roster out.
+// ---------------------------------------------------------------------------
+
+export type Visibility = "shown" | "glimpse" | "internal";
+
+export interface CommandVisibility {
+  /** Canonical command name WITHOUT the leading `*` (e.g. "spec", "build-evals"). */
+  name: string;
+  /** The §9.4.6 visibility class. Unknown/missing flags default to "internal". */
+  visibility: Visibility;
+  /** Routing owner: "orchestrator-internal", a route_target, or a forward-intent owning_skill. */
+  owner: string;
+  /** Where the command is declared in routing.yaml. */
+  source: "owned" | "forward_intent";
+}
+
+const VALID_VISIBILITY = new Set<Visibility>(["shown", "glimpse", "internal"]);
+
+/** Coerce a raw flag to a Visibility; anything unknown/missing => "internal" (safe-hidden). */
+function coerceVisibility(raw: unknown): Visibility {
+  return typeof raw === "string" && VALID_VISIBILITY.has(raw as Visibility)
+    ? (raw as Visibility)
+    : "internal";
+}
+
+// Default routing.yaml: this file's sibling-of-parent (scripts/ -> orchestrator/).
+function defaultRoutingPath(): string {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  return path.resolve(here, "..", "routing.yaml");
+}
+
+/** The committed routing.yaml path (the single source of truth). */
+export const DEFAULT_ROUTING_PATH = defaultRoutingPath();
+
+interface RoutingYaml {
+  commands?: Record<
+    string,
+    { route_target?: string; visibility?: unknown } | null
+  >;
+  forward_intents?: Array<{
+    owning_skill?: string;
+    commands?: Record<string, { visibility?: unknown } | null>;
+  }>;
+}
+
+/**
+ * Parse routing.yaml and return the visibility class of every command (owned +
+ * forward-intent), sorted by name for deterministic output. Pure: the path is a
+ * parameter so tests can point at fixtures.
+ */
+export function loadCommandVisibility(
+  routingPath: string = DEFAULT_ROUTING_PATH,
+): CommandVisibility[] {
+  const parsed = parseYaml(fs.readFileSync(routingPath, "utf-8")) as RoutingYaml;
+  const out: CommandVisibility[] = [];
+
+  for (const [name, def] of Object.entries(parsed.commands ?? {})) {
+    out.push({
+      name,
+      visibility: coerceVisibility(def?.visibility),
+      owner: def?.route_target ?? "orchestrator-internal",
+      source: "owned",
+    });
+  }
+
+  for (const group of parsed.forward_intents ?? []) {
+    const owner = group.owning_skill ?? "unknown";
+    for (const [name, def] of Object.entries(group.commands ?? {})) {
+      out.push({
+        name,
+        visibility: coerceVisibility(def?.visibility),
+        owner,
+        source: "forward_intent",
+      });
+    }
+  }
+
+  out.sort((a, b) => a.name.localeCompare(b.name));
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// PRESENTATION layer. Visibility (above) decides INCLUSION; this map decides
+// LAYOUT (which block, order, one-liner, route tag). It is NOT a second source
+// of truth for visibility — every NON-internal command in routing.yaml MUST
+// have an entry here, else renderRoster THROWS (caught by the drift test). No
+// internal command is listed here (they are filtered out before lookup).
+// ---------------------------------------------------------------------------
+
+type Block = "lifecycle" | "evaluator" | "state";
+
+interface Presentation {
+  block: Block;
+  order: number;
+  summary: string;
+  /** Optional right-side route annotation, e.g. "[→ evaluator]". */
+  tag?: string;
+}
+
+const DISPLAY: Readonly<Record<string, Presentation>> = {
+  // ── Lifecycle (① SPEC ▶ ② BUILD ▶ ③ EVALUATE ▶ ④ DIAGNOSE ▶ ⑤ IMPROVE) ───
+  spec: {
+    block: "lifecycle",
+    order: 1,
+    summary: "Capture WHAT a new agent IS → portable, validated agentspec.yaml",
+    tag: "[→ agentspec]",
+  },
+  build: {
+    block: "lifecycle",
+    order: 2,
+    summary: "Implement a validated agentspec.yaml into the target",
+    tag: "[→ builder]",
+  },
+  "sync-spec": {
+    block: "lifecycle",
+    order: 3,
+    summary: "Resync agentspec.yaml from implementation drift",
+    tag: "[→ builder]",
+  },
+  discover: {
+    block: "lifecycle",
+    order: 4,
+    summary: "Collect + curate traces (fetch · select · classify) → curated handoff",
+    tag: "[→ discovery]",
+  },
+  evaluate: {
+    block: "lifecycle",
+    order: 4,
+    summary: "Run evals vs a skill/agent → success/failure + verdict (judge only)",
+    tag: "[→ evaluator]",
+  },
+  diagnose: {
+    block: "lifecycle",
+    order: 5,
+    summary: "RCA + causal chains on routed failures → ranked remedies",
+    tag: "[→ diagnostics]",
+  },
+  // ── Evaluator (glimpse) — evaluator ops under EVALUATE, NOT standalone stages ──
+  "discover-evals": {
+    block: "evaluator",
+    order: 1,
+    summary: "Mine eval criteria from discovered traces → grow the eval suite",
+  },
+  "discover-dataset": {
+    block: "evaluator",
+    order: 2,
+    summary: "Distill a scenario-balanced dataset from traces (edge-cases first)",
+  },
+  "build-evals": {
+    block: "evaluator",
+    order: 3,
+    summary: "Build the eval suite for the judge (guided HITL · --auto = direct)",
+  },
+  "build-dataset": {
+    block: "evaluator",
+    order: 4,
+    summary: "Synthesize test cases (coverage)            (HITL)",
+  },
+  // review + validate are visibility:internal for now (hidden from roster; still route).
+  review: {
+    block: "evaluator",
+    order: 5,
+    summary: "Human label-capture UI (feeds *validate)    (HITL)",
+  },
+  validate: {
+    block: "evaluator",
+    order: 6,
+    summary: "Calibrate a judge vs human labels (TPR/TNR)  (HITL)",
+  },
+  // ── State & Setup ─────────────────────────────────────────────────────────
+  sync: {
+    block: "state",
+    order: 1,
+    summary: "Explore + index the topology of skills/agents",
+  },
+  status: {
+    block: "state",
+    order: 2,
+    summary: "Where are we — active stage · last verdict · pending gates",
+  },
+  onboard: {
+    block: "state",
+    order: 3,
+    summary: "Unified onboarding + config (.mutagent/config.yaml)   (alias *config)",
+  },
+  help: {
+    block: "state",
+    order: 4,
+    summary: "Show this dashboard",
+  },
+};
+
+// Operator-facing section headers. NOTE: the `glimpse` visibility tier maps to
+// the clean "=== Evaluator ===" header — the §9.4.6 enum value "glimpse" is an
+// IMPLEMENTATION directive (routing.yaml `visibility:`), NEVER rendered as UI
+// text. Likewise "shown"/"internal"/"visibility" must never surface here.
+const BLOCK_HEADERS: Readonly<Record<Block, string>> = {
+  lifecycle: "=== Lifecycle ===",
+  evaluator: "=== Evaluator ===",
+  state: "=== State & Setup ===",
+};
+
+const BLOCK_ORDER: readonly Block[] = ["lifecycle", "evaluator", "state"];
+
+/** The ⑤ IMPROVE note, rendered as a continuation under the Lifecycle block. */
+const GATED_APPLY_NOTE =
+  "                   (⑤ IMPROVE = gated apply, downstream of *diagnose — never auto-applies)";
+
+// Dot-leader column width for the `*label .... summary` rows.
+const DOT_COL = 18;
+
+function formatRow(name: string, p: Presentation): string {
+  const label = `*${name}`;
+  const lead = `${label} `;
+  const dots = ".".repeat(Math.max(3, DOT_COL - lead.length));
+  const body = `${lead}${dots} ${p.summary}`;
+  return p.tag ? `${body}   ${p.tag}` : body;
+}
+
+/**
+ * Render the visible roster from a command-visibility list. INTERNAL commands
+ * are filtered out; SHOWN + GLIMPSE commands are grouped into their block and
+ * ordered. A non-internal command with no DISPLAY entry is a drift error and
+ * THROWS (the test catches it).
+ */
+export function renderRoster(commands: CommandVisibility[]): string {
+  const visible = commands.filter((c) => c.visibility !== "internal");
+
+  for (const c of visible) {
+    if (!(c.name in DISPLAY)) {
+      throw new Error(
+        `render-roster: non-internal command "*${c.name}" is missing presentation metadata in DISPLAY. ` +
+          `Add it (block/order/summary) or mark it visibility:internal in routing.yaml.`,
+      );
+    }
+  }
+
+  const lines: string[] = [];
+  for (const block of BLOCK_ORDER) {
+    const rows = visible
+      .filter((c) => DISPLAY[c.name]!.block === block)
+      .sort((a, b) => DISPLAY[a.name]!.order - DISPLAY[b.name]!.order);
+    if (rows.length === 0) continue;
+
+    if (lines.length > 0) lines.push("");
+    lines.push(BLOCK_HEADERS[block]);
+    for (const c of rows) lines.push(formatRow(c.name, DISPLAY[c.name]!));
+    if (block === "lifecycle") lines.push(GATED_APPLY_NOTE);
+  }
+
+  return lines.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// CLI — thin wrapper. Flags: --json (visibility list only) · <routing.yaml>
+// positional override (defaults to the sibling routing.yaml).
+// ---------------------------------------------------------------------------
+function main(argv: string[]): void {
+  const args = argv.slice(2);
+  const jsonOnly = args.includes("--json");
+  const positional = args.find((a) => !a.startsWith("--"));
+  const routingPath = positional ? path.resolve(positional) : DEFAULT_ROUTING_PATH;
+
+  const commands = loadCommandVisibility(routingPath);
+
+  if (jsonOnly) {
+    console.info(JSON.stringify(commands, null, 2));
+    return;
+  }
+  console.info(renderRoster(commands));
+}
+
+const isMain =
+  typeof import.meta !== "undefined" &&
+  (import.meta as unknown as { main?: boolean }).main === true;
+if (isMain) {
+  const argv = typeof Bun !== "undefined" ? Bun.argv : process.argv;
+  main(argv);
+}

package/mutagent-orchestrator/scripts/resolve-credential.ts

@@ -0,0 +1,185 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+// ---------------------------------------------------------------------------
+// resolve-credential — the ONE shared secret resolver (operator decision
+// 2026-06-29).
+//
+// A `credential_ref` in `.mutagent/config.yaml` is NEVER a raw secret value — it
+// names where the value lives. This resolver turns that ref into the actual
+// secret by a fixed PRECEDENCE:
+//
+//   1. process.env[name]      — the running environment wins (CI, shell export).
+//   2. local `.env`           — projectRoot/.env (the conventional dev secret file).
+//   3. `.mutagentrc`          — projectRoot/.mutagentrc (the credential/provider
+//                               store; the fallback when no `.env` is around).
+//
+// `.mutagentrc` STAYS — it is the gitignored provider-secret store. Raw secret
+// VALUES never enter config.yaml; the config holds only the `credential_ref`.
+//
+// A ref may be a bare ENV-VAR NAME (string) or an object that also pins an
+// explicit file to read first: `{ env: "LANGFUSE_SECRET_KEY", path: ".env.ci" }`.
+//
+// Design invariants (mirror config-schema.ts / handover-contract.ts):
+//   - Pure core with INJECTED deps (env map + file reader) → deterministic tests,
+//     never touches the real environment or disk in the pure path.
+//   - A thin CLI wrapper binds the real process.env + fs.
+//   - Never throws on a missing file; a not-found ref returns { found:false }.
+// ---------------------------------------------------------------------------
+
+/** A credential reference: a bare env-var NAME, or a name + an explicit file to try first. */
+export type CredentialRef = string | { env: string; path?: string };
+
+/** Where a resolved secret came from (transparency — surfaced, never the value). */
+export type CredentialSource = "env" | ".env" | ".mutagentrc" | "ref-path";
+
+export type ResolveCredentialResult =
+  | { found: true; value: string; source: CredentialSource; from: string }
+  | { found: false; name: string; tried: string[] };
+
+export interface ResolveCredentialDeps {
+  /** Injected environment map (defaults to process.env in the thin wrapper). */
+  env: Record<string, string | undefined>;
+  /** Injected file reader → file contents, or null if unreadable/absent. Never throws. */
+  readFile: (p: string) => string | null;
+}
+
+const ENV_LINE = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)\s*$/;
+
+/**
+ * Parse a dotenv-style file (`.env` / `.mutagentrc`). One `KEY=VALUE` per line;
+ * `#` comments + blank lines ignored; surrounding single/double quotes stripped;
+ * `export ` prefix tolerated. Pure — string in, map out. Last assignment wins.
+ */
+export function parseDotenv(content: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const rawLine of content.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (line === "" || line.startsWith("#")) continue;
+    const m = ENV_LINE.exec(line);
+    if (!m) continue;
+    const key = m[1];
+    let val = m[2];
+    // Strip a trailing inline comment only when the value is unquoted.
+    const quoted =
+      (val.startsWith('"') && val.endsWith('"') && val.length >= 2) ||
+      (val.startsWith("'") && val.endsWith("'") && val.length >= 2);
+    if (quoted) {
+      val = val.slice(1, -1);
+    } else {
+      const hash = val.indexOf(" #");
+      if (hash >= 0) val = val.slice(0, hash).trim();
+    }
+    out[key] = val;
+  }
+  return out;
+}
+
+/** Normalize a CredentialRef to `{ name, refPath }`. */
+function normalizeRef(ref: CredentialRef): { name: string; refPath?: string } {
+  if (typeof ref === "string") return { name: ref };
+  return { name: ref.env, refPath: ref.path };
+}
+
+/**
+ * Resolve a credential ref to its secret value by precedence (env → .env →
+ * .mutagentrc), with an optional ref-pinned file tried FIRST. Pure: all I/O is
+ * injected via `deps`. Returns the value + its source for transparency, or
+ * { found:false } with the list of places tried.
+ *
+ * @param ref         bare env-var name, or { env, path }.
+ * @param projectRoot the install/init dir (where `.env` + `.mutagentrc` live).
+ * @param deps        injected env map + file reader.
+ */
+export function resolveCredential(
+  ref: CredentialRef,
+  projectRoot: string,
+  deps: ResolveCredentialDeps,
+): ResolveCredentialResult {
+  const { name, refPath } = normalizeRef(ref);
+  const tried: string[] = [];
+
+  // 0. process.env always wins (CI / shell export).
+  const envVal = deps.env[name];
+  if (envVal !== undefined && envVal !== "") {
+    return { found: true, value: envVal, source: "env", from: `process.env.${name}` };
+  }
+  tried.push(`process.env.${name}`);
+
+  // 1. A ref-pinned explicit file (highest file priority when given).
+  const fileTiers: { label: CredentialSource; file: string }[] = [];
+  if (refPath) {
+    fileTiers.push({ label: "ref-path", file: path.resolve(projectRoot, refPath) });
+  }
+  // 2./3. conventional files, in precedence order.
+  fileTiers.push({ label: ".env", file: path.resolve(projectRoot, ".env") });
+  fileTiers.push({ label: ".mutagentrc", file: path.resolve(projectRoot, ".mutagentrc") });
+
+  for (const tier of fileTiers) {
+    tried.push(tier.file);
+    const content = deps.readFile(tier.file);
+    if (content === null) continue;
+    const parsed = parseDotenv(content);
+    const val = parsed[name];
+    if (val !== undefined && val !== "") {
+      return { found: true, value: val, source: tier.label, from: tier.file };
+    }
+  }
+
+  return { found: false, name, tried };
+}
+
+/** Real-fs file reader for the thin wrapper: contents or null (never throws). */
+export function readFileOrNull(p: string): string | null {
+  try {
+    return fs.readFileSync(p, "utf-8");
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Thin wrapper binding the REAL process.env + fs. App code calls this; tests call
+ * the pure `resolveCredential` with injected deps.
+ */
+export function resolveCredentialLive(
+  ref: CredentialRef,
+  projectRoot: string,
+): ResolveCredentialResult {
+  return resolveCredential(ref, projectRoot, {
+    env: process.env,
+    readFile: readFileOrNull,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// CLI — resolve a ref and report ONLY its source (never the secret value):
+//   bun run scripts/resolve-credential.ts <ENV_VAR_NAME> [projectRoot]
+// Exit 0 = found (prints source); exit 1 = not found (prints places tried).
+// ---------------------------------------------------------------------------
+
+function runCli(argv: string[]): number {
+  const name = argv[2];
+  const root = argv[3] ?? process.cwd();
+  if (!name) {
+    process.stderr.write("usage: resolve-credential.ts <ENV_VAR_NAME> [projectRoot]\n");
+    return 1;
+  }
+  const res = resolveCredentialLive(name, root);
+  if (res.found) {
+    console.info(`[resolve-credential] FOUND ${name} via ${res.source} (${res.from}). Value NOT printed.`);
+    return 0;
+  }
+  process.stderr.write(
+    `[resolve-credential] NOT FOUND ${name}. Tried:\n  ${res.tried.join("\n  ")}\n`,
+  );
+  return 1;
+}
+
+const isMain =
+  typeof import.meta !== "undefined" &&
+  (import.meta as unknown as { main?: boolean }).main === true;
+if (isMain) {
+  const argv = typeof Bun !== "undefined" ? Bun.argv : process.argv;
+  process.exit(runCli(argv));
+}

package/mutagent-orchestrator/scripts/resolve-paths.ts

@@ -0,0 +1,114 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+// ---------------------------------------------------------------------------
+// resolve-paths — the LOCAL `.mutagent/` source-of-truth resolver (operator
+// decision 2026-06-29).
+//
+// Everything lives under ONE local `.mutagent/` rooted at the INSTALL/init dir —
+// the dir where `mutagent … init` ran (the nearest ancestor that already has a
+// `.mutagent/`). NEVER `~/.mutagent`: config + artifacts are project-local so a
+// checkout is self-contained and two projects never share state.
+//
+//   <root>/.mutagent/
+//     config.yaml                  ← the single global config (resolveConfigPath)
+//     evaluator/                   ← evaluator artifacts        (stageDir "evaluator")
+//     diagnostics/{runId}/         ← diagnostics run artifacts  (stageDir "diagnostics")
+//     diagnostics/library/         ← class-memory (per-install)
+//     specs/{spec_id}/             ← agentspec build artifacts  (stageDir "specs")
+//     skill-builder/               ← (stageDir "skill-builder")
+//
+// Design invariants (mirror config-schema.ts / resolve-credential.ts):
+//   - Pure core with an INJECTED `exists` predicate → deterministic tests.
+//   - A thin live wrapper binds real fs + process.cwd().
+//   - Never throws; when no `.mutagent/` ancestor exists, fall back to the start
+//     dir (that is where `init` will create it — first-run friendly).
+// ---------------------------------------------------------------------------
+
+/** The single local root dir name. Never `~/.mutagent`. */
+export const MUTAGENT_DIR = ".mutagent" as const;
+
+/** The canonical ADL stage sub-roots under `.mutagent/`. */
+export const STAGE_DIRS = {
+  evaluator: "evaluator",
+  diagnostics: "diagnostics",
+  specs: "specs",
+  skillBuilder: "skill-builder",
+} as const;
+export type StageDirName = (typeof STAGE_DIRS)[keyof typeof STAGE_DIRS];
+
+/**
+ * Walk UP from `startDir` to the nearest ancestor that already contains a
+ * `.mutagent/` directory; return that ancestor (the install/init root). If none
+ * is found, return `startDir` (first run — `init` creates `.mutagent/` here).
+ * Pure: directory existence is the injected `exists` predicate.
+ */
+export function findConfigRoot(
+  startDir: string,
+  exists: (p: string) => boolean,
+): string {
+  let dir = path.resolve(startDir);
+  // Bounded by the filesystem root — path.dirname("/") === "/" terminates.
+  for (;;) {
+    if (exists(path.join(dir, MUTAGENT_DIR))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return path.resolve(startDir);
+}
+
+/** True iff `p` is an existing directory (real-fs predicate for the live wrapper). */
+export function dirExists(p: string): boolean {
+  try {
+    return fs.statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/** Live: the install/init root for the current process (nearest `.mutagent/` ancestor, else cwd). */
+export function resolveConfigRoot(startDir: string = process.cwd()): string {
+  return findConfigRoot(startDir, dirExists);
+}
+
+/** `<root>/.mutagent`. */
+export function mutagentDir(root: string): string {
+  return path.join(root, MUTAGENT_DIR);
+}
+
+/** The single global config path: `<root>/.mutagent/config.yaml`. */
+export function configPath(root: string): string {
+  return path.join(mutagentDir(root), "config.yaml");
+}
+
+/** Live: the resolved global config path for the current process. */
+export function resolveConfigPath(startDir: string = process.cwd()): string {
+  return configPath(resolveConfigRoot(startDir));
+}
+
+/** A stage artifact root: `<root>/.mutagent/<stage>[/...segments]`. */
+export function stageDir(root: string, stage: StageDirName, ...segments: string[]): string {
+  return path.join(mutagentDir(root), stage, ...segments);
+}
+
+// ---------------------------------------------------------------------------
+// CLI — print the resolved root + config path for the current dir:
+//   bun run scripts/resolve-paths.ts [startDir]
+// ---------------------------------------------------------------------------
+
+function runCli(argv: string[]): number {
+  const start = argv[2] ?? process.cwd();
+  const root = resolveConfigRoot(start);
+  console.info(`[resolve-paths] root:   ${root}`);
+  console.info(`[resolve-paths] config: ${configPath(root)}`);
+  return 0;
+}
+
+const isMain =
+  typeof import.meta !== "undefined" &&
+  (import.meta as unknown as { main?: boolean }).main === true;
+if (isMain) {
+  const argv = typeof Bun !== "undefined" ? Bun.argv : process.argv;
+  process.exit(runCli(argv));
+}

package/mutagent-orchestrator/scripts/slack/format.ts

@@ -0,0 +1,63 @@
+// ---------------------------------------------------------------------------
+// slack/format — PURE Slack mrkdwn primitives (SLACK-CORE).
+//
+// The SHARED low-level formatting layer used by BOTH monitor emitters
+// (dogfood/slack-thread.ts · monitor/slack-notify.ts). No I/O, no clock, no
+// random — every function is `string → string` (or a small tuple in), so a
+// rendered message is byte-identical for identical input (deterministic tests).
+//
+// Slack "mrkdwn" is NOT CommonMark: bold is `*x*` (single asterisk), italic is
+// `_x_`, inline code is backticks. These primitives encode exactly that dialect.
+// ---------------------------------------------------------------------------
+
+/** Bold — Slack mrkdwn uses a SINGLE asterisk (`*x*`, not `**x**`). */
+export function bold(text: string): string {
+  return `*${text}*`;
+}
+
+/** Italic — Slack mrkdwn underscores (`_x_`). */
+export function italic(text: string): string {
+  return `_${text}_`;
+}
+
+/** Inline code span (backticks). */
+export function code(text: string): string {
+  return `\`${text}\``;
+}
+
+/** A single bullet line (`• item`). Compose several with `\n`. */
+export function bullet(text: string): string {
+  return `• ${text}`;
+}
+
+/**
+ * A titled section: a bold heading followed by its body lines (each already a
+ * rendered string, e.g. `bullet(...)`). Empty bodies render the heading alone.
+ */
+export function section(title: string, lines: string[] = []): string {
+  const head = bold(title);
+  return lines.length === 0 ? head : `${head}\n${lines.join("\n")}`;
+}
+
+/**
+ * A deterministic UTC `HH:MM` clock label for an epoch-ms stamp. Pure (no locale,
+ * no self-read clock) — the caller INJECTS the epoch, so renders stay stable
+ * across machines/timezones.
+ */
+export function ts(epochMs: number): string {
+  return new Date(epochMs).toISOString().slice(11, 16);
+}
+
+/**
+ * A compact human duration for a millisecond span (`0s` · `45s` · `12m` · `3h`).
+ * Pure + deterministic. Used by progress/heartbeat lines.
+ */
+export function fmtDuration(ms: number): string {
+  const totalSeconds = Math.max(0, Math.floor(ms / 1000));
+  if (totalSeconds < 60) return `${totalSeconds}s`;
+  const totalMinutes = Math.floor(totalSeconds / 60);
+  if (totalMinutes < 60) return `${totalMinutes}m`;
+  const hours = Math.floor(totalMinutes / 60);
+  const minutes = totalMinutes % 60;
+  return minutes === 0 ? `${hours}h` : `${hours}h${minutes}m`;
+}