@sabaiway/agent-workflow-kit 10.4.0 → 10.5.0

package/tools/recipes.mjs

@@ -1,19 +1,9 @@
 #!/usr/bin/env node
-// Recipe planner — the pure brain behind the read-only `/agent-workflow-kit recipes` advisor.
-//
-// A "recipe" is a NAMED orchestration pattern over the family's optional carriers: the
-// subscription-CLI bridges (codex-cli-bridge → `codex`, antigravity-cli-bridge → `agy`) and the
-// executor subagent vehicle. The ENGINE owns the canonical narrative
-// (agent-workflow-engine/references/orchestration.md, kept in lockstep by the recipe-name parity
-// guard in recipes.test.mjs); this module owns the EXECUTABLE dispatch. The activity/slot registry
-// lives in carriers.mjs, re-exported here so every importer keeps its './recipes.mjs' path.
-// Invariants: pure (no fs/network/CLI in planRecipe/recommendRecipe), read-only, NEVER runs a
-// subscription CLI. The orchestrator executes a recipe and always makes the single commit; a
-// backend or a subagent is advisory or delegated, never autonomous. Dependency-free, Node >= 22.
+// Read-only recipe planner. The engine owns the narrative; carriers.mjs owns the activity/slot
+// registry re-exported here. Pure planning functions never run a subscription CLI.
 
 import { existsSync, readFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
-// The READ-ONLY settings core, never the writer: this advisor never pulls in the atomic-write core.
 import { settingsSnapshot, DEFAULT_BUNDLE_ROOT } from './bridge-settings-read.mjs';
 import { isDirectRun } from './direct-run.mjs';
 import {
@@ -29,10 +19,13 @@ import {
   vehicleDegradeReason,
   EXECUTOR_APPLY,
   safeLine,
+  DISPLAY_ALIASES,
+  BACKEND_PRIORITY,
 } from './carriers.mjs';
-// The READ core of the vehicle surface, never the writer: this advisor can never reach a module
-// that creates `.claude/agents/`.
-import { surveyExecutorVehicle } from './cheap-agents-read.mjs';
+import { surveyExecutorVehicle, surveyVehicle } from './cheap-agents-read.mjs';
+import { obligationsOf } from './review-roster.mjs';
+import { resolveRoster, activeLineCell, remedyFor } from './review-roster-resolve.mjs';
+import { posturesByBackend } from './bridge-posture.mjs';
 import {
   detectBackends,
   wrapperCmdFor,
@@ -43,32 +36,32 @@ import {
   DEGRADED,
 } from './detect-backends.mjs';
 
-export { ACTIVITIES, POLICY_ACTIVITIES, SLOT_RECIPES, isSwitchSlot, EXECUTOR_APPLY, safeLine };
+export { ACTIVITIES, POLICY_ACTIVITIES, SLOT_RECIPES, isSwitchSlot, EXECUTOR_APPLY, safeLine, DISPLAY_ALIASES };
 
-const CODEX = 'codex-cli-bridge';
-const AGY = 'antigravity-cli-bridge';
+const [CODEX, AGY] = BACKEND_PRIORITY;
 
-// The manifest-name → human-alias map (the detector emits manifest names; humans say codex/agy).
-export const DISPLAY_ALIASES = { [CODEX]: 'codex', [AGY]: 'agy' };
-
-// The provider → role table, keyed by the name the readiness array carries, NOT the display alias.
-// The bridge rows are drift-guarded against each capability.json `provides[]`; the executor row is
-// the vehicle withVehicle appends, and the ONLY provider of `carry`.
+// Keyed by readiness-array provider name; executor is the only `carry` provider.
 export const BACKEND_ROLES = {
   [CODEX]: ['execute', 'review'],
   [AGY]: ['review', 'probe'],
   [EXECUTOR_PROVIDER]: [CARRY_ROLE],
 };
 
-// Review obligations from the CONFIGURED plan-execution.review recipe — the RAW config value, never
-// the readiness-degraded one. Homed HERE so review-state and flow-check share one backend set (#42).
-export const requiredBackendsForConfiguredRecipe = ({ config, readiness = [], detectionFailed = false } = {}) => {
-  const configured = config?.['plan-execution']?.review;
+// Review obligations from the CONFIGURED activity's review recipe — the RAW config value, never
+// the readiness-degraded one. The default preserves review-state and flow-check's backend set (#42).
+export const requiredBackendsForConfiguredRecipe = ({ config, readiness = [], detectionFailed = false, activity = 'plan-execution' } = {}) => {
+  if (!Object.hasOwn(ACTIVITIES, activity) || !Object.hasOwn(ACTIVITIES[activity].slots, 'review')) {
+    throw new Error(`activity "${activity}" has no review slot`);
+  }
+  const configured = config?.[activity]?.review;
   const providers = Object.values(DISPLAY_ALIASES); // every review-capable backend, codex first
   if (configured == null && detectionFailed) {
     // No config + no readiness signal: the computed default is UNKNOWABLE — fail closed upstream.
     return { recipe: null, source: 'default', backends: [], minShip: 0, perBackend: false, unknowable: true };
   }
+  if (Array.isArray(configured)) {
+    return { ...obligationsOf(configured), source: 'config', unknowable: false };
+  }
   // Role-filtered: a ready EXECUTOR vehicle is a carry provider, never a reviewer, so it must not
   // turn a silent review config into `reviewed`.
   const anyReady = readyProvidersOf('review', readiness).length >= 1;
@@ -90,8 +83,6 @@ export const BACKEND_META = {
   },
 };
 
-// Deterministic tie-break: codex before agy — the more reliable default for substantive reviews.
-const BACKEND_PRIORITY = [CODEX, AGY];
 const priorityIndex = (name) => {
   const i = BACKEND_PRIORITY.indexOf(name);
   return i === -1 ? BACKEND_PRIORITY.length : i;
@@ -137,14 +128,6 @@ export const RECIPES = [
 
 const recipeById = (id) => RECIPES.find((r) => r.id === id);
 
-// Read-only file-presence remedies — never a claim about whether a backend's service is responsive.
-const READINESS_REASON = {
-  [NEEDS_SKILL]: 'bridge skill not installed — run /agent-workflow-kit setup',
-  [NEEDS_CLI]: 'the CLI is not installed',
-  [NEEDS_CREDENTIALS]: 'not signed in (credentials missing)',
-  [DEGRADED]: 'wrapper not on PATH — run /agent-workflow-kit setup',
-};
-
 // ── pure planner ───────────────────────────────────────────────────────────────
 
 const providersOf = (role, detection) => detection.filter((b) => (BACKEND_ROLES[b.name] ?? []).includes(role));
@@ -171,7 +154,7 @@ const degradeReason = (recipe, detection) => {
     .filter((b) => b.readiness !== READY)
     .map((b) => (b.name === EXECUTOR_PROVIDER
       ? vehicleDegradeReason(b.vehicle, EXECUTOR_APPLY)
-      : `${DISPLAY_ALIASES[b.name] ?? b.name}: ${READINESS_REASON[b.readiness] ?? b.readiness}`))
+      : `${DISPLAY_ALIASES[b.name] ?? b.name}: ${remedyFor({ readiness: b.readiness })}`))
     .join('; ');
   return `${recipe.title} needs ${recipe.minBackends} provider(s) providing ${recipe.role}, but only ${ready.length} ready${detail ? ` — ${detail}` : ''}`;
 };
@@ -268,7 +251,7 @@ const computedDefaultForSlot = (slotType, detection) => {
 // The effective recipe for ONE slot. Precedence: an explicit `override` (degrades LOUDLY, so the
 // agent tells the user) > the `config` entry (graceful) > the computed default. Satisfiability and
 // the lattice REUSE planRecipe — one source. Pure; never mutates.
-export const resolveActivityRecipe = ({ config = {}, readiness = [], activity, slot, override } = {}) => {
+export const resolveActivityRecipe = ({ config = {}, readiness = [], activity, slot, override, surveyLens, postures } = {}) => {
   const activityDef = ACTIVITIES[activity];
   if (!activityDef) throw new Error(`unknown activity: ${activity}`);
   const slotType = activityDef.slots[slot];
@@ -278,6 +261,21 @@ export const resolveActivityRecipe = ({ config = {}, readiness = [], activity, s
   const requested = override ?? configured ?? computedDefaultForSlot(slotType, readiness);
   const source = override != null ? 'override' : configured != null ? 'config' : 'default';
 
+  if (Array.isArray(requested)) {
+    if (slotType !== 'review' || source !== 'config') {
+      throw new Error(`invalid roster for ${slotType} slot of "${activity}"`);
+    }
+    const obligations = obligationsOf(requested);
+    return {
+      recipe: obligations.recipe,
+      source,
+      degradedFrom: null,
+      reason: null,
+      overrideUnsatisfied: false,
+      roster: resolveRoster({ value: requested, readiness, surveyLens, postures }),
+    };
+  }
+
   // Defensive: the IO shell and the CLI validate first, so a stray value here is a programmer error
   // — surfaced loudly rather than silently coerced into a neighbour recipe.
   if (!(SLOT_RECIPES[slotType] ?? []).includes(requested)) {
@@ -300,42 +298,14 @@ export const resolveActivityRecipe = ({ config = {}, readiness = [], activity, s
   };
 };
 
-// ── the one-line backend status (the tool speaks, the agent pastes) ───────────────────────────────
-// Machine-composed so the agent composes NOTHING factual (a session once echoed SKILL.md's canonical
-// example while the detector said otherwise). Always exactly one line.
-
-// The CONFIGURED dispatch posture: the bundled manifests' pins overlaid with the active
-// bridge-settings. No pins or a corrupt bundle → null; the posture segment is a fact, never a gate.
+// Configured posture from bundled manifest pins plus bridge settings; corruption returns null.
 export const composeConfiguredPosture = (ctx = {}) => {
   try {
-    const bundleRoot = ctx.bundleRoot ?? DEFAULT_BUNDLE_ROOT;
-    const read = ctx.readFile ?? readFileSync;
-    const parts = [];
-    for (const name of BACKEND_PRIORITY) {
-      let manifest;
-      try {
-        manifest = JSON.parse(String(read(join(bundleRoot, name, 'capability.json'), 'utf8')));
-      } catch {
-        return null; // an unreadable/corrupt manifest is CORRUPTION — a partial posture would lie
-      }
-      if (!Object.hasOwn(manifest, 'posture')) continue; // a pre-D5 bridge — legitimate absence
-      const posture = manifest.posture;
-      // A present-but-invalid block nulls the WHOLE render — never a partial/mangled line.
-      const invalid =
-        posture === null || typeof posture !== 'object' || Array.isArray(posture) ||
-        typeof posture.model !== 'string' || posture.model.length === 0 ||
-        (Object.hasOwn(posture, 'effort') && (typeof posture.effort !== 'string' || posture.effort.length === 0)) ||
-        (Object.hasOwn(posture, 'tier') && posture.tier !== null && (typeof posture.tier !== 'string' || posture.tier.length === 0)) ||
-        Object.keys(posture).some((k) => !['model', 'effort', 'tier'].includes(k));
-      if (invalid) return null;
-      const seg = [`model=${posture.model}`];
-      if (Object.hasOwn(posture, 'effort')) seg.push(`effort=${posture.effort}`);
-      if (Object.hasOwn(posture, 'tier')) {
-        const knob = (ctx.settings?.active ?? []).find((s) => s.key === 'CODEX_SERVICE_TIER' && s.bridge === name);
-        seg.push(knob ? `tier=${knob.value} (bridge-settings)` : `tier=${posture.tier ?? 'standard'}`);
-      }
-      parts.push(`${DISPLAY_ALIASES[name] ?? name} ${seg.join(' ')}`);
-    }
+    const rows = posturesByBackend({ bundleRoot: ctx.bundleRoot ?? DEFAULT_BUNDLE_ROOT, settings: ctx.settings ?? { active: [] }, readFile: ctx.readFile ?? readFileSync });
+    if (Object.values(rows).some((row) => row.state === 'unreadable')) return null;
+    const parts = Object.entries(rows)
+      .filter(([, row]) => row.state === 'valid')
+      .map(([receiptId, row]) => `${receiptId} ${row.posture}`);
     return parts.length ? parts.join(' · ') : null;
   } catch {
     return null;
@@ -422,19 +392,25 @@ export const composeAutonomyFacts = async (cwd, deps = {}) => {
 // ONE line rendering the CONFIGURED recipe of every activity/slot with its source, degradation and
 // dispatched wrappers — contrasted with the readiness-RECOMMENDED recipe, which is NOT what runs.
 // The session-start checklist and the handover "Active recipes:" slot paste it verbatim.
-export const composeActiveRecipeLine = ({ config, source } = {}, detection, autonomy = null) => {
+export const composeActiveRecipeLine = ({ config, source } = {}, detection, autonomy = null, rosterDeps = null) => {
   const cells = [];
   for (const [activity, def] of Object.entries(ACTIVITIES)) {
     const level = autonomy?.activities?.[activity]?.autonomy;
     const auto = level ? `; autonomy ${level}` : '';
     for (const [slot, slotType] of Object.entries(def.slots)) {
-      const r = resolveActivityRecipe({ config: config ?? {}, readiness: detection, activity, slot });
-      const dispatch = isSwitchSlot(slotType) ? [] : planRecipe(r.recipe, detection).dispatch;
+      const r = resolveActivityRecipe({
+        config: config ?? {}, readiness: detection, activity, slot,
+        surveyLens: rosterDeps?.surveyLens, postures: rosterDeps?.postures,
+      });
+      const dispatch = isSwitchSlot(slotType) || r.roster ? [] : planRecipe(r.recipe, detection).dispatch;
       const wrappers = dispatch.map((d) => wrapperCmdFor(d.backend, d.role)).filter(Boolean);
       const srcLabel = r.source === 'config' ? 'configured' : 'computed default';
+      const renderedValue = r.roster
+        ? activeLineCell(r.roster, { states: rosterDeps !== null })
+        : r.recipe;
       const head = r.degradedFrom
         ? `${activity}.${slot} = ${r.degradedFrom} (${srcLabel}; degrades here to ${r.recipe} — ${r.reason}${auto})`
-        : `${activity}.${slot} = ${r.recipe} (${srcLabel}${isSwitchSlot(slotType) ? '; switch' : ''}${auto})`;
+        : `${activity}.${slot} = ${renderedValue} (${srcLabel}${isSwitchSlot(slotType) ? '; switch' : ''}${auto})`;
       const suffix =
         wrappers.length >= 2
           ? ` → every backend every round: ${wrappers.join(' + ')}`
@@ -553,7 +529,12 @@ exclusive. Detection only — never writes, never commits, never runs a subscrip
     // Lazy: orchestration-config.mjs statically imports this module — no static cycle.
     const { loadConfig } = await import('./orchestration-config.mjs');
     try {
-      console.log(composeActiveRecipeLine(loadConfig(cwd), readiness, await composeAutonomyFacts(cwd)));
+      const snapshot = settingsSnapshot();
+      const surveyLens = deps.surveyLens ?? ((spec) => surveyVehicle(cwd, spec, deps));
+      console.log(composeActiveRecipeLine(
+        loadConfig(cwd), readiness, await composeAutonomyFacts(cwd),
+        { surveyLens, postures: posturesByBackend({ settings: snapshot }) },
+      ));
     } catch (err) {
       console.error(`[agent-workflow-kit] ${err.message}`);
       return err.exitCode ?? 1;

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;
+}