@sabaiway/agent-workflow-kit 1.34.0 → 1.36.0

package/tools/autonomy-config.mjs

@@ -0,0 +1,306 @@
+#!/usr/bin/env node
+// autonomy-config.mjs — the schema / read / pure-transform core for the per-project autonomy policy
+// (docs/ai/autonomy.json). It is the SINGLE source of the policy contract, mirroring
+// orchestration-config.mjs structurally (AD-044):
+//
+//   loadAutonomy / validateAutonomy / AUTONOMY_REL — the strict-JSON reader the read-only surfaces
+//                                                    share (the Claude render imports loadAutonomy).
+//   parseAutonomyOp / assertAutonomyAssignment      — the TYPED op parser + the ONE section/key/value
+//                                                    validity table the set-autonomy writer reuses
+//                                                    (drift-guarded: one accept/reject grammar).
+//   applyAutonomyOps / serializeAutonomy            — the PURE merge + the canonical (2-space,
+//                                                    _README-first) serializer the writer commits.
+//   resolveAutonomy                                 — the pure computed-defaults resolver (sparse →
+//                                                    effective policy); the render + any future read
+//                                                    surface share this ONE resolver.
+//
+// This module performs NO filesystem WRITES — only reads (loadAutonomy). The single fs-writer lives in
+// autonomy-write.mjs, which no read-only module imports, so the read surface stays fs-write-free.
+// Pure-where-possible (fs injectable), dependency-free, Node >= 18. No side effects on import.
+
+import { readFileSync, lstatSync } from 'node:fs';
+import { join } from 'node:path';
+import { ACTIVITIES } from './recipes.mjs';
+
+// The hand-editable / agent-writable, per-project policy (strict JSON). cwd-relative — the error prefix
+// uses this rel path so a user sees a path they can open, never an absolute temp/host path.
+export const AUTONOMY_REL = 'docs/ai/autonomy.json';
+
+// A tagged failure: a plain Error carrying the intended process exit code (2 usage / 1 config). Avoids
+// a class (project rule) while letting a CLI main() map a throw to the right code in one place. Shared
+// so set-autonomy.mjs raises identically-typed errors (mirrors orchestration-config.mjs `fail`).
+export const fail = (exitCode, message) => Object.assign(new Error(message), { exitCode });
+
+// ── the grammar tables (Decision 5) — the ONE shared accept/reject data ──────────────
+// Both validateAutonomy and parseAutonomyOp read THESE tables (never a second hand-copy), so the
+// accept/reject decision can never drift between config-validation and the writer's op parser (pinned
+// by the full-matrix drift test, the orchestration recipeValidForSlot precedent).
+
+// The six red-lines split into command red-lines (commit/push/publish) and non-command red-lines
+// (network/credentials/fs_outside_repo). Both take `ask` or `deny`; only the Decision-4 DEFAULT differs.
+export const COMMAND_REDLINES = Object.freeze(['commit', 'push', 'publish']);
+export const NONCOMMAND_REDLINES = Object.freeze(['network', 'credentials', 'fs_outside_repo']);
+export const REDLINE_KEYS = Object.freeze([...COMMAND_REDLINES, ...NONCOMMAND_REDLINES]);
+export const REDLINE_VALUES = Object.freeze(['ask', 'deny']);
+// Decision 4 defaults: command red-lines default to `ask` (commit stays the human checkpoint), the
+// non-command red-lines default to `deny` (network/credentials/fs escape are the conservative floor).
+export const REDLINE_DEFAULTS = Object.freeze({
+  commit: 'ask', push: 'ask', publish: 'ask',
+  network: 'deny', credentials: 'deny', fs_outside_repo: 'deny',
+});
+
+// Per-activity autonomy level (Decision 2): `sandbox` ⇒ auto-allow + acceptEdits; `prompt` ⇒
+// conservative prompting (sandbox still confines). An absent activity floors at `prompt` (Decision 5).
+export const AUTONOMY_LEVELS = Object.freeze(['sandbox', 'prompt']);
+export const DEFAULT_ACTIVITY_AUTONOMY = 'prompt';
+export const ACTIVITY_KEY = 'autonomy';
+export const REDLINES_SECTION = 'redlines';
+
+const KNOWN_ACTIVITIES = () => Object.keys(ACTIVITIES).join(', ');
+const KNOWN_SECTIONS = () => `${REDLINES_SECTION}, ${KNOWN_ACTIVITIES()}`;
+const isJsonObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+// ── the ONE section/key/value validity grammar (shared accept/reject) ────────────────
+// assignmentValid is the PURE predicate (mirror recipeValidForSlot) the full-matrix drift test pins;
+// assertAutonomySlot / assertAutonomyAssignment are the LOUD assertions the op parser uses. All read
+// the same tables above, so parseAutonomyOp and validateAutonomy can never disagree.
+
+// True iff (section, key) is a known slot of the policy (redlines.<redline> | <activity>.autonomy).
+export const slotValid = (section, key) => {
+  if (section === REDLINES_SECTION) return REDLINE_KEYS.includes(key);
+  if (ACTIVITIES[section]) return key === ACTIVITY_KEY;
+  return false;
+};
+
+// Accepted values for a KNOWN slot: red-lines take ask|deny; an activity's autonomy takes sandbox|prompt.
+export const acceptedValuesFor = (section) => (section === REDLINES_SECTION ? REDLINE_VALUES : AUTONOMY_LEVELS);
+
+// True iff (section, key, value) is a fully-valid assignment. Pure predicate; throws nothing.
+export const assignmentValid = (section, key, value) =>
+  slotValid(section, key) && acceptedValuesFor(section).includes(value);
+
+// Assert (section, key) is a known slot; return its kind ('redline' | 'activity'). Loud (exit 2 by
+// default) with the shared "unknown section" / "unknown slot" message the op parser emits.
+export const assertAutonomySlot = (section, key, exitCode = 2) => {
+  if (section === REDLINES_SECTION) {
+    if (!REDLINE_KEYS.includes(key)) {
+      throw fail(exitCode, `unknown red-line "${key}" (known: ${REDLINE_KEYS.join(', ')})`);
+    }
+    return 'redline';
+  }
+  if (ACTIVITIES[section]) {
+    if (key !== ACTIVITY_KEY) {
+      throw fail(exitCode, `unknown key "${key}" for activity "${section}" (only: ${ACTIVITY_KEY})`);
+    }
+    return 'activity';
+  }
+  throw fail(exitCode, `unknown section "${section}" (known: ${KNOWN_SECTIONS()})`);
+};
+
+// Assert (section, key, value) is a fully-valid assignment — unknown section/key OR bad value → loud.
+// Used by the set-autonomy op parser AND (with exitCode 1) by validateAutonomy, so they accept/reject
+// in lockstep on ONE grammar. Returns the slot kind.
+export const assertAutonomyAssignment = (section, key, value, exitCode = 2) => {
+  const kind = assertAutonomySlot(section, key, exitCode);
+  const accepted = acceptedValuesFor(section);
+  if (typeof value !== 'string' || !accepted.includes(value)) {
+    throw fail(exitCode, `invalid value "${value}" for ${section}.${key} (accepts: ${accepted.join(', ')})`);
+  }
+  return kind;
+};
+
+// ── the typed op parser (usage errors → exit 2) ─────────────────────────────────────
+// The grammar is ALWAYS fully-qualified `<section>.<key>` — the writer never guesses a section. A bare
+// `commit=ask` is rejected (name the section). No `all`-magic; the agent expands plain language into
+// explicit per-key ops (asking if scope is unclear) — the set-recipe division of labor.
+
+const parseQualified = (lhs, flag) => {
+  const dot = lhs.indexOf('.');
+  if (dot <= 0 || dot === lhs.length - 1) {
+    throw fail(
+      2,
+      `${flag} must be fully-qualified <section>.<key> (got "${lhs}") — name the section, e.g. redlines.commit / plan-execution.autonomy`,
+    );
+  }
+  return { section: lhs.slice(0, dot), key: lhs.slice(dot + 1) };
+};
+
+// parseAutonomyOp(kind, token) → a typed record:
+//   kind 'set'   + token `<section>.<key>=<value>` → { kind:'set', section, key, value }
+//   kind 'unset' + token `<section>.<key>`         → { kind:'unset', section, key }
+// Every malformed token is a USAGE error (exit 2): a bare key (no section), an unknown section/key, a
+// bad value, a missing value on --set, or a stray value on --unset.
+export const parseAutonomyOp = (kind, token) => {
+  if (kind === 'set') {
+    const eq = token.indexOf('=');
+    if (eq <= 0) throw fail(2, `--set must be <section>.<key>=<value> (got "${token}")`);
+    const value = token.slice(eq + 1);
+    if (!value) throw fail(2, `--set must be <section>.<key>=<value> (got "${token}")`);
+    const { section, key } = parseQualified(token.slice(0, eq), '--set');
+    assertAutonomyAssignment(section, key, value);
+    return { kind: 'set', section, key, value };
+  }
+  if (token.includes('=')) throw fail(2, `--unset takes <section>.<key> without a value (got "${token}")`);
+  const { section, key } = parseQualified(token, '--unset');
+  assertAutonomySlot(section, key);
+  return { kind: 'unset', section, key };
+};
+
+// ── policy validation (config errors → exit 1) ──────────────────────────────────────
+
+// Validate a parsed autonomy.json object against the Decision-5 grammar. Strict: an unknown top-level
+// key, an unknown red-line, an unknown activity/key, or a bad value is an error. All keys optional
+// (sparse). An optional "_README" string key is allowed + ignored. Never a silent fallback — every
+// rejection is a loud `path: reason` (exit 1). Returns the config on success.
+export const validateAutonomy = (config) => {
+  if (!isJsonObject(config)) {
+    throw fail(1, `${AUTONOMY_REL}: must be a JSON object (red-lines + per-activity autonomy)`);
+  }
+  for (const [key, val] of Object.entries(config)) {
+    if (key === '_README') {
+      if (typeof val !== 'string') throw fail(1, `${AUTONOMY_REL}: "_README" must be a string`);
+      continue;
+    }
+    if (key === REDLINES_SECTION) {
+      if (!isJsonObject(val)) throw fail(1, `${AUTONOMY_REL}: "${REDLINES_SECTION}" must be a JSON object of red-line → ask|deny`);
+      for (const [rk, rv] of Object.entries(val)) {
+        try {
+          assertAutonomyAssignment(REDLINES_SECTION, rk, rv, 1);
+        } catch (err) {
+          throw fail(1, `${AUTONOMY_REL}: ${err.message}`);
+        }
+      }
+      continue;
+    }
+    if (ACTIVITIES[key]) {
+      if (!isJsonObject(val)) throw fail(1, `${AUTONOMY_REL}: activity "${key}" must be a JSON object of { ${ACTIVITY_KEY}: sandbox|prompt }`);
+      for (const [ak, av] of Object.entries(val)) {
+        try {
+          assertAutonomyAssignment(key, ak, av, 1);
+        } catch (err) {
+          throw fail(1, `${AUTONOMY_REL}: ${err.message}`);
+        }
+      }
+      continue;
+    }
+    throw fail(1, `${AUTONOMY_REL}: unknown top-level key "${key}" (known: _README, ${KNOWN_SECTIONS()})`);
+  }
+  return config;
+};
+
+// ── policy IO (config errors → exit 1) ──────────────────────────────────────────────
+
+// Load + validate the policy from <cwd>/docs/ai/autonomy.json. Absent FILE → computed defaults (NOT an
+// error): { config: null, source: 'none' }. Malformed JSON / schema-invalid / unreadable → loud
+// `path: reason` (exit 1). lstat (NOT existsSync) so a DANGLING SYMLINK reads as present and its later
+// read failure surfaces loudly — never silently treated as absent (no-silent-failures Hard Constraint).
+export const loadAutonomy = (cwd, readFile = readFileSync, lstat = lstatSync) => {
+  const full = join(cwd, AUTONOMY_REL);
+  try {
+    lstat(full);
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return { config: null, source: 'none' };
+    throw fail(1, `${AUTONOMY_REL}: unreadable (${(err && err.code) || (err && err.message) || err})`);
+  }
+  let raw;
+  try {
+    raw = readFile(full, 'utf8');
+  } catch (err) {
+    throw fail(1, `${AUTONOMY_REL}: unreadable (${(err && err.code) || (err && err.message) || err})`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw fail(1, `${AUTONOMY_REL}: malformed JSON (${err.message})`);
+  }
+  return { config: validateAutonomy(parsed), source: AUTONOMY_REL };
+};
+
+// ── the pure computed-defaults resolver ─────────────────────────────────────────────
+
+// resolveAutonomy(config) → the effective policy: every red-line resolved to its config value or its
+// Decision-4 default; every ACTIVITIES entry resolved to its config autonomy or `prompt`. The render +
+// any future read surface share THIS resolver, so a sparse policy always yields one full effective
+// policy (no key ever undefined). Pure; accepts null (absent file → all defaults).
+export const resolveAutonomy = (config) => {
+  const cfg = isJsonObject(config) ? config : {};
+  const rl = isJsonObject(cfg[REDLINES_SECTION]) ? cfg[REDLINES_SECTION] : {};
+  const redlines = {};
+  for (const k of REDLINE_KEYS) redlines[k] = rl[k] ?? REDLINE_DEFAULTS[k];
+  const activities = {};
+  for (const a of Object.keys(ACTIVITIES)) {
+    const entry = isJsonObject(cfg[a]) ? cfg[a] : {};
+    activities[a] = { [ACTIVITY_KEY]: entry[ACTIVITY_KEY] ?? DEFAULT_ACTIVITY_AUTONOMY };
+  }
+  return { redlines, activities };
+};
+
+// ── pure merge + canonical serialization ────────────────────────────────────────────
+
+// A pure deep-equal over the JSON-ish policy shape (plain objects + string values). Used only for the
+// "did anything actually change?" decision (no-op detection + seed-on-change), never for output.
+const deepEqual = (a, b) => {
+  if (a === b) return true;
+  if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null) return false;
+  const ak = Object.keys(a);
+  const bk = Object.keys(b);
+  if (ak.length !== bk.length) return false;
+  return ak.every((k) => Object.prototype.hasOwnProperty.call(b, k) && deepEqual(a[k], b[k]));
+};
+
+// applyAutonomyOps(current, ops, { seedReadme }) → the merged policy. PURE: deep-clones `current` (or
+// {}), applies each set/unset, preserves `_README` + every untouched section/key, drops a section that
+// an unset empties (sparse), then re-runs validateAutonomy (loud on invalid — defensive; the op parser
+// pre-validates). When (and ONLY when) the merge CHANGES the policy, `_README` is absent, and
+// `seedReadme` is supplied, the canonical note is seeded — so a no-op set never spuriously seeds it.
+export const applyAutonomyOps = (current, ops, { seedReadme = null } = {}) => {
+  const base = current == null ? {} : structuredClone(current);
+  const next = structuredClone(base);
+  for (const op of ops) {
+    if (op.kind === 'set') {
+      next[op.section] = { ...(next[op.section] ?? {}) };
+      next[op.section][op.key] = op.value;
+    } else if (next[op.section] && op.key in next[op.section]) {
+      const rest = { ...next[op.section] };
+      delete rest[op.key];
+      if (Object.keys(rest).length === 0) delete next[op.section];
+      else next[op.section] = rest;
+    }
+  }
+  validateAutonomy(next);
+  const changed = !deepEqual(next, base);
+  if (changed && seedReadme != null && next._README === undefined) next._README = seedReadme;
+  return next;
+};
+
+// serializeAutonomy(config) → strict JSON, 2-space, trailing newline, `_README` FIRST (explicitly, so
+// the onboarding note never sinks below the policy). This is the canonical on-disk form: a touched
+// write normalizes to it (content-preserving, NOT byte-preserving of arbitrary hand-formatting).
+export const serializeAutonomy = (config) => {
+  const ordered = {};
+  if (config._README !== undefined) ordered._README = config._README;
+  for (const [k, v] of Object.entries(config)) {
+    if (k !== '_README') ordered[k] = v;
+  }
+  return `${JSON.stringify(ordered, null, 2)}\n`;
+};
+
+// ── the canonical seed (Decision 5) ──────────────────────────────────────────────────
+// AUTONOMY_README is the onboarding note; SEED_AUTONOMY is the Decision-5 fixture the set-autonomy
+// writer seeds and the config tests copy/validate verbatim. Plan 1 ships NO references/templates/
+// autonomy.json and NO template-parity test (both Plan 4) — SEED_AUTONOMY's Plan-1 consumers are the
+// autonomy-config tests and the render's "seed one first" guidance.
+export const AUTONOMY_README =
+  'Per-project autonomy policy: red-lines (always) + per-activity autonomy level. Hand-editable; or ' +
+  'use the set-autonomy writer (previews, then writes valid JSON). Strict JSON — no comments.';
+
+export const SEED_AUTONOMY = {
+  _README: AUTONOMY_README,
+  redlines: {
+    commit: 'ask', push: 'ask', publish: 'ask',
+    network: 'deny', credentials: 'deny', fs_outside_repo: 'deny',
+  },
+  'plan-authoring': { autonomy: 'sandbox' },
+  'plan-execution': { autonomy: 'sandbox' },
+};

