@codedology/code-forge 0.1.0

package/src/config/refresh.mjs

@@ -0,0 +1,276 @@
+/**
+ * `models --refresh --from-cli-caches` (plan §2 step 3, §1.3, C15 — un-cut from v1.1's original
+ * "returns as an opt-in"). Reads each CLI's own model cache off disk (Codex's `~/.codex/
+ * models_cache.json`, Grok's `~/.grok/models_cache.json` — whichever are present) and merges the
+ * ids into a **user-level** cache written by THIS module, `~/.code-forge/cache/models.json`,
+ * shaped `{status: "seen-in-cache", updated_at, seen: {<provider>: [<id>, ...]}}`. It never
+ * touches the project's `.code-forge.yml` — a model seen this way is only ever a WARNING-
+ * suppressing fact for `validate.mjs`'s `unknown-model-id` rule (like `known_extra`, but
+ * per-machine instead of per-project), never something this module writes into the config a
+ * project commits.
+ *
+ * `home` is always an explicit parameter (default `os.homedir()`), never hardcoded — the only way
+ * a test can point this at a fixture HOME without touching the real `~/.codex`/`~/.grok`.
+ *
+ * **Real cache shapes** (read once from this machine's own `~/.codex/models_cache.json` and
+ * `~/.grok/models_cache.json`, 2026-09-24, to build the fixtures under `test/fixtures/cli-caches/`
+ * — no secret, identity, etag or auth-looking field was copied into either fixture):
+ *  - Codex: `{fetched_at, etag, client_version, identity, models: [{slug, display_name,
+ *    supported_reasoning_levels: [{effort, description}, ...], ...many more fields}, ...]}` — an
+ *    ARRAY of model OBJECTS, id at `.slug`.
+ *  - Grok: `{fetched_at, grok_version, auth_method, origin, identity, etag, models: {<id>:
+ *    {info: {id, model, model_family, reasoning_efforts: [{id, value, label, ...}], ...}, api_key,
+ *    env_key, api_base_url}, ...}}` — an OBJECT keyed by id, id at `.info.id` (falls back to the
+ *    object's own key if `info.id` is absent).
+ * Both extractors also accept a bare `["id", ...]` array or `{"models": ["id", ...]}` — a
+ * deliberately simple form kept for hand-written test fixtures and for forward compatibility with
+ * a future CLI cache that already lists bare id strings.
+ */
+
+import { mkdir, readFile, rename, unlink, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+/**
+ * @typedef {(parsed: unknown) => string[]} ModelIdExtractor
+ */
+
+/**
+ * Codex's real shape: `models` is an ARRAY of objects; the id is `.slug`. Also accepts the
+ * simple array-of-strings / `{models: [string]}` forms.
+ * @type {ModelIdExtractor}
+ */
+function extractCodexModelIds(parsed) {
+  const models = Array.isArray(parsed) ? parsed : /** @type {any} */ (parsed)?.models;
+  if (!Array.isArray(models)) {
+    return [];
+  }
+  return models
+    .map((entry) => (typeof entry === 'string' ? entry : entry?.slug))
+    .filter((id) => typeof id === 'string' && id.length > 0);
+}
+
+/**
+ * Grok's real shape: `models` is an OBJECT keyed by id; the id is `.info.id` (or the key itself
+ * when `info.id` is missing/malformed). Also accepts the simple array-of-strings /
+ * `{models: [string]}` forms.
+ * @type {ModelIdExtractor}
+ */
+function extractGrokModelIds(parsed) {
+  if (Array.isArray(parsed)) {
+    return parsed.filter((id) => typeof id === 'string');
+  }
+  const models = /** @type {any} */ (parsed)?.models;
+  if (Array.isArray(models)) {
+    return models.filter((id) => typeof id === 'string');
+  }
+  if (models && typeof models === 'object') {
+    return Object.entries(models)
+      .map(([key, entry]) => (typeof entry?.info?.id === 'string' && entry.info.id.length > 0 ? entry.info.id : key))
+      .filter((id) => typeof id === 'string' && id.length > 0);
+  }
+  return [];
+}
+
+/** Where each CLI keeps its own model cache, relative to `$HOME`, and how to read its ids. */
+const CLI_CACHE_SOURCES = Object.freeze([
+  { provider: 'openai', relativePath: path.join('.codex', 'models_cache.json'), extract: extractCodexModelIds },
+  { provider: 'xai', relativePath: path.join('.grok', 'models_cache.json'), extract: extractGrokModelIds },
+]);
+
+/**
+ * @param {string} home
+ * @returns {string}
+ */
+export function userModelsCachePath(home = os.homedir()) {
+  return path.join(home, '.code-forge', 'cache', 'models.json');
+}
+
+/**
+ * @typedef {object} RefreshResult
+ * @property {string[]} sourcesRead - absolute paths of the CLI caches that existed, parsed as
+ *   valid JSON, AND yielded at least one id.
+ * @property {{path: string, reason: string}[]} sourcesSkipped - a CLI cache that existed but
+ *   could not be used — unreadable (`unreadable (EISDIR)`), malformed JSON (`not valid JSON`,
+ *   optionally `(at position N)` — never a source excerpt), or parsed but yielded 0 ids (a shape
+ *   this module doesn't recognise). A source being skipped never aborts the other source.
+ * @property {Record<string, string[]>} seenThisRun - provider -> ids read from THIS run's sources only.
+ * @property {string} cachePath - where the merged user-level cache was written.
+ */
+
+/**
+ * @param {{home?: string}} [opts]
+ * @returns {Promise<RefreshResult>}
+ */
+export async function refreshFromCliCaches(opts = {}) {
+  const home = opts.home ?? os.homedir();
+  /** @type {Record<string, string[]>} */
+  const seenThisRun = {};
+  /** @type {string[]} */
+  const sourcesRead = [];
+  /** @type {{path: string, reason: string}[]} */
+  const sourcesSkipped = [];
+
+  for (const { provider, relativePath, extract } of CLI_CACHE_SOURCES) {
+    const cachePath = path.join(home, relativePath);
+    let raw;
+    try {
+      raw = await readFile(cachePath, 'utf8');
+    } catch (err) {
+      const code = /** @type {NodeJS.ErrnoException} */ (err).code;
+      if (code === 'ENOENT') {
+        continue;
+      }
+      // EACCES, EISDIR, EMFILE, … — skipped like a malformed file, never aborting the OTHER
+      // provider's valid cache (round-2 MINOR). Only the errno code is reported.
+      sourcesSkipped.push({ path: cachePath, reason: `unreadable (${safeErrnoCode(code)})` });
+      continue;
+    }
+
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch (err) {
+      // A malformed source (e.g. the CLI is partway through writing it) never aborts the other
+      // provider's valid cache — skip and record why, keep going. NEVER `err.message`: V8's
+      // SyntaxError quotes a slice of the source text, and Grok's real cache stores `api_key` in
+      // every model entry, so a half-written file would put a key into this reason (round-2
+      // MAJOR). Only the numeric position, parsed out, is kept.
+      sourcesSkipped.push({ path: cachePath, reason: `not valid JSON${jsonErrorPosition(err)}` });
+      continue;
+    }
+
+    const ids = extract(parsed);
+    if (ids.length === 0) {
+      // Parsed fine but yielded nothing — an unrecognised shape is reported, never silently
+      // recorded as a successful empty refresh.
+      sourcesSkipped.push({ path: cachePath, reason: 'parsed but no model ids could be read from it' });
+      continue;
+    }
+    seenThisRun[provider] = ids;
+    sourcesRead.push(cachePath);
+  }
+
+  const cachePath = userModelsCachePath(home);
+  const existingSeen = await readExistingSeen(cachePath);
+
+  /** @type {Record<string, string[]>} */
+  const mergedSeen = { ...existingSeen };
+  for (const [provider, ids] of Object.entries(seenThisRun)) {
+    const merged = new Set(Object.hasOwn(mergedSeen, provider) ? mergedSeen[provider] : []);
+    for (const id of ids) {
+      merged.add(id);
+    }
+    mergedSeen[provider] = [...merged].sort();
+  }
+
+  await writeModelsCacheAtomically(cachePath, {
+    status: 'seen-in-cache',
+    updated_at: new Date().toISOString(),
+    seen: mergedSeen,
+  });
+
+  return { sourcesRead, sourcesSkipped, seenThisRun, cachePath };
+}
+
+/**
+ * @param {unknown} code
+ * @returns {string} an errno code (`EISDIR`) when it has the errno shape, else `unknown error` —
+ *   the reason string must never carry free text.
+ */
+function safeErrnoCode(code) {
+  return typeof code === 'string' && /^E[A-Z0-9]+$/.test(code) ? code : 'unknown error';
+}
+
+/**
+ * @param {unknown} err - a `JSON.parse` SyntaxError.
+ * @returns {string} ` (at position N)` when V8 reported one, else `''` — digits only, never the
+ *   quoted source excerpt V8 also puts in the message.
+ */
+function jsonErrorPosition(err) {
+  const message = err instanceof Error ? err.message : '';
+  const match = /\bposition (\d+)\b/.exec(message);
+  return match ? ` (at position ${match[1]})` : '';
+}
+
+/** A provider key that must never be written into a map — it names the prototype, not a provider. */
+const FORBIDDEN_PROVIDER_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+
+/**
+ * Reads the existing user-level cache's `seen` map, tolerating a missing, unreadable, corrupt, or
+ * wrongly-shaped file by discarding it (never crashing a refresh — or a `validate` — over it).
+ * Only keeps `seen.<provider>` entries that are themselves arrays of strings — a string value
+ * (`new Set("abc")` would silently split it into characters) or any other shape is dropped rather
+ * than trusted. `__proto__`/`constructor`/`prototype` keys are dropped (round-2 MINOR): JSON.parse
+ * makes `"__proto__"` an OWN key, and assigning it into a plain object would replace that
+ * object's prototype with the id array. (A plain object, not a null-prototype one, on purpose:
+ * callers and tests compare the result against `{}` with strict deep equality.)
+ * @param {string} cachePath
+ * @returns {Promise<Record<string, string[]>>}
+ */
+async function readExistingSeen(cachePath) {
+  /** @type {Record<string, string[]>} */
+  const cleaned = {};
+  let raw;
+  try {
+    raw = await readFile(cachePath, 'utf8');
+  } catch {
+    // ENOENT (never refreshed), EISDIR, EACCES, … — every read error means "nothing usable seen".
+    // A refresh then fails loudly at its own write step if the path is genuinely unwritable.
+    return cleaned;
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return cleaned; // corrupt JSON — a refresh is about to overwrite it with a valid file anyway.
+  }
+
+  const seen = parsed && typeof parsed === 'object' ? /** @type {any} */ (parsed).seen : undefined;
+  if (!seen || typeof seen !== 'object' || Array.isArray(seen)) {
+    return cleaned;
+  }
+  for (const [provider, ids] of Object.entries(seen)) {
+    if (FORBIDDEN_PROVIDER_KEYS.has(provider)) {
+      continue;
+    }
+    if (Array.isArray(ids) && ids.every((id) => typeof id === 'string')) {
+      cleaned[provider] = ids;
+    }
+  }
+  return cleaned;
+}
+
+/**
+ * Writes `contents` to `cachePath` atomically: write to a sibling temp file, then `rename()` it
+ * over the target. `rename()` within the same directory is a single filesystem operation, so a
+ * reader never observes a partially-written file, and an interrupted write leaves the ORIGINAL
+ * file (or no file) intact rather than a truncated one.
+ * @param {string} cachePath
+ * @param {Record<string, any>} contents
+ */
+async function writeModelsCacheAtomically(cachePath, contents) {
+  await mkdir(path.dirname(cachePath), { recursive: true });
+  const tempPath = path.join(path.dirname(cachePath), `.models.json.${randomUUID()}.tmp`);
+  await writeFile(tempPath, `${JSON.stringify(contents, null, 2)}\n`, 'utf8');
+  try {
+    await rename(tempPath, cachePath);
+  } catch (err) {
+    await unlink(tempPath).catch(() => {});
+    throw err;
+  }
+}
+
+/**
+ * Loads the merged user-level cache written by {@link refreshFromCliCaches}, for `validate.mjs`'s
+ * `unknown-model-id` rule to pass in as `opts.seenInCache`. Returns `{}` when the cache has never
+ * been written, is corrupt, or is wrongly shaped (a project that never ran `--refresh-models`, or
+ * whose cache file got damaged, sees the same warnings it always did — never a crash).
+ * @param {{home?: string}} [opts]
+ * @returns {Promise<Record<string, string[]>>}
+ */
+export async function loadSeenInCache(opts = {}) {
+  return readExistingSeen(userModelsCachePath(opts.home ?? os.homedir()));
+}

package/src/config/schema-compile.mjs

@@ -0,0 +1,211 @@
+/**
+ * Per-provider schema compilation (plan §1.3, §5.2, O36) — the S2 session's answer schema and
+ * (in a later block) `s2.mjs`'s compiled-schema-per-provider both need this.
+ *
+ * OpenAI's structured-output "strict" mode has three rules a hand-written schema violates by
+ * default: (1) every property under an object must be listed in `required` (optional fields are
+ * instead modeled as **nullable** required fields), (2) every object must set
+ * `additionalProperties: false`, (3) nothing may be missing from `required`. Claude and Grok take
+ * the source schema unchanged (they support ordinary JSON Schema `required`/optional).
+ *
+ * **Nullability.** `makeNullable()` does ONE thing, unconditionally, for anything it cannot PROVE
+ * already accepts null: move the WHOLE original sub-schema into one `anyOf` branch and add
+ * `{type: 'null'}` as the other. That is correct regardless of what was inside — enum, const, an
+ * object, a `$ref`, a `not`, an `if/then/else`, a nested `anyOf` — because `null` gets its own
+ * branch that doesn't depend on anything the original constrains. `schemaAcceptsNull()` is
+ * deliberately conservative (round-2 MINOR): a sibling `type`/`const`/`enum` that excludes null
+ * wins over a union branch that allows it (`{type:'object', anyOf:[…,{type:'null'}]}` rejects
+ * null), and `$ref`/`not`/`if`/`then`/`else` are never "proven" — wrapping a schema that already
+ * accepted null is harmless, skipping one that didn't is the bug.
+ *
+ * **`additionalProperties: false`.** Every object node that owns a `properties` map gets
+ * `additionalProperties: false` unless it already declares an open-ended one, and a bare
+ * `{type: 'object'}` with no `properties` and no `additionalProperties` is closed to
+ * `{properties: {}, required: [], additionalProperties: false}`. A node that stays open-ended
+ * (`additionalProperties: true` or a schema — one of this project's deliberately open maps such as
+ * `thresholds`, `known_extra`) has NO representation in OpenAI strict mode; forcing it to `false`
+ * would silently drop the map semantics the source intends. Such nodes are left as they are and
+ * reported by {@link openAIStrictViolations}; `compileSchema(…, 'openai', {strict: true})` throws
+ * naming every one. B9's S2 answer schema has none; only the full project config schema (this
+ * package's own test) does.
+ */
+
+/**
+ * @typedef {Record<string, any>} SchemaNode - see `schema-paths.mjs`'s typedef of the same name —
+ *   a schema fragment's shape genuinely varies (`properties`, `$ref`, `anyOf`, `$defs`, …).
+ */
+
+/**
+ * @param {SchemaNode} schema
+ * @param {"anthropic" | "openai" | "xai"} provider
+ * @param {{strict?: boolean}} [opts] - `strict: true` (openai only) throws when the compiled
+ *   schema still has a node OpenAI strict mode cannot accept, naming each JSON pointer.
+ * @returns {SchemaNode} a fresh, independent schema object — never the same reference as `schema`.
+ */
+export function compileSchema(schema, provider, opts = {}) {
+  const clone = structuredClone(schema);
+  if (provider !== 'openai') {
+    return clone;
+  }
+  compileForOpenAI(clone, new Set());
+  if (opts.strict === true) {
+    const violations = openAIStrictViolations(clone);
+    if (violations.length > 0) {
+      throw new Error(`schema cannot be made OpenAI-strict at: ${violations.join(', ')} (open-ended object: additionalProperties is not false)`);
+    }
+  }
+  return clone;
+}
+
+/**
+ * @param {SchemaNode | boolean} schema - a boolean schema (`true`/`false`) is legal JSON Schema.
+ * @returns {boolean} true only when `schema` provably validates `null`. Conservative: anything it
+ *   cannot prove (a `$ref`, `not`, `if`/`then`/`else`) counts as "does not accept null".
+ */
+function schemaAcceptsNull(schema) {
+  if (schema === true) {
+    return true;
+  }
+  if (!schema || typeof schema !== 'object') {
+    return false;
+  }
+  if ('type' in schema) {
+    const types = Array.isArray(schema.type) ? schema.type : [schema.type];
+    if (!types.includes('null')) {
+      return false;
+    }
+  }
+  if ('const' in schema && schema.const !== null) {
+    return false;
+  }
+  if (Array.isArray(schema.enum) && !schema.enum.includes(null)) {
+    return false;
+  }
+  for (const unprovable of ['$ref', 'not', 'if', 'then', 'else']) {
+    if (unprovable in schema) {
+      return false;
+    }
+  }
+  if (Array.isArray(schema.anyOf) && !schema.anyOf.some(schemaAcceptsNull)) {
+    return false;
+  }
+  if (Array.isArray(schema.oneOf) && schema.oneOf.filter(schemaAcceptsNull).length !== 1) {
+    return false;
+  }
+  if (Array.isArray(schema.allOf) && !schema.allOf.every(schemaAcceptsNull)) {
+    return false;
+  }
+  return true;
+}
+
+/**
+ * Makes `propSchema` nullable, in place, unconditionally wrapping whatever it already was.
+ * @param {SchemaNode} propSchema
+ */
+function makeNullable(propSchema) {
+  if (!propSchema || typeof propSchema !== 'object' || schemaAcceptsNull(propSchema)) {
+    return;
+  }
+  /** @type {SchemaNode} */
+  const original = {};
+  for (const key of Object.keys(propSchema)) {
+    original[key] = propSchema[key];
+    delete propSchema[key];
+  }
+  propSchema.anyOf = [original, { type: 'null' }];
+}
+
+/**
+ * @param {SchemaNode} node
+ * @returns {boolean}
+ */
+function isObjectTyped(node) {
+  return node.type === 'object' || (Array.isArray(node.type) && node.type.includes('object'));
+}
+
+/**
+ * Every child schema of `node` with its JSON-pointer suffix — the ONE traversal both the compiler
+ * and {@link openAIStrictViolations} use, so neither can skip a keyword the other visits.
+ * @param {SchemaNode} node
+ * @returns {Array<[string, SchemaNode]>}
+ */
+function childSchemas(node) {
+  /** @type {Array<[string, SchemaNode]>} */
+  const out = [];
+  const push = (/** @type {string} */ suffix, /** @type {unknown} */ child) => {
+    if (child && typeof child === 'object') {
+      out.push([suffix, /** @type {SchemaNode} */ (child)]);
+    }
+  };
+  for (const [key, child] of Object.entries(node.properties ?? {})) push(`/properties/${key}`, child);
+  for (const keyword of ['anyOf', 'oneOf', 'allOf', 'prefixItems']) {
+    if (Array.isArray(node[keyword])) node[keyword].forEach((child, i) => push(`/${keyword}/${i}`, child));
+  }
+  for (const keyword of ['items', 'additionalProperties', 'not', 'if', 'then', 'else']) push(`/${keyword}`, node[keyword]);
+  for (const keyword of ['patternProperties', '$defs', 'definitions']) {
+    for (const [key, child] of Object.entries(node[keyword] ?? {})) push(`/${keyword}/${key}`, child);
+  }
+  return out;
+}
+
+/**
+ * Recursively rewrites every object node: a `properties` map makes every property `required` and
+ * nullable and closes the node (unless it already has an open-ended `additionalProperties`); a
+ * bare `{type: 'object'}` is closed to an empty strict object. `visited` guards against revisiting
+ * the same shared node twice — not against a genuine schema cycle, which this project's schema
+ * does not have.
+ * @param {SchemaNode} node
+ * @param {Set<SchemaNode>} visited
+ */
+function compileForOpenAI(node, visited) {
+  if (!node || typeof node !== 'object' || visited.has(node)) {
+    return;
+  }
+  visited.add(node);
+
+  if (node.properties && typeof node.properties === 'object') {
+    const keys = Object.keys(node.properties);
+    node.required = keys;
+    if (node.additionalProperties === undefined) {
+      node.additionalProperties = false;
+    }
+    for (const key of keys) {
+      makeNullable(node.properties[key]);
+    }
+  } else if (isObjectTyped(node) && node.additionalProperties === undefined && node.patternProperties === undefined) {
+    node.properties = {};
+    node.required = [];
+    node.additionalProperties = false;
+  }
+
+  for (const [, child] of childSchemas(node)) {
+    compileForOpenAI(child, visited);
+  }
+}
+
+/**
+ * Every object node in an (already compiled) schema that OpenAI strict mode cannot accept: an
+ * object-typed or `properties`-owning node whose `additionalProperties` is not exactly `false`.
+ * @param {SchemaNode} compiled
+ * @returns {string[]} JSON pointers (`#/properties/thresholds`), in traversal order.
+ */
+export function openAIStrictViolations(compiled) {
+  /** @type {string[]} */
+  const out = [];
+  /** @type {Set<SchemaNode>} */
+  const visited = new Set();
+  const walk = (/** @type {SchemaNode} */ node, /** @type {string} */ pointer) => {
+    if (!node || typeof node !== 'object' || visited.has(node)) {
+      return;
+    }
+    visited.add(node);
+    if ((isObjectTyped(node) || (node.properties && typeof node.properties === 'object')) && node.additionalProperties !== false) {
+      out.push(pointer);
+    }
+    for (const [suffix, child] of childSchemas(node)) {
+      walk(child, `${pointer}${suffix}`);
+    }
+  };
+  walk(compiled, '#');
+  return out;
+}

package/src/config/schema-paths.mjs

@@ -0,0 +1,84 @@
+/**
+ * A small, shared JSON-Schema navigator used by tests (schema-coverage, the config-contract path
+ * enumeration) and by `schema-compile.mjs`. Handles exactly what `schema/code-forge.schema.json`
+ * actually uses between two dotted-path segments: a `properties` lookup, a typed
+ * `additionalProperties` map (`thresholds.<question>`, `known_extra.<provider>`, `keys.<name>`), a
+ * `$ref` (`levels.L0` points at `#/$defs/level`), and an `anyOf` branch (`review.second_levels` is
+ * `anyOf: [null, {additionalProperties: level}]` — nullable-but-otherwise-a-map). Nothing richer
+ * than that (no `oneOf`/`allOf`) appears anywhere in this schema. **B1.1 (v1.3)** added
+ * `review.max_rounds_per_file`, `review.recheck_scope`, `review.late_findings`, `budget.block_cases`
+ * and `tmp.root` — each is a plain `properties` lookup (`tmp.root` an `anyOf: [string, null]` leaf,
+ * the same shape `review.second_levels` already exercises below) — no new traversal shape needed.
+ *
+ * @typedef {Record<string, any>} SchemaNode - a raw JSON-Schema fragment. Left as an index-typed
+ *   object rather than a precise union: a schema node's shape genuinely varies (bare `properties`,
+ *   `$ref`, `anyOf`, `additionalProperties`, `$defs`, …) and this module's whole job is walking
+ *   between those shapes generically.
+ */
+
+/**
+ * @param {SchemaNode} node
+ * @param {SchemaNode} rootSchema
+ * @returns {SchemaNode} `node` itself, or the `$defs` target its `$ref` points at.
+ */
+export function deref(node, rootSchema) {
+  if (node && typeof node === 'object' && typeof node.$ref === 'string') {
+    const parts = node.$ref.replace(/^#\//, '').split('/');
+    let target = rootSchema;
+    for (const part of parts) {
+      target = target?.[part];
+    }
+    return target;
+  }
+  return node;
+}
+
+/**
+ * Resolves `segments` starting from `node` (already expected to need dereferencing itself).
+ * @param {SchemaNode} node
+ * @param {string[]} segments
+ * @param {SchemaNode} rootSchema
+ * @returns {SchemaNode | undefined}
+ */
+function resolveFrom(node, segments, rootSchema) {
+  const current = deref(node, rootSchema);
+  if (!current) {
+    return undefined;
+  }
+  if (segments.length === 0) {
+    return current;
+  }
+  const [segment, ...rest] = segments;
+
+  const props = current.properties;
+  if (props && Object.prototype.hasOwnProperty.call(props, segment)) {
+    return resolveFrom(props[segment], rest, rootSchema);
+  }
+  if (typeof current.additionalProperties === 'object' && current.additionalProperties !== null) {
+    return resolveFrom(current.additionalProperties, rest, rootSchema);
+  }
+  if (Array.isArray(current.anyOf)) {
+    for (const branch of current.anyOf) {
+      const resolved = resolveFrom(branch, segments, rootSchema);
+      if (resolved !== undefined) {
+        return resolved;
+      }
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Walks a dotted path (`"levels.L0.model"`, `"review.second_levels.L2.provider"`) through the
+ * schema, dereferencing `$ref`s and `anyOf` branches as needed at every step.
+ *
+ * @param {SchemaNode} rootSchema
+ * @param {string} dottedPath - the empty string resolves to `rootSchema` itself (zero segments).
+ * @returns {SchemaNode | undefined} the leaf sub-schema, or `undefined` if any segment is missing.
+ */
+export function resolveSchemaPath(rootSchema, dottedPath) {
+  // `''.split('.')` is `['']` (one EMPTY-STRING segment), not zero segments — without this guard
+  // the empty path would look up `properties['']` and fail, instead of meaning "the root itself".
+  const segments = dottedPath === '' ? [] : dottedPath.split('.');
+  return resolveFrom(rootSchema, segments, rootSchema);
+}

package/src/config/secret-patterns.mjs

@@ -0,0 +1,85 @@
+/**
+ * Secret-SHAPED text detection, shared by the validator's `secret-looking-value` rule and by every
+ * B1 path that prints text derived from a user's files (`validate.mjs` messages, `load.mjs` parse
+ * errors, `refresh.mjs` skip reasons, the `validate`/`models` verbs).
+ *
+ * This is the SHAPE layer. B0's `redact()` is the other layer: it masks secrets a key resolver
+ * has explicitly registered, and deliberately never guesses. Config text is never registered — it
+ * is exactly where a user pastes a key by mistake — so B1 masks anything shaped like a vendor
+ * secret on top of `redact()`.
+ */
+
+/**
+ * Conservative, prefix-shaped patterns for common vendor secret formats. Deliberately NOT a
+ * generic high-entropy/long-string heuristic: a model id like `claude-haiku-4-5-20251001` or a
+ * `keys.jev` reference like `op://vault/item/field` is exactly the kind of long, dash-heavy,
+ * mixed-alnum string a naive entropy check would also flag — refusing every valid config forever.
+ * Every pattern anchors on a real-world secret PREFIX no legitimate config value shares.
+ *
+ * NOT `^…$`-anchored: a token embedded in a longer string (a gates argv element
+ * `Authorization: Bearer sk-…`) must be caught too. The lookbehind is the word-boundary stand-in —
+ * the prefix may not be glued to a preceding identifier character, so `task-…` or `disk-…` never
+ * match the `sk-` pattern. No `g`/`y` flag: `.test()` must carry no `lastIndex` state.
+ */
+export const SECRET_LOOKING_PATTERNS = Object.freeze([
+  /(?<![A-Za-z0-9_-])sk-[A-Za-z0-9_-]{10,}/, // OpenAI / Anthropic API keys
+  /(?<![A-Za-z0-9_-])xai-[A-Za-z0-9]{20,}/, // xAI API keys
+  /(?<![A-Za-z0-9_-])xox[baprs]-[A-Za-z0-9-]{10,}/, // Slack tokens
+  /(?<![A-Za-z0-9_-])gh[opsu]_[A-Za-z0-9]{20,}/, // GitHub tokens (classic prefixes)
+  /(?<![A-Za-z0-9_-])github_pat_[A-Za-z0-9_]{20,}/, // GitHub fine-grained PATs
+  /(?<![A-Za-z0-9_-])AKIA[0-9A-Z]{12,}/, // AWS access key id
+  /(?<![A-Za-z0-9_-])AIza[0-9A-Za-z_-]{20,}/, // Google API key
+  /(?<![A-Za-z0-9_-])eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{5,}/, // JWT
+]);
+
+/** The mask every B1 scrub writes in place of a secret-shaped token (same text as B0's `redact`). */
+export const SECRET_MASK = '[REDACTED]';
+
+/**
+ * A `keys.<name>` value is a REFERENCE (`env:NAME`, `op://…`, `user`), never a secret, by design.
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+export function isKeyReferenceValue(value) {
+  return typeof value === 'string' && (value.startsWith('env:') || value.startsWith('op://') || value === 'user');
+}
+
+/**
+ * @param {unknown} value
+ * @returns {boolean} true when `value` is a string holding at least one secret-shaped token and is
+ *   not itself a key reference.
+ */
+export function looksLikeSecret(value) {
+  if (typeof value !== 'string' || isKeyReferenceValue(value)) {
+    return false;
+  }
+  return SECRET_LOOKING_PATTERNS.some((pattern) => pattern.test(value));
+}
+
+/**
+ * @param {string} text
+ * @returns {string[]} every secret-shaped token inside `text` (the matched substrings).
+ */
+export function secretTokensIn(text) {
+  const tokens = [];
+  for (const pattern of SECRET_LOOKING_PATTERNS) {
+    for (const match of text.matchAll(new RegExp(pattern.source, 'g'))) {
+      tokens.push(match[0]);
+    }
+  }
+  return tokens;
+}
+
+/**
+ * Masks every secret-shaped token in `text`. Applied to OUTPUT text (a message, a reason), so no
+ * key-reference exemption: a message never needs to show a token in full.
+ * @param {string} text
+ * @returns {string}
+ */
+export function maskSecretTokens(text) {
+  let out = text;
+  for (const pattern of SECRET_LOOKING_PATTERNS) {
+    out = out.replace(new RegExp(pattern.source, 'g'), SECRET_MASK);
+  }
+  return out;
+}