@mmerterden/multi-agent-pipeline 20.2.1 → 20.3.0

package/pipeline/schemas/unattended-profile.json

@@ -0,0 +1,248 @@
+{
+  "$comment": "The permission posture `install --unattended` writes into ~/.claude/multi-agent-unattended.settings.json (never ~/.claude/settings.json, so attended sessions keep their own posture), one reason per entry, and the rule doctor's unattended-permissions check and the autopilot runner's launch precondition apply (lib/unattended-profile-check.mjs). The OS sandbox block is the boundary for Bash and everything it starts; the Edit and Read deny rules cover the file tools the sandbox does not; agent-guard.sh under MULTI_AGENT_UNATTENDED=1 is a second layer over both (multi-agent-refs/features/unattended-security.md). Keys checked against the Claude Code settings reference: permissions.defaultMode, permissions.allow, permissions.deny, env, sandbox.enabled, sandbox.failIfUnavailable, sandbox.allowUnsandboxedCommands, sandbox.autoAllowBashIfSandboxed, sandbox.enableWeakerNetworkIsolation, sandbox.filesystem.allowWrite, sandbox.filesystem.denyWrite, sandbox.filesystem.denyRead, sandbox.network.allowedDomains, sandbox.network.strictAllowlist, sandbox.network.allowLocalBinding, sandbox.network.allowMachLookup.",
+  "defaultMode": {
+    "value": "dontAsk",
+    "why": "a call that would prompt is denied instead of waiting for a person who is not there"
+  },
+  "wideAllows": [
+    {
+      "rule": "Bash",
+      "why": "a bare Bash allow in ~/.claude/settings.json lets every command through; permission lists merge across files, so it would apply to an unattended run too. Reported, never removed: that file is the attended posture"
+    },
+    {
+      "rule": "Bash(*)",
+      "why": "Bash(*) is a whole-Bash allow, the same as bare Bash; reported, never removed"
+    },
+    {
+      "rule": "Bash(:*)",
+      "why": "Bash(:*) is a whole-Bash allow, the same as bare Bash; reported, never removed"
+    },
+    {
+      "rule": "Bash(**)",
+      "why": "Bash(**) is a whole-Bash allow, the same as bare Bash; reported, never removed"
+    }
+  ],
+  "allow": [
+    ["Read", "reading the repo it was pointed at"],
+    ["Glob", "finding files by pattern"],
+    ["Grep", "searching file content"],
+    [
+      "Edit",
+      "Phase 2 changes files; protected paths and manifests are denied below and by agent-guard"
+    ],
+    ["Write", "new files and every artefact a phase leaves behind; same limits as Edit"],
+    ["NotebookEdit", "notebooks in the repo; same limits as Edit"],
+    ["Agent", "Phase 1 and Phase 3 dispatch subagents"],
+    ["Skill", "the phase specs are skills"],
+    ["WebFetch", "issue and ticket bodies referenced by URL (reads only)"],
+    ["TaskCreate", "the phase tracker's task list"],
+    ["TaskUpdate", "the same"],
+    ["TaskList", "the same"],
+    ["TaskGet", "the same"],
+    [
+      "mcp__multi-agent-toolkit__*",
+      "simulator, build and design tools; research tools are denied below"
+    ],
+    ["Bash(git *)", "status, diff, add, commit, log; pushes are denied below and by agent-guard"],
+    [
+      "Bash(gh *)",
+      "reads of issues and PRs; every write is blocked by agent-guard when unattended"
+    ],
+    ["Bash(bash *)", "the pipeline's own scripts under ~/.claude/scripts and ~/.claude/lib"],
+    ["Bash(node *)", "the pipeline's own .mjs scripts and the repo's node tooling"],
+    ["Bash(python3 *)", "the pipeline's Python helpers"],
+    ["Bash(jq *)", "state and payload reads"],
+    ["Bash(npm run *)", "the repo's own build and test scripts"],
+    ["Bash(npm test *)", "the same"],
+    ["Bash(npm ci *)", "restore from the committed lockfile"],
+    [
+      "Bash(npx *)",
+      "binaries already in the repo's node_modules; npx --yes is blocked by agent-guard"
+    ],
+    ["Bash(xcodebuild *)", "iOS build and test"],
+    ["Bash(xcrun simctl *)", "simulator control"],
+    ["Bash(xcrun xcresulttool *)", "reading test result bundles"],
+    ["Bash(xcrun xctrace *)", "performance traces"],
+    ["Bash(xcrun --find *)", "toolchain lookups"],
+    ["Bash(swift *)", "SwiftPM build and test"],
+    ["Bash(./gradlew *)", "Android build and test"],
+    [
+      "Bash(pod install *)",
+      "restore from the committed Podfile.lock; blocked by agent-guard once the Podfile changed"
+    ],
+    ["Bash(pytest *)", "Python tests"],
+    ["Bash(go test *)", "Go tests"],
+    ["Bash(go build *)", "Go builds"],
+    ["Bash(cargo test *)", "Rust tests"],
+    ["Bash(cargo build *)", "Rust builds"],
+    ["Bash(make *)", "repos whose entry point is a Makefile"],
+    ["Bash(ls *)", "listing"],
+    ["Bash(cat *)", "reading"],
+    ["Bash(head *)", "reading"],
+    ["Bash(tail *)", "reading"],
+    ["Bash(wc *)", "counting"],
+    ["Bash(find *)", "finding"],
+    ["Bash(grep *)", "searching"],
+    ["Bash(rg *)", "searching"],
+    ["Bash(sed *)", "text filtering; in-place edits of protected paths are blocked by agent-guard"],
+    ["Bash(awk *)", "text filtering"],
+    ["Bash(sort *)", "text filtering"],
+    ["Bash(diff *)", "comparing"],
+    ["Bash(mkdir *)", "creating directories"],
+    ["Bash(cp *)", "copying; protected destinations are blocked by agent-guard"],
+    ["Bash(mv *)", "moving; protected destinations are blocked by agent-guard"],
+    ["Bash(echo *)", "output"],
+    ["Bash(printf *)", "output"],
+    ["Bash(date *)", "timestamps"],
+    ["Bash(cd *)", "changing directory inside the worktree"]
+  ],
+  "deny": [
+    ["Bash(gh pr merge *)", "merging is a person's decision"],
+    ["Bash(git push *)", "the runner pushes, after it verified pr-request.json"],
+    ["Bash(git push)", "the same, with no arguments"],
+    ["Read(~/.ssh/**)", "SSH keys"],
+    ["Read(~/.aws/**)", "cloud credentials"],
+    ["Read(~/.gnupg/**)", "signing keys"],
+    ["Read(~/Library/Keychains/**)", "the Keychain database files"],
+    ["Read(~/.netrc)", "plaintext host credentials"],
+    ["Read(~/.git-credentials)", "plaintext git credentials"],
+    ["Read(~/.docker/config.json)", "registry credentials"],
+    [
+      "Edit(~/.claude/**)",
+      "the installed pipeline, its settings, this profile and the runner's files; a run writes its logs and its PR request under the unattended run directory instead"
+    ],
+    ["Edit(~/.copilot/**)", "the Copilot CLI twin of the installed pipeline"],
+    ["Edit(~/.codex/**)", "the Codex twin of the installed pipeline"],
+    ["Edit(~/.claude.json)", "Claude Code's own state and MCP server list"],
+    ["Edit(~/Library/LaunchAgents/**)", "per-user launchd jobs run as the operator"],
+    ["Edit(~/.zshrc)", "shell startup file"],
+    ["Edit(~/.zshenv)", "shell startup file"],
+    ["Edit(~/.zprofile)", "shell startup file"],
+    ["Edit(~/.zlogin)", "shell startup file"],
+    ["Edit(~/.zlogout)", "shell startup file"],
+    ["Edit(~/.bashrc)", "shell startup file"],
+    ["Edit(~/.bash_profile)", "shell startup file"],
+    ["Edit(~/.bash_login)", "shell startup file"],
+    ["Edit(~/.profile)", "shell startup file"],
+    ["Edit(~/.ssh/**)", "SSH keys and their config"],
+    ["Edit(~/.gnupg/**)", "signing keys and their config"],
+    ["Edit(~/.config/gh/**)", "the GitHub CLI's hosts and config"],
+    ["Edit(~/.config/git/**)", "the XDG git config"],
+    ["Edit(~/.gitconfig)", "the user's git config"],
+    ["Edit(~/.npmrc)", "npm registry and token configuration"],
+    ["Edit(~/.netrc)", "plaintext host credentials"],
+    ["Edit(~/.git-credentials)", "plaintext git credentials"],
+    ["Edit(~/.gradle/init.d/**)", "Gradle init scripts run in every build"],
+    ["Edit(~/.lldbinit)", "commands lldb runs at start"],
+    ["Edit(~/.curlrc)", "options curl applies to every request"],
+    ["Edit(.git/hooks/**)", "hooks run on the next git command"],
+    ["Edit(.git/config)", "the repository's git config"],
+    ["Edit(**/.github/workflows/**)", "CI definitions run with the repo's secrets"],
+    ["mcp__multi-agent-toolkit__research_*", "research tools send the query to an outside service"]
+  ],
+  "env": [
+    [
+      "MCP_TOOLKIT_URL_POLICY",
+      "strict",
+      "web_goto and web_crawl refuse loopback, link-local and metadata addresses"
+    ],
+    [
+      "MCP_TOOLKIT_INDEX_DENY",
+      "~/.ssh,~/.aws,~/.gnupg,~/Library/Keychains",
+      "context_index never indexes, and context_get never returns, credential directories"
+    ]
+  ],
+  "sandbox": {
+    "$comment": "Always written. On macOS the sandbox is Seatbelt. failIfUnavailable makes a missing sandbox a refusal to start; allowUnsandboxedCommands false removes the unsandboxed retry; autoAllowBashIfSandboxed false keeps the allow list above in force for sandboxed commands; no excludedCommands, so every command runs sandboxed. Writes are limited to the working directory, the session temp directory and allowWrite; ~/.claude is also protected by Claude Code itself. In-repo paths are denied through the Edit deny rules above, which Claude Code adds to denyWrite: a relative denyWrite entry in a --settings file does not resolve to the repository. enableWeakerNetworkIsolation lets Go tools such as gh reach the macOS trust service to verify TLS; network egress stays limited to allowedDomains. allowMachLookup lets xcrun simctl reach the simulator service.",
+    "enabled": true,
+    "failIfUnavailable": true,
+    "allowUnsandboxedCommands": false,
+    "autoAllowBashIfSandboxed": false,
+    "enableWeakerNetworkIsolation": true,
+    "filesystem": {
+      "allowWrite": [
+        "~/.multi-agent-unattended",
+        "~/.npm",
+        "~/Library/Caches/Yarn",
+        "~/.gradle",
+        "~/.m2/repository",
+        "~/.cargo/registry",
+        "~/.cargo/git",
+        "~/go/pkg/mod",
+        "~/Library/Caches/go-build",
+        "~/Library/Caches/pip",
+        "~/Library/Caches/CocoaPods",
+        "~/Library/Caches/org.swift.swiftpm",
+        "~/Library/Caches/com.apple.dt.Xcode",
+        "~/Library/Developer/Xcode/DerivedData"
+      ],
+      "denyWrite": [
+        "~/.claude",
+        "~/.copilot",
+        "~/.codex",
+        "~/.claude.json",
+        "~/Library/LaunchAgents",
+        "~/.zshrc",
+        "~/.zshenv",
+        "~/.zprofile",
+        "~/.zlogin",
+        "~/.zlogout",
+        "~/.bashrc",
+        "~/.bash_profile",
+        "~/.bash_login",
+        "~/.profile",
+        "~/.ssh",
+        "~/.gnupg",
+        "~/.config/gh",
+        "~/.config/git",
+        "~/.gitconfig",
+        "~/.npmrc",
+        "~/.netrc",
+        "~/.git-credentials",
+        "~/.gradle/init.d",
+        "~/.gradle/gradle.properties",
+        "~/.lldbinit",
+        "~/.curlrc"
+      ],
+      "denyRead": [
+        "~/.ssh",
+        "~/.aws",
+        "~/.gnupg",
+        "~/Library/Keychains",
+        "~/.netrc",
+        "~/.git-credentials",
+        "~/.docker/config.json"
+      ]
+    },
+    "network": {
+      "strictAllowlist": true,
+      "allowLocalBinding": true,
+      "allowMachLookup": ["com.apple.coresimulator.*"],
+      "allowedDomains": [
+        "github.com",
+        "api.github.com",
+        "codeload.github.com",
+        "objects.githubusercontent.com",
+        "raw.githubusercontent.com",
+        "registry.npmjs.org",
+        "registry.yarnpkg.com",
+        "pypi.org",
+        "files.pythonhosted.org",
+        "repo.maven.apache.org",
+        "repo1.maven.org",
+        "dl.google.com",
+        "maven.google.com",
+        "plugins.gradle.org",
+        "plugins-artifacts.gradle.org",
+        "services.gradle.org",
+        "downloads.gradle.org",
+        "cdn.cocoapods.org",
+        "proxy.golang.org",
+        "sum.golang.org",
+        "index.crates.io",
+        "static.crates.io",
+        "rubygems.org"
+      ]
+    }
+  }
+}

