Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

82.2 KB
Raw Blame
/**
 * Review-Loop reviewer vocabulary: which reviewers exist, what each one's
 * CLI/model/effort contract is, and how a reviewer set renders into slashdo's
 * `--review-with` argv (`buildReviewWithArgs`) and into the human-readable
 * reviewer notes spliced into agent prompts (`buildReviewerPinNote` /
 * `buildReviewerEffortNote`).
 *
 * Split out of cosValidation.js (issue #5702), which keeps the CoS Zod schemas
 * and re-exports everything here (`export * from './reviewerConfig.js'`) so
 * existing deep imports of cosValidation.js / validation.js keep working.
 * This module must stay Zod-free — it is pure reviewer domain vocabulary.
 */
import { isPlainObject } from './objects.js';
import { isTruthyMeta } from './metadataFlags.js';
import { EFFORT_LEVELS, effortLevelsForProvider, buildEffortArgs, foldCursorEffortIntoModel, splitAntigravityModel } from './providerModels.js';
import { ANTIGRAVITY_COMMAND } from './antigravity.js';
import { CURSOR_COMMAND } from './cursor.js';
import { PR_COMPLETIONS } from './prDisposition.js';
import { activeReviewerGroupIndex, isReviewerConfigFault } from './reviewerHealth.js';
export { REVIEWER_CONFIG_FAULT_CODES, isReviewerConfigFault } from './reviewerHealth.js';

// Reviewer choices for the Review Loop. `copilot` requests a native GitHub
// Copilot review; `claude`/`antigravity`/`codex`/`grok`/`cursor`/`opencode`/`kimi`
// instruct the review-loop follow-up agent to invoke the named CLI to critique the
// PR diff; `lmstudio`/`ollama`/`mtplx` route the diff through PortOS's local
// code-review endpoint (`POST /api/code-review/local`) which runs the configured
// local LLM model.
//
// The roster deliberately covers every coding-agent vendor PortOS can already
// spawn (`PROVIDER_VENDORS` in providerVendors.js) plus every OpenAI-compatible
// local backend it manages, so the provider a user is told is their best local
// coding agent is also selectable as their reviewer. `opencode` is the one CLI
// whose model flag is `-m` rather than `--model` (see REVIEWER_MODEL_FLAGS), and
// `kilo`/`kimi`/`mtplx` — like `lmstudio` — have no slashdo counterpart, so they
// are PORTOS_ONLY_REVIEWERS.
//
// A vendor left OUT of the roster is declared in NON_REVIEWER_VENDORS below, so
// "covers every vendor" is an invariant a test can check rather than a sentence
// that quietly stops being true.
// Mirrored in client/src/components/cos/constants.js → REVIEWER_OPTIONS.
export const REVIEWER_VALUES = ['copilot', 'claude', 'antigravity', 'codex', 'grok', 'cursor', 'pi', 'opencode', 'kilo', 'kimi', 'lmstudio', 'ollama', 'mtplx'];
// Provider records retain their own identity instead of collapsing to a harness.
export const isProviderReviewer = (value) => typeof value === 'string' && /^provider:[a-z0-9][a-z0-9-]{0,79}$/.test(value);
export const isReviewer = (value) => REVIEWER_VALUES.includes(value) || isProviderReviewer(value);
// Legacy name: identifies bridge-dispatched reviewers, not an enforced tool policy.
export const isToolFreeReviewer = (value) => LOCAL_LLM_REVIEWERS.includes(value) || isProviderReviewer(value);

/**
 * What an agent does with a review that could not return a verdict: say so in
 * the run summary, and leave the PR/MR thread alone.
 *
 * A comment announcing "the review was unavailable, so this is left open" is
 * noise on a PR a human still has to read — it restates the absence of a review
 * they can already see, and every reopened thread costs them a notification.
 * The run summary is where that belongs.
 *
 * One exported sentence because the rule reaches ~6 prompt sites across
 * `promptSections/` and `taskPromptDefaults/prompts.js`; spelled out at each
 * one, a future seventh gets written a seventh way and the rule quietly stops
 * being one. `reviewerConfig.test.js` pins the no-drift claim.
 */
export const REVIEW_UNAVAILABLE_REPORTING_NOTE = 'Report the pending review in your run summary — do NOT post a PR/MR comment saying the review was unavailable or inconclusive.';

/**
 * How a claim run waits on a forge reviewer (`@login`). That reviewer is often a
 * person, so a few minutes of polling is not a wait: the run would give up long
 * before they look. Each poll is bounded below an agent shell's command limit,
 * and the four-hour round budget keeps an absent reviewer from holding the agent
 * slot forever. Shared by every claim prompt's PR/MR-side review step.
 */
export const FORGE_REVIEWER_WAIT_NOTE = 'An `@<login>` is often a person, not a bot: after requesting the review, wait for it with blocking polls of at most 9 minutes each (check once a minute inside, counting only a review that login submitted on the current head commit), and keep repeating them for up to 4 hours per round. Do not end the run, skip the reviewer, or treat it as clean while that wait runs. Each review is a round: fix every comment, push, reply to and resolve its threads, then re-request their review. Only their approval of the current head satisfies them; changes requested or comments start the next round. No review after 4 hours is unsatisfied, not clean.';

/**
 * What an agent does when EVERY configured reviewer returned a config fault:
 * distinguish it from clean in the run summary, so the operator sees "no
 * reviewer reviewed this branch" rather than a silent success.
 *
 * One exported sentence for the same reason as `REVIEW_UNAVAILABLE_REPORTING_NOTE`:
 * the rule reaches prompt sites and run-summary builders, and spelled out at each
 * one it drifts. `reviewerConfig.test.js` pins the claim.
 */
export const ZERO_REVIEWER_COVERAGE_NOTE = 'No reviewer reviewed this branch — every configured reviewer returned a configuration fault. The review loop is currently a no-op. Check Settings → Code Reviewers for the setting that fixes each reviewer.';

/**
 * Did any configured reviewer produce a verdict this run?
 *
 * Inputs: the configured reviewer list and a map of per-reviewer statuses from
 * the run, where each value is either `{ code }` (a fault code from
 * `REVIEWER_CONFIG_FAULT_CODES`) or `{ verdict }` (a real result).
 * `isReviewerConfigFault(status.code)` identifies the config faults.
 *
 * Returns `true` when at least one reviewer produced a non-empty `verdict`.
 * A non-configuration failure code without a verdict is still inconclusive.
 * Returns
 * `false` when every reviewer's status is a config fault, or when the reviewer
 * list is empty. The empty-list case is a distinct condition from zero coverage
 * (no reviewers were configured at all vs. reviewers were configured but none
 * could answer); callers that need to distinguish them check the reviewer list
 * length separately.
 *
 * This is the resolver the issue (#7783) names: it sits beside
 * `hasRequiredReviewer()` and answers a complementary question — one asks
 * "is any reviewer binding?", this asks "did any reviewer actually review?".
 *
 * @param {string[]} reviewers - the configured reviewer list for this run
 * @param {Object<string, { code?: string, verdict?: string }>} perReviewerStatus
 *   - per-reviewer status map keyed by reviewer token
 * @returns {boolean}
 */
export function hasReviewerCoverage(reviewers, perReviewerStatus) {
  const list = Array.isArray(reviewers) ? reviewers : [];
  if (!list.length) return false;
  const statuses = perReviewerStatus && typeof perReviewerStatus === 'object' ? perReviewerStatus : {};
  return list.some(reviewer => {
    const status = statuses[reviewer] || statuses[reviewer?.toLowerCase?.()];
    if (!status || typeof status !== 'object') return false; // no status recorded = did not run
    if (isReviewerConfigFault(status.code)) return false;
    return typeof status.verdict === 'string' && status.verdict.trim().length > 0;
  });
}

/**
 * Vendors PortOS can spawn that are deliberately NOT reviewers, each mapped to
 * the reason. The roster above claims to cover every spawnable vendor; this is
 * the other half of that claim, and `reviewerConfig.test.js` fails on a
 * `PROVIDER_VENDORS` id that appears in neither — so a future vendor is either
 * offered as a reviewer or has its exclusion written down, instead of being
 * silently missing from ten hand-maintained lists.
 *
 * Kept as data here rather than imported from `providerVendors.js`: this module
 * is pure reviewer vocabulary reached by ~280 suites, and the cross-registry
 * comparison belongs in the test, not in this file's import closure.
 */
export const NON_REVIEWER_VENDORS = Object.freeze({
  'gemini-legacy': 'a retired row kept only so an old stored config still resolves — Gemini CLI was migrated to Antigravity and ships no binary of its own',
  openchamber: "a reviewer is a one-shot critique of a diff, and OpenChamber's only prompt path creates a persistent session inside a running workspace runtime the user owns — a review round would leave a session behind per reviewer per PR, and cannot run at all when that runtime is down",
});

