@sabaiway/agent-workflow-kit 1.34.0 → 1.35.0

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: [] };
+  }
+};

package/tools/bridge-settings.mjs

@@ -0,0 +1,288 @@
+#!/usr/bin/env node
+// bridge-settings.mjs — the reader + consent-gated WRITER for the host-level bridge settings file
+// (bridges 2.3.0, D6). The four bridge wrappers READ ${XDG_CONFIG_HOME:-~/.config}/agent-workflow/
+// bridge-settings.conf (KEY=VALUE lines, parsed never sourced; env > file > built-in default); this is
+// the ONLY writer for it. It lives OUTSIDE every kit-managed tree, so a kit refresh never touches it
+// (D2 — upgrade-survival is structural). The allowlist + typed validation come from the BUNDLED bridge
+// manifests' `settings` blocks (manifest-as-source): the tool never invents a key or a value rule, and
+// what it writes always passes the wrappers' own aw_settings_valid (the shared settingValueValid).
+//
+// Posture (D3, guarded): PREVIEW BY DEFAULT; --apply writes. It refuses an unknown key, an invalid /
+// out-of-range value, and — loudly, naming the key — a file that already carries DUPLICATE keys (it
+// never emits duplicates and never edits blindly around them). It touches only the KEY= line it owns,
+// preserving every comment/blank/other line verbatim, and creates the dir + file on first apply via
+// the hardened out-of-tree atomic writer (symlink/parent/TOCTOU-safe). Model/effort are NOT in the
+// allowlist — the wrappers' quality-first guard is untouched (D4). CODEX_SERVICE_TIER carries the
+// credit-rate caveat wherever it renders (from the manifest `effect`).
+//
+// Output is ENGLISH/structured (repo-artifact Hard Constraint); the agent localizes when narrating.
+// Exit codes: 0 success (reader, preview, or apply); 2 usage (bad args / unknown key / invalid value);
+// 1 precondition STOP (duplicate-carrying / symlinked / unreadable file, a write STOP) or a corrupt
+// bundle (cannot determine the allowlist). main(argv, ctx) → { code, stdout, stderr }; getenv / home /
+// bundleRoot / fs are injectable for host-independent tests.
+//
+// Dependency-free, Node >= 18. No side effects on import (the isDirectRun idiom).
+
+import { pathToFileURL } from 'node:url';
+import { settingValueValid } from './manifest/validate.mjs';
+import { writeHostConfigFileAtomic } from './atomic-write.mjs';
+import {
+  SETTINGS_SUBDIR, SETTINGS_FILENAME, fail, loadRegistry, allowedLabel, settingsDir, settingsPath,
+  joinLines, readFileState, parseSettings, duplicateKeys, effectiveOf, displayValue,
+} from './bridge-settings-read.mjs';
+
+// ── reader render ──────────────────────────────────────────────────────────────────
+
+const renderReader = (registry, parsed, fileState, ctx, path) => {
+  const getenv = ctx.getenv ?? process.env;
+  const lines = [`bridge settings — ${path}`];
+  if (fileState.state === 'absent') lines.push('  (no settings file yet — every knob is at its built-in default)');
+  else if (fileState.state === 'unusable') lines.push('  ⚠ the settings file is a symlink / not a regular file / unreadable — the wrappers ignore it and fall back to built-in defaults');
+  lines.push('', '  effective knobs (env > file > built-in default):');
+  for (const entry of registry.values()) {
+    const eff = effectiveOf(entry, parsed, getenv);
+    const note = eff.note ? `  — ${eff.note}` : '';
+    lines.push(`    ${entry.key} = ${displayValue(eff.value)}  [${eff.source}]${note}`);
+    lines.push(`        ${entry.bridge} · ${allowedLabel(entry)} · ${entry.effect}`);
+  }
+  const dups = duplicateKeys(parsed);
+  const unknown = [...parsed.byKey.keys()].filter((k) => !registry.has(k));
+  if (dups.length) lines.push('', `  ⚠ duplicate keys in the file (last wins at read time; the writer refuses to edit until you fix these): ${dups.join(', ')}`);
+  if (unknown.length) lines.push('', `  ⚠ unknown keys (ignored by every wrapper): ${unknown.join(', ')}`);
+  if (parsed.malformed.length) lines.push('', `  ⚠ malformed lines (ignored): ${parsed.malformed.map((m) => `line ${m.index + 1}`).join(', ')}`);
+  lines.push('', `  edit with:  /agent-workflow-kit bridge-settings --set KEY=VALUE   (preview; add --apply to write)`);
+  return lines.join('\n');
+};
+
+const buildReaderJson = (registry, parsed, fileState, ctx, path) => {
+  const getenv = ctx.getenv ?? process.env;
+  return {
+    path,
+    fileState: fileState.state,
+    knobs: [...registry.values()].map((entry) => {
+      const eff = effectiveOf(entry, parsed, getenv);
+      return { key: entry.key, bridge: entry.bridge, kind: entry.kind, effective: eff.value, source: eff.source, note: eff.note ?? null, default: entry.default };
+    }),
+    duplicateKeys: duplicateKeys(parsed),
+    unknownKeys: [...parsed.byKey.keys()].filter((k) => !registry.has(k)),
+    malformedLines: parsed.malformed.map((m) => m.index + 1),
+  };
+};
+
+// ── reconcile (the init/upgrade survival check — read-only, NEVER edits) ───────────────
+
+// Classify every file key against the NEW bundled manifests (the union registry), for the init
+// cascade + Mode: upgrade to run AFTER the bridge refresh. It NEVER writes: the file lives outside
+// every kit tree (D2), so upgrade-survival is structural — a key the new manifests no longer declare
+// (unknown / retired) is a loud flag, PRESERVED verbatim (the lens-region custom-edit posture). One
+// tool-composed line per outcome, printed verbatim by the caller. Throws only on a corrupt bundle
+// (cannot determine the allowlist) — the caller degrades that best-effort. Outcomes: absent · unusable
+// · flagged (unknown/retired keys) · duplicates · ok.
+export const reconcileSettings = (ctx = {}) => {
+  const registry = loadRegistry(ctx);
+  const path = settingsPath(ctx);
+  const fileState = readFileState(path, ctx);
+  if (fileState.state === 'absent') return { outcome: 'absent', lines: [`  bridge-settings: no settings file — skipped (${path})`] };
+  if (fileState.state === 'unusable') return { outcome: 'unusable', lines: [`  bridge-settings: settings file is a symlink / not a regular file — skipped, never edited (${path})`] };
+  const parsed = parseSettings(fileState.text);
+  const known = [...parsed.byKey.keys()].filter((k) => registry.has(k));
+  const unknown = [...parsed.byKey.keys()].filter((k) => !registry.has(k));
+  const dups = duplicateKeys(parsed);
+  const lines = [];
+  if (unknown.length) lines.push(`  bridge-settings: ${unknown.length} unknown/retired key(s) preserved verbatim (never edited) — compare with the current knobs when convenient: ${unknown.join(', ')}`);
+  if (dups.length) lines.push(`  bridge-settings: duplicate key(s) — the reader takes the last; fix by hand before the writer will edit: ${dups.join(', ')}`);
+  if (!unknown.length && !dups.length) lines.push(`  bridge-settings: ${known.length} key(s) recognized, all current`);
+  return { outcome: unknown.length ? 'flagged' : dups.length ? 'duplicates' : 'ok', lines };
+};
+
+// ── writer ─────────────────────────────────────────────────────────────────────────
+
+// argv → { ops, apply, dryRun, json }. `--set KEY=VALUE` / `--unset KEY` (inline `=` forms too). A
+// duplicate op for the same key, an unknown flag, or --dry-run WITH --apply → usage error (2). Order-
+// independent so a later flag never silently decides whether the tool mutates.
+const parseArgs = (argv) => {
+  const ops = [];
+  const seen = new Set();
+  const flags = { apply: false, dryRun: false, json: false };
+  const takeOp = (kind, tok) => {
+    if (tok === undefined || tok.startsWith('-')) throw fail(2, `--${kind} requires KEY${kind === 'set' ? '=VALUE' : ''}`);
+    if (kind === 'set') {
+      const eq = tok.indexOf('=');
+      if (eq <= 0) throw fail(2, `--set needs KEY=VALUE (got ${JSON.stringify(tok)})`);
+      const key = tok.slice(0, eq);
+      const value = tok.slice(eq + 1);
+      if (seen.has(key)) throw fail(2, `duplicate op for "${key}" — name each key at most once`);
+      seen.add(key);
+      ops.push({ kind, key, value });
+    } else {
+      const key = tok;
+      if (seen.has(key)) throw fail(2, `duplicate op for "${key}" — name each key at most once`);
+      seen.add(key);
+      ops.push({ kind, key });
+    }
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '--apply') flags.apply = true;
+    else if (a === '--dry-run') flags.dryRun = true;
+    else if (a === '--json') flags.json = true;
+    else if (a === '--set') { takeOp('set', argv[i + 1]); i += 1; }
+    else if (a === '--unset') { takeOp('unset', argv[i + 1]); i += 1; }
+    else if (a.startsWith('--set=')) takeOp('set', a.slice('--set='.length));
+    else if (a.startsWith('--unset=')) takeOp('unset', a.slice('--unset='.length));
+    else if (a.startsWith('-')) throw fail(2, `unknown flag: ${a}`);
+    else throw fail(2, `unexpected argument: ${a}`);
+  }
+  if (flags.apply && flags.dryRun) throw fail(2, '--apply does not combine with --dry-run (default is preview)');
+  return { ops, ...flags };
+};
+
+// Validate ops against the registry: an unknown key or an out-of-range/invalid value is refused (2)
+// BEFORE any file read, so a typo never reaches the settings file.
+const validateOps = (ops, registry) => {
+  for (const op of ops) {
+    const entry = registry.get(op.key);
+    if (!entry) throw fail(2, `unknown key "${op.key}" — not a settings knob of any bundled bridge. Known keys: ${[...registry.keys()].join(', ')}`);
+    if (op.kind === 'set' && !settingValueValid(entry, op.value)) {
+      throw fail(2, `invalid value "${op.value}" for ${op.key} — allowed: ${allowedLabel(entry)}`);
+    }
+  }
+};
+
+// Apply one op to the line array: replace the single owned KEY= line, append it, or drop it. The caller
+// guarantees the file carries no duplicate keys, so findIndex hits at most one line. `startsWith(KEY=)`
+// is exact (the `=` anchors it: `FOO_BAR=` never matches key `FOO`).
+const applyOp = (lines, op) => {
+  const idx = lines.findIndex((l) => l.startsWith(`${op.key}=`));
+  if (op.kind === 'set') {
+    const newLine = `${op.key}=${op.value}`;
+    return idx === -1 ? [...lines, newLine] : lines.map((l, i) => (i === idx ? newLine : l));
+  }
+  return idx === -1 ? lines : lines.filter((_, i) => i !== idx);
+};
+
+const changeLine = (c) => {
+  const b = c.before == null ? '(unset)' : c.before;
+  const a = c.kind === 'set' ? c.after : '(unset — built-in default applies)';
+  return `  ${c.key}: ${b} → ${a}`;
+};
+
+const renderWriter = ({ changes, wrote, path, willWrite, envShadows, caveats }) => {
+  const lines = [];
+  lines.push(wrote ? `wrote ${path}` : 'bridge-settings — preview (nothing written; re-run with --apply to write)');
+  for (const c of changes) lines.push(changeLine(c));
+  for (const cav of caveats) lines.push(`      ↳ ${cav}`);
+  for (const key of envShadows) lines.push(`  ⚠ ${key} is currently set in the environment — the env value overrides the file for this session (unset it, or it wins until you do).`);
+  if (!wrote && willWrite) lines.push('', `re-run with --apply to write ${path}.`);
+  if (!wrote && !willWrite) lines.push('  no change — the file already reads this way.');
+  return lines.join('\n');
+};
+
+// ── main ───────────────────────────────────────────────────────────────────────────
+
+const HELP = `bridge-settings — read / write the host-level bridge settings file.
+
+  ${'${XDG_CONFIG_HOME:-~/.config}'}/${SETTINGS_SUBDIR}/${SETTINGS_FILENAME}   (KEY=VALUE lines; parsed, never sourced)
+
+Usage:
+  node bridge-settings.mjs                          show every knob's effective value + source
+  node bridge-settings.mjs --set KEY=VALUE          preview a change (writes nothing)
+  node bridge-settings.mjs --set KEY=VALUE --apply  write the change (atomic; creates the file on first use)
+  node bridge-settings.mjs --unset KEY [--apply]    return a knob to its built-in default
+  node bridge-settings.mjs --json                   machine-readable read-out
+  node bridge-settings.mjs --reconcile              init/upgrade survival check: flag unknown/retired
+                                                    keys (preserved verbatim), never writes
+
+Precedence at run time: explicit env (even empty: KEY= disables) > this file > the wrapper's built-in
+default. Allowed keys + value rules come from the bundled bridge manifests; model/effort are NOT
+settable here (the wrappers' quality guard is untouched). This host file survives every kit upgrade —
+a kit refresh never writes or clobbers it.
+
+Exit codes: 0 success (read / preview / write); 2 usage (bad args, unknown key, invalid value);
+            1 precondition STOP (duplicate-carrying / symlinked / unreadable file, or a corrupt bundle).`;
+
+export const main = (argv = [], ctx = {}) => {
+  const getenv = ctx.getenv ?? process.env;
+  try {
+    if (argv.includes('--help') || argv.includes('-h')) return { code: 0, stdout: HELP, stderr: '' };
+    // Reconcile mode (init/upgrade survival check) — classify keys, never write, exit 0 on any outcome.
+    // It is a standalone mode: a write flag/op alongside it is a usage error, never silently ignored
+    // (a consent-gated writer never lets a stray flag make a caller think it wrote when it only classified).
+    if (argv.includes('--reconcile')) {
+      const extra = argv.filter((a) => a !== '--reconcile');
+      if (extra.length) throw fail(2, `--reconcile takes no other arguments (got ${extra.join(' ')}) — it only classifies keys, never writes`);
+      return { code: 0, stdout: reconcileSettings(ctx).lines.join('\n'), stderr: '' };
+    }
+    const { ops, apply, json } = parseArgs(argv);
+    const registry = loadRegistry(ctx);
+    const path = settingsPath(ctx);
+
+    // Reader (no ops): show effective settings. Best-effort — an unusable file warns but still exits 0.
+    if (ops.length === 0) {
+      const fileState = readFileState(path, ctx);
+      const parsed = parseSettings(fileState.text ?? '');
+      const stdout = json
+        ? JSON.stringify(buildReaderJson(registry, parsed, fileState, ctx, path), null, 2)
+        : renderReader(registry, parsed, fileState, ctx, path);
+      return { code: 0, stdout, stderr: '' };
+    }
+
+    // Writer. Validate the ops against the registry BEFORE the file is even read — a typo / unknown key /
+    // out-of-range value is refused (exit 2) without touching the file, exactly as the mode doc promises.
+    validateOps(ops, registry);
+    const fileState = readFileState(path, ctx);
+    if (fileState.state === 'unusable') {
+      throw fail(1, `the settings file is a symlink / not a regular file / unreadable — refusing to write through it: ${path}`);
+    }
+    const parsed = parseSettings(fileState.text ?? '');
+    const dups = duplicateKeys(parsed);
+    if (dups.length) {
+      throw fail(1, `the settings file already carries duplicate keys (${dups.join(', ')}) — refusing to edit it. Fix the duplicates by hand first: ${path}`);
+    }
+
+    const changes = ops.map((op) => {
+      const before = parsed.byKey.get(op.key)?.at(-1)?.value ?? null;
+      const after = op.kind === 'set' ? op.value : null;
+      return { key: op.key, kind: op.kind, before, after, entry: registry.get(op.key) };
+    });
+    const noop = changes.every((c) => (c.kind === 'set' ? c.before === c.after : c.before === null));
+    // The credit-rate / spend caveat rides with any knob whose manifest effect flags a cost (D4).
+    const caveats = changes
+      .filter((c) => c.kind === 'set' && /credit rate|SPEND KNOB/i.test(c.entry.effect))
+      .map((c) => `${c.key}: ${c.entry.effect}`);
+    const envShadows = changes
+      .filter((c) => Object.prototype.hasOwnProperty.call(getenv, c.key))
+      .map((c) => c.key);
+
+    const newLines = ops.reduce(applyOp, parsed.lines);
+    const body = joinLines(newLines);
+
+    // The machine surface carries the SAME spend/credit-rate caveats the human preview prints (D4) — a
+    // --json consumer must not miss the 2.5x-credit consent warning the human render shows.
+    const jsonBody = (wrote) => ({ path, wrote, noop, changes: changes.map((c) => ({ key: c.key, kind: c.kind, before: c.before, after: c.after })), envShadows, caveats });
+
+    if (!apply || noop) {
+      const stdout = json
+        ? JSON.stringify(jsonBody(false), null, 2)
+        : renderWriter({ changes, wrote: false, path, willWrite: !noop, envShadows, caveats });
+      return { code: 0, stdout, stderr: '' };
+    }
+
+    // --apply. The out-of-tree atomic writer creates the dir + file on first use; symlink/parent/TOCTOU-safe.
+    writeHostConfigFileAtomic(settingsDir(ctx), SETTINGS_FILENAME, body, ctx, { noun: 'the bridge settings file' });
+    const stdout = json
+      ? JSON.stringify(jsonBody(true), null, 2)
+      : renderWriter({ changes, wrote: true, path, willWrite: false, envShadows, caveats });
+    return { code: 0, stdout, stderr: '' };
+  } catch (err) {
+    return { code: err.exitCode ?? 1, stdout: '', stderr: `bridge-settings: ${err.message}` };
+  }
+};
+
+const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isDirectRun) {
+  const r = main(process.argv.slice(2));
+  if (r.stdout) console.log(r.stdout);
+  if (r.stderr) console.error(r.stderr);
+  process.exit(r.code);
+}