package/pipeline/schemas/unattended-profile.schema.json

@@ -0,0 +1,198 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/unattended-profile.schema.json",
+  "title": "Unattended settings profile",
+  "description": "The permission profile the installer writes for unattended runs: the default mode, the allow and deny rules, the toolkit environment and the optional sandbox, each rule with the reason it exists.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["defaultMode", "wideAllows", "allow", "deny", "env", "sandbox"],
+  "$defs": {
+    "ruleWithReason": {
+      "type": "array",
+      "prefixItems": [
+        {
+          "type": "string",
+          "minLength": 1
+        },
+        {
+          "type": "string",
+          "minLength": 1
+        }
+      ],
+      "minItems": 2,
+      "maxItems": 2
+    }
+  },
+  "properties": {
+    "$comment": {
+      "type": "string"
+    },
+    "defaultMode": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["value", "why"],
+      "properties": {
+        "value": {
+          "type": "string"
+        },
+        "why": {
+          "type": "string"
+        }
+      }
+    },
+    "wideAllows": {
+      "type": "array",
+      "description": "Allow rules in the attended settings that would let every call through; reported, never removed.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["rule", "why"],
+        "properties": {
+          "rule": {
+            "type": "string"
+          },
+          "why": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "allow": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/ruleWithReason"
+      }
+    },
+    "deny": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/ruleWithReason"
+      }
+    },
+    "env": {
+      "type": "array",
+      "description": "[name, value, reason] for each variable the unattended child receives.",
+      "items": {
+        "type": "array",
+        "prefixItems": [
+          {
+            "type": "string",
+            "pattern": "^[A-Z][A-Z0-9_]*$"
+          },
+          {
+            "type": "string"
+          },
+          {
+            "type": "string",
+            "minLength": 1
+          }
+        ],
+        "minItems": 3,
+        "maxItems": 3
+      }
+    },
+    "sandbox": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["enabled"],
+      "properties": {
+        "$comment": {
+          "type": "string"
+        },
+        "enabled": {
+          "type": "boolean"
+        },
+        "failIfUnavailable": {
+          "type": "boolean"
+        },
+        "allowUnsandboxedCommands": {
+          "type": "boolean"
+        },
+        "network": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "allowedDomains": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "deniedDomains": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "strictAllowlist": {
+              "type": "boolean"
+            },
+            "allowManagedDomainsOnly": {
+              "type": "boolean"
+            },
+            "allowLocalBinding": {
+              "type": "boolean"
+            },
+            "allowMachLookup": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          }
+        },
+        "filesystem": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "denyRead": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "allowWrite": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "denyWrite": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "allowRead": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "disabled": {
+              "type": "boolean"
+            }
+          }
+        },
+        "autoAllowBashIfSandboxed": {
+          "type": "boolean"
+        },
+        "enableWeakerNetworkIsolation": {
+          "type": "boolean"
+        },
+        "allowAppleEvents": {
+          "type": "boolean"
+        },
+        "enableWeakerNestedSandbox": {
+          "type": "boolean"
+        },
+        "excludedCommands": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  }
+}