export const REVIEWER_ALIASES = { gemini: 'antigravity', 'cursor-agent': 'cursor' };
export const DEFAULT_REVIEWER = 'copilot';
export const DEFAULT_REVIEWERS = [];
// Reviewers slashdo's `--reviewer-applies` actually reaches. Its loop forces
// every OTHER local CLI back to review-only and reverts what it wrote — codex is
// the one with a verified write-isolated profile — and the flag is meaningless
// for the cloud (`copilot`, `@login`) and non-agentic (`ollama`) paths, so a list
// without one of these emits no flag rather than a promise slashdo drops.
//
// A roster plus a predicate, like every other capability axis in this file
// (LOCAL_LLM_REVIEWERS, MODEL_CAPABLE_CLI_REVIEWERS, …): slashdo granting a
// second reviewer the editing pass is then one row, not an edit at every gate.
export const APPLY_CAPABLE_REVIEWERS = Object.freeze(['codex']);
// Aliases resolve first, matching the client mirror — a predicate that accepted
// `codex` but not a future alias of it would silently drop the flag for a user
// who typed the alias, and the two sides would disagree about the same reviewer.
export const isApplyCapableReviewer = (slug) => {
  if (typeof slug !== 'string') return false;
  const lower = slug.trim().toLowerCase();
  return APPLY_CAPABLE_REVIEWERS.includes(REVIEWER_ALIASES[lower] || lower);
};
// Reviewers that resolve to a local-LLM backend (rather than a CLI or GitHub
// bot). Used by the code-review endpoint, settings panel, and prompt builder
// to gate model-id resolution.
export const LOCAL_LLM_REVIEWERS = ['lmstudio', 'ollama', 'mtplx'];
// Reviewers PortOS serves ITSELF, with no counterpart in slashdo's reviewer
// vocabulary (`copilot`/`codex`/`agy`/`claude`/`grok`/`pi`/`cursor`/`opencode`/
// `ollama`/`@login`): `lmstudio`/`mtplx` run through `POST /api/code-review/local`,
// which takes their model in the request body, and `kilo`/`kimi` are CLIs PortOS's
// own review procedure spawns. slashdo has no such slug, so none can carry a
// `[<model>]` bracket or appear in a `--review-with` list (an unknown value aborts
// the command). One constant so a future addition can't be fixed in one of those
// two places and missed in the other — `splitSlashdoReviewerTokens` is the shared
// partition every emitter goes through.
//
// `opencode` left this set when slashdo added it (v3.38.0, `--review-with
// opencode`, aliases `zen`/`opencode-zen`); PortOS was still dropping it from the
// flag and silently reviewing with whatever the host's saved defaults named.
export const PORTOS_ONLY_REVIEWERS = ['lmstudio', 'mtplx', 'kilo', 'kimi'];
// CLI reviewers whose binary accepts a `--model <id>` tier the user can pin on
// the Code Review Defaults panel (stored as a `<reviewer>Model` settings scalar,
// e.g. `codexModel` / `claudeModel` / `antigravityModel`). The review-loop
// follow-up threads each as a reviewer-keyed model map
// (`reviewLoopReviewerModels`) so the prompt emits `<reviewer> --model <id>` per
// configured reviewer. `claude` covers both a normal Claude tier and an
// Ollama-backed `claude` (see isOllamaClaudeProvider) where `--model` selects the
// local Ollama model. `antigravity` runs `agy --model <id>`; an effort-suffixed
// agy id is reconciled with the effort pin by `pairReviewerModelsAndEfforts`.
// `grok` runs `grok --model <id>` (slashdo's `grok[<model>]` bracket); it takes a
// model but NO effort at all, which is why this roster and
// EFFORT_SELECTABLE_REVIEWERS are genuinely different sets rather than two names
// for one list. `cursor` runs `cursor-agent --model <id>` and DOES take an
// effort — but as a parameter of the model id (`gpt-5[effort=max]`), not a flag,
// so its pin rides this roster's `--model` rather than an `--effort` argv.
// `opencode` runs `opencode run -m <provider/model>`, `kilo` (its fork) runs
// `kilo run --model <provider/model>`, and `kimi` runs `kimi --model <id>`; none
// offers a pickable effort, so they widen this roster past
// EFFORT_SELECTABLE_REVIEWERS the same way `grok` does. `reviewerModelFlag`
// owns which of `--model`/`-m` each one spells.
// Copilot/local-LLM reviewers are excluded — the former has no CLI, the latter
// get their model injected server-side by `POST /api/code-review/local`. Add a
// reviewer here when its CLI gains model selection; the `<reviewer>Model`
// settings scalar is generated from this roster (codeReviewSettingsSchema).
export const MODEL_CAPABLE_CLI_REVIEWERS = ['codex', 'claude', 'antigravity', 'grok', 'cursor', 'pi', 'opencode', 'kilo', 'kimi'];
// Every reviewer whose model the user can PICK in the UI: the model-capable CLIs
// above (threaded into the follow-up prompt as `<reviewer> --model <id>`) plus the
// local-LLM backends (whose id is injected server-side by
// `POST /api/code-review/local`, or emitted as slashdo's `[<model>]` bracket for a
// claim flow). `copilot` and `@username` reviewers are excluded — neither is a
// model-taking backend, matching slashdo rejecting `copilot[…]`/`@login[…]`.
export const MODEL_SELECTABLE_REVIEWERS = [...MODEL_CAPABLE_CLI_REVIEWERS, ...LOCAL_LLM_REVIEWERS];
// The executable a CLI reviewer's slug actually resolves to on PATH. Every slug
// except `antigravity` names its own binary; `antigravity` is the STORED,
// federated reviewer identity (aliased from the older `gemini`) while the
// shipped executable is `agy` — there is no `antigravity` command. A prompt that
// names only the slug sends the follow-up agent looking for a binary that does
// not exist: one CoS review-loop agent probed `command -v antigravity`, found
// nothing, declared "no reviewer available", and merged its own PR on a
// self-review. Prompt builders must resolve the slug through
// `reviewerCliBinary()` before telling an agent what to invoke.
// A reviewer absent from this map has no spawnable CLI (`copilot` is a GitHub
// API review, `lmstudio`/`ollama` go through `POST /api/code-review/local`).
export const REVIEWER_CLI_BINARIES = {
  claude: 'claude',
  antigravity: ANTIGRAVITY_COMMAND,
  codex: 'codex',
  grok: 'grok',
  cursor: CURSOR_COMMAND,
  pi: 'pi',
  opencode: 'opencode',
  kilo: 'kilo',
  kimi: 'kimi',
};

// The `--model` flag a CLI reviewer's binary actually spells. Only a reviewer
// that deviates from `--model` appears; `reviewerModelFlag` supplies the default
// for the rest. `opencode` takes its model as `opencode run -m <provider/model>`
// (mirroring `opencodeCliArgs` in providerVendors.js) — rendering `--model`
// there would have the follow-up agent probe for a flag that is not the
// documented one.
const REVIEWER_MODEL_FLAGS = { opencode: '-m' };

/**
 * The flag a CLI reviewer's pinned model must be passed with (`--model` unless
 * that reviewer's binary spells it differently). Accepts the `gemini` alias.
 *
 * @param {string} reviewer - reviewer slug
 * @returns {string}
 */
export function reviewerModelFlag(reviewer) {
  const slug = typeof reviewer === 'string' ? reviewer.trim().toLowerCase() : '';
  return REVIEWER_MODEL_FLAGS[REVIEWER_ALIASES[slug] ?? slug] || '--model';
}

/**
 * Is this reviewer a CLI the agent spawns itself? Derived by EXCLUSION rather
 * than from REVIEWER_CLI_BINARIES so a newly added CLI reviewer still drives the
 * review loop before anyone remembers to map its binary (the map's coverage is
 * pinned separately by reviewerConfig.test.js).
 *
 * The one definition of the rule — the prompt builder and the coverage test both
 * call it, so neither can re-implement (and quietly diverge from) it.
 *
 * @param {string} reviewer - reviewer slug
 * @returns {boolean}
 */
export function isCliReviewer(reviewer) {
  return reviewer !== DEFAULT_REVIEWER && !isToolFreeReviewer(reviewer);
}

/**
 * The PATH executable for a CLI reviewer slug, or `null` when the reviewer is
 * not a spawnable CLI. Accepts the `gemini` alias.
 *
 * A null here means "no binary is mapped", NOT "not a CLI" — use isCliReviewer
 * for that question. The two can disagree for exactly one reviewer: a new CLI
 * reviewer added to REVIEWER_VALUES before its REVIEWER_CLI_BINARIES entry.
 * That reviewer still drives the loop (isCliReviewer says yes) and its prompt
 * falls back to naming the slug — the pre-existing behavior — rather than being
 * silently dropped. reviewerConfig.test.js pins the map's coverage so the window
 * closes at review time.
 *
 * @param {string} reviewer - reviewer slug (`antigravity`, `gemini`, `codex`, …)
 * @returns {string|null}
 */
export function reviewerCliBinary(reviewer) {
  if (typeof reviewer !== 'string') return null;
  const slug = reviewer.trim().toLowerCase();
  return REVIEWER_CLI_BINARIES[REVIEWER_ALIASES[slug] || slug] || null;
}

/**
 * Render a reviewer slug for an agent prompt as the command it must actually
 * run, keeping the slug visible so the text still lines up with the configured
 * reviewer list and slashdo's `--review-with` token.
 *
 * `antigravity` → ``​`agy` (the `antigravity` reviewer)``; every other reviewer,
 * whose binary equals its slug, → ``​`codex` `` with no redundant restatement.
 *
 * @param {string} reviewer - reviewer slug
 * @returns {string} markdown fragment
 */
export function describeReviewerCli(reviewer) {
  if (typeof reviewer !== 'string' || !reviewer) return '';
  const binary = reviewerCliBinary(reviewer);
  if (!binary || binary === reviewer) return `\`${reviewer}\``;
  return `\`${binary}\` (the \`${reviewer}\` reviewer)`;
}
// Stop-mode for the multi-reviewer loop (slashdo `--review-stop-on-*`).
export const REVIEW_STOP_MODES = ['all', 'on-findings', 'on-clean'];
export const DEFAULT_REVIEW_STOP_MODE = 'all';

// The task-metadata keys that TOGETHER form a task-local reviewer override —
// everything the picker writes, and so everything its "Use system Code Review
// Defaults" reset has to remove. A key missing here leaves a pin behind after a
// reset the user believes cleared it.
// Mirrored in client/src/lib/reviewerPins.js.
export const REVIEWER_OVERRIDE_KEYS = Object.freeze([
  // Legacy singular, still stored on schedules saved before the list existed.
  'reviewer',
  'reviewers',
  'usernames',
  'optionalReviewers',
  'reviewerMaxRounds',
  'reviewerModels',
  'reviewerEfforts',
  'reviewStopMode',
  'reviewerApplies',
]);

// The subset `resolveReviewerConfig` actually READS. `reviewStopMode` and
// `reviewerApplies` are deliberately absent: they are slashdo run flags, and a
// claim flow has no flag string to put them in (the claim prompt gets a reviewer
// CSV), so neither can change which reviewers a claim runs. Keying the reported
// `source` on the full roster would label a task `task-override` for a stop-mode
// the user set years ago and then send them to clear an "override" that is not
// supplying the list they are looking at.
export const REVIEWER_LIST_OVERRIDE_KEYS = Object.freeze(
  REVIEWER_OVERRIDE_KEYS.filter((key) => key !== 'reviewStopMode' && key !== 'reviewerApplies')
);

/**
 * Does this task metadata pin any part of the reviewer list itself (as opposed
 * to a run flag)? Key PRESENCE is the signal, not truthiness: an explicitly
 * empty `optionalReviewers: []` or `reviewerModels: {}` is a real override — it
 * clears the defaults' value — so collapsing it into "nothing configured" would
 * report the wrong source.
 */
export function hasReviewerOverride(metadata) {
  return isPlainObject(metadata) && REVIEWER_LIST_OVERRIDE_KEYS.some((key) => key in metadata);
}

// Arbitrary GitHub reviewer usernames (e.g. `@CodeReviewbot`) requested as PR
// reviewers to gate merging — a class distinct from the fixed REVIEWER_VALUES
// enum (which either invoke a CLI, hit the local-LLM endpoint, or request the
// native Copilot reviewer). Usernames are appended to slashdo's `--review-with`
// as `@user` tokens after the keyed reviewers; the review-loop follow-up prompt
// instructs the agent to request each as a PR reviewer and gate the merge on it.
//
// Stored WITHOUT the leading `@` (added back only in the flag string). The
// charset is deliberately shell-safe — a GitHub/GitLab username (1–39 chars,
// alphanumeric + single hyphens, no leading/trailing hyphen) optionally followed
// by a `/team-slug` for org-team mentions. No shell metacharacters, so the token
// stays inert wherever it lands in a command string.
export const MAX_REVIEW_USERNAMES = 20;
const REVIEW_USERNAME_RE = /^[A-Za-z0-9_](?:[A-Za-z0-9._-]{0,254})(?:\/[A-Za-z0-9._-]{1,100})?$/;

