@sabaiway/agent-workflow-kit 10.2.0 → 10.4.0

package/tools/recommendations.mjs

@@ -32,7 +32,6 @@
 // idiom).
 
 import { readFileSync, readdirSync, lstatSync, existsSync } from 'node:fs';
-import { createHash } from 'node:crypto';
 import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -52,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';
@@ -83,7 +82,28 @@ 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 {
+  ACKS_FILE,
+  ACKS_LANE_KEY,
+  ACKS_WORKTREES_DIR_KEY,
+  ACKS_COVERAGE_DOMAIN_KEY,
+  ACKS_SOURCE_SIZE_COPY_KEY,
+  ACK_LANES,
+  factFingerprint,
+  readAckValue,
+} from './ack-store.mjs';
+import { ADOPTION, STORE_DIR_REL as SPEC_STORE_DIR_REL, SPEC_ADOPTION_LANE, declineFingerprint, readDeclineAck, surveySpecAdoption } from './spec-adoption.mjs';
+import { ENSURE_OPS } from './ensure-vocabulary.mjs';
+
+// The upgrade ensure that seeds the spec store — the not-adopted item's apply; pinned to the vocabulary.
+const SPEC_LAYER_ENSURE = ENSURE_OPS.includes('specs') ? 'specs' : null;
+
+export { ACKS_FILE, ACKS_LANE_KEY, ACKS_WORKTREES_DIR_KEY, ACKS_COVERAGE_DOMAIN_KEY, ACKS_SOURCE_SIZE_COPY_KEY, ACK_LANES, factFingerprint };
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const toolPath = (rel) => join(HERE, rel);
@@ -158,11 +178,20 @@ 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,
   'sandbox-lane': SEVERITY_OPTIONAL,
   'worktrees-dir': SEVERITY_OPTIONAL,
+  // The layer is opt-in, so both arms are OFFERS under the frozen registry (attention is a CONFIGURED
+  // declaration that is broken): an absent store offers the seed, a store with no live contract offers
+  // the decline. Neither arm can leave the flow-optimal line standing — an offer is still an item.
+  'spec-adoption': SEVERITY_OPTIONAL,
+  'spec-adoption.adopting': SEVERITY_OPTIONAL,
 });
 // The per-item render tags (frozen presentation data, same language contract as the templates).
 export const SEVERITY_LABELS = Object.freeze({
@@ -227,13 +256,16 @@ 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',
   '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)',
   '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',
+  'spec-adoption': 'feature-spec store absent (docs/ai/specs) — no feature contract can govern a plan here yet; seed the store, or record the decline',
+  'spec-adoption.adopting': 'feature-spec store: {n} draft spec(s), no live contract — nothing governs a plan through it yet; land a live contract, or record the decline',
 });
 
 // ── the shape contract (D2): registry strings AND composed items stay one line under the cap ────
@@ -284,12 +316,14 @@ 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)',
   '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',
+  'spec-adoption': 'contracts — a plan names the contract it builds to, and a change to a governed slice is visible at review instead of after it',
 });
 
 // ── the CLOSED opt-in capability registry (OPT-IN-SHIPS-INVISIBLE) ──────────────────────────────
