catherd-cli 1.3.0 → 1.5.0

package/src/services/preflight.ts

@@ -1,16 +1,19 @@
 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 { assertLaneHeader, LANE_HEADER_FIX, onlyAllowedHits, parseLaneHeader } from "../domain/lane.ts";
 import { checkEnv } from "../infra/env.ts";
-import { heavySlots, withHeavySlot } from "../infra/heavy-lock.ts";
+import { heavySlots, withHeavySlotWithin } from "../infra/heavy-lock.ts";
+import { loginEnv } from "../infra/login-env.ts";
 import { killGroup } from "../infra/proc.ts";
+import { readGateEnv, resolveGateEnv } from "./gate-env.ts";
+import { landedMilestones } from "./milestones.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";
+/** Spec §4.7. Only `cannot-start` blocks the run; `lock-busy` (plan 23) means: run preflight again. */
+export type PreflightOutcome = "pass" | "fails-as-expected" | "skipped" | "cannot-start" | "lock-busy";
 
 interface PreflightResult {
   lane: string;
@@ -28,6 +31,8 @@ export type PreflightReport =
       commands: { lane: string; check: string | null }[];
       results: PreflightResult[];
       blocked: boolean;
+      /** plan 23: lanes whose fast check runs no linter while the repo has one */
+      warnings: string[];
     };
 
 const CHECK_TIMEOUT_MS = 120_000;
@@ -47,6 +52,8 @@ interface LaneCheck {
   lane: string;
   check: string | null;
   owns: string[];
+  /** spec 1.5: the Allow: exceptions of the lane's absence check */
+  allow: string[];
   problem: string | null;
   /** spec 1.1 §6: why its Kind: or Difficulty: line is refused */
   invalid: string | null;
@@ -73,15 +80,19 @@ function laneChecks(run: Run): LaneCheck[] {
           lane,
           check: h.fastCheck,
           owns: h.owns,
+          allow: h.allow,
           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 };
+        return { lane, check: null, owns: [], allow: [], problem: (e as Error).message, invalid };
       }
     });
 }
 
+/** How many output lines a check's Allow: exceptions are matched against; past it, the check fails as before. */
+const ALLOW_LINES = 1_000;
+
 /** How long the pipes may stay open after the check's own process exits. */
 export const DRAIN_MS = 500;
 
