@sabaiway/agent-workflow-kit 3.15.0 → 4.1.0

package/tools/bridge-settings.mjs

@@ -42,8 +42,10 @@ const renderReader = (registry, parsed, fileState, ctx, path) => {
   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}`);
+    const retired = entry.retired ? '  ⚠ RETIRED' : '';
+    lines.push(`    ${entry.key} = ${displayValue(eff.value)}  [${eff.source}]${retired}${note}`);
     lines.push(`        ${entry.bridge} · ${allowedLabel(entry)} · ${entry.effect}`);
+    if (entry.retired) lines.push(`        RETIRED — ${entry.retired}`);
   }
   const dups = duplicateKeys(parsed);
   const unknown = [...parsed.byKey.keys()].filter((k) => !registry.has(k));
@@ -61,7 +63,7 @@ const buildReaderJson = (registry, parsed, fileState, ctx, 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 };
+      return { key: entry.key, bridge: entry.bridge, kind: entry.kind, effective: eff.value, source: eff.source, note: eff.note ?? null, default: entry.default, retired: entry.retired ?? null };
     }),
     duplicateKeys: duplicateKeys(parsed),
     unknownKeys: [...parsed.byKey.keys()].filter((k) => !registry.has(k)),
@@ -85,14 +87,21 @@ export const reconcileSettings = (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));
+  // RECOGNIZED and CURRENT are not the same thing: a manifest-RETIRED key is still in the registry
+  // (so an existing line never warns as unknown) but it arms nothing, and filing it under "all
+  // current" would be the survival check contradicting the retirement contract on the one surface
+  // init/upgrade actually shows.
+  const fileKeys = [...parsed.byKey.keys()];
+  const retired = fileKeys.filter((k) => registry.get(k)?.retired);
+  const known = fileKeys.filter((k) => registry.has(k) && !registry.get(k).retired);
+  const unknown = fileKeys.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 (unknown.length) lines.push(`  bridge-settings: ${unknown.length} unknown key(s) preserved verbatim (never edited) — compare with the current knobs when convenient: ${unknown.join(', ')}`);
+  for (const key of retired) lines.push(`  bridge-settings: ${key} is RETIRED and arms nothing — preserved verbatim (never edited); clear it with --unset ${key} --apply. ${registry.get(key).retired}`);
   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 };
+  if (!unknown.length && !retired.length && !dups.length) lines.push(`  bridge-settings: ${known.length} key(s) recognized, all current`);
+  return { outcome: unknown.length || retired.length ? 'flagged' : dups.length ? 'duplicates' : 'ok', lines };
 };
 
 // ── writer ─────────────────────────────────────────────────────────────────────────
@@ -143,6 +152,12 @@ 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(', ')}`);
+    // A RETIRED key (D3) is recognized so an existing line never warns as unknown — but writing a NEW
+    // one would arm nothing while reading as configuration. `--unset` stays allowed on purpose: it is
+    // the recovery the retirement notice tells the user to run.
+    if (op.kind === 'set' && entry.retired) {
+      throw fail(2, `${op.key} is RETIRED — ${entry.retired} Setting it would arm nothing; use --unset ${op.key} to clear an existing line.`);
+    }
     if (op.kind === 'set' && !settingValueValid(entry, op.value)) {
       throw fail(2, `invalid value "${op.value}" for ${op.key} — allowed: ${allowedLabel(entry)}`);
     }

package/tools/cheap-agents.mjs

@@ -28,6 +28,7 @@
 import { existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync, readdirSync } from 'node:fs';
 import { join, resolve, dirname } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
+import { shellQuoteArg } from './review-state.mjs';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 
@@ -49,8 +50,10 @@ export const CHEAP_AGENTS_BUNDLE = 'CHEAP_AGENTS_BUNDLE';
 
 const USAGE = `usage: cheap-agents [--dry-run | --apply] [--cwd <dir>] [--help]
 
-Places the bundled cheap-lane subagent definitions (haiku/low, read-only tools) into the
-project's ${AGENTS_DIR}/. Default is --dry-run (a preview; writes nothing). --apply writes.
+Places the bundled READ-ONLY subagent definitions into the project's ${AGENTS_DIR}/. No vehicle
+grants a shell: three ride a cheap model (haiku/low) for mechanical work — extraction sweeps,
+changelog fact-skeletons, gate triage — and review-lens is a read-only REVIEW vehicle on a
+review-capable model. Default is --dry-run (a preview; writes nothing). --apply writes.
 An existing file with DIFFERENT content is preserved and reported, never overwritten.`;
 
 export const fail = (exitCode, message) => Object.assign(new Error(message), { exitCode });
