@sabaiway/agent-workflow-kit 10.3.0 → 10.5.0

package/tools/recommendations.mjs

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

package/tools/renderers.mjs

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

package/tools/repo-lex.mjs

@@ -20,3 +20,43 @@ export const lexicalRepoRelative = (rel) => {
 
 // POSIX single-quote for pasteable command rendering (display only — never an execution boundary).
 export const shellQuoteArg = (s) => (/^[A-Za-z0-9_/.\-]+$/.test(s) ? s : `'${s.replace(/'/g, `'\\''`)}'`);
+
+// The bytes a settings-level allow rule cannot see past: command separators, redirections,
+// expansions and globs. ONE home for the seeder (velocity-profile.mjs, the allow-rule writer) and
+// the renders that must spell a path in the seeded byte-form (procedures.mjs) — two predicates for
+// one rule drift apart, and a drifted render is a dead allow rule that simply prompts.
+export const SHELL_METACHARACTERS = Object.freeze([
+  '&', '|', ';', '<', '>', '$', '`', '(', ')',
+  '\n', '\r', '\t', '\\', '{', '}', '*', '?', '#', '~', '!',
+]);
+export const hasShellMetacharacter = (cmd) => SHELL_METACHARACTERS.some((ch) => cmd.includes(ch));
+
+// A string a one-line render can carry: no control character (C0 or C1) and no Unicode line or
+// paragraph separator. The receipt-derived fields are REFUSED on it; a plan name is escaped for display.
+const LINE_BREAKING_SOURCE = '[\\p{Cc}\\p{Zl}\\p{Zp}]';
+const LINE_BREAKING = new RegExp(LINE_BREAKING_SOURCE, 'u');
+const LINE_BREAKING_ALL = new RegExp(LINE_BREAKING_SOURCE, 'gu');
+export const isRenderableLine = (value) => typeof value === 'string' && !LINE_BREAKING.test(value);
+export const escapeForDisplay = (value) => String(value).replace(LINE_BREAKING_ALL, (ch) => `\\u${ch.codePointAt(0).toString(16).padStart(4, '0')}`);
+
+// The receipt encoder's carriability rule for an artifact path (S21), the JS twin of the wrappers'
+// refuse_uncarriable_artifact_byte: a quote, a backslash, a C0 control or DEL — deliberately NOT
+// \p{Cc} (C1 is the declared residual, and the two normalizations are parity-pinned on this set).
+// ONE home: the round table's refusal names the byte, the advisor's fallback reads the boolean.
+export const uncarriableArtifactByte = (value) =>
+  value.includes('"') ? 'a double quote' : value.includes('\\') ? 'a backslash' : /[\u0000-\u001f\u007f]/u.test(value) ? 'a control' : null;
+export const isArtifactPathCarriable = (value) => typeof value === 'string' && uncarriableArtifactByte(value) === null;
+
+// Characters that survive whitespace tokenization but break an UNQUOTED byte-exact path rule:
+// shell quoting syntax and glob brackets (SHELL_METACHARACTERS owns the command-level separators/
+// redirections/expansions — `*`/`?` globs included — but not these four).
+const PATH_BREAKING_CHARACTERS = Object.freeze(["'", '"', '[', ']']);
+
+// A path token that can be seeded UNQUOTED into a byte-exact allow rule: POSIX-absolute, no
+// whitespace, no shell metacharacter, no quoting/glob syntax.
+export const isSeedablePathToken = (token) =>
+  typeof token === 'string' &&
+  token.startsWith('/') &&
+  !/\s/u.test(token) &&
+  !hasShellMetacharacter(token) &&
+  !PATH_BREAKING_CHARACTERS.some((ch) => token.includes(ch));

package/tools/review-roster-resolve.mjs

