@sabaiway/agent-workflow-kit 1.34.0 → 1.35.0

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

package/tools/setup-backends.mjs

@@ -99,6 +99,78 @@ const probeMarker = (file, fs) => {
   }
 };
 
+// ── overwrite honesty (D5) — state what a refresh replaced, never a silent wipe ────────────────────
+
+// The host-level settings surface a refresh NEVER touches — the one place a bridge tweak survives a
+// kit upgrade (bridge CODE stays kit-owned; only these knobs persist). Named wherever a refresh
+// reports overwriting a local edit, so the recovery is always a copy-paste away.
+const SETTINGS_FILE_HINT = '${XDG_CONFIG_HOME:-~/.config}/agent-workflow/bridge-settings.conf';
+const SETTINGS_CMD_HINT = '/agent-workflow-kit bridge-settings';
+
+// Bundle-owned regular files whose PLACED copy differs from the bundle (a local edit an equal-version
+// refresh would overwrite) or cannot be read (indeterminate — an honest degrade). Mirrors
+// copyTreeRefresh's src dispatch so it flags EXACTLY the files the overwrite touches: a symlink src is
+// additive (copyTreeRefresh skips an existing dest — never overwritten) and a dir recurses; a
+// bundled-only file (no placed copy) is a pure add, no loss. The BUNDLE read is our own shipped
+// artifact — a failure there is a loud corrupt-kit error upstream (never swallowed here); only the
+// PLACED read is caught (EACCES/EIO → 'unreadable', and the refresh still proceeds). Sorted output is
+// deterministic for the stated line. Exported for a direct unit test (the full driver cannot observe a
+// symlinked placed file — copyTreeRefresh refuses to overwrite one, so the refresh fails before any line).
+export const scanBundleOwnedDrift = (bundleDir, skillDir, fs) => {
+  const drifted = [];
+  const unreadable = [];
+  const walk = (rel) => {
+    const src = join(bundleDir, rel);
+    const dest = join(skillDir, rel);
+    const st = fs.lstat(src);
+    if (st.isSymbolicLink()) return;
+    if (st.isDirectory()) {
+      for (const entry of fs.readdir(src)) walk(rel ? join(rel, entry) : entry);
+      return;
+    }
+    // lstat the PLACED path NO-FOLLOW first — never read THROUGH a symlink (copyTreeRefresh's
+    // assertContainedRealPath would refuse to overwrite a symlinked dest, so reading its target here
+    // would be both unsafe and moot). Absent → a bundled-only addition (no local loss); a symlink /
+    // non-regular / unreadable placed node → "could not compare" without a read-through.
+    const destStat = (() => {
+      try {
+        return fs.lstat(dest);
+      } catch (err) {
+        return err && err.code === 'ENOENT' ? 'absent' : 'error';
+      }
+    })();
+    if (destStat === 'absent') return;
+    if (destStat === 'error' || destStat.isSymbolicLink() || !destStat.isFile()) {
+      unreadable.push(rel);
+      return;
+    }
+    const srcBytes = fs.readFile(src);
+    const destBytes = (() => {
+      try {
+        return fs.readFile(dest);
+      } catch {
+        unreadable.push(rel);
+        return null;
+      }
+    })();
+    if (destBytes === null) return;
+    if (!Buffer.from(srcBytes).equals(Buffer.from(destBytes))) drifted.push(rel);
+  };
+  walk('');
+  return { drifted: drifted.sort(), unreadable: unreadable.sort() };
+};
+
+// One user-facing sentence naming what an equal-version re-sync overwrote — or null when nothing local
+// was lost. Callers apply their own indent; the pointer names the settings file that survives a refresh.
+const driftSummary = (drift) => {
+  if (!drift) return null;
+  const parts = [];
+  if (drift.drifted.length) parts.push(`overwrote ${drift.drifted.length} locally-changed file(s): ${drift.drifted.join(', ')}`);
+  if (drift.unreadable.length) parts.push(`could not compare ${drift.unreadable.length} file(s) (kept the bundled copy): ${drift.unreadable.join(', ')}`);
+  if (!parts.length) return null;
+  return `${parts.join('; ')} — bridge code is kit-owned and always refreshed; persist host tweaks in ${SETTINGS_FILE_HINT} (survives every refresh): ${SETTINGS_CMD_HINT}`;
+};
+
 // ── path resolution ──────────────────────────────────────────────────────────
 
 const skillDirOf = (entry, deps) =>