package/tools/autonomy-write.mjs

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+// autonomy-write.mjs — the ONLY filesystem WRITER for docs/ai/autonomy.json. It is imported by the
+// set-autonomy writer alone; no read-only module (autonomy-config.mjs, velocity-profile.mjs's read
+// path) imports it, so "a read-only surface can never reach a writer" is a STRUCTURAL invariant (an
+// import-split test pins it), not just an assertion. Splitting the writer out of the schema/read module
+// keeps the read surface fs-write-free — the orchestration-write.mjs precedent (AD-044).
+//
+// The hardened write flow (deployment gate → symlink STOPs → containment guard → exclusive-create tmp
+// + rename with a TOCTOU re-check → tmp cleanup; LAST-WRITER-WINS) lives in the shared atomic-write
+// core (tools/atomic-write.mjs, AD-042) and is consumed here with this module's own STOP identity, so
+// the public API + error contract are its own (this file's tests pin them).
+//
+// Dependency-free, Node >= 18. Every fs primitive is injectable (deps.*) so the guards are unit-testable.
+
+import { AUTONOMY_REL, serializeAutonomy } from './autonomy-config.mjs';
+import { writeDocsAiFileAtomic } from './atomic-write.mjs';
+
+// A typed STOP — a deliberate refusal we surface (deployment gate / symlinked leaf), distinct from a
+// native fs error. `Object.assign(new Error(), { code })`, the codebase's typed-error idiom (no classes).
+export const AUTONOMY_WRITE_STOP = 'AUTONOMY_WRITE_STOP';
+const stop = (message) => Object.assign(new Error(`[agent-workflow-kit] ${message}`), { name: 'AutonomyWriteStop', code: AUTONOMY_WRITE_STOP });
+
+// writeAutonomy(cwd, config, deps) → { writtenPath } on success; THROWS a typed STOP (no deployment /
+// symlinked leaf) or a native fs error otherwise. The tmp is cleaned up on any failure after its
+// creation. config is serialized canonically (serializeAutonomy: 2-space, _README-first, trailing NL).
+export const writeAutonomy = (cwd, config, deps = {}) =>
+  writeDocsAiFileAtomic(cwd, AUTONOMY_REL, serializeAutonomy(config), deps, { stop, noun: 'a policy' });

