nomarmy 0.1.0-alpha.2 → 0.1.0-alpha.21

package/lib/validators.mjs

@@ -0,0 +1,220 @@
+// Optional semantic validators: judgments nomArmy's mechanical checks can't
+// make, from a model the operator configures with their own key. Today one:
+// Jev, TypeSafe's System One model (https://docs.typesafe.ai).
+//
+// They only ever add review flags. Diffs and reports are written by the
+// worker being judged, and a model can be talked into a verdict (Jev's own
+// docs list prompt injection as a weakness), so a validator's answer never
+// passes a check, clears a flag or allows a commit. Its worst case is a flag
+// it failed to raise.
+//
+// Off by default, and it sends excerpts of your code to TypeSafe.
+//
+// ~/.config/nomarmy/validators.yml:
+//   jev:
+//     enabled: true
+//     key_file: ~/.config/nomarmy/secrets/typesafe.key   # or key_env: NAME
+//     model: jev-latest
+//     checks: [scout-citations, report-claims]
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import YAML from "yaml";
+import { z } from "zod";
+import { globalConfigDir } from "./army.mjs";
+
+export const VALIDATORS_FILE = "validators.yml";
+export const JEV_CHECKS = Object.freeze(["scout-citations", "report-claims"]);
+export const JEV_ENDPOINT = "https://api.typesafe.ai/v1/systemone";
+
+const jevSchema = z.object({
+  enabled: z.boolean().default(true),
+  key_file: z.string().min(1).optional(),
+  key_env: z.string().regex(/^[A-Z_][A-Z0-9_]*$/, "must be an environment variable NAME, never the key itself").optional(),
+  model: z.string().regex(/^[A-Za-z0-9._-]{1,64}$/).default("jev-latest"),
+  checks: z.array(z.enum(JEV_CHECKS)).default([...JEV_CHECKS]),
+}).strict().refine((j) => j.key_file || j.key_env, "needs key_file or key_env");
+
+// A model judge (lib/judge.mjs): an agent from agents.yml and a model.
+export const JUDGE_CHECK_NAMES = Object.freeze(["acceptance", "report-claims", "test-weakening"]);
+const judgeSchema = z.object({
+  enabled: z.boolean().default(true),
+  agent: z.string().regex(/^[A-Za-z0-9._-]{1,64}$/, "must name an agent from agents.yml"),
+  model: z.string().regex(/^\S{1,200}$/, "must be a model id"),
+  checks: z.array(z.enum(JUDGE_CHECK_NAMES)).default([...JUDGE_CHECK_NAMES]),
+  // A judge on an agent whose tools run on this machine (the Claude CLI)
+  // reads worker-written text with those tools available: explicit consent.
+  host_tools: z.boolean().default(false),
+}).strict();
+
+const validatorsSchema = z.object({ jev: jevSchema.optional(), judge: judgeSchema.optional() }).strict();
+
+export function validatorsPath(configDir = globalConfigDir()) {
+  return path.join(configDir, VALIDATORS_FILE);
+}
+
+export function defaultKeyFile(configDir = globalConfigDir()) {
+  return path.join(configDir, "secrets", "typesafe.key");
+}
+
+const expandHome = (p) => (p.startsWith("~/") ? path.join(os.homedir(), p.slice(2)) : p);
+
+/** The validators config, or {} when there's none. Throws on an invalid file. */
+export function loadValidators(configDir = globalConfigDir()) {
+  let text;
+  try { text = fs.readFileSync(validatorsPath(configDir), "utf8"); } catch { return {}; }
+  const parsed = validatorsSchema.safeParse(YAML.parse(text) ?? {});
+  if (!parsed.success) throw new Error(`${validatorsPath(configDir)} is not valid: ${parsed.error.issues.map((i) => `${i.path.join(".") || "config"}: ${i.message}`).join("; ")}`);
+  return parsed.data;
+}
+
+/** Jev's settings and key when it's enabled and its key is readable; else null. */
+export function jevSettings({ configDir = globalConfigDir(), env = process.env } = {}) {
+  let config;
+  try { config = loadValidators(configDir).jev; } catch { return null; }
+  if (!config?.enabled) return null;
+  const key = config.key_env ? String(env[config.key_env] ?? "").trim() : readKeyFile(expandHome(config.key_file));
+  return key ? { ...config, key } : null;
+}
+
+function readKeyFile(file) {
+  try { return fs.readFileSync(file, "utf8").trim() || null; } catch { return null; }
+}
+
+/**
+ * Save the key where only this user can read it (0600, in a 0700 directory)
+ * and enable Jev. The key never goes into validators.yml.
+ */
+export function saveJevKey(key, { configDir = globalConfigDir(), checks = [...JEV_CHECKS] } = {}) {
+  const clean = String(key ?? "").trim();
+  if (!clean || /\s/.test(clean)) throw new Error("that doesn't look like an API key (empty, or contains spaces)");
+  const keyFile = defaultKeyFile(configDir);
+  fs.mkdirSync(path.dirname(keyFile), { recursive: true, mode: 0o700 });
+  fs.chmodSync(path.dirname(keyFile), 0o700);
+  fs.writeFileSync(keyFile, `${clean}\n`, { mode: 0o600 });
+  fs.chmodSync(keyFile, 0o600);
+  const current = (() => { try { return loadValidators(configDir); } catch { return {}; } })();
+  const next = { ...current, jev: { enabled: true, key_file: keyFile, model: current.jev?.model ?? "jev-latest", checks } };
+  fs.mkdirSync(configDir, { recursive: true });
+  fs.writeFileSync(validatorsPath(configDir), YAML.stringify(next));
+  return { keyFile, configPath: validatorsPath(configDir) };
+}
+
+/**
+ * The judge's settings with its agent resolved, or { problem } when it can't
+ * run as configured (unknown agent, host tools without consent), or null
+ * when there's no enabled judge.
+ */
+export function judgeSettings({ configDir = globalConfigDir(), agents = {}, providerOf, runsOnHost }) {
+  let config;
+  try { config = loadValidators(configDir).judge; } catch (error) { return { problem: error.message }; }
+  if (!config?.enabled) return null;
+  const agent = agents[config.agent];
+  if (!agent) return { problem: `the judge's agent "${config.agent}" isn't in agents.yml` };
+  if (agent.kind === "local") return { problem: "the judge needs an api or subscription agent; the local model's context is too small for a whole diff" };
+  if (runsOnHost(agent) && !config.host_tools) return { problem: `agent "${config.agent}" runs its tools on this machine, and a judge reads worker-written text; set host_tools: true on the judge in validators.yml to accept that, or use a sandboxed agent` };
+  return { ...config, provider: providerOf(agent) };
+}
+
+export function saveJudge({ agent, model, hostTools = false, checks = [...JUDGE_CHECK_NAMES] }, { configDir = globalConfigDir() } = {}) {
+  const current = (() => { try { return loadValidators(configDir); } catch { return {}; } })();
+  const next = { ...current, judge: { enabled: true, agent, model, checks, host_tools: Boolean(hostTools) } };
+  const parsed = validatorsSchema.safeParse(next);
+  if (!parsed.success) throw new Error(parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; "));
+  fs.mkdirSync(configDir, { recursive: true });
+  fs.writeFileSync(validatorsPath(configDir), YAML.stringify(next));
+  return { configPath: validatorsPath(configDir) };
+}
+
+/** Build the guided judge list. Local agents cannot judge a whole diff. */
+export function judgeAgentChoices({ agents, roles = {}, providerOf, runsOnHost }) {
+  const builderVendors = new Map();
+  for (const role of Object.values(roles)) {
+    if (role.phase !== "build" || !agents[role.agent] || agents[role.agent].kind === "local") continue;
+    const vendor = providerOf(agents[role.agent]);
+    builderVendors.set(vendor, (builderVendors.get(vendor) ?? 0) + 1);
+  }
+  const choices = Object.entries(agents)
+    .filter(([name, agent]) => name !== "local" && agent.kind !== "local")
+    .map(([name, agent]) => {
+      const vendor = providerOf(agent);
+      return { name, agent, vendor, hostTools: runsOnHost(agent), sharesBuilderVendor: builderVendors.has(vendor) };
+    });
+  choices.sort((a, b) => Number(a.sharesBuilderVendor) - Number(b.sharesBuilderVendor) || a.name.localeCompare(b.name));
+  const dominantBuilderVendor = [...builderVendors.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))[0]?.[0] ?? null;
+  return { choices, dominantBuilderVendor };
+}
+
+/** Print numbered choices and keep asking until one valid number is entered. */
+export async function chooseJudgeAgent({ choices, ask, write }) {
+  write("Configured judge agents:");
+  choices.forEach((choice, index) => {
+    const independence = choice.sharesBuilderVendor ? "same vendor as builders; verdicts are not independent" : "independent of your builders";
+    write(`  ${index + 1}. ${choice.name}${choice.hostTools ? " (runs tools on this machine)" : ""} (${independence})`);
+  });
+  for (;;) {
+    const answer = String(await ask("Choose a judge agent: ")).trim();
+    if (/^[1-9][0-9]*$/.test(answer) && Number(answer) <= choices.length) return choices[Number(answer) - 1];
+    write(`Choose a number from 1 to ${choices.length}.`);
+  }
+}
+
+/** Explain the host boundary and accept only an explicit y or yes. */
+export async function confirmJudgeHostTools({ agent, ask, write }) {
+  write("The judge's model can run commands on this machine as you, outside the sandbox, while reading text a worker wrote.");
+  write("Alternatively, use a sandboxed agent such as an api key, Codex or Muse.");
+  const answer = String(await ask(`Allow ${agent} to run as a judge with tools on this machine? [y/N] `)).trim().toLowerCase();
+  return answer === "y" || answer === "yes";
+}
+
+export function removeJudge({ configDir = globalConfigDir() } = {}) {
+  const current = (() => { try { return loadValidators(configDir); } catch { return {}; } })();
+  delete current.judge;
+  if (fs.existsSync(validatorsPath(configDir))) fs.writeFileSync(validatorsPath(configDir), YAML.stringify(current));
+}
+
+/** Turn Jev off and delete the key file nomArmy saved. */
+export function removeJev({ configDir = globalConfigDir() } = {}) {
+  const current = (() => { try { return loadValidators(configDir); } catch { return {}; } })();
+  const keyFile = current.jev?.key_file ? expandHome(current.jev.key_file) : null;
+  if (keyFile && path.resolve(keyFile) === path.resolve(defaultKeyFile(configDir))) fs.rmSync(keyFile, { force: true });
+  delete current.jev;
+  if (fs.existsSync(validatorsPath(configDir))) fs.writeFileSync(validatorsPath(configDir), YAML.stringify(current));
+  return { removedKey: Boolean(keyFile) };
+}
+
+// A Jev outage must never slow nomArmy down, let alone stop it: after a
+// failure (unreachable, timeout, 5xx, a rejected key), every job skips Jev
+// for BREAKER_MS, and a job's own checks stop at their first failure.
+export const BREAKER_MS = 10 * 60 * 1000;
+let openUntil = 0, lastFailure = null;
+export function jevBreaker(now = Date.now()) {
+  return now < openUntil ? { open: true, reason: lastFailure, retryAt: new Date(openUntil).toISOString() } : { open: false };
+}
+export function tripJevBreaker(reason, now = Date.now()) { openUntil = now + BREAKER_MS; lastFailure = reason; }
+export function resetJevBreaker() { openUntil = 0; lastFailure = null; }
+
+/**
+ * One System One request. Retries once on 429/529. Never logs the key.
+ * @returns {Promise<{ answers: object, usage: object|null }>}
+ */
+export async function askJev({ key, model = "jev-latest", state, questions, fetchFn = fetch, timeoutMs = 15000 }) {
+  const body = JSON.stringify({ model, state, questions });
+  for (let attempt = 0; attempt < 2; attempt++) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    let response;
+    try {
+      response = await fetchFn(JEV_ENDPOINT, { method: "POST", headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json" }, body, signal: controller.signal });
+    } finally { clearTimeout(timer); }
+    if ((response.status === 429 || response.status === 529) && attempt === 0) { await new Promise((r) => setTimeout(r, 1500)); continue; }
+    if (!response.ok) {
+      const why = response.status === 401 ? "the API key was rejected (401)" : `TypeSafe answered ${response.status}`;
+      throw new Error(why);
+    }
+    const data = await response.json();
+    return { answers: data.answers ?? {}, usage: data.usage ?? null, model: data.model ?? model };
+  }
+  throw new Error("TypeSafe stayed rate-limited or overloaded");
+}

package/lib/verification-artifacts.mjs

@@ -0,0 +1,46 @@
+import { credentialForms } from "./verification-network.mjs";
+import fs from "node:fs";
+import path from "node:path";
+import { loadHarnesses, matchHarnesses } from "./harnesses.mjs";
+import { matchesGlob } from "./repo-query.mjs";
+
+/** Copy regular evidence files only; never follow repository-controlled symlinks. */
+export function collectVerificationArtifacts(cwd, jobDir, { secrets = [], maxFiles = 200, maxBytes = 50 * 1024 * 1024 } = {}) {
+  const { harnesses } = loadHarnesses();
+  const globs = matchHarnesses(cwd, harnesses).flatMap((name) => harnesses[name].artifacts);
+  const artifacts = [];
+  let bytes = 0, capped = false, dropped = 0;
+  const forms = credentialForms(secrets).map(s => Buffer.from(s));
+  const destination = path.join(jobDir, "artifacts");
+  // Do not reuse a directory the runner could have populated with symlinks.
+  fs.rmSync(destination, { recursive: true, force: true });
+  function walk(dir = "") {
+    for (const entry of fs.readdirSync(path.join(cwd, dir), { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      const rel = path.posix.join(dir, entry.name);
+      if (entry.isSymbolicLink()) continue;
+      if (entry.isDirectory()) {
+        if ([".git", "node_modules"].includes(entry.name) || path.resolve(cwd, rel) === path.resolve(destination)) continue;
+        walk(rel);
+      } else if (entry.isFile() && globs.some((glob) => matchesGlob(rel, glob))) {
+        const source = path.join(cwd, rel);
+        const fd = fs.openSync(source, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+        try {
+          const stat = fs.fstatSync(fd);
+          if (!stat.isFile()) continue;
+          if (artifacts.length >= maxFiles || bytes + stat.size > maxBytes) { capped = true; continue; }
+          // Bound reads even if the file grows while verification is finishing.
+          const content = Buffer.alloc(stat.size);
+          const size = fs.readSync(fd, content, 0, content.length, 0);
+          if (forms.some(form => content.subarray(0, size).includes(form) || Buffer.from(rel).includes(form))) { dropped++; continue; }
+          const target = path.join(destination, rel);
+          fs.mkdirSync(path.dirname(target), { recursive: true });
+          fs.writeFileSync(target, content.subarray(0, size));
+          bytes += size;
+          artifacts.push(path.posix.join("artifacts", rel));
+        } finally { fs.closeSync(fd); }
+      }
+    }
+  }
+  if (globs.length) walk();
+  return { artifacts, artifactsCapped: capped, ...(dropped ? { artifactsNote: `dropped ${dropped} artifact(s) containing credentials` } : {}) };
+}

package/lib/verification-flow.mjs

@@ -2,6 +2,7 @@ import { execFileSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import crypto from "node:crypto";
+import { collectVerificationArtifacts } from "./verification-artifacts.mjs";
 
 // ---------------------------------------------------------------------------
 // Production-file revert/restore helpers. These operate on plain
@@ -164,7 +165,7 @@ export function createVerificationFlow(deps) {
   // worktree may not be provably back to the worker's real edit, which the
   // caller must treat as a hard, unconditional block, never as just another
   // failed check (see the call site in executeImplement).
-  async function runRegressionCheck({ cwd, jobId, productionFiles, nameStatus, profile, baseSha, branch, mode }) {
+  async function runRegressionCheck({ cwd, jobId, productionFiles, nameStatus, profile, baseSha, branch, mode, verificationResult }) {
     if (!productionFiles || productionFiles.length === 0) {
       return { status: "not_run", rawRerunStatus: null, basis: "not-applicable", reason: "no production files changed", detail: null };
     }
@@ -196,17 +197,25 @@ export function createVerificationFlow(deps) {
     const restoreErrors = [];
     for (const item of plan) { try { restoreWorkerVersion(item); } catch (error) { restoreErrors.push({ path: item.path, error: error.message }); } }
 
+    if (rerun.network && verificationResult?.network) {
+      verificationResult.network.reached = [...new Set([...(verificationResult.network.reached ?? []), ...(rerun.network.reached ?? [])])];
+      if (rerun.log && verificationResult.log) {
+        try { fs.appendFileSync(verificationResult.log, "\n\n[regression check]\n" + fs.readFileSync(rerun.log, "utf8")); }
+        catch { rerun = { ...rerun, status: "not_run", basis: "egress-log-failed", reason: "could not merge regression network log" }; }
+      }
+    }
+    const rerunEvidence = rerun.network ? { network: rerun.network, log: rerun.log, issues: rerun.issues } : {};
     const mismatches = [...expectedAfterRestore].filter(([full, hash]) => currentBlobHash(full) !== hash).map(([full]) => full);
     if (restoreErrors.length > 0 || mismatches.length > 0) {
-      return { status: "restore_failed", rawRerunStatus: rerun.status, basis: "restore-error",
+      return { ...rerunEvidence, status: "restore_failed", rawRerunStatus: rerun.status, basis: "restore-error",
         reason: `production files may not be fully restored after regression check: ${[...restoreErrors.map(e => e.path), ...mismatches].join(", ")}`, detail: null };
     }
     if (revertErrors.length > 0) {
       return { status: "not_run", rawRerunStatus: null, basis: "revert-error", reason: `failed to revert ${revertErrors.length} file(s): ${revertErrors.map(e => e.path).join(", ")}`, detail: null };
     }
-    if (rerun.status === "fail") return { status: "pass", rawRerunStatus: "fail", basis: rerun.basis, reason: "reverting the production change made the same verification profile fail, as expected -- a test catches this regression", detail: rerun.detail };
-    if (rerun.status === "pass") return { status: "fail", rawRerunStatus: "pass", basis: rerun.basis, reason: "verification still passed with the production change reverted -- no test demonstrably catches this regression", detail: rerun.detail };
-    return { status: "not_run", rawRerunStatus: "not_run", basis: rerun.basis, reason: `regression rerun was inconclusive: ${rerun.reason}`, detail: rerun.detail };
+    if (rerun.status === "fail") return { ...rerunEvidence, status: "pass", rawRerunStatus: "fail", basis: rerun.basis, reason: "reverting the production change made the same verification profile fail, as expected -- a test catches this regression", detail: rerun.detail };
+    if (rerun.status === "pass") return { ...rerunEvidence, status: "fail", rawRerunStatus: "pass", basis: rerun.basis, reason: "verification still passed with the production change reverted -- no test demonstrably catches this regression", detail: rerun.detail };
+    return { ...rerunEvidence, status: "not_run", rawRerunStatus: "not_run", basis: rerun.basis, reason: `regression rerun was inconclusive: ${rerun.reason}`, detail: rerun.detail };
   }
 
   // ---------------------------------------------------------------------------
@@ -222,7 +231,8 @@ export function createVerificationFlow(deps) {
     return {
       status, profile: value?.profile ?? profile ?? null,
       basis: value?.basis ?? (verificationRunner ? "registered-runner" : "none"),
-      reason: value?.reason ?? null, detail: value?.detail ?? null
+      reason: value?.reason ?? null, detail: value?.detail ?? null,
+      ...(value?.network ? { network: value.network, issues: value.issues ?? [] } : {})
     };
   }
   async function runIndependentVerification(context) {
@@ -230,7 +240,42 @@ export function createVerificationFlow(deps) {
       return normalizeVerification({ status: "not_run", basis: "none",
         reason: "no verification runner registered; profile execution is owned by the verification component" }, context.profile);
     }
-    try { return normalizeVerification(await verificationRunner(context), context.profile); }
+    try {
+      const artifactJobDir = context.jobDir ?? (context.logFile ? path.dirname(context.logFile) :
+        context.jobId && ensureJobsRoot ? path.join(ensureJobsRoot(), context.jobId) : null);
+      const value = await verificationRunner({ ...context, jobDir: artifactJobDir });
+      const normalized = normalizeVerification(value, context.profile);
+      // Networked runs must retain the proxy verdicts for every job mode.
+      if (!context.logFile && value?.network && context.jobId && ensureJobsRoot) {
+        context = { ...context, logFile: path.join(ensureJobsRoot(), context.jobId, "verification.log") };
+      }
+      // Persist only the runner-sanitized output (credentialed runs withhold it).
+      if (context.logFile && typeof value?.output === "string") {
+        try {
+          if (value?.network) fs.mkdirSync(path.dirname(context.logFile), { recursive: true });
+          fs.writeFileSync(context.logFile, value.output);
+          normalized.log = context.logFile;
+        } catch {
+          if (value?.network) return { ...normalized, status: "not_run", basis: "egress-log-failed", reason: "could not retain verification network log", detail: null };
+          // Non-networked logs remain best-effort for compatibility.
+        }
+      }
+      const jobDir = context.jobDir ?? (context.logFile ? path.dirname(context.logFile) :
+        context.jobId && ensureJobsRoot ? path.join(ensureJobsRoot(), context.jobId) : null);
+      if (jobDir && context.cwd) {
+        try {
+          Object.assign(normalized, value?.artifacts ? {
+            artifacts: value.artifacts, artifactsCapped: value.artifactsCapped,
+            ...(value.artifactsNote ? { artifactsNote: value.artifactsNote } : {})
+          } : value?.network ? { artifacts: [], artifactsCapped: false } : collectVerificationArtifacts(context.cwd, jobDir));
+          if (normalized.artifactsCapped) normalized.detail = [normalized.detail, "artifact collection capped at 200 files / 50 MB"].filter(Boolean).join("; ");
+        } catch (error) {
+          normalized.artifacts = [];
+          normalized.artifactsError = error.message;
+        }
+      }
+      return normalized;
+    }
     catch (error) {
       // A crashed runner produced no evidence. `not_run` is the truthful state:
       // it can never promote a recovery to success, and it never fabricates a

package/lib/verification-network.mjs

@@ -0,0 +1,66 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { parseYaml } from './config.mjs';
+import { target } from './egress-proxy.mjs';
+
+export function validateVerificationNetwork(value) {
+  const mapping = v => v && typeof v === 'object' && !Array.isArray(v);
+  if (!mapping(value) || Object.keys(value).some(k => !['allow', 'env', 'keep_output'].includes(k)) ||
+      !Array.isArray(value.allow) || !value.allow.length || !mapping(value.env ?? {})) throw new Error('invalid verification_network: expected allow list and env name mapping');
+  if (value.keep_output !== undefined && typeof value.keep_output !== 'boolean') throw new Error('verification_network.keep_output must be boolean');
+  let allow;
+  try { allow = [...new Set(value.allow.map(v => target(v).authority))]; }
+  catch { throw new Error('verification_network.allow requires exact public DNS hosts with optional ports (no IPs or private names)'); }
+  const env = {};
+  for (const [name, source] of Object.entries(value.env ?? {})) {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name) || typeof source !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(source) ||
+        /^(?:https?_proxy|no_proxy|all_proxy)$/i.test(name) || name === '__proto__') throw new Error('verification_network.env must map test variable names to host variable names; proxy variables are reserved');
+    Object.defineProperty(env, name, { value: source, enumerable: true });
+  }
+  return { allow, env, ...(value.keep_output !== undefined ? { keep_output: value.keep_output } : {}) };
+}
+
+// Never call this on a job worktree. Only the coordinator supplies projectDir.
+// Fail closed if Git cannot establish both untracked and ignored provenance.
+export function loadVerificationNetwork(projectDir, { check = (args) => spawnSync('git', args, { cwd: projectDir, encoding: 'utf8', timeout: 5000 }) } = {}) {
+  if (!projectDir) return null;
+  const filename = '.nomarmy.local.yml', file = path.join(projectDir, filename);
+  let stat;
+  try { stat = fs.lstatSync(file); } catch (e) { if (e.code === 'ENOENT') return null; throw new Error('cannot read operator-local verification policy'); }
+  // Do not include YAML parser errors: the document might contain a mistaken secret.
+  let parsed;
+  try { parsed = stat.isFile() && !stat.isSymbolicLink() ? parseYaml(fs.readFileSync(file, 'utf8')) : null; }
+  catch { throw new Error('invalid operator-local YAML'); }
+  // The file also holds other operator-local settings (registries, the army);
+  // provenance only matters when it grants network.
+  if (parsed?.verification_network === undefined && stat.isFile() && !stat.isSymbolicLink()) return null;
+  if (!stat.isFile() || stat.isSymbolicLink()) throw new Error('verification_network requires a regular operator-local file');
+  const tracked = check(['ls-files', '--error-unmatch', '--', filename]);
+  const ignored = check(['check-ignore', '-q', '--', filename]);
+  if (tracked.status !== 1 || ignored.status !== 0) throw new Error('verification_network requires an untracked, gitignored .nomarmy.local.yml');
+  return validateVerificationNetwork(parsed.verification_network);
+}
+
+export function credentialForms(secrets) {
+  return [...new Set(secrets.filter(Boolean).flatMap(secret => {
+    const bytes = Buffer.from(secret);
+    const percent = [...bytes].map(b => '%' + b.toString(16).padStart(2, '0')).join('');
+    return [secret, bytes.toString('base64'), bytes.toString('base64url'),
+      bytes.toString('hex'), bytes.toString('hex').toUpperCase(),
+      encodeURIComponent(secret), encodeURIComponent(secret).replace(/%[0-9A-F]{2}/g, s => s.toLowerCase()),
+      percent, percent.toUpperCase()];
+  }))].sort((a, b) => b.length - a.length);
+}
+
+export function redactCredentials(value, secrets, { truncated = true } = {}) {
+  let text = String(value ?? '');
+  for (const secret of credentialForms(secrets)) {
+    text = text.split(secret).join('***');
+    // Capturing may have cut the final chunk in the middle of a credential.
+    for (let n = truncated ? Math.min(secret.length - 1, text.length) : 0; n > 0; n--) {
+      if (text.endsWith(secret.slice(0, n))) { text = text.slice(0, -n) + '***'; break; }
+    }
+  }
+  return text;
+}