catherd-cli 0.2.1 → 1.1.0

package/src/services/ports.ts

@@ -0,0 +1,135 @@
+import type { Budget } from "../domain/budget.ts";
+import type { SessionEnv } from "../infra/claude-session.ts";
+import type { BillingMode } from "../domain/cost.ts";
+import type { Verdict } from "../domain/jev.ts";
+import type { Difficulty, Kind } from "../domain/lane.ts";
+import type { Access } from "../domain/record.ts";
+import type { Role } from "../domain/roles.ts";
+import type { Change, ProfilePatch } from "../domain/profile.ts";
+import type { Issue } from "../domain/profile-rules.ts";
+import type { RouteJev, RouteSource } from "../domain/route.ts";
+
+/** What the run lifecycle reads from a profile. Rungs are `backend:model#effort`; a role's in ladder order. */
+export interface ProfileView {
+  name: string;
+  objective: "cost" | "speed";
+  /** `defaultRung`, when set, is where a lane starts without a kind and difficulty (spec §5.4) */
+  roles: Partial<
+    Record<Role, { enabled: boolean; access: Access; rungs: string[]; defaultRung?: string; network?: false }>
+  >;
+  /** per billing key (spec §7.1); a missing key bills as DEFAULT_BILLING */
+  billing: Partial<Record<string, BillingMode>>;
+  jev: { use: "auto" | "off" };
+  /** per backend id: run its harness isolated (spec §7.1 `harness`) */
+  isolated: Partial<Record<string, boolean>>;
+  /** rung → its stand-in on a usage limit (spec §4.5) */
+  failover: Record<string, string>;
+  budget: Budget;
+  timeouts: { idleMin: number; wallMin: number };
+  preflight: { confirm: boolean };
+  heavy: number | "cpus/2";
+  notify: string[];
+}
+
+/** What a profile write returns (spec §7.3): whether it saved, why not, what changed, and the agents it touched. */
+export interface ProfileSaved {
+  saved: boolean;
+  errors: Issue[];
+  warnings: Issue[];
+  diff: Change[];
+  linked: string[];
+  pruned: string[];
+  /** agents whose link is new or whose file changed: they apply from the next Claude Code session */
+  newSessionNeededFor: string[];
+}
+
+export interface ProfilePort {
+  /** The profile bound to `repo` (a git toplevel), else the active one; null asks for the active one. */
+  forRepo(repo: string | null): ProfileView;
+  /** Without a name (get, validate, set): the profile `repo`, a repository's toplevel, runs on. */
+  get(
+    name?: string,
+    repo?: string | null,
+  ): {
+    /** the global active profile */
+    active: string;
+    /** the profile `repo` runs on: its binding, else the active one */
+    here: string;
+    profiles: string[];
+    profile: ProfileView;
+    /** per role: whether its backend holds it to its access mode (spec D10) */
+    enforcement: Partial<Record<Role, "enforced" | "advisory">>;
+  };
+  validate(name?: string, repo?: string | null): { valid: boolean; errors: Issue[]; warnings: Issue[] };
+  set(name: string | undefined, patch: ProfilePatch, repo?: string | null): ProfileSaved;
+  /** The native agent that runs `rung` for `role` under `repo`'s profile; null unless it is a `claude:` rung. */
+  agentFor(repo: string | null, role: Role, rung: string): string | null;
+}
+
+export interface RouteRequest {
+  runDir: string;
+  repo: string;
+  profile: ProfileView;
+  role: Role;
+  /** the lane's id, for jev.jsonl; null when routing a role without a lane */
+  lane: string | null;
+  laneText: string | null;
+  spentFraction: number;
+}
+
+export interface RouteAnswer {
+  rung: string;
+  ladder: string[];
+  source: RouteSource;
+  kind: Kind | null;
+  difficulty: Difficulty | null;
+  /** the Jev question set asked, and its summed probabilities, for outcomes.jsonl (spec §5.6) */
+  questionSet: string | null;
+  jev: RouteJev | null;
+}
+
+export type { Verdict };
+
+export interface CatalogFilter {
+  role?: Role;
+  backend?: string;
+  text?: string;
+  scoredOnly: boolean;
+  limit: number;
+  /** the git toplevel whose per-repository listings (opencode's) to read; none reads the global ones */
+  repo?: string;
+}
+
+export interface RoutingPort {
+  route(req: RouteRequest): Promise<RouteAnswer>;
+  /** `use` is the repo profile's `jev.use`: "off" answers with the rule's default and never asks Jev */
+  finding(
+    runDir: string,
+    laneText: string,
+    finding: string,
+    use: "auto" | "off",
+  ): Promise<Verdict<"design" | "code" | "unclear">>;
+  sameDefect(
+    runDir: string,
+    before: string,
+    after: string,
+    use: "auto" | "off",
+  ): Promise<Verdict<"yes" | "no">>;
+  /** `billing` prices the rungs (spec §5.3); absent keys bill as DEFAULT_BILLING */
+  catalog(
+    filter: CatalogFilter,
+    billing?: Partial<Record<string, BillingMode>>,
+  ): { total: number; models: unknown[] };
+}
+
+/** Everything a service needs from outside it; the entry layer builds one, tests build fakes. */
+export interface Deps {
+  profiles: ProfilePort;
+  routing: RoutingPort;
+  version: string;
+  /** how often the supervisor and the dispatch watchers poll, in ms */
+  pollMs: number;
+  /** the Claude Code session this process serves (spec §3.3), from its environment; null outside one */
+  session: SessionEnv | null;
+  now: () => number;
+}

