@sabaiway/agent-workflow-kit 1.33.0 → 1.35.0

package/tools/commands.mjs

@@ -96,7 +96,7 @@ const CATALOG = [
     invocation: invocationOf('gates'),
     group: 'Inspect',
     kind: PROJECT_EXEC,
-    oneLine: 'Run the project’s own declared gate commands (docs/ai/gates.json) as one batch — a PASS/FAIL table, one summary line.',
+    oneLine: 'Run the project’s own declared gate commands (docs/ai/gates.json) as one batch — a PASS/FAIL table, one summary line. The mode itself writes nothing; a separate consent-gated seeder can propose entries from your project’s own scripts (preview first, written only on your yes).',
   },
   {
     key: 'setup',
@@ -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'),
@@ -212,6 +219,19 @@ const KIND_TAG = {
 };
 const pad = (s, n) => (s.length >= n ? s : s + ' '.repeat(n - s.length));
 
+// The "Tune" tail — the opt-in accelerator funnel, rendered AFTER the catalog groups. NOT a new
+// catalog key or mode (the frozen CATALOG + GROUP_ORDER stay; the router SKILL.md is untouched):
+// the same four entries the bootstrap accelerators block presents, one line of why each.
+const TUNE_TAIL = Object.freeze([
+  '',
+  'Tune — opt-in accelerators (consent-first: every writer previews before writing; nothing runs without your yes)',
+  `  ${BARE_INVOCATION} velocity      routine read-only commands stop prompting (incl. the --kit-tools tier for the kit's own read-only tools)`,
+  `  ${BARE_INVOCATION} agents        cheap-model subagents take the mechanical work (sweeps, changelog skeletons, gate triage)`,
+  `  ${BARE_INVOCATION} gates         run your declared gates (docs/ai/gates.json) as one batch; its guide also offers the consent-gated seeding preview — writes only on your yes`,
+  `  ${BARE_INVOCATION} hook          auto-approve exactly your declared gate commands (byte-exact matches only)`,
+  `  ${BARE_INVOCATION} set-recipe    put a ready review backend to work on plans and diffs`,
+]);
+
 // formatHelp() → the grouped, kind-tagged human index. Deterministic; groups in GROUP_ORDER, modes in
 // catalog order within each group. The header states the index itself is read-only.
 export const formatHelp = () => {
@@ -229,6 +249,7 @@ export const formatHelp = () => {
       lines.push(`  ${pad(c.invocation, invocWidth)}  ${KIND_TAG[c.kind] ?? c.kind}  ${c.oneLine}`);
     }
   }
+  lines.push(...TUNE_TAIL);
   return lines.join('\n');
 };
 

package/tools/family-registry.mjs

@@ -47,7 +47,13 @@ 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';
-import { GATES_REL } from './run-gates.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).
+import { readBundledAgents, planPlacement } from './cheap-agents.mjs';
 // The status vocabulary (manifestState constants, internal→public maps, display names, the no-leak
 // forbidden set) lives in the frozen labels.mjs LEAF (Plan §4.2 B1) so the import graph is acyclic —
 // nothing imports family-registry for vocabulary. Imported here for internal use; the public subset is
@@ -456,21 +462,50 @@ export const surveyGateHook = (dir, deps = {}) => {
     const exists = deps.exists ?? existsSync;
     const project = readSettingsFile(join(d, SETTINGS_FILE), { ...deps, cwd: d });
     const local = readSettingsFile(join(d, SETTINGS_LOCAL_FILE), { ...deps, cwd: d });
+    // How many gates are actually DECLARED — the welcome-mat hook rung keys on a non-empty
+    // declaration (a fresh bootstrap seeds gates.json EMPTY, so file presence alone would misfire).
+    // 0 = absent or empty list; null = present but unreadable/malformed (unknown — never a false
+    // count, and never an area-wide error: the wired/placed probes still report; the validation
+    // REASON is preserved beside the null so status never renders a bare question mark).
+    const declaration = (() => {
+      try {
+        const res = loadDeclaration(d, deps);
+        return { declaredGates: res.outcome === 'loaded' ? res.gates.length : 0 };
+      } catch (err) {
+        return { declaredGates: null, declarationError: localizeError(err) };
+      }
+    })();
     return {
       wired: isHookWired(project.data) || isHookWired(local.data),
       filePlaced: Boolean(exists(join(d, GATE_HOOK_FILE_REL))),
       declarationPresent: Boolean(exists(join(d, GATES_REL))),
+      ...declaration,
     };
   } catch (err) {
     return { error: localizeError(err) };
   }
 };
 