@@ -253,14 +325,26 @@ const assertNoDowngrade = (plan, deps = {}) => {
   if (compareSemver(placed, bundled) === 1) throw stop(downgradeReason(placed, bundled), { skillDir: plan.skillDir, wouldDowngrade: true });
 };
 
+// Copy the bundle over the placed skill dir (the refresh overwrite), FIRST scanning bundle-owned files
+// for local drift so the caller can STATE what the overwrite replaced (D5 — overwrite honesty). Scan
+// only on a refresh: a `place` writes into an absent/empty dir, so there is nothing local to lose. The
+// copy proceeds either way — bridge code is kit-owned. Returns the drift report (null for a place).
+const copyBridgeWithHonesty = (action, bundleDir, skillDir, deps) => {
+  const fs = fsDeps(deps);
+  const drift = action === 'refresh' ? scanBundleOwnedDrift(bundleDir, skillDir, fs) : null;
+  copyTreeRefresh(bundleDir, skillDir, skillDir, fs);
+  return drift;
+};
+
 // Place/refresh the bundled bridge skill. Re-inspects before writing (never trusts a stale plan).
+// Returns the plan plus `drift`: on a refresh, the bundle-owned files whose local edits it overwrote.
 export const placeSkill = (name, deps = {}) => {
   const entry = registryEntry(name);
   if (!entry) throw stop(`unknown backend: ${name}`);
   const plan = inspectSkillDir(entry, deps);
   assertNoDowngrade(plan, deps);
-  copyTreeRefresh(plan.bundleDir, plan.skillDir, plan.skillDir, fsDeps(deps));
-  return plan;
+  const drift = copyBridgeWithHonesty(plan.action, plan.bundleDir, plan.skillDir, deps);
+  return { ...plan, drift };
 };
 
 // Link the wrappers onto `bindir`. PREFLIGHT all (source is a regular non-symlink file inside the
