@sabaiway/agent-workflow-kit 10.3.0 → 10.5.0

package/tools/cheap-agents-read.mjs

@@ -0,0 +1,234 @@
+// 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';
+import { deriveLensTemplate } from './review-roster-resolve.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 CHEAP_AGENTS_CONFIG = 'CHEAP_AGENTS_CONFIG';
+
+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}`;
+export const EXECUTOR_VEHICLE_SPEC = Object.freeze({
+  stem: 'executor', template: 'executor', model: null, effort: null, tools: 'full', derived: false,
+});
+const READ_ONLY_TOOLS = new Set(['Read', 'Grep', 'Glob']);
+
+// 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 stripComment = (raw) => String(raw ?? '').replace(/^((?:[^"'#]|"[^"]*"|'[^']*')*?)\s+#.*$/u, '$1').trim();
+const cleanValue = (raw) => stripComment(raw).replace(/^(["'])(.*)\1$/u, '$2').replace(/^\[(.*)\]$/u, '$1').trim();
+
+const scalarValue = (raw) => {
+  const value = stripComment(raw);
+  const quoted = value.match(/^(["'])(.*)\1$/u);
+  if (quoted) return quoted[2].trim();
+  return /^[[{|>]|["']/u.test(value) ? null : value;
+};
+const scalarOf = (frontmatter, key) => scalarValue(frontmatter.match(new RegExp(`^${key}:(.*)$`, 'mu'))?.[1]);
+
+// 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 frontmatterOf = (content) => String(content).replace(/\r\n/gu, '\n').match(/^---\n([\s\S]*?)\n---(?:\n|$)/u)?.[1] ?? '';
+
+const listedTools = (frontmatter) => {
+  const inline = cleanValue(frontmatter.match(/^tools:(.*)$/mu)?.[1]);
+  return (inline || blockItems(frontmatter).join(', ')).split(',').map((tool) => cleanValue(tool)).filter(Boolean);
+};
+
+const executorFrontmatterRefusal = (frontmatter, stem) => {
+  for (const key of ['name', 'tools']) {
+    if ((frontmatter.match(new RegExp(`^${key}:`, 'gmu')) ?? []).length > 1) return `duplicate \`${key}:\` key in the frontmatter`;
+  }
+  if (scalarOf(frontmatter, 'name') !== stem) return `frontmatter does not declare \`name: ${stem}\``;
+  if (!/^tools:/mu.test(frontmatter)) return null;
+  const granted = listedTools(frontmatter);
+  if (granted.length === 0) return 'tools: is empty — grant a list that includes Bash, or drop the line';
+  return granted.includes('Bash') ? null : `tools: ${granted.join(', ')} is read-only`;
+};
+
+const lensFrontmatter = (frontmatter, stem) => {
+  for (const key of ['name', 'model', 'effort', 'tools']) {
+    const count = (frontmatter.match(new RegExp(`^${key}:`, 'gmu')) ?? []).length;
+    if (count !== 1) return { refusal: count === 0 ? `frontmatter has no \`${key}:\` key` : `duplicate \`${key}:\` key in the frontmatter` };
+  }
+  if (scalarOf(frontmatter, 'name') !== stem) {
+    return { refusal: `frontmatter does not declare \`name: ${stem}\`` };
+  }
+  const scalars = Object.fromEntries(['model', 'effort'].map((key) => [key, scalarOf(frontmatter, key)]));
+  for (const [key, value] of Object.entries(scalars)) {
+    if (value === null) return { refusal: `${key}: is not a scalar` };
+    if (value === '') return { refusal: `${key}: is empty` };
+  }
+  const tools = listedTools(frontmatter);
+  if (tools.length === 0) return { refusal: 'tools: must grant a non-empty read-only list' };
+  const unsafe = tools.find((tool) => !READ_ONLY_TOOLS.has(tool));
+  if (unsafe) return { refusal: `tools: grants non-read-only tool ${unsafe}` };
+  return { refusal: null, ...scalars };
+};
+
+const templateFor = (spec, deps) => {
+  if (spec.template == null) return null;
+  const bundled = readBundledAgents(deps).find((item) => item.name === `${spec.template}.md`);
+  if (!bundled) throw makeCheapAgentsError(CHEAP_AGENTS_BUNDLE, `${spec.template}.md is missing from the bundle`);
+  return {
+    name: `${spec.stem}.md`,
+    content: spec.derived ? deriveLensTemplate(bundled.content, spec) : bundled.content,
+  };
+};
+
+export const surveyVehicle = (projectDir, spec, deps = {}) => {
+  const rel = `${AGENTS_DIR}/${spec.stem}.md`;
+  try {
+    const template = templateFor(spec, deps);
+    const fs = readFsDeps(deps);
+    assertDirSafe(join(projectDir, CLAUDE_DIR), CLAUDE_DIR, fs);
+    assertDirSafe(join(projectDir, AGENTS_DIR), AGENTS_DIR, fs);
+    const placeholder = template ?? { name: `${spec.stem}.md`, content: null };
+    const [placement] = planPlacement([placeholder], projectDir, deps);
+    if (placement.action === 'place') {
+      const reason = template === null ? 'no bundled template to derive it from' : null;
+      return { state: 'missing', reason, rel };
+    }
+    const frontmatter = frontmatterOf(placement.existing ?? template?.content);
+    if (placement.action === 'already-current') {
+      if (spec.tools !== 'read-only') return { state: 'placed', reason: null, rel };
+      const lens = lensFrontmatter(frontmatter, spec.stem);
+      return lens.refusal === null
+        ? { state: 'placed', reason: null, rel, model: lens.model, effort: lens.effort }
+        : { state: 'unusable', reason: lens.refusal, rel };
+    }
+    if (spec.tools !== 'read-only') {
+      const refusal = executorFrontmatterRefusal(frontmatter, spec.stem);
+      return refusal === null
+        ? { state: 'customized', reason: null, rel }
+        : { state: 'unusable', reason: refusal, rel };
+    }
+    const lens = lensFrontmatter(frontmatter, spec.stem);
+    return lens.refusal === null
+      ? { state: 'customized', reason: null, rel, model: lens.model, effort: lens.effort }
+      : { state: 'unusable', reason: lens.refusal, rel };
+  } catch (err) {
+    return { state: 'unusable', reason: err?.message ?? String(err), rel };
+  }
+};
+
+export const surveyExecutorVehicle = (projectDir, deps = {}) => surveyVehicle(projectDir, EXECUTOR_VEHICLE_SPEC, deps);
+
+refuseDirectRun(import.meta.url);

