omp-conductor 0.3.25 → 0.4.0

package/src/config.ts

@@ -17,21 +17,36 @@ import { homedir } from "node:os";
 import { dirname, isAbsolute, join } from "node:path";
 import {
   AUTHORITY_HOLDERS,
+  BASE_FRESHNESS,
+  BEHIND_BASE_ACTIONS,
   CONFIG_VERSION,
+  CREDENTIAL_ISOLATIONS,
   DEFAULT_AUTHORITY,
   DEFAULT_CAPS,
-  DEFAULT_RELEASE_POLICY,
+  DEFAULT_PROJECT_POLICY,
   DEFAULT_REPORT_SCOPE,
+  DENIED_RELEASE_GRANTS,
+  DRAFT_POLICIES,
+  LEGACY_RELEASE_POLICIES,
+  OPERATOR_BRIEF_GRANTS,
   ORCHESTRATOR_MODES,
   READABLE_CONFIG_VERSIONS,
-  RELEASE_POLICIES,
+  RELEASE_REQUIREMENTS,
+  RELEASE_SHAPES,
   REPORT_SCOPES,
   type Caps,
   type ConductorConfig,
+  type CredentialConfig,
+  type CredentialIsolation,
+  type MergePreconditions,
+  type PlanUsageCap,
   type ProjectConfig,
+  type ProjectPolicy,
+  type ReleasePreconditions,
+  type ReleaseRequirement,
   type ReportScope,
-  type ReleasePolicy,
   type RepoTarget,
+  type ResolvedGrants,
 } from "./types.ts";
 
 /**
@@ -53,6 +68,13 @@ const CAP_KEYS = Object.keys(DEFAULT_CAPS) as (keyof Caps)[];
 const REPORT_SCOPE_LIST = quoteList(REPORT_SCOPES);
 const AUTHORITY_HOLDER_LIST = quoteList(AUTHORITY_HOLDERS);
 const ORCHESTRATOR_MODE_LIST = quoteList(ORCHESTRATOR_MODES);
+const RELEASE_SHAPE_LIST = quoteList(RELEASE_SHAPES);
+const LEGACY_RELEASE_POLICY_LIST = quoteList(LEGACY_RELEASE_POLICIES);
+const CREDENTIAL_ISOLATION_LIST = quoteList(CREDENTIAL_ISOLATIONS);
+const BASE_FRESHNESS_LIST = quoteList(BASE_FRESHNESS);
+const DRAFT_POLICY_LIST = quoteList(DRAFT_POLICIES);
+const BEHIND_BASE_ACTION_LIST = quoteList(BEHIND_BASE_ACTIONS);
+const RELEASE_REQUIREMENT_LIST = quoteList(RELEASE_REQUIREMENTS);
 
 /** `owner/repo`, the only tracker spelling `gh` accepts without a host. */
 const REPO_RE = /^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/;
@@ -85,6 +107,82 @@ export function stateDir(): string {
   return dirname(configPath());
 }
 