package/tools/bridge-settings-read.mjs

@@ -0,0 +1,221 @@
+// bridge-settings-read.mjs — the READ-ONLY core of the host-level bridge settings surface (bridges
+// 2.3.0, D6). Split out from bridge-settings.mjs so the read-only status/advisor consumers
+// (family-registry, recipes --status-line, procedures) can surface settings facts WITHOUT importing
+// the writer (which pulls in the atomic-write core — forbidden in a read-only module, pinned by the
+// procedures import guard). It reads: the settings-file path, the file's state, the parsed KEY=VALUE
+// lines, the manifest-as-source registry (the union of the bundled bridges' `settings` blocks), and
+// the effective value of each knob (env > file > built-in default). It NEVER writes.
+//
+// Dependency-free, Node >= 18. No side effects on import.
+
+import { readFileSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { FAMILY_MEMBERS } from './family-members.mjs';
+import { resolveDir } from './detect-backends.mjs';
+import { settingValueValid, SETTING_KINDS } from './manifest/validate.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+// bridges/ ships beside tools/ in both the repo and the installed kit, so this resolves in both.
+export const DEFAULT_BUNDLE_ROOT = resolve(__dirname, '..', 'bridges');
+export const SETTINGS_XDG = { env: 'XDG_CONFIG_HOME', default: '~/.config' };
+export const SETTINGS_SUBDIR = 'agent-workflow';
+export const SETTINGS_FILENAME = 'bridge-settings.conf';
+// A valid settings line: an UPPER/lower_snake KEY (the wrappers' own `^[A-Za-z_][A-Za-z0-9_]*=`) then
+// everything after the first `=` as the value. Anchored at column 0, exactly like the wrappers' grep.
+export const KEY_LINE_RE = /^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/;
+
+// A typed refusal we surface. `exitCode` lets a CLI map it to the process code without matching text.
+export const fail = (exitCode, message) =>
+  Object.assign(new Error(`[agent-workflow-kit] ${message}`), { name: 'BridgeSettingsError', exitCode });
+
+// ── the registry (manifest-as-source) ───────────────────────────────────────────────
+
+// The bundled execution-backend bridge dirs (derived, never hardcoded — a future bridge joins here by
+// its family-members row, not an edit).
+const bridgeDirs = (ctx) =>
+  FAMILY_MEMBERS
+    .filter((m) => m.kind === 'execution-backend')
+    .map((m) => ({ name: m.name, dir: join(ctx.bundleRoot ?? DEFAULT_BUNDLE_ROOT, m.name) }));
+
+// Load the union of both bridges' `settings` blocks → a Map keyed by settings key, each entry carrying
+// its typed rule + the owning bridge. A missing/corrupt bundle is a loud STOP (a writer cannot be
+// honored without a trustworthy allowlist; a reader/snapshot caller catches it to degrade). The
+// registry is validated at build time (manifest validate --strict + the mirror drift-guard); here we
+// only guard fs/JSON errors and the block's basic shape.
+export const loadRegistry = (ctx) => {
+  const read = ctx.readFile ?? readFileSync;
+  const byKey = new Map();
+  for (const { name, dir } of bridgeDirs(ctx)) {
+    const manifestPath = join(dir, 'capability.json');
+    const manifest = (() => {
+      try {
+        return JSON.parse(String(read(manifestPath, 'utf8')));
+      } catch (err) {
+        throw fail(1, `cannot read the bundled bridge manifest ${manifestPath} (${err.code ?? err.message}) — corrupt kit install?`);
+      }
+    })();
+    const settings = manifest.settings ?? [];
+    if (!Array.isArray(settings)) throw fail(1, `bundled ${name} manifest \`settings\` is not an array — corrupt kit install?`);
+    for (const entry of settings) {
+      if (!entry || typeof entry.key !== 'string' || !SETTING_KINDS.has(entry.kind)) {
+        throw fail(1, `bundled ${name} manifest carries a malformed settings entry — corrupt kit install?`);
+      }
+      byKey.set(entry.key, { ...entry, bridge: name });
+    }
+  }
+  return byKey;
+};
+
+// A one-line, fact-only description of a knob's allowed values (from its typed rule) for help/preview.
+export const allowedLabel = (entry) => {
+  switch (entry.kind) {
+    case 'enum': return entry.values.map((v) => `"${v}"`).join(' | ');
+    case 'integer': return `integer ${entry.min}..${entry.max}`;
+    case 'duration': return 'duration (e.g. 5m, 30m, 90s — a unit is required, nonzero)';
+    case 'boolean': return '"0" | "1"';
+    default: return entry.kind;
+  }
+};
+
+// ── the settings file ────────────────────────────────────────────────────────────────
+
+export const settingsDir = (ctx) => join(resolveDir(SETTINGS_XDG, ctx.getenv ?? process.env, ctx.home ?? homedir()), SETTINGS_SUBDIR);
+export const settingsPath = (ctx) => join(settingsDir(ctx), SETTINGS_FILENAME);
+
+// Lines with a single trailing newline normalized away, so edits operate on an exact line array and
+// re-serialize with one trailing newline (comments/blank lines in the middle survive verbatim).
+export const splitLines = (text) => {
+  if (text === '') return [];
+  const parts = text.split('\n');
+  if (parts[parts.length - 1] === '') parts.pop();
+  return parts;
+};
+export const joinLines = (lines) => (lines.length ? `${lines.join('\n')}\n` : '');
+
+// Read the file's STATE the SAME way the wrappers do — `stat` (FOLLOW symlinks), matching their
+// `-e`/`-f`/`-r` guard EXACTLY so the reader/status/reconcile reflect what the wrappers actually use:
+// 'absent' (missing OR a dangling symlink — silent, defaults apply, like the wrapper's `-e`), 'unusable'
+// (a directory / FIFO / unreadable target — the wrapper's `-f`/`-r` false → warn + defaults), or
+// 'present' with its text (a regular file OR a symlink-to-regular — the wrapper reads it). The WRITER
+// stays secure regardless: the atomic core refuses a symlinked leaf (a write would clobber the target),
+// so a symlinked config is READ (matching the wrappers) but never written THROUGH.
+export const readFileState = (path, ctx) => {
+  const stat = ctx.stat ?? statSync;
+  const read = ctx.readFile ?? readFileSync;
+  const st = (() => {
+    try {
+      return stat(path);
+    } catch (err) {
+      if (err && err.code === 'ENOENT') return null;
+      return 'error';
+    }
+  })();
+  if (st === null) return { state: 'absent' };
+  if (st === 'error' || !st.isFile()) return { state: 'unusable' };
+  try {
+    return { state: 'present', text: String(read(path, 'utf8')) };
+  } catch {
+    return { state: 'unusable' };
+  }
+};
+
+// Parse a settings file body → valid KEY= entries (in order), malformed lines, and a key→entries map.
+export const parseSettings = (text) => {
+  const lines = splitLines(text);
+  const entries = [];
+  const malformed = [];
+  lines.forEach((line, index) => {
+    const noLeadWs = line.replace(/^[\s]+/, '');
+    if (noLeadWs === '' || noLeadWs.startsWith('#')) return; // blank / comment (indented ok)
+    const m = line.match(KEY_LINE_RE);
+    if (!m) {
+      malformed.push({ index, text: line });
+      return;
+    }
+    entries.push({ key: m[1], value: m[2], index });
+  });
+  const byKey = new Map();
+  for (const e of entries) {
+    if (!byKey.has(e.key)) byKey.set(e.key, []);
+    byKey.get(e.key).push(e);
+  }
+  return { lines, entries, malformed, byKey };
+};
+
+export const duplicateKeys = (parsed) => [...parsed.byKey.entries()].filter(([, es]) => es.length > 1).map(([k]) => k);
+
+// ── effective-value resolution (env > file > built-in default) ────────────────────────
+
+// The effective value of one knob + where it comes from. Fact-only; never a model claim.
+export const effectiveOf = (entry, parsed, getenv) => {
+  const key = entry.key;
+  if (Object.prototype.hasOwnProperty.call(getenv, key)) {
+    const v = getenv[key];
+    // An EXPLICITLY-EMPTY env (`KEY=`) suppresses the FILE override for this run (the wrapper skips a
+    // key already present in env, `${!key+x}`), so the effective value falls to the WRAPPER BUILT-IN —
+    // NOT "flag absent" (only the tier's built-in default happens to be "no flag"; the timeout / bytes /
+    // add-dir knobs fall to their real built-in default). Report the manifest default (null ⇒ "wrapper
+    // built-in applies"), not a misleading null-for-everything.
+    if (v === '') return { value: entry.default, source: 'default', note: 'the env KEY= suppresses the file override — the wrapper built-in applies' };
+    // Mirror the wrapper: an ENUM knob (the service tier) validates its ENV value too — codex accepts
+    // any `-c service_tier` string silently, so the wrapper drops an unsupported one to the built-in
+    // default (codex-exec.sh:188). A non-enum env value is the operator's documented RAW override (e.g.
+    // a timeout(1) duration like `2h` the wrapper passes straight through) — shown as-is (D3 scopes
+    // typed validation to FILE lines; the Phase-1 council refuted validating non-enum env usage).
+    if (entry.kind === 'enum' && !settingValueValid(entry, v)) {
+      return { value: entry.default, source: 'default', note: `env value "${v}" is not a supported ${key} — the wrapper runs the built-in default` };
+    }
+    return { value: v, source: 'env' };
+  }
+  const fileEntries = parsed.byKey.get(key);
+  if (fileEntries && fileEntries.length) {
+    const v = fileEntries[fileEntries.length - 1].value; // last occurrence wins
+    if (settingValueValid(entry, v)) return { value: v, source: 'file' };
+    return { value: entry.default, source: 'default', note: `file value "${v}" is invalid — falls back to the built-in default` };
+  }
+  return { value: entry.default, source: 'default' };
+};
+
+export const displayValue = (v) => (v == null ? '(unset — wrapper built-in applies)' : v);
+
+// ── the fact-only snapshot the read-only status/advisor surfaces consume ────────────────
+
+// Best-effort, never throws: the ACTIVE knobs (a non-default value is in play — source env/file,
+// non-null) plus file presence + any unknown/duplicate keys. Model/effort are structurally excluded
+// from the registry, so `active` can NEVER carry a model claim (the fact-only guarantee). A corrupt
+// bundle or fs error degrades to `{ error }` — the caller renders that localized-on-error, never crashes.
+export const settingsSnapshot = (ctx = {}) => {
+  try {
+    const registry = loadRegistry(ctx);
+    const path = settingsPath(ctx);
+    const fileState = readFileState(path, ctx);
+    // A symlink / non-regular / unreadable file is IGNORED by the wrappers (built-in defaults apply) —
+    // surface that honestly instead of silently omitting it (the wrappers warn; the status must too).
+    if (fileState.state === 'unusable') {
+      return { path, fileState: 'unusable', active: [], unknown: [], duplicates: [], error: 'the settings file is a symlink / not a regular file — ignored, built-in defaults apply' };
+    }
+    const parsed = parseSettings(fileState.text ?? '');
+    const getenv = ctx.getenv ?? process.env;
+    const active = [];
+    for (const entry of registry.values()) {
+      const eff = effectiveOf(entry, parsed, getenv);
+      // ACTIVE = a non-default value is genuinely in effect (source env/file AND differs from the
+      // built-in default). A value that merely equals the default keeps every surface byte-identical to
+      // "nothing set" — the "status line unchanged unless a knob is active" contract.
+      if ((eff.source === 'env' || eff.source === 'file') && eff.value != null && eff.value !== entry.default) {
+        active.push({ key: entry.key, value: eff.value, source: eff.source, bridge: entry.bridge });
+      }
+    }
+    return {
+      path,
+      fileState: fileState.state,
+      active,
+      unknown: [...parsed.byKey.keys()].filter((k) => !registry.has(k)),
+      duplicates: duplicateKeys(parsed),
+    };
+  } catch (err) {
+    return { error: err && err.message ? err.message : String(err), active: [] };
+  }
+};