package/pipeline/schemas/worktrees.schema.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/worktrees.schema.json",
+  "title": "Run worktrees",
+  "description": "What `worktrees.mjs --json` prints: one entry per run that owns a worktree, with its size when --measure was passed. --redact removes every x-sensitivity local field.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["contractVersion", "worktrees"],
+  "properties": {
+    "contractVersion": {
+      "type": "string",
+      "pattern": "^1\\.[0-9]+\\.[0-9]+$",
+      "x-sensitivity": "none"
+    },
+    "worktrees": {
+      "type": "array",
+      "x-sensitivity": "none",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["taskId", "exists", "sizeBytes", "measuredAt"],
+        "properties": {
+          "taskId": { "type": "string", "minLength": 1, "x-sensitivity": "none" },
+          "project": { "type": ["string", "null"], "x-sensitivity": "none" },
+          "worktreePath": {
+            "type": "string",
+            "x-sensitivity": "local",
+            "description": "Absolute path on this machine."
+          },
+          "exists": {
+            "type": "boolean",
+            "x-sensitivity": "none",
+            "description": "The directory is on disk. false: removed by Phase 4 or by hand, and the run still names it."
+          },
+          "sizeBytes": {
+            "type": ["integer", "null"],
+            "minimum": 0,
+            "x-sensitivity": "none",
+            "description": "Disk usage from du -sk. null unless --measure ran and the directory exists."
+          },
+          "measuredAt": {
+            "type": ["string", "null"],
+            "format": "date-time",
+            "x-sensitivity": "none",
+            "description": "When sizeBytes was taken; null when it was not."
+          }
+        }
+      }
+    }
+  }
+}