@@ -116,10 +127,11 @@ export async function runCheck(
   repo: string,
   check: string,
   timeoutMs: number,
-): Promise<{ code: number | null; timedOut: boolean; tail: string[] }> {
+  env: Record<string, string> = checkEnv(process.env, repo),
+): Promise<{ code: number | null; timedOut: boolean; tail: string[]; lines: string[] }> {
   const p = Bun.spawn(["sh", "-c", check], {
     cwd: repo,
-    env: checkEnv(process.env, repo),
+    env,
     stdin: "ignore",
     stdout: "pipe",
     stderr: "pipe",
@@ -141,11 +153,10 @@ export async function runCheck(
       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 };
+    // every line, up to a bound, for a lane's Allow: exceptions; the tail is what the report shows
+    const all = `${out.text()}${err.text()}`.split("\n").filter((l) => l.trim());
+    const lines = all.length <= ALLOW_LINES ? all : [];
+    return { code: timedOut ? null : code, timedOut, tail: all.slice(-TAIL_LINES), lines };
   } finally {
     clearTimeout(timer);
     out.stop();
@@ -153,10 +164,100 @@ export async function runCheck(
   }
 }
 
-export function classify(r: { code: number | null; timedOut: boolean; tail: string[] }): PreflightOutcome {
+/**
+ * Plan 23: a check that failed on the machine, not on the code: no Docker (or none at DOCKER_HOST), no DNS, a
+ * permission the sandbox or the OS denied. Such a check cannot start; it never fails as expected.
+ */
+const ENVIRONMENT = [
+  /command not found/i,
+  /Cannot connect to the Docker daemon/i,
+  /rootless Docker not found/i,
+  /Could not find a valid Docker environment/i,
+  /docker\.sock: connect: no such file or directory/i,
+  /Temporary failure in name resolution|Could not resolve host|no such host|Name or service not known|nodename nor servname|getaddrinfo (ENOTFOUND|EAI_AGAIN)/i,
+  /permission denied|operation not permitted|\bEACCES\b|\bEPERM\b/i,
+];
+
+/** pnpm exits 0 on a `--filter` that matches no package: the lane creates it, so there is nothing to run yet. */
+const EMPTY_FILTER = /No projects matched the filters/i;
+
+/** The first tail line an ENVIRONMENT pattern matches, or null. */
+export const environmentLine = (tail: string[]): string | null =>
+  tail.find((l) => ENVIRONMENT.some((re) => re.test(l))) ?? null;
+
+/** One `pnpm … --filter …` command, nothing chained, piped or backgrounded beside it. */
+const SINGLE_PNPM_FILTER = /^\s*pnpm\s(?:[^;&|\n`$()<>]*\s)?(?:--filter|-F)(?:[\s=])[^;&|\n`$()<>]*$/;
+
+/**
+ * An unmatched pnpm filter is "skipped" only when it is provably the check's sole failure: the whole check
+ * exited 0, or the check is a single pnpm --filter command. In a compound check (`pnpm --filter new test;
+ * docker compose up`) a later command's failure decides.
+ */
+export function classify(
+  r: { code: number | null; timedOut: boolean; tail: string[] },
+  command?: string,
+): PreflightOutcome {
   if (r.timedOut || r.code === 126 || r.code === 127) return "cannot-start";
+  const soleFailure = r.code === 0 || (command !== undefined && SINGLE_PNPM_FILTER.test(command));
+  if (soleFailure && r.tail.some((l) => EMPTY_FILTER.test(l))) return "skipped";
   if (r.code === 0) return "pass";
-  return r.tail.some((l) => /command not found/i.test(l)) ? "cannot-start" : "fails-as-expected";
+  return environmentLine(r.tail) !== null ? "cannot-start" : "fails-as-expected";
+}
+
+/** Why a classified result says what it says, for its note. */
+function noteOf(
+  r: { code: number | null; timedOut: boolean; tail: string[] },
+  outcome: PreflightOutcome,
+  timeoutMs: number,
+): string | null {
+  if (r.timedOut) return `timed out after ${timeoutMs / 1000} s`;
+  if (outcome === "skipped") return "the pnpm filter matches no package yet; the lane creates it";
+  const env = outcome === "cannot-start" ? environmentLine(r.tail) : null;
+  return env ? `environment: ${env.trim()}` : null;
+}
+
+/** How long one check waits for a heavy slot before it reports lock-busy; tests shorten it. */
+export const preflightLimits = { lockWaitMs: 60_000 };
+
+/**
+ * Plan 23: a check runs in the user's login environment (DOCKER_HOST and the rest a login shell sets), through
+ * the allowlist, plus the repo's gate environment. A login PATH comes first, with the server's own after it.
+ */
+export async function checkEnvFor(repo: string): Promise<Record<string, string>> {
+  const login = loginEnv();
+  const base: Record<string, string | undefined> = { ...process.env, ...login };
+  const path = [
+    ...new Set([...(login.PATH ?? "").split(":"), ...(process.env.PATH ?? "").split(":")].filter(Boolean)),
+  ];
+  if (path.length) base.PATH = path.join(":");
+  return { ...checkEnv(base, repo), ...resolveGateEnv(await readGateEnv(repo), base).env };
+}
+
+/** What a fast check names when it lints: a lint script, or a linter by name. */
+const LINT_STEP = /\b(lint|eslint|biome|oxlint|golangci-lint|ruff|clippy|vet|check)\b/i;
+
+/** Root files that say the repo has a linter, by the linter they configure. */
+const LINT_CONFIGS: [RegExp, string][] = [
+  [/^\.golangci\.(ya?ml|toml|json)$/, "golangci-lint"],
+  [/^(biome\.jsonc?)$/, "biome"],
+  [/^(eslint\.config\.[cm]?[jt]s|\.eslintrc(\.[a-z]+)?)$/, "eslint"],
+  [/^\.?oxlintrc\.json$/, "oxlint"],
+  [/^\.?ruff\.toml$/, "ruff"],
+];
+
+/** The linter the repo has, by name, or null: a root lint config, or a `lint` script in package.json. */
+export function repoLinter(repo: string): string | null {
+  for (const name of existsSync(repo) ? readdirSync(repo) : [])
+    for (const [re, linter] of LINT_CONFIGS) if (re.test(name)) return linter;
+  try {
+    const pkg = JSON.parse(readFileSync(join(repo, "package.json"), "utf8")) as {
+      scripts?: Record<string, unknown>;
+    };
+    if (typeof pkg.scripts?.lint === "string") return "the lint script";
+  } catch {
+    // no package.json, or one that does not parse: no lint script
+  }
+  return null;
 }
 
 /**
@@ -165,11 +266,16 @@ export function classify(r: { code: number | null; timedOut: boolean; tail: stri
  */
 export async function preflight(
   deps: Deps,
-  i: { run: string; confirmed?: boolean; timeoutMs?: number },
+  i: { run: string; confirmed?: boolean; timeoutMs?: number; milestone?: string },
 ): Promise<PreflightReport> {
   const run = findRun(i.run);
   const profile = deps.profiles.forRepo(run.meta.repo);
-  const lanes = laneChecks(run);
+  // plan 23: one milestone's lanes, or by default every lane whose milestone has not landed
+  const landed = new Set(landedMilestones(run));
+  const milestoneOf = (lane: string) => lane.split(".")[0] as string;
+  const lanes = laneChecks(run).filter((l) =>
+    i.milestone ? milestoneOf(l.lane) === i.milestone : !landed.has(milestoneOf(l.lane)),
+  );
   // 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 });
@@ -177,6 +283,8 @@ export async function preflight(
   if (profile.preflight.confirm && !i.confirmed) return { needsConfirmation: true, commands };
   const timeoutMs = i.timeoutMs ?? CHECK_TIMEOUT_MS;
   const results: PreflightResult[] = [];
+  // the login env is captured once per server; the gate env is read once per preflight
+  let env: Record<string, string> | undefined;
   for (const l of lanes) {
     const check = l.check;
     if (!check) {
@@ -202,20 +310,46 @@ export async function preflight(
       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));
+    env ??= await checkEnvFor(run.meta.repo);
+    const checkEnvironment = env;
+    // plan 23: each check waits for its slot within its own budget, and says lock-busy past it
+    const slot = await withHeavySlotWithin(heavySlots(profile.heavy), preflightLimits.lockWaitMs, () =>
+      runCheck(run.meta.repo, check, timeoutMs, checkEnvironment),
+    );
+    if (slot.busy) {
+      const note = `every heavy slot stayed busy for ${preflightLimits.lockWaitMs / 1000} s (other lanes' checks); run preflight again when they finish`;
+      results.push({ lane: l.lane, check, outcome: "lock-busy", exitCode: null, tail: [], note });
+      continue;
+    }
+    const r = slot.value;
+    // spec 1.5: an absence check whose every hit is one of the lane's Allow: exceptions has passed
+    const classified = classify(r, check);
+    const allowed = classified === "fails-as-expected" && onlyAllowedHits(r.lines, l.allow);
+    const outcome = allowed ? "pass" : classified;
     results.push({
       lane: l.lane,
       check,
-      outcome: classify(r),
+      outcome,
       exitCode: r.code,
       tail: r.tail,
-      note: r.timedOut ? `timed out after ${timeoutMs / 1000} s` : null,
+      note: allowed ? `every hit is an Allow: exception (${r.lines.length})` : noteOf(r, outcome, timeoutMs),
     });
   }
+  // plan 23: lint reaches the worker only through its fast check
+  const linter = repoLinter(run.meta.repo);
+  const warnings = linter
+    ? lanes
+        .filter((l) => l.check && !LINT_STEP.test(l.check))
+        .map(
+          (l) =>
+            `${l.lane}: its fast check runs no linter, and the repo has one (${linter}): add the linter of every package the lane touches to its Fast check: line`,
+        )
+    : [];
   return {
     needsConfirmation: false,
     commands,
     results,
     blocked: results.some((r) => r.outcome === "cannot-start"),
+    warnings,
   };
 }

package/src/services/profile-service.ts

@@ -1,3 +1,5 @@
+import type { HostContext, OrchestrationHost } from "../domain/host.ts";
+import { agentFiles } from "../domain/agents.ts";
 import { existsSync, readFileSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { isDeepStrictEqual } from "node:util";
@@ -9,18 +11,19 @@ import {
   assertProfileName,
   type Change,
   defaultProfileDoc,
+  hostDefaultsDoc,
   diffProfiles,
   type Profile,
   type ProfileDoc,
   type ProfilePatch,
   resolveProfile,
 } from "../domain/profile.ts";
-import { repairs, type Validation } from "../domain/profile-rules.ts";
+import { nativeClaudeIssue, repairs, type Validation } 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 { apply, plan, pruneProfileAgents, type Synced } from "./agent-links.ts";
 import { loadCatalog } from "./catalog-service.ts";
 import type { ProfilePort, ProfileSaved, ProfileView } from "./ports.ts";
 import {
@@ -54,11 +57,18 @@ 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 {
+/** `repairing`: a saved repair with errors still open, whose remaining native roles are among those errors. */
+function saveAndLink(name: string, doc: ProfileDoc, host: OrchestrationHost, repairing = false): Synced {
   const before = existsSync(profileFile(name)) ? readFileSync(profileFile(name), "utf8") : null;
+  const nativeOn = (h: OrchestrationHost) => agentFiles(getProfile(name, h), "").length > 0;
+  const hadNative = before !== null && nativeOn(host);
+  // omitted defaults are native only on claude-code: the artifacts that resolution made count too
+  const hadClaudeNative = before !== null && host !== "claude-code" && nativeOn("claude-code");
   writeDoc(name, doc);
   try {
-    return apply(plan([name]));
+    // a profile left with no native role on any host owns no agents; one still native there keeps them
+    const allowPrune = host === "claude-code" || hadNative || (hadClaudeNative && !nativeOn("claude-code"));
+    return syncFor(name, host, [name], allowPrune, repairing);
   } catch (e) {
     if (before === null) rmSync(profileFile(name), { force: true });
     else writeTextAtomic(profileFile(name), before);
@@ -66,8 +76,34 @@ function saveAndLink(name: string, doc: ProfileDoc): Synced {
   }
 }
 
-const validate = (doc: ProfileDoc, name: string): Validation =>
-  validateHere(resolveProfile(doc, name), loadCatalog({ timings: false }), doc);
+const validate = (doc: ProfileDoc, name: string, host: OrchestrationHost): Validation => {
+  try {
+    return validateHere(resolveProfile(doc, name, host), loadCatalog({ timings: false }), doc, host);
+  } catch (e) {
+    if (!(e instanceof CatherdError)) throw e;
+    return { errors: [{ path: "roles", message: e.message, fix: e.fix }], warnings: [] };
+  }
+};
+function nativeAgents(name: string, host: OrchestrationHost) {
+  const files = agentFiles(getProfile(name, host), "");
+  const first = files[0];
+  const issue = first && nativeClaudeIssue(first.rung, host, `roles.${first.role}.rungs`);
+  if (issue) throw new CatherdError("E_CONFIG_INVALID", issue.message, { fix: issue.fix });
+  return files;
+}
+function syncFor(
+  name: string,
+  host: OrchestrationHost,
+  extra: string[] = [],
+  allowPrune = host === "claude-code",
+  repairing = false,
+): Synced {
+  // a partial repair keeps its open native-role errors: link and prune nothing until they are fixed
+  if (repairing && agentFiles(getProfile(name, host), "").some((f) => nativeClaudeIssue(f.rung, host, "")))
+    return { linked: [], pruned: [], newSessionNeededFor: [] };
+  if (nativeAgents(name, host).length) return apply(plan(host, extra));
+  return allowPrune ? pruneProfileAgents(name) : { linked: [], pruned: [], newSessionNeededFor: [] };
+}
 
 /** What a save returns: the port's ProfileSaved (one type for the CLI, the TUI and the MCP tools). */
 export type Saved = ProfileSaved;
@@ -95,7 +131,7 @@ export const CHANGED_ON_DISK = "profile";
 export function patchProfile(
   name: string | undefined,
   patch: ProfilePatch,
-  opts: { expect?: ProfileDoc } = {},
+  opts: { host: OrchestrationHost; expect?: ProfileDoc },
 ): Saved {
   return locked(() => {
     const n = assertProfileName(name ?? activeName());
@@ -111,17 +147,18 @@ export function patchProfile(
         ],
         warnings: [],
       });
+    const host = opts.host;
     const after = applyPatch(before, patch);
-    const resolved = resolveProfile(after, n);
-    const v = validate(after, n);
-    if (v.errors.length && !repairs(profileExists(n) ? validate(before, n) : null, v)) return unsaved(v);
-    const diff = diffProfiles(resolveProfile(before, n), resolved);
-    return { saved: true, ...v, diff, ...saveAndLink(n, after) };
+    const v = validate(after, n, host);
+    if (v.errors.length && !repairs(profileExists(n) ? validate(before, n, host) : null, v))
+      return unsaved(v);
+    const diff = diffProfiles(resolveProfile(before, n, host), resolveProfile(after, n, host));
+    return { saved: true, ...v, diff, ...saveAndLink(n, after, host, v.errors.length > 0) };
   });
 }
 
 /** Spec §7.3 `create` and `copy`: a new profile from `from` (default: the default profile). */
-export function createProfile(name: string, from?: string): Saved {
+export function createProfile(name: string, from: string | undefined, host: OrchestrationHost): Saved {
   return locked(() => {
     // `default` exists without a file: resetProfile is the only way to write it
     if (profileExists(assertProfileName(name)))
@@ -133,20 +170,20 @@ export function createProfile(name: string, from?: string): Saved {
         fix: "catherd profile list",
       });
     const doc = from === undefined ? defaultProfileDoc(name) : readProfileDoc(from);
-    const v = validate(doc, name);
+    const v = validate(doc, name, host);
     if (v.errors.length) return unsaved(v);
-    return { saved: true, ...v, diff: [], ...saveAndLink(name, doc) };
+    return { saved: true, ...v, diff: [], ...saveAndLink(name, doc, host) };
   });
 }
 
 /** Writes the default profile under `name`, replacing what is there (`catherd init` when asked to). */
-export function resetProfile(name: string): Saved {
+export function resetProfile(name: string, host: OrchestrationHost): Saved {
   return locked(() => {
     assertProfileName(name);
     const doc = defaultProfileDoc(name);
-    const v = validate(doc, name);
+    const v = validate(doc, name, host);
     if (v.errors.length) return unsaved(v);
-    return { saved: true, ...v, diff: [], ...saveAndLink(name, doc) };
+    return { saved: true, ...v, diff: [], ...saveAndLink(name, doc, host) };
   });
 }
 
@@ -181,7 +218,7 @@ export function deleteProfile(name: string): Synced {
         bindings: Object.fromEntries(Object.entries(projects.bindings).filter(([r]) => !gone.has(r))),
       });
     try {
-      return apply(plan(), [name]);
+      return pruneProfileAgents(name);
     } catch (e) {
       writeTextAtomic(profileFile(name), text);
       if (gone.size) writeJsonAtomic(projectsFile(), projects);
@@ -193,7 +230,8 @@ export function deleteProfile(name: string): Synced {
 /** 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,
+  repo: string | null,
+  host: OrchestrationHost,
 ): Synced & { active: string; repo: string | null } {
   return locked(() => {
     assertProfileName(name);
@@ -201,6 +239,7 @@ export function activate(
       throw new CatherdError("E_INPUT_INVALID", `no profile named "${name}"`, {
         fix: "catherd profile list",
       });
+    nativeAgents(name, host);
     const config = readConfig();
     const projects = readProjects();
     const write = () =>
@@ -213,7 +252,7 @@ export function activate(
           });
     write();
     try {
-      return { active: name, repo, ...apply(plan([name])) };
+      return { active: name, repo, ...syncFor(name, host, [name]) };
     } catch (e) {
       if (repo === null) writeJsonAtomic(configFile(), config);
       else writeJsonAtomic(projectsFile(), projects);
@@ -223,7 +262,7 @@ export function activate(
 }
 
 /** `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 } {
+export function unbind(repo: string, host: OrchestrationHost): Synced & { repo: string; was: string } {
   return locked(() => {
     const projects = readProjects();
     const was = projects.bindings[repo];
@@ -235,7 +274,11 @@ export function unbind(repo: string): Synced & { repo: string; was: string } {
     delete bindings[repo];
     writeJsonAtomic(projectsFile(), { ...projects, schema: 1, bindings });
     try {
-      return { repo, was, ...apply(plan()) };
+      // a binding to a deleted profile is what doctor sends here to clear: there is nothing of it to relink
+      const synced = profileExists(was)
+        ? syncFor(was, host)
+        : { linked: [], pruned: [], newSessionNeededFor: [] };
+      return { repo, was, ...synced };
     } catch (e) {
       writeJsonAtomic(projectsFile(), projects);
       throw e;
@@ -243,8 +286,8 @@ export function unbind(repo: string): Synced & { repo: string; was: string } {
   });
 }
 
-export function diffNamed(a: string, b: string): Change[] {
-  return diffProfiles(getProfile(a), getProfile(b));
+export function diffNamed(a: string, b: string, host: OrchestrationHost): Change[] {
+  return diffProfiles(getProfile(a, host), getProfile(b, host));
 }
 
 function viewOf(p: Profile): ProfileView {
@@ -267,13 +310,16 @@ function viewOf(p: Profile): ProfileView {
 }
 
 /** The ProfilePort the run engine and the MCP tools use (spec §7.3: the single writer). */
-export function profileService(): ProfilePort {
+export function profileService(host: () => HostContext): 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)),
+    withHost: profileService,
+    raw: (name, repo = null) => readProfileDoc(name ?? activeName(repo)),
+    budgetFor: (repo) => readProfileDoc(activeName(repo)).budget ?? {},
+    forRepo: (repo) => viewOf(profileFor(repo, host().host)),
     get(name, repo = null) {
       const here = activeName(repo);
-      const p = getProfile(name === undefined ? here : requireProfile(name));
+      const p = getProfile(name === undefined ? here : requireProfile(name), host().host);
       return {
         active: activeName(),
         here,
@@ -283,12 +329,53 @@ export function profileService(): ProfilePort {
       };
     },
     validate(name, repo = null) {
-      const v = validateNamed(name === undefined ? activeName(repo) : requireProfile(name), repo);
+      const v = validateNamed(
+        name === undefined ? activeName(repo) : requireProfile(name),
+        repo,
+        host().host,
+        { reach: true },
+      );
       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),
+    set: (name, patch, repo = null) => patchProfile(name ?? activeName(repo), patch, { host: host().host }),
     agentFor: (repo, role, rung) =>
       parseRung(rung).backend === "claude" ? agentName(activeName(repo), role, rung) : null,
   };
 }
+
+export function resetHostDefaults(
+  name: string,
+  host: OrchestrationHost,
+  opts:
+    | { preview: true; expect?: ProfileDoc }
+    | { preview: false; expect: ProfileDoc; reviewed: { profile: string; host: OrchestrationHost } },
+): Saved & { expect: ProfileDoc; profile: string; host: OrchestrationHost } {
+  return locked(() => {
+    const refuse = (message: string, expect: ProfileDoc) => ({
+      ...unsaved({
+        errors: [{ path: CHANGED_ON_DISK, message, fix: "preview again and review the changes" }],
+        warnings: [],
+      }),
+      expect,
+      profile: name,
+      host,
+    });
+    // the reset is host-specific: a preview approves one profile on one host, never another
+    if (!opts.preview && (opts.reviewed.profile !== name || opts.reviewed.host !== host))
+      return refuse(
+        `the preview was for profile "${opts.reviewed.profile}" on host ${opts.reviewed.host}, not "${name}" on ${host}`,
+        opts.expect,
+      );
+    const before = readProfileDoc(name);
+    if (!opts.preview && !isDeepStrictEqual(before, opts.expect))
+      return refuse(`profile "${name}" changed on disk since it was shown`, before);
+    const after = hostDefaultsDoc(before);
+    const v = validate(after, name, host);
+    if (v.errors.length) return { ...unsaved(v), expect: before, profile: name, host };
+    const diff = diffProfiles(resolveProfile(before, name, host), resolveProfile(after, name, host));
+    return opts.preview
+      ? { ...unsaved(v), diff, expect: before, profile: name, host }
+      : { saved: true, ...v, diff, ...saveAndLink(name, after, host), expect: before, profile: name, host };
+  });
+}

package/src/services/profile-store.ts

@@ -1,3 +1,4 @@
+import type { OrchestrationHost } from "../domain/host.ts";
 import { existsSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { z } from "zod";
@@ -14,7 +15,12 @@ import {
   ProfileDocSchema,
   resolveProfile,
 } from "../domain/profile.ts";
-import { type Issue, type Validation, validateProfile } from "../domain/profile-rules.ts";
+import {
+  type Issue,
+  type ValidateOptions,
+  type Validation,
+  validateProfile,
+} from "../domain/profile-rules.ts";
 import type { Catalog } from "../domain/catalog.ts";
 import type { Access } from "../domain/record.ts";
 import { ROLES, type Role } from "../domain/roles.ts";
@@ -94,7 +100,8 @@ export function readProfileDoc(name: string): ProfileDoc {
   throw new CatherdError("E_CONFIG_INVALID", `no profile named "${name}"`, { fix: "catherd profile list" });
 }
 
-export const getProfile = (name: string): Profile => resolveProfile(readProfileDoc(name), name);
+export const getProfile = (name: string, host: OrchestrationHost): Profile =>
+  resolveProfile(readProfileDoc(name), name, host);
 
 /** A profile name the user typed: refused as bad input (exit 2) when no such profile exists. */
 export function requireProfile(name: string): string {
@@ -109,7 +116,8 @@ export function activeName(repo: string | null = null): string {
   return bound ?? readConfig().activeProfile ?? "default";
 }
 
-export const profileFor = (repo: string | null): Profile => getProfile(activeName(repo));
+export const profileFor = (repo: string | null, host: OrchestrationHost): Profile =>
+  getProfile(activeName(repo), host);
 
 /** The backends catherd can run: every registered adapter, and the native `claude` path. */
 export const runnableBackends = (): string[] => ["claude", ...ADAPTER_IDS.filter((id) => adapterFor(id))];
@@ -212,8 +220,14 @@ export function budgetUsdWarnings(p: Profile): Issue[] {
  * Spec §7.1 validation on this machine: the backends catherd can run here, the keys isolation needs, the
  * accesses a backend holds only when isolated, and the backends a dollar budget cannot see.
  */
-export function validateHere(p: Profile, c: Catalog, doc?: ProfileDoc): Validation {
-  const v = validateProfile(p, c, runnableBackends(), doc);
+export function validateHere(
+  p: Profile,
+  c: Catalog,
+  doc?: ProfileDoc,
+  host: OrchestrationHost = "unknown",
+  o: ValidateOptions = {},
+): Validation {
+  const v = validateProfile(p, c, runnableBackends(), doc, host, o);
   return {
     errors: [...v.errors, ...isolationKeyErrors(p), ...isolatedOnlyErrors(p)],
     warnings: [...v.warnings, ...budgetUsdWarnings(p)],
@@ -221,11 +235,21 @@ export function validateHere(p: Profile, c: Catalog, doc?: ProfileDoc): Validati
 }
 
 /** `repo`: the git toplevel whose listing route reads (opencode lists its models per repository). */
-export function validateNamed(name?: string, repo: string | null = null): Validation {
+export function validateNamed(
+  name: string | undefined,
+  repo: string | null,
+  host: OrchestrationHost,
+  o: ValidateOptions = {},
+): Validation {
   const n = name ?? activeName(repo);
   const doc = readProfileDoc(n);
   const catalog = loadCatalog({ timings: false, ...(repo === null ? {} : { repo }) });
-  return validateHere(resolveProfile(doc, n), catalog, doc);
+  try {
+    return validateHere(resolveProfile(doc, n, host), catalog, doc, host, o);
+  } catch (e) {
+    if (!(e instanceof CatherdError)) throw e;
+    return { errors: [{ path: "roles", message: e.message, fix: e.fix }], warnings: [] };
+  }
 }
 
 /** Spec D10: how strongly the backend holds a role to its access mode. */