harnery 0.8.0 → 0.10.0

package/src/core/workflow/billing.ts

@@ -0,0 +1,152 @@
+/**
+ * Billing-mode probe: which auth a headless harness child will actually use.
+ *
+ * The engine never handles credentials — children are plain harness CLIs and
+ * authenticate however that CLI does. But the CLIs prefer an exported API key
+ * over a stored (subscription) login when both are present, and that override
+ * is almost always an accident: a sourced .env or a leftover export silently
+ * moves the run from subsidized subscription billing to per-token API billing.
+ * This probe classifies the state per harness so the engine can refuse the
+ * silent-override case (see decision 0015 addendum) while leaving deliberate
+ * key-only hosts (CI boxes with no login) working.
+ *
+ * Detection is a heuristic over well-known credential locations; when a
+ * location can't prove presence or absence (e.g. Claude Code stores its OAuth
+ * token in the macOS keychain, not a file), the state is "unknown" and the
+ * engine never hard-fails on it — the harness CLI itself is the final
+ * authority and will error loudly if truly unauthenticated.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { HarnessName } from "./types.ts";
+
+/** The env var each harness CLI reads as an API key (preferred over a stored
+ * login when set). Shared with the child-env builder's subscription-only
+ * scrub. */
+export const API_KEY_VARS: Record<string, string> = {
+  "claude-code": "ANTHROPIC_API_KEY",
+  codex: "OPENAI_API_KEY",
+  cursor: "CURSOR_API_KEY",
+};
+
+export type LoginState = "present" | "absent" | "unknown";
+
+export type BillingMode =
+  /** No API key exported; the child rides the stored (subscription) login. */
+  | "subscription"
+  /** API key present, no stored login detected: a deliberate key-only host. */
+  | "api-key"
+  /** API key present AND a stored login exists: the key silently overrides
+   * subsidized auth. The engine refuses this unless explicitly allowed. */
+  | "api-key-override";
+
+export interface BillingProbe {
+  harness: HarnessName;
+  /** The env var checked (from API_KEY_VARS), or a note when the key was
+   * found in a credential file instead of the environment. */
+  apiKeySource: string | null;
+  apiKeyPresent: boolean;
+  login: LoginState;
+  mode: BillingMode;
+}
+
+export interface ProbeIo {
+  env?: NodeJS.ProcessEnv;
+  home?: string;
+}
+
+export type BillingProber = (harness: HarnessName) => BillingProbe;
+
+export function probeBilling(harness: HarnessName, io: ProbeIo = {}): BillingProbe {
+  const env = io.env ?? process.env;
+  const home = io.home ?? homedir();
+  const keyVar = API_KEY_VARS[harness];
+  const envKey = keyVar ? Boolean(env[keyVar]?.trim()) : false;
+
+  let login: LoginState;
+  let apiKeyPresent = envKey;
+  let apiKeySource: string | null = envKey ? keyVar : null;
+
+  switch (harness) {
+    case "claude-code":
+      login = probeClaudeLogin(home);
+      break;
+    case "codex": {
+      const codex = probeCodexAuth(env, home);
+      login = codex.login;
+      // `codex login --api-key` stores the key in auth.json rather than the
+      // env; that is still API-key billing and should surface as such.
+      if (!envKey && codex.storedApiKey) {
+        apiKeyPresent = true;
+        apiKeySource = codex.storedApiKeyNote;
+      }
+      break;
+    }
+    case "cursor":
+      // cursor-agent's stored-login location is not yet verified against a
+      // live install (adapter itself is pending verification); never claim
+      // presence or absence we can't prove.
+      login = "unknown";
+      break;
+    default:
+      // External adapters own their authentication. The generic engine must
+      // not guess credential locations or fail a plugin on a built-in-only
+      // heuristic.
+      login = "unknown";
+      break;
+  }
+
+  const mode: BillingMode =
+    apiKeyPresent && login === "present"
+      ? "api-key-override"
+      : apiKeyPresent
+        ? "api-key"
+        : "subscription";
+
+  return { harness, apiKeySource, apiKeyPresent, login, mode };
+}
+
+/** Claude Code: OAuth login lives at ~/.claude/.credentials.json on Linux;
+ * macOS stores it in the keychain (dir exists, file doesn't → unknown). */
+function probeClaudeLogin(home: string): LoginState {
+  const dir = join(home, ".claude");
+  const credFile = join(dir, ".credentials.json");
+  if (existsSync(credFile)) {
+    try {
+      const parsed = JSON.parse(readFileSync(credFile, "utf8")) as {
+        claudeAiOauth?: { accessToken?: string };
+      };
+      return parsed.claudeAiOauth?.accessToken ? "present" : "absent";
+    } catch {
+      return "unknown";
+    }
+  }
+  return existsSync(dir) ? "unknown" : "absent";
+}
+
+/** codex: auth lives at $CODEX_HOME/auth.json (default ~/.codex). A `tokens`
+ * object means a ChatGPT (subscription) login; an OPENAI_API_KEY field means
+ * a stored API key (`codex login --api-key`). */
+function probeCodexAuth(
+  env: NodeJS.ProcessEnv,
+  home: string,
+): { login: LoginState; storedApiKey: boolean; storedApiKeyNote: string } {
+  const authPath = join(env.CODEX_HOME?.trim() || join(home, ".codex"), "auth.json");
+  const storedApiKeyNote = `${authPath} (stored key)`;
+  if (!existsSync(authPath)) return { login: "absent", storedApiKey: false, storedApiKeyNote };
+  try {
+    const parsed = JSON.parse(readFileSync(authPath, "utf8")) as {
+      tokens?: unknown;
+      OPENAI_API_KEY?: string | null;
+    };
+    return {
+      login: parsed.tokens ? "present" : "absent",
+      storedApiKey: !parsed.tokens && Boolean(parsed.OPENAI_API_KEY),
+      storedApiKeyNote,
+    };
+  } catch {
+    return { login: "unknown", storedApiKey: false, storedApiKeyNote };
+  }
+}