+/**
+ * Root of everything a run principal must reach: worktrees, mirrors, per-run
+ * session transcripts and per-run boundary homes.
+ *
+ * **Outside the daemon's home, not a sibling of the state directory**, and both
+ * halves of that are load-bearing:
+ *
+ * - It cannot live *inside* {@link stateDir}, which stays `0700` because it
+ *   holds `config.json`, `conductor.db` and the WAL/SHM files SQLite recreates
+ *   at runtime with the process umask. Making it searchable — all a slot needs
+ *   — would publish fleet, run and report history to every local account, and
+ *   chmod-ing the leaves once would not hold.
+ * - It cannot live under the daemon's **home** either, which the boundary
+ *   requires to be `0700` so a slot cannot reach `gh` config, `~/.ssh` or
+ *   `~/.npmrc`. A shared root at `~/.omp/conductor-shared` is unreachable for
+ *   exactly the same reason, and the two hardening steps would silently cancel
+ *   each other out — the boundary would look correct and no run could start.
+ *
+ * So it is a system path: `0711` — traversable by a slot that already knows its
+ * own path, listable by nobody, writable by nobody but the daemon. Only used
+ * when a per-run boundary is active; an `isolation: "none"` fleet keeps every
+ * path exactly where it was (#125).
+ *
+ * `$OMP_CONDUCTOR_SHARED` overrides it, which is how tests and non-FHS hosts
+ * relocate it. Uninstall is two paths instead of one, and the README says so.
+ */
+export function sharedRoot(): string {
+  const override = process.env["OMP_CONDUCTOR_SHARED"];
+  if (override !== undefined && override.length > 0) return expandHome(override);
+  // Deliberately NOT derived from whether `$OMP_CONDUCTOR_HOME` happens to be
+  // set: generated systemd units set it even for a default install, so keying
+  // the security topology off it lets the CLI, setup and the daemon each pick a
+  // different root depending on how they were invoked. One explicit override,
+  // or the platform default.
+  // Not `/tmp`: a shared root a slot could rename or replace would hand one run
+  // control of another's checkout path.
+  return process.platform === "linux" ? "/var/lib/omp-conductor" : `${stateDir()}-shared`;
+}
+
+/**
+ * Where per-run worktrees and bare mirrors live when a project names neither.
+ *
+ * Exported because two readers need the same answer: `normalizeProject` below,
+ * and the orchestrator jail (`confinement.ts`, #127), which must deny the
+ * worker checkouts even when the config was too broken to load and say where
+ * they are. Two copies of this default would mean a jail guarding the wrong
+ * directory on exactly the day the config is broken.
+ *
+ * `base` is what makes these usable under a per-run boundary. A slot principal
+ * cannot traverse the `0700` state directory, and dispatch now refuses rather
+ * than widening it — so an isolated fleet whose roots defaulted under the state
+ * dir would provision a repository and then fail before launching anything.
+ * Setup passes {@link sharedRoot} for those fleets and `stateDir()` for the
+ * rest, so an `isolation: "none"` install keeps every path exactly where it was
+ * (#125).
+ */
+export function defaultWorkspaceRoot(base: string = stateDir()): string {
+  return join(base, "worktrees");
+}
+
+export function defaultMirrorRoot(base: string = stateDir()): string {
+  return join(base, "mirrors");
+}
+/**
+ * The root a project's slot-accessible trees belong under, given its isolation.
+ *
+ * Only `per-run` moves. `group-mode` runs sessions as the daemon's *own* uid —
+ * it separates checkouts by group and mode, not by principal — so it can reach
+ * the state directory perfectly well, and sending it to a system path would
+ * demand privileged provisioning a group-mode host may deliberately not have.
+ * `none` never moves either.
+ */
+export function projectTreeBase(isolation: CredentialIsolation): string {
+  return isolation === "per-run" ? sharedRoot() : stateDir();
+}
+
 /**
  * Reads, validates and normalises the config. Throws an `Error` naming the
  * path and the fix; never returns a partially-shaped `ConductorConfig`.
@@ -149,6 +247,7 @@ export function resolveCaps(p: ProjectConfig, defaults: Caps): Caps {
   return {
     maxConcurrentWorkers: o.maxConcurrentWorkers ?? defaults.maxConcurrentWorkers,
     dailySpendUsd: o.dailySpendUsd !== undefined ? o.dailySpendUsd : defaults.dailySpendUsd,
+    planUsage: o.planUsage !== undefined ? o.planUsage : defaults.planUsage,
     workerMaxTurns: o.workerMaxTurns ?? defaults.workerMaxTurns,
     workerWallClockMs: o.workerWallClockMs ?? defaults.workerWallClockMs,
     maxAttemptsPerIssue: o.maxAttemptsPerIssue ?? defaults.maxAttemptsPerIssue,
@@ -157,9 +256,83 @@ export function resolveCaps(p: ProjectConfig, defaults: Caps): Caps {
   };
 }
 
-/** Old configs and omitted keys are fail-closed at the enforcement boundary. */
-export function resolveReleasePolicy(p: ProjectConfig): ReleasePolicy {
-  return p.releasePolicy ?? DEFAULT_RELEASE_POLICY;
+/**
+ * The effective grant for every shape. Old configs, an omitted key and a
+ * hand-written partial map are all fail-closed here: a shape the map does not
+ * name is denied, never inherited from a neighbour and never opened.
+ *
+ * `loadConfig` has already migrated what it read, so for a loaded project this
+ * is a copy. It stays because a `ProjectConfig` also reaches the gate from
+ * `buildProject` and from tests, and #122's point is that "absent means denied"
+ * has exactly one spelling in the package.
+ */
+export function resolveReleaseGrants(p: ProjectConfig): ResolvedGrants {
+  const policy = p.releasePolicy;
+  if (policy === undefined || policy === "none") return { ...DENIED_RELEASE_GRANTS };
+
+  const grants = { ...DENIED_RELEASE_GRANTS };
+  for (const shape of RELEASE_SHAPES) {
+    const holder = policy[shape];
+    if (holder !== undefined) grants[shape] = holder;
+  }
+  return grants;
+}
+
+/**
+ * The gating conditions for one project, complete (#129).
+ *
+ * The loader always writes a complete `policy`, so this is only ever the
+ * fallback for a `ProjectConfig` that never went through it — a hand-built one
+ * in a test, or a config written before the key existed. Spelled once here so a
+ * caller cannot invent a different answer for the absent case, which is exactly
+ * how "conditions live in typed config" degrades back into "conditions live
+ * wherever the reader looked".
+ */
+export function resolvePolicy(p: ProjectConfig): ProjectPolicy {
+  return clonePolicy(p.policy ?? DEFAULT_PROJECT_POLICY);
+}
+
+/**
+ * A policy with no array shared with its source.
+ *
+ * {@link DEFAULT_PROJECT_POLICY} is one object for the whole process, and every
+ * consumer of a resolved policy holds something it may hand to the wizard and
+ * back. A shared `requiredChecks` array would let one project's amend push a
+ * check onto every project that had never answered the question.
+ */
+export function clonePolicy(policy: ProjectPolicy): ProjectPolicy {
+  return {
+    merge: { ...policy.merge, requiredChecks: [...policy.merge.requiredChecks] },
+    release: {
+      ...policy.release,
+      requires: [...policy.release.requires],
+      requiredChecks: [...policy.release.requiredChecks],
+      artefacts: [...policy.release.artefacts],
+      environments: [...policy.release.environments],
+    },
+  };
+}
+
+/**
+ * The runtime twin of {@link pickLiteral}, for a value a *model* supplied rather
+ * than a value an operator wrote (#129).
+ *
+ * Throws rather than returning a flag: a verb's `reason` is the field the ledger
+ * records the act under, and a caller that forgets to check a boolean has
+ * written an unexplained act into the audit trail instead of refusing one. The
+ * message names every accepted value, because the reader is a session that can
+ * only correct itself from what the refusal tells it — "invalid reason" costs a
+ * turn and teaches nothing.
+ *
+ * Free-form rationale is not this function's business. It rides beside the
+ * reason as a `rationale` field, is logged verbatim, and is never matched.
+ */
+export function requireReason<R extends string>(value: unknown, allowed: readonly R[], field: string): R {
+  const hit = allowed.find((a) => a === value);
+  if (hit === undefined) {
+    throw new Error(`${field} must be ${quoteList(allowed)}, found ${JSON.stringify(value)}`);
+  }
+  return hit;
 }
 
 /**
@@ -282,14 +455,9 @@ function normalizeProject(
 
   const escalation = normalizeEscalation(raw["escalation"], label, problems);
   const authority = normalizeAuthority(raw["authority"], label, problems);
-  const releasePolicy = pickLiteral(
-    raw["releasePolicy"],
-    RELEASE_POLICIES,
-    DEFAULT_RELEASE_POLICY,
-    `${label}: releasePolicy`,
-    RELEASE_POLICIES.map((value) => JSON.stringify(value)).join(" or "),
-    problems,
-  );
+  const releasePolicy = normalizeReleasePolicy(raw["releasePolicy"], label, problems);
+  const credentials = normalizeCredentials(raw["credentials"], label, problems);
+  const policy = normalizeProjectPolicy(raw["policy"], label, problems);
 
   const caps = coerceCaps(raw["caps"], `${label}: caps`, problems, legacyCaps);
   const reporting = normalizeReporting(raw["reporting"], label, problems);
@@ -298,6 +466,11 @@ function normalizeProject(
   // (logged by `runWorker`) is what tells the operator the pattern missed.
   const rawWorkerModel = raw["workerModel"];
   const workerModel = nonEmptyString(rawWorkerModel) ? rawWorkerModel : undefined;
+  const orchestratorReadPaths = normalizeOrchestratorReadPaths(
+    raw["orchestratorReadPaths"],
+    label,
+    problems,
+  );
 
   if (problems.length > before) return undefined;
 
@@ -316,9 +489,20 @@ function normalizeProject(
     escalation,
     authority,
     releasePolicy,
+    policy,
+    credentials,
     reporting,
-    workspaceRoot: expandHome(pickString(raw["workspaceRoot"], join(stateDir(), "worktrees"))),
-    mirrorRoot: expandHome(pickString(raw["mirrorRoot"], join(stateDir(), "mirrors"))),
+    ...(orchestratorReadPaths === undefined ? {} : { orchestratorReadPaths }),
+    // Derived from this project's own isolation, not from `stateDir()`: a
+    // hand-written `per-run` config that omits these optional keys would
+    // otherwise resolve under the 0700 private tree and be refused at dispatch,
+    // having never gone through the setup wizard that knows better (#125).
+    workspaceRoot: expandHome(
+      pickString(raw["workspaceRoot"], defaultWorkspaceRoot(projectTreeBase(credentials.isolation))),
+    ),
+    mirrorRoot: expandHome(
+      pickString(raw["mirrorRoot"], defaultMirrorRoot(projectTreeBase(credentials.isolation))),
+    ),
   };
 }
 
@@ -432,6 +616,355 @@ function normalizeAuthority(parsed: unknown, label: string, problems: string[]):
   };
 }
 
+/**
+ * Per-shape release grants, and the migration off the two legacy strings.
+ *
+ * Normalised to a *complete* map at load, so everything downstream — the gate,
+ * `status`, the standing orders, the wizard — reads the same five answers and
+ * none of them has to know which spelling was on disk.
+ *
+ * `"operator-brief"` migrates to every shape except `deploy` (#122). That is the
+ * safe reading of what an operator believed the binary gate opened: a stale
+ * `operator-brief` was enough for an orchestrator session to invoke Komodo
+ * `DeployStack`, which is the grant nobody knowingly gave.
+ *
+ * An unknown shape key is rejected rather than ignored, as in `authority` and
+ * for the same reason: the set is closed, so `{ "deploy-prod": "orchestrator" }`
+ * is a typo every time — and a config that loaded it cleanly would read as
+ * granted in the file while the gate denied every call.
+ */
+function normalizeReleasePolicy(parsed: unknown, label: string, problems: string[]): ResolvedGrants {
+  if (parsed === undefined || parsed === "none") return { ...DENIED_RELEASE_GRANTS };
+  if (parsed === "operator-brief") return { ...OPERATOR_BRIEF_GRANTS };
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    problems.push(
+      `${label}: releasePolicy must be an object mapping release shapes (${RELEASE_SHAPE_LIST}) to ` +
+        `${AUTHORITY_HOLDER_LIST}, or the legacy ${LEGACY_RELEASE_POLICY_LIST}, found ${JSON.stringify(parsed)}`,
+    );
+    return { ...DENIED_RELEASE_GRANTS };
+  }
+  const raw = parsed as Raw;
+
+  const unknownKeys = Object.keys(raw).filter((k) => !Object.hasOwn(DENIED_RELEASE_GRANTS, k));
+  if (unknownKeys.length > 0) {
+    problems.push(
+      `${label}: releasePolicy has unknown release shape(s): ${unknownKeys.join(", ")} — expected ${RELEASE_SHAPE_LIST}`,
+    );
+  }
+
+  const grants = { ...DENIED_RELEASE_GRANTS };
+  for (const shape of RELEASE_SHAPES) {
+    // An absent shape stays denied; a present-but-malformed one is reported and
+    // also stays denied, never folded to the value the operator asked for.
+    grants[shape] = pickLiteral(
+      raw[shape],
+      AUTHORITY_HOLDERS,
+      "human",
+      `${label}: releasePolicy.${shape}`,
+      AUTHORITY_HOLDER_LIST,
+      problems,
+    );
+  }
+  return grants;
+}
+
+/**
+ * The merge and release gating conditions (#129).
+ *
+ * These used to be sentences in the operator's POLICY.md, which meant a verb
+ * could only honour them by asking a model to read prose. Typed and normalised
+ * here to a *complete* value, so the gate, the wizard, the plan summary and the
+ * brief all read the same answers and none of them has to know which fields
+ * were spelled on disk.
+ *
+ * Fail-closed throughout, as in `authority` and for the same reason: both
+ * sections have a closed key set, so an unrecognised key is a typo every time —
+ * and a `policy: { merge: { requiredCheck: [...] } }` that loaded cleanly would
+ * read as configured in the file while the gate went on requiring every check.
+ * A malformed value takes the documented default and is reported; it is never
+ * folded to whatever the operator asked for.
+ */
+function normalizeProjectPolicy(parsed: unknown, label: string, problems: string[]): ProjectPolicy {
+  if (parsed === undefined) return clonePolicy(DEFAULT_PROJECT_POLICY);
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    problems.push(`${label}: policy must be an object with "merge" and "release" sections`);
+    return clonePolicy(DEFAULT_PROJECT_POLICY);
+  }
+  const raw = parsed as Raw;
+
+  const unknownKeys = Object.keys(raw).filter((k) => k !== "merge" && k !== "release");
+  if (unknownKeys.length > 0) {
+    problems.push(`${label}: policy has unknown key(s): ${unknownKeys.join(", ")} — expected "merge" or "release"`);
+  }
+
+  return {
+    merge: normalizeMergePreconditions(raw["merge"], `${label}: policy.merge`, problems),
+    release: normalizeReleasePreconditions(raw["release"], `${label}: policy.release`, problems),
+  };
+}
+
+/** When a pull request may be merged. Absent members take {@link DEFAULT_PROJECT_POLICY}. */
+function normalizeMergePreconditions(parsed: unknown, at: string, problems: string[]): MergePreconditions {
+  const fallback = clonePolicy(DEFAULT_PROJECT_POLICY).merge;
+  if (parsed === undefined) return fallback;
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    problems.push(`${at} must be an object`);
+    return fallback;
+  }
+  const raw = parsed as Raw;
+
+  const known = new Set(Object.keys(fallback));
+  const unknownKeys = Object.keys(raw).filter((k) => !known.has(k));
+  if (unknownKeys.length > 0) {
+    problems.push(`${at} has unknown key(s): ${unknownKeys.join(", ")} — expected ${quoteList([...known])}`);
+  }
+
+  return {
+    requiredChecks: normalizeNameList(raw["requiredChecks"], `${at}.requiredChecks`, problems),
+    baseFreshness: pickLiteral(
+      raw["baseFreshness"],
+      BASE_FRESHNESS,
+      fallback.baseFreshness,
+      `${at}.baseFreshness`,
+      BASE_FRESHNESS_LIST,
+      problems,
+    ),
+    drafts: pickLiteral(raw["drafts"], DRAFT_POLICIES, fallback.drafts, `${at}.drafts`, DRAFT_POLICY_LIST, problems),
+    whenBehindBase: pickLiteral(
+      raw["whenBehindBase"],
+      BEHIND_BASE_ACTIONS,
+      fallback.whenBehindBase,
+      `${at}.whenBehindBase`,
+      BEHIND_BASE_ACTION_LIST,
+      problems,
+    ),
+  };
+}
+
+/** When a release may be cut, what it produces, and where it may go. */
+function normalizeReleasePreconditions(parsed: unknown, at: string, problems: string[]): ReleasePreconditions {
+  const fallback = clonePolicy(DEFAULT_PROJECT_POLICY).release;
+  if (parsed === undefined) return fallback;
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    problems.push(`${at} must be an object`);
+    return fallback;
+  }
+  const raw = parsed as Raw;
+
+  const known = new Set(Object.keys(fallback));
+  const unknownKeys = Object.keys(raw).filter((k) => !known.has(k));
+  if (unknownKeys.length > 0) {
+    problems.push(`${at} has unknown key(s): ${unknownKeys.join(", ")} — expected ${quoteList([...known])}`);
+  }
+
+  return {
+    requires: normalizeReleaseRequirements(raw["requires"], `${at}.requires`, fallback.requires, problems),
+    requiredChecks: normalizeNameList(raw["requiredChecks"], `${at}.requiredChecks`, problems),
+    artefacts: normalizeNameList(raw["artefacts"], `${at}.artefacts`, problems),
+    environments: normalizeNameList(raw["environments"], `${at}.environments`, problems),
+  };
+}
+
+/**
+ * The `requires` set, in the vocabulary's own order rather than the file's.
+ *
+ * Canonical order and de-duplication because this list is rendered into a
+ * refusal and into the plan summary: two configs that require the same three
+ * things must read identically, or an operator diffing them sees a change that
+ * is not one.
+ */
+function normalizeReleaseRequirements(
+  parsed: unknown,
+  at: string,
+  fallback: readonly ReleaseRequirement[],
+  problems: string[],
+): ReleaseRequirement[] {
+  if (parsed === undefined) return [...fallback];
+  if (!Array.isArray(parsed)) {
+    problems.push(`${at} must be an array of ${RELEASE_REQUIREMENT_LIST}`);
+    return [...fallback];
+  }
+
+  const chosen = new Set<string>();
+  parsed.forEach((entry: unknown, i) => {
+    if (!RELEASE_REQUIREMENTS.some((r) => r === entry)) {
+      problems.push(`${at}[${i}] must be ${RELEASE_REQUIREMENT_LIST}, found ${JSON.stringify(entry)}`);
+      return;
+    }
+    chosen.add(entry as ReleaseRequirement);
+  });
+  return RELEASE_REQUIREMENTS.filter((r) => chosen.has(r));
+}
+
+/**
+ * A list of names an operator wrote: check names, artefacts, environments.
+ *
+ * Open-ended by necessity — this package cannot know what a fleet publishes —
+ * but a malformed entry still rejects the whole config rather than being
+ * dropped. A silently dropped environment name is an operator debugging a
+ * refusal that reads exactly like a correctly-denied one, which is the same
+ * trap `orchestratorReadPaths` documents.
+ */
+function normalizeNameList(parsed: unknown, at: string, problems: string[]): string[] {
+  if (parsed === undefined) return [];
+  if (!Array.isArray(parsed)) {
+    problems.push(`${at} must be an array of non-empty strings`);
+    return [];
+  }
+
+  const names: string[] = [];
+  parsed.forEach((entry: unknown, i) => {
+    if (!nonEmptyString(entry)) {
+      problems.push(`${at}[${i}] must be a non-empty string, found ${JSON.stringify(entry)}`);
+      return;
+    }
+    names.push(entry.trim());
+  });
+  return names;
+}
+
+
+/**
+ * The credential boundary, and the one migration that must never brick a fleet.
+ *
+ * `omp/systemd/omp-conductor.service.example` runs the daemon as an
+ * unprivileged account. A naive "fail closed unless per-run uids are available"
+ * release would therefore stop every *existing* fleet from dispatching on
+ * upgrade — a production outage caused by a security feature, which is a worse
+ * outcome than the day before. The issue's rule ("never the silent default")
+ * still holds; it is satisfied by a **migration** rather than by a default:
+ *
+ * 1. Key present → honoured exactly.
+ * 2. Key absent → resolves to `"none"`, and `migrateCredentialsOnDisk` rewrites
+ *    the file so the answer is explicit on disk, exactly the way the v1→v2 caps
+ *    migration normalises on load. The operator ends up with
+ *    `"isolation": "none"` in their config plus one log line naming it, and
+ *    nothing stops dispatching.
+ * 3. A new config from `setup` asks, and only offers `per-run` as the default
+ *    when the host capability probe passes.
+ *
+ * A malformed value is rejected rather than folded to `"none"`, for the reason
+ * every other vocabulary here is: a misspelt `"per_run"` that silently resolved
+ * to unprotected would read as configured in the file while the fleet ran open.
+ */
+function normalizeCredentials(parsed: unknown, label: string, problems: string[]): CredentialConfig {
+  if (parsed === undefined) return { isolation: "none" };
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    problems.push(
+      `${label}: credentials must be an object with an "isolation" of ${CREDENTIAL_ISOLATION_LIST}, ` +
+        `found ${JSON.stringify(parsed)}`,
+    );
+    return { isolation: "none" };
+  }
+  const raw = parsed as Raw;
+  const isolation = pickLiteral(
+    raw["isolation"],
+    CREDENTIAL_ISOLATIONS,
+    "none",
+    `${label}: credentials.isolation`,
+    CREDENTIAL_ISOLATION_LIST,
+    problems,
+  );
+  const rawToken = raw["readToken"];
+  if (rawToken !== undefined && !nonEmptyString(rawToken)) {
+    problems.push(
+      `${label}: credentials.readToken must be a non-empty string when present — an empty token is not ` +
+        `"no token", it is a token that fails every call`,
+    );
+  }
+  return {
+    isolation,
+    ...(nonEmptyString(rawToken) ? { readToken: rawToken } : {}),
+  };
+}
+
+/**
+ * The effective boundary for a project. `loadConfig` always writes one, so this
+ * only matters for a `ProjectConfig` some caller hand-built — and it resolves
+ * the same way the loader does rather than inventing a second answer.
+ */
+export function resolveCredentials(p: ProjectConfig): CredentialConfig {
+  return p.credentials ?? { isolation: "none" };
+}
+
+/**
+ * Named projects whose on-disk config predates `credentials` — the input to the
+ * migration, and pure so it can be tested against a raw object.
+ */
+export function projectsMissingCredentials(parsed: unknown): string[] {
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return [];
+  const projects = (parsed as Raw)["projects"];
+  if (!Array.isArray(projects)) return [];
+  const missing: string[] = [];
+  projects.forEach((p: unknown, i) => {
+    if (typeof p !== "object" || p === null || Array.isArray(p)) return;
+    const raw = p as Raw;
+    const credentials = raw["credentials"];
+    const explicit =
+      typeof credentials === "object" &&
+      credentials !== null &&
+      !Array.isArray(credentials) &&
+      (credentials as Raw)["isolation"] !== undefined;
+    if (!explicit) missing.push(nonEmptyString(raw["name"]) ? raw["name"] : `projects[${String(i)}]`);
+  });
+  return missing;
+}
+
+/**
+ * Write the migration through, once. Returns the projects that gained an
+ * explicit key, so the caller can log it by name.
+ *
+ * Separate from `loadConfig` on purpose: `loadConfig` is read-only and is called
+ * by every CLI surface, and a loader with a write side-effect is one an
+ * operator cannot run against a config they are only inspecting. A failure to
+ * persist is logged by the caller and is **not** fatal — the in-memory value is
+ * already `"none"`, and refusing to boot because the config file is read-only
+ * would be exactly the outage this migration exists to avoid.
+ */
+export function migrateCredentialsOnDisk(): { migrated: string[]; path: string } {
+  const path = configPath();
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return { migrated: [], path };
+  }
+  const migrated = projectsMissingCredentials(parsed);
+  if (migrated.length === 0) return { migrated: [], path };
+  // Through the loader and back out, so the rewrite is the same normalisation
+  // every other key already gets rather than a second, divergent writer.
+  saveConfig(loadConfig());
+  return { migrated, path };
+}
+
+/**
+ * A clone URL carrying credentials voids the entire boundary (#125).
+ *
+ * `git clone` persists whatever is in the URL into the mirror's config, and the
+ * run repository inherits `origin` from it — so a `https://<pat>@github.com/…`
+ * hands every session the write credential the rest of this release removes,
+ * through a file no environment scrub touches. This used to be a `ponytail`
+ * note on `worktree.ts`'s `ensureMirror`; a warning is not a boundary, so it is
+ * now rejected at load with the field named.
+ *
+ * An SSH URL with a plain username (`ssh://git@github.com/o/r`, `git@github.com:o/r`)
+ * is not a credential and is left alone — that is how nearly every fleet is
+ * configured, and rejecting it would be a migration nobody asked for.
+ */
+export function cloneUrlCredentialProblem(url: string): string | undefined {
+  const m = /^([a-zA-Z][a-zA-Z0-9+.-]*):\/\/([^/]*)@/.exec(url);
+  if (m === null) return undefined;
+  const scheme = (m[1] ?? "").toLowerCase();
+  const userinfo = m[2] ?? "";
+  if (userinfo.includes(":")) {
+    return "embeds a user:password — git persists it into the mirror config, which hands every session the credential";
+  }
+  if (scheme === "http" || scheme === "https") {
+    return "embeds userinfo in an http(s) URL, which is how a personal access token is spelled — git persists it into the mirror config";
+  }
+  return undefined;
+}
+
 function normalizeRepos(parsed: unknown, label: string, problems: string[]): Record<string, RepoTarget> {
   const repos: Record<string, RepoTarget> = {};
 
@@ -449,6 +982,14 @@ function normalizeRepos(parsed: unknown, label: string, problems: string[]): Rec
       problems.push(`${label}: routing.repos.${key}.cloneUrl must be a non-empty string`);
       continue;
     }
