@sabaiway/agent-workflow-kit 10.3.0 → 10.4.0

package/tools/recommendations.mjs

@@ -51,7 +51,7 @@ import { loadAutonomy, isSparseSeedConfig, AUTONOMY_REL } from './autonomy-confi
 import { deriveDoctorPlan } from './autonomy-doctor.mjs';
 import { detectBackends, findOnPath } from './detect-backends.mjs';
 import { isDirectRun } from './direct-run.mjs';
-import { ACTIVITIES, resolveActivityRecipe } from './recipes.mjs';
+import { ACTIVITIES, resolveActivityRecipe, composeReadiness, safeLine } from './recipes.mjs';
 import { surveyFamily, surveyGateHook, surveyAdrLayoutStrict } from './family-registry.mjs';
 import { probeSandboxMasks, needsMasksApply } from './sandbox-masks.mjs';
 import { shellQuoteArg } from './review-state.mjs';
@@ -82,7 +82,9 @@ import { loadConfig } from './orchestration-config.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';
+import { preflightCheapAgents, EXECUTOR_VEHICLE } from './cheap-agents.mjs';
+// The vehicle READINESS comes from the read-only half — the same survey `recipes` and `status` read.
+import { surveyExecutorVehicle, readStamp, readFsDeps, WORKFLOW_STAMP, EXPECTED_WORKFLOW_VERSION } from './cheap-agents-read.mjs';
 // The ack store's path, keys, lane registry, fingerprint and guarded reader live in their own leaf
 // (contract: kit/ack-store) — `status` reads the same store, and a second copy is what drifts.
 import {
@@ -176,6 +178,10 @@ export const SEVERITIES = Object.freeze({
   'mcp-channel.masked': SEVERITY_OPTIONAL,
   'mcp-channel.differing': SEVERITY_ATTENTION,
   agents: SEVERITY_OPTIONAL,
+  // The `agents` row above is an OFFER to place vehicles. This one reports a config that ALREADY
+  // names the subagent carrier over a vehicle that cannot carry it — a configured declaration that
+  // is broken, which is what attention means.
+  'executor-vehicle': SEVERITY_ATTENTION,
   'family-freshness': SEVERITY_ATTENTION,
   'adr-store-migration': SEVERITY_ATTENTION,
   'sandbox-masks': SEVERITY_OPTIONAL,
@@ -250,7 +256,8 @@ export const WHATS = Object.freeze({
   'mcp-channel': "the kit's read-only MCP server is not registered here — path questions and literal searches stay shell strings",
   'mcp-channel.masked': '{rel} is a {className} here (a sandbox device mask is the usual cause), so the entry to merge is printed instead',
   'mcp-channel.differing': 'an "{server}" MCP entry is already declared here and DIFFERS from the registration this kit copy would write',
-  agents: '{n} read-only subagent(s) not placed (Claude Code) — no shell-free vehicle for that work; the apply PREVIEWS first',
+  agents: '{n} bundled subagent vehicle(s) not placed (Claude Code) — {ro} read-only, {ex} the full-tool executor; the apply PREVIEWS first',
+  'executor-vehicle': '{n} slot(s) configured subagent but the executor vehicle is {state}{reason} — every such slot runs solo until it is usable',
   'family-freshness': '{parts}',
   'adr-store-migration': 'still on the retired 3-tier ADR layout — {shape}',
   'sandbox-masks': '{n} sandbox device mask(s) clutter git status — the managed exclude block is absent or stale',
@@ -309,7 +316,8 @@ export const BENEFITS = Object.freeze({
   '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',
   'mcp-channel': 'velocity — path facts and literal searches arrive as typed tool calls whose arguments are JSON fields, never a shell string',
-  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',
+  agents: 'cost and quiet — cheap-model mechanical work, no shell on a read-only vehicle (no prompt flood); the executor carries slices you verify',
+  'executor-vehicle': 'carrier readiness — a slot you configured subagent dispatches the subagent it names instead of silently running solo',
   'family-freshness': 'currency — placed family members carry the latest shipped fixes and features',
   'adr-store-migration': 'durability — every decision becomes its own file with a generated navigator, instead of one hand-rotated pile',
   'sandbox-masks': 'zero clutter — git status shows only your changes (the review domain already ignores the masks by construction)',
@@ -367,6 +375,10 @@ export const OPT_IN_CAPABILITIES = Object.freeze([
   // 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' },
+  // A DISTINCT capability from the offer above: the offer converges the moment nothing is left to
+  // PLACE, which a customized-but-unusable executor also satisfies — so it can never observe the
+  // state that makes a configured subagent carrier run solo.
+  { id: 'executor-vehicle', mode: 'agents', advisorKey: 'executor-vehicle' },
   // 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
@@ -477,11 +489,12 @@ const probeReviewRecipe = ({ root, deps, add, skip }) => {
     // The VALIDATED reader (Segment B): a schema-invalid config (unknown activity/slot,
     // bad recipe) throws here and becomes a stated skip — raw JSON.parse would silently ignore it.
     const { config } = loadConfig(root, deps.readFile ?? readFileSync, deps.lstat ?? lstatSync);
-    const detection = detectBackends(deps);
+    const readiness = composeReadiness(root, { ...deps, detect: deps.detect ?? (() => detectBackends(deps)), onDetectError: (err) => { throw err; } });
     const degraded = [];
     for (const [activity, def] of Object.entries(ACTIVITIES)) {
       for (const slot of Object.keys(def.slots)) {
-        const r = resolveActivityRecipe({ config, readiness: detection, activity, slot });
+        if (config?.[activity]?.[slot] === 'subagent') continue; // the executor vehicle has its own probe
+        const r = resolveActivityRecipe({ config, readiness, activity, slot });
         if (r.degradedFrom) degraded.push(`${activity}.${slot}: configured ${r.degradedFrom} degrades to ${r.recipe} (${r.reason})`);
       }
     }
@@ -952,11 +965,9 @@ const probeCheapAgents = ({ root, deps, add, skip }) => {
     // 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',
+    const executors = toPlace.filter((item) => item.name === EXECUTOR_VEHICLE).length;
+    add('agents', fillTemplate(WHATS.agents, { n: toPlace.length, ex: executors, ro: toPlace.length - executors }),
+      `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) {
@@ -964,6 +975,60 @@ const probeCheapAgents = ({ root, deps, add, skip }) => {
   }
 };
 
+// The subagent carrier's ONE instrument (contract: kit/carriers). Neither neighbour can report this
+// state: `probeReviewRecipe` skips a slot configured `subagent` by construction, and the offer above
+// judges only what is left to PLACE — a customized-but-broken vehicle leaves nothing to place. So a
+// project could declare the carrier and have every such slot run solo, unseen.
+const VEHICLE_BROKEN_STATES = Object.freeze(['missing', 'unusable']);
+
+const writerBlock = (root, deps) => {
+  try {
+    preflightCheapAgents({ cwd: root }, deps);
+    return null;
+  } catch (err) {
+    return safeLine(err?.message ?? String(err));
+  }
+};
+
+const probeExecutorVehicle = ({ root, deps, add, skip }) => {
+  try {
+    // The VALIDATED reader, as probeReviewRecipe uses it: a schema-invalid config is a stated skip,
+    // never an item computed over a shape nothing accepted.
+    const { config } = loadConfig(root, deps.readFile ?? readFileSync, deps.lstat ?? lstatSync);
+    const configured = Object.entries(ACTIVITIES).flatMap(([activity, def]) =>
+      Object.keys(def.slots).filter((slot) => config?.[activity]?.[slot] === 'subagent'));
+    if (configured.length === 0) return;
+    const survey = (deps.surveyVehicle ?? surveyExecutorVehicle)(root, deps);
+    if (!VEHICLE_BROKEN_STATES.includes(survey.state)) return;
+    const reason = safeLine(survey.reason ?? '');
+    const stamp = readStamp(join(root, WORKFLOW_STAMP), readFsDeps(deps));
+    const preconditions = [
+      ...(stamp === EXPECTED_WORKFLOW_VERSION ? [] : [`run /agent-workflow-kit upgrade first (deployment stamp ${stamp ?? 'none'}, expected ${EXPECTED_WORKFLOW_VERSION})`]),
+      ...(survey.state === 'unusable' ? [`${reason || 'the vehicle file is unusable'} — fix that`] : []),
+    ];
+    // The writer refuses on ANY vehicle path it cannot touch (a symlinked read-only vehicle blocks a
+    // missing executor's placement too), so its own preflight is the last precondition — named once.
+    const blocked = writerBlock(root, deps);
+    if (blocked && blocked !== reason) preconditions.push(`${blocked} — fix that`);
+    const room = templateBudget(WHATS['executor-vehicle']) - String(configured.length).length - survey.state.length - 2;
+    add(
+      'executor-vehicle',
+      fillTemplate(WHATS['executor-vehicle'], {
+        n: configured.length,
+        state: survey.state,
+        reason: reason && room > 0 ? `: ${truncatedTo(reason, room)}` : '',
+      }),
+      // The writer places a MISSING vehicle; an unusable path (a symlink, a read-only customization)
+      // is kept or refused, so that state's apply is a hand-apply precondition before the writer.
+      `${preconditions.length ? `HAND-APPLY: ${preconditions.join('; ')}, then run: ` : ''}node ${q(toolPath('cheap-agents.mjs'))} --apply --cwd ${q(root)}`,
+      'executor-vehicle',
+      `hidden-mode deployments only: after the apply, run node ${q(toolPath('hide-footprint.mjs'))} --dir ${q(root)} --reconcile so the placed .claude/agents/ stays invisible to git status`,
+    );
+  } catch (err) {
+    skip('executor-vehicle', err);
+  }
+};
+
 const probeFamilyFreshness = ({ deps, add, skip }) => {
   try {
     const survey = deps.surveyFamily ?? surveyFamily;
@@ -1485,6 +1550,7 @@ const PROBES = Object.freeze([
   probeReadLane,
   probeStateBlockHook,
   probeCheapAgents,
+  probeExecutorVehicle,
   probeFamilyFreshness,
   probeAdrStore,
   probeMasksItem,

package/tools/renderers.mjs

@@ -20,6 +20,10 @@ const SETTINGS_COL = 14;
 // checks, so a future token joins the render by joining this line.
 const ACTIONABLE_ADR_LAYOUTS = Object.freeze(['old', 'old-unrotated']);
 
+const DEGRADE_ARROW = '←';
+const EMPTY_CELL = '—';
+const UNKNOWN_EXECUTOR = 'unknown';
+
 const SGR = Object.freeze({ bold: '\x1b[1m', reset: '\x1b[0m' });
 const ANSI_RE = /\x1b\[[0-9;]*m/g;
 export const visibleLength = (s) => s.replace(ANSI_RE, '').length;
@@ -116,13 +120,22 @@ const renderSettings = (vm, { color, glyph }) => {
   const s = vm.project?.settings;
   if (!s) return [];
   const lines = ['', heading(BLOCK_TITLES.settings, color)];
-  // recipes — the effective recipe per slot, or a loud error; a detector floor adds a sub-line.
+  // recipes — one line per slot: the effective recipe, where it came from, and the requested value
+  // a degrade replaced (a joined single line could not carry three activities and their slots), or a
+  // loud error; a detector floor adds a sub-line.
   if (s.recipes?.error) lines.push(`  ${pad(SETTINGS_LABELS.recipes, SETTINGS_COL)}error: ${s.recipes.error}`);
   else if (s.recipes) {
-    const joined = s.recipes.pairs.map((p) => `${p.key}=${p.recipe}`).join(' · ') || '—';
-    lines.push(`  ${pad(SETTINGS_LABELS.recipes, SETTINGS_COL)}${joined}`);
+    const rows = s.recipes.pairs.map((p) => {
+      const source = p.source ? ` (${p.source})` : '';
+      const recovery = p.degradedFrom === 'subagent' ? ' — runs solo until the executor vehicle is usable (/agent-workflow-kit agents)' : '';
+      const degraded = p.degradedFrom ? ` ${DEGRADE_ARROW} degraded from ${p.degradedFrom}${recovery}` : '';
+      return `${p.key}: ${p.recipe}${source}${degraded}`;
+    });
+    (rows.length ? rows : [EMPTY_CELL]).forEach((row, i) => {
+      lines.push(`  ${pad(i === 0 ? SETTINGS_LABELS.recipes : '', SETTINGS_COL)}${row}`);
+    });
     if (s.recipes.detectError) {
-      lines.push(`  ${pad('', SETTINGS_COL)}${glyph.note} couldn't check backends (${s.recipes.detectError}); recipes floored at solo`);
+      lines.push(`  ${pad('', SETTINGS_COL)}${glyph.note} couldn't check backends (${s.recipes.detectError}); bridge-backed recipes floored at solo; the executor vehicle is unaffected`);
     }
   }
   // attribution — effective includeCoAuthoredBy; a real local override is called out.
@@ -136,10 +149,17 @@ 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}`);
   }
-  // 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}`);
+  // cheap agents — the kit-placed .claude/agents/ vehicles: placed count vs the bundle, then the
+  // split the subagent carrier turns on — the read-only vehicles and the ONE executor, whose state
+  // decides whether a slot configured `subagent` can ride it (an unusable one carries its reason).
+  if (s.agents?.error) {
+    const partial = s.agents.executor ? ` — executor ${s.agents.executor}${s.agents.executorReason ? ` (${s.agents.executorReason})` : ''}` : '';
+    lines.push(`  ${pad(SETTINGS_LABELS.agents, SETTINGS_COL)}error: ${s.agents.error}${partial}`);
+  }
   else if (s.agents) {
-    lines.push(`  ${pad(SETTINGS_LABELS.agents, SETTINGS_COL)}placed=${s.agents.placed}/${s.agents.bundled}`);
+    const reason = s.agents.executorReason ? ` (${s.agents.executorReason})` : '';
+    const executor = s.agents.executor == null ? `${UNKNOWN_EXECUTOR} (the installed kit predates the field)` : `${s.agents.executor}${reason}`;
+    lines.push(`  ${pad(SETTINGS_LABELS.agents, SETTINGS_COL)}${s.agents.placed}/${s.agents.bundled} placed — ${s.agents.readOnly} read-only, executor ${executor}`);
   }
   // 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).

package/tools/review-state.mjs

@@ -93,9 +93,9 @@ import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
-import { detectBackends, READY } from './detect-backends.mjs';
+import { detectBackends } from './detect-backends.mjs';
 import { isDirectRun } from './direct-run.mjs';
-import { resolveActivityRecipe, DISPLAY_ALIASES, requiredBackendsForConfiguredRecipe } from './recipes.mjs';
+import { resolveActivityRecipe, DISPLAY_ALIASES, requiredBackendsForConfiguredRecipe, composeReadiness } from './recipes.mjs';
 import { CONFIG_REL, fail, loadConfig } from './orchestration-config.mjs';
 import { resolveFlowStorePath, readFlowStore, deriveFlowOwner, readPlanFrontmatterId } from './flow-store.mjs';
 import { CHAIN_KIND, authoritativeFlowRecords } from './flow-record.mjs';
@@ -309,16 +309,16 @@ export const degradeRecordSet = ({ cwd, env = process.env, fingerprint }) => {
 // work-tree ROOT when one exists — the fingerprint is root-anchored, so a subdirectory invocation
 // must read the same config/plans or a dirty unreceipted tree could false-PASS as "no plan in
 // flight". Outside a git tree the cwd is the only anchor (and --check exits 0).
-export const buildState = ({ cwd, env = process.env, detect = detectBackends, lstat = lstatSync, readFile = readFileSync } = {}) => {
+export const buildState = ({ cwd, env = process.env, detect = detectBackends, surveyVehicle, lstat = lstatSync, readFile = readFileSync } = {}) => {
   const root = gitLine(['rev-parse', '--show-toplevel'], cwd) ?? cwd;
   const { config, source: configSource } = loadConfig(root);
-  let detection = [];
+  // A bridge-detector throw reaches the hook, never a catch that would also lose the surveyed
+  // executor vehicle: bridge readiness goes unknown (fail closed below), the carrier stays known.
   let detectionWarning = null;
-  try {
-    detection = detect();
-  } catch (err) {
-    detectionWarning = `backend detection failed (${(err && err.message) || err}) — readiness unknown.`;
-  }
+  const onDetectError = (err) => {
+    detectionWarning = `backend detection failed (${(err && err.message) || err}) — bridge readiness unknown.`;
+  };
+  const detection = composeReadiness(root, { detect, surveyVehicle, onDetectError });
   // The resolver stays for DISPLAY/diagnostics only; the OBLIGATIONS come from the configured
   // recipe (never the readiness-degraded effective one — no silent solo).
   const resolved = resolveActivityRecipe({ config: config ?? {}, readiness: detection, activity: ACTIVITY, slot: SLOT });
@@ -439,7 +439,6 @@ export const buildState = ({ cwd, env = process.env, detect = detectBackends, ls
     degradedExempt,
     maskedUntracked: countNeverCommittableUntracked(cwd, { lstat }),
     detectionWarning,
-    anyReviewerReady: detection.some((b) => b.readiness === READY),
     flowPresent,
     flowArmed,
     flowBrokenReason,
@@ -733,7 +732,7 @@ export const main = (argv, ctx = {}) => {
     if (argv.includes('--help') || argv.includes('-h')) return { code: 0, stdout: HELP, stderr: '' };
     const unknown = argv.find((a) => !KNOWN_ARGS.has(a));
     if (unknown !== undefined) throw fail(2, `unknown argument: ${unknown}`);
-    const state = buildState({ cwd, env, detect, lstat: ctx.lstat, readFile: ctx.readFile });
+    const state = buildState({ cwd, env, detect, surveyVehicle: ctx.surveyVehicle, lstat: ctx.lstat, readFile: ctx.readFile });
     const check = decideCheck(state);
     // The mask advisory is NON-FAILING by contract: one notice line, never an exit-code arm.
     const advisory = maskAdvisoryLine(state);

package/tools/set-recipe.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // set-recipe.mjs — the WRITER for docs/ai/orchestration.json. The division of labor (AD-025): the AGENT
-// turns plain language into explicit `--set <activity>.<slot>=<recipe>` / `--unset <activity>.<slot>`
+// turns plain language into explicit `--set <activity>.<slot>=<value>` / `--unset <activity>.<slot>`
 // ops; the KIT does the deterministic validate → merge → preview → write. The kit ships NO NL parser
 // (stays dependency-free + deterministic) and performs no `all`-magic — the agent expands "both review"
 // into explicit per-activity ops (asking if scope is unclear).
@@ -17,15 +17,25 @@
 // language when narrating. Exit codes: 0 success (an explicit recipe that gracefully degrades is still
 // 0); 2 usage (bad/duplicate op, --write with zero ops); 1 config error (malformed/unreadable config)
 // or a write STOP (no deployment / symlinked leaf). main(argv, ctx) → { code, stdout, stderr }; cwd /
-// env / home / detect / fs are injectable for host-independent tests.
+// env / home / detect / surveyVehicle / fs are injectable for host-independent tests.
+//
+// It writes every slot of every activity in the registry (carriers.mjs, via recipes.mjs) — the
+// carrier slots and the `routine.parallel` switch included — and resolves each preview against the
+// SAME readiness the recipes advisor composes: detected backends plus the executor-vehicle survey.
 //
 // Dependency-free, Node >= 22. No side effects on import (the isDirectRun idiom).
 
 import { readFileSync, lstatSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { detectBackends } from './detect-backends.mjs';
 import { isDirectRun } from './direct-run.mjs';
-import { resolveActivityRecipe, composeActiveRecipeLine } from './recipes.mjs';
+import {
+  ACTIVITIES,
+  SLOT_RECIPES,
+  EXECUTOR_APPLY,
+  composeReadiness,
+  resolveActivityRecipe,
+  composeActiveRecipeLine,
+} from './recipes.mjs';
 import { loadAutonomy, resolveAutonomy } from './autonomy-config.mjs';
 import {
   CONFIG_REL,
@@ -35,6 +45,7 @@ import {
   parseOp,
   applySetOps,
   serializeConfig,
+  refreshReadme,
   CANON_README,
 } from './orchestration-config.mjs';
 import { writeConfig as writeConfigFs } from './orchestration-write.mjs';
@@ -50,7 +61,7 @@ const parseArgs = (argv) => {
   let write = false;
   let json = false;
   const takeOp = (kind, tok) => {
-    if (tok === undefined || tok.startsWith('--')) throw fail(2, `--${kind} requires <activity>.<slot>${kind === 'set' ? '=<recipe>' : ''}`);
+    if (tok === undefined || tok.startsWith('--')) throw fail(2, `--${kind} requires <activity>.<slot>${kind === 'set' ? '=<value>' : ''}`);
     const op = parseOp(kind, tok);
     const key = `${op.activity}.${op.slot}`;
     if (seen.has(key)) throw fail(2, `duplicate op for "${key}" — name each activity.slot at most once`);
@@ -74,12 +85,24 @@ const parseArgs = (argv) => {
 
 // ── effective-recipe resolution per op (degradation honesty) ────────────────────────
 
+// The readiness EVERY resolution here runs against: the detected bridges plus the executor-vehicle
+// survey, composed by the one helper the recipes CLI uses. Detection is a SECONDARY input — a bridge
+// detector throw must NOT block the write (the config write is readiness-independent) and must not
+// cost the CARRIER either: the hook warns, the bridge half floors at not-ready, the vehicle survives.
+const composeReadinessOrWarn = (cwd, deps, warnings) =>
+  composeReadiness(cwd, {
+    ...deps,
+    onDetectError: (err) => warnings.push(
+      `backend detection failed (${(err && err.message) || err}) — treating every bridge as not ready; recipes needing a bridge degrade to solo (the executor vehicle is unaffected).`,
+    ),
+  });
+
 // A single op's before/after value + the effective recipe it resolves to here (vs live readiness).
 // `to` is null for an unset (falls to the computed default). degradedFrom/reason carry the honesty.
-const resolveOp = (op, current, after, detection) => {
+const resolveOp = (op, current, after, readiness) => {
   const from = current?.[op.activity]?.[op.slot] ?? null;
   const to = after?.[op.activity]?.[op.slot] ?? null;
-  const r = resolveActivityRecipe({ config: after ?? {}, readiness: detection, activity: op.activity, slot: op.slot });
+  const r = resolveActivityRecipe({ config: after ?? {}, readiness, activity: op.activity, slot: op.slot });
   return { activity: op.activity, slot: op.slot, from, to, effective: r.recipe, degradedFrom: r.degradedFrom, reason: r.reason };
 };
 
@@ -127,19 +150,40 @@ const buildJson = ({ changed, unchanged, warnings, writtenPath, noop, activeLine
   activeLine: activeLine ?? null,
 });
 
+// The writable surface, rendered FROM the registry — never re-typed as literals, so an activity, a
+// slot or an accepted value added to the table shows up in the help (and in the doc that quotes it).
+const ACTIVITY_LINES = Object.entries(ACTIVITIES)
+  .map(([activity, def]) => `  ${activity} → ${Object.keys(def.slots).join(', ')}`)
+  .join('\n');
+
+const VALUE_LINES = Object.entries(SLOT_RECIPES)
+  .map(([slotType, values]) => `  ${slotType} slots accept ${values.join(' | ')}`)
+  .join('\n');
+
+const QUALIFIED_SLOTS = Object.entries(ACTIVITIES)
+  .flatMap(([activity, def]) => Object.keys(def.slots).map((slot) => `${activity}.${slot}`))
+  .join(', ');
+
 const HELP = `set-recipe — write the per-project orchestration config (docs/ai/orchestration.json).
 
 Usage:
-  node set-recipe.mjs [--set <activity>.<slot>=<recipe>]... [--unset <activity>.<slot>]... [--write] [--json]
+  node set-recipe.mjs [--set <activity>.<slot>=<value>]... [--unset <activity>.<slot>]... [--write] [--json]
 
-  --set    <activity>.<slot>=<recipe>   pin a recipe (fully-qualified; e.g. plan-authoring.review=council)
+  --set    <activity>.<slot>=<value>   pin a value (fully-qualified; e.g. plan-authoring.review=council)
   --unset  <activity>.<slot>            return a slot to its computed default
   --write                               apply the change (default: preview only — writes nothing)
   --json                                machine-readable output
   --help, -h                            this help
 
-Activities/slots: plan-authoring → review;  plan-execution → execute, review
-Recipes:          review accepts solo|reviewed|council;  execute accepts solo|delegated
+Activities and their slots:
+${ACTIVITY_LINES}
+
+Accepted values per slot type:
+${VALUE_LINES}
+
+A carrier slot set to subagent needs the executor vehicle placed in this project — ${EXECUTOR_APPLY};
+without it the slot resolves to solo with the reason stated. routine.parallel is a flag, not a
+recipe: it never degrades.
 
 Previews by default; --write applies via an atomic, symlink/TOCTOU-safe write behind a deployment gate.
 Config writer only: it NEVER runs a backend and NEVER commits. Hand-editing the file stays fully supported.
@@ -152,7 +196,7 @@ Exit codes: 0 success (an explicit recipe that gracefully degrades is still 0);
 
 export const main = (argv, ctx = {}) => {
   const cwd = ctx.cwd ?? process.cwd();
-  const detect = ctx.detect ?? detectBackends;
+  const readinessDeps = { detect: ctx.detect, surveyVehicle: ctx.surveyVehicle };
   const readFile = ctx.readFileSync ?? readFileSync;
   const lstat = ctx.lstatSync ?? lstatSync;
   const writeConfig = ctx.writeConfig ?? writeConfigFs;
@@ -170,23 +214,18 @@ export const main = (argv, ctx = {}) => {
         return { code: 0, stdout: JSON.stringify(buildJson({ changed: [], unchanged: [], warnings: [], writtenPath: null, noop: true }), null, 2), stderr: '' };
       }
       const shown = current == null ? `(no ${CONFIG_REL} yet — computed defaults apply)` : serializeConfig(current).replace(/\n$/, '');
-      const hint = `\nPass --set <activity>.<slot>=<recipe> (preview) then --write to apply. Activities/slots: plan-authoring.review, plan-execution.execute, plan-execution.review.`;
+      const hint = `\nPass --set <activity>.<slot>=<value> (preview) then --write to apply. Activities/slots: ${QUALIFIED_SLOTS}.`;
       return { code: 0, stdout: `${source === 'none' ? '' : `${CONFIG_REL}:\n`}${shown}${hint}`, stderr: '' };
     }
 
-    const after = applySetOps(current, ops, { seedReadme: CANON_README });
+    // The merged config, then the _README refresh: a note that normalize-matches a KNOWN PRIOR canonical
+    // is replaced by the current one on a touched write, while a customized note stays untouched.
+    const after = refreshReadme(applySetOps(current, ops, { seedReadme: CANON_README })).config;
 
-    // Detection is a SECONDARY input — it only refines the EFFECTIVE recipe note. A throw must NOT block
-    // the write (the config write is readiness-independent): treat all backends as not-ready, warn, exit 0.
     const warnings = [];
-    let detection = [];
-    try {
-      detection = detect();
-    } catch (err) {
-      warnings.push(`backend detection failed (${(err && err.message) || err}) — treating all backends as not ready; recipes needing a backend degrade to solo.`);
-    }
+    const readiness = composeReadinessOrWarn(cwd, readinessDeps, warnings);
 
-    const resolved = ops.map((op) => resolveOp(op, current, after, detection));
+    const resolved = ops.map((op) => resolveOp(op, current, after, readiness));
     const changed = resolved.filter((e) => e.from !== e.to);
     const unchanged = resolved.filter((e) => e.from === e.to);
     const noop = changed.length === 0;
@@ -220,7 +259,7 @@ export const main = (argv, ctx = {}) => {
         return { error: (err && err.message) || String(err) };
       }
     })();
-    const activeLine = composeActiveRecipeLine({ config: after, source: CONFIG_REL }, detection, autonomyFacts);
+    const activeLine = composeActiveRecipeLine({ config: after, source: CONFIG_REL }, readiness, autonomyFacts);
     const stdout = json
       ? JSON.stringify(buildJson({ changed, unchanged, warnings, writtenPath, noop: false, activeLine }), null, 2)
       : formatHuman({ changed, unchanged, warnings, wrote: true, fileBody, activeLine });

package/tools/view-model.mjs

@@ -54,7 +54,11 @@ const recipesVm = (r) => {
   if (r.error) return { error: r.error };
   const pairs = [];
   for (const [activity, slots] of Object.entries(r.activities ?? {})) {
-    for (const [slot, v] of Object.entries(slots)) pairs.push({ key: `${activity}.${slot}`, recipe: v.recipe });
+    // source + degradedFrom ride along: an effective recipe alone cannot tell a chosen value from a
+    // computed default, nor a degrade from a configuration that really names the resolved recipe.
+    for (const [slot, v] of Object.entries(slots)) {
+      pairs.push({ key: `${activity}.${slot}`, recipe: v.recipe, source: v.source ?? null, degradedFrom: v.degradedFrom ?? null });
+    }
   }
   return { pairs, detectError: r.detectError ?? null };
 };
@@ -76,8 +80,18 @@ const velocityVm = (v) => {
 
 const agentsVm = (a) => {
   if (!a) return null;
-  if (a.error) return { error: a.error };
-  return { bundled: a.bundled ?? 0, placed: a.placed ?? 0 };
+  if (a.error) return { error: a.error, executor: a.executor ?? null, executorReason: a.executorReason ?? null };
+  const bundled = a.bundled ?? 0;
+  return {
+    bundled,
+    placed: a.placed ?? 0,
+    // The envelope counts the read-only vehicles; an envelope predating the executor field bundled
+    // only read-only ones.
+    readOnly: a.readOnly ?? (a.executor == null ? bundled : Math.max(bundled - 1, 0)),
+    // null = an envelope predating the field (unknown), never a state.
+    executor: a.executor ?? null,
+    executorReason: a.executorReason ?? null,
+  };
 };
 
 const hookVm = (h) => {