package/src/core/workflow/child-env.ts

@@ -0,0 +1,47 @@
+/**
+ * Child-process environment builder shared by every spawn adapter.
+ *
+ * Rules (the first is a hard-won Phase 1 spike finding):
+ * 1. **Delete inherited harness-session vars, never blank them.** A nested
+ *    harness CLI under a live session inherits vars that make it exit 1 with
+ *    empty output; an empty-string var still reads as set. Scrub all three
+ *    families (CLAUDE*, CODEX*, CURSOR*) regardless of which adapter spawns —
+ *    a codex child launched from inside a Claude Code session must not
+ *    inherit CLAUDE* either.
+ * 2. **The scrub targets SESSION vars, not credentials.** CURSOR_API_KEY
+ *    matches the CURSOR* prefix but is an auth credential, so it is carved
+ *    out and re-added — a key-only cursor host must keep working. (The other
+ *    two key vars, ANTHROPIC_API_KEY and OPENAI_API_KEY, don't collide with
+ *    the scrub prefixes.)
+ * 3. **subscriptionOnly deletes every API-key var** (see billing.ts) so the
+ *    child can only authenticate via its stored subscription login — the
+ *    guarantee behind `workflow run --subscription-only`.
+ * 4. **Mark the child as a workflow child** (HARNERY_WORKFLOW_CHILD=1): the
+ *    stop-hook rule exempts it from the human-facing end-of-turn ritual while
+ *    hooks stay on, keeping heartbeat + event capture.
+ * 5. **Stamp the run id** (HARNERY_WORKFLOW_RUN_ID) so the coord layer and
+ *    web UI can associate child sessions with their workflow run.
+ */
+
+import { API_KEY_VARS } from "./billing.ts";
+
+const SCRUB_PREFIXES = ["CLAUDE", "CODEX", "CURSOR"];
+
+export interface ChildEnvOpts {
+  /** Delete all API-key vars so children can only use stored logins. */
+  subscriptionOnly?: boolean;
+}
+
+export function buildChildEnv(runId?: string, opts: ChildEnvOpts = {}): Record<string, string> {
+  const env: Record<string, string> = {};
+  const keyVars = new Set<string>(Object.values(API_KEY_VARS));
+  for (const [k, v] of Object.entries(process.env)) {
+    if (v === undefined) continue;
+    if (opts.subscriptionOnly && keyVars.has(k)) continue;
+    if (SCRUB_PREFIXES.some((p) => k.startsWith(p)) && !keyVars.has(k)) continue;
+    env[k] = v;
+  }
+  env.HARNERY_WORKFLOW_CHILD = "1";
+  if (runId) env.HARNERY_WORKFLOW_RUN_ID = runId;
+  return env;
+}

package/src/core/workflow/engine.ts