@@ -176,8 +179,8 @@ const ACTION_LABEL = {
 export const formatResult = (result) => {
   const lines = [
     result.dryRun
-      ? 'agent-workflow cheap-lane agents — DRY RUN (no changes; re-run with --apply)'
-      : 'agent-workflow cheap-lane agents — APPLY',
+      ? 'agent-workflow read-only subagents — DRY RUN (no changes)'
+      : 'agent-workflow read-only subagents — APPLY',
   ];
   for (const item of result.plan) {
     const verb = result.dryRun && item.action === 'place' ? 'would place' : ACTION_LABEL[item.action];
@@ -187,8 +190,15 @@ export const formatResult = (result) => {
     lines.push(`note: no current deployment stamp found (${result.stamp ?? 'none'}) — --apply will refuse until init/upgrade runs.`);
   }
   lines.push(
-    'the vehicles are Claude Code subagents (model: haiku, effort: low, read-only tools) for mechanical work only — judgment, review, and real code stay on your main lane.',
+    'the vehicles are Claude Code subagents with READ-ONLY tools and NO shell — so a fan-out can never turn into a wave of approval prompts.',
+    'three ride the cheap lane (model: haiku, effort: low) for mechanical work; review-lens is an ADDITIONAL read-only review opinion, not a replacement for your configured review recipe. Writing code and running gates stay on your main lane.',
   );
+  // A preview must print the EXACT command that applies it. The advisor renders this dry-run as an
+  // item's one-liner, and that flow's contract is "run the printed command, no improvisation" — a
+  // bare "re-run with --apply" would leave the caller to reconstruct --cwd and its quoting.
+  if (result.dryRun && result.plan.some((item) => item.action === 'place')) {
+    lines.push(`to apply, run exactly: node ${shellQuoteArg(fileURLToPath(import.meta.url))} --apply --cwd ${shellQuoteArg(result.projectDir)}`);
+  }
   if (!result.dryRun && result.wrote) {
     lines.push('hidden-mode note: if this deployment is hidden, run the hide-footprint reconcile so the placed files stay out of `git status`.');
   }

package/tools/commands.mjs

@@ -131,7 +131,7 @@ const CATALOG = [
     invocation: invocationOf('agents'),
     group: 'Configure',
     kind: WRITER,
-    oneLine: 'Place bundled cheap-model subagent definitions for mechanical work — sweeps, changelog skeletons, gate triage (Claude Code; opt-in; preview first).',
+    oneLine: 'Place bundled READ-ONLY subagent definitions, none of them granted a shell — three cheap-model ones for mechanical work (sweeps, changelog skeletons, gate triage) and a review lens (Claude Code; opt-in; preview first).',
   },
   {
     key: 'hook',
@@ -305,7 +305,7 @@ 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} agents        shell-free subagents: cheap ones take the mechanical work, a review lens gives an extra read-only opinion`,
   `  ${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`,

package/tools/core-evidence.mjs

@@ -452,8 +452,22 @@ export const REVIEW_RECEIPT_CLASS = Object.freeze({
   MALFORMED_MARKER: 'malformed-marker',
   POSTURE_UNMARKED: 'posture-unmarked',
   MALFORMED_POSTURE: 'malformed-posture',
+  DELIVERY_UNMARKED: 'delivery-unmarked',
+  MALFORMED_DELIVERY: 'malformed-delivery',
 });
 
+// Backends whose `code` receipts must SELF-DECLARE how the change set reached the model (D8b).
+// Scoped, not universal: agy's oversized lane was the one observed returning a confident
+// fabrication, and codex's receipt semantics are deliberately untouched.
+const DELIVERY_DECLARING_BACKENDS = new Set(['agy']);
+
+// A delivery declaration is a lowercase token naming HOW delivery was established (`inline` when
+// the whole change set rode one prompt, `fed` when a chunked feed proved it by echo). The gate
+// requires PRESENT and WELL-FORMED, never a PARTICULAR value — which lane was used is the
+// wrapper's business; that the receipt declares one at all is the gate's.
+const isValidReceiptDelivery = (delivery) =>
+  typeof delivery === 'string' && delivery.length > 0 && delivery.length <= 32 && /^[a-z][a-z0-9-]*$/.test(delivery);
+
 // The D5 posture declaration (strip Phase 4): an object whose `model` is a NON-EMPTY string;
 // `effort` (when present) a non-empty string; `tier` (when present) a non-empty string or null.
 // Backend-agnostic — the wrapper is the writer authority on WHICH keys it declares.
@@ -483,6 +497,15 @@ export const classifyReviewReceiptForTree = (receipt, fingerprint) => {
   if (!isValidReceiptPosture(receipt.posture)) return REVIEW_RECEIPT_CLASS.MALFORMED_POSTURE;
   if (!isRecognizedVerdict(receipt.verdict)) return REVIEW_RECEIPT_CLASS.UNRECOGNIZED_VERDICT;
   if (receipt.grounded !== true) return REVIEW_RECEIPT_CLASS.UNGROUNDED;
+  // LAST on purpose. The delivery arm may only intercept a receipt that would otherwise ATTEST:
+  // placing it earlier pulled delivery-less `unrecognized-verdict` / `ungrounded` agy receipts out
+  // of summarize's latest-NORMAL selection, so an EARLIER ship survived a LATER bad receipt — the
+  // selection-first doctrine, broken silently. Those two classes stay byte-identical to before;
+  // the ONE class this arm changes is the previously-attesting one, which is the point.
+  if (DELIVERY_DECLARING_BACKENDS.has(receipt.backend)) {
+    if (!Object.hasOwn(receipt, 'delivery')) return REVIEW_RECEIPT_CLASS.DELIVERY_UNMARKED;
+    if (!isValidReceiptDelivery(receipt.delivery)) return REVIEW_RECEIPT_CLASS.MALFORMED_DELIVERY;
+  }
   return REVIEW_RECEIPT_CLASS.ATTESTING;
 };
 
@@ -504,6 +527,8 @@ export const summarizeReviewReceiptsForTree = (receipts, fingerprint) => {
   const malformedMarker = rowsFor(REVIEW_RECEIPT_CLASS.MALFORMED_MARKER);
   const postureUnmarked = rowsFor(REVIEW_RECEIPT_CLASS.POSTURE_UNMARKED);
   const malformedPosture = rowsFor(REVIEW_RECEIPT_CLASS.MALFORMED_POSTURE);
+  const deliveryUnmarked = rowsFor(REVIEW_RECEIPT_CLASS.DELIVERY_UNMARKED);
+  const malformedDelivery = rowsFor(REVIEW_RECEIPT_CLASS.MALFORMED_DELIVERY);
   const counts = {
     currentCount: classified.length,
     ungroundedCount: rowsFor(REVIEW_RECEIPT_CLASS.UNGROUNDED).length,
@@ -512,6 +537,7 @@ export const summarizeReviewReceiptsForTree = (receipts, fingerprint) => {
     markerRejected: malformedMarker.length,
     unmarkedRejected: unmarked.length,
     postureRejected: postureUnmarked.length + malformedPosture.length,
+    deliveryRejected: deliveryUnmarked.length + malformedDelivery.length,
   };
   if (normal.length > 0) {
     const latest = normal[normal.length - 1];
@@ -521,7 +547,7 @@ export const summarizeReviewReceiptsForTree = (receipts, fingerprint) => {
   }
   if (classified.length > 0) {
     return {
-      state: malformedMarker.length > 0 || unmarked.length > 0 || counts.postureRejected > 0 ? 'rejected' : 'probe',
+      state: malformedMarker.length > 0 || unmarked.length > 0 || counts.postureRejected > 0 || counts.deliveryRejected > 0 ? 'rejected' : 'probe',
       receipt: null,
       ...counts,
     };
@@ -537,12 +563,13 @@ export const describeMissingReviewAttestation = (summary) => {
     summary.markerRejected > 0 ? `${summary.markerRejected} receipt(s) with a malformed probe marker` : null,
     summary.unmarkedRejected > 0 ? `${summary.unmarkedRejected} receipt(s) with no probe marker` : null,
     (summary.postureRejected ?? 0) > 0 ? `${summary.postureRejected} receipt(s) with an absent/invalid run posture (a pre-D5 wrapper — re-run the review on the current bridge)` : null,
+    (summary.deliveryRejected ?? 0) > 0 ? `${summary.deliveryRejected} agy receipt(s) with an absent/invalid delivery declaration (minted before the change set was PROVEN delivered — re-run the review on the current bridge)` : null,
   ].filter(Boolean);
   const exclusionSuffix = exclusions.length > 0 ? `; excluded ${exclusions.join(', ')}` : '';
   if (summary.state === 'ungrounded') return `the latest normal receipt for the current tree is ungrounded${exclusionSuffix}`;
   if (summary.state === 'unrecognized-verdict') return `the latest normal receipt carries an unrecognized verdict (${JSON.stringify(summary.receipt?.verdict ?? null)}) — an unknown verdict never attests${exclusionSuffix}`;
   if (summary.state === 'probe') return 'only probe receipts exist for the current tree — a probe review never attests';
-  if (summary.state === 'rejected') return `current-tree receipts have an untrustworthy probe marker or run posture${exclusionSuffix}`;
+  if (summary.state === 'rejected') return `current-tree receipts have an untrustworthy probe marker, run posture or delivery declaration${exclusionSuffix}`;
   return 'no fresh code receipt exists for the current tree';
 };
 

package/tools/detect-backends.mjs

@@ -133,7 +133,7 @@ const RAW_BACKENDS = [
           'agy-review --continue [--decided @f] [--focus "…"]',
           'agy-review --conversation <id> [--decided @f] [--focus "…"]',
         ],
-        receipt: "side effect — a successful review appends one JSON receipt line to <git dir>/agent-workflow-review-receipts.jsonl (AW_REVIEW_RECEIPTS overrides; plan/diff outside a git tree: warn + skip unless overridden): fingerprint = sha256 over the canonical uncommitted-state payload (staged diff + unstaged diff + untracked-not-ignored contents — the review-payload domain; never-committable untracked paths — character/block devices, FIFOs, sockets — are excluded from the domain entirely, untracked symlinks/directories ride as name-only notes) in code mode, the artifact-file sha256 in plan/diff mode; verdict recorded verbatim from the mandated '### Verdict' section (SHIP / SHIP WITH NITS / REWORK); grounded = whether a NON-EMPTY --facts payload was supplied (code mode refuses pre-spend without one — no run, no receipt — unless --ungrounded/AGY_PROBE=1; in plan/diff an empty payload records grounded:false — fail-closed, the state gate rejects it), factsHash = sha256 of the facts payload; a continuation receipt is fresh:false (informational-only — it cannot attest the folded tree); probe = whether the run relaxed the quality guards (AGY_PROBE=1), written on EVERY receipt so it self-declares — the kit's review-state gate rejects a probe-marked receipt (a probe review never attests) and equally rejects an unmarked one (silence is not a declaration); posture = the ACTUAL run posture {model} (agy has no tier), written on EVERY receipt (D5) — the gate rejects a receipt with an absent/invalid posture (a pre-D5 wrapper minted it; re-run the review), one stderr banner line states the same posture, an ATTESTING review with AGY_MODEL explicitly emptied refuses pre-spend, and a model string carrying control bytes refuses pre-spend in every mode; a run whose output carries NO recognized '### Verdict' section — empty output included — exits 4 with NO receipt (D4: a FAILED review to RE-RUN, never a fatal session error); a write failure warns, never fails the review",
+        receipt: "side effect — a successful review appends one JSON receipt line to <git dir>/agent-workflow-review-receipts.jsonl (AW_REVIEW_RECEIPTS overrides; plan/diff outside a git tree: warn + skip unless overridden): fingerprint = sha256 over the canonical uncommitted-state payload (staged diff + unstaged diff + untracked-not-ignored contents — the review-payload domain; never-committable untracked paths — character/block devices, FIFOs, sockets — are excluded from the domain entirely, untracked symlinks/directories ride as name-only notes) in code mode, the artifact-file sha256 in plan/diff mode; verdict recorded verbatim from the mandated '### Verdict' section (SHIP / SHIP WITH NITS / REWORK); grounded = whether a NON-EMPTY --facts payload was supplied (code mode refuses pre-spend without one — no run, no receipt — unless --ungrounded/AGY_PROBE=1; in plan/diff an empty payload records grounded:false — fail-closed, the state gate rejects it), factsHash = sha256 of the facts payload; a continuation receipt is fresh:false (informational-only — it cannot attest the folded tree); probe = whether the run relaxed the quality guards (AGY_PROBE=1), written on EVERY receipt so it self-declares — the kit's review-state gate rejects a probe-marked receipt (a probe review never attests) and equally rejects an unmarked one (silence is not a declaration); posture = the ACTUAL run posture {model} (agy has no tier), written on EVERY receipt (D5) — the gate rejects a receipt with an absent/invalid posture (a pre-D5 wrapper minted it; re-run the review), one stderr banner line states the same posture, an ATTESTING review with AGY_MODEL explicitly emptied refuses pre-spend, and a model string carrying control bytes refuses pre-spend in every mode; delivery = how the change set REACHED the model, currently emitted as 'inline' (the whole set rode one prompt — proven by construction) or 'fed' (a chunked feed whose per-part echo proof verified); REQUIRED on every agy code receipt and its ABSENCE is what stops a pre-fed-lane receipt attesting, while the gate accepts any well-formed declaration rather than a particular value; absent by construction on plan/diff/continuation receipts, which carry no change set; a run whose output carries NO recognized '### Verdict' section — empty output included — exits 4 with NO receipt (D4: a FAILED review to RE-RUN, never a fatal session error); a write failure warns, never fails the review",
         notes: [
           'pre-dispatch host-diff: before the FIRST dispatch of this bridge, diff its declared networkHosts against the live sandbox allow-list — a missing host is surfaced to the maintainer BEFORE dispatching, never fired into a known prompt',
           'the review posture banner appends a banner-only timeout=<duration|uncapped> field — exactly the duration agy-run hands to timeout(1), uncapped when no timeout/gtimeout binary caps the run; INFORMATIONAL only: it never enters the receipt posture or the D5 banner↔receipt parity',

package/tools/manifest/schema.md

@@ -83,6 +83,13 @@ this block). Each entry:
   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).
+- `retired` (string, optional; **>= 20 chars when present**) — the STATED reason a key is kept only
+  for RECOGNITION. Recognition alone is not enough: a retired key stays in the registry so an
+  existing settings line never starts warning as unknown, but it **arms nothing**. Runtime semantics
+  the field switches on: the writer REFUSES a new `--set` (and still permits `--unset`, which is the
+  stated recovery), the reader/`--json`/status/`procedures` render it as retired rather than active,
+  and the init/upgrade survival check reports it as flagged rather than "all current". A bare flag is
+  rejected by validation — a dead knob must explain itself wherever it surfaces.
 
 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,

package/tools/manifest/validate.mjs

@@ -596,6 +596,14 @@ export const validateManifest = (skillDir) => {
           seenKeys.add(entry.key);
         }
         if (typeof entry.effect !== 'string' || !entry.effect) errors.push(`${at}.effect must be a non-empty string`);
+        // RETIRED metadata (D3): recognition alone is not enough. A key kept only so an existing
+        // settings line never warns as unknown carries a STATED reason; the writer refuses a new
+        // `--set` of it and every reader surface renders it as retired. Optional, but never a bare
+        // flag — an unvalidated field must not be able to ship.
+        if (Object.hasOwn(entry, 'retired')
+            && (typeof entry.retired !== 'string' || entry.retired.trim().length < 20)) {
+          errors.push(`${at}.retired must be a string stating WHY the key is retired (>= 20 chars)`);
+        }
         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`);

package/tools/presentation.mjs

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

package/tools/procedures.mjs

@@ -160,7 +160,10 @@ const resolveAllSlots = ({ activity, config, detection, overrides }) => {
     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)
-      .map((c) => ({ ...c, settings: knobsFor(c.cmd).map((k) => ({ key: k.key, allowed: allowedLabel(k) })) }));
+      // `retired` rides along: without it this surface advertised a RETIRED key as an ordinary
+      // settable knob, while the writer refuses to set it — a driving contract that contradicts the
+      // tool it points at.
+      .map((c) => ({ ...c, settings: knobsFor(c.cmd).map((k) => ({ key: k.key, allowed: allowedLabel(k), retired: k.retired ?? null })) }));
     return { slot, ...resolved, backends, contracts };
   });
 };