+    const credentialInUrl = cloneUrlCredentialProblem(cloneUrl);
+    if (credentialInUrl !== undefined) {
+      problems.push(
+        `${label}: routing.repos.${key}.cloneUrl ${credentialInUrl} (#125). Use an SSH URL, or an https URL ` +
+          `backed by the daemon's own credential helper.`,
+      );
+      continue;
+    }
     const target: RepoTarget = {
       name: pickString(value?.["name"], key),
       cloneUrl,
@@ -490,6 +1031,53 @@ function normalizeGraphProject(parsed: unknown, label: string, problems: string[
   return undefined;
 }
 
+/**
+ * Extra roots the orchestrator's tool gate will let it read (#127).
+ *
+ * Fail-closed for the same reason `graphProject` is: the value is written by a
+ * human here and *enforced* in another process, by a session whose cwd is the
+ * state directory. A relative `../notes` would name a different directory for
+ * every reader, so it is an error rather than something resolved against
+ * whichever cwd happened to load the file — and a jail entry that resolves
+ * somewhere unintended is worse than no entry at all.
+ *
+ * A malformed entry rejects the whole config rather than being dropped: an
+ * operator who mistyped a path they believed they had granted would otherwise
+ * debug a refusal that reads exactly like a correctly-denied one.
+ */
+function normalizeOrchestratorReadPaths(
+  parsed: unknown,
+  label: string,
+  problems: string[],
+): string[] | undefined {
+  if (parsed === undefined) return undefined;
+  if (!Array.isArray(parsed)) {
+    problems.push(`${label}.orchestratorReadPaths must be an array of absolute paths`);
+    return undefined;
+  }
+
+  const paths: string[] = [];
+  parsed.forEach((entry: unknown, i) => {
+    if (!nonEmptyString(entry)) {
+      problems.push(
+        `${label}.orchestratorReadPaths[${i}] must be a non-empty absolute path, found ${JSON.stringify(entry)}`,
+      );
+      return;
+    }
+    const path = expandHome(entry.trim());
+    if (!isAbsolute(path)) {
+      problems.push(
+        `${label}.orchestratorReadPaths[${i}] must be an absolute path (or start with "~") — the ` +
+          `orchestrator session's cwd is the state directory, not wherever this file was edited — ` +
+          `found ${JSON.stringify(entry)}`,
+      );
+      return;
+    }
+    paths.push(path);
+  });
+  return paths.length === 0 ? undefined : paths;
+}
+
 /**
  * Gates are the pre-push CI equivalent, so a malformed entry is an error, not
  * something to drop quietly: a skipped gate is exactly how a lint failure
@@ -537,6 +1125,14 @@ function coerceCaps(parsed: unknown, label: string, problems: string[], legacy:
   for (const key of CAP_KEYS) {
     const v = raw[key];
     if (v === undefined) continue;
+    // The plan-allowance guard is the only cap that is an object rather than a
+    // number, so it validates its own shape before the numeric rule below can
+    // reject it wholesale.
+    if (key === "planUsage") {
+      const cap = coercePlanUsage(v, `${label}.planUsage`, problems);
+      if (cap !== undefined) out.planUsage = cap;
+      continue;
+    }
     // Spend is the only cap that may be null (= no gate). Every other ceiling
     // is a non-negative number; 0 remains a hard stop where it already was.
     if (key === "dailySpendUsd" && v === null) {
@@ -566,6 +1162,63 @@ function coerceCaps(parsed: unknown, label: string, problems: string[], legacy:
   return out;
 }
 
+/**
+ * `{ windowId, maxUsedFraction }`, or `null` for unmetered.
+ *
+ * Fail-closed for the same reason every other guard here is: a plan-allowance
+ * cap the daemon cannot read is a ceiling the operator believes they have. Two
+ * mistakes in particular are rejected by name rather than folded:
+ *
+ * - **`maxUsedFraction: 85`.** The threshold is a fraction, so `85` compares
+ *   as "hold at 8500% consumed" — a guard that can never fire, and one that
+ *   reads in the config file exactly like a deliberate 85% ceiling.
+ * - **A misspelled key.** `windowID`, `window`, `maxUsedPercent` and friends
+ *   would leave a cap with a missing half, which is the same silent
+ *   never-fires outcome.
+ *
+ * A `windowId` no provider reports cannot be caught here — only a live reading
+ * knows what exists — so that case is caught at admission instead, where it
+ * holds dispatch and names the window (see `planUsageStatus` in `usage.ts`).
+ */
+function coercePlanUsage(
+  v: unknown,
+  label: string,
+  problems: string[],
+): PlanUsageCap | null | undefined {
+  if (v === null) return null;
+  if (typeof v !== "object" || Array.isArray(v)) {
+    problems.push(
+      `${label} must be { windowId, maxUsedFraction } or null (unmetered), found ${JSON.stringify(v)}`,
+    );
+    return undefined;
+  }
+  const raw = v as Raw;
+  const rawId = raw["windowId"];
+  const rawFraction = raw["maxUsedFraction"];
+  const windowId = nonEmptyString(rawId) ? rawId.trim() : undefined;
+  const maxUsedFraction =
+    typeof rawFraction === "number" && Number.isFinite(rawFraction) && rawFraction >= 0 && rawFraction <= 1
+      ? rawFraction
+      : undefined;
+  const unknownKeys = Object.keys(raw).filter((k) => k !== "windowId" && k !== "maxUsedFraction");
+
+  if (windowId === undefined) {
+    problems.push(
+      `${label}.windowId must be a non-empty allowance id such as "anthropic:7d", found ${JSON.stringify(rawId)}`,
+    );
+  }
+  if (maxUsedFraction === undefined) {
+    problems.push(
+      `${label}.maxUsedFraction must be a fraction between 0 and 1 (0.85 holds at 85% of the allowance), found ${JSON.stringify(rawFraction)}`,
+    );
+  }
+  if (unknownKeys.length > 0) {
+    problems.push(`${label} has unknown key(s): ${unknownKeys.join(", ")} — expected windowId and maxUsedFraction`);
+  }
+  if (windowId === undefined || maxUsedFraction === undefined || unknownKeys.length > 0) return undefined;
+  return { windowId, maxUsedFraction };
+}
+
 function nonEmptyString(v: unknown): v is string {
   return typeof v === "string" && v.trim().length > 0;
 }