package/tools/cheap-agents.mjs

@@ -1,13 +1,17 @@
 #!/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;
 //   • deployment-gated — `--apply` STOPs unless docs/ai/.workflow-version equals the lineage
-//     head (a dry-run stays usable on any project);
+//     head (a dry-run stays usable whatever the stamp says; an unreadable orchestration config
+//     STOPs both, since the derived lenses it names cannot be known);
 //   • symlink-safe — a symlinked `.claude` / `.claude/agents` / target file is a STOP, never a
 //     write-through;
 //   • NEVER overwrites an existing .claude/agents/ file whose content differs from the bundled
@@ -22,32 +26,59 @@
 // apply report reminds you.
 //
 // Exit codes: 0 done / dry-run (incl. preserved customizations — a user's file is a legitimate
-// state, not an error); 1 precondition STOP (stamp, symlink, missing bundle); 2 usage.
+// state, not an error); 1 precondition STOP (stamp, symlink, missing bundle, an unreadable
+// orchestration config — the derived lenses it names cannot be known); 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');
+import { loadConfig } from './orchestration-config.mjs';
+import { lensMembersOf } from './review-roster.mjs';
+import { deriveLensTemplate, lensVehicleSpec } from './review-roster-resolve.mjs';
+// 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,
+  CHEAP_AGENTS_BUNDLE,
+  CHEAP_AGENTS_CONFIG,
+  EXECUTOR_VEHICLE,
+  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,
+  CHEAP_AGENTS_CONFIG,
+  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,110 +88,69 @@ 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.
+Configured derived review lenses are planned and placed beside the bundled vehicles.
 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;
