@sabaiway/agent-workflow-kit 10.3.0 → 10.4.0

package/tools/carriers.mjs

@@ -0,0 +1,140 @@
+// carriers.mjs — the activity/slot registry plus the subagent carrier's readiness composition.
+// ACTIVITIES + SLOT_RECIPES are the ONE table: recipes.mjs re-exports them, so no importer's path
+// moves. The carrier half declares the `subagent` recipe, appends the executor vehicle to a
+// readiness array as the single provider of the `carry` role, words the degrade a missing or
+// unusable vehicle causes, and holds the dispatch-form wording every render prints (one source, a
+// red line where it is a red line). Governing contract: docs/ai/specs/kit/carriers.md.
+// Leaf — imports only the direct-run guard (recipes.mjs imports THIS), no fs, nothing on import.
+import { refuseDirectRun } from './direct-run.mjs';
+
+// The slot VALUE is the slot's TYPE; SLOT_RECIPES lists the values each type accepts. A `switch`
+// slot is a flag, not a recipe: it resolves outside the recipe lattice and never degrades.
+// `policy` marks an activity that is a SESSION with an autonomy level of its own; a routine chore
+// runs inside such a session and carries none.
+export const ACTIVITIES = {
+  'plan-authoring': { slots: { author: 'carrier', review: 'review' }, policy: true },
+  'plan-execution': { slots: { execute: 'execute', review: 'review' }, policy: true },
+  routine: { slots: { carrier: 'carrier', parallel: 'switch' }, policy: false },
+};
+
+export const POLICY_ACTIVITIES = Object.fromEntries(
+  Object.entries(ACTIVITIES).filter(([, activity]) => activity.policy),
+);
+
+export const SLOT_RECIPES = {
+  review: ['solo', 'reviewed', 'council'],
+  execute: ['solo', 'delegated', 'subagent'],
+  carrier: ['solo', 'subagent'],
+  switch: ['on', 'off'],
+};
+
+export const SWITCH_SLOT = 'switch';
+export const SWITCH_DEFAULT = 'on';
+
+export const isSwitchSlot = (slotType) => slotType === SWITCH_SLOT;
+
+export const CARRY_ROLE = 'carry';
+export const EXECUTOR_PROVIDER = 'executor';
+
+export const SUBAGENT_RECIPE = {
+  id: 'subagent',
+  title: 'Subagent',
+  role: CARRY_ROLE,
+  minBackends: 1,
+  degradesTo: 'solo',
+  summary:
+    'a full-tool frontier subagent from the placed executor vehicle carries a bounded, file-disjoint slice; the orchestrator verifies it and commits.',
+};
+
+// The readiness tokens the planner judges on. Mirrored from detect-backends.mjs rather than
+// imported: this module is the leaf the planner itself imports.
+const READY = 'ready';
+const MISSING = 'missing';
+
+const VEHICLE_READY_STATES = ['placed', 'customized'];
+
+// withVehicle(readiness, survey) → a NEW array carrying the executor as the ONE provider of `carry`.
+// Every caller that hands readiness to the resolver composes it this way; a role-filtered readiness
+// computation is what keeps a placed executor from counting as a ready reviewer.
+export const withVehicle = (readiness = [], survey = null) => [
+  ...readiness.filter((entry) => entry?.name !== EXECUTOR_PROVIDER),
+  {
+    name: EXECUTOR_PROVIDER,
+    readiness: VEHICLE_READY_STATES.includes(survey?.state) ? READY : MISSING,
+    vehicle: survey,
+  },
+];
+
+export const EXECUTOR_APPLY = '/agent-workflow-kit agents';
+
+// A survey reason may quote a file the user wrote; it is collapsed to one safe line before it rides
+// the one-line render contracts: no escape sequences, control bytes or line breaks, and none of the
+// characters those renders use as cell structure (the separator, parentheses, the equals sign).
+export const safeLine = (text) => String(text ?? '')
+  .replace(/\x1b\[[0-?]*[ -/]*[@-~]/gu, '')
+  .replace(/[·()=]/gu, ' ')
+  .replace(/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}\s]+/gu, ' ')
+  .trim();
+
+export const vehicleDegradeReason = (survey, applyHint = EXECUTOR_APPLY) => {
+  const state = survey?.state ?? MISSING;
+  const reason = safeLine(survey?.reason);
+  const detail = reason ? ` (${reason})` : '';
+  const remedy = state === 'unusable'
+    ? `fix or remove ${safeLine(survey?.rel) || '.claude/agents/executor.md'}, then place it with: ${applyHint}`
+    : `place it with: ${applyHint}`;
+  return `the executor vehicle is ${state}${detail} — ${remedy}`;
+};
+
+// ── the dispatch form: the ONE wording source every render prints ───────────────────
+// Pure constants. `procedures.mjs` prints them for a slot resolved to `subagent`; the wording is a
+// red line, so a render composes these strings and never re-words one.
+
+// The slice noun is per ACTIVITY — what a bounded slice IS differs for execution, authoring and a
+// routine chore, while the four dispatch lines below are shared by all three.
+export const SLICE_BY_ACTIVITY = {
+  'plan-authoring': 'a slice is a brief naming the goal, the governing spec(s) and the ledger constraints; the subagent drafts the plan or the contract from it, and the orchestrator reviews the draft as its own',
+  'plan-execution': 'a slice is a set of file-disjoint ledger rows; wording is copied verbatim where wording is a red line',
+  routine: "a slice is a bounded mechanical task; a read-only one (a sweep, gate triage) rides its placed read-only vehicle, or is carried solo with a stated reason when that vehicle is absent; a write-capable one (a regeneration, a fixture build) rides the executor; the changelog stays the orchestrator's",
+};
+
+export const VEHICLE_STATE_TOKEN = '<state>';
+
+export const DISPATCH_LINES = [
+  `dispatch: the executor vehicle (.claude/agents/executor.md — ${VEHICLE_STATE_TOKEN}), in the background`,
+  'the orchestrator verifies every returned slice by running its suites itself',
+  'the subagent is never told to commit, never a review backend, never a bridge substitute',
+  'honest limit: a Claude Code lane — on a host that cannot dispatch the vehicle, follow this form by hand and say so',
+];
+
+export const PARALLEL_SOLO_NOTE = '(no effect while the carrier is solo)';
+
+export const PARALLEL_LINES = {
+  on: 'parallel: on — file-disjoint slices dispatch concurrently',
+  off: 'parallel: off — one slice at a time',
+};
+
+// The slot TYPES a subagent can carry — computed from the one value table, never a second list.
+export const SUBAGENT_SLOT_TYPES = Object.entries(SLOT_RECIPES)
+  .filter(([, values]) => values.includes(SUBAGENT_RECIPE.id))
+  .map(([slotType]) => slotType);
+
+// dispatchForm({ activity, slot, state }) → the lines a `subagent`-resolved slot renders: the
+// activity's slice sentence, then the four shared lines with the surveyed vehicle state filled in.
+// A slot whose type cannot hold `subagent` (a review slot) and an unknown activity render nothing.
+export const dispatchForm = ({ activity, slot, state } = {}) => {
+  const slice = SLICE_BY_ACTIVITY[activity];
+  const slotType = ACTIVITIES[activity]?.slots?.[slot];
+  if (!slice || !SUBAGENT_SLOT_TYPES.includes(slotType)) return [];
+  return [slice, ...DISPATCH_LINES.map((line) => line.replace(VEHICLE_STATE_TOKEN, state ?? MISSING))];
+};
+
+// parallelLine({ value, carrier }) → the `routine` switch line. The concurrency claim is TRUE only
+// while the effective carrier is `subagent`; under a solo carrier the flag states its own inertness.
+export const parallelLine = ({ value, carrier } = {}) => {
+  const inert = carrier !== SUBAGENT_RECIPE.id ? ` ${PARALLEL_SOLO_NOTE}` : '';
+  if (value === 'on') return inert ? `parallel: on${inert}` : PARALLEL_LINES.on;
+  return `${PARALLEL_LINES.off}${inert}`;
+};
+
+refuseDirectRun(import.meta.url);