@@ -0,0 +1,403 @@
+/**
+ * Workflow engine: loads a workflow script (plain JS, `export default
+ * async (ctx) => …`), injects the ctx API, enforces the caps, journals every
+ * step to `.harnery/workflows/<run-id>/journal.jsonl`, and returns a RunReport.
+ *
+ * Guarantees the engine makes (the pitch, in code):
+ *   - **Bounded**: hard total-agent ceiling + bounded parallel() concurrency.
+ *     A runaway loop hits `maxAgents` and the run fails loud, not silently.
+ *   - **Terminating**: the run is over when the script's default export
+ *     returns. There is no recursive self-spawning path: subagents are leaf
+ *     processes; only the top-level script can spawn.
+ *   - **Schema-gated**: with `schema`, an agent's reply must strict-parse and
+ *     validate; failures re-prompt with the validation errors appended, up to
+ *     `maxAttempts`, then throw. Routing decisions read validated fields, so
+ *     the deterministic script — not a model — decides what runs next.
+ *   - **Journaled**: every stage/agent start+end lands in the run journal with
+ *     cost, duration, and child session id (the resume + web-UI substrate).
+ */
+
+import { createHash, randomBytes } from "node:crypto";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { type BillingProbe, probeBilling } from "./billing.ts";
+import type {
+  AgentOpts,
+  EngineOpts,
+  HarnessName,
+  RunReport,
+  SpawnResult,
+  WorkflowContext,
+  WorkflowModule,
+} from "./types.ts";
+import { parseStageOutput, validateAgainstSchema } from "./validate.ts";
+
+const DEFAULT_MAX_AGENTS = 50;
+const DEFAULT_CONCURRENCY = 4;
+const DEFAULT_MAX_ATTEMPTS = 2;
+const DEFAULT_TIMEOUT_MS = 300_000;
+const DEFAULT_MAX_TURNS = 25;
+
+export async function runWorkflow(scriptPath: string, opts: EngineOpts): Promise<RunReport> {
+  const absScript = isAbsolute(scriptPath) ? scriptPath : resolve(process.cwd(), scriptPath);
+  const mod = (await import(pathToFileURL(absScript).href)) as WorkflowModule;
+  if (typeof mod.default !== "function") {
+    throw new Error(`${scriptPath}: workflow script must \`export default async (ctx) => …\``);
+  }
+  const name = mod.meta?.name ?? scriptPath.replace(/^.*\//, "").replace(/\.[cm]?js$/, "");
+
+  const runId = `wf-${new Date().toISOString().replace(/[:.]/g, "-")}-${randomBytes(3).toString("hex")}`;
+  const runDir = join(opts.coordRoot, ".harnery", "workflows", runId);
+  mkdirSync(runDir, { recursive: true });
+  const journalPath = join(runDir, "journal.jsonl");
+
+  const maxAgents = opts.maxAgents ?? DEFAULT_MAX_AGENTS;
+  const concurrency = opts.concurrency ?? DEFAULT_CONCURRENCY;
+  const cwd = opts.cwd ?? opts.coordRoot;
+  const log = opts.onLog ?? ((line: string) => process.stderr.write(`${line}\n`));
+  const defaultHarness: HarnessName = opts.defaultHarness ?? "claude-code";
+
+  // Per-child fixed context overhead: children spawn in `cwd` and load its
+  // repo-instructions file into their system prompt, cache-writing it once
+  // per child. A fan-out multiplies this, so surface it BEFORE the burn.
+  const contextTokensPerChildEstimate = estimateInstructionTokens(cwd);
+  if (contextTokensPerChildEstimate > 0) {
+    log(
+      `[context] each child cache-writes ~${Math.round(contextTokensPerChildEstimate / 1000)}K tokens of repo ` +
+        `instructions from ${cwd}; a fan-out multiplies this per agent`,
+    );
+  }
+
+  // Resume: journaled results of a prior run, keyed by agent-call identity.
+  const resumeCache = opts.resumeFrom
+    ? loadResumeCache(opts.coordRoot, opts.resumeFrom)
+    : new Map<string, { kind: "json" | "text"; value: unknown }>();
+
+  let agentsSpawned = 0;
+  let agentsCached = 0;
+  let costUsd = 0;
+  let currentStage = "";
+  let agentSeq = 0;
+  const billingProbed = new Map<HarnessName, BillingProbe>();
+
+  const journal = (event: string, data: Record<string, unknown>): void => {
+    const line = JSON.stringify({
+      ts: new Date().toISOString(),
+      event,
+      stage: currentStage,
+      ...data,
+    });
+    appendFileSync(journalPath, `${line}\n`, "utf8");
+  };
+
+  // Bounded concurrency gate shared by every spawn in the run — direct
+  // `agent()` calls and `parallel()` thunks draw from the same slot pool, so
+  // the cap holds even when a script nests parallel() inside loops.
+  let inFlight = 0;
+  const waiters: Array<() => void> = [];
+  const acquire = async (): Promise<void> => {
+    if (inFlight < concurrency) {
+      inFlight++;
+      return;
+    }
+    await new Promise<void>((res) => waiters.push(res));
+    inFlight++;
+  };
+  const release = (): void => {
+    inFlight--;
+    waiters.shift()?.();
+  };
+
+  const agent = async (prompt: string, agentOpts: AgentOpts = {}): Promise<unknown> => {
+    const harness = agentOpts.harness ?? defaultHarness;
+    const spawner = opts.spawners[harness];
+    if (!spawner) {
+      throw new Error(
+        `no spawner registered for harness "${harness}" (registered: ${Object.keys(opts.spawners).join(", ") || "none"})`,
+      );
+    }
+    const id = `a${++agentSeq}`;
+    const label = agentOpts.label ?? `${prompt.slice(0, 60).replace(/\s+/g, " ")}…`;
+    const maxAttempts = agentOpts.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+
+    // Call identity for resume: same stage + harness + model + effort + turns + schema
+    // + ORIGINAL prompt → same key. Retry-mutated prompts never enter the key.
+    const key = agentCallKey(currentStage, harness, agentOpts, prompt);
+    const cached = resumeCache.get(key);
+    if (cached) {
+      agentsCached++;
+      journal("agent.cached", { id, label, key, kind: cached.kind });
+      log(
+        `[${name}] ${currentStage || "(no stage)"} → ${id} ${label} (cached from ${opts.resumeFrom})`,
+      );
+      return cached.value;
+    }
+
+    // Billing safeguard: on a harness's FIRST spawn this run, classify which
+    // auth its children will use and refuse the silent-override state (an
+    // exported API key shadowing a stored subscription login) unless the
+    // caller explicitly opted into API billing. Cached agents never reach
+    // this — no spawn, no billing.
+    if (!billingProbed.has(harness)) {
+      const probe = (opts.probeBilling ?? probeBilling)(harness);
+      billingProbed.set(harness, probe);
+      journal("billing.probe", {
+        harness,
+        mode: opts.subscriptionOnly ? "subscription" : probe.mode,
+        api_key_source: probe.apiKeySource,
+        login: probe.login,
+        subscription_only: Boolean(opts.subscriptionOnly),
+      });
+      if (opts.subscriptionOnly) {
+        if (probe.login === "absent") {
+          throw new Error(
+            `subscription-only: no stored login detected for ${harness}; ` +
+              `log the harness CLI in (or drop --subscription-only for a key-only host)`,
+          );
+        }
+        log(`[billing] ${harness}: subscription-only (API-key vars scrubbed from child env)`);
+      } else if (probe.mode === "api-key-override" && !opts.allowApiBilling) {
+        throw new Error(
+          `${probe.apiKeySource} is set AND a stored ${harness} login exists — the key silently ` +
+            `overrides your subscription auth, so children would bill per-token API rates. ` +
+            `Either unset ${probe.apiKeySource}, run with --subscription-only to scrub it from ` +
+            `child envs, or pass --allow-api-billing if API billing is intended`,
+        );
+      } else if (probe.mode === "api-key") {
+        log(
+          `[billing] ${harness}: API-key billing (${probe.apiKeySource}; no stored login detected) — ` +
+            `children bill per-token rates`,
+        );
+      } else if (probe.mode === "api-key-override") {
+        log(
+          `[billing] ${harness}: API-key billing (--allow-api-billing; key overrides stored login)`,
+        );
+      } else {
+        log(`[billing] ${harness}: subscription login`);
+      }
+    }
+
+    if (agentsSpawned >= maxAgents) {
+      throw new Error(
+        `workflow agent cap reached (${maxAgents}); raise --max-agents deliberately if the fan-out is intended`,
+      );
+    }
+    agentsSpawned++;
+
+    await acquire();
+    try {
+      journal("agent.start", {
+        id,
+        label,
+        key,
+        harness,
+        model: agentOpts.model ?? null,
+        effort: agentOpts.effort ?? null,
+      });
+      log(`[${name}] ${currentStage || "(no stage)"} → ${id} [${harness}] ${label}`);
+
+      let attemptPrompt = prompt;
+      let last: SpawnResult | null = null;
+      for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        last = await spawner({
+          prompt: attemptPrompt,
+          model: agentOpts.model,
+          effort: agentOpts.effort,
+          timeoutMs: agentOpts.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+          maxTurns: agentOpts.maxTurns ?? DEFAULT_MAX_TURNS,
+          cwd,
+          runId,
+          subscriptionOnly: opts.subscriptionOnly,
+        });
+        costUsd += last.costUsd ?? 0;
+
+        if (!last.ok) {
+          journal("agent.attempt_failed", { id, attempt, error: last.error });
+          continue; // spawn-level failure: retry with the original prompt
+        }
+        if (!agentOpts.schema) {
+          journal("agent.end", {
+            id,
+            key,
+            attempts: attempt,
+            cost_usd: last.costUsd,
+            duration_ms: last.durationMs,
+            session_id: last.sessionId,
+            result_kind: "text",
+            result: last.text,
+          });
+          return last.text;
+        }
+
+        const parsed = parseStageOutput(last.text);
+        const problems =
+          parsed.error !== undefined
+            ? [parsed.error]
+            : validateAgainstSchema(parsed.value, agentOpts.schema);
+        if (problems.length === 0) {
+          journal("agent.end", {
+            id,
+            key,
+            attempts: attempt,
+            cost_usd: last.costUsd,
+            duration_ms: last.durationMs,
+            session_id: last.sessionId,
+            result_kind: "json",
+            result: parsed.value,
+          });
+          return parsed.value;
+        }
+
+        journal("agent.schema_retry", { id, attempt, problems });
+        // Feed the validation failure back verbatim — the retry prompt carries
+        // exactly what was wrong, which is what makes bounded retry converge.
+        attemptPrompt =
+          `${prompt}\n\nYour previous reply failed validation:\n` +
+          `${problems.map((p) => `  - ${p}`).join("\n")}\n` +
+          `Reply with ONLY the corrected JSON object. No prose, no code fences.`;
+      }
+
+      const reason = last?.ok
+        ? `schema validation failed after ${maxAttempts} attempt(s)`
+        : (last?.error ?? "spawn failed");
+      journal("agent.failed", { id, error: reason });
+      throw new Error(`agent ${id} (${label}): ${reason}`);
+    } finally {
+      release();
+    }
+  };
+
+  const parallel = async <T>(thunks: Array<() => Promise<T>>): Promise<Array<T | null>> => {
+    // Fire everything; the shared slot pool inside agent() bounds real
+    // concurrency. A rejected thunk lands as null so one bad item can't kill
+    // the batch — the script filters and routes.
+    return Promise.all(
+      thunks.map((t) =>
+        t().catch((err: unknown) => {
+          journal("parallel.item_failed", { error: (err as Error).message });
+          return null;
+        }),
+      ),
+    );
+  };
+
+  const stage = (title: string): void => {
+    currentStage = title;
+    journal("stage.start", { title });
+    log(`[${name}] ── stage: ${title}`);
+  };
+
+  const ctx: WorkflowContext = { agent, parallel, stage, log };
+
+  const t0 = Date.now();
+  journal("run.start", { name, script: absScript, max_agents: maxAgents, concurrency });
+  try {
+    const result = await mod.default(ctx);
+    const report: RunReport = {
+      runId,
+      name,
+      result,
+      agentsSpawned,
+      agentsCached,
+      costUsd: round4(costUsd),
+      durationMs: Date.now() - t0,
+      journalPath,
+      contextTokensPerChildEstimate,
+      billing: Array.from(billingProbed.values()).map((p) => ({
+        harness: p.harness,
+        mode: opts.subscriptionOnly ? "subscription" : p.mode,
+      })),
+    };
+    journal("run.end", {
+      ok: true,
+      agents: agentsSpawned,
+      cached: agentsCached,
+      cost_usd: report.costUsd,
+      duration_ms: report.durationMs,
+    });
+    return report;
+  } catch (err) {
+    journal("run.end", {
+      ok: false,
+      error: (err as Error).message,
+      agents: agentsSpawned,
+      cached: agentsCached,
+      cost_usd: round4(costUsd),
+    });
+    throw err;
+  }
+}
+
+/** Stable identity for one agent() call, for the resume cache. The ORIGINAL
+ * prompt (never a retry-mutated one) plus everything that changes behavior. */
+function agentCallKey(
+  stage: string,
+  harness: string,
+  agentOpts: AgentOpts,
+  prompt: string,
+): string {
+  const basis = JSON.stringify([
+    stage,
+    harness,
+    agentOpts.model ?? null,
+    agentOpts.effort ?? null,
+    agentOpts.maxTurns ?? DEFAULT_MAX_TURNS,
+    agentOpts.schema ?? null,
+    prompt,
+  ]);
+  return createHash("sha256").update(basis).digest("hex").slice(0, 16);
+}
+
+/** Per-child fixed context overhead: the repo-instructions file at the child
+ * cwd (CLAUDE.md preferred, AGENTS.md fallback) is loaded into every child's
+ * system prompt. bytes/4 token heuristic; 0 when neither file exists. */
+function estimateInstructionTokens(cwd: string): number {
+  for (const f of ["CLAUDE.md", "AGENTS.md"]) {
+    const p = join(cwd, f);
+    if (existsSync(p)) {
+      try {
+        return Math.round(statSync(p).size / 4);
+      } catch {
+        return 0;
+      }
+    }
+  }
+  return 0;
+}
+
+/** Load a prior run's journal into a key → result map. Only `agent.end`
+ * entries (completed, validated) are resumable; failed or retried-out agents
+ * re-run live. Unreadable journal → error (a typo'd run id should fail loud,
+ * not silently run everything fresh). */
+function loadResumeCache(
+  coordRoot: string,
+  resumeFrom: string,
+): Map<string, { kind: "json" | "text"; value: unknown }> {
+  const path = join(coordRoot, ".harnery", "workflows", resumeFrom, "journal.jsonl");
+  if (!existsSync(path)) {
+    throw new Error(`--resume-from ${resumeFrom}: no journal at ${path}`);
+  }
+  const cache = new Map<string, { kind: "json" | "text"; value: unknown }>();
+  for (const line of readFileSync(path, "utf8").split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      const e = JSON.parse(line) as {
+        event?: string;
+        key?: string;
+        result_kind?: "json" | "text";
+        result?: unknown;
+      };
+      if (e.event === "agent.end" && e.key && e.result_kind !== undefined) {
+        cache.set(e.key, { kind: e.result_kind, value: e.result });
+      }
+    } catch {
+      /* skip malformed */
+    }
+  }
+  return cache;
+}
+
+function round4(n: number): number {
+  return Math.round(n * 10_000) / 10_000;
+}