-  }
+export const preflightCheapAgents = ({ cwd, derived = [] }, deps = {}) => {
+  const fs = readFsDeps(deps);
+  const projectDir = cwd ?? process.cwd();
+  const templatesByName = new Map(readBundledAgents(deps).map((template) => [template.name, template]));
+  for (const template of derived) templatesByName.set(template.name, template);
+  const templates = [...templatesByName.values()];
+  const stamp = readStamp(join(projectDir, WORKFLOW_STAMP), fs);
+  const stampOk = stamp === EXPECTED_WORKFLOW_VERSION;
+  assertDirSafe(join(projectDir, CLAUDE_DIR), CLAUDE_DIR, fs);
+  assertDirSafe(join(projectDir, AGENTS_DIR), AGENTS_DIR, fs);
+  const plan = planPlacement(templates, projectDir, deps);
+  return { projectDir, stamp, stampOk, plan };
 };
 
-// ── 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;
+const loadConfigOrStop = (cwd, deps) => {
   try {
-    names = fs.readdir(bundleDir);
+    return loadConfig(cwd, deps.readFile, deps.lstat).config;
   } 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`);
+    throw makeCheapAgentsError(CHEAP_AGENTS_CONFIG, `${err?.message ?? err} — the agents writer cannot read the configured review lenses — nothing is placed`);
   }
-  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 configuredDerivedTemplates = (cwd, deps) => {
+  const config = loadConfigOrStop(cwd, deps);
+  const bundle = readBundledAgents(deps);
+  const templates = new Map();
+  for (const member of lensMembersOf(config)) {
+    const spec = lensVehicleSpec(member);
+    if (!spec.derived) continue;
+    const base = bundle.find((template) => template.name === `${spec.template}.md`);
+    if (!base) throw makeCheapAgentsError(CHEAP_AGENTS_BUNDLE, `${spec.template}.md is missing from the bundle`);
+    templates.set(`${spec.stem}.md`, { name: `${spec.stem}.md`, content: deriveLensTemplate(base.content, spec) });
   }
+  return [...templates.values()];
 };
 
-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 projectDir = cwd ?? process.cwd();
-  const templates = readBundledAgents(deps);
-  const stamp = readStamp(join(projectDir, WORKFLOW_STAMP), fs);
-  const stampOk = stamp === EXPECTED_WORKFLOW_VERSION;
-  assertDirSafe(join(projectDir, CLAUDE_DIR), CLAUDE_DIR, fs);
-  assertDirSafe(join(projectDir, AGENTS_DIR), AGENTS_DIR, fs);
-  const plan = planPlacement(templates, projectDir, deps);
-  return { projectDir, stamp, stampOk, plan };
-};
+export const applyCheapAgentsCommand = (root) =>
+  `node ${shellQuoteArg(fileURLToPath(import.meta.url))} --apply --cwd ${shellQuoteArg(root)}`;
 
 // ── the writer ────────────────────────────────────────────────────────────────────────
 
 export const writeCheapAgents = ({ cwd, dryRun = true } = {}, deps = {}) => {
-  const fs = fsDeps(deps);
-  const preflight = preflightCheapAgents({ cwd }, deps);
+  const fs = writeFsDeps(deps);
+  const projectDir = cwd ?? process.cwd();
+  const derived = configuredDerivedTemplates(projectDir, deps);
+  const preflight = preflightCheapAgents({ cwd: projectDir, derived }, deps);
   if (dryRun) return { wrote: false, dryRun: true, ...preflight };
 
   if (!preflight.stampOk) {
@@ -186,8 +176,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];
@@ -196,15 +186,17 @@ export const formatResult = (result) => {
   if (!result.stampOk) {
     lines.push(`note: no current deployment stamp found (${result.stamp ?? 'none'}) — --apply will refuse until init/upgrade runs.`);
   }
+  const readOnlyCount = result.plan.filter((item) => item.name !== EXECUTOR_VEHICLE).length;
   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.`,
+    `${readOnlyCount} vehicles are Claude Code subagents with READ-ONLY tools and NO shell as bundled or derived (a customized file keeps whatever it grants) — so a fan-out on the shipped templates 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
   // bare "re-run with --apply" would leave the caller to reconstruct --cwd and its quoting.
   if (result.dryRun && result.plan.some((item) => item.action === 'place')) {
-    lines.push(`to apply, run exactly: node ${shellQuoteArg(fileURLToPath(import.meta.url))} --apply --cwd ${shellQuoteArg(result.projectDir)}`);
+    lines.push(`to apply, run exactly: ${applyCheapAgentsCommand(result.projectDir)}`);
   }
   if (!result.dryRun && result.wrote) {
     lines.push('hidden-mode note: if this deployment is hidden, run the hide-footprint reconcile so the placed files stay out of `git status`.');

package/tools/commands.mjs

@@ -131,7 +131,7 @@ const CATALOG = [
     invocation: invocationOf('agents'),
     group: 'Configure',
     kind: WRITER,
-    oneLine: 'Place bundled 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/detect-backends.mjs

@@ -97,7 +97,7 @@ const RAW_BACKENDS = [
         ],
         grounding: 'automatic — the wrapper precomputes the full working-tree change set (repo map, status, diffs, untracked contents) and codex auto-merges the root AGENTS.md; no grounding flags',
         continue: [],
-        receipt: 'side effect — a successful review appends one JSON receipt line to <git dir>/agent-workflow-review-receipts.jsonl (AW_REVIEW_RECEIPTS overrides): fingerprint = sha256 over the canonical uncommitted-state payload (staged diff + unstaged diff + untracked-not-ignored contents — the review-payload domain; never-committable untracked paths — character/block devices, FIFOs, sockets — are excluded from the domain entirely, untracked symlinks/directories ride as name-only notes) in code mode, the artifact-file sha256 in plan mode; verdict parsed from the mandated literal verdict line (schema mode: the verdict field); always fresh:true (one-shot) + grounded:true (native AGENTS.md auto-merge, factsHash null); probe = whether the run relaxed the quality guards (CODEX_PROBE=1), written on EVERY receipt so it self-declares — the kit\'s review-state gate rejects a probe-marked receipt (a probe review never attests) and equally rejects an unmarked one (silence is not a declaration); posture = the ACTUAL run posture {model, effort, tier} (tier null on the standard tier), written on EVERY receipt (D5) — the gate rejects a receipt with an absent/invalid posture (a pre-D5 wrapper minted it; re-run the review), one stderr banner line states the same posture, and a posture value carrying control bytes refuses pre-spend in every mode; a run whose final message carries NO recognized \'Verdict: <ship|revise|rethink>\' line — empty or missing output included — exits 4 with NO receipt (D4: a FAILED review to RE-RUN, never a fatal session error); when the dispatch nonce seam is supplied — the AW_REVIEW_NONCE environment value or its plain-argument equivalent --nonce <n> (one seam: the flag assigns the same value; supplying both with different values refuses pre-spend) — under the safe grammar [A-Za-z0-9._-]{1,64} (anything else refuses pre-spend), the wrapper first mints the finding MANIFEST {schema, backend, nonce, fingerprint, findings} beside the receipts file (agent-workflow-finding-manifest-<backend>-<nonce>.json; atomic, no-clobber — a byte-identical rewrite is an idempotent no-op, different bytes refuse loudly) ORDERED before the receipt append — a failed manifest write EXCLUDES the receipt append, so a nonce-supplied dispatch can never land a receipt without its readable manifest; a nonce-less invocation adds NO nonce field and mints NO finding manifest (the existing wrapperVersion field still changes with each bridge release); a write failure warns, never fails the review',
+        receipt: 'side effect — a successful review appends one JSON receipt line to <git dir>/agent-workflow-review-receipts.jsonl (AW_REVIEW_RECEIPTS overrides): fingerprint = sha256 over the canonical uncommitted-state payload (staged diff + unstaged diff + untracked-not-ignored contents — the review-payload domain; never-committable untracked paths — character/block devices, FIFOs, sockets — are excluded from the domain entirely, untracked symlinks/directories ride as name-only notes) in code mode, the artifact-file sha256 in plan mode; durationS = integer wall-clock seconds from CLI start through verdict parsing and the wrapper prints review duration: <n>s; blocking = the count of [blocker] and [major] lines (schema mode: findings with either severity; a payload whose findings cannot be counted fails the run, no receipt); artifactPath = the normalized realpath on plan receipts only (repo-relative inside the work tree, absolute otherwise), while a double quote, backslash or control byte refuses pre-spend because the receipt encoder cannot carry it; verdict parsed from the mandated literal verdict line (schema mode: the verdict field); always fresh:true (one-shot) + grounded:true (native AGENTS.md auto-merge, factsHash null); probe = whether the run relaxed the quality guards (CODEX_PROBE=1), written on EVERY receipt so it self-declares — the kit\'s review-state gate rejects a probe-marked receipt (a probe review never attests) and equally rejects an unmarked one (silence is not a declaration); posture = the ACTUAL run posture {model, effort, tier} (tier null on the standard tier), written on EVERY receipt (D5) — the gate rejects a receipt with an absent/invalid posture (a pre-D5 wrapper minted it; re-run the review), one stderr banner line states the same posture, and a posture value carrying control bytes refuses pre-spend in every mode; a run whose final message carries NO recognized \'Verdict: <ship|revise|rethink>\' line — empty or missing output included — exits 4 with NO receipt (D4: a FAILED review to RE-RUN, never a fatal session error); when the dispatch nonce seam is supplied — the AW_REVIEW_NONCE environment value or its plain-argument equivalent --nonce <n> (one seam: the flag assigns the same value; supplying both with different values refuses pre-spend) — under the safe grammar [A-Za-z0-9._-]{1,64} (anything else refuses pre-spend), the wrapper first mints the finding MANIFEST {schema, backend, nonce, fingerprint, findings} beside the receipts file (agent-workflow-finding-manifest-<backend>-<nonce>.json; atomic, no-clobber — a byte-identical rewrite is an idempotent no-op, different bytes refuse loudly) ORDERED before the receipt append — a failed manifest write EXCLUDES the receipt append, so a nonce-supplied dispatch can never land a receipt without its readable manifest; a nonce-less invocation adds NO nonce field and mints NO finding manifest (the existing wrapperVersion field still changes with each bridge release); a write failure warns, never fails the review',
         notes: [
           'the review posture banner appends a banner-only timeout=<duration> field — exactly the duration handed to timeout(1); the hard-timeout preflight fails CLOSED when no timeout/gtimeout binary exists (the wrapper refuses by name before any CLI run, so an uncapped review run can no longer happen), and the field never enters the receipt posture or the D5 banner↔receipt parity',
           'quote the posture banner verbatim when labeling this dispatch — the banner is the machine-stated posture; a prose re-type drifts',
@@ -139,7 +139,7 @@ const RAW_BACKENDS = [
           'agy-review --continue [--decided @f] [--focus "…"] [--nonce <n>]',
           'agy-review --conversation <id> [--decided @f] [--focus "…"] [--nonce <n>]',
         ],
-        receipt: "side effect — a successful review appends one JSON receipt line to <git dir>/agent-workflow-review-receipts.jsonl (AW_REVIEW_RECEIPTS overrides; plan/diff outside a git tree: warn + skip unless overridden): fingerprint = sha256 over the canonical uncommitted-state payload (staged diff + unstaged diff + untracked-not-ignored contents — the review-payload domain; never-committable untracked paths — character/block devices, FIFOs, sockets — are excluded from the domain entirely, untracked symlinks/directories ride as name-only notes) in code mode, the artifact-file sha256 in plan/diff mode; verdict recorded verbatim from the mandated '### Verdict' section (SHIP / SHIP WITH NITS / REWORK); grounded = whether a NON-EMPTY --facts payload was supplied (code mode refuses pre-spend without one — no run, no receipt — unless --ungrounded/AGY_PROBE=1; in plan/diff an empty payload records grounded:false — fail-closed, the state gate rejects it), factsHash = sha256 of the facts payload; a continuation receipt is fresh:false (informational-only — it cannot attest the folded tree); probe = whether the run relaxed the quality guards (AGY_PROBE=1), written on EVERY receipt so it self-declares — the kit's review-state gate rejects a probe-marked receipt (a probe review never attests) and equally rejects an unmarked one (silence is not a declaration); posture = the ACTUAL run posture {model} (agy has no tier), written on EVERY receipt (D5) — the gate rejects a receipt with an absent/invalid posture (a pre-D5 wrapper minted it; re-run the review), one stderr banner line states the same posture, an ATTESTING review with AGY_MODEL explicitly emptied refuses pre-spend, and a model string carrying control bytes refuses pre-spend in every mode; delivery = how the change set REACHED the model, currently emitted as 'inline' (the whole set rode one prompt — proven by construction) or 'fed' (a chunked feed whose per-part echo proof verified); REQUIRED on every agy code receipt and its ABSENCE is what stops a pre-fed-lane receipt attesting, while the gate accepts any well-formed declaration rather than a particular value; absent by construction on plan/diff/continuation receipts, which carry no change set; a run whose output carries NO recognized '### Verdict' section — empty output included — exits 4 with NO receipt (D4: a FAILED review to RE-RUN, never a fatal session error); when the dispatch nonce seam is supplied — the AW_REVIEW_NONCE environment value or its plain-argument equivalent --nonce <n> (one seam: the flag assigns the same value; supplying both with different values refuses pre-spend) — under the safe grammar [A-Za-z0-9._-]{1,64} (anything else refuses pre-spend), the wrapper first mints the finding MANIFEST {schema, backend, nonce, fingerprint, findings} beside the receipts file (agent-workflow-finding-manifest-<backend>-<nonce>.json; atomic, no-clobber — a byte-identical rewrite is an idempotent no-op, different bytes refuse loudly) ORDERED before the receipt append — a failed manifest write EXCLUDES the receipt append, so a nonce-supplied dispatch can never land a receipt without its readable manifest; a nonce-less invocation adds NO nonce field and mints NO finding manifest (the existing wrapperVersion field still changes with each bridge release); a write failure warns, never fails the review",
+        receipt: "side effect — a successful review appends one JSON receipt line to <git dir>/agent-workflow-review-receipts.jsonl (AW_REVIEW_RECEIPTS overrides; plan/diff outside a git tree: warn + skip unless overridden): fingerprint = sha256 over the canonical uncommitted-state payload (staged diff + unstaged diff + untracked-not-ignored contents — the review-payload domain; never-committable untracked paths — character/block devices, FIFOs, sockets — are excluded from the domain entirely, untracked symlinks/directories ride as name-only notes) in code mode, the artifact-file sha256 in plan/diff mode; durationS = integer wall-clock seconds from CLI start through verdict parsing and the wrapper prints review duration: <n>s; blocking = the count of numbered items in the first ### Blocking section; artifactPath = the normalized realpath on plan/diff receipts only (repo-relative inside the work tree, absolute otherwise), while a double quote, backslash or control byte refuses pre-spend because the receipt encoder cannot carry it; verdict recorded verbatim from the mandated '### Verdict' section (SHIP / SHIP WITH NITS / REWORK); grounded = whether a NON-EMPTY --facts payload was supplied (code mode refuses pre-spend without one — no run, no receipt — unless --ungrounded/AGY_PROBE=1; in plan/diff an empty payload records grounded:false — fail-closed, the state gate rejects it), factsHash = sha256 of the facts payload; a continuation receipt is fresh:false (informational-only — it cannot attest the folded tree); probe = whether the run relaxed the quality guards (AGY_PROBE=1), written on EVERY receipt so it self-declares — the kit's review-state gate rejects a probe-marked receipt (a probe review never attests) and equally rejects an unmarked one (silence is not a declaration); posture = the ACTUAL run posture {model} (agy has no tier), written on EVERY receipt (D5) — the gate rejects a receipt with an absent/invalid posture (a pre-D5 wrapper minted it; re-run the review), one stderr banner line states the same posture, an ATTESTING review with AGY_MODEL explicitly emptied refuses pre-spend, and a model string carrying control bytes refuses pre-spend in every mode; delivery = how the change set REACHED the model, currently emitted as 'inline' (the whole set rode one prompt — proven by construction) or 'fed' (a chunked feed whose per-part echo proof verified); REQUIRED on every agy code receipt and its ABSENCE is what stops a pre-fed-lane receipt attesting, while the gate accepts any well-formed declaration rather than a particular value; absent by construction on plan/diff/continuation receipts, which carry no change set; a run whose output carries NO recognized '### Verdict' section — empty output included — exits 4 with NO receipt (D4: a FAILED review to RE-RUN, never a fatal session error); when the dispatch nonce seam is supplied — the AW_REVIEW_NONCE environment value or its plain-argument equivalent --nonce <n> (one seam: the flag assigns the same value; supplying both with different values refuses pre-spend) — under the safe grammar [A-Za-z0-9._-]{1,64} (anything else refuses pre-spend), the wrapper first mints the finding MANIFEST {schema, backend, nonce, fingerprint, findings} beside the receipts file (agent-workflow-finding-manifest-<backend>-<nonce>.json; atomic, no-clobber — a byte-identical rewrite is an idempotent no-op, different bytes refuse loudly) ORDERED before the receipt append — a failed manifest write EXCLUDES the receipt append, so a nonce-supplied dispatch can never land a receipt without its readable manifest; a nonce-less invocation adds NO nonce field and mints NO finding manifest (the existing wrapperVersion field still changes with each bridge release); a write failure warns, never fails the review",
         notes: [
           'transport: every review dispatch drives the CLI in --output-format json (plus --disable-slash-commands) and the returned envelope is parsed in node (bin/agy-envelope.mjs) — the operator-facing invocations and flags above do NOT change, and on a ZERO exit the wrapper still PRINTS the review text, never JSON. A missing or unreadable envelope on a zero exit is a loud failure with NO receipt, never a downgraded verdict and never a fallback to raw-stdout parsing; a non-zero CLI exit keeps its own code and message, and publishes the captured stdout unchanged from the SINGLE dispatch or the FINAL fed turn (which may therefore be a JSON or partial payload — the envelope is parsed only on a zero exit); an INTERMEDIATE feed turn is the exception, its output stays private (Invariant E) and its failure prints only a named error. Enforced by a PRE-SPEND capability probe, not a version floor: agy --help must advertise --output-format and --disable-slash-commands, node must be >= 22, and bin/agy-envelope.mjs must be present — otherwise the review refuses before any run is spent and names the missing capability',
           'pre-dispatch host-diff: before the FIRST dispatch of this bridge, diff its declared networkHosts against the live sandbox allow-list — a missing host is surfaced to the maintainer BEFORE dispatching, never fired into a known prompt',

package/tools/direct-run.mjs

@@ -56,6 +56,15 @@ 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',
+  'review-roster.mjs': '/agent-workflow-kit recipes',
+  'review-roster-resolve.mjs': '/agent-workflow-kit recipes',
+  'set-recipe-roster.mjs': '/agent-workflow-kit set-recipe',
 });
 
 // The frozen refusal line. One line, names the module, names the command.