+// cheap agents: the kit-placed .claude/agents/ vehicles (Mode: agents) — how many of the bundled
+// cheap-lane definitions are present in the project. A customized copy counts as PLACED (it exists;
+// the writer preserves it) — the welcome-mat agents rung keys on zero placed. Read-only; REUSES the
+// writer's own bundle reader + placement planner (cheap-agents.mjs — one implementation).
+export const surveyCheapAgents = (dir, deps = {}) => {
+  try {
+    const templates = readBundledAgents(deps);
+    const plan = planPlacement(templates, resolve(dir), deps);
+    return { bundled: templates.length, placed: plan.filter((p) => p.action !== 'place').length };
+  } catch (err) {
+    return { error: localizeError(err) };
+  }
+};
+
 // the project-scoped settings survey (needs a project dir). Each area is independently localized-on-error.
 export const surveySettings = (dir, deps = {}) => ({
   recipes: surveyRecipes(dir, deps),
   attribution: surveyAttribution(dir, deps),
   velocity: surveyVelocity(dir, deps),
+  agents: surveyCheapAgents(dir, deps),
   hook: surveyGateHook(dir, deps),
 });
 
@@ -481,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/orchestration-write.mjs

@@ -4,94 +4,24 @@
 // can never reach a writer" is a STRUCTURAL invariant (an import-split test pins it), not just an
 // assertion. Splitting the writer out of the schema/read module keeps the read surface fs-write-free.
 //
-// writeConfig is hardened (mirrors the setup-backends posture):
-//   - DEPLOYMENT GATE first: refuse to scatter a config into a repo with no docs/ai/ — STOP loud,
-//     pointing at init/bootstrap (a config without a deployment is meaningless + surprising).
-//   - refuse a SYMLINKED leaf (orchestration.json itself a symlink) — a rename would silently replace
-//     the link target.
-//   - guard the dst + the tmp sibling with assertContainedRealPath (fs-safe) — refuses a symlinked
-//     docs/ or docs/ai/ PARENT, not just the leaf, and refuses any escape outside cwd.
-//   - atomic: write a UNIQUE *.json.<rand>.tmp opened EXCLUSIVE-CREATE (wx), then rename over the dst.
-//   - RE-CHECK the parent chain + the leaf immediately before the rename (TOCTOU).
-//   - LAST-WRITER-WINS: local, single-user; no cross-process lock (documented, not silently assumed).
+// The hardened write flow (deployment gate → symlink STOPs → containment guard → exclusive-create
+// tmp + rename with a TOCTOU re-check → tmp cleanup; LAST-WRITER-WINS, documented) lives in the
+// shared atomic-write core (tools/atomic-write.mjs, extracted from this module — AD-042) and is
+// consumed here with this module's own STOP identity, so the public API + error contract are
+// unchanged (this file's tests pin them, characterize-first).
 //
 // Dependency-free, Node >= 18. Every fs primitive is injectable (deps.*) so the guards are unit-testable.
 
-import { lstatSync, writeFileSync, renameSync, rmSync } from 'node:fs';
-import { randomBytes } from 'node:crypto';
-import { join } from 'node:path';
-import { assertContainedRealPath } from './fs-safe.mjs';
 import { CONFIG_REL, serializeConfig } from './orchestration-config.mjs';
+import { writeDocsAiFileAtomic } from './atomic-write.mjs';
 
 // A typed STOP — a deliberate refusal we surface (deployment gate / symlinked leaf), distinct from a
 // native fs error. `Object.assign(new Error(), { code })`, the codebase's typed-error idiom (no classes).
 export const ORCH_WRITE_STOP = 'ORCH_WRITE_STOP';
 const stop = (message) => Object.assign(new Error(`[agent-workflow-kit] ${message}`), { name: 'OrchWriteStop', code: ORCH_WRITE_STOP });
 
-// lstat without following symlinks; null when absent. A non-ENOENT error propagates (never fail open).
-const lstatNoFollow = (path, lstat) => {
-  try {
-    return lstat(path);
-  } catch (err) {
-    if (err && err.code === 'ENOENT') return null;
-    throw err;
-  }
-};
-
 // writeConfig(cwd, config, deps) → { writtenPath } on success; THROWS a typed STOP (no deployment /
 // symlinked leaf) or a native fs error otherwise. The tmp is cleaned up on any failure after its
 // creation. config is serialized canonically (serializeConfig: 2-space, _README-first, trailing NL).