@@ -0,0 +1,104 @@
+import { safeLine, REVIEW_CMD_ALIASES } from './carriers.mjs';
+import { READY, NEEDS_SKILL, NEEDS_CLI, NEEDS_CREDENTIALS, DEGRADED } from './detect-backends.mjs';
+import { parseSlotToken, validateRoster } from './review-roster.mjs';
+import { refuseDirectRun } from './direct-run.mjs';
+
+const READY_STATES = new Set([READY, 'placed', 'customized']);
+
+const setupTarget = (entry) => entry?.setupHint?.local ?? entry?.setupHint?.url ?? null;
+
+export const remedyFor = (entry = {}) => {
+  const setup = setupTarget(entry);
+  if (entry.readiness === NEEDS_SKILL) return setup ? `bridge skill not installed — ${safeLine(setup)}` : 'bridge skill not installed — run /agent-workflow-kit setup';
+  if (entry.readiness === NEEDS_CLI) return setup ? `the CLI is not installed — ${safeLine(setup)}` : 'the CLI is not installed';
+  if (entry.readiness === NEEDS_CREDENTIALS) return 'not signed in (credentials missing)';
+  if (entry.readiness === DEGRADED) return 'wrapper not on PATH — run /agent-workflow-kit setup';
+  return entry.readiness ? safeLine(entry.readiness) : 'bridge readiness unavailable';
+};
+
+export const lensVehicleSpec = (member) => {
+  const parsed = typeof member === 'string' ? parseSlotToken(member) : member;
+  if (parsed.kind !== 'lens') throw new Error(`not a lens member: ${parsed.member ?? member}`);
+  return {
+    stem: parsed.stem,
+    template: parsed.template,
+    model: parsed.model,
+    effort: parsed.effort,
+    tools: 'read-only',
+    derived: parsed.derived,
+  };
+};
+
+export const deriveLensTemplate = (template, spec) => {
+  if (!spec?.derived) return String(template);
+  return String(template)
+    .replace(/^name:.*$/mu, `name: ${spec.stem}`)
+    .replace(/^model:.*$/mu, `model: ${spec.model}`)
+    .replace(/^effort:.*$/mu, `effort: ${spec.effort}`);
+};
+
+const postureValue = (postures, receiptId) => {
+  const value = postures?.[receiptId];
+  if (typeof value === 'string') return value;
+  return value?.state === 'valid' ? value.posture : null;
+};
+
+const bridgeRow = (parsed, readiness, postures) => {
+  const alias = REVIEW_CMD_ALIASES[parsed.instrument];
+  const entry = readiness.find((candidate) => candidate?.name === alias.backend);
+  const state = entry?.readiness ?? NEEDS_SKILL;
+  return {
+    member: parsed.member,
+    stem: parsed.stem,
+    kind: 'bridge',
+    state,
+    reason: state === READY ? null : remedyFor({ ...entry, readiness: state }),
+    posture: postureValue(postures, parsed.stem),
+  };
+};
+
+const lensRow = (parsed, surveyLens) => {
+  if (typeof surveyLens !== 'function') {
+    return {
+      member: parsed.member, stem: parsed.stem, kind: 'lens', state: 'unsurveyed',
+      reason: null, posture: null,
+    };
+  }
+  const survey = surveyLens(lensVehicleSpec(parsed)) ?? {};
+  const state = survey.state ?? 'unusable';
+  const posture = READY_STATES.has(state) && survey.model && survey.effort
+    ? `model=${safeLine(survey.model)} effort=${safeLine(survey.effort)}`
+    : null;
+  return {
+    member: parsed.member,
+    stem: parsed.stem,
+    kind: 'lens',
+    state,
+    reason: survey.reason == null ? null : safeLine(survey.reason),
+    posture,
+  };
+};
+
+export const resolveRoster = ({ value, readiness = [], surveyLens, postures } = {}) => {
+  validateRoster(value);
+  return value.map((member) => {
+    const parsed = parseSlotToken(member);
+    return parsed.kind === 'bridge'
+      ? bridgeRow(parsed, readiness, postures)
+      : lensRow(parsed, surveyLens);
+  });
+};
+
+export const isReadyMember = (row) => READY_STATES.has(row.state);
+
+export const skippedLine = (row, remedy = row.reason) =>
+  `skipped this round — ${safeLine(row.state)}: ${remedy ?? 'no remedy recorded'}`;
+
+export const rosterLabel = (roster, { states = true } = {}) => roster.map((row) => {
+  if (!states || isReadyMember(row)) return row.member;
+  return `${row.member} (${safeLine(row.state)})`;
+}).join(' + ');
+
+export const activeLineCell = (roster, options) => `[${rosterLabel(roster, options)}]`;
+
+refuseDirectRun(import.meta.url);

package/tools/review-roster.mjs