/**
 * Normalize a raw list of reviewer usernames: strip an optional leading `@`,
 * trim, drop anything that isn't a shell-safe GitHub/GitLab username/team slug,
 * case-insensitively dedupe (GitHub logins are case-insensitive) while
 * preserving first-occurrence order, and cap at MAX_REVIEW_USERNAMES. Returns
 * a clean array of usernames WITHOUT the `@` prefix. Non-array input → [].
 */
export function normalizeReviewUsernames(list) {
  if (!Array.isArray(list)) return [];
  const seen = new Set();
  const out = [];
  for (const raw of list) {
    if (typeof raw !== 'string') continue;
    const trimmed = raw.trim().replace(/^@+/, '');
    if (!trimmed || !REVIEW_USERNAME_RE.test(trimmed)) continue;
    const key = trimmed.toLowerCase();
    if (seen.has(key)) continue;
    seen.add(key);
    out.push(trimmed);
    if (out.length >= MAX_REVIEW_USERNAMES) break;
  }
  return out;
}

/**
 * Resolve reviewer usernames with task-over-default precedence: a task-level
 * list (even explicitly empty) overrides the Code Review Defaults; only fall
 * back to the defaults when the task didn't pin its own. Mirrors how
 * `normalizeReviewers`'s fallback param works for the keyed reviewers.
 */
export function resolveReviewUsernames(metadataUsernames, defaultUsernames) {
  return Array.isArray(metadataUsernames)
    ? normalizeReviewUsernames(metadataUsernames)
    : normalizeReviewUsernames(defaultUsernames);
}

/**
 * Normalize ONE raw reviewer identity to the exact token `--review-with` emits:
 * a keyed slug from `REVIEWER_VALUES` (aliasing `gemini` → `antigravity`) or an
 * `@<username>`. Returns null for anything else. Single definition of the token
 * identity shared by `normalizeOptionalReviewers` and
 * `normalizeReviewerMaxRounds`, so the `~opt` set and the `~max=<n>` map can't
 * disagree about what a reviewer is called.
 */
function normalizeReviewerToken(raw) {
  if (typeof raw !== 'string') return null;
  const trimmed = raw.trim();
  if (!trimmed) return null;
  if (trimmed.startsWith('@')) {
    const [user] = normalizeReviewUsernames([trimmed]);
    return user ? `@${user}` : null;
  }
  const slug = REVIEWER_ALIASES[trimmed] ?? trimmed;
  return isReviewer(slug) ? slug : null;
}

/**
 * Reviewer identities the user marked OPTIONAL (non-blocking). slashdo's `~opt`
 * suffix is appended to each matching `--review-with` token, so an *inconclusive*
 * verdict from that reviewer (timeout / no-verdict / partial) no longer gates the
 * merge — a hard-error from it still does (slashdo `lib/multi-reviewer-loop.md`).
 * This is the escape hatch for a valuable-but-flaky reviewer (a local Ollama
 * model that often returns nothing) that would otherwise strand every PR on an
 * `inconclusive` aggregate.
 *
 * Each entry mirrors an *emitted* `--review-with` token so the builder's
 * membership test is a plain lookup: a keyed slug from `REVIEWER_VALUES`
 * (`ollama`, `lmstudio`, …) or an `@<username>`. Normalizes like the sibling
 * helpers — drop non-strings/unknown slugs/unsafe usernames, alias `gemini` →
 * `antigravity`, dedupe case-insensitively preserving order. Non-array → undefined
 * (an omitted field isn't persisted as an empty override).
 */
export function normalizeOptionalReviewers(list) {
  if (!Array.isArray(list)) return undefined;
  const seen = new Set();
  const out = [];
  for (const raw of list) {
    const token = normalizeReviewerToken(raw);
    if (!token) continue;
    const key = token.toLowerCase();
    if (seen.has(key)) continue;
    seen.add(key);
    out.push(token);
  }
  return out;
}

/**
 * Resolve optional (non-blocking) reviewers with task-over-default precedence:
 * a task-level list (even explicitly empty) overrides the Code Review Defaults;
 * only fall back to the defaults when the task didn't pin its own. Mirrors
 * `resolveReviewUsernames`.
 */
export function resolveOptionalReviewers(metadataOptional, defaultOptional) {
  return Array.isArray(metadataOptional)
    ? (normalizeOptionalReviewers(metadataOptional) || [])
    : (normalizeOptionalReviewers(defaultOptional) || []);
}

/**
 * True when `reviewer` is one the user marked `~opt` (non-blocking).
 *
 * Both sides go through `normalizeReviewerToken` first, so this answers the
 * same question `buildReviewWithArgs` answers when it decides whether to append
 * `~opt` — an alias on one side (`gemini` vs `antigravity`) can't make the
 * emitted flag and the merge gate disagree about the same configuration. An
 * unrecognizable reviewer token is never optional: fail closed toward blocking.
 *
 * For a whole list, prefer `hasRequiredReviewer`, which builds the membership
 * set once.
 */
export function isOptionalReviewer(reviewer, optionalReviewers) {
  const token = normalizeReviewerToken(reviewer);
  return token !== null && optionalReviewerSet(optionalReviewers).has(token.toLowerCase());
}

/**
 * True when at least one of `reviewers` is NOT marked optional — i.e. some
 * reviewer's verdict genuinely gates the merge.
 *
 * The inverse ("every configured reviewer is `~opt`") is what the gates read:
 * a phase with no binding reviewer can never record `review-blocked`, and the
 * completion workflow tells such a run not to invent a blocker from a reviewer
 * that returned nothing. It does NOT license merging an `inconclusive`
 * aggregate — slashdo already excluded the optional misses from that, so one
 * that survives means `push-failed` (see `buildPostPRMergeSteps`).
 *
 * Shared so the local pre-PR phase, the PR-side phase, and the completion
 * workflow's merge step can't disagree about which reviewers are binding.
 */
export function hasRequiredReviewer(reviewers, optionalReviewers) {
  const optional = optionalReviewerSet(optionalReviewers);
  return (Array.isArray(reviewers) ? reviewers : []).some(reviewer => {
    const token = normalizeReviewerToken(reviewer);
    return token === null || !optional.has(token.toLowerCase());
  });
}

/**
 * Factory for the token-keyed per-reviewer PIN normalizers (`~max=<n>` caps,
 * model ids, reasoning efforts). All three share one contract and only differ in
 * how they validate a single value, so the contract lives here once:
 *
 * - Non-object input → `undefined`, so an omitted field isn't persisted as an
 *   empty override (an explicitly empty `{}` IS kept — it's a real "clear the
 *   defaults for this task" choice).
 * - Keys are normalized to the exact token `--review-with` emits
 *   (`normalizeReviewerToken`), so the maps can't disagree about what a reviewer
 *   is called; unknown tokens are dropped.
 * - First spelling wins for two names of one reviewer (`gemini`/`antigravity`,
 *   `@Bot`/`@bot`) — mirrors `normalizeOptionalReviewers`' dedupe.
 * - A value `normalizeOne` rejects is DROPPED, never coerced — for every pin
 *   kind, "absent" and "a falsy value" mean different things downstream.
 *
 * `Object.create(null)` while building so a reviewer token can't collide with
 * `Object.prototype` keys; spread on return so callers get a plain object.
 *
 * @param {(value: unknown, token: string) => unknown} normalizeOne - returns the
 *   validated value, or a falsy value to drop the entry.
 */
function keyedReviewerPinNormalizer(normalizeOne) {
  return (map) => {
    if (!isPlainObject(map)) return undefined;
    const out = Object.create(null);
    for (const [rawKey, rawValue] of Object.entries(map)) {
      const token = normalizeReviewerToken(rawKey);
      if (!token) continue;
      const value = normalizeOne(rawValue, token);
      if (!value && value !== 0) continue;
      if (Object.prototype.hasOwnProperty.call(out, token)) continue;
      out[token] = value;
    }
    return { ...out };
  };
}

/**
 * Factory for the matching task-over-default resolvers: a task-level map — even
 * an explicitly empty one — overrides the Code Review Defaults; only an
 * absent/malformed one falls back. Mirrors `resolveOptionalReviewers`.
 *
 * @param {(map: unknown) => Object|undefined} normalizeMap - the normalizer this
 *   pin kind was built with.
 */
function keyedReviewerPinResolver(normalizeMap) {
  return (metadataMap, defaultMap) => (isPlainObject(metadataMap)
    ? (normalizeMap(metadataMap) || {})
    : (normalizeMap(defaultMap) || {}));
}

// Ceiling on a per-reviewer `~max=<n>` cap. slashdo's inner loops carry their own
// 10-iteration safety guardrail, so a budget above it can never be spent —
// accepting one would just be a lie in the flag string.
export const MAX_REVIEWER_MAX_ROUNDS = 10;

/**
 * Per-reviewer iteration caps — slashdo's `~max=<n>` suffix (v3.25.0). Caps how
 * many review → fix → re-review cycles ONE reviewer runs before it stops, so a
 * slow local model can be included in a chain without paying for its otherwise
 * hardcoded 3 rounds (`--review-with claude~max=2,ollama~max=1,codex~max=3`).
 * Stored as a token-keyed map (`{ ollama: 1, '@flaky-bot': 0 }`) rather than a
 * list because the cap carries a value; the key is the same *emitted*
 * `--review-with` token `normalizeOptionalReviewers` uses.
 *
 * **Absent ≠ 0.** slashdo reads `~max=0` as "loop until this reviewer is clean"
 * (bounded by its own 10-round guardrail), which is the OPPOSITE of "no cap
 * requested" (that keeps slashdo's built-in default of 3 for CLI/Ollama
 * reviewers). So a missing key and an explicit `0` must never collapse: an entry
 * whose value isn't a usable cap is DROPPED rather than coerced to `0`.
 * Drops unknown tokens, non-integers, negatives, and anything above
 * MAX_REVIEWER_MAX_ROUNDS so a hand-edited settings.json can't smuggle in an
 * unbounded budget. Non-object input → undefined (an omitted field isn't
 * persisted as an empty override).
 *
 * `0` is the one pin value that is falsy AND meaningful, which is why the shared
 * factory keeps it explicitly.
 */
export const normalizeReviewerMaxRounds = keyedReviewerPinNormalizer((rawValue) => (
  // Only a genuine non-negative integer is a cap. A string "2", null, NaN, or
  // 1.5 is not — and must NOT fall through to 0, which slashdo reads as
  // "unlimited".
  (Number.isInteger(rawValue) && rawValue >= 0 && rawValue <= MAX_REVIEWER_MAX_ROUNDS)
    ? rawValue
    : undefined
));

