@sabaiway/agent-workflow-kit 1.34.0 → 1.36.0

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'),
@@ -147,6 +154,13 @@ const CATALOG = [
     kind: WRITER,
     oneLine: 'Set the orchestration recipe for an activity from plain language — previews the change, then writes the config when you confirm.',
   },
+  {
+    key: 'set-autonomy',
+    invocation: invocationOf('set-autonomy'),
+    group: 'Orchestrate',
+    kind: WRITER,
+    oneLine: 'Set the per-project autonomy policy from plain language — which actions always ask (commit/push/publish/network) and how autonomously each activity runs; previews the change, then writes the policy when you confirm.',
+  },
   {
     key: 'review-state',
     invocation: invocationOf('review-state'),
@@ -161,6 +175,13 @@ const CATALOG = [
     kind: WRITER,
     oneLine: 'Assemble the verified-facts payload a grounded review runs against — the entry-point Hard Constraints plus a plan’s decision sections; prints it, or writes ONE scratch file with --out.',
   },
+  {
+    key: 'review-ledger',
+    invocation: invocationOf('review-ledger'),
+    group: 'Orchestrate',
+    kind: WRITER,
+    oneLine: 'Record each review round and read the computed crossover-stop for the plan-execution loop (converged / accepted-residual / triage-required); --check turns it into a gate exit code and forces a triage before over-running the review.',
+  },
 ];
 
 // Deep-freeze: freeze the array AND every entry, so the catalog is genuinely immutable at runtime

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** (`{{…}}` / `${…}`)

package/tools/manifest/validate.mjs

@@ -36,6 +36,30 @@ export const VALID = 'valid';
 export const UNSUPPORTED = 'unsupported';
 export const INVALID = 'invalid';
 