package/pipeline/scripts/README.md

@@ -55,6 +55,7 @@ Validate contracts. Each emits `══ <name> smoke: N passed, M failed ══`
 - `smoke-multi-repo-integration.sh`  -  v5.6.0 integration build + learn-once registry (20 assertions)
 - `smoke-multi-repo-worktree.sh`  -  serial worktree creation with atomicity rollback
 - `smoke-prefs-language.sh`  -  `prefs.global.promptLanguage` contract
+- `smoke-terminal-language.sh`  -  every terminal surface renders in `prefs.global.outputLanguage`, English as the fallback
 - `smoke-progress-contract.sh`  -  progress-line quiet/normal/verbose
 - `smoke-search.sh`  -  `/multi-agent:search` log search + smart ranking
 - `smoke-subagent-validators.sh`  -  Phase 1/2 validator schemas

package/pipeline/scripts/_autopilot-config.mjs

@@ -0,0 +1,130 @@
+/**
+ * _autopilot-config.mjs  -  ~/.claude/autopilot/config.json, checked against
+ * autopilot-config.schema.json at the moment it is loaded.
+ *
+ * Every reader turns the numbers in this file into ceilings: the spend ceiling,
+ * the attempt ceiling, the research-round ceiling, the slot count. `Number("$25")`
+ * is NaN, and every comparison with NaN is false, so a typo would read as "no
+ * ceiling at all". The readers therefore ask here first and treat any problem
+ * as a stop with the problem as its reason.
+ *
+ * The package ships without dependencies, so this is a small validator for the
+ * keywords the schema uses: type, const, enum, minimum, maximum, pattern,
+ * required, properties, additionalProperties, items and uniqueItems. `format`,
+ * `default` and the annotations are not assertions and are not checked.
+ *
+ * @module pipeline/scripts/_autopilot-config
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const SCHEMA_PATH = join(import.meta.dirname, "..", "schemas", "autopilot-config.schema.json");
+
+let cached = null;
+function schema() {
+  if (!cached) cached = JSON.parse(readFileSync(SCHEMA_PATH, "utf-8"));
+  return cached;
+}
+
+function typeOf(v) {
+  if (v === null) return "null";
+  if (Array.isArray(v)) return "array";
+  if (typeof v === "number") return Number.isInteger(v) ? "integer" : "number";
+  return typeof v;
+}
+
+function typeMatches(v, t) {
+  const actual = typeOf(v);
+  if (t === "number") return actual === "number" || actual === "integer";
+  return actual === t;
+}
+
+function check(node, v, path, out) {
+  if (!node || typeof node !== "object") return;
+  const where = path || "config";
+  if (node.type !== undefined) {
+    const types = [node.type].flat();
+    if (!types.some((t) => typeMatches(v, t))) {
+      out.push(`${where} must be ${types.join(" or ")}, got ${JSON.stringify(v)}`);
+      return;
+    }
+  }
+  if ("const" in node && v !== node.const) {
+    out.push(`${where} must be ${JSON.stringify(node.const)}, got ${JSON.stringify(v)}`);
+  }
+  if (Array.isArray(node.enum) && !node.enum.includes(v)) {
+    out.push(`${where} must be one of ${node.enum.join(", ")}, got ${JSON.stringify(v)}`);
+  }
+  if (typeof v === "number") {
+    if (typeof node.minimum === "number" && v < node.minimum) {
+      out.push(`${where} must be >= ${node.minimum}, got ${v}`);
+    }
+    if (typeof node.maximum === "number" && v > node.maximum) {
+      out.push(`${where} must be <= ${node.maximum}, got ${v}`);
+    }
+  }
+  if (typeof v === "string") {
+    if (typeof node.minLength === "number" && v.length < node.minLength) {
+      out.push(
+        `${where} must be at least ${node.minLength} character(s), got ${JSON.stringify(v)}`,
+      );
+    }
+    if (typeof node.maxLength === "number" && v.length > node.maxLength) {
+      out.push(`${where} must be at most ${node.maxLength} character(s), got ${JSON.stringify(v)}`);
+    }
+    if (typeof node.pattern === "string" && !new RegExp(node.pattern).test(v)) {
+      out.push(`${where} must match ${node.pattern}, got ${JSON.stringify(v)}`);
+    }
+  }
+  if (Array.isArray(v)) {
+    if (node.items) v.forEach((x, i) => check(node.items, x, `${where}[${i}]`, out));
+    if (node.uniqueItems && new Set(v.map((x) => JSON.stringify(x))).size !== v.length) {
+      out.push(`${where} must not repeat an item`);
+    }
+  }
+  if (typeOf(v) === "object") {
+    for (const key of node.required || []) {
+      if (!(key in v)) out.push(`${where}.${key} is required`);
+    }
+    const props = node.properties || {};
+    for (const [key, value] of Object.entries(v)) {
+      const sub = `${path ? path + "." : ""}${key}`;
+      if (key in props) check(props[key], value, sub, out);
+      else if (node.additionalProperties === false) out.push(`${sub} is not a known key`);
+    }
+  }
+}
+
+/**
+ * Every way `config` breaks the schema, as one readable line each. Empty means
+ * valid.
+ *
+ * @param {unknown} config
+ * @returns {string[]}
+ */
+export function configProblems(config) {
+  let doc;
+  try {
+    doc = schema();
+  } catch (e) {
+    return [`autopilot-config.schema.json cannot be read (${e?.message || e})`];
+  }
+  const out = [];
+  check(doc, config, "", out);
+  return out;
+}
+
+/**
+ * One sentence for a refusal, or null when the config is valid.
+ *
+ * @param {unknown} config
+ * @returns {string|null}
+ */
+export function configRefusal(config) {
+  const problems = configProblems(config);
+  if (!problems.length) return null;
+  const shown = problems.slice(0, 3).join("; ");
+  const more = problems.length > 3 ? ` (+${problems.length - 3} more)` : "";
+  return `autopilot config.json is invalid: ${shown}${more}`;
+}