/**
 * Resolve per-reviewer iteration caps with task-over-default precedence: a
 * task-level map (even explicitly empty) overrides the Code Review Defaults;
 * only fall back to the defaults when the task didn't pin its own. Mirrors
 * `resolveOptionalReviewers`.
 */
export const resolveReviewerMaxRounds = keyedReviewerPinResolver(normalizeReviewerMaxRounds);

// Upper bound on a pinned reviewer model id. Generous (Bedrock/Ollama ids get
// long) but present so a hand-edited settings.json can't smuggle in a blob that
// then round-trips the TASKS.md store.
export const MAX_REVIEWER_MODEL_LENGTH = 200;

// Characters a model id may not contain, because they are STRUCTURAL in the
// emitted `--review-with` token and there is no escape for them:
//  - `]` would close the `[<model>]` selector early (`foo]~opt` → a corrupt entry
//    whose remainder slashdo then parses as suffixes),
//  - `[` would open a nested one,
//  - `,` would split the entry list, turning one reviewer into two bogus ones,
//  - whitespace that breaks lines would split the single-line flag string.
// Everything else stays legal on purpose: the value is free-form in slashdo's
// grammar (`agy[Gemini 3.5 Flash (High)]` is valid), and the field has to accept
// whatever id the user's environment actually needs. A space is fine; a newline is
// not.
const REVIEWER_MODEL_FORBIDDEN_RE = /[[\],\r\n\t]/;

/**
 * Validate ONE reviewer model id — the single definition shared by the
 * token-keyed map normalizer, the `<reviewer>Model` settings scalars, and the
 * defaults→map adapter, so a pin can't be accepted by one path and dropped by
 * another (which would show the user a stored pin that never reaches a reviewer).
 *
 * Returns the trimmed id, or `undefined` when it isn't usable: a non-string, a
 * blank/whitespace-only value (absent ≠ `''` — a `--model ` with no id would break
 * the invocation), an over-long one, one carrying a structural delimiter, or one
 * naming a reviewer that takes no model. Pass `reviewer` to apply that last check.
 */
export function normalizeReviewerModel(raw, reviewer = null) {
  if (reviewer !== null && !MODEL_SELECTABLE_REVIEWERS.includes(reviewer) && !isProviderReviewer(reviewer)) return undefined;
  if (typeof raw !== 'string') return undefined;
  const model = raw.trim();
  if (!model || model.length > MAX_REVIEWER_MODEL_LENGTH) return undefined;
  if (REVIEWER_MODEL_FORBIDDEN_RE.test(model)) return undefined;
  return model;
}

// Reviewers whose slashdo `--review-with` entry accepts a `[<model>]` bracket
// (`lib/multi-reviewer-loop.md`: codex/claude/agy/grok/cursor/ollama). A
// PORTOS_ONLY_REVIEWERS entry has no slashdo counterpart at all, so a pinned
// model for it never becomes a bracket, and `copilot`/`@login` entries reject
// one outright.
export const BRACKET_MODEL_REVIEWERS = MODEL_SELECTABLE_REVIEWERS.filter(r => !PORTOS_ONLY_REVIEWERS.includes(r));

/**
 * Per-reviewer model pins — the model id ONE reviewer runs with, keyed by the
 * same emitted `--review-with` token as `normalizeOptionalReviewers` /
 * `normalizeReviewerMaxRounds` (e.g. `{ codex: 'gpt-5.6-sol', ollama: 'qwen2.5:7b' }`).
 *
 * The value is free-text on purpose: a reviewer CLI is spawned by the *agent*,
 * not by PortOS's argv builder, so the id the user needs is environment-specific
 * (a Bedrock-form Claude id on a Bedrock box, an installed Ollama model for an
 * Ollama-backed `claude`). We validate the shape, not the catalog.
 *
 * Only MODEL_SELECTABLE_REVIEWERS can carry a pin — `copilot` has no CLI and a
 * `@username` reviewer is a human/bot, mirroring slashdo rejecting `copilot[…]`
 * and `@login[…]`. An absent key means "let that reviewer pick its own default",
 * which is NOT the same as an empty string, so a blank/whitespace value is
 * DROPPED rather than persisted as `''` (a `--model ` with no id would break the
 * reviewer invocation). Non-object input → undefined, so an omitted field isn't
 * persisted as an empty override.
 *
 * An id carrying a character that is structural in the emitted token
 * (REVIEWER_MODEL_FORBIDDEN_RE — `[`, `]`, `,`, line breaks) is dropped rather
 * than emitted: there's no escape for them inside `[<model>]`, so `foo]~opt` would
 * close the selector early and leave slashdo parsing the remainder as a suffix.
 * Dropping is the safe failure — the reviewer falls back to its own default model
 * instead of running against a corrupt reviewer list.
 */
export const normalizeReviewerModels = keyedReviewerPinNormalizer(normalizeReviewerModel);

/**
 * Resolve per-reviewer model pins with task-over-default precedence: a
 * task-level map (even explicitly empty) overrides the Code Review Defaults;
 * only fall back to the defaults when the task didn't pin its own. Mirrors
 * `resolveReviewerMaxRounds`.
 */
export const resolveReviewerModels = keyedReviewerPinResolver(normalizeReviewerModels);

/**
 * Fold the Code Review Defaults' per-reviewer model SCALARS
 * (`codexModel` / `claudeModel` / `lmstudioModel` / `ollamaModel`) into the
 * token-keyed map shape the resolvers and the picker UI both speak.
 *
 * The scalars are the persisted settings encoding and stay that way — they cross
 * installs, and rewriting them to a map would need a migration for zero gain.
 * This is the one adapter between the two shapes; everything downstream works in
 * map form.
 */
export function reviewerModelsFromDefaults(defaults) {
  const out = Object.fromEntries(Object.entries(normalizeReviewerModels(defaults?.providerModels) || {}).filter(([key]) => isProviderReviewer(key)));
  for (const r of MODEL_SELECTABLE_REVIEWERS) {
    // Re-checked here, not trusted: settings.json is hand-editable, and a value
    // stored before the scalars were validated must not surface as a pin the token
    // builders would then drop.
    const model = normalizeReviewerModel(defaults?.[`${r}Model`], r);
    if (model) out[r] = model;
  }
  return out;
}

// Reasoning-effort ladder for the local-LLM reviewers. Their review request goes
// out as an OpenAI-compatible `/v1/chat/completions` call, whose `reasoning_effort`
// field both LM Studio and Ollama accept for thinking models — but only over the
// low/medium/high tier names. The wider CLI ladder (`minimal`/`xhigh`/`max`/
// `ultra`) is vendor-CLI vocabulary that an OpenAI-shaped backend can reject, so
// the local reviewers get their own, narrower set.
export const LOCAL_LLM_EFFORT_LEVELS = Object.freeze(['low', 'medium', 'high']);

/**
 * Reviewer slug → the reasoning-effort ladder that reviewer accepts. Only
 * reviewers WITH an effort control appear: `copilot` is a GitHub review, `grok`'s
 * CLI has no effort control of any kind, and an `@username` reviewer is a person.
 *
 * A ladder here means "the user can PICK a level", not "the CLI takes an
 * `--effort` flag" — `cursor` accepts a level only as a variant baked into its
 * model id, so it appears here while `reviewerEffortArgs` returns `[]` for it
 * and `reviewerModelArg` folds the level into `--model` instead.
 *
 * Built once at module load and DERIVED from `effortLevelsForProvider` rather
 * than restated, so a reviewer's ladder here is exactly the one
 * `reviewerEffortArgs` (and the agent-spawn argv builder) will accept — a CLI
 * that gains or loses a tier moves both at once. The lookup goes through
 * `reviewerCliBinary` because that's what identifies the CLI: the `antigravity`
 * slug names no executable, `agy` does.
 *
 * Mirrored in `client/src/components/cos/constants.js` (pinned by a parity test)
 * so the picker only offers a level the server would keep.
 */
export const REVIEWER_EFFORT_LEVELS = Object.freeze(Object.fromEntries(
  REVIEWER_VALUES
    .map((slug) => {
      if (LOCAL_LLM_REVIEWERS.includes(slug)) return [slug, LOCAL_LLM_EFFORT_LEVELS];
      const binary = reviewerCliBinary(slug);
      return [slug, binary ? effortLevelsForProvider({ id: slug, command: binary }) : null];
    })
    .filter(([, levels]) => levels?.length)
));

/**
 * Every reviewer the user can pick an effort for — the effort-capable CLIs
 * (`claude`, `codex`, `antigravity`, `cursor`) plus the local-LLM backends.
 */
export const EFFORT_SELECTABLE_REVIEWERS = Object.freeze(Object.keys(REVIEWER_EFFORT_LEVELS));

/**
 * The ladder for ONE reviewer token, or `null` when it takes no effort. Accepts
 * the `gemini` alias; an `@username` token resolves to null like any non-reviewer.
 *
 * For `codex` reviewers, the ladder is gated on the pinned model: gpt-6 family
 * models reject `minimal`, dropping it from the ladder. Pass the model id to get
 * the right tier set for that model; omit it to get the default static ladder.
 *
 * @param {string} reviewer - reviewer slug
 * @param {string|null|undefined} [model] - optional pinned model id (codex only)
 * @returns {readonly string[]|null}
 */
export function reviewerEffortLevels(reviewer, model = null) {
  if (typeof reviewer !== 'string') return null;
  const slug = reviewer.trim().toLowerCase();
  const normalized = REVIEWER_ALIASES[slug] ?? slug;

  // For codex, derive the ladder from the model if provided
  if (normalized === 'codex' && model) {
    return effortLevelsForProvider({ id: 'codex', command: 'codex' }, model);
  }

  return REVIEWER_EFFORT_LEVELS[normalized] || null;
}

/**
 * Validate ONE reviewer effort — the single definition shared by the token-keyed
 * map normalizer and the `<reviewer>Effort` settings scalars, so a level can't be
 * accepted by one path and dropped by another.
 *
 * `reviewer` is REQUIRED — this is the tight branch by design. Defaulting it to
 * "any known effort" would validate against the union of every ladder, so a
 * caller that forgot the argument would quietly accept `ollama: 'ultra'` and
 * `antigravity: 'max'`, the exact values the drop-don't-clamp contract exists to
 * reject.
 *
 * For `codex` reviewers, pass the pinned model id to gate the ladder on gpt-6
 * family models that reject `minimal`.
 *
 * Returns the level, or `undefined` when it isn't usable: a non-string, a level
 * outside that reviewer's own ladder (`agy` really does reject `--effort max`),
 * or a reviewer with no effort control at all. Deliberately NOT clamped the way
 * `resolveCliEffort` clamps a provider pin: this value is user-chosen from a
 * per-reviewer list, so an out-of-ladder entry means the stored config is stale
 * or hand-edited, and silently reviewing at a *different* effort than the one
 * displayed is worse than falling back to the reviewer's own default.
 *
 * @param {string} raw - raw effort value
 * @param {string} reviewer - reviewer slug
 * @param {string|null|undefined} [model] - optional pinned model id (codex only)
 * @returns {string|undefined}
 */