package/src/core/workflow/harnesses.ts

@@ -0,0 +1,33 @@
+/**
+ * Per-harness CLI metadata: binary names plus install/login hints, shared by
+ * the spawn adapters (a not-found error should say how to fix it, not just
+ * that it happened) and `harn doctor`'s workflow-harness checks.
+ *
+ * Install commands are the vendors' official one-liners; they drift rarely
+ * but they do drift — keep this module the single place they live.
+ */
+
+import { BUILTIN_HARNESS_PROFILES } from "../harnesses/profiles.ts";
+import type { HarnessName } from "./types.ts";
+
+export const HARNESS_BINARIES: Record<string, string> = Object.fromEntries(
+  Object.values(BUILTIN_HARNESS_PROFILES).map((profile) => [profile.id, profile.binary]),
+);
+
+export const HARNESS_INSTALL_HINTS: Record<string, string> = Object.fromEntries(
+  Object.values(BUILTIN_HARNESS_PROFILES).map((profile) => [profile.id, profile.installHint]),
+);
+
+/** How to authenticate each CLI with a subscription login (the billing
+ * default — see billing.ts). */
+export const HARNESS_LOGIN_HINTS: Record<string, string> = Object.fromEntries(
+  Object.values(BUILTIN_HARNESS_PROFILES).map((profile) => [profile.id, profile.loginHint]),
+);
+
+/** One-line "it's missing, here's the fix" string for spawn adapters. */
+export function notFoundError(harness: HarnessName): string {
+  const binary = HARNESS_BINARIES[harness] ?? harness;
+  const install = HARNESS_INSTALL_HINTS[harness] ?? "install the harness CLI";
+  const login = HARNESS_LOGIN_HINTS[harness] ?? "authenticate the harness CLI";
+  return `${binary} CLI not found on PATH; ` + `install: ${install}  then authenticate: ${login}`;
+}