@@ -329,7 +332,11 @@ const contractLines = ({ cmd, contract, settings }) => {
   // 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}`);
+    for (const s of settings) {
+      lines.push(s.retired
+        ? `          ${s.key} — RETIRED: recognized but arms nothing; the writer refuses --set, --unset clears an existing line`
+        : `          ${s.key} — ${s.allowed}`);
+    }
   }
   return lines;
 };

package/tools/recipes.mjs

@@ -352,7 +352,10 @@ export const composeStatusLine = (detection, recommendation, settings = null, au
   // 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(' · ')}` : '';
+  // A RETIRED knob is rendered as retired, never as an armed capability (D3 Invariant E): the line
+  // exists in the user's file, so hiding it would be a silent deletion — but reading it as active
+  // would claim a capability the wrapper no longer has.
+  const suffix = active.length ? ` · settings: ${active.map((s) => `${oneLine(s.key)}=${oneLine(s.value)}${s.retired ? ' (RETIRED — arms nothing)' : ''}`).join(' · ')}` : '';
   // The autonomy segment (AD-044 Plan 4): rendered ONLY when the caller supplies the computed
   // facts (composeAutonomyFacts) — an omitted param keeps the line byte-identical (the settings-
   // suffix precedent). Fact-only: effective per-activity levels + the render-sync state; an absent

package/tools/recommendations.mjs

@@ -57,9 +57,10 @@ import { shellQuoteArg } from './review-state.mjs';
 import { isFinalCapableDeclaration } from './run-gates.mjs';
 import { resolveGitHooksPath } from './commit-guard.mjs';
 import { loadConfig } from './orchestration-config.mjs';
-import { DEFAULT_BUNDLE_ROOT, SETTINGS_FILENAME, settingsPath, parseSettings, duplicateKeys } from './bridge-settings-read.mjs';
+import { DEFAULT_BUNDLE_ROOT } from './bridge-settings-read.mjs';
 import { assertContainedRealPath } from './fs-safe.mjs';
 import { loadWorktreesConfig, resolveProbeDir } from './worktrees.mjs';
+import { preflightCheapAgents } from './cheap-agents.mjs';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const toolPath = (rel) => join(HERE, rel);
@@ -105,10 +106,9 @@ export const SEVERITIES = Object.freeze({
   'read-lane.stale': SEVERITY_ATTENTION,
   'read-lane.missing': SEVERITY_ATTENTION,
   'state-block': SEVERITY_OPTIONAL,
+  agents: SEVERITY_OPTIONAL,
   'family-freshness': SEVERITY_ATTENTION,
   'sandbox-masks': SEVERITY_OPTIONAL,
-  'agy-adddir': SEVERITY_OPTIONAL,
-  'agy-adddir.invalid-env': SEVERITY_ATTENTION,
   'sandbox-lane': SEVERITY_OPTIONAL,
   'worktrees-dir': SEVERITY_OPTIONAL,
 });
@@ -163,11 +163,10 @@ export const WHATS = Object.freeze({
   'read-lane.stale': 'the read-lane is ON but the placed gate hook is stale — an old hook never reads lanes.json, so the lane is silently dark; reseed it',
   'read-lane.missing': 'the gate hook is wired but its placed file is missing — every Bash call errors and the read-lane is dark; re-place it',
   'state-block': 'nothing checks the closing state block — a turn that ends on «nothing needed from you», or on a promise it never started, passes unseen',
+  agents: '{n} read-only subagent(s) not placed (Claude Code) — no shell-free vehicle for that work; the apply PREVIEWS first',
   'family-freshness': '{parts}',
   'sandbox-masks': '{n} sandbox device mask(s) clutter git status — the managed exclude block is absent or stale',
   'sandbox-masks.stale-real': '{n} sandbox device mask(s) clutter git status — the exclude block is stale; {m} fenced entr(ies) are REAL paths (a fresh apply drops them)',
-  'agy-adddir': 'agy-review is placed but AGY_REVIEW_ALLOW_ADDDIR is not set ({file}) — an oversized code review refuses instead of offloading',
-  'agy-adddir.invalid-env': 'AGY_REVIEW_ALLOW_ADDDIR is set to an INVALID value ({value}) — refuse-mode applies and the settings file is shadowed while it is set',
   'sandbox-lane': 'the wired review wrappers declare a session-sandbox recipe (egress hosts + writable state dirs) not yet acknowledged for this project',
   'worktrees-dir': 'write access to the worktrees parent dir {dir} is not confirmed — provision may still stop',
 });
@@ -211,19 +210,73 @@ export const BENEFITS = Object.freeze({
   'autonomy-policy': 'clarity — the per-activity autonomy policy becomes an explicit, versioned declaration instead of implicit computed defaults',
   'autonomy-render': `velocity — confined commands auto-allow per your declared policy; ${DUAL_SECURITY_BENEFIT}`,
   'sandbox-provision': `velocity — confined ad-hoc commands stop prompting; ${DUAL_SECURITY_BENEFIT}`,
-  'review-recipe': 'review coverage — the review recipe you configured actually runs instead of silently degrading',
+  'review-recipe': 'recipe coverage — the review AND execution recipes you configured actually run instead of silently degrading',
   'gates-declaration': 'velocity — your project’s gates run as ONE declared batch with a PASS/FAIL table',
   'gate-hook': 'velocity — your own declared gate commands auto-approve byte-exactly (opt-in PreToolUse hook)',
   'commit-guard': 'integrity — commits require the ONE green --final receipt at the exact staged fingerprint (consented pre-commit arm)',
   'read-lane': 'velocity — pipes/chains of your seeded read-only commands auto-approve instead of prompting (opt-in, conservatively classified)',
   'state-block': 'no silent stalls — a turn ending on «you are not needed», or on work it never started, warns at once instead of waiting to be spotted',
+  agents: 'cost and quiet — mechanical work runs on a cheap model, and no vehicle has a shell, so a read-only fan-out cannot flood you with prompts',
   'family-freshness': 'currency — placed family members carry the latest shipped fixes and features',
   'sandbox-masks': 'zero clutter — git status shows only your changes (the review domain already ignores the masks by construction)',
-  'agy-adddir': 'large reviews — an oversized agy code review offloads to a staging dir instead of refusing',
   'sandbox-lane': 'discoverability — the manifest-declared observed sandbox recipe for bridge runs surfaces itself instead of waiting to be asked',
   'worktrees-dir': 'parallel features — the host-specific write allowance or terminal fallback is surfaced before provision',
 });
 
+// ── the CLOSED opt-in capability registry (OPT-IN-SHIPS-INVISIBLE) ──────────────────────────────
+// 3.14.0 shipped a capability with every surface an AGENT reads and NO advisor entry, so `upgrade`
+// told a user their setup was optimal while the thing that had just shipped sat unwired. Every other
+// surface of a mode is drift-guarded; the advisor was the one that was not, and it is the only
+// surface a user receives PASSIVELY.
+//
+// Keyed by CAPABILITY, not by mode: a per-mode registry cannot detect a new opt-in added INSIDE an
+// already-registered mode (the read-lane belongs to mode `hook`), because the mode set does not move.
+// Each id is DECLARED at its point of use in references/modes/<mode>.md and this registry is asserted
+// set-equal to those declarations (test/advisor-coverage.test.mjs), mirroring the catalog ⟷ SKILL.md
+// ⟷ mode-docs triangle commands.test.mjs already enforces.
+//
+// Every row carries EXACTLY ONE of `advisorKey` (the offer that observes its unconfigured state) or
+// `exempt` (a stated reason it legitimately has none). Adding a capability ADDS a checked row; it
+// never widens a blocklist.
+export const OPT_IN_CAPABILITIES = Object.freeze([
+  { id: 'velocity-core', mode: 'velocity', advisorKey: 'velocity-core' },
+  { id: 'kit-tools-tier', mode: 'velocity', advisorKey: 'kit-tools-tier' },
+  { id: 'bridge-tier', mode: 'velocity', advisorKey: 'bridge-tier' },
+  { id: 'autonomy-render', mode: 'velocity', advisorKey: 'autonomy-render' },
+  { id: 'sandbox-lane', mode: 'velocity', advisorKey: 'sandbox-lane' },
+  { id: 'autonomy-policy', mode: 'set-autonomy', advisorKey: 'autonomy-policy' },
+  { id: 'sandbox-provision', mode: 'autonomy-doctor', advisorKey: 'sandbox-provision' },
+  { id: 'gates-declaration', mode: 'gates', advisorKey: 'gates-declaration' },
+  { id: 'gate-hook', mode: 'hook', advisorKey: 'gate-hook' },
+  { id: 'read-lane', mode: 'hook', advisorKey: 'read-lane' },
+  { id: 'commit-guard', mode: 'commit-guard', advisorKey: 'commit-guard' },
+  { id: 'state-block', mode: 'state-block-guard', advisorKey: 'state-block' },
+  { id: 'sandbox-masks', mode: 'sandbox-masks', advisorKey: 'sandbox-masks' },
+  { id: 'worktrees-dir', mode: 'worktrees', advisorKey: 'worktrees-dir' },
+  { id: 'family-freshness', mode: 'upgrade', advisorKey: 'family-freshness' },
+  { id: 'review-recipe', mode: 'set-recipe', advisorKey: 'review-recipe' },
+  // The execute slot is a DISTINCT opt-in from the review slot, and the same probe reports both —
+  // which is why the review-recipe benefit is worded for either slot rather than for review alone.
+  { id: 'delegated-execution', mode: 'set-recipe', advisorKey: 'review-recipe' },
+  { id: 'agents', mode: 'agents', advisorKey: 'agents' },
+  // Exempt, not un-audited. `acceptEdits` auto-applies Edit/Write and auto-runs mkdir/touch/mv/cp:
+  // a TRUST-POSTURE change. The kit never nudges a user toward weakening their approval posture (the
+  // same doctrine that keeps sandbox network/filesystem allowances HAND-APPLY); velocity presents the
+  // full honest posture at its own consent moment, where the user is already deciding.
+  {
+    id: 'accept-edits',
+    mode: 'velocity',
+    exempt: 'a trust-posture change (auto-applied edits, auto-run mkdir/touch/mv/cp) — the kit never nudges a user toward weakening their own approval posture; velocity states the full posture at its own consent moment',
+  },
+  // Exempt for the mirror-image reason: the Fast tier bills at a higher credit rate, so an unprompted
+  // offer would be the kit nudging the user to spend money.
+  {
+    id: 'codex-fast',
+    mode: 'bridge-settings',
+    exempt: 'a paid SPEND knob (the priority tier bills at a higher credit rate) — the kit never nudges a user toward spending money; bridge-settings surfaces it with its cost caveat when asked',
+  },
+].map((c) => Object.freeze(c)));
+
 // A typed usage failure (exit 2) — the codebase's typed-error idiom (no classes).
 const usageFail = (message) => Object.assign(new Error(message), { exitCode: 2 });
 
@@ -462,6 +515,42 @@ const probeStateBlockHook = ({ root, deps, add, skip }) => {
   }
 };
 