package/src/services/preflight.ts

@@ -0,0 +1,221 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { CatherdError, errorMessage } from "../domain/errors.ts";
+import { assertLaneHeader, LANE_HEADER_FIX, parseLaneHeader } from "../domain/lane.ts";
+import { checkEnv } from "../infra/env.ts";
+import { heavySlots, withHeavySlot } from "../infra/heavy-lock.ts";
+import { killGroup } from "../infra/proc.ts";
+import type { Deps } from "./ports.ts";
+import { TAIL_LINES } from "./run-debug.ts";
+import { findRun, type Run, runPaths } from "./run-store.ts";
+
+/** Spec §4.7. Only `cannot-start` blocks the run. */
+export type PreflightOutcome = "pass" | "fails-as-expected" | "skipped" | "cannot-start";
+
+interface PreflightResult {
+  lane: string;
+  check: string | null;
+  outcome: PreflightOutcome;
+  exitCode: number | null;
+  tail: string[];
+  note: string | null;
+}
+
+export type PreflightReport =
+  | { needsConfirmation: true; commands: { lane: string; check: string | null }[] }
+  | {
+      needsConfirmation: false;
+      commands: { lane: string; check: string | null }[];
+      results: PreflightResult[];
+      blocked: boolean;
+    };
+
+const CHECK_TIMEOUT_MS = 120_000;
+
+/** Whose uid preflight runs under; tests stand in for root with it. */
+export const preflightUser = { uid: (): number => process.getuid?.() ?? -1 };
+
+/**
+ * Spec §10.4: a lane's check never runs as root. A machine that says it is disposable (IS_SANDBOX, the
+ * rule claude itself applies to root) is the one exception.
+ */
+const refusesRoot = (): boolean => preflightUser.uid() === 0 && !process.env.IS_SANDBOX;
+const AS_ROOT =
+  "not run: catherd runs as root, and preflight never runs a lane's check as root (spec §10.4); run catherd as a normal user, or set IS_SANDBOX=1 on a disposable machine";
+
+interface LaneCheck {
+  lane: string;
+  check: string | null;
+  owns: string[];
+  problem: string | null;
+  /** spec 1.1 §6: why its Kind: or Difficulty: line is refused */
+  invalid: string | null;
+}
+
+function laneChecks(run: Run): LaneCheck[] {
+  const dir = runPaths(run.dir).lanes;
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((f) => f.endsWith(".md"))
+    .sort()
+    .map((f) => {
+      const lane = f.slice(0, -".md".length);
+      let invalid: string | null = null;
+      try {
+        const text = readFileSync(join(dir, f), "utf8");
+        try {
+          assertLaneHeader(text, `lanes/${f}`);
+        } catch (e) {
+          invalid = errorMessage(e);
+        }
+        const h = parseLaneHeader(text);
+        return {
+          lane,
+          check: h.fastCheck,
+          owns: h.owns,
+          problem: h.fastCheck ? null : `lanes/${f} has no Fast check: line`,
+          invalid,
+        };
+      } catch (e) {
+        return { lane, check: null, owns: [], problem: (e as Error).message, invalid };
+      }
+    });
+}
+
+/** How long the pipes may stay open after the check's own process exits. */
+export const DRAIN_MS = 500;
+
+/** Reads a pipe chunk by chunk, so what arrived is kept when the reading stops early. */
+export function collect(stream: ReadableStream<Uint8Array>): {
+  done: Promise<void>;
+  text: () => string;
+  stop: () => void;
+} {
+  const reader = stream.getReader();
+  const decoder = new TextDecoder();
+  let text = "";
+  const done = (async () => {
+    for (;;) {
+      const { value, done } = await reader.read();
+      if (done) return;
+      text += decoder.decode(value, { stream: true });
+    }
+  })().catch(() => {
+    // a pipe that breaks ends the reading; what arrived is kept
+  });
+  // cancelling a pipe that is already closed has nothing to report
+  return { done, text: () => text, stop: () => void reader.cancel().catch(() => {}) };
+}
+
+/**
+ * Runs `check` with `sh -c` in its own process group, with an allowlisted env (no credentials), killing the
+ * group on timeout. A process the check leaves behind (even in a new session) may hold the pipes open: once
+ * the check exits, the pipes get DRAIN_MS to close, then the reading stops with what arrived.
+ */
+export async function runCheck(
+  repo: string,
+  check: string,
+  timeoutMs: number,
+): Promise<{ code: number | null; timedOut: boolean; tail: string[] }> {
+  const p = Bun.spawn(["sh", "-c", check], {
+    cwd: repo,
+    env: checkEnv(process.env, repo),
+    stdin: "ignore",
+    stdout: "pipe",
+    stderr: "pipe",
+    detached: true,
+  });
+  let timedOut = false;
+  const timer = setTimeout(() => {
+    timedOut = true;
+    killGroup(p.pid, "SIGKILL");
+  }, timeoutMs);
+  const out = collect(p.stdout);
+  const err = collect(p.stderr);
+  try {
+    // the timeout kills the group, so the check's own process always exits
+    const code = await p.exited;
+    clearTimeout(timer); // the check is done: a slow drain is not a timeout
+    const drained = await Promise.race([
+      Promise.all([out.done, err.done]).then(() => true),
+      Bun.sleep(DRAIN_MS).then(() => false),
+    ]);
+    if (!drained) killGroup(p.pid, "SIGKILL"); // leftovers still in the check's group
+    const tail = `${out.text()}${err.text()}`
+      .split("\n")
+      .filter((l) => l.trim())
+      .slice(-TAIL_LINES);
+    return { code: timedOut ? null : code, timedOut, tail };
+  } finally {
+    clearTimeout(timer);
+    out.stop();
+    err.stop();
+  }
+}
+
+export function classify(r: { code: number | null; timedOut: boolean; tail: string[] }): PreflightOutcome {
+  if (r.timedOut || r.code === 126 || r.code === 127) return "cannot-start";
+  if (r.code === 0) return "pass";
+  return r.tail.some((l) => /command not found/i.test(l)) ? "cannot-start" : "fails-as-expected";
+}
+
+/**
+ * Spec §4.7: each lane's fast check once, on the base tree, behind the heavy lock. A check on a file the
+ * lane itself creates is skipped. With `profile.preflight.confirm`, the first call only lists the commands.
+ */
+export async function preflight(
+  deps: Deps,
+  i: { run: string; confirmed?: boolean; timeoutMs?: number },
+): Promise<PreflightReport> {
+  const run = findRun(i.run);
+  const profile = deps.profiles.forRepo(run.meta.repo);
+  const lanes = laneChecks(run);
+  // spec 1.1 §6: refuse before running anything, naming every lane whose header the catalog cannot route
+  const invalid = lanes.flatMap((l) => (l.invalid ? [l.invalid] : []));
+  if (invalid.length) throw new CatherdError("E_LANE_INVALID", invalid.join("; "), { fix: LANE_HEADER_FIX });
+  const commands = lanes.map((l) => ({ lane: l.lane, check: l.check }));
+  if (profile.preflight.confirm && !i.confirmed) return { needsConfirmation: true, commands };
+  const timeoutMs = i.timeoutMs ?? CHECK_TIMEOUT_MS;
+  const results: PreflightResult[] = [];
+  for (const l of lanes) {
+    const check = l.check;
+    if (!check) {
+      results.push({
+        lane: l.lane,
+        check,
+        outcome: "cannot-start",
+        exitCode: null,
+        tail: [],
+        note: l.problem,
+      });
+      continue;
+    }
+    if (refusesRoot()) {
+      results.push({ lane: l.lane, check, outcome: "skipped", exitCode: null, tail: [], note: AS_ROOT });
+      continue;
+    }
+    const unborn = l.owns.filter(
+      (p) => check.includes(p.replace(/\/$/, "")) && !existsSync(join(run.meta.repo, p)),
+    );
+    if (unborn.length) {
+      const note = `${unborn.join(", ")} does not exist yet; the lane creates it`;
+      results.push({ lane: l.lane, check, outcome: "skipped", exitCode: null, tail: [], note });
+      continue;
+    }
+    const r = await withHeavySlot(heavySlots(profile.heavy), () => runCheck(run.meta.repo, check, timeoutMs));
+    results.push({
+      lane: l.lane,
+      check,
+      outcome: classify(r),
+      exitCode: r.code,
+      tail: r.tail,
+      note: r.timedOut ? `timed out after ${timeoutMs / 1000} s` : null,
+    });
+  }
+  return {
+    needsConfirmation: false,
+    commands,
+    results,
+    blocked: results.some((r) => r.outcome === "cannot-start"),
+  };
+}