@@ -332,12 +366,19 @@ export const OPT_IN_CAPABILITIES = Object.freeze([
   { id: 'mcp-channel', mode: 'mcp', advisorKey: 'mcp-channel' },
   { id: 'worktrees-dir', mode: 'worktrees', advisorKey: 'worktrees-dir' },
   { id: 'family-freshness', mode: 'upgrade', advisorKey: 'family-freshness' },
+  // The feature-spec layer is delivered by upgrade's spec-layer ensure (there is no specs mode), so
+  // its adoption state is declared where the store is seeded.
+  { id: 'spec-adoption', mode: 'upgrade', advisorKey: 'spec-adoption' },
   { id: 'adr-store-migration', mode: 'migrate-adr-store', advisorKey: 'adr-store-migration' },
   { 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' },
+  // 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
@@ -448,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})`);
       }
     }
@@ -923,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) {
@@ -935,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;
@@ -1042,41 +1136,13 @@ export const recipeFingerprint = ({ hosts, dirs, home }) => {
     if (abs === homeAbs) return '~';
     return abs.startsWith(`${homeAbs}/`) ? `~/${abs.slice(homeAbs.length + 1)}` : abs;
   };
-  const canonical = JSON.stringify({ hosts: [...hosts].sort(), dirs: [...new Set(dirs.map(norm))].sort() });
-  return createHash('sha256').update(canonical).digest('hex').slice(0, 16);
+  return factFingerprint(JSON.stringify({ hosts: [...hosts].sort(), dirs: [...new Set(dirs.map(norm))].sort() }));
 };
 
-// The fingerprint for an acknowledgment whose subject is already a canonical STRING — the census
-// fact, the sorted set of declared tool-elsewhere claims — rather than a hosts ∪ dirs recipe. Same
-// 16-hex shape the ack writer validates, so every lane records one comparable token; the canonical
-// form is the caller's, because only the caller knows which part of its fact is durable and which
-// is churn (the census binds the verdict + extension set, never per-file counts).
-export const factFingerprint = (fact) => createHash('sha256').update(fact).digest('hex').slice(0, 16);
-
-// The kit-owned neutral ack store (D4; AD-055 Part I): a FAMILY-OWNED strict-JSON file no host
-// validator guards — top-level key `sandboxLaneAck` (+ optional `_README`), unknown keys tolerated
-// on read (future acks are siblings). This is the PRIMARY ack channel; the legacy settings-scope
-// keys below are read for one deprecation window. The sandbox/permissions security keys are NEVER
-// consulted as an ack.
-export const ACKS_FILE = 'docs/ai/acks.json';
-export const ACKS_LANE_KEY = 'sandboxLaneAck';
-export const ACKS_WORKTREES_DIR_KEY = 'worktreesDirAck';
-export const ACKS_COVERAGE_DOMAIN_KEY = 'coverageDomainAck';
-export const ACKS_SOURCE_SIZE_COPY_KEY = 'sourceSizeCopyAck';
-// The CLOSED-WORLD ack-lane registry: the lane name an advisor item renders on the writer's
-// command line → the store key that writer sets. A lane the registry does not name is a usage
-// refusal at the writer, never a newly-invented key in the shared store.
-//
-// An ack lane exists for a state the maintainer can only ANSWER, never converge: a tracked tree the
-// coverage domain cannot reach, a checker deliberately vendored elsewhere. It is deliberately NOT
-// available to a state that is simply BROKEN — a dead checker/producer pair is fixed, not
-// acknowledged, so no lane names it.
-export const ACK_LANES = Object.freeze({
-  'sandbox-lane': ACKS_LANE_KEY,
-  'worktrees-dir': ACKS_WORKTREES_DIR_KEY,
-  'coverage-domain': ACKS_COVERAGE_DOMAIN_KEY,
-  'source-size-copy': ACKS_SOURCE_SIZE_COPY_KEY,
-});
+// The ack store (D4; AD-055 Part I) is the kit-owned PRIMARY ack channel; the legacy settings-scope
+// keys below are read for one deprecation window. An ack lane exists for a state the maintainer can
+// only ANSWER, never converge — a dead checker/producer pair is fixed, not acknowledged, so no lane
+// names it. The store's path, keys, lane registry and reader are ack-store.mjs (re-exported above).
 
 // The opt-in read-lane toggle file (AD-055 Part II) — the SAME kit-owned docs/ai/lanes.json the
 // placed hook reads live. The read-lane item offers to enable it once the hook is placed+wired.
@@ -1146,38 +1212,6 @@ const declarationCarriesMarker = (root, deps) => {
 export const SANDBOX_LANE_ACK_PARENT = 'agentWorkflow';
 export const SANDBOX_LANE_ACK_KEY = 'sandboxLaneAck';
 
-// Read the family-owned ack store. An ABSENT file (or absent docs/ai) is the NORMAL not-yet-acked
-// state → null (plain fall-through, never a skip). A parse/IO error on an EXISTING file THROWS — the
-// probe's catch turns it into a stated skip line (Decisions 2). A non-object root is a malformed
-// store (fail-closed skip); a non-string value at the key is tolerated → null (the item re-fires).
-// The WHOLE path chain (root / docs / ai / acks.json) is guarded WITHOUT following symlinks
-// BEFORE any read: a symlinked ANCESTOR could otherwise read an ack from OUTSIDE the project (the
-// writer refuses such a deployment — the reader must too), a symlinked/dangling LEAF must not read as
-// not-yet-acked, and a non-regular target (FIFO/dir/device) is a fail-closed SKIP — never read it (a
-// FIFO would BLOCK the advisor). ENOENT-safe: an absent file/dir is the NORMAL not-yet-acked null.
-const readAckValue = (root, deps, ackKey) => {
-  const readFile = deps.readFile ?? readFileSync;
-  const lstat = deps.lstat ?? lstatSync;
-  const absPath = join(root, ACKS_FILE);
-  let st;
-  try {
-    assertContainedRealPath(root, absPath, { lstat }); // symlinked root/ancestor/leaf or escape → throws
-    st = lstat(absPath);
-  } catch (err) {
-    if (err?.code === 'ENOENT') return null; // genuinely absent (file or docs/ai) — normal not-yet-acked
-    throw err; // a symlinked ancestor/leaf, an escape, or a real IO error — stated skip
-  }
-  if (!st.isFile()) {
-    throw new Error(`${ACKS_FILE} is not a regular file — refusing to read it`);
-  }
-  const parsed = JSON.parse(readFile(absPath, 'utf8'));
-  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
-    throw new Error(`${ACKS_FILE}: expected a JSON object`);
-  }
-  const value = parsed[ackKey];
-  return typeof value === 'string' ? value : null;
-};
-
 // Read the opt-in read-lane toggle for the read-lane item. An ABSENT file (or absent docs/ai) →
 // 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
@@ -1208,7 +1242,38 @@ 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(['sandbox-lane', 'read-lane', 'worktrees-dir', 'adr-store-migration', 'gates-inert', 'source-size', 'gate-hook', 'mcp-channel']);
+export const RISK_NOTED_KEYS = Object.freeze(['sandbox-lane', 'read-lane', 'worktrees-dir', 'adr-store-migration', 'gates-inert', 'source-size', 'gate-hook', 'mcp-channel', 'spec-adoption']);
+
+// The feature-spec layer's adoption state (contract: kit/spec-adoption). The canon lets a plan cite
+// zero governing specs while a project adopts the layer, and nothing ever said whether adoption had
+// started — an owner found the store absent only by asking. The survey reads the store through
+// spec-check's own census; a recorded decline (the `spec-adoption` ack lane) is the fact that
+// silences the item, and an unreadable store is a stated skip so the flow-optimal line never renders
+// over it. The not-adopted apply is the spec-layer ensure; the decline preview rides the recipe line.
+export const probeSpecAdoption = ({ root, deps, add, skip }) => {
+  try {
+    const survey = surveySpecAdoption(root, deps);
+    if (survey.state === ADOPTION.UNREADABLE) {
+      skip('spec-adoption', new Error(`${survey.reason} — the adoption state under ${SPEC_STORE_DIR_REL} cannot be judged`));
+      return;
+    }
+    if (survey.state === ADOPTION.ADOPTED || readDeclineAck(root, deps)) return;
+    const decline = `node ${q(toolPath('ack-write.mjs'))} --lane ${SPEC_ADOPTION_LANE} --fingerprint ${declineFingerprint()} --cwd ${q(root)}`;
+    if (survey.state === ADOPTION.NOT_ADOPTED) {
+      add(
+        'spec-adoption',
+        fillTemplate(WHATS['spec-adoption'], {}),
+        `node ${q(toolPath('ensure-configs.mjs'))} --reconcile --only ${SPEC_LAYER_ENSURE} --cwd ${q(root)}`,
+        'spec-adoption',
+        `HAND-APPLY alternative (instead of the apply, never after it): decline the layer by recording it — ${decline}`,
+      );
+      return;
+    }
+    add('spec-adoption', fillTemplate(WHATS['spec-adoption.adopting'], { n: survey.draft }), decline, 'spec-adoption.adopting');
+  } catch (err) {
+    skip('spec-adoption', err);
+  }
+};
 
 const probeSandboxLane = ({ root, deps, add, skip }) => {
   try {
@@ -1485,12 +1550,14 @@ const PROBES = Object.freeze([
   probeReadLane,
   probeStateBlockHook,
   probeCheapAgents,
+  probeExecutorVehicle,
   probeFamilyFreshness,
   probeAdrStore,
   probeMasksItem,
   probeSandboxLane,
   probeWorktreesDir,
   probeMcpChannel,
+  probeSpecAdoption,
 ]);
 
 export const buildRecommendations = ({ cwd, deps = {} } = {}) => {

package/tools/renderers.mjs

@@ -8,6 +8,7 @@
 // Pure, no side effects, Node >= 22.
 
 import { BLOCK_TITLES, SETTINGS_LABELS, glyphsFor, NO_DEPLOYMENT } from './presentation.mjs';
+import { describeAdoption } from './spec-adoption.mjs';
 
 const MEMBER_COL = 20;
 const VERSION_COL = 12;
@@ -19,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;
@@ -96,6 +101,14 @@ const renderProject = (vm, { color }) => {
   if (ACTIONABLE_ADR_LAYOUTS.includes(p.adrLayout)) {
     lines.push(`  ${pad('ADR store', STAMP_COL)}old layout — run /agent-workflow-kit migrate-adr-store`);
   }
+  // Every state renders — an owner opens this surface deliberately, so "not adopted" is the one line
+  // that must never be missing; an envelope without the field says so rather than inventing a state.
+  if (p.specs) {
+    const declineNote = p.specs.declineError ? ` (decline ack unreadable: ${p.specs.declineError})` : '';
+    lines.push(`  ${pad('specs', STAMP_COL)}${describeAdoption(p.specs, { declined: p.specs.declined })}${declineNote}`);
+  } else {
+    lines.push(`  ${pad('specs', STAMP_COL)}unknown — the installed kit predates the adoption state`);
+  }
   if (p.visibility) {
     const v = p.visibility.error ? `error: ${p.visibility.error}` : p.visibility.phrase;
     lines.push(`  ${pad('visibility', STAMP_COL)}${v}`);
@@ -107,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.
@@ -127,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);