package/tools/cheap-agents-read.mjs

@@ -0,0 +1,172 @@
+// cheap-agents-read.mjs — the READ-ONLY core of the subagent-vehicle surface: the bundle, the
+// placement plan and the executor vehicle's readiness. Split from cheap-agents.mjs (the writer) so
+// the read-only advisor graph (procedures -> recipes) reaches these facts WITHOUT importing a module
+// that can create `.claude/agents/` — by construction, pinned by the read-graph purity walk.
+
+import { existsSync, lstatSync, readFileSync, readdirSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { refuseDirectRun } from './direct-run.mjs';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+export const AGENTS_DIR = '.claude/agents';
+export const CLAUDE_DIR = '.claude';
+export const WORKFLOW_STAMP = 'docs/ai/.workflow-version';
+export const EXPECTED_WORKFLOW_VERSION = '3.0.0';
+export const BUNDLED_AGENTS_DIR = resolve(HERE, '..', 'references', 'agents');
+
+export const UTF8 = 'utf8';
+const ERROR_PREFIX = '[agent-workflow-kit]';
+const EXIT_PRECONDITION = 1;
+
+export const CHEAP_AGENTS_STAMP = 'CHEAP_AGENTS_STAMP';
+export const CHEAP_AGENTS_SYMLINK = 'CHEAP_AGENTS_SYMLINK';
+export const CHEAP_AGENTS_BUNDLE = 'CHEAP_AGENTS_BUNDLE';
+
+export const makeCheapAgentsError = (code, message) =>
+  Object.assign(new Error(`${ERROR_PREFIX} ${message}`), { name: 'CheapAgentsError', code, exitCode: EXIT_PRECONDITION });
+
+// The injectable READ surface — four functions, none of which can create or modify a file. The
+// writer shell adds its own mkdir/writeFile pair rather than widening this one.
+export const readFsDeps = (deps = {}) => ({
+  exists: deps.exists ?? existsSync,
+  lstat: deps.lstat ?? lstatSync,
+  readFile: deps.readFile ?? readFileSync,
+  readdir: deps.readdir ?? readdirSync,
+});
+
+export const lstatNoFollow = (absPath, fs) => {
+  try {
+    return fs.lstat(absPath);
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return null;
+    throw err;
+  }
+};
+
+// ── the bundle (the kit's own references/agents/) ─────────────────────────────────────
+
+export const readBundledAgents = (deps = {}) => {
+  const fs = readFsDeps(deps);
+  const bundleDir = deps.bundleDir ?? BUNDLED_AGENTS_DIR;
+  let names;
+  try {
+    names = fs.readdir(bundleDir);
+  } catch (err) {
+    throw makeCheapAgentsError(CHEAP_AGENTS_BUNDLE, `bundled agents dir unreadable (${err.code ?? err.message}): ${bundleDir}`);
+  }
+  const templates = names
+    .filter((name) => name.endsWith('.md'))
+    .sort()
+    .map((name) => ({ name, content: fs.readFile(join(bundleDir, name), UTF8) }));
+  if (templates.length === 0) {
+    throw makeCheapAgentsError(CHEAP_AGENTS_BUNDLE, `no bundled agent templates found in ${bundleDir} — the kit install is incomplete`);
+  }
+  return templates;
+};
+
+// ── the preflight reads (velocity discipline: symlink-safe, stamp read, no writes) ────
+
+export const readStamp = (absPath, fs) => {
+  try {
+    if (!fs.exists(absPath)) return null;
+    const stamp = String(fs.readFile(absPath, UTF8)).trim();
+    return stamp.length ? stamp : null;
+  } catch {
+    return null; // unreadable stamp == not a valid deployment stamp (apply STOPs; dry-run reports)
+  }
+};
+
+export const assertDirSafe = (absPath, relPath, fs) => {
+  const stat = lstatNoFollow(absPath, fs);
+  if (stat === null) return { absent: true };
+  if (stat.isSymbolicLink()) throw makeCheapAgentsError(CHEAP_AGENTS_SYMLINK, `${relPath} is a symlink — refusing to write through it`);
+  if (!stat.isDirectory()) throw makeCheapAgentsError(CHEAP_AGENTS_SYMLINK, `${relPath} exists but is not a directory — refusing to write through it`);
+  return { absent: false };
+};
+
+// Per-template placement plan: place | already-current | customized-preserved (never clobbered).
+export const planPlacement = (templates, projectDir, deps = {}) => {
+  const fs = readFsDeps(deps);
+  return templates.map((template) => {
+    const rel = `${AGENTS_DIR}/${template.name}`;
+    const abs = join(projectDir, AGENTS_DIR, template.name);
+    const stat = lstatNoFollow(abs, fs);
+    if (stat === null) return { ...template, rel, abs, action: 'place' };
+    if (stat.isSymbolicLink() || !stat.isFile()) {
+      throw makeCheapAgentsError(CHEAP_AGENTS_SYMLINK, `${rel} exists but is not a regular file — refusing to touch it`);
+    }
+    const existing = fs.readFile(abs, UTF8);
+    if (existing === template.content) return { ...template, rel, abs, action: 'already-current' };
+    return { ...template, rel, abs, action: 'customized-preserved', existing };
+  });
+};
+
+// ── the executor vehicle's readiness (the subagent carrier's one instrument) ──────────
+
+export const EXECUTOR_VEHICLE = 'executor.md';
+export const EXECUTOR_VEHICLE_REL = `${AGENTS_DIR}/${EXECUTOR_VEHICLE}`;
+
+// The YAML subset a vehicle's frontmatter is read with: a bare scalar, a single- or double-quoted
+// scalar, or a flow sequence; an unquoted ` #comment` and surrounding whitespace are dropped first.
+const cleanValue = (raw) => {
+  const noComment = String(raw ?? '').replace(/^((?:[^"'#]|"[^"]*"|'[^']*')*?)\s+#.*$/u, '$1').trim();
+  return noComment.replace(/^(["'])(.*)\1$/u, '$2').replace(/^\[(.*)\]$/u, '$1').trim();
+};
+
+// The block-sequence items under the `tools:` key: `- item` lines indented deeper than the key,
+// with blank and comment lines allowed between them; the first other line ends the list.
+const blockItems = (frontmatter) => {
+  const lines = frontmatter.split('\n');
+  const start = lines.findIndex((line) => /^tools:/u.test(line));
+  if (start === -1) return [];
+  const keyIndent = lines[start].match(/^[ \t]*/u)[0].length;
+  const items = [];
+  for (const line of lines.slice(start + 1)) {
+    if (/^[ \t]*(#.*)?$/u.test(line)) continue;
+    const item = line.match(/^([ \t]*)-[ \t]*(.*)$/u);
+    if (!item || item[1].length <= keyIndent) break;
+    const value = cleanValue(item[2]);
+    if (value) items.push(value);
+  }
+  return items;
+};
+
+const executorFrontmatterRefusal = (content) => {
+  const frontmatter = String(content).replace(/\r\n/gu, '\n').match(/^---\n([\s\S]*?)\n---(?:\n|$)/u)?.[1] ?? '';
+  for (const key of ['name', 'tools']) {
+    if ((frontmatter.match(new RegExp(`^${key}:`, 'gmu')) ?? []).length > 1) return `duplicate \`${key}:\` key in the frontmatter`;
+  }
+  if (cleanValue(frontmatter.match(/^name:(.*)$/mu)?.[1]) !== 'executor') return 'frontmatter does not declare `name: executor`';
+  if (!/^tools:/mu.test(frontmatter)) return null;
+  const inline = cleanValue(frontmatter.match(/^tools:(.*)$/mu)?.[1]);
+  const listed = inline || blockItems(frontmatter).join(', ');
+  if (!listed) return 'tools: is empty — grant a list that includes Bash, or drop the line';
+  const granted = listed.split(',').map((tool) => cleanValue(tool));
+  return granted.includes('Bash') ? null : `tools: ${listed} is read-only`;
+};
+
+// A symlinked, non-regular or unreadable vehicle is a STATE the carrier degrades on, so this survey
+// answers it instead of throwing: its callers compose the answer into a readiness array.
+export const surveyExecutorVehicle = (projectDir, deps = {}) => {
+  const rel = EXECUTOR_VEHICLE_REL;
+  try {
+    const template = readBundledAgents(deps).find((item) => item.name === EXECUTOR_VEHICLE);
+    if (!template) throw makeCheapAgentsError(CHEAP_AGENTS_BUNDLE, `${EXECUTOR_VEHICLE} is missing from the bundle`);
+    const fs = readFsDeps(deps);
+    assertDirSafe(join(projectDir, CLAUDE_DIR), CLAUDE_DIR, fs);
+    assertDirSafe(join(projectDir, AGENTS_DIR), AGENTS_DIR, fs);
+    const [placement] = planPlacement([template], projectDir, deps);
+    if (placement.action === 'place') return { state: 'missing', reason: null, rel };
+    if (placement.action === 'already-current') return { state: 'placed', reason: null, rel };
+    const refusal = executorFrontmatterRefusal(placement.existing);
+    return refusal === null
+      ? { state: 'customized', reason: null, rel }
+      : { state: 'unusable', reason: refusal, rel };
+  } catch (err) {
+    return { state: 'unusable', reason: err?.message ?? String(err), rel };
+  }
+};
+
+refuseDirectRun(import.meta.url);

package/tools/cheap-agents.mjs

@@ -1,8 +1,11 @@
 #!/usr/bin/env node
-// cheap-agents.mjs — the onboarding writer behind `/agent-workflow-kit agents`: places the
-// bundled CHEAP-LANE subagent definitions (references/agents/*.md — haiku/low-effort, bounded
-// read-only tools) into a project's .claude/agents/ so mechanical work (sweeps, changelog
-// skeletons, gate triage) stops running on a frontier model by default.
+// cheap-agents.mjs — the onboarding writer behind `/agent-workflow-kit agents`: places the bundled
+// subagent definitions (references/agents/*.md) into a project's .claude/agents/. FOUR vehicles
+// grant NO shell — three ride the cheap lane (haiku/low-effort) so mechanical work (sweeps,
+// changelog skeletons, gate triage) stops running on a frontier model by default, and review-lens
+// is the read-only review opinion. The fifth, `executor`, is the ONE full-tool vehicle: dispatched
+// only for a bounded execution, authoring, or write-capable routine slice the orchestrator verifies, never for read-only work, and it
+// never commits. `surveyExecutorVehicle` is that vehicle's readiness, for the subagent carrier.
 //
 // The family's second `.claude/` writer, the velocity-profile.mjs writer discipline verbatim:
 //   • preview-then-mutate — `--dry-run` is the DEFAULT and writes nothing; `--apply` writes;
@@ -25,29 +28,48 @@
 // state, not an error); 1 precondition STOP (stamp, symlink, missing bundle); 2 usage.
 // Dependency-free, Node >= 22. No side effects on import.
 
-import { existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync, readdirSync } from 'node:fs';
-import { join, resolve, dirname } from 'node:path';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { isDirectRun } from './direct-run.mjs';
 import { shellQuoteArg } from './repo-lex.mjs';
-
-const HERE = dirname(fileURLToPath(import.meta.url));
-
-export const AGENTS_DIR = '.claude/agents';
-export const CLAUDE_DIR = '.claude';
-export const WORKFLOW_STAMP = 'docs/ai/.workflow-version';
-export const EXPECTED_WORKFLOW_VERSION = '3.0.0';
-export const BUNDLED_AGENTS_DIR = resolve(HERE, '..', 'references', 'agents');
+// The READ core, never a second copy: the bundle, the placement plan and the executor survey live
+// there so the read-only advisor graph can reach them without reaching this writer.
+import {
+  AGENTS_DIR,
+  CLAUDE_DIR,
+  WORKFLOW_STAMP,
+  EXPECTED_WORKFLOW_VERSION,
+  UTF8,
+  CHEAP_AGENTS_STAMP,
+  makeCheapAgentsError,
+  readFsDeps,
+  readBundledAgents,
+  readStamp,
+  assertDirSafe,
+  planPlacement,
+} from './cheap-agents-read.mjs';
+
+export {
+  AGENTS_DIR,
+  CLAUDE_DIR,
+  WORKFLOW_STAMP,
+  EXPECTED_WORKFLOW_VERSION,
+  BUNDLED_AGENTS_DIR,
+  CHEAP_AGENTS_STAMP,
+  CHEAP_AGENTS_SYMLINK,
+  CHEAP_AGENTS_BUNDLE,
+  makeCheapAgentsError,
+  readBundledAgents,
+  planPlacement,
+  surveyExecutorVehicle,
+  EXECUTOR_VEHICLE,
+  EXECUTOR_VEHICLE_REL,
+} from './cheap-agents-read.mjs';
 
 const EXIT_OK = 0;
 const EXIT_PRECONDITION = 1;
 const EXIT_USAGE = 2;
-const UTF8 = 'utf8';
-const ERROR_PREFIX = '[agent-workflow-kit]';
-
-export const CHEAP_AGENTS_STAMP = 'CHEAP_AGENTS_STAMP';
-export const CHEAP_AGENTS_SYMLINK = 'CHEAP_AGENTS_SYMLINK';
-export const CHEAP_AGENTS_BUNDLE = 'CHEAP_AGENTS_BUNDLE';
 
 // The fallback-lens contract, formalized where it lives (flow-orchestration #15/#3, Phase 4.3):
 // the internal-attestation evaluation consumes this sentence — a lens set claiming a configured
@@ -57,95 +79,24 @@ export const FALLBACK_LENS_ADDITIONAL_ONLY = 'review-lens is an ADDITIONAL read-
 
 const USAGE = `usage: cheap-agents [--dry-run | --apply] [--cwd <dir>] [--help]
 
-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.
+Places the bundled subagent definitions into the project's ${AGENTS_DIR}/. Four vehicles grant NO
+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. The fifth, executor, is the ONE full-tool vehicle: dispatched only for a bounded execution,
+authoring, or write-capable routine slice the orchestrator verifies, never for read-only work, and
+it never commits.
+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 });
 
-export const makeCheapAgentsError = (code, message) =>
-  Object.assign(new Error(`${ERROR_PREFIX} ${message}`), { name: 'CheapAgentsError', code, exitCode: EXIT_PRECONDITION });
-
-const fsDeps = (deps = {}) => ({
-  exists: deps.exists ?? existsSync,
-  lstat: deps.lstat ?? lstatSync,
+const writeFsDeps = (deps = {}) => ({
   mkdir: deps.mkdir ?? mkdirSync,
-  readFile: deps.readFile ?? readFileSync,
   writeFile: deps.writeFile ?? writeFileSync,
-  readdir: deps.readdir ?? readdirSync,
 });
 
-const lstatNoFollow = (absPath, fs) => {
-  try {
-    return fs.lstat(absPath);
-  } catch (err) {
-    if (err && err.code === 'ENOENT') return null;
-    throw err;
-  }
-};
-
-// ── the bundle (the kit's own references/agents/) ─────────────────────────────────────
-
-export const readBundledAgents = (deps = {}) => {
-  const fs = fsDeps(deps);
-  const bundleDir = deps.bundleDir ?? BUNDLED_AGENTS_DIR;
-  let names;
-  try {
-    names = fs.readdir(bundleDir);
-  } catch (err) {
-    throw makeCheapAgentsError(CHEAP_AGENTS_BUNDLE, `bundled agents dir unreadable (${err.code ?? err.message}): ${bundleDir}`);
-  }
-  const templates = names
-    .filter((name) => name.endsWith('.md'))
-    .sort()
-    .map((name) => ({ name, content: fs.readFile(join(bundleDir, name), UTF8) }));
-  if (templates.length === 0) {
-    throw makeCheapAgentsError(CHEAP_AGENTS_BUNDLE, `no bundled agent templates found in ${bundleDir} — the kit install is incomplete`);
-  }
-  return templates;
-};
-
-// ── preflight (velocity discipline: symlink-safe, stamp read, no writes) ──────────────
-
-const readStamp = (absPath, fs) => {
-  try {
-    if (!fs.exists(absPath)) return null;
-    const stamp = String(fs.readFile(absPath, UTF8)).trim();
-    return stamp.length ? stamp : null;
-  } catch {
-    return null; // unreadable stamp == not a valid deployment stamp (apply STOPs; dry-run reports)
-  }
-};
-
-const assertDirSafe = (absPath, relPath, fs) => {
-  const stat = lstatNoFollow(absPath, fs);
-  if (stat === null) return { absent: true };
-  if (stat.isSymbolicLink()) throw makeCheapAgentsError(CHEAP_AGENTS_SYMLINK, `${relPath} is a symlink — refusing to write through it`);
-  if (!stat.isDirectory()) throw makeCheapAgentsError(CHEAP_AGENTS_SYMLINK, `${relPath} exists but is not a directory — refusing to write through it`);
-  return { absent: false };
-};
-
-// Per-template placement plan: place | already-current | customized-preserved (never clobbered).
-export const planPlacement = (templates, projectDir, deps = {}) => {
-  const fs = fsDeps(deps);
-  return templates.map((template) => {
-    const rel = `${AGENTS_DIR}/${template.name}`;
-    const abs = join(projectDir, AGENTS_DIR, template.name);
-    const stat = lstatNoFollow(abs, fs);
-    if (stat === null) return { ...template, rel, abs, action: 'place' };
-    if (stat.isSymbolicLink() || !stat.isFile()) {
-      throw makeCheapAgentsError(CHEAP_AGENTS_SYMLINK, `${rel} exists but is not a regular file — refusing to touch it`);
-    }
-    const existing = fs.readFile(abs, UTF8);
-    if (existing === template.content) return { ...template, rel, abs, action: 'already-current' };
-    return { ...template, rel, abs, action: 'customized-preserved' };
-  });
-};
-
 export const preflightCheapAgents = ({ cwd }, deps = {}) => {
-  const fs = fsDeps(deps);
+  const fs = readFsDeps(deps);
   const projectDir = cwd ?? process.cwd();
   const templates = readBundledAgents(deps);
   const stamp = readStamp(join(projectDir, WORKFLOW_STAMP), fs);
@@ -159,7 +110,7 @@ export const preflightCheapAgents = ({ cwd }, deps = {}) => {
 // ── the writer ────────────────────────────────────────────────────────────────────────
 
 export const writeCheapAgents = ({ cwd, dryRun = true } = {}, deps = {}) => {
-  const fs = fsDeps(deps);
+  const fs = writeFsDeps(deps);
   const preflight = preflightCheapAgents({ cwd }, deps);
   if (dryRun) return { wrote: false, dryRun: true, ...preflight };
 
@@ -186,8 +137,8 @@ const ACTION_LABEL = {
 export const formatResult = (result) => {
   const lines = [
     result.dryRun
-      ? 'agent-workflow read-only subagents — DRY RUN (no changes)'
-      : 'agent-workflow read-only subagents — APPLY',
+      ? 'agent-workflow subagent vehicles — DRY RUN (no changes)'
+      : 'agent-workflow subagent vehicles — APPLY',
   ];
   for (const item of result.plan) {
     const verb = result.dryRun && item.action === 'place' ? 'would place' : ACTION_LABEL[item.action];
@@ -197,8 +148,9 @@ 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 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; ${FALLBACK_LENS_ADDITIONAL_ONLY} Writing code and running gates stay on your main lane.`,
+    'four 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 of those ride the cheap lane (model: haiku, effort: low) for mechanical work; ${FALLBACK_LENS_ADDITIONAL_ONLY}`,
+    'executor is the one FULL-TOOL vehicle: dispatched only for a bounded execution, authoring, or write-capable routine slice the orchestrator verifies, never for read-only work, and it never commits.',
   );
   // 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

package/tools/commands.mjs

@@ -131,7 +131,7 @@ const CATALOG = [
     invocation: invocationOf('agents'),
     group: 'Configure',
     kind: WRITER,
-    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).',
+    oneLine: 'Place the bundled subagent vehicles: four read-only ones, none granted a shell — three cheap-model ones for mechanical work (sweeps, changelog skeletons, gate triage) and a review lens — plus the one full-tool executor that carries bounded slices you verify (Claude Code; opt-in; preview first).',
   },
   {
     key: 'hook',
@@ -180,7 +180,7 @@ const CATALOG = [
     invocation: invocationOf('recipes'),
     group: 'Orchestrate',
     kind: READ_ONLY,
-    oneLine: 'See the orchestration recipes (Solo / Reviewed / Council / Delegated), which one fits this environment, and the configured per-activity line to paste at session start.',
+    oneLine: 'See the orchestration recipes (Solo / Reviewed / Council / Delegated / Subagent), which one fits this environment, and the configured per-activity line to paste at session start.',
   },
   {
     key: 'procedures',
@@ -341,7 +341,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        shell-free subagents: cheap ones take the mechanical work, a review lens gives an extra read-only opinion`,
+  `  ${BARE_INVOCATION} agents        subagent vehicles: four read-only (cheap ones take the mechanical work, a review lens gives another opinion) + the one full-tool executor that carries bounded slices you verify`,
   `  ${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/direct-run.mjs

@@ -56,6 +56,12 @@ export const LIBRARY_ONLY_MODULES = Object.freeze({
   // Named by references/modes/mcp.md as the read half the advisor and uninstall ask. It only ever
   // REPORTS; the command that acts on what it reports is the mode itself.
   'mcp-registration.mjs': '/agent-workflow-kit mcp',
+  // Named by references/modes/set-recipe.md as the activity/slot registry; the command that shows
+  // the recipes it defines, resolved for this environment, is the recipes advisor.
+  'carriers.mjs': '/agent-workflow-kit recipes',
+  // The READ core of the subagent-vehicle surface: it sits one name away from the writer
+  // references/modes/agents.md DOES name, and reaching for it is reaching for the agents mode.
+  'cheap-agents-read.mjs': '/agent-workflow-kit agents',
 });
 
 // The frozen refusal line. One line, names the module, names the command.