package/tools/commands.mjs

@@ -126,6 +126,13 @@ const CATALOG = [
     kind: WRITER,
     oneLine: 'Auto-approve your own declared gate commands (docs/ai/gates.json) via a Claude Code hook — exact matches only, previews first (opt-in).',
   },
+  {
+    key: 'bridge-settings',
+    invocation: invocationOf('bridge-settings'),
+    group: 'Configure',
+    kind: GUARDED,
+    oneLine: 'Read or change the host-level bridge settings (e.g. the codex Fast tier) — a KEY=VALUE file that survives kit upgrades; previews first, and the Fast tier carries its extra-cost caveat.',
+  },
   {
     key: 'recipes',
     invocation: invocationOf('recipes'),

package/tools/family-registry.mjs

@@ -47,6 +47,9 @@ import {
 // The gate-hook writer's own wired-detection + placed path — reused by the settings survey (one
 // implementation; gate-hook imports only node builtins + velocity-profile, so no cycle).
 import { HOOK_FILE_REL as GATE_HOOK_FILE_REL, isHookWired } from './gate-hook.mjs';
+// The host-level bridge-settings snapshot (fact-only, best-effort). The READ-ONLY core (never the
+// writer, which pulls in the atomic-write core) so the status survey stays a pure reader.
+import { settingsSnapshot } from './bridge-settings-read.mjs';
 import { GATES_REL, loadDeclaration } from './run-gates.mjs';
 // The cheap-agents writer's own bundle reader + placement planner — reused by the settings survey
 // (one implementation, never a drifting copy; cheap-agents imports only node builtins, no cycle).
@@ -513,12 +516,20 @@ export const surveySettings = (dir, deps = {}) => ({
 export const surveyBridges = (deps = {}) => {
   const { detection } = detectSafe(deps); // a detector failure → every readiness reads 'unknown' (honest)
   const probe = deps.findOnPath ?? findOnPath;
+  // Host-level bridge settings, read ONCE (best-effort — never throws; a corrupt bundle/fs error → error).
+  const snapshot = settingsSnapshot(deps);
   return FAMILY_MEMBERS.filter((m) => m.kind === 'execution-backend').map((m) => {
     const det = detection.find((d) => d.name === m.name);
     // Preserve findOnPath's THREE-state result (present | missing | unknown): an `unknown` (EACCES,
     // "cannot confirm") must stay distinct from a real `missing` — never flattened to a false boolean.
     const wrappers = m.wrapperCmds.map((cmd) => ({ cmd, state: probe(cmd, deps).state }));
-    return { member: m.name, display: displayOf(m.name), readiness: det?.readiness ?? 'unknown', wrappers };
+    // Fact-only: the settings knobs ACTIVE (env/file, non-default) for THIS bridge. Model/effort are
+    // structurally absent from the registry, so this can NEVER carry a model claim (the survey's
+    // no-default-model-claim invariant). Localized-on-error like every other survey.
+    const settings = snapshot.error
+      ? { error: snapshot.error }
+      : { active: snapshot.active.filter((a) => a.bridge === m.name) };
+    return { member: m.name, display: displayOf(m.name), readiness: det?.readiness ?? 'unknown', wrappers, settings };
   });
 };
 

package/tools/manifest/schema.md

@@ -17,6 +17,7 @@ expansion), never via the shell. The validator is [`validate.mjs`](./validate.mj
 | `provides` | string[] | yes | subset of the **role vocabulary** |
 | `roles` | object | yes | keys ⊆ `provides`; see *Roles* |
 | `detect` | object | no | `installed` (skill on the machine) + `deployed` (substrate set up in cwd) |
+| `settings` | array | no | the bridge's **settings-file surface** (typed; see *Settings*). Unlike `contract`, a malformed entry **fails** `--strict`. |
 | `install` / `uninstall` | object | no | `install.npm` is a package name, not a path |
 | `cost` / `quota` / `provenance` | misc | no | informational |
 | `available` | boolean | no | `false` = a declared-but-not-installed stub; skips fs/version checks |
@@ -54,6 +55,36 @@ Each `roles.<role>` is an object:
     `{ policy: "guarded", blocked: string[], probeRelaxed: string[] }`, matching the wrapper's
     real case-arm patterns (pinned by the source-level reverse-guard test).
 
+## Settings (bridges 2.3.0, D6 — manifest-as-source)
+
+`settings` declares the bridge's host-level settings-file surface
+(`${XDG_CONFIG_HOME:-~/.config}/agent-workflow/bridge-settings.conf`). It is an **array** of
+typed entries — a JSON object would silently dedupe duplicate keys under `JSON.parse` — and,
+unlike `contract`, it is validated by `validate.mjs` itself: a malformed entry **fails**
+`--strict` (the kit writer, the status renderers, and the wrapper shell constants all consume
+this block). Each entry:
+
+- `key` (string, required) — UPPER_SNAKE_CASE env-var name; unique across the array.
+- `kind` (string, required) — `enum | integer | duration | boolean`.
+  - `enum` → `values` (string[], non-empty, unique).
+  - `integer` → `min` / `max` (safe integers, `min <= max`); values are decimal strings.
+  - `duration` → the wrappers' shell duration grammar (`5m`, `30m`, `90s`): a unit suffix
+    (`s|m|h|d`) is **required** — a bare integer is invalid — and **zero durations are
+    rejected** (`timeout 0` would silently DISABLE a hard cap).
+  - `boolean` → the pinned wire format `"0" | "1"` (exactly what the wrappers' env vars accept).
+- `default` (string|null, **required property** — a missing key fails validation) — `null` = no
+  file default, the wrapper built-ins apply (state them in `effect`); a non-null default must
+  itself pass the kind's validation.
+- `appliesTo` (string[], required) — the wrapper `cmd` names (from `roles.*.cmd` of THIS
+  manifest) that APPLY the key. Every wrapper still RECOGNIZES the whole family registry (the
+  union of both bridges' `settings` keys) and skips other wrappers' keys silently.
+- `effect` (string, required) — what the knob does, incl. built-in defaults and any spend/risk
+  caveat (the credit-rate caveat rides here for the tier knob).
+
+Wrappers never parse JSON at run time: each carries its own shell registry/validation constants,
+drift-guarded set-equal to this block by the bridge `bin/*.test.mjs` suites (help section keys,
+`aw_settings_known` registry, `AW_SETTINGS_APPLIED` subset, `aw_settings_valid` typed arms).
+
 ## Path-field rules (Windows-safe, traversal-safe)
 
 - **No absolute paths**, **no `..` traversal**, **no unresolved placeholders** (`{{…}}` / `${…}`)