package/src/services/profile-service.ts

@@ -0,0 +1,292 @@
+import { existsSync, readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { CatherdError } from "../domain/errors.ts";
+import { parseRung } from "../domain/ids.ts";
+import {
+  agentName,
+  applyPatch,
+  assertProfileName,
+  type Change,
+  defaultProfileDoc,
+  diffProfiles,
+  type Profile,
+  type ProfileDoc,
+  type ProfilePatch,
+  resolveProfile,
+} from "../domain/profile.ts";
+import { type Validation, validateProfile } from "../domain/profile-rules.ts";
+import { ROLES } from "../domain/roles.ts";
+import { withFileLockSync } from "../infra/filelock.ts";
+import { configDir } from "../infra/paths.ts";
+import { ensurePrivateDir, writeJsonAtomic, writeTextAtomic } from "../infra/store.ts";
+import { apply, plan, type Synced } from "./agent-links.ts";
+import { loadCatalog } from "./catalog-service.ts";
+import type { ProfilePort, ProfileSaved, ProfileView } from "./ports.ts";
+import {
+  activeName,
+  configFile,
+  getProfile,
+  listProfiles,
+  profileExists,
+  profileFile,
+  profileFor,
+  projectsFile,
+  readConfig,
+  readProfileDoc,
+  readProjects,
+  requireProfile,
+  roleEnforcement,
+  runnableBackends,
+  validateNamed,
+} from "./profile-store.ts";
+
+// Spec §7.3, the single writer: one lock over profiles, config.json, projects.json, agent files and links.
+// Reads live in profile-store.ts, the agent files and links in agent-links.ts.
+
+/** The profiles lock every writer here takes; `init` moves 0.x files aside under it too. */
+export const withProfilesLock = <T>(fn: () => T): T => {
+  ensurePrivateDir(configDir());
+  return withFileLockSync(join(configDir(), "profiles"), fn);
+};
+const locked = withProfilesLock;
+
+const writeDoc = (name: string, doc: ProfileDoc) => writeJsonAtomic(profileFile(name), { ...doc, name });
+
+/** Writes `doc` as profile `name` and relinks; when the relink refuses, puts the profile back as it was. */
+function saveAndLink(name: string, doc: ProfileDoc): Synced {
+  const before = existsSync(profileFile(name)) ? readFileSync(profileFile(name), "utf8") : null;
+  writeDoc(name, doc);
+  try {
+    return apply(plan([name]));
+  } catch (e) {
+    if (before === null) rmSync(profileFile(name), { force: true });
+    else writeTextAtomic(profileFile(name), before);
+    throw e;
+  }
+}
+
+const validate = (doc: ProfileDoc, name: string): Validation =>
+  validateProfile(resolveProfile(doc, name), loadCatalog({ timings: false }), runnableBackends(), doc);
+
+/** What a save returns: the port's ProfileSaved (one type for the CLI, the TUI and the MCP tools). */
+export type Saved = ProfileSaved;
+
+const unsaved = (v: Validation): Saved => ({
+  saved: false,
+  ...v,
+  diff: [],
+  linked: [],
+  pruned: [],
+  newSessionNeededFor: [],
+});
+
+/** The issue path of a save refused because the profile is no longer the one its caller was shown. */
+export const CHANGED_ON_DISK = "profile";
+
+/**
+ * Spec §7.3 `patch` (profile_set, `catherd profile set`): validates first and writes nothing when invalid.
+ * A profile that does not exist yet starts from the default profile. With `expect` (the profile as a
+ * preview read it), it writes nothing when the profile under the lock is no longer that one: the patch
+ * would land on values the preview never showed.
+ */
+export function patchProfile(
+  name: string | undefined,
+  patch: ProfilePatch,
+  opts: { expect?: ProfileDoc } = {},
+): Saved {
+  return locked(() => {
+    const n = assertProfileName(name ?? activeName());
+    const before = profileExists(n) ? readProfileDoc(n) : defaultProfileDoc(n);
+    if (opts.expect !== undefined && !isDeepStrictEqual(before, opts.expect))
+      return unsaved({
+        errors: [
+          {
+            path: CHANGED_ON_DISK,
+            message: `profile "${n}" changed on disk since it was shown`,
+            fix: "check the changes and save again",
+          },
+        ],
+        warnings: [],
+      });
+    const after = applyPatch(before, patch);
+    const resolved = resolveProfile(after, n);
+    const v = validate(after, n);
+    if (v.errors.length) return unsaved(v);
+    const diff = diffProfiles(resolveProfile(before, n), resolved);
+    return { saved: true, ...v, diff, ...saveAndLink(n, after) };
+  });
+}
+
+/** Spec §7.3 `create` and `copy`: a new profile from `from` (default: the default profile). */
+export function createProfile(name: string, from?: string): Saved {
+  return locked(() => {
+    // `default` exists without a file: resetProfile is the only way to write it
+    if (profileExists(assertProfileName(name)))
+      throw new CatherdError("E_INPUT_INVALID", `profile "${name}" already exists`, {
+        fix: `pick another name, or edit it with catherd profile set --profile ${name}`,
+      });
+    if (from !== undefined && !profileExists(assertProfileName(from)))
+      throw new CatherdError("E_INPUT_INVALID", `no profile named "${from}" to copy`, {
+        fix: "catherd profile list",
+      });
+    const doc = from === undefined ? defaultProfileDoc(name) : readProfileDoc(from);
+    const v = validate(doc, name);
+    if (v.errors.length) return unsaved(v);
+    return { saved: true, ...v, diff: [], ...saveAndLink(name, doc) };
+  });
+}
+
+/** Writes the default profile under `name`, replacing what is there (`catherd init` when asked to). */
+export function resetProfile(name: string): Saved {
+  return locked(() => {
+    assertProfileName(name);
+    const doc = defaultProfileDoc(name);
+    const v = validate(doc, name);
+    if (v.errors.length) return unsaved(v);
+    return { saved: true, ...v, diff: [], ...saveAndLink(name, doc) };
+  });
+}
+
+/**
+ * Spec §7.3 `delete`: never the active profile or a repo-bound one; its agent files go with it. A binding
+ * whose repo no longer exists does not count: it is pruned with the profile.
+ */
+export function deleteProfile(name: string): Synced {
+  return locked(() => {
+    assertProfileName(name);
+    if (!existsSync(profileFile(name)))
+      throw new CatherdError("E_INPUT_INVALID", `profile "${name}" has no file to delete`, {
+        fix: "catherd profile list",
+      });
+    if (name === activeName())
+      throw new CatherdError("E_INPUT_INVALID", `"${name}" is the active profile`, {
+        fix: "make another profile active first: catherd profile use <name>",
+      });
+    const projects = readProjects();
+    const mine = Object.keys(projects.bindings).filter((repo) => projects.bindings[repo] === name);
+    const bound = mine.filter((repo) => existsSync(repo));
+    if (bound.length)
+      throw new CatherdError("E_INPUT_INVALID", `"${name}" is bound to ${bound.join(", ")}`, {
+        fix: "run catherd profile use --repo --clear (or use <name> --repo) inside each of those repos",
+      });
+    const text = readFileSync(profileFile(name), "utf8");
+    rmSync(profileFile(name), { force: true });
+    const gone = new Set(mine);
+    if (gone.size)
+      writeJsonAtomic(projectsFile(), {
+        ...projects,
+        bindings: Object.fromEntries(Object.entries(projects.bindings).filter(([r]) => !gone.has(r))),
+      });
+    try {
+      return apply(plan(), [name]);
+    } catch (e) {
+      writeTextAtomic(profileFile(name), text);
+      if (gone.size) writeJsonAtomic(projectsFile(), projects);
+      throw e;
+    }
+  });
+}
+
+/** Spec §7.3 `activate(name, repo?)`: the active profile, or the one bound to a repo; relinks the agents. */
+export function activate(
+  name: string,
+  repo: string | null = null,
+): Synced & { active: string; repo: string | null } {
+  return locked(() => {
+    assertProfileName(name);
+    if (!profileExists(name))
+      throw new CatherdError("E_INPUT_INVALID", `no profile named "${name}"`, {
+        fix: "catherd profile list",
+      });
+    const config = readConfig();
+    const projects = readProjects();
+    const write = () =>
+      repo === null
+        ? writeJsonAtomic(configFile(), { ...config, schema: 1, activeProfile: name })
+        : writeJsonAtomic(projectsFile(), {
+            ...projects,
+            schema: 1,
+            bindings: { ...projects.bindings, [repo]: name },
+          });
+    write();
+    try {
+      return { active: name, repo, ...apply(plan([name])) };
+    } catch (e) {
+      if (repo === null) writeJsonAtomic(configFile(), config);
+      else writeJsonAtomic(projectsFile(), projects);
+      throw e;
+    }
+  });
+}
+
+/** `catherd profile use --repo --clear`: removes `repo`'s binding, so it runs on the active profile again. */
+export function unbind(repo: string): Synced & { repo: string; was: string } {
+  return locked(() => {
+    const projects = readProjects();
+    const was = projects.bindings[repo];
+    if (was === undefined)
+      throw new CatherdError("E_INPUT_INVALID", `${repo} is bound to no profile`, {
+        fix: "catherd profile list shows the bound repos",
+      });
+    const bindings = { ...projects.bindings };
+    delete bindings[repo];
+    writeJsonAtomic(projectsFile(), { ...projects, schema: 1, bindings });
+    try {
+      return { repo, was, ...apply(plan()) };
+    } catch (e) {
+      writeJsonAtomic(projectsFile(), projects);
+      throw e;
+    }
+  });
+}
+
+export function diffNamed(a: string, b: string): Change[] {
+  return diffProfiles(getProfile(a), getProfile(b));
+}
+
+function viewOf(p: Profile): ProfileView {
+  const roles: ProfileView["roles"] = {};
+  for (const role of ROLES) roles[role] = { ...p.roles[role], rungs: [...p.roles[role].rungs] };
+  return {
+    name: p.name,
+    objective: p.objective,
+    roles,
+    billing: p.billing,
+    jev: p.jev,
+    isolated: Object.fromEntries(Object.entries(p.harness).map(([k, h]) => [k, h.isolated])),
+    failover: p.failover,
+    budget: p.budget,
+    timeouts: p.timeouts,
+    preflight: p.preflight,
+    heavy: p.lock.heavy,
+    notify: p.notify,
+  };
+}
+
+/** The ProfilePort the run engine and the MCP tools use (spec §7.3: the single writer). */
+export function profileService(): ProfilePort {
+  // without a name, each tool acts on the profile `repo` runs on (the active one outside a repo)
+  return {
+    forRepo: (repo) => viewOf(profileFor(repo)),
+    get(name, repo = null) {
+      const here = activeName(repo);
+      const p = getProfile(name === undefined ? here : requireProfile(name));
+      return {
+        active: activeName(),
+        here,
+        profiles: listProfiles(),
+        profile: viewOf(p),
+        enforcement: roleEnforcement(p),
+      };
+    },
+    validate(name, repo = null) {
+      const v = validateNamed(name === undefined ? activeName(repo) : requireProfile(name), repo);
+      return { valid: v.errors.length === 0, ...v };
+    },
+    // a name that does not exist yet starts from the default profile
+    set: (name, patch, repo = null) => patchProfile(name ?? activeName(repo), patch),
+    agentFor: (repo, role, rung) =>
+      parseRung(rung).backend === "claude" ? agentName(activeName(repo), role, rung) : null,
+  };
+}