export function normalizeReviewerEffort(raw, reviewer, model = null) {
  if (typeof raw !== 'string') return undefined;
  const effort = raw.trim().toLowerCase();
  if (!effort) return undefined;
  // Provider identities are dynamic; their model-specific ladder is resolved from
  // the provider catalog at selection/execution, while storage accepts known tiers.
  const levels = isProviderReviewer(reviewer) ? EFFORT_LEVELS : reviewerEffortLevels(reviewer, model);
  return levels?.includes(effort) ? effort : undefined;
}

/**
 * Per-reviewer reasoning-effort pins — how hard ONE reviewer thinks, keyed by the
 * same emitted `--review-with` token as `normalizeReviewerModels` (e.g.
 * `{ codex: 'high', ollama: 'low' }`).
 *
 * Three carriers, depending on who invokes the reviewer. On a slashdo invocation
 * it rides the emitted token as `~effort=<level>` (`markSuffixes`), which slashdo
 * turns into the reviewer's own flag. Where PortOS drives the invocation itself it
 * is spelled out instead: the review-loop follow-up prompt's CLI command line
 * (`codex -c model_reasoning_effort=high`, `claude --effort high`) and the
 * `reasoning_effort` field of the local reviewer's `/api/code-review/local` body.
 *
 * An absent key means "let that reviewer use its own default effort", which is
 * NOT the same as a blank string, so an unusable value is DROPPED rather than
 * persisted. Non-object input → undefined, so an omitted field isn't persisted as
 * an empty override.
 */
export const normalizeReviewerEfforts = keyedReviewerPinNormalizer(normalizeReviewerEffort);

/**
 * Resolve per-reviewer effort pins with task-over-default precedence: a
 * task-level map (even explicitly empty) overrides the Code Review Defaults;
 * only fall back to the defaults when the task didn't pin its own. Mirrors
 * `resolveReviewerModels`.
 */
export const resolveReviewerEfforts = keyedReviewerPinResolver(normalizeReviewerEfforts);

/**
 * Resolve a task's whole reviewer configuration against the Code Review Defaults
 * in one call — the reviewer list plus every per-reviewer pin, each with the same
 * task-over-default precedence its own resolver defines.
 *
 * The prompt builder resolves this set at three separate spawn paths (the review
 * follow-up, the claim prompt, and the light/cleanup prompt). Hand-copying six
 * resolver calls per site meant adding a pin kind was a three-site edit where a
 * missed site is silent: the pin is configured, persisted, and displayed, but
 * never reaches the reviewer, and no test fails. One bundle, one edit.
 *
 * Shape matches `resolveReviewLoopOptions`'s in `services/codeReview.js`, minus
 * the stop-mode/applies fields that come from elsewhere at these call sites.
 */
export function resolveReviewerConfig(metadata, codeReviewDefaults, defaultReviewers) {
  return {
    reviewers: resolveReviewerGroup(metadata, codeReviewDefaults, defaultReviewers),
    usernames: resolveReviewUsernames(metadata?.usernames, codeReviewDefaults?.usernames),
    optionalReviewers: resolveOptionalReviewers(metadata?.optionalReviewers, codeReviewDefaults?.optionalReviewers),
    reviewerMaxRounds: resolveReviewerMaxRounds(metadata?.reviewerMaxRounds, codeReviewDefaults?.reviewerMaxRounds),
    ...resolveReviewerPins(metadata, codeReviewDefaults)
  };
}

/**
 * `resolveReviewerConfig` plus the two run flags the prompt builders need — the
 * complete reviewer configuration as ONE frozen value, so a prompt builder takes
 * `reviewPolicy` instead of eight parameters and a ninth knob is added here, not
 * at every call site.
 *
 * - `forgeReviewerUsernames` — the forge logins (`@user` review tokens) requested
 *   as PR/MR reviewers; the bare `usernames` of `resolveReviewerConfig`.
 * - `reviewStopMode` — task over Code Review Defaults over `DEFAULT_REVIEW_STOP_MODE`.
 * - `reviewerApplies` — the `--reviewer-applies` flag. `crossesPublicForge` clamps
 *   it to `false`: a PR/MR review reads contributor-controlled public content, so
 *   its reviewer stays review-only and the orchestrating agent applies the fixes.
 *
 * @param {Object|undefined} metadata - task metadata
 * @param {Object|null|undefined} codeReviewDefaults
 * @param {string[]|null|undefined} defaultReviewers
 * @param {Object} [opts]
 * @param {boolean} [opts.crossesPublicForge=false] - the run opens a PR/MR or is a
 *   review-loop follow-up over one
 */
export function resolveReviewPolicy(metadata, codeReviewDefaults, defaultReviewers, { crossesPublicForge = false } = {}) {
  const { usernames, ...config } = resolveReviewerConfig(metadata, codeReviewDefaults, defaultReviewers);
  const configuredReviewerApplies = metadata?.reviewerApplies !== undefined
    ? isTruthyMeta(metadata.reviewerApplies)
    : (codeReviewDefaults?.reviewerApplies === true);
  return Object.freeze({
    ...config,
    forgeReviewerUsernames: usernames,
    reviewStopMode: metadata?.reviewStopMode || codeReviewDefaults?.stopMode || DEFAULT_REVIEW_STOP_MODE,
    reviewerApplies: crossesPublicForge ? false : configuredReviewerApplies
  });
}

/** The reviewer a claim flow falls back to when its resolved list is unusable. */
const CLAIM_REVIEWER_FALLBACK = ['codex'];

/**
 * Constrain an already-resolved reviewer list to what an UNATTENDED claim run can
 * actually invoke: `copilot` is a forge-side PR reviewer with no CLI, so a claim
 * agent told to "review with copilot" has nothing to run and stalls (#2507).
 * An empty result falls back to `codex` rather than to `DEFAULT_REVIEWERS`
 * (which is `copilot`, the very thing being removed) — unless `usernames` names
 * forge reviewers, which the run requests and waits on itself.
 */
export function claimSafeReviewers(reviewers, usernames = []) {
  const kept = (Array.isArray(reviewers) ? reviewers : []).filter((reviewer) => reviewer !== 'copilot');
  // A forge reviewer the run requests and waits on is a reviewer it can invoke.
  if (!kept.length && normalizeReviewUsernames(usernames).length) return [];
  return kept.length ? kept : [...CLAIM_REVIEWER_FALLBACK];
}

/**
 * Keep bridge-dispatched providers and local models ahead of standalone/forge
 * reviewers. The historical export name and stable partition preserve saved
 * ordering; provider identities no longer imply tool-free execution.
 */
export function prioritizeToolFreeReviewers(reviewers) {
  const normalized = Array.isArray(reviewers) ? reviewers : [];
  return [
    ...normalized.filter((reviewer) => isToolFreeReviewer(reviewer)),
    ...normalized.filter((reviewer) => !isToolFreeReviewer(reviewer)),
  ];
}

/**
 * `resolveReviewerConfig` plus the claim flow's copilot guard and the emitted
 * `--review-with` token list — the ONE resolver a claim prompt's reviewer text
 * and a claim task's persisted `reviewers` metadata both go through, so the two
 * cannot name different reviewers.
 *
 * The generators resolve their list before a task record exists (they read
 * schedule metadata + Code Review Defaults); the prompt builder resolves it from
 * the persisted task metadata at spawn time. Feeding both the same function is
 * what makes `reviewerConfigMetadata`'s round-trip exact.
 */
export function resolveClaimReviewerConfig(metadata, codeReviewDefaults, defaultReviewers) {
  if (metadata?.prCompletion === PR_COMPLETIONS.MERGE_ON_GREEN) {
    return {
      reviewers: [],
      usernames: [],
      optionalReviewers: [],
      reviewerMaxRounds: {},
      reviewerModels: {},
      reviewerEfforts: {},
      csv: ''
    };
  }
  const config = resolveReviewerConfig(metadata, codeReviewDefaults, defaultReviewers);
  const reviewers = claimSafeReviewers(config.reviewers, config.usernames);
  return {
    ...config,
    reviewers,
    csv: buildReviewersCsv(reviewers, config.usernames, config.optionalReviewers, config.reviewerMaxRounds, config.reviewerModels, config.reviewerEfforts)
  };
}

/**
 * Resolve the model and effort pins TOGETHER — `{ reviewerModels, reviewerEfforts }`
 * with task-over-default precedence, already reconciled into a pair the reviewer's
 * CLI accepts (`pairReviewerModelsAndEfforts`).
 *
 * The two are never legitimately resolved apart: an `antigravity` model id can
 * carry its effort as a suffix, so whoever resolves the models must also be
 * holding the efforts to hand the suffix to. Resolving them separately is the
 * footgun — three prompt-building sites in `cosTaskGenerator.js` had already
 * hand-copied the pair of calls, and each would have emitted an
 * `agy --model <suffixed-id> --effort <tier>` invocation agy rejects. This is the
 * one call every site makes instead.
 *
 * Deliberately NOT expressed on `lib/llmRoutePin.js` (#4793). That module owns a
 * single `{ providerId, model, effort }` triple; a reviewer pin is two maps keyed
 * by reviewer slug, with no provider dimension at all — the slug IS the routing
 * key — and its precedence is whole-MAP (an explicitly empty task map overrides
 * the defaults), not per-field. Its effort is also validated against each
 * reviewer's OWN ladder via `normalizeReviewerEffort`, which is strictly narrower
 * than the union `EFFORT_LEVELS` enum the shared schema uses: `agy` really does
 * reject `--effort max`. There is no shape the two can meet in without losing
 * that narrowing, so this stays hand-rolled.
 *
 * @param {Object} [pins] - task metadata (or explicit options) carrying
 *   `reviewerModels` / `reviewerEfforts` maps; an absent map falls back to the
 *   Code Review Defaults, an explicitly empty one overrides them.
 * @param {Object} [codeReviewDefaults] - the `<reviewer>Model` / `<reviewer>Effort` scalars
 * @returns {{reviewerModels: Object<string,string>, reviewerEfforts: Object<string,string>}}
 */
export function resolveReviewerPins(pins, codeReviewDefaults) {
  return pairReviewerModelsAndEfforts(
    resolveReviewerModels(pins?.reviewerModels, reviewerModelsFromDefaults(codeReviewDefaults)),
    resolveReviewerEfforts(pins?.reviewerEfforts, reviewerEffortsFromDefaults(codeReviewDefaults))
  );
}

