axstack 0.9.0

package/src/instructions.js

@@ -0,0 +1,100 @@
+// Pure planning and byte-preserving edits for the Axstack-owned routing block.
+import { hashContent } from './manifest.js';
+import { join } from './posixpath.js';
+
+const BEGIN = '<!-- axstack:begin v1 -->';
+const END = '<!-- axstack:end -->';
+
+export function renderInstructionBlock(skillsDir) {
+  return [
+    BEGIN,
+    `Use Axstack for engineering work. Load \`${join(skillsDir, 'axstack', 'SKILL.md')}\` to route the request.`,
+    'Route every subagent, delegated worker, reviewer, and cross-harness dispatch through Orca orchestration via the `orca` CLI and its `orca-cli` / `orchestration` skills so the work stays visible.',
+    'Do not use a harness native subagent tool for delegated work.',
+    END,
+  ].join('\n');
+}
+
+export function locateInstructionBlock(text) {
+  const begins = [...text.matchAll(/<!--\s*axstack:begin\b[^>]*-->/g)];
+  const ends = [...text.matchAll(/<!--\s*axstack:end\s*-->/g)];
+  if (begins.length === 0 && ends.length === 0) return null;
+  if (begins.length !== 1 || ends.length !== 1) {
+    throw new Error('invalid Axstack instruction markers: duplicate or incomplete marker');
+  }
+  if (!/^<!-- axstack:begin v\d+ -->$/.test(begins[0][0])) {
+    throw new Error('invalid Axstack instruction begin marker');
+  }
+  const start = begins[0].index;
+  const end = ends[0].index + ends[0][0].length;
+  if (begins[0].index >= ends[0].index) {
+    throw new Error('invalid Axstack instruction markers: nested or reversed marker');
+  }
+  const body = text.slice(start, end);
+  if (/<!--\s*axstack:(?:begin|end)\b/.test(body.slice(begins[0][0].length, -ends[0][0].length))) {
+    throw new Error('invalid Axstack instruction markers: nested marker');
+  }
+  return { start, end, block: body };
+}
+
+export function planInstruction({ text, block, ownership, force = false }) {
+  if (text === null) {
+    if (ownership) return { action: 'conflict', reason: 'owned instruction file is missing' };
+    return { action: 'created', block, separation: '' };
+  }
+  const located = locateInstructionBlock(text);
+  if (!located) {
+    if (ownership) return { action: 'conflict', reason: 'owned instruction block is missing' };
+    const separation = text.length === 0 ? '' : text.endsWith('\n') ? '\n' : '\n\n';
+    return { action: 'updated', block, separation, append: true };
+  }
+  if (!ownership) {
+    return { action: 'conflict', reason: 'instruction block is present but unowned' };
+  }
+  if (hashContent(located.block) !== ownership.hash) {
+    if (!force) return { action: 'conflict', reason: 'owned instruction block was edited' };
+  }
+  if (located.block === block) return { action: 'unchanged', block, separation: ownership.separation ?? '' };
+  return {
+    action: 'updated',
+    block,
+    separation: ownership.separation ?? '',
+    start: located.start,
+    end: located.end,
+    forced: hashContent(located.block) !== ownership.hash,
+  };
+}
+
+export function applyInstructionPlan(text, plan) {
+  if (plan.action === 'created') return plan.block;
+  if (plan.action !== 'updated') return text;
+  if (plan.append) return `${text}${plan.separation}${plan.block}`;
+  return `${text.slice(0, plan.start)}${plan.block}${text.slice(plan.end)}`;
+}
+
+export function stripInstructionBlock(text, ownership, { force = false } = {}) {
+  const located = locateInstructionBlock(text);
+  if (!located || (!force && hashContent(located.block) !== ownership.hash)) {
+    return { text, removed: false, conflict: true };
+  }
+  const separation = ownership.separation ?? '';
+  const prefix = text.slice(0, located.start);
+  if (separation && !prefix.endsWith(separation)) {
+    return { text, removed: false, conflict: true };
+  }
+  return {
+    text: prefix.slice(0, prefix.length - separation.length) + text.slice(located.end),
+    removed: true,
+    block: located.block,
+  };
+}
+
+export function findLegacyRoutingLines(text) {
+  const located = locateInstructionBlock(text);
+  const outside = located
+    ? text.slice(0, located.start) + text.slice(located.end)
+    : text;
+  return outside.split('\n').filter((line) =>
+    /\bhaoshoku\b.*\b(?:rout\w*|skills?)\b|\b(?:planning-advisor|review-code|paseo-pr-review|paseo-pr-babysit)\b/i.test(line),
+  );
+}