+// Typed settings-value grammar (D6, bridges 2.3.0) — the ONE predicate the manifest validator (for a
+// declared `default`), the kit-side bridge-settings writer (for a user-supplied value), and — mirrored
+// in shell as aw_settings_valid — the wrappers all use, so a value the writer accepts is exactly a
+// value a wrapper honors. A value is always compared as a STRING (the settings-file wire format).
+export const SETTING_KINDS = new Set(['enum', 'integer', 'duration', 'boolean']);
+// The wrappers' shell duration grammar: a unit suffix is REQUIRED (a bare integer is invalid), and
+// zero durations are rejected — `timeout 0` DISABLES a hard cap, so a persistent settings line could
+// otherwise silently remove the stall guard.
+export const DURATION_RE = /^[0-9]+(\.[0-9]+)?[smhd]$/;
+export const ZERO_DURATION_RE = /^0+(\.0+)?[smhd]$/;
+export const settingValueValid = (entry, value) => {
+  switch (entry.kind) {
+    case 'enum': return Array.isArray(entry.values) && entry.values.includes(value);
+    case 'integer': {
+      if (!/^[0-9]+$/.test(value)) return false;
+      const n = Number(value);
+      return Number.isSafeInteger(n) && n >= entry.min && n <= entry.max;
+    }
+    case 'duration': return DURATION_RE.test(value) && !ZERO_DURATION_RE.test(value);
+    case 'boolean': return value === '0' || value === '1';
+    default: return false;
+  }
+};
+
 const hasTraversal = (p) => p.split(/[\\/]/).includes('..');
 const isUnresolved = (s) => /\{\{|\}\}|\$\{/.test(s);
 
@@ -228,6 +252,67 @@ export const validateManifest = (skillDir) => {
     if (role.template != null) checkInSkillPath(`role "${key}".template`, role.template, !isStub);
   }
 
+  // Typed `settings` block (bridges 2.3.0, D6 manifest-as-source): the per-bridge settings-file
+  // surface — an ARRAY of typed entries (a JSON object would silently dedupe duplicate keys under
+  // JSON.parse). Unlike the AD-033 `contract` block (validator-tolerated, externally
+  // drift-guarded), a malformed `settings` entry FAILS validation: the kit writer, the status
+  // renderers, and the wrapper shell constants all consume this block, so a bad entry would
+  // corrupt a host-level config surface.
+  const settings = manifest.settings;
+  if (settings != null) {
+    if (!Array.isArray(settings)) {
+      errors.push('`settings` must be an array of setting entries');
+    } else {
+      const cmds = new Set(Object.values(roles)
+        .map((r) => (r && typeof r === 'object' && !Array.isArray(r) ? r.cmd : null))
+        .filter((c) => typeof c === 'string' && c));
+      const seenKeys = new Set();
+      settings.forEach((entry, i) => {
+        const at = `\`settings[${i}]\``;
+        if (entry == null || typeof entry !== 'object' || Array.isArray(entry)) {
+          errors.push(`${at} must be an object`);
+          return;
+        }
+        if (typeof entry.key !== 'string' || !/^[A-Z][A-Z0-9_]*$/.test(entry.key)) {
+          errors.push(`${at}.key must be an UPPER_SNAKE_CASE string`);
+        } else if (seenKeys.has(entry.key)) {
+          errors.push(`duplicate settings key "${entry.key}" (${at})`);
+        } else {
+          seenKeys.add(entry.key);
+        }
+        if (typeof entry.effect !== 'string' || !entry.effect) errors.push(`${at}.effect must be a non-empty string`);
+        if (!Array.isArray(entry.appliesTo) || entry.appliesTo.length === 0
+            || !entry.appliesTo.every((c) => typeof c === 'string' && c)) {
+          errors.push(`${at}.appliesTo must be a non-empty array of wrapper cmd names`);
+        } else {
+          for (const c of entry.appliesTo) {
+            if (!cmds.has(c)) errors.push(`${at}.appliesTo names "${c}" which is no roles.*.cmd of this manifest`);
+          }
+        }
+        if (!SETTING_KINDS.has(entry.kind)) {
+          errors.push(`${at}.kind must be one of enum|integer|duration|boolean`);
+          return; // the typed checks below are meaningless without a kind
+        }
+        if (entry.kind === 'enum'
+            && (!Array.isArray(entry.values) || entry.values.length === 0
+              || !entry.values.every((v) => typeof v === 'string' && v)
+              || new Set(entry.values).size !== entry.values.length)) {
+          errors.push(`${at}.values must be a non-empty array of unique non-empty strings (enum kind)`);
+        }
+        if (entry.kind === 'integer'
+            && (!Number.isSafeInteger(entry.min) || !Number.isSafeInteger(entry.max) || entry.min > entry.max)) {
+          errors.push(`${at}.min/.max must be integers with min <= max (integer kind)`);
+        }
+        if (!Object.hasOwn(entry, 'default')) {
+          errors.push(`${at}.default is required (null = the wrapper built-ins apply)`);
+        } else if (entry.default != null
+            && (typeof entry.default !== 'string' || !settingValueValid(entry, entry.default))) {
+          errors.push(`${at}.default must be null or a string value that passes the ${entry.kind} validation`);
+        }
+      });
+    }
+  }
+
   if (!isStub) {
     const auth = readAuthoritativeVersion(skillDir);
     if (auth.version == null) errors.push(`could not resolve an authoritative version (${auth.from})`);

package/tools/procedures.mjs

@@ -21,6 +21,9 @@ import { homedir } from 'node:os';
 import { join, dirname } from 'node:path';
 import { pathToFileURL, fileURLToPath } from 'node:url';
 import { detectBackends, wrapperCmdFor, wrapperContractFor } from './detect-backends.mjs';
+// The host-level bridge-settings registry (manifest-as-source) + its allowed-value labels. READ-ONLY
+// core only — never the writer — so this read-only advisor never imports the atomic-write core.
+import { loadRegistry, allowedLabel } from './bridge-settings-read.mjs';
 import { ACTIVITIES, resolveActivityRecipe, planRecipe } from './recipes.mjs';
 import { resolveEngineDir, readEngineFragment, PROCEDURES_FRAGMENT_REL } from './engine-source.mjs';
 // The plan-in-flight detector (AD-038) — imported from the READ-ONLY checker (review-state.mjs
@@ -130,8 +133,19 @@ export const extractSection = (text, activity) => {
 
 // ── resolution + rendering ─────────────────────────────────────────────────────────
 
-const resolveAllSlots = ({ activity, config, detection, overrides }) =>
-  Object.keys(ACTIVITIES[activity].slots).map((slot) => {
+const resolveAllSlots = ({ activity, config, detection, overrides }) => {
+  // The host-level settings knobs (manifest-as-source), best-effort: a corrupt bundle degrades to none
+  // and the advisor never crashes. Attached per wrapper cmd via each knob's `appliesTo`. Fact-only —
+  // model/effort are not knobs, so no model claim can ride here.
+  const registry = (() => {
+    try {
+      return loadRegistry({});
+    } catch {
+      return new Map();
+    }
+  })();
+  const knobsFor = (cmd) => [...registry.values()].filter((k) => (k.appliesTo ?? []).includes(cmd));
+  return Object.keys(ACTIVITIES[activity].slots).map((slot) => {
     const resolved = resolveActivityRecipe({ config: config ?? {}, readiness: detection, activity, slot, override: overrides[slot] });
     // The concrete wrapper set this slot's EFFECTIVE recipe dispatches (empty for solo). Reuse
     // planRecipe's drift-guarded dispatch for WHICH backends, then resolve each (backend, role) to its
@@ -144,9 +158,11 @@ const resolveAllSlots = ({ activity, config, detection, overrides }) =>
     // is NEVER gated by REVIEW_RECIPES (that set gates only the review-loop economics block).
     const contracts = dispatch
       .map((d) => ({ backend: d.backend, role: d.role, cmd: wrapperCmdFor(d.backend, d.role), contract: wrapperContractFor(d.backend, d.role) }))
-      .filter((c) => c.cmd && c.contract);
+      .filter((c) => c.cmd && c.contract)
+      .map((c) => ({ ...c, settings: knobsFor(c.cmd).map((k) => ({ key: k.key, allowed: allowedLabel(k) })) }));
     return { slot, ...resolved, backends, contracts };
   });
+};
 
 // An unsatisfiable EXPLICIT override is the only "warning" (loud, flagged for the agent to relay). A
 // graceful config/default degradation is reported as a per-slot reason, not a warning.
@@ -250,7 +266,7 @@ const costLanesAdvice = () => [
 // roles[role].contract (drift-guarded), never re-derived or re-worded here. Rendered for EVERY
 // dispatched backend of EVERY slot (review AND execute=delegated); each wrapper's --help prints the
 // same contract, so the agent never needs to open the wrapper source.
-const contractLines = ({ cmd, contract }) => {
+const contractLines = ({ cmd, contract, settings }) => {
   const lines = [`      ${cmd} — driving contract (as bundled with this kit; copy-paste — \`${cmd} --help\` prints the same):`];
   for (const inv of contract.invocations) lines.push(`        ${inv}`);
   for (const f of contract.flags ?? []) lines.push(`        ${f}`);
@@ -263,6 +279,12 @@ const contractLines = ({ cmd, contract }) => {
   if (contract.passthrough) {
     lines.push(`        passthrough after '--' is ${contract.passthrough.policy}: blocked always: ${contract.passthrough.blocked.join(' ')}; relaxed only under CODEX_PROBE=1: ${contract.passthrough.probeRelaxed.join(' ')}`);
   }
+  // Host-level settings knobs this wrapper honors (fact-only, from the bundled manifests; explicit
+  // branch — contractLines drops any contract key it does not name, so this must be enumerated here).
+  if ((settings ?? []).length) {
+    lines.push('        host settings (survive kit upgrades — set via /agent-workflow-kit bridge-settings):');
+    for (const s of settings) lines.push(`          ${s.key} — ${s.allowed}`);
+  }
   return lines;
 };
 

package/tools/recipes.mjs

@@ -15,6 +15,9 @@
 // a backend is advisory or delegated, never autonomous. Dependency-free, Node >= 18.
 
 import { pathToFileURL } from 'node:url';
+// The host-level bridge-settings snapshot (fact-only, best-effort). READ-ONLY core only — never the
+// writer — so this read-only advisor never pulls in the atomic-write core.
+import { settingsSnapshot } from './bridge-settings-read.mjs';
 import {
   detectBackends,
   wrapperCmdFor,
@@ -293,12 +296,19 @@ export const resolveActivityRecipe = ({ config = {}, readiness = [], activity, s
 // DISPLAY_ALIASES — the ONE alias table the recommendation clause already uses; ordering is the
 // deterministic BACKEND_PRIORITY (codex before agy), independent of detection emission order.
 // Always exactly one line: no part may carry a newline (pinned by tests).
-export const composeStatusLine = (detection, recommendation) => {
+export const composeStatusLine = (detection, recommendation, settings = null) => {
   const backends = [...detection]
     .sort((a, b) => priorityIndex(a.name) - priorityIndex(b.name))
     .map((b) => `${DISPLAY_ALIASES[b.name] ?? b.name} ${b.readiness === READY ? '✓' : '✗'} ${b.readiness}`)
     .join(' · ');
-  return `backends: ${backends} — run /agent-workflow-kit backends · recipes: ${recommendation.clause} — see /agent-workflow-kit recipes`;
+  const base = `backends: ${backends} — run /agent-workflow-kit backends · recipes: ${recommendation.clause} — see /agent-workflow-kit recipes`;
+  // Fact-only suffix, ONLY when a bridge knob is actively set (env/file, non-default). Omitted otherwise,
+  // so the default line is byte-identical to before. A raw env value may (D3) carry newlines/control
+  // chars — collapse them to a single space so the "exactly one line" backend-status contract holds.
+  const oneLine = (s) => String(s).replace(/[\s]+/g, ' ').trim();
+  const active = settings?.active ?? [];
+  const suffix = active.length ? ` · settings: ${active.map((s) => `${oneLine(s.key)}=${oneLine(s.value)}`).join(' · ')}` : '';
+  return base + suffix;
 };
 
 // ── the one-line ACTIVE-recipe line (the discovery line — configured, never recommended) ───────────
@@ -340,7 +350,7 @@ export const composeActiveRecipeLine = ({ config, source } = {}, detection) => {
 
 // The structured report behind `--json` — the recipes, the recommendation, a plan per recipe, and
 // (additive) the pasteable one-line backend status composed from the same detection.
-export const buildReport = (detection) => {
+export const buildReport = (detection, settings = null) => {
   const recommendation = recommendRecipe(detection);
   return {
     recipes: RECIPES.map(({ id, title, role, minBackends, degradesTo, summary }) => ({
@@ -353,7 +363,7 @@ export const buildReport = (detection) => {
     })),
     recommendation,
     plans: RECIPES.map((r) => planRecipe(r.id, detection)),
-    statusLine: composeStatusLine(detection, recommendation),
+    statusLine: composeStatusLine(detection, recommendation, settings),
   };
 };
 
@@ -423,8 +433,8 @@ exclusive. Detection only — never writes, never commits, never runs a subscrip
       console.error(`[agent-workflow-kit] ${err.message}`);
       return err.exitCode ?? 1;
     }
-  } else if (argv.includes('--status-line')) console.log(composeStatusLine(detection, recommendRecipe(detection)));
-  else if (argv.includes('--json')) console.log(JSON.stringify(buildReport(detection), null, 2));
+  } else if (argv.includes('--status-line')) console.log(composeStatusLine(detection, recommendRecipe(detection), settingsSnapshot()));
+  else if (argv.includes('--json')) console.log(JSON.stringify(buildReport(detection, settingsSnapshot()), null, 2));
   else console.log(formatRecipes(detection));
   return 0;
 };

package/tools/renderers.mjs

@@ -56,6 +56,13 @@ const renderBridges = (vm, { glyph, color }) => {
   for (const b of vm.bridges) {
     const wrappers = b.wrappers.map((w) => `${w.cmd} ${glyph[w.state] ?? glyph.unknown}`).join(', ') || '—';
     lines.push(`  ${pad(b.display, MEMBER_COL)}${pad(b.readiness, READINESS_COL)}wrappers: ${wrappers}`);
+    // Fact-only host-level settings sub-line: the active knobs for this bridge, or a localized error.
+    // Absent when no knob is active, so the block stays byte-identical to before when nothing is set.
+    if (b.settings?.error) lines.push(`  ${pad('', MEMBER_COL)}${glyph.note} couldn't read bridge settings (${b.settings.error})`);
+    else if (b.settings?.active?.length) {
+      const active = b.settings.active.map((s) => `${s.key}=${s.value} [${s.source}]`).join(' · ');
+      lines.push(`  ${pad('', MEMBER_COL)}settings: ${active}`);
+    }
   }
   return lines;
 };