/**
 * Reconcile the resolved model and effort pins into a pair the reviewer's CLI
 * will actually accept, and return them as `{ reviewerModels, reviewerEfforts }`.
 *
 * Only `antigravity` needs reconciling. `agy models` enumerates its reasoning
 * tiers as separate model ids (`gemini-3.6-flash-high`), so a hand-typed pin can
 * carry an effort inside the model — and `agy` validates the PAIR, so
 * `--model gemini-3.6-flash-high --effort high` is not the same thing as the
 * `--model <base> --effort high` it expects. Splitting here mirrors what
 * `resolveAntigravityModelAndEffort` already does for PortOS's own agy spawns:
 * the base id becomes the model, and the baked tier supplies the effort ONLY when
 * the user pinned none (an explicit pick always wins).
 *
 * Applied once inside `resolveReviewerPins` rather than at each emission site, so
 * the slashdo `agy[<model>]` bracket, the effort instruction, and the review-loop
 * prompt's literal command line all describe the same invocation.
 *
 * @param {Object<string,string>} [reviewerModels]
 * @param {Object<string,string>} [reviewerEfforts]
 * @returns {{reviewerModels: Object<string,string>, reviewerEfforts: Object<string,string>}}
 */
export function pairReviewerModelsAndEfforts(reviewerModels, reviewerEfforts) {
  const models = { ...(reviewerModels || {}) };
  const efforts = { ...(reviewerEfforts || {}) };
  const { base, effort } = splitAntigravityModel(models.antigravity);
  if (effort && base) {
    models.antigravity = base;
    if (!normalizeReviewerEffort(efforts.antigravity, 'antigravity')) efforts.antigravity = effort;
  }
  return { reviewerModels: models, reviewerEfforts: efforts };
}

/**
 * Every token-keyed per-reviewer pin, as `[metadataKey, normalizeMap]`.
 *
 * The three pins share one persist contract, so the two places that copy them
 * out of caller input — `sanitizeTaskMetadata` here and `addTask` in
 * `cosTaskStore.js` — iterate this table instead of hand-copying a block per
 * pin. Adding a fourth pin kind is then a one-line change that reaches both
 * persist paths at once; a hand-copied block missed at one site would silently
 * drop the pin at write time while every other layer still carried it.
 *
 * Shared semantics for all three: the value is a MAP keyed by the emitted
 * `--review-with` token, and an explicitly empty map is KEPT — that's a real
 * "override the Code Review Defaults back to each reviewer's own default" choice,
 * distinct from an absent key (fall back to the defaults). Individual entries the
 * normalizer can't validate are DROPPED rather than coerced, so a hand-edited
 * settings.json can't smuggle in a cap slashdo would read as "loop until clean"
 * (`~max=0`), a model a reviewer doesn't take, or an effort level its CLI rejects.
 */
export const KEYED_REVIEWER_PINS = [
  ['reviewerMaxRounds', normalizeReviewerMaxRounds],
  ['reviewerModels', normalizeReviewerModels],
  ['reviewerEfforts', normalizeReviewerEfforts]
];

/**
 * Fold the Code Review Defaults' per-reviewer effort SCALARS (`codexEffort` /
 * `claudeEffort` / `antigravityEffort` / `lmstudioEffort` / `ollamaEffort`) into
 * the token-keyed map shape the resolvers and the picker UI both speak — the
 * effort twin of `reviewerModelsFromDefaults`, and the one adapter between the
 * two shapes. Configured providers use the additive `providerEfforts` map.
 */
export function reviewerEffortsFromDefaults(defaults) {
  const out = Object.fromEntries(Object.entries(normalizeReviewerEfforts(defaults?.providerEfforts) || {}).filter(([key]) => isProviderReviewer(key)));
  for (const r of EFFORT_SELECTABLE_REVIEWERS) {
    // Re-checked, not trusted: settings.json is hand-editable, and a stale level
    // must not surface as a pin the invocation builders would then drop.
    const effort = normalizeReviewerEffort(defaults?.[`${r}Effort`], r);
    if (effort) out[r] = effort;
  }
  return out;
}

/**
 * The argv fragment a CLI reviewer takes for a reasoning-effort override —
 * `['--effort', 'high']` for claude/agy, `['-c', 'model_reasoning_effort=high']`
 * for codex, `[]` for everything else. Delegates to `buildEffortArgs` so the flag
 * shape has exactly one home (the spawn builders use the same one).
 *
 * **`cursor` is deliberately `[]` despite having a ladder.** `cursor-agent` has
 * no `--effort` flag and exits non-zero on one, so its level rides `--model`
 * instead — build that with `reviewerModelArg`. Anything that renders a cursor
 * invocation must call BOTH, or it will silently drop the pin (or, worse,
 * hand-roll the `--effort` this returns nothing for).
 *
 * **Normalizes first, deliberately.** `buildEffortArgs` CLAMPS an out-of-ladder
 * value (`agy` + `max` → `--effort high`), which is right for a provider pin the
 * user set against a different provider, but wrong here: a reviewer effort is
 * chosen from that reviewer's own list, so an out-of-ladder value means stale or
 * hand-edited state — and emitting a clamped flag would run the review at an
 * effort the picker displays as `unsupported`. Dropping to the reviewer's own
 * default is the honest failure, matching `normalizeReviewerEffort`'s contract.
 * The normalize is here rather than left to callers because this function is
 * reached with raw task metadata (`reviewLoopReviewerEfforts`), which no
 * normalizer has necessarily touched.
 *
 * For `codex` reviewers, pass the pinned model id to reject `minimal` on gpt-6
 * family models that don't accept it.
 *
 * @param {string} reviewer - reviewer slug
 * @param {string|null|undefined} effort
 * @param {string|null|undefined} [model] - optional pinned model id (codex only)
 * @returns {string[]}
 */
export function reviewerEffortArgs(reviewer, effort, model = null) {
  const binary = reviewerCliBinary(reviewer);
  if (!binary) return [];
  const level = normalizeReviewerEffort(effort, reviewer, model);
  if (!level) return [];
  return buildEffortArgs(level, { id: reviewer, command: binary });
}

/**
 * The id a CLI reviewer's `--model` flag should carry, or `null` when there is
 * no model to pin. The twin of `reviewerEffortArgs`: together they are the whole
 * invocation a pinned reviewer needs, and the ONLY place that knows which of the
 * two carries a cursor effort.
 *
 * For every reviewer but `cursor` this is just the pinned id, threaded verbatim
 * (the id is environment-specific free text — see `normalizeReviewerModels`).
 * For `cursor` the effort is folded in as Cursor's native model variant
 * (`gpt-5` + `max` → `gpt-5[effort=max]`), matching slashdo's own fold, because
 * `cursor-agent` has no `--effort` flag. A cursor effort with no model pinned
 * returns `null` — there is nothing to attach the variant to, and emitting a
 * flag cursor rejects is worse than letting it use its default tier. (The picker
 * says so on the row, so the dropped tier isn't silent to the user.)
 *
 * The extend-an-existing-bracket and leave-an-`effort=`-alone arms of the fold
 * can't be reached by a STORED reviewer pin today — `normalizeReviewerModel`
 * rejects `[`/`]`/`,` because they're structural in the emitted `--review-with`
 * token. They serve the paths that don't go through that gate: a provider's own
 * `defaultModel` and hand-written task metadata.
 *
 * @param {string} reviewer - reviewer slug
 * @param {string|null|undefined} model - the pinned model id
 * @param {string|null|undefined} [effort] - the pinned effort (cursor only)
 * @returns {string|null}
 */
export function reviewerModelArg(reviewer, model, effort) {
  const id = typeof model === 'string' ? model.trim() : '';
  if (!id) return null;
  const slug = typeof reviewer === 'string' ? reviewer.trim().toLowerCase() : '';
  if ((REVIEWER_ALIASES[slug] ?? slug) !== 'cursor') return id;
  const level = normalizeReviewerEffort(effort, 'cursor');
  return level ? foldCursorEffortIntoModel(id, level) : id;
}

/**
 * Prose instruction carrying the per-reviewer effort pins into a prompt whose
 * agent spawns the reviewer CLI ITSELF — the claim flows (which run each
 * configured reviewer by hand, no `--review-with` anywhere in the prompt) and a
 * slashdo invocation that pins no reviewer list.
 *
 * **Not for an invocation that pins `--review-with`.** slashdo's entry grammar is
 * `<agent>[<model>](~opt|~max=<n>|~effort=<level>)*`, and `markSuffixes` emits
 * that `~effort=` suffix, so the pin already reaches the CLI the loop spawns.
 * Restating it as prose there is worse than silent: the agent passes the flag a
 * second time, or hand-runs a reviewer the loop was about to run. Pass the
 * emitted `--review-with` text as `reviewWith` and this returns '' when it sees
 * the suffix — one check, so a caller can't decide wrong.
 *
 * Scoped to CLI reviewers on purpose — `ollama`/`lmstudio` have no binary to
 * name (their effort rides the `POST /api/code-review/local` body instead).
 *
 * `cursor` needs its MODEL to say anything at all: its level is a variant of the
 * model id, never a flag, so pass `reviewerModels` — a cursor pin with no model
 * emits nothing rather than an `--effort` its CLI rejects.
 *
 * @param {string[]} reviewers - the reviewer slugs the invocation emits
 * @param {Object<string, string>} [reviewerEfforts] - token-keyed effort pins
 * @param {Object} [options]
 * @param {string} [options.reviewWith] - the `--review-with` text this prompt
 *   emits, if any. A `~effort=` in it means slashdo already carries the pin.
 * @param {Object<string, string>} [options.reviewerModels] - token-keyed model
 *   pins, needed only to render a cursor invocation (see above)
 * @returns {string} a single sentence, or '' when nothing is left to say
 */
export function buildReviewerEffortNote(reviewers, reviewerEfforts = {}, { reviewWith = '', reviewerModels = {} } = {}) {
  if (typeof reviewWith === 'string' && reviewWith.includes('~effort=')) return '';
  const efforts = normalizeReviewerEfforts(reviewerEfforts) || {};
  const models = normalizeReviewerModels(reviewerModels) || {};
  const entries = (Array.isArray(reviewers) ? reviewers : [])
    .map((r) => {
      // No binary, nothing to name: `lmstudio`/`ollama` reach their backend over
      // HTTP, and copilot/@username aren't commands at all. Checked FIRST so no
      // branch below can render a `null` command into a prompt.
      const binary = reviewerCliBinary(r);
      if (!binary) return null;
      const args = reviewerEffortArgs(r, efforts[r]);
      if (args.length) return `\`${binary} ${args.join(' ')}\``;
      // No effort ARGV, but the reviewer may still carry the level inside
      // --model (cursor). Gated on the effort pin so this stays an effort note:
      // a model-only pin is not this sentence's business.
      if (!normalizeReviewerEffort(efforts[r], r)) return null;
      const model = reviewerModelArg(r, models[r], efforts[r]);
      return model ? `\`${binary} ${reviewerModelFlag(r)} ${model}\`` : null;
    })
    .filter(Boolean);
  if (!entries.length) return '';
  return `Invoke each reviewer CLI at its pinned reasoning effort: ${entries.join(', ')}. Pass the flag yourself when you spawn the reviewer — nothing else in this prompt applies it (a \`~effort=<level>\` suffix in a reviewer list is slashdo's own grammar, which only its \`--review-with\` parses).`;
}