+// The cheap-agents offer (OPT-IN-SHIPS-INVISIBLE). This item exists because the coverage registry
+// surfaced its absence: `agents` is the family's SECOND `.claude/` writer, the `help` Tune tail
+// advertises it, and the advisor had no entry for it — so a user who never runs `help` never learned
+// it existed while the advisor reported the deployment optimal. Found by the guard, not by an incident.
+// Only a PLACE action counts as a gap: `already-current` is converged and `customized-preserved` is
+// the user's own edit, which the writer never clobbers and the advisor must never nag about.
+const probeCheapAgents = ({ root, deps, add, skip }) => {
+  try {
+    const preflight = preflightCheapAgents({ cwd: root }, deps);
+    // The writer refuses below the expected lineage, so offering its command would hand the user a
+    // guaranteed failure — the honest surface is a stated skip naming the recovery.
+    if (!preflight.stampOk) {
+      skip('agents', new Error(`not a deployed agent-workflow project at the current lineage (found ${preflight.stamp ?? 'none'}) — run upgrade first`));
+      return;
+    }
+    const toPlace = preflight.plan.filter((item) => item.action === 'place');
+    if (toPlace.length === 0) return; // converged
+    // The writer's contract is «--dry-run first, ALWAYS» (references/modes/agents.md, and its stated
+    // invariant «preview by default»), so the rendered line is the PREVIEW — this item joins the
+    // dry-run-preview class the mode doc already documents for the gates-declaration seeder, where the
+    // same confirmation then runs the follow-up the preview prints. Rendering --apply here would have
+    // skipped the per-vehicle plan the user is supposed to see before consenting.
+    // The hidden-mode reconcile rides the detail, never the apply line: it is wrong to run on a
+    // VISIBLE deployment, and the apply slot must stay one pure executable command.
+    add(
+      'agents',
+      fillTemplate(WHATS.agents, { n: toPlace.length }),
+      `node ${q(toolPath('cheap-agents.mjs'))} --cwd ${q(root)}`,
+      'agents',
+      `hidden-mode deployments only: after the --apply the preview prints, run node ${q(toolPath('hide-footprint.mjs'))} --dir ${q(root)} --reconcile so the placed .claude/agents/ stays invisible to git status`,
+    );
+  } catch (err) {
+    skip('agents', err);
+  }
+};
+
 const probeFamilyFreshness = ({ deps, add, skip }) => {
   try {
     const survey = deps.surveyFamily ?? surveyFamily;
@@ -502,53 +591,13 @@ const probeMasksItem = ({ root, deps, add, skip }) => {
   }
 };
 
-const probeAgyAdddir = ({ deps, add, skip }) => {
-  try {
-    const probePlaced = deps.findWrapper ?? ((cmd) => findOnPath(cmd, deps).state === 'present');
-    if (!probePlaced('agy-review')) return;
-    // Configured means a VALID boolean value (the wrapper validates and falls back to the default
-    // on garbage — presence alone proves nothing). An explicit valid 0 is a user CHOICE
-    // (refuse mode) — respected, never nagged. env > file, the wrappers' own precedence.
-    const isValidBool = (v) => v === '0' || v === '1';
-    const env = deps.getenv ?? process.env;
-    if (env.AGY_REVIEW_ALLOW_ADDDIR != null) {
-      if (isValidBool(env.AGY_REVIEW_ALLOW_ADDDIR)) return; // an explicit valid env choice — respected
-      // A SET-BUT-EMPTY env var is the wrapper's opt-out shape (${!key+x}: it shadows the file
-      // and falls back to the built-in refuse default) — a user CHOICE, never nagged (codex).
-      if (env.AGY_REVIEW_ALLOW_ADDDIR === '') return;
-      // env > file: while ANY env value is set the wrapper ignores the settings file, so the file
-      // writer cannot fix an invalid env — the honest apply is to fix/unset the env var (codex).
-      const value = truncatedTo(oneLineOf(JSON.stringify(env.AGY_REVIEW_ALLOW_ADDDIR)), templateBudget(WHATS['agy-adddir.invalid-env']));
-      add('agy-adddir', fillTemplate(WHATS['agy-adddir.invalid-env'], { value }), 'HAND-APPLY: unset AGY_REVIEW_ALLOW_ADDDIR in the environment (or export it as 1), THEN configure it durably via the bridge-settings writer', 'agy-adddir.invalid-env');
-      return;
-    }
-    const confPath = settingsPath({ getenv: env, home: deps.home });
-    const readFile = deps.readFile ?? readFileSync;
-    const text = (() => {
-      try {
-        return readFile(confPath, 'utf8');
-      } catch (err) {
-        if (err?.code === 'ENOENT') return '';
-        throw err;
-      }
-    })();
-    const parsed = parseSettings(text);
-    const fileEntries = parsed.byKey.get('AGY_REVIEW_ALLOW_ADDDIR');
-    const fileValue = fileEntries?.length ? fileEntries[fileEntries.length - 1].value : null;
-    if (fileValue != null && isValidBool(fileValue)) return; // env is absent here — a valid file value governs
-    // The settings writer REFUSES a duplicate-carrying file — rendering its command would hand
-    // the user a guaranteed failure; the honest apply is fix-duplicates-first (codex terminal).
-    const dups = duplicateKeys(parsed);
-    const what = fillTemplate(WHATS['agy-adddir'], { file: SETTINGS_FILENAME });
-    if (dups.length > 0) {
-      add('agy-adddir', what, `HAND-APPLY: ${SETTINGS_FILENAME} carries duplicate key(s) (${dups.join(', ')}) and the settings writer refuses to edit it — remove the duplicate lines by hand, THEN run: node ${q(toolPath('bridge-settings.mjs'))} --set AGY_REVIEW_ALLOW_ADDDIR=1 --apply`);
-      return;
-    }
-    add('agy-adddir', what, `node ${q(toolPath('bridge-settings.mjs'))} --set AGY_REVIEW_ALLOW_ADDDIR=1 --apply`);
-  } catch (err) {
-    skip('agy-adddir', err);
-  }
-};
+// probeAgyAdddir is GONE, not silenced. It offered to arm AGY_REVIEW_ALLOW_ADDDIR with the benefit
+// "large reviews — an oversized agy code review offloads to a staging dir instead of refusing".
+// Headless agy AUTO-DENIES its own read_file tool, so that lane could return a confident fabrication
+// (two BLOCKING findings citing lines of a file that has none, observed) or an empty SHIP, with no
+// way to tell — the advisor was recommending the one lane whose failure mode is undetectable. The
+// knob is retired in the wrappers (recognized, arms nothing) and an oversized code review is now a
+// chunked feed with a per-part delivery proof, so there is nothing left to offer.
 
 // The manifest-declared session-sandbox recipe surfaces of every BUNDLED bridge whose review
 // wrapper is in the wired set — networkHosts ∪ writableDirs, derived from the manifests (the
@@ -713,7 +762,7 @@ const readAckValue = (root, deps, ackKey) => {
 // false (the lane is off — offer it). `readLane === true` → enabled (converged). A parse/IO error on
 // an EXISTING file, a symlinked ancestor/leaf, an escape, or a non-object root THROWS — the probe
 // turns it into a stated skip (a BROKEN toggle the writer would refuse to overwrite is not "off").
-// A present-but-non-boolean `readLane` is a valid store the writer merges → false (offer), never a skip.
+// A present-but-non-boolean value is a valid store the writer merges → false (offer), never a skip.
 const readReadLaneToggle = (root, deps) => {
   const readFile = deps.readFile ?? readFileSync;
   const lstat = deps.lstat ?? lstatSync;
@@ -739,7 +788,7 @@ const readReadLaneToggle = (root, deps) => {
 // D3: the risk-marked keys — every key here has a per-item posture note in the mode doc, surfaced
 // at the consent moment; the static contract test asserts EXACT bidirectional coverage
 // (risk-marked keys == mode-doc note keys — a dropped note goes red, not silent).
-export const RISK_NOTED_KEYS = Object.freeze(['agy-adddir', 'sandbox-lane', 'read-lane', 'worktrees-dir']);
+export const RISK_NOTED_KEYS = Object.freeze(['sandbox-lane', 'read-lane', 'worktrees-dir']);
 
 const probeSandboxLane = ({ root, deps, add, skip }) => {
   try {
@@ -926,9 +975,9 @@ const PROBES = Object.freeze([
   probeCommitGuard,
   probeReadLane,
   probeStateBlockHook,
+  probeCheapAgents,
   probeFamilyFreshness,
   probeMasksItem,
-  probeAgyAdddir,
   probeSandboxLane,
   probeWorktreesDir,
 ]);
@@ -946,7 +995,8 @@ export const buildRecommendations = ({ cwd, deps = {} } = {}) => {
   // its class differs from the base (the invalid-env attention arm).
   // `detail` (optional) is an extra rendered `recipe:` line — factual context that is TOO LONG for
   // the capped WHAT and does NOT belong in the pure-command apply (the sandbox-lane live recipe:
-  // egress hosts + resolved writable dirs). Single-line like apply; absent for every other item.
+  // egress hosts + resolved writable dirs; the worktrees-dir hand-apply-first grant advice; the
+  // agents hidden-mode reconcile follow-up). Single-line like apply; absent for every other item.
   const add = (key, what, apply, severityKey = key, detail = null) => {
     const problems = [];
     if (!(key in BENEFITS)) problems.push(`unregistered item key ${JSON.stringify(key)}`);
@@ -1005,7 +1055,8 @@ Usage:
 Computes the deterministic Recommendations section every kit upgrade ends with — VERDICT-FIRST:
 one composed verdict line opens every non-optimal render, then per item {severity · what is
 sub-optimal · the benefit in one plain line · an optional \`recipe:\` line (the sandbox-lane live
-recipe, or the worktrees-dir hand-apply-first grant advice) · the exact consent-gated apply one-liner}. --cwd is
+recipe, the worktrees-dir hand-apply-first grant advice, or the agents hidden-mode reconcile
+follow-up) · the exact consent-gated apply one-liner}. --cwd is
 REQUIRED (the target project is explicit, never inferred from the shell's current directory). The
 section renders present-even-when-empty ("${RECOMMENDATIONS_EMPTY_LINE}"); a probe failure is a
 stated skipped-item line. Apply lines are cwd-independent (absolute tool paths, a pinned --cwd;

package/tools/renderers.mjs

@@ -60,8 +60,17 @@ const renderBridges = (vm, { glyph, color }) => {
     // 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(' · ');
+      // A RETIRED knob is CONFIGURED but arms nothing. It must still SHOW — the line really is in
+      // the user's file — but rendering it like any other active setting would claim a capability
+      // the wrapper no longer has, which is the exact confusion the retirement exists to prevent.
+      const active = b.settings.active
+        .map((s) => `${s.key}=${s.value} [${s.source}]${s.retired ? ' RETIRED — arms nothing' : ''}`)
+        .join(' · ');
       lines.push(`  ${pad('', MEMBER_COL)}settings: ${active}`);
+      const retired = b.settings.active.filter((s) => s.retired);
+      for (const s of retired) {
+        lines.push(`  ${pad('', MEMBER_COL)}${glyph.note} ${s.key} is retired — clear it with: bridge-settings --unset ${s.key} --apply`);
+      }
     }
   }
   return lines;

package/tools/review-state.mjs

@@ -244,6 +244,7 @@ export const backendReceiptStatus = (receipts, backend, fingerprint) => {
     markerRejected: summary.markerRejected,
     unmarkedRejected: summary.unmarkedRejected,
     postureRejected: summary.postureRejected,
+    deliveryRejected: summary.deliveryRejected,
   };
   if (summary.state === 'current') {
     return { state: 'current', verdict: summary.receipt.verdict ?? 'unknown', shipClass: isShipVerdict(summary.receipt.verdict), grounded: true, timestamp: summary.receipt.timestamp ?? null, ...counts };
@@ -373,6 +374,9 @@ const rejectionCause = (b) => {
   if ((b.postureRejected ?? 0) > 0) {
     parts.push(`${b.postureRejected} with an absent/invalid run posture (D5) — a pre-posture wrapper minted it; re-run the review on the current bridge`);
   }
+  if ((b.deliveryRejected ?? 0) > 0) {
+    parts.push(`${b.deliveryRejected} with an absent/invalid delivery declaration (D8b) — the receipt never declared HOW the change set reached the model, so delivery was not proven; re-run the review on the current bridge`);
+  }
   return parts.join(' + ');
 };