@sabaiway/agent-workflow-kit 1.33.0 → 1.35.0

package/tools/atomic-write.mjs

@@ -0,0 +1,144 @@
+// atomic-write.mjs — the family's ONE hardened atomic-write core for kit writers. Extracted from
+// orchestration-write.mjs (the only full implementation of the discipline, AD-042) and parameterized
+// by (containment ROOT, absolute target, body, stop identity) so every consumer runs the same guarded
+// flow with zero drift:
+//   • writeDocsAiFileAtomic  — a file under a project's docs/ai/ (deployment-gated to cwd):
+//       orchestration-write.mjs → docs/ai/orchestration.json; seed-gates.mjs → docs/ai/gates.json.
+//   • writeHostConfigFileAtomic — a file under a host config dir OUTSIDE any project tree
+//       (bridges 2.3.0, D6): ${XDG_CONFIG_HOME:-~/.config}/agent-workflow/bridge-settings.conf. The
+//       host dir is CREATED if absent (a host config SHOULD materialize), unlike the docs/ai gate
+//       which REFUSES an absent deployment.
+//
+// The discipline (verbatim from the source implementation) — writeContainedFileAtomic(root, dst, …):
+//   - a per-consumer GATE runs first (deployment gate for docs/ai; create+verify for the host dir).
+//   - refuse a SYMLINKED leaf — a rename would silently replace the link target.
+//   - guard the dst + the tmp sibling with assertContainedRealPath (fs-safe) — refuses a symlinked
+//     PARENT component inside `root`, not just the leaf, and refuses any escape outside `root`.
+//   - atomic: write a UNIQUE *.<rand>.tmp opened EXCLUSIVE-CREATE (wx), then rename over the dst.
+//   - RE-CHECK the parent chain + the leaf immediately before the rename (TOCTOU).
+//   - tmp cleaned up on any failure after its creation.
+//   - LAST-WRITER-WINS: local, single-user; no cross-process lock (documented, not silently assumed).
+//
+// Dependency-free, Node >= 18. Every fs primitive is injectable (deps.*) so the guards are
+// unit-testable. NEVER imported by a read-only module (procedures.mjs — pinned by an import guard).
+
+import { lstatSync, writeFileSync, renameSync, rmSync, mkdirSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import { join } from 'node:path';
+import { assertContainedRealPath } from './fs-safe.mjs';
+
+export const ATOMIC_WRITE_STOP = 'ATOMIC_WRITE_STOP';
+const defaultStop = (message) =>
+  Object.assign(new Error(`[agent-workflow-kit] ${message}`), { name: 'AtomicWriteStop', code: ATOMIC_WRITE_STOP });
+
+// lstat without following symlinks; null when absent. A non-ENOENT error propagates (never fail open).
+export const lstatNoFollow = (path, lstat = lstatSync) => {
+  try {
+    return lstat(path);
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return null;
+    throw err;
+  }
+};
+
+// Deployment gate — never scatter a file into a non-deployed repo. lstat, NOT existsSync:
+// existsSync FOLLOWS a symlink, so a DANGLING `docs/ai` symlink would read as "absent" and
+// mislabel a broken/symlinked deployment as "no deployment". lstat the leaf instead: a true
+// ENOENT → no deployment (STOP, run init); a symlink or non-directory → STOP loud.
+// `noun` names what the caller writes ("a config" / "a gate declaration") so each consumer's STOP
+// message stays exactly as its own tests pinned it.
+export const assertDocsAiDeployment = (cwd, deps = {}, opts = {}) => {
+  const lstat = deps.lstat ?? lstatSync;
+  const stop = opts.stop ?? defaultStop;
+  const noun = opts.noun ?? 'a file';
+  const rel = opts.rel ?? 'under docs/ai';
+  const docsAi = join(cwd, 'docs', 'ai');
+  const docsAiStat = lstatNoFollow(docsAi, lstat);
+  if (docsAiStat === null) {
+    throw stop(`no agent-workflow deployment here (docs/ai is absent) — run init/bootstrap before writing ${rel}`);
+  }
+  if (docsAiStat.isSymbolicLink()) {
+    throw stop(`docs/ai is a symlink — refusing to write ${noun} through it (run init/bootstrap in a real deployment)`);
+  }
+  if (!docsAiStat.isDirectory()) {
+    throw stop(`docs/ai exists but is not a directory — refusing to write ${rel}`);
+  }
+};
+
+// Host config dir gate — CREATE the dir if absent (a host config SHOULD materialize on first write,
+// the opposite of the docs/ai deployment gate), then refuse a symlinked / non-directory dir we would
+// write THROUGH (a rename into a symlinked dir would land outside where the user thinks). `noun` names
+// what the caller writes so each consumer's STOP message stays exactly as its own tests pinned it.
+export const assertHostConfigDirSafe = (dir, deps = {}, opts = {}) => {
+  const lstat = deps.lstat ?? lstatSync;
+  const mkdir = deps.mkdir ?? ((p) => mkdirSync(p, { recursive: true }));
+  const stop = opts.stop ?? defaultStop;
+  const noun = opts.noun ?? 'a host config file';
+  mkdir(dir);
+  const st = lstatNoFollow(dir, lstat);
+  if (st === null) throw stop(`could not create the host config dir: ${dir}`);
+  if (st.isSymbolicLink()) throw stop(`${dir} is a symlink — refusing to write ${noun} through it`);
+  if (!st.isDirectory()) throw stop(`${dir} exists but is not a directory — refusing to write ${noun}`);
+};
+
+// The hardened atomic flow, parameterized by containment ROOT + an already-passed gate. `dst` is the
+// ABSOLUTE target under `root`; `opts.label` names it in a symlink-refusal message. Returns
+// { writtenPath: dst }. THROWS the caller's typed STOP (opts.stop) or a native fs error.
+export const writeContainedFileAtomic = (root, dst, body, deps = {}, opts = {}) => {
+  const lstat = deps.lstat ?? lstatSync;
+  const writeFile = deps.writeFile ?? writeFileSync;
+  const rename = deps.rename ?? renameSync;
+  const rm = deps.rm ?? ((p) => rmSync(p, { force: true }));
+  const rand = deps.rand ?? (() => randomBytes(6).toString('hex'));
+  const stop = opts.stop ?? defaultStop;
+  const label = opts.label ?? dst;
+  const guard = (target) => assertContainedRealPath(root, target, { lstat });
+
+  // Refuse a symlinked leaf with a CLEAR message before the generic traversal guard fires (a rename
+  // would silently replace the link rather than the file the user thinks they are editing).
+  const leaf = lstatNoFollow(dst, lstat);
+  if (leaf && leaf.isSymbolicLink()) {
+    throw stop(`${label} is a symlink — refusing to replace it (a write would clobber the link target)`);
+  }
+  // Guard the dst + a unique tmp SIBLING: refuses a symlinked parent component inside root, and any escape.
+  guard(dst);
+  const tmp = `${dst}.${rand()}.tmp`;
+  guard(tmp);
+
+  // Exclusive-create (wx): never clobber a leftover tmp (a stray collision is surfaced, not silently
+  // overwritten). The random suffix makes a collision effectively impossible; wx makes it impossible-loud.
+  writeFile(tmp, body, { encoding: 'utf8', flag: 'wx' });
+  try {
+    // TOCTOU re-check: the parent chain + the leaf may have changed since the pre-checks above.
+    guard(dst);
+    const leafAgain = lstatNoFollow(dst, lstat);
+    if (leafAgain && leafAgain.isSymbolicLink()) {
+      throw stop(`${label} became a symlink — refusing to replace it`);
+    }
+    rename(tmp, dst);
+  } catch (err) {
+    rm(tmp); // never leave a temp file behind on failure
+    throw err;
+  }
+  return { writtenPath: dst };
+};
+
+// writeDocsAiFileAtomic(cwd, rel, body, deps, opts) → { writtenPath: rel } on success; THROWS the
+// caller's typed STOP (via opts.stop) or a native fs error otherwise. `body` arrives pre-serialized
+// (each consumer owns its canonical serialization). Thin wrapper over the core: gate = deployment
+// gate, root = cwd, target = cwd/rel; the label + return stay `rel` so its public API is unchanged.
+export const writeDocsAiFileAtomic = (cwd, rel, body, deps = {}, opts = {}) => {
+  assertDocsAiDeployment(cwd, deps, { ...opts, rel });
+  const dst = join(cwd, rel);
+  writeContainedFileAtomic(cwd, dst, body, deps, { ...opts, label: rel });
+  return { writtenPath: rel };
+};
+
+// writeHostConfigFileAtomic(dir, filename, body, deps, opts) → { writtenPath: dir/filename }. Gate =
+// create+verify the host dir; root = that dir; target = dir/filename. For the out-of-tree host config
+// surface (bridge-settings.conf) that no project deployment owns.
+export const writeHostConfigFileAtomic = (dir, filename, body, deps = {}, opts = {}) => {
+  assertHostConfigDirSafe(dir, deps, opts);
+  const dst = join(dir, filename);
+  return writeContainedFileAtomic(dir, dst, body, deps, { ...opts, label: opts.label ?? dst });
+};

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);
+}