// Examples of slashdo commands that run a review loop and therefore resolve
// `--review-with` from a saved default when the invocation doesn't pin one.
// EXAMPLES, deliberately — the rule is stated over "any `/do:*` that reviews"
// because the real roster is larger and moves with the submodule (`/do:review`,
// `/do:better`, `/do:better-swift`, `/do:depfree`, `/do:release` all read it
// too). A hand-maintained enumeration is the part that rots, and a command
// missing from it would read as exempt.
const REVIEW_LOOP_SLASHDO_EXAMPLES_MD = ['/do:pr', '/do:next', '/do:review', '/do:rpr']
  .map(command => `\`${command}\``).join(', ');

/**
 * The reviewer slug inside an emitted `--review-with` token, without its
 * `[<model>]` / `~<suffix>` decoration — the inverse of `markSuffixes`, which is
 * the only thing that ever builds one. Kept beside its emitter, and pinned to it
 * by a round-trip test, so a grammar change can't silently mis-slug here.
 */
export const reviewerTokenSlug = (token) => String(token).split('[')[0].split('~')[0].trim().toLowerCase();

/**
 * Partition emitted `--review-with` tokens into the ones slashdo can parse and
 * the ones PortOS serves itself.
 *
 * slashdo's parser ABORTS the whole command on an unknown `--review-with` value,
 * so a PORTOS_ONLY_REVIEWERS slug in that flag doesn't degrade the run — it kills
 * it, and the PR the invocation existed to open never gets created. Every emitter
 * of that flag therefore drops those slugs and names them separately, alongside
 * the Local Reviewer Procedure that actually runs them.
 *
 * An `@login` entry is always a valid slashdo reviewer. `portosOnly` is reported
 * by BARE slug — the `[<model>]`/`~<suffix>` decoration is slashdo grammar, and
 * these reviewers never reach a slashdo parser.
 *
 * @param {string[]} tokens - emitted reviewer tokens (decorated or bare)
 * @returns {{flagTokens: string[], portosOnly: string[]}}
 */
export function splitSlashdoReviewerTokens(tokens) {
  const trimmed = (Array.isArray(tokens) ? tokens : []).map(t => String(t).trim()).filter(Boolean);
  const isSlashdoToken = t => t.startsWith('@') || (!PORTOS_ONLY_REVIEWERS.includes(reviewerTokenSlug(t)) && !isProviderReviewer(reviewerTokenSlug(t)));
  return {
    flagTokens: trimmed.filter(isSlashdoToken),
    portosOnly: [...new Set(trimmed.filter(t => !isSlashdoToken(t)).map(reviewerTokenSlug))],
  };
}

/**
 * Prose block pinning a claim prompt's reviewer list against slashdo's SAVED
 * defaults.
 *
 * The claim flows hand-run their reviewers, so the prompt names the list and
 * emits no flag. But the claim agent is usually a Claude Code session with
 * slashdo installed, and reaching for `/do:pr` mid-flow is a short step from
 * the phase text — at which point slashdo resolves `--review-with` from the
 * host's saved defaults (`.slashdo.json` at the repo root, or the host CLI's
 * `.slashdo-config.json`), i.e. some OTHER user-level reviewer set, plus
 * whatever `merge` default rides with it. That silently replaces the reviewers
 * PortOS resolved for this run. So state the pin once, in the prompt, with the
 * exact token list to pass.
 *
 * `reviewersCsv` must be the text `buildReviewersCsv` emits — the same
 * `<agent>[<model>]~opt~max=<n>~effort=<level>` grammar `--review-with` parses —
 * so the agent can paste it verbatim.
 *
 * Unlike `buildReviewWithArgs` this does NOT suppress a lone bare `copilot`
 * (the #2507 stall): every claim path resolves its list through
 * `claimSafeReviewers`, which strips `copilot` and falls back to `codex`,
 * so the suppressed case cannot reach here. A future caller that skips that
 * normalizer has to add the guard rather than assume it.
 *
 * @param {string} reviewersCsv - the emitted reviewer token list
 * @returns {string} a Markdown block, or '' when there is no list to pin
 */
export function buildReviewerPinNote(reviewersCsv) {
  const csv = typeof reviewersCsv === 'string' ? reviewersCsv.trim() : '';
  if (!csv) return '';
  // A `@login` entry is always a valid slashdo reviewer; a keyed one is valid
  // unless PortOS serves it itself. Emitting a PORTOS_ONLY_REVIEWERS slug in a
  // `--review-with` list would abort the command outright, so it is dropped from
  // the flag text and named separately with the procedure that DOES run it.
  const { flagTokens, portosOnly } = splitSlashdoReviewerTokens(csv.split(','));

  return [
    '## Reviewer pin — use the reviewers PortOS configured',
    `PortOS resolved this run's reviewers from its own configuration: \`${csv}\`. That list is authoritative for every review in this run — it is the same list the phases above name. Never substitute a different reviewer set for it.`,
    flagTokens.length
      && `**A saved slashdo default must never stand in for it.** If you invoke ANY slashdo \`/do:*\` command that runs a review loop (${REVIEW_LOOP_SLASHDO_EXAMPLES_MD}, and others), pass \`--review-with ${flagTokens.join(',')}\` explicitly. A bare invocation resolves \`--review-with\` from the host's saved defaults instead — \`.slashdo.json\` at the repo root, or the host CLI's \`.slashdo-config.json\` — which name a different reviewer set and can carry an auto-merge default this run never asked for.`,
    flagTokens.length
      && 'Pass those tokens exactly as written: their `[<model>]`, `~opt`, `~max=<n>`, and `~effort=<level>` suffixes are slashdo grammar and already carry each reviewer\'s pinned model, optional/blocking status, round cap, and reasoning effort — so do not also apply those by hand on that path.',
    portosOnly.length
      && `PortOS runs \`${portosOnly.join('`, `')}\` itself — no slashdo slug, so never a \`--review-with\` value. That review happens through the Local Reviewer Procedure below, and leaving it out of a slashdo invocation is not permission to skip it.`,
  ].filter(Boolean).join('\n\n');
}

/**
 * Build the set of lowercased optional-reviewer tokens for a fast membership
 * test in the builders. Tolerates the raw (unnormalized) list.
 */
function optionalReviewerSet(optionalReviewers) {
  return new Set((normalizeOptionalReviewers(optionalReviewers) || []).map(t => t.toLowerCase()));
}

/**
 * Build a lowercased-token → cap lookup for the builders. Tolerates the raw
 * (unnormalized) map. A `Map` (not a plain object) so a reviewer token can never
 * collide with `Object.prototype` keys, and so `.get()` distinguishes an absent
 * cap (`undefined`) from an explicit `0`.
 */
function reviewerMaxRoundsLookup(reviewerMaxRounds) {
  const normalized = normalizeReviewerMaxRounds(reviewerMaxRounds) || {};
  return new Map(Object.entries(normalized).map(([token, max]) => [token.toLowerCase(), max]));
}

/**
 * Build a lowercased-token → model-id lookup for the builders. Tolerates the raw
 * (unnormalized) map. A `Map` for the same reasons as the cap lookup.
 */
function reviewerModelLookup(reviewerModels) {
  const normalized = normalizeReviewerModels(reviewerModels) || {};
  return new Map(Object.entries(normalized).map(([token, model]) => [token.toLowerCase(), model]));
}

/**
 * Build a lowercased-token → effort-level lookup for the builders. Tolerates the raw
 * (unnormalized) map. A `Map` for the same reasons as the cap and model lookups.
 */
function reviewerEffortLookup(reviewerEfforts) {
  const normalized = normalizeReviewerEfforts(reviewerEfforts) || {};
  return new Map(Object.entries(normalized).map(([token, effort]) => [token.toLowerCase(), effort]));
}

/**
 * Render one emitted `--review-with` entry: the reviewer token, its optional
 * `[<model>]` selector, then slashdo's per-entry suffixes in canonical storage
 * order — `~opt`, `~max=<n>`, then `~effort=<level>`.
 *
 * Order matters. slashdo's grammar is
 * `entry := ( <agent> [ "[" <model> "]" ] | "@" <login> ) ( "~opt" | "~max=" <n> | "~effort=" <level> )*`
 * and its parser strips the `~` suffixes from the RIGHT before reading the
 * bracket — so the bracket has to sit between the slug and the suffixes.
 *
 * A reviewer with no pinned model emits no bracket, which is what leaves that
 * reviewer's own default in place; likewise a reviewer with no cap emits no
 * `~max` at all (`~max=0` is a real, distinct value meaning "loop until clean"), and
 * a reviewer with no effort level emits no `~effort`.
 * Only BRACKET_MODEL_REVIEWERS get a bracket — `copilot`/`@login` reject one, and
 * PortOS's `lmstudio` reviewer has no slashdo slug at all (its model rides in the
 * `POST /api/code-review/local` body instead).
 */
function markSuffixes(token, optSet, maxLookup, modelLookup, effortLookup) {
  const key = token.toLowerCase();
  const max = maxLookup?.get(key);
  const model = BRACKET_MODEL_REVIEWERS.includes(key) ? modelLookup?.get(key) : undefined;
  const effort = effortLookup?.get(key);
  return `${token}${model ? `[${model}]` : ''}${optSet.has(key) ? '~opt' : ''}${max === undefined ? '' : `~max=${max}`}${effort ? `~effort=${effort}` : ''}`;
}

/**
 * Resolve task metadata to an ordered, deduped reviewer list. Prefers the new
 * `reviewers` array; falls back to the legacy single `reviewer` string. When
 * the metadata yields nothing, returns `fallback` (empty by default) — pass the
 * settings-resolved defaults here so a Review Loop run picks up the user's Code
 * Review Defaults when the task itself didn't pin reviewers. Filters to known
 * reviewers and preserves first-occurrence order.
 */
export function normalizeReviewers(meta, fallback = DEFAULT_REVIEWERS) {
  const raw = meta && typeof meta === 'object' && !Array.isArray(meta) ? meta : {};
  const source = Array.isArray(raw.reviewers)
    ? raw.reviewers
    : (typeof raw.reviewer === 'string' && raw.reviewer ? [raw.reviewer] : []);
  const out = normalizeReviewerList(source);
  if (out.length) return out;
  const fallbackList = normalizeReviewerList(fallback);
  return fallbackList.length ? [...fallbackList] : [...DEFAULT_REVIEWERS];
}

/**
 * True when the winning layer explicitly lists NO keyed (AI/CLI) reviewers and
 * forge reviewers (`@login`) remain: the user chose "review by these people or
 * bots only", which must not fall back to the install default chain.
 */