package/src/locations.js

@@ -0,0 +1,43 @@
+// Supported harness skill locations. `discovery` records how the default
+// directory was established: upstream docs, local CLI help, or unverified.
+// `source` is the verified primary-source page for the default (checked
+// 2026-09-13; re-check local `<tool> --help` when in doubt). Unverified
+// harnesses (notably Grok) have no automatic destination: callers must pass
+// an explicit --skills-dir override. Installing files alone never proves
+// harness behavior; that needs a real end-to-end run.
+export function harnessLocations() {
+  return [
+    {
+      harness: 'claude',
+      skillsDir: '~/.claude/skills',
+      discovery: 'docs',
+      source: 'https://docs.claude.com/en/api/agent-sdk/skills',
+      notes:
+        'User skills directory from Anthropic docs; confirm with local help. Pass --skills-dir to override.',
+    },
+    {
+      harness: 'codex',
+      skillsDir: '$CODEX_HOME/skills (default ~/.codex/skills)',
+      discovery: 'docs',
+      source: 'https://developers.openai.com/codex/skills',
+      notes:
+        'User skills live under $CODEX_HOME/skills per OpenAI docs (CODEX_HOME defaults to ~/.codex). The CLI honors $CODEX_HOME when set. Pass --skills-dir to override.',
+    },
+    {
+      harness: 'opencode',
+      skillsDir: '~/.config/opencode/skills',
+      discovery: 'docs',
+      source: 'https://opencode.ai/docs/skills',
+      notes:
+        'Global skills directory from OpenCode docs; confirm with local help. Pass --skills-dir to override.',
+    },
+    {
+      harness: 'grok',
+      skillsDir: '(explicit --skills-dir required)',
+      discovery: 'unverified',
+      source: null,
+      notes:
+        'No verified skill directory for Grok; automatic discovery is unverified so an explicit --skills-dir override is required.',
+    },
+  ];
+}

package/src/manifest.js