-export const writeConfig = (cwd, config, deps = {}) => {
-  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 guard = (target) => assertContainedRealPath(cwd, target, { lstat });
-
-  // Deployment gate — never scatter a config into a non-deployed repo (mirror velocity / setup). 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 (never write through it).
-  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 ${CONFIG_REL}`);
-  }
-  if (docsAiStat.isSymbolicLink()) {
-    throw stop(`docs/ai is a symlink — refusing to write a config 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 ${CONFIG_REL}`);
-  }
-
-  const dst = join(cwd, CONFIG_REL);
-  // 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(`${CONFIG_REL} is a symlink — refusing to replace it (a write would clobber the link target)`);
-  }
-  // Guard the dst + a unique tmp SIBLING: refuses a symlinked docs/ or docs/ai/ parent, and any escape.
-  guard(dst);
-  const tmp = `${dst}.${rand()}.tmp`;
-  guard(tmp);
-
-  const body = serializeConfig(config);
-  // 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(`${CONFIG_REL} 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: CONFIG_REL };
-};
+export const writeConfig = (cwd, config, deps = {}) =>
+  writeDocsAiFileAtomic(cwd, CONFIG_REL, serializeConfig(config), deps, { stop, noun: 'a config' });

package/tools/presentation.mjs

@@ -41,6 +41,7 @@ export const SETTINGS_LABELS = Object.freeze({
   recipes: 'recipes',
   attribution: 'attribution',
   velocity: 'velocity',
+  agents: 'cheap agents',
   hook: 'gate hook',
 });
 

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;
 };
@@ -101,11 +108,19 @@ const renderSettings = (vm, { color, glyph }) => {
   else if (s.velocity) {
     lines.push(`  ${pad(SETTINGS_LABELS.velocity, SETTINGS_COL)}defaultMode=${String(s.velocity.defaultMode)} · allow project/local=${s.velocity.allow.project}/${s.velocity.allow.local}`);
   }
-  // gate hook — the opt-in PreToolUse gate-approval hook: wired / file placed / declaration present.
+  // cheap agents — the kit-placed .claude/agents/ vehicles: placed count vs the bundle.
+  if (s.agents?.error) lines.push(`  ${pad(SETTINGS_LABELS.agents, SETTINGS_COL)}error: ${s.agents.error}`);
+  else if (s.agents) {
+    lines.push(`  ${pad(SETTINGS_LABELS.agents, SETTINGS_COL)}placed=${s.agents.placed}/${s.agents.bundled}`);
+  }
+  // gate hook — the opt-in PreToolUse gate-approval hook: wired / file placed / declaration present /
+  // declared gate count (null → '?' — unknown is shown as unknown, never as a number).
   if (s.hook?.error) lines.push(`  ${pad(SETTINGS_LABELS.hook, SETTINGS_COL)}error: ${s.hook.error}`);
   else if (s.hook) {
     const yn = (b) => (b ? 'yes' : 'no');
-    lines.push(`  ${pad(SETTINGS_LABELS.hook, SETTINGS_COL)}wired=${yn(s.hook.wired)} · file=${yn(s.hook.filePlaced)} · gates.json=${yn(s.hook.declarationPresent)}`);
+    // A null count carries its preserved validation reason — never a silent bare "?".
+    const declared = s.hook.declaredGates ?? (s.hook.declarationError ? `? (${s.hook.declarationError})` : '?');
+    lines.push(`  ${pad(SETTINGS_LABELS.hook, SETTINGS_COL)}wired=${yn(s.hook.wired)} · file=${yn(s.hook.filePlaced)} · gates.json=${yn(s.hook.declarationPresent)} · declared=${declared}`);
   }
   return lines;
 };

package/tools/review-state.mjs

@@ -5,7 +5,8 @@
 // resolves the effective `plan-execution.review` recipe (the advisor's single-source readers),
 // recomputes the CURRENT canonical uncommitted-state fingerprint, and reports — per recipe-named
 // backend — whether a FRESH, grounded, current-fingerprint receipt exists. `--check` turns the
-// report into a gate exit code (declare it in docs/ai/gates.json — by hand; never auto-seeded).
+// report into a gate exit code (declare it in docs/ai/gates.json — by hand OR via the
+// explicit-consent seeder, tools/seed-gates.mjs — never without consent, AD-021/AD-042).
 //
 // Normative `--check` exit contract (the single home of this list — SKILL.md points here):
 //   exit 0  when the resolved plan-execution.review recipe is solo (configured, or degraded there —
@@ -353,7 +354,8 @@ presence + verdict + grounding for the CURRENT tree. Plan/diff-mode receipts and
 --check exits 0/1 per the normative contract in the tool header: 0 for solo / no plan in flight /
 a clean tree / not-a-git-tree / all recipe-named backends receipted-current-and-grounded; 1 when a
 recipe-named backend is missing, stale (edited after review), or grounded:false under
-reviewed/council. Declare it as a project gate by hand (docs/ai/gates.json) — never auto-seeded.
+reviewed/council. Declare it as a project gate by hand (docs/ai/gates.json) or via the
+explicit-consent seeder (tools/seed-gates.mjs) — never without consent.
 
 Read-only: never writes, never commits, never runs a subscription CLI; spawns read-only git queries.
 Human residual: git commit --no-verify and receipt-file deletion remain possible — this is a