function usernameOnlyRoster(metadata, codeReviewDefaults) {
  if (!resolveReviewUsernames(metadata?.usernames, codeReviewDefaults?.usernames).length) return false;
  if (!Array.isArray(metadata?.reviewers) && typeof metadata?.reviewer === 'string' && metadata.reviewer) return false;
  const explicitEmpty = (layer) => Array.isArray(layer?.reviewers) && layer.reviewers.length === 0;
  return Array.isArray(metadata?.reviewers) ? explicitEmpty(metadata) : explicitEmpty(codeReviewDefaults);
}

/**
 * Resolve an explicit task reviewer list as its preferred tier, followed by
 * the system Code Review Defaults tiers. This lets scheduled task overrides
 * retain their choice while inheriting a configured default when that tier is
 * paused. Tasks without a reviewer-list override keep the existing resolved
 * default selection.
 */
export function resolveReviewerGroup(metadata, codeReviewDefaults, defaultReviewers, normalize = normalizeReviewers) {
  const raw = metadata && typeof metadata === 'object' && !Array.isArray(metadata) ? metadata : {};
  const source = Array.isArray(raw.reviewers)
    ? raw.reviewers
    : (typeof raw.reviewer === 'string' && raw.reviewer ? [raw.reviewer] : []);
  const taskGroup = normalizeReviewerList(source);
  if (usernameOnlyRoster(raw, codeReviewDefaults)) return [];
  if (!taskGroup.length) {
    return prioritizeToolFreeReviewers(normalize(metadata, defaultReviewers));
  }

  const configuredGroups = Array.isArray(codeReviewDefaults?.reviewerFallbackGroups)
    ? codeReviewDefaults.reviewerFallbackGroups
    : [defaultReviewers ?? codeReviewDefaults?.reviewers];
  const fallbackGroups = configuredGroups
    .map(normalizeReviewerList)
    .filter(group => group.length);
  const groups = [taskGroup, ...fallbackGroups];
  const activeGroup = groups[activeReviewerGroupIndex(groups, codeReviewDefaults?.reviewerHealth)];
  return prioritizeToolFreeReviewers(activeGroup || taskGroup);
}

function normalizeReviewerList(list) {
  const seen = new Set();
  const out = [];
  for (const raw of Array.isArray(list) ? list : []) {
    if (typeof raw !== 'string') continue;
    const normalized = REVIEWER_ALIASES[raw] || raw;
    if (isReviewer(normalized) && !seen.has(normalized)) {
      seen.add(normalized);
      out.push(normalized);
    }
  }
  return out;
}

/**
 * Resolve the keyed (enum) reviewer list, honoring the "username-only" case: an
 * EXPLICITLY empty keyed list with username reviewers present (e.g. copilot was
 * stripped on a non-GitHub forge) stays empty rather than falling back to the
 * install default normalizeReviewers would apply. Absent/legacy input still
 * normalizes to the configured default. Single source for the guard shared by
 * `buildReviewWithArgs` and the review-loop follow-up prompt builder.
 */
export function resolveKeyedReviewers(reviewers, hasUsernames) {
  if (Array.isArray(reviewers) && reviewers.length === 0 && hasUsernames) return [];
  return normalizeReviewers({ reviewers });
}

/**
 * Build the comma-separated reviewer token list used to fill the `{reviewers}`
 * placeholder in claim/plan prompts: keyed reviewers (falling back to the
 * configured default when empty, unless usernames make it a username-only roster) followed by `@user` tokens for the reviewer usernames.
 * Reviewers in `optionalReviewers` get slashdo's `~opt` non-blocking suffix, and
 * reviewers carrying a `reviewerMaxRounds` cap get `~max=<n>` after it. A
 * reviewer with a `reviewerModels` pin gets slashdo's `[<model>]` selector
 * between the slug and those suffixes, and a reviewer with a `reviewerEfforts` pin
 * gets `~effort=<level>`.
 * The flag-string variant is `buildReviewWithArgs`.
 */
export function buildReviewersCsv(reviewers, usernames = [], optionalReviewers = [], reviewerMaxRounds = {}, reviewerModels = {}, reviewerEfforts = {}) {
  const users = normalizeReviewUsernames(usernames);
  const keyed = Array.isArray(reviewers) && reviewers.length ? reviewers : (users.length ? [] : [...DEFAULT_REVIEWERS]);
  const optSet = optionalReviewerSet(optionalReviewers);
  const maxLookup = reviewerMaxRoundsLookup(reviewerMaxRounds);
  const modelLookup = reviewerModelLookup(reviewerModels);
  const effortLookup = reviewerEffortLookup(reviewerEfforts);
  const combined = [...keyed, ...users.map(u => `@${u}`)];
  return combined.map(t => markSuffixes(t, optSet, maxLookup, modelLookup, effortLookup)).join(',');
}

/**
 * Build the slashdo review flag string for an ordered reviewer list plus any
 * arbitrary GitHub reviewer usernames.
 * - `--review-with a,b,@user` only when the effective list isn't the lone default
 *   copilot (any username, or any non-default keyed reviewer, forces it on).
 *   Usernames are appended as `@user` tokens after the keyed reviewers.
 * - `--review-stop-on-*` only when the effective list is 2+ (stop-mode is
 *   meaningless for one).
 * - `--reviewer-applies` only when an `APPLY_CAPABLE_REVIEWERS` slug (`codex`) is
 *   in the emitted list. slashdo's loop forces every OTHER local reviewer
 *   (`claude`/`agy`/`grok`/`pi`/`cursor`/`opencode`) back to review-only — codex
 *   is the one with a verified write-isolated profile — and the flag is a no-op on
 *   `copilot`/`@login` (cloud, read-only) and `ollama` (non-agentic). Emitting it
 *   for a list with no codex would promise an editing pass slashdo will not run,
 *   so it is dropped and the rendered command says what will actually happen.
 * - Reviewers in `optionalReviewers` get slashdo's `~opt` non-blocking suffix on
 *   their emitted token, so an inconclusive verdict from them doesn't gate the
 *   merge. Reviewers with a `reviewerMaxRounds` cap get `~max=<n>` after it,
 *   a reviewer with a `reviewerModels` pin gets a `[<model>]` selector before both,
 *   and a reviewer with a `reviewerEfforts` pin gets `~effort=<level>`.
 *   A lone default `copilot` that is marked optional, carries a cap, or carries an
 *   effort DOES force the flag on (otherwise the suffix — the whole point — would be
 *   dropped with the flag).
 *
 * - A `PORTOS_ONLY_REVIEWERS` slug (`lmstudio`/`mtplx`/`kilo`/`kimi`) is
 *   DROPPED from the emitted list: slashdo aborts on an unknown `--review-with`
 *   value, so emitting one would kill the whole invocation rather than degrade
 *   it. With nothing left to name, no flag is emitted at all.
 *
 * Everything past `reviewers` is an options object: the two reviewer-name lists
 * (`usernames` / `optionalReviewers`) and the three per-reviewer lookup maps
 * (`reviewerMaxRounds` / `reviewerModels` / `reviewerEfforts`) are same-shaped.
 *
 * @param {string[]} reviewers - ordered keyed reviewer slugs
 * @param {Object} [options]
 * @param {string} [options.stopMode] - review stop mode (`all` / `on-findings` / `on-clean`)
 * @param {boolean} [options.reviewerApplies] - emit `--reviewer-applies`
 * @param {string[]} [options.usernames] - GitHub reviewer usernames (emitted as `@user`)
 * @param {string[]} [options.optionalReviewers] - reviewers that get the `~opt` suffix
 * @param {Object<string, number>} [options.reviewerMaxRounds] - per-reviewer `~max=<n>` caps
 * @param {Object<string, string>} [options.reviewerModels] - per-reviewer `[<model>]` pins
 * @param {Object<string, string>} [options.reviewerEfforts] - per-reviewer `~effort=<level>` pins
 * @returns {string} the slashdo review flag string (possibly empty)
 */
export function buildReviewWithArgs(reviewers, {
  stopMode = DEFAULT_REVIEW_STOP_MODE,
  reviewerApplies = false,
  usernames = [],
  optionalReviewers = [],
  reviewerMaxRounds = {},
  reviewerModels = {},
  reviewerEfforts = {},
} = {}) {
  const users = normalizeReviewUsernames(usernames);
  const keyed = resolveKeyedReviewers(reviewers, users.length > 0);
  const configured = [...keyed, ...users.map(u => `@${u}`)];
  // PortOS-only reviewers are dropped rather than emitted — see the doc comment
  // above and `splitSlashdoReviewerTokens`. The surrounding prompt still names the
  // full reviewer list and the Local Reviewer Procedure that runs them.
  const combined = splitSlashdoReviewerTokens(configured).flagTokens;
  const optSet = optionalReviewerSet(optionalReviewers);
  const maxLookup = reviewerMaxRoundsLookup(reviewerMaxRounds);
  const modelLookup = reviewerModelLookup(reviewerModels);
  const effortLookup = reviewerEffortLookup(reviewerEfforts);
  // The lone-default-copilot suppression only applies when copilot carries NO
  // per-entry suffix — a `copilot~opt` / `copilot~max=2` / `copilot~effort=high` list must still
  // emit the flag to carry that suffix.
  //
  // Measured against the CONFIGURED list, not the emitted one. Suppressing the
  // flag hands `--review-with` to the host's saved slashdo defaults, which name
  // some other reviewer set — right for a run that asked for nothing but the
  // default copilot, wrong for `[lmstudio, copilot]`, where the user chose this
  // pair and only lmstudio's slug is unemittable. Reading the filtered list here
  // would silently swap copilot out for whatever `.slashdo.json` happens to say.
  const isDefaultOnly = configured.length === 1 && configured[0] === DEFAULT_REVIEWER
    && !optSet.has(DEFAULT_REVIEWER) && maxLookup.get(DEFAULT_REVIEWER) === undefined
    && effortLookup.get(DEFAULT_REVIEWER) === undefined;
  // Keyed by resolved SLUG, like every other per-reviewer lookup in this function,
  // so a bracketed or suffixed token cannot slip past the comparison.
  const hasApplyCapableReviewer = combined.some(t => isApplyCapableReviewer(reviewerTokenSlug(t)));
  const parts = [];
  // Nothing slashdo can parse (a list of PortOS-only reviewers): emit no flag at
  // all rather than a bare `--review-with`.
  if (!isDefaultOnly && combined.length) parts.push(`--review-with ${combined.map(t => markSuffixes(t, optSet, maxLookup, modelLookup, effortLookup)).join(',')}`);
  if (combined.length >= 2) {
    if (stopMode === 'on-findings') parts.push('--review-stop-on-findings');
    else if (stopMode === 'on-clean') parts.push('--review-stop-on-clean');
  }
  if (reviewerApplies && hasApplyCapableReviewer) parts.push('--reviewer-applies');
  return parts.join(' ');
}