@@ -0,0 +1,251 @@
+// Ownership-manifest helpers: sha256 hashes plus atomic manifest read/write.
+// The manifest lives at <skillsDir>/.axstack-manifest.json and records the
+// exact bytes Axstack installed, so updates and uninstalls only touch
+// unchanged owned assets.
+import { chmod, lstat, mkdir, open, rename, readFile, rm, stat } from 'node:fs/promises';
+import { isAbsolute, join } from './posixpath.js';
+
+export const MANIFEST_NAME = '.axstack-manifest.json';
+export const MANIFEST_TMP_NAME = '.axstack-manifest.json.tmp';
+export const MANIFEST_VERSION = 1;
+
+export function hashContent(content) {
+  // Byte-for-byte compatible with the pre-migration implementation:
+  // strings hash as UTF-8; every other input (including Buffers read from
+  // skill files) hashes as its JSON serialization. Do NOT "fix" Buffers to
+  // hash as raw bytes without a manifest migration: every recorded
+  // ownership hash would stop matching and unchanged owned files would lose
+  // ownership. Proven by fixtures/old-impl under both runtimes.
+  const input = typeof content === 'string' ? content : JSON.stringify(content);
+  const hasher = new Bun.CryptoHasher('sha256');
+  hasher.update(input, 'utf8');
+  return hasher.digest('hex');
+}
+
+// Deterministic object hash for profile entries (key order independent).
+export function hashObject(value) {
+  return hashContent(stableStringify(value));
+}
+
+function stableStringify(value) {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(',')}]`;
+  const keys = Object.keys(value).sort();
+  return `{${keys.map((k) => `${JSON.stringify(k)}:${stableStringify(value[k])}`).join(',')}}`;
+}
+
+export function manifestPath(skillsDir) {
+  return join(skillsDir, MANIFEST_NAME);
+}
+
+export function assertSafeRel(rel) {
+  if (
+    !rel ||
+    typeof rel !== 'string' ||
+    isAbsolute(rel) ||
+    rel.split('/').includes('..') ||
+    rel.includes('\0') ||
+    /^[a-zA-Z]:/.test(rel) ||
+    rel === MANIFEST_NAME
+  ) {
+    throw new Error(`unsafe manifest path rejected: ${rel || '(empty)'}`);
+  }
+}
+
+function isHashMap(value) {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    !Array.isArray(value) &&
+    Object.values(value).every((v) => typeof v === 'string')
+  );
+}
+
+// Normalized shape:
+// { version, files, profiles: { path, preset, entries },
+//   claudeSettings: { path }, instructions: { path, hash, separation? } }.
+// `profiles.path` binds owned profile hashes to the canonical config file
+// they were installed into; `path: null` marks legacy unbound entries, which
+// callers must reset rather than honor for removal.
+function normalizeManifest(parsed) {
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+    throw new Error('invalid ownership manifest: expected a JSON object');
+  }
+  if (parsed.version !== MANIFEST_VERSION) {
+    throw new Error(
+      `unsupported ownership manifest version: ${JSON.stringify(parsed.version)}`,
+    );
+  }
+  if (!isHashMap(parsed.files)) {
+    throw new Error('invalid ownership manifest: files must be an object of path hashes');
+  }
+  const rawClaudeSettings = parsed.claudeSettings ?? { path: null };
+  if (
+    typeof rawClaudeSettings !== 'object' || rawClaudeSettings === null ||
+    Array.isArray(rawClaudeSettings) ||
+    (rawClaudeSettings.path !== null && typeof rawClaudeSettings.path !== 'string')
+  ) {
+    throw new Error('invalid ownership manifest: claudeSettings must bind a config path');
+  }
+  const rawInstructions = parsed.instructions ?? { path: null, hash: null };
+  if (
+    typeof rawInstructions !== 'object' || rawInstructions === null ||
+    Array.isArray(rawInstructions) ||
+    !(
+      (rawInstructions.path === null && rawInstructions.hash === null) ||
+      (typeof rawInstructions.path === 'string' &&
+        isAbsolute(rawInstructions.path) &&
+        typeof rawInstructions.hash === 'string')
+    ) ||
+    (rawInstructions.separation !== undefined &&
+      !['', '\n', '\n\n'].includes(rawInstructions.separation))
+  ) {
+    throw new Error('invalid ownership manifest: instructions must bind an absolute path and hash');
+  }
+  const instructions = rawInstructions.separation === undefined
+    ? { path: rawInstructions.path, hash: rawInstructions.hash }
+    : {
+      path: rawInstructions.path,
+      hash: rawInstructions.hash,
+      separation: rawInstructions.separation,
+    };
+  for (const rel of Object.keys(parsed.files)) assertSafeRel(rel);
+  const rawProfiles = parsed.profiles ?? { path: null, preset: null, entries: {} };
+  if (isHashMap(rawProfiles)) {
+    return {
+      version: MANIFEST_VERSION,
+      files: { ...parsed.files },
+      profiles: { path: null, preset: null, entries: { ...rawProfiles } },
+      claudeSettings: { path: rawClaudeSettings.path },
+      instructions,
+    };
+  }
+  if (
+    typeof rawProfiles === 'object' &&
+    rawProfiles !== null &&
+    (rawProfiles.path === null || typeof rawProfiles.path === 'string') &&
+    (rawProfiles.preset === undefined || rawProfiles.preset === null || typeof rawProfiles.preset === 'string') &&
+    isHashMap(rawProfiles.entries ?? {})
+  ) {
+    return {
+      version: MANIFEST_VERSION,
+      files: { ...parsed.files },
+      profiles: {
+        path: rawProfiles.path,
+        preset: rawProfiles.preset ?? null,
+        entries: { ...(rawProfiles.entries ?? {}) },
+      },
+      claudeSettings: { path: rawClaudeSettings.path },
+      instructions,
+    };
+  }
+  throw new Error('invalid ownership manifest: profiles must bind a config path to id hashes');
+}
+
+export async function readManifest(skillsDir) {
+  const dest = manifestPath(skillsDir);
+  try {
+    if ((await lstat(dest)).isSymbolicLink()) {
+      throw new Error('unsafe ownership manifest: manifest path is a symlink; refusing');
+    }
+  } catch (err) {
+    if (err?.code === 'ENOENT') return null;
+    throw err?.code ? new Error(`cannot read ownership manifest: ${err.message}`) : err;
+  }
+  let raw;
+  try {
+    raw = await readFile(dest, 'utf8');
+  } catch (err) {
+    if (err?.code === 'ENOENT') return null;
+    throw new Error(`cannot read ownership manifest: ${err.message}`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error('ownership manifest is corrupt; refusing to proceed');
+  }
+  return normalizeManifest(parsed);
+}
+
+export async function writeManifest(skillsDir, manifest) {
+  await mkdir(skillsDir, { recursive: true });
+  const dest = manifestPath(skillsDir);
+  // Fixed temp name (single-writer assumption for a user-invoked installer;
+  // a failed run leaves either the old manifest or no manifest, and retries
+  // converge). A fixed name also keeps manifest-write failures testable.
+  const tmp = join(skillsDir, MANIFEST_TMP_NAME);
+  const normalized = normalizeManifest(manifest);
+  let existingMode = null;
+  try {
+    existingMode = (await stat(dest)).mode & 0o777;
+  } catch (err) {
+    if (err?.code !== 'ENOENT') throw new Error(`cannot write ownership manifest: ${err.message}`);
+  }
+  try {
+    await writeFileExclusive(tmp, JSON.stringify(normalized, null, 2) + '\n');
+  } catch (err) {
+    if (/temporary file already exists/.test(err?.message ?? '')) throw err;
+    throw new Error(`cannot write ownership manifest: ${err?.message ?? err}`);
+  }
+  try {
+    await rename(tmp, dest);
+  } catch (err) {
+    try {
+      await rm(tmp);
+    } catch {
+      // best effort cleanup of a temp file this run created
+    }
+    throw new Error(`cannot write ownership manifest: ${err?.message ?? err}`);
+  }
+  try {
+    await chmod(dest, existingMode ?? 0o600);
+  } catch (err) {
+    throw new Error(`wrote ownership manifest but could not set permissions: ${err.message}`);
+  }
+}
+
+// Create a temp file exclusively with restrictive permissions. Pre-existing
+// temp entries (files, directories, symlinks) are refused — never followed,
+// truncated, or removed — so a planted temp path cannot redirect writes.
+// This guards pre-existing entries, not an active concurrent attacker.
+export async function writeFileExclusive(tmpPath, bytes) {
+  let preexisting = null;
+  try {
+    preexisting = await lstat(tmpPath);
+  } catch (err) {
+    if (err?.code !== 'ENOENT') throw err;
+  }
+  if (preexisting) {
+    throw new Error(
+      `temporary file already exists at ${tmpPath}; refusing to overwrite it (remove it if it is a stale leftover)`,
+    );
+  }
+  let handle;
+  try {
+    handle = await open(tmpPath, 'wx', 0o600);
+  } catch (err) {
+    if (err?.code === 'EEXIST') {
+      throw new Error(
+        `temporary file already exists at ${tmpPath}; refusing to overwrite it (remove it if it is a stale leftover)`,
+      );
+    }
+    throw err;
+  }
+  try {
+    await handle.writeFile(bytes);
+    await handle.close();
+  } catch (err) {
+    try {
+      await handle.close();
+    } catch {
+      // ignore close failure; original error matters
+    }
+    try {
+      await rm(tmpPath); // only unlink: this run created it via wx
+    } catch {
+      // best effort cleanup of a temp file this run created
+    }
+    throw err;
+  }
+}

package/src/posixpath.js

@@ -0,0 +1,108 @@
+// Small explicit POSIX path helper covering only the operations the
+// installer uses (join, resolve, relative, isAbsolute, basename, dirname).
+// Backslashes are ordinary filename characters on POSIX and are NEVER
+// treated as separators (this is the documented divergence from pathe,
+// which normalizes Windows separators). No syscalls, no dependencies.
+export const sep = '/';
+
+export function isAbsolute(p) {
+  return typeof p === 'string' && p.startsWith('/');
+}
+
+function normalizeSegments(parts, { allowAboveRoot }) {
+  const out = [];
+  for (const part of parts) {
+    if (part === '' || part === '.') continue;
+    if (part === '..') {
+      if (out.length > 0 && out[out.length - 1] !== '..') out.pop();
+      else if (allowAboveRoot) out.push('..');
+    } else {
+      out.push(part);
+    }
+  }
+  return out;
+}
+
+export function normalize(p) {
+  if (typeof p !== 'string') throw new TypeError('path must be a string');
+  if (p === '') return '.';
+  const absolute = p.startsWith('/');
+  const trailing = p.length > 1 && p.endsWith('/');
+  const segs = normalizeSegments(p.split('/'), { allowAboveRoot: !absolute });
+  let result = (absolute ? '/' : '') + segs.join('/');
+  if (result === '') result = absolute ? '/' : '.';
+  else if (trailing && result !== '/') result += '/';
+  return result;
+}
+
+export function join(...parts) {
+  const strings = parts.filter((p) => typeof p === 'string' && p !== '');
+  if (strings.length === 0) return '.';
+  const joined = strings.join('/');
+  let result = normalize(joined);
+  // join preserves a trailing slash from the last segment.
+  const last = strings[strings.length - 1];
+  if (last.endsWith('/') && !result.endsWith('/')) result += '/';
+  return result;
+}
+
+export function resolveFrom(cwd, ...paths) {
+  let resolved = '';
+  let isAbs = false;
+  const all = [...paths];
+  for (let i = all.length - 1; i >= 0; i--) {
+    const p = all[i];
+    if (typeof p !== 'string' || p === '') continue;
+    resolved = resolved ? `${p}/${resolved}` : p;
+    if (p.startsWith('/')) {
+      isAbs = true;
+      break;
+    }
+  }
+  if (!isAbs) resolved = resolved ? `${cwd}/${resolved}` : String(cwd);
+  const result = normalize(resolved);
+  return result.length > 1 && result.endsWith('/') ? result.slice(0, -1) : result;
+}
+
+export function resolve(...paths) {
+  return resolveFrom(Bun.cwd, ...paths);
+}
+
+export function relative(from, to) {
+  const a = resolve(from);
+  const b = resolve(to);
+  if (a === b) return '';
+  const aSegs = a.split('/').filter((s) => s !== '');
+  const bSegs = b.split('/').filter((s) => s !== '');
+  let common = 0;
+  while (common < aSegs.length && common < bSegs.length && aSegs[common] === bSegs[common]) {
+    common++;
+  }
+  const up = aSegs.length - common;
+  return [...Array(up).fill('..'), ...bSegs.slice(common)].join('/');
+}
+
+function stripTrailing(p) {
+  let end = p.length;
+  while (end > 1 && p[end - 1] === '/') end--;
+  return p.slice(0, end);
+}
+
+// No `ext` parameter: no caller strips extensions (YAGNI).
+export function basename(p) {
+  if (typeof p !== 'string') throw new TypeError('path must be a string');
+  const stripped = stripTrailing(p);
+  if (stripped === '') return '';
+  const idx = stripped.lastIndexOf('/');
+  return idx === -1 ? stripped : stripped.slice(idx + 1);
+}
+
+export function dirname(p) {
+  if (typeof p !== 'string') throw new TypeError('path must be a string');
+  const stripped = stripTrailing(p);
+  if (stripped === '') return '.';
+  const idx = stripped.lastIndexOf('/');
+  if (idx === -1) return '.';
+  if (idx === 0) return '/';
+  return stripped.slice(0, idx);
+}

package/src/roles.js

@@ -0,0 +1,142 @@
+const PROVIDER_BOUNDS = Object.freeze({
+  mixed: new Set(['codex', 'claude']),
+  'codex-only': new Set(['codex']),
+  'claude-only': new Set(['claude']),
+});
+
+const AUTHORED_ROUTES = Object.freeze({
+  mixed: {
+    'codex/gpt-5.6-sol': ['axstack-reviewer-secondary', 'claude/claude-opus-5', 'medium'],
+    'claude/claude-opus-5': ['axstack-reviewer-primary', 'codex/gpt-5.6-sol', 'medium'],
+  },
+  'codex-only': {
+    'codex/gpt-5.6-sol': ['axstack-reviewer-secondary', 'codex/gpt-5.6-terra', 'xhigh'],
+  },
+  'claude-only': {
+    'claude/claude-opus-5': ['axstack-reviewer-secondary', 'claude/claude-sonnet-5', 'xhigh'],
+  },
+});
+
+export function assertBundleRoles(roles) {
+  if (!Array.isArray(roles) || roles.length === 0) {
+    throw new Error('invalid bundle roles: expected a non-empty roles array');
+  }
+  const ids = new Set();
+  for (const role of roles) {
+    if (!role || typeof role !== 'object' || Array.isArray(role)) {
+      throw new Error('invalid bundle roles: every role must be an object');
+    }
+    for (const field of ['id', 'name', 'provider']) {
+      if (typeof role[field] !== 'string' || role[field].trim() === '') {
+        throw new Error(`invalid bundle roles: every role needs a non-empty ${field} string`);
+      }
+    }
+    if (!role.id.startsWith('axstack-')) {
+      throw new Error('invalid bundle roles: every role needs a namespaced axstack-* id');
+    }
+    if (ids.has(role.id)) throw new Error(`invalid bundle roles: duplicate role ID ${role.id}`);
+    ids.add(role.id);
+    if (!Object.hasOwn(role, 'model')) {
+      throw new Error('invalid bundle roles: model must be a non-empty string or explicit null');
+    }
+    if (role.model !== null && (typeof role.model !== 'string' || role.model.trim() === '')) {
+      throw new Error('invalid bundle roles: model must be a non-empty string or explicit null');
+    }
+    for (const field of ['icon', 'color', 'modeId', 'thinkingOptionId', 'notes']) {
+      if (role[field] !== undefined && typeof role[field] !== 'string') {
+        throw new Error(`invalid bundle roles: ${field} must be a string when present`);
+      }
+    }
+    if (
+      role.featureValues !== undefined &&
+      (typeof role.featureValues !== 'object' || role.featureValues === null || Array.isArray(role.featureValues))
+    ) {
+      throw new Error('invalid bundle roles: featureValues must be an object when present');
+    }
+  }
+}
+
+export function assessRoleReadiness(roles, preset) {
+  assertBundleRoles(roles);
+  const bounds = PROVIDER_BOUNDS[preset];
+  if (!bounds) throw new Error(`cannot assess readiness for unknown preset: ${preset}`);
+  const byId = new Map(roles.map((role) => [role.id, role]));
+  const gaps = [];
+  const isIntentionalAbsence = (role) => role.model === null && (
+    (preset === 'mixed' && role.id === 'axstack-checker') ||
+    (preset === 'codex-only' && role.id === 'axstack-advisor-fable') ||
+    (preset === 'claude-only' && role.id === 'axstack-advisor-astra')
+  );
+  for (const role of roles) {
+    if (!bounds.has(role.provider)) {
+      gaps.push(`${role.id} provider ${JSON.stringify(role.provider)} is outside ${preset} bounds (${[...bounds].join('|')})`);
+    }
+    if (!isIntentionalAbsence(role) && (typeof role.model !== 'string' || role.model.trim() === '')) {
+      gaps.push(`${role.id} requires a configured model`);
+    }
+  }
+
+  for (const id of ['axstack-reviewer-opus', 'axstack-reviewer-sol']) {
+    if (byId.has(id)) gaps.push(`legacy reviewer remains: ${id}`);
+  }
+  const primary = byId.get('axstack-reviewer-primary');
+  const secondary = byId.get('axstack-reviewer-secondary');
+  if (primary && secondary) {
+    if (primary.model === secondary.model) gaps.push('reviewer pair must use two distinct models');
+    if (preset === 'mixed' && primary.provider === secondary.provider) {
+      gaps.push('mixed reviewer pair must use different providers');
+    }
+  }
+
+  const author = byId.get('axstack-author');
+  if (author) {
+    const authorRoute = `${author.provider}/${author.model}`;
+    const route = AUTHORED_ROUTES[preset]?.[authorRoute];
+    if (!route) {
+      gaps.push(`authored routing gap: unsupported axstack-author route ${authorRoute}`);
+    } else {
+      const [reviewerId, reviewerRoute, effort] = route;
+      const reviewer = byId.get(reviewerId);
+      if (!reviewer || `${reviewer.provider}/${reviewer.model}` !== reviewerRoute || reviewer.thinkingOptionId !== effort) {
+        gaps.push(`authored routing gap: ${reviewerId} must be ${reviewerRoute}/${effort} for author ${authorRoute}`);
+      }
+    }
+  }
+  return { ready: gaps.length === 0, gaps };
+}
+
+export function installedRoleBytes(preset, roles) {
+  return Buffer.from(JSON.stringify({ version: 1, preset, roles }, null, 2) + '\n');
+}
+
+export function assessInstalledRoleSnapshot(bytes, expectedPreset, expectedRoles) {
+  let snapshot;
+  try {
+    snapshot = JSON.parse(bytes.toString());
+  } catch {
+    return { ready: false, gaps: ['installed axstack/roles.json is not valid JSON'] };
+  }
+  if (snapshot?.version !== 1 || snapshot?.preset !== expectedPreset || !Array.isArray(snapshot?.roles)) {
+    return {
+      ready: false,
+      gaps: [`installed role snapshot must be version 1 for preset ${expectedPreset}`],
+    };
+  }
+  try {
+    assertBundleRoles(expectedRoles);
+    const readiness = assessRoleReadiness(snapshot.roles, expectedPreset);
+    const installedIds = new Set(snapshot.roles.map((role) => role.id));
+    const expectedIds = new Set(expectedRoles.map((role) => role.id));
+    const gaps = [];
+    for (const role of expectedRoles) {
+      if (!installedIds.has(role.id)) gaps.push(`missing selected bundle role: ${role.id}`);
+    }
+    for (const role of snapshot.roles) {
+      if (!expectedIds.has(role.id)) gaps.push(`unexpected installed role: ${role.id}`);
+    }
+    gaps.push(...readiness.gaps);
+    return { ready: gaps.length === 0, gaps };
+  } catch (error) {
+    return { ready: false, gaps: [error.message] };
+  }
+}