@@ -0,0 +1,128 @@
+import { REVIEW_CMD_ALIASES, receiptIdOfCmd, LENS_VERDICTS } from './carriers.mjs';
+import { KNOWN_BACKENDS } from './detect-backends.mjs';
+import { refuseDirectRun } from './direct-run.mjs';
+
+export { LENS_VERDICTS };
+
+export const BUNDLED_LENS_TEMPLATES = Object.freeze(['review-lens']);
+const MEMBER_TOKEN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
+const SUFFIX_TOKEN = /^[a-z0-9]+$/u;
+
+const reviewCommands = () => KNOWN_BACKENDS
+  .map((backend) => backend.roleCmds?.review)
+  .filter(Boolean);
+
+const failRoster = (message, code = null) => Object.assign(new Error(`review roster: ${message}`), { code });
+
+export const parseSlotToken = (member) => {
+  if (typeof member !== 'string' || member.length === 0) {
+    throw failRoster('every member must be a non-empty string');
+  }
+  const bridgeCommands = reviewCommands();
+  if (bridgeCommands.includes(member)) {
+    const alias = REVIEW_CMD_ALIASES[member];
+    if (!alias) throw failRoster(`bridge member "${member}" has no receipt alias`);
+    return {
+      member,
+      instrument: member,
+      kind: 'bridge',
+      stem: alias.receiptId,
+      model: null,
+      effort: null,
+      template: null,
+      derived: false,
+    };
+  }
+  const parts = member.split(':');
+  if (parts.length !== 1 && parts.length !== 3) {
+    if (bridgeCommands.includes(parts[0])) throw failRoster(`bridge member "${parts[0]}" takes no suffix`);
+    throw failRoster(`member "${member}" must be a bare stem or carry both model and effort`);
+  }
+  const [instrument, model = null, effort = null] = parts;
+  if (bridgeCommands.includes(instrument)) throw failRoster(`bridge member "${instrument}" takes no suffix`);
+  if (!MEMBER_TOKEN.test(instrument)) throw failRoster(`member instrument "${instrument}" is not a slug`);
+  if (model !== null && (!SUFFIX_TOKEN.test(model) || !SUFFIX_TOKEN.test(effort))) {
+    throw failRoster(`member "${member}" has an invalid model or effort token`);
+  }
+  if (model !== null && !BUNDLED_LENS_TEMPLATES.includes(instrument)) {
+    throw failRoster(`derived member "${member}" has no bundled lens template`);
+  }
+  return {
+    member,
+    instrument,
+    kind: 'lens',
+    stem: model === null ? instrument : `${instrument}-${model}-${effort}`,
+    model,
+    effort,
+    template: BUNDLED_LENS_TEMPLATES.includes(instrument) ? instrument : null,
+    derived: model !== null,
+  };
+};
+
+export const validateRoster = (value) => {
+  if (!Array.isArray(value)) throw failRoster('value must be an array');
+  if (value.length === 0) throw failRoster('array must not be empty');
+  const parsed = value.map(parseSlotToken);
+  const seen = new Set();
+  for (const member of parsed) {
+    if (seen.has(member.stem)) throw failRoster(`duplicate resolved stem "${member.stem}"`);
+    seen.add(member.stem);
+  }
+  return value;
+};
+
+export const expandShorthand = (value) => {
+  if (value === 'solo') return { lossless: true, members: [] };
+  if (value === 'council') return { lossless: true, members: reviewCommands() };
+  return { lossless: false, members: null };
+};
+
+export const bridgeMembersOf = (value) => validateRoster(value)
+  .filter((member) => parseSlotToken(member).kind === 'bridge');
+
+export const lensMembersOf = (value) => {
+  const values = Array.isArray(value)
+    ? [value]
+    : Object.values(value ?? {}).flatMap((activity) => (
+      Array.isArray(activity?.review) ? [activity.review] : []
+    ));
+  return values.flat().filter((member) => parseSlotToken(member).kind === 'lens');
+};
+
+export const obligationsOf = (value) => {
+  const backends = bridgeMembersOf(value).map(receiptIdOfCmd);
+  if (backends.length === 0) return { recipe: 'solo', backends, minShip: 0, perBackend: false };
+  return {
+    recipe: backends.length === 1 ? 'reviewed' : 'council',
+    backends,
+    minShip: 1,
+    perBackend: true,
+  };
+};
+
+const explicitMembers = (value) => {
+  if (Array.isArray(value)) return [...value];
+  const expanded = expandShorthand(value);
+  if (!expanded.lossless) throw failRoster('reviewed has no lossless roster expansion');
+  return [...expanded.members];
+};
+
+export const addReviewer = (value, member) => {
+  const next = explicitMembers(value);
+  const parsed = parseSlotToken(member);
+  if (next.some((entry) => parseSlotToken(entry).stem === parsed.stem)) return next;
+  next.push(member);
+  validateRoster(next);
+  return next;
+};
+
+export const removeReviewer = (value, member) => {
+  const next = explicitMembers(value);
+  const stem = parseSlotToken(member).stem;
+  const filtered = next.filter((entry) => parseSlotToken(entry).stem !== stem);
+  if (next.length > 0 && filtered.length === 0) throw failRoster('removing the last member requires the solo shorthand', 'last-member');
+  if (filtered.length > 0) validateRoster(filtered);
+  return filtered;
+};
+
+refuseDirectRun(import.meta.url);