@@ -413,9 +497,12 @@ export const planFor = (backend, deps = {}) => {
 // in the plan across the read→write gap). Throws on a mid-flight conflict / fs error (honest partial
 // failure — placeSkill/chmod/symlink all converge on a re-run, so there is nothing to roll back).
 const applyBackend = (plan, deps) => {
-  if (plan.place.action === 'place' || plan.place.action === 'refresh') placeSkill(plan.name, deps);
+  const placed = (plan.place.action === 'place' || plan.place.action === 'refresh')
+    ? placeSkill(plan.name, deps)
+    : null;
   const manifest = readBundledManifest(plan.place.bundleDir, deps);
   linkWrappers(plan.skillDir, manifest, { ...deps, bindir: plan.bindir, platform: plan.platform });
+  return { drift: placed?.drift ?? null };
 };
 
 // ── formatting ─────────────────────────────────────────────────────────────────
@@ -442,6 +529,11 @@ const formatBackend = (plan, applied) => {
   }
   const placeVerb = applied ? { place: 'placed', refresh: 'refreshed' } : { place: 'will place', refresh: 'will refresh' };
   lines.push(`      • skill: ${placeVerb[plan.place.action]}${versionLabel(plan)} → ${plan.skillDir}`);
+  // Overwrite honesty (D5): on an equal-version re-sync that clobbered a local edit, say so (a version
+  // upgrade's diffs are the version delta — versionLabel's arrow already signals that change).
+  const equalVersionRefresh = plan.place.action === 'refresh' && (!plan.priorVersion || plan.priorVersion === plan.version);
+  const driftLine = equalVersionRefresh ? driftSummary(plan.drift) : null;
+  if (driftLine) lines.push(`      ↳ ${driftLine}`);
   for (const l of plan.links) {
     const verb = l.dstState === 'ours' ? 'already linked' : applied ? 'linked' : 'will link';
     lines.push(`      • wrapper ${l.cmd}: ${verb} → ${l.dst}`);
@@ -463,10 +555,10 @@ const formatBackend = (plan, applied) => {
 // a per-bridge lock file would be new machinery for a user-driven, self-healing race.
 const refreshSkillOnly = (entry, deps = {}) => {
   const fresh = inspectSkillDir(entry, deps);
-  if (fresh.action !== 'refresh') return false;
+  if (fresh.action !== 'refresh') return { refreshed: false, drift: null };
   assertNoDowngrade(fresh, deps);
-  copyTreeRefresh(fresh.bundleDir, fresh.skillDir, fresh.skillDir, fsDeps(deps));
-  return true;
+  const drift = copyBridgeWithHonesty('refresh', fresh.bundleDir, fresh.skillDir, deps);
+  return { refreshed: true, drift };
 };
 
 const NOT_PLACED_LINE = 'skipped — not placed (placement is opt-in: /agent-workflow-kit setup)';
@@ -499,7 +591,8 @@ export const refreshPlacedBridges = (deps = {}, names = KNOWN_BACKENDS.map((b) =
       if (plan.outcome === 'stop' || plan.outcome === 'error') {
         return { name: plan.name, outcome: 'failed', line: `  ${plan.name}: could not refresh — ${stripPrefix(plan.reason)}; recover with /agent-workflow-kit setup` };
       }
-      if (!refreshSkillOnly(registryEntry(plan.name), deps)) {
+      const refresh = refreshSkillOnly(registryEntry(plan.name), deps);
+      if (!refresh.refreshed) {
         return { name: plan.name, outcome: 'not-placed', line: `  ${plan.name}: ${NOT_PLACED_LINE}` };
       }
       const manifest = readBundledManifest(plan.place.bundleDir, deps);
@@ -507,10 +600,14 @@ export const refreshPlacedBridges = (deps = {}, names = KNOWN_BACKENDS.map((b) =
       const current = plan.version !== null && plan.priorVersion === plan.version;
       // The equal-version line still states the copy that ran (repair-on-rerun) — the tool never
       // reports a mutation-free "already current" while it re-synced files underneath.
+      const base = `  ${plan.name}: ${current ? `already current${versionLabel(plan)} — files re-synced from the bundled copy` : `refreshed${versionLabel(plan)}`}`;
+      // Overwrite honesty (D5): only an EQUAL-version re-sync can prove a byte diff is a LOCAL edit —
+      // a version upgrade's diffs are the version delta, which the (vOld → vNew) arrow already states.
+      const summary = current ? driftSummary(refresh.drift) : null;
       return {
         name: plan.name,
         outcome: current ? 'already-current' : 'refreshed',
-        line: `  ${plan.name}: ${current ? `already current${versionLabel(plan)} — files re-synced from the bundled copy` : `refreshed${versionLabel(plan)}`}`,
+        line: summary ? `${base}\n     ↳ ${summary}` : base,
       };
     } catch (err) {
       // A downgrade STOP raised at the write boundary (a newer bridge landed between plan and apply)
@@ -647,7 +744,8 @@ export const main = (argv = process.argv.slice(2), deps = {}) => {
     let plan = planFor(name, runDeps);
     if (!args.dryRun && plan.outcome === 'ok') {
       try {
-        applyBackend(plan, runDeps);
+        const { drift } = applyBackend(plan, runDeps);
+        plan = { ...plan, drift };
         appliedOk = true;
       } catch (err) {
         plan = { ...plan, outcome: err.code === SETUP_STOP ? 'stop' : 'error', reason: err.message };

package/tools/view-model.mjs

@@ -32,6 +32,13 @@ const bridgeVm = (b) => ({
   readiness: b.readiness,
   // preserve the three-state wrapper status (present | missing | unknown) — the renderer maps to a glyph.
   wrappers: (b.wrappers ?? []).map((w) => ({ cmd: w.cmd, state: w.state })),
+  // fact-only host-level settings: the active knobs for this bridge, or a localized error; null when
+  // nothing is set (the renderer then adds no sub-line — the block stays as it was before any knob).
+  settings: b.settings?.error
+    ? { error: b.settings.error }
+    : b.settings?.active?.length
+      ? { active: b.settings.active.map((a) => ({ key: a.key, value: a.value, source: a.source })) }
+      : null,
 });
 
 const visibilityVm = (v) => {