package/tools/review-rounds-cli.mjs

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+import { realpathSync } from 'node:fs';
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { isDirectRun } from './direct-run.mjs';
+import { uncarriableArtifactByte } from './repo-lex.mjs';
+import { readReceipts, resolveReceiptsPath } from './core-evidence.mjs';
+import { loadConfig } from './orchestration-config.mjs';
+import { ACTIVITIES, composeReadiness, requiredBackendsForConfiguredRecipe } from './recipes.mjs';
+import { groupRounds, renderRounds } from './review-rounds.mjs';
+
+const REVIEW_ACTIVITIES = new Set(Object.entries(ACTIVITIES).filter(([, def]) => Object.hasOwn(def.slots, 'review')).map(([name]) => name));
+
+const assertArtifactPathCarryable = (value) => {
+  const byte = uncarriableArtifactByte(value);
+  if (byte !== null) throw new Error(`artifact path contains ${byte} byte, which the receipt encoder cannot carry`);
+};
+
+const gitTopLevel = (cwd, run = spawnSync) => {
+  const result = run('git', ['rev-parse', '--show-toplevel'], { cwd, encoding: 'utf8' });
+  return result.status === 0 ? result.stdout.replace(/\r?\n$/u, '') : null;
+};
+
+export const normalizeArtifactPath = (path, { cwd = process.cwd(), run = spawnSync, realpath = realpathSync, top = gitTopLevel(cwd, run) } = {}) => {
+  assertArtifactPathCarryable(path);
+  const absolute = realpath(resolve(cwd, path));
+  const root = top === null ? null : realpath(top);
+  const rel = root === null ? null : relative(root, absolute);
+  const contained = rel !== null && rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+  const normalized = contained ? rel.split(sep).join('/') : absolute.split(sep).join('/');
+  assertArtifactPathCarryable(normalized);
+  return normalized;
+};
+
+const parseArgs = (argv) => {
+  const values = { activity: 'plan-authoring', artifact: null };
+  for (const [index, arg] of argv.entries()) {
+    if (arg === '--artifact' || arg === '--activity') {
+      const value = argv[index + 1];
+      if (value === undefined || value.startsWith('--')) throw new Error(`${arg} needs a value`);
+      if (arg === '--artifact') values.artifact = value;
+      else values.activity = value;
+      continue;
+    }
+    if (index > 0 && (argv[index - 1] === '--artifact' || argv[index - 1] === '--activity')) continue;
+    throw new Error(`unknown argument: ${arg}`);
+  }
+  if (values.artifact === null) throw new Error('--artifact needs a <path>');
+  if (!REVIEW_ACTIVITIES.has(values.activity)) throw new Error(`--activity must be one of ${[...REVIEW_ACTIVITIES].join(', ')}, got ${values.activity}`);
+  return values;
+};
+
+// Every refusal exits 2: usage, an unreadable store, a malformed config, a detection failure.
+export const main = (argv, deps = {}) => {
+  try {
+    const cwd = deps.cwd ?? process.cwd();
+    const env = deps.env ?? process.env;
+    const { artifact, activity } = parseArgs(argv);
+    const run = deps.run ?? spawnSync;
+    const top = gitTopLevel(cwd, run);
+    const artifactPath = normalizeArtifactPath(artifact, { cwd, run, top });
+    const root = top ?? cwd;
+    const { config } = loadConfig(root);
+    const detection = { failed: false };
+    const readiness = config?.[activity]?.review == null
+      ? composeReadiness(root, { onDetectError: () => { detection.failed = true; }, ...(deps.readinessDeps ?? {}) })
+      : [];
+    const obligation = requiredBackendsForConfiguredRecipe({ config, readiness, detectionFailed: detection.failed, activity });
+    if (obligation.unknowable) throw new Error('backend detection failed — the review obligation is unknowable');
+    const receiptsPath = resolveReceiptsPath(root, env);
+    if (receiptsPath === null) throw new Error('the review receipts store cannot be resolved (not a git work tree and AW_REVIEW_RECEIPTS is unset)');
+    const read = readReceipts(receiptsPath);
+    if (read.readError !== undefined) throw new Error(`the review receipts store is unreadable: ${read.readError}`);
+    const selected = read.receipts.filter((receipt) => receipt.artifactPath === artifactPath);
+    const pathless = read.receipts.filter((receipt) => ['plan', 'diff'].includes(receipt.artifact) && !Object.hasOwn(receipt, 'artifactPath')).length;
+    const grouped = groupRounds(selected, obligation);
+    return {
+      code: 0,
+      stdout: renderRounds({ ...grouped, obligation, artifactPath, pathless, malformed: read.malformed }),
+      stderr: '',
+    };
+  } catch (err) {
+    return { code: 2, stdout: '', stderr: `review-rounds: ${err.message}` };
+  }
+};
+
+if (isDirectRun(import.meta.url)) {
+  const result = main(process.argv.slice(2));
+  if (result.stdout) process.stdout.write(`${result.stdout}\n`);
+  if (result.stderr) process.stderr.write(`${result.stderr}\n`);
+  process.exitCode = result.code;
+}