syncstaff-mcp 0.2.3

package/dist/lib/index/vector-cache.js

@@ -0,0 +1,176 @@
+import { createHash } from "node:crypto";
+import { distillBody, EMBEDDED_BODY_CHARS } from "./pages.js";
+const instances = new Set();
+const anonymousEmbedderIds = new WeakMap();
+let nextAnonymousEmbedderId = 1;
+/**
+ * Return a stable identity for one embedder instance.
+ *
+ * Providers may expose an id/model, but custom test and application
+ * embedders often do not. In that case identity is deliberately scoped to the
+ * object instance: reusing vectors across two unknown implementations would
+ * be less safe than doing a second embedding pass.
+ */
+export function embedderIdentity(embedder) {
+    const candidate = embedder;
+    if (typeof candidate.id === "string" && candidate.id)
+        return candidate.id;
+    if (typeof candidate.provider === "string" && typeof candidate.model === "string") {
+        return `${candidate.provider}:${candidate.model}:${candidate.dimensions}`;
+    }
+    const object = embedder;
+    let id = anonymousEmbedderIds.get(object);
+    if (!id) {
+        id = `anonymous-${nextAnonymousEmbedderId++}`;
+        anonymousEmbedderIds.set(object, id);
+    }
+    return `${id}:${embedder.dimensions}`;
+}
+/**
+ * Opt into the Repowise-shaped document representation for experiments.
+ *
+ * The default stays unchanged so a candidate representation cannot silently
+ * alter production retrieval or invalidate a deployed vector cache. The
+ * benchmark process can enable this per run and the document hash naturally
+ * keeps the representations in separate cache entries. `facts` is the
+ * narrower candidate; `1` additionally includes the bounded vocabulary.
+ */
+const vectorDocumentFactsMode = () => process.env.KEEL_VECTOR_DOCUMENT_FACTS ?? "";
+/**
+ * The exact text sent to the embedder for one page.
+ *
+ * Exported so the vector leg and this cache cannot disagree about it: the
+ * cache key is derived from this string, so any drift between the two would
+ * silently serve vectors of text that was never embedded.
+ *
+ * `summary` alone is close to a constant — "X is a typescript file with 3
+ * exports and 5 imports" — so embedding title-plus-summary produced vectors
+ * that differed only by path, and the vector leg was ranking on filenames
+ * while appearing to do semantic search. The body prefix is what gives the
+ * embedding actual subject matter.
+ *
+ * The prefix is bounded because sentence embedders truncate hard (BGE-small
+ * at 512 tokens); sending a whole file would silently discard most of it and
+ * cost the encode anyway.
+ */
+export const documentText = (page) => {
+    const factsMode = vectorDocumentFactsMode();
+    const structuralFacts = factsMode === "facts" || factsMode === "1" ? page.content.trim() : "";
+    const vocabulary = factsMode === "1" ? page.lexical_vocabulary?.trim() ?? "" : "";
+    return [
+        page.title,
+        page.summary,
+        structuralFacts,
+        vocabulary,
+        distillBody(page.body ?? "").slice(0, EMBEDDED_BODY_CHARS),
+    ].filter(Boolean).join(" ").trimEnd();
+};
+/** The identity of the text sent to the embedder, independent of source bytes. */
+export function documentSummaryHash(page) {
+    return createHash("sha256").update(documentText(page)).digest("hex");
+}
+function cacheKey(page, embedder) {
+    return `${embedderIdentity(embedder)}\0${documentSummaryHash(page)}`;
+}
+/**
+ * Cache document vectors by retrieval-summary identity and embedder identity.
+ *
+ * The page source hash is intentionally absent. Editing a function body can
+ * change the parser/index fingerprint without changing the bounded summary
+ * that the vector leg embeds; reusing that vector is safe and avoids paying
+ * the model again. `page_id` remains the natural key in the returned lookup.
+ *
+ * The promise is cached while work is in flight as well as after it resolves,
+ * so concurrent queries cannot start duplicate model calls. Failed work is
+ * removed and may be retried after the provider recovers.
+ */
+export class VectorCache {
+    entries = new Map();
+    store;
+    constructor(store) {
+        this.store = store ?? null;
+        instances.add(this);
+    }
+    async documentVectors(_fingerprint, pages, embedder) {
+        const embedDocument = embedder.embedDocument ?? embedder.embed;
+        const vectors = await Promise.all(pages.map(async (page) => [
+            page.page_id,
+            await this.documentVector(page, embedder, embedDocument),
+        ]));
+        return new Map(vectors);
+    }
+    async documentVector(page, embedder, embedDocument) {
+        const key = cacheKey(page, embedder);
+        const existing = this.entries.get(key);
+        if (existing)
+            return existing.promise;
+        let persisted = null;
+        try {
+            persisted = this.store?.getVector(key) ?? null;
+        }
+        catch {
+            // Persistence is an optimization. A locked or corrupt cache must not
+            // make a local retrieval answer unavailable.
+        }
+        const promise = persisted
+            ? Promise.resolve(persisted)
+            : embedDocument.call(embedder, documentText(page)).then((vector) => {
+                try {
+                    this.store?.putVector(key, vector);
+                }
+                catch {
+                    // Keep the freshly computed vector usable when the cache is unwritable.
+                }
+                return vector;
+            });
+        const entry = { key, promise };
+        this.entries.set(key, entry);
+        try {
+            return await promise;
+        }
+        catch (error) {
+            if (this.entries.get(key) === entry)
+                this.entries.delete(key);
+            throw error;
+        }
+    }
+    /**
+     * Kept for incremental-index callers for API compatibility.
+     *
+     * Fingerprints no longer identify vector inputs: summary hashes do. A
+     * fingerprint change therefore must not evict vectors whose summaries are
+     * unchanged; `clear()` remains available when a caller is disposing a whole
+     * cache or changing provider policy.
+     */
+    invalidateFingerprint(_fingerprint) {
+        // Deliberately empty; summary-hash identity makes this invalidation too broad.
+    }
+    /** Drop all entries, useful when a caller releases a local index. */
+    clear() {
+        this.entries.clear();
+    }
+    /** Number of fingerprints/embedder pairs currently retained. */
+    get size() {
+        return this.entries.size;
+    }
+    /** Remove this cache from the process-wide invalidation registry. */
+    dispose() {
+        this.clear();
+        instances.delete(this);
+    }
+}
+/** The default cache for retrieval callers that do not need a private one. */
+export const defaultVectorCache = new VectorCache();
+/**
+ * Retain the incremental-index hook without invalidating summary-stable vectors.
+ *
+ * Incremental indexing calls this hook because the cache is derived from the
+ * index, just like the graph and retrieval pages. Keeping it process-wide
+ * lets callers use private caches without making the indexer know their
+ * ownership, while `dispose()` prevents abandoned clients from retaining
+ * entries forever.
+ */
+export function invalidateVectorCache(fingerprint) {
+    for (const cache of instances)
+        cache.invalidateFingerprint(fingerprint);
+}

package/dist/lib/index/verification.js

@@ -0,0 +1,58 @@
+import { buildCheckerCallGraph, callersOf, loadCheckerProgram } from "./checker-resolver.js";
+import { byCodeUnit } from "./order.js";
+/**
+ * Verify candidate call sites; never discard an unverified candidate.
+ *
+ * ATTRIBUTION. `callersOf` answers "who calls this symbol", filtering on the
+ * symbol and its declaring file and nothing else. Asking it once per candidate
+ * and promoting on a non-empty result therefore promotes *every* candidate
+ * whenever the symbol has any caller anywhere in the repository: the answer
+ * never reads `candidate.path`, so a file with no connection to the symbol is
+ * promoted on the strength of some other file's call, and then carries that
+ * other file's call sites as its own "evidence". That is the sham this phase
+ * was written against — a verification claim that cannot fail — and it was
+ * invisible because the tests only ever exercised the degraded paths, where
+ * no candidate is promoted at all.
+ *
+ * The edge already names its own origin, so the fix is to read it: a candidate
+ * is promoted only on an edge whose `from` is that candidate.
+ *
+ * NO EDGE, NO CLAIM. A promoted candidate always carries at least one call
+ * site (R9.2). A file that declares the implicated symbol but has no callers
+ * stays unverified rather than being promoted on an empty evidence list — the
+ * checker learned nothing there that the symbol index had not already said,
+ * and claiming verification with nothing to show is the failure R9.3 calls
+ * worse than no verification at all.
+ */
+export async function verifyCandidates(root, candidates, options = {}) {
+    const started = Date.now();
+    const budget = options.budgetMs ?? 5000;
+    const unavailable = (reason) => ({
+        candidates: candidates.map((candidate) => ({ ...candidate, verified: false, evidence: [], verification: reason })),
+        verified: false,
+        caveat: reason === "budget_exceeded" ? `checker exceeded ${budget}ms budget` : "no TypeScript project available; candidates remain unverified",
+        elapsed_ms: Date.now() - started,
+    });
+    const backend = await loadCheckerProgram(root);
+    if (!backend)
+        return unavailable("unavailable");
+    const graph = buildCheckerCallGraph(backend.ts, root, backend.configs);
+    if (Date.now() - started > budget)
+        return unavailable("budget_exceeded");
+    const verified = candidates.map((candidate) => {
+        const incoming = callersOf(graph, candidate.symbol, candidate.declared_in);
+        const references = incoming.filter((edge) => edge.from === candidate.path);
+        if (references.length > 0) {
+            return { ...candidate, verified: true, evidence: references, verification: "checker", relation: "references" };
+        }
+        // A file is never among its own callers, so the declaring file can only be
+        // promoted here. Its evidence is the incoming calls that make the
+        // declaration worth editing; with none, it stays unverified.
+        if (candidate.path === candidate.declared_in && incoming.length > 0) {
+            return { ...candidate, verified: true, evidence: incoming, verification: "checker", relation: "declares" };
+        }
+        return { ...candidate, verified: false, evidence: [], verification: "checker" };
+    });
+    verified.sort((a, b) => Number(b.verified) - Number(a.verified) || (b.score ?? 0) - (a.score ?? 0) || byCodeUnit(a.path, b.path));
+    return { candidates: verified, verified: true, caveat: null, elapsed_ms: Date.now() - started };
+}

package/dist/lib/mcp-compaction.js

@@ -0,0 +1,241 @@
+/**
+ * Shrinking tool responses before they reach a model.
+ *
+ * Every function here is pure, and that is the point: the MCP adapter is a
+ * process that connects on import, so nothing inside it can be unit tested.
+ * These were measured against 40 sessions of real transcripts — 960,307
+ * response tokens across 1,837 keel tool calls, against roughly 6,000 tokens
+ * per session of static tool schemas and protocol instructions. Responses
+ * outweigh definitions about four to one, so this is where the budget is.
+ *
+ * The rule they share: a response should carry what the caller does not
+ * already have. Echoing back a body the caller just sent, or a path list
+ * printed twice in one payload, costs a model's context and tells it nothing.
+ */
+/**
+ * Elide the arbiter's prose on a verdict that asks nothing of the reader.
+ *
+ * The arbiter is an LLM and writes like one: a multi-paragraph argument on
+ * every declaration. Measured across 234 declarations, 213 of them — 91% —
+ * came back `clear`, and those carried 69,496 tokens of reasoning that changed
+ * nothing, because the only action a clear verdict permits is the one the
+ * agent already intended. The 21 non-clear verdicts carried 9,075 tokens that
+ * an agent must act on, and those are kept in full.
+ *
+ * This is the one trim here that is conditional rather than structural, and
+ * deliberately so: the rule is "drop what cannot change the reader's next
+ * move", and on a conflict or an escalation the reasoning is precisely what
+ * does change it.
+ */
+function compactArbiter(arbiter) {
+    if (!arbiter || typeof arbiter !== "object")
+        return arbiter;
+    if (arbiter.verdict !== "clear")
+        return arbiter;
+    const { reasoning, suggested_options, ...rest } = arbiter;
+    return {
+        ...rest,
+        ...(reasoning === undefined
+            ? {}
+            : { reasoning: "elided on a clear verdict — intent_get(intent_id) returns it in full" }),
+    };
+}
+/**
+ * Strip the historical argument from a charter, keeping every binding word.
+ *
+ * An invariant's `text` binds and is returned intact. Its `rationale` is the
+ * case that was made for it when it was ratified — written for the human
+ * weighing an amendment, not for the agent obeying the rule — and across
+ * measured sessions the rationales came to 11,268 tokens against 7,255 for the
+ * invariant texts themselves. An agent that needs the argument is proposing an
+ * amendment, which is a human-facing path with the full record attached.
+ */
+export function compactCharter(response) {
+    const charter = response?.charter;
+    if (!charter || !Array.isArray(charter.invariants))
+        return response;
+    let elided = false;
+    const invariants = charter.invariants.map((inv) => {
+        if (!inv || typeof inv !== "object" || inv.rationale == null)
+            return inv;
+        const { rationale, ...rest } = inv;
+        elided = true;
+        return rest;
+    });
+    return {
+        ...response,
+        charter: {
+            ...charter,
+            invariants,
+            ...(elided
+                ? { rationales: "elided — every invariant text is intact; ratification rationales are on the board and in the amendment record" }
+                : {}),
+        },
+    };
+}
+/**
+ * Compact one intent for a listing.
+ *
+ * A call site report is the declaring client's own analysis: every place a
+ * changed symbol is used, with the source line quoted at each. It is the right
+ * thing to send up — the server cannot compute it without reading code, which
+ * the charter forbids — and the wrong thing to send back. Measured 29 Aug, two
+ * active intents carried 87 quoted call sites and made intent_list_active the
+ * largest single response of the session, most of it returned to the very agent
+ * that produced it.
+ *
+ * A reader of this list is deciding one thing: whether to stay away. That needs
+ * the file set and how much of it is guesswork, not the source. `intent_get`
+ * serves the full report to anyone who wants it.
+ */
+export function compactIntent(intent) {
+    if (!intent || typeof intent !== "object")
+        return intent;
+    const interfaces = Array.isArray(intent.interfaces_touched)
+        ? intent.interfaces_touched.map((touched) => {
+            const report = touched?.call_site_report;
+            if (!report || !Array.isArray(report.call_sites))
+                return touched;
+            const sites = report.call_sites;
+            return {
+                ...touched,
+                call_site_report: {
+                    analyzer: report.analyzer,
+                    status: report.status,
+                    truncated: report.truncated,
+                    call_sites_total: sites.length,
+                    call_sites_unconfirmed: sites.filter((s) => s?.confidence === "unconfirmed").length,
+                    paths: [...new Set(sites.map((s) => s?.path).filter(Boolean))].sort(),
+                    detail: "call sites elided — intent_get(intent_id) returns them in full",
+                },
+            };
+        })
+        : intent.interfaces_touched;
+    // A listing flattens the arbiter to a bare `arbiter_reasoning` string, so the
+    // same 91%-of-verdicts-are-clear argument applies here in a different shape.
+    const reasoningElided = typeof intent.arbiter_reasoning === "string" && intent.verdict === "clear"
+        ? { arbiter_reasoning: "elided on a clear verdict — intent_get(intent_id) returns it in full" }
+        : {};
+    return { ...intent, interfaces_touched: interfaces, ...reasoningElided };
+}
+/**
+ * Compact a declaration response.
+ *
+ * `overlaps` is a list of other agents' intents, each carrying the same call
+ * site reports `compactIntent` exists to elide — in the largest declaration
+ * measured it was 7,993 of 14,098 characters, 57% of the payload. The reader
+ * of an overlap is deciding whether to stay away, which is the exact decision
+ * compactIntent was written for; it was simply never wired to this path.
+ */
+export function compactDeclaration(declared) {
+    if (!declared || typeof declared !== "object")
+        return declared;
+    return {
+        ...declared,
+        ...(declared.arbiter ? { arbiter: compactArbiter(declared.arbiter) } : {}),
+        ...(Array.isArray(declared.overlaps)
+            ? { overlaps: declared.overlaps.map(compactIntent) }
+            : {}),
+    };
+}
+/**
+ * Drop the blast radius file list from a lease grant.
+ *
+ * `POST /leases` returns `secondary_paths` — the files the radius widened the
+ * lease onto — and then returns the identical list again inside
+ * `blast_radius.files_added_to_lease`. One response, the same 29 paths twice.
+ * The count is kept so the summary still reconciles with the array above it.
+ */
+export function compactLeaseGrant(grant) {
+    if (!grant || typeof grant !== "object")
+        return grant;
+    const radius = grant.blast_radius;
+    if (!radius || typeof radius !== "object" || !Array.isArray(radius.files_added_to_lease)) {
+        return grant;
+    }
+    const { files_added_to_lease, ...rest } = radius;
+    return {
+        ...grant,
+        blast_radius: { ...rest, files_added_to_lease_count: files_added_to_lease.length },
+    };
+}
+/**
+ * What a board write returns.
+ *
+ * board_create and board_update used to return the stored row, which meant a
+ * caller that sent a two-field patch received the whole markdown body back —
+ * measured at 3,769 chars average for patches under 300 chars, and 252k tokens
+ * across 40 sessions, almost all of it text the caller either just sent or
+ * already had.
+ *
+ * `version` is the field that has to come back: it is the `expected_version`
+ * of the caller's next update. `status` confirms the transition actually
+ * applied, which is the other thing a writer checks. Anyone who wants the
+ * stored row can board_get it.
+ */
+export function boardWriteReceipt(item) {
+    if (!item || typeof item !== "object")
+        return item;
+    const { id, version, status, detail } = item;
+    return {
+        id,
+        version,
+        status,
+        ...(typeof detail === "string" ? { detail_chars: detail.length } : {}),
+    };
+}
+/**
+ * Fields every board row carries that no reader of a listing uses.
+ *
+ * `etag`, `version` and `position` belong to the update path, and board_get is
+ * already documented as where you obtain an etag before board_update — so a
+ * listing that omits it cannot mislead anyone into a stale write. `project_id`
+ * and `team_id` repeat the project on every row of a single-project listing.
+ * `detail_truncated` restates what detail_chars already says.
+ *
+ * `created_at` and `created_by` joined them after measurement: a listing is
+ * read to decide what to work on next, and neither when a row was written nor
+ * the ULID of the agent that wrote it moves that decision. `updated_at` stays
+ * because staleness does. `claimed_by` stays because it signals contention.
+ */
+export const BOARD_ROW_NOISE = [
+    "project_id",
+    "team_id",
+    "etag",
+    "version",
+    "position",
+    "detail_truncated",
+    "created_at",
+    "created_by",
+    "claimed_at",
+];
+/**
+ * How much of a body a listing row previews.
+ *
+ * The server sends 200 characters, and that stays the HTTP contract — the web
+ * dashboard renders from it. Measured over real listings that excerpt was the
+ * single largest field at 32% of row content, and most of it is preamble:
+ * findings on this board open "Found <date> ... **Resolved <date>**" before
+ * they say anything that distinguishes one row from another. 120 characters
+ * clears the preamble and keeps the affordance; `detail_chars` still tells the
+ * caller what a board_get would cost.
+ */
+export const BOARD_EXCERPT_CHARS = 120;
+/** Drop the scaffolding, and drop keys that are simply absent. */
+export function compactBoardItem(item) {
+    if (!item || typeof item !== "object")
+        return item;
+    const out = {};
+    for (const [key, value] of Object.entries(item)) {
+        if (BOARD_ROW_NOISE.includes(key))
+            continue;
+        if (value === null)
+            continue;
+        if (key === "detail_excerpt" && typeof value === "string") {
+            out[key] = value.slice(0, BOARD_EXCERPT_CHARS);
+            continue;
+        }
+        out[key] = value;
+    }
+    return out;
+}

package/dist/lib/model-roles.js

@@ -0,0 +1,206 @@
+/**
+ * Model roles: which assistant does what, and which model does it.
+ *
+ * Before this, four separate decisions picked four models in four different
+ * ways — a hardcoded string in the chat agent (in two call sites), a project
+ * setting for the intent arbiter, an environment variable for the chief of
+ * staff's judgment, and a constant nobody had wired. Changing one told you
+ * nothing about the others, and nothing anywhere listed what the system was
+ * actually paying for.
+ *
+ * This makes the roles first-class. Each is a named job with a description, a
+ * default, and one place to change it. Plug any model into any role; the server
+ * resolves the assignment and the callers ask for a role rather than a model.
+ *
+ * Two things this deliberately is not:
+ *
+ * - **Not a provider catalogue.** Providers are `anthropic` or
+ *   `openai_compatible`, because the wire format is the only thing that
+ *   actually differs. A list of vendor names would need a release per vendor.
+ * - **Not a secret store.** An assignment names the environment variable that
+ *   holds a key, never the key. Assignments are returned by the settings API
+ *   and rendered in the dashboard, so they must be safe to show.
+ */
+export const MODEL_ROLES = ["chat", "arbiter", "cos_judge"];
+/**
+ * The roles, and why each is defaulted the way it is.
+ *
+ * The defaults are not uniform on purpose: cost matters where a role runs on
+ * every request, and judgment matters where its output is durable.
+ */
+export const ROLE_CATALOG = {
+    chat: {
+        role: "chat",
+        title: "Chief of staff — chat",
+        description: "Answers questions about the project in the dashboard's Ask panel and in Slack. Reads the board and can propose changes for you to confirm.",
+        cadence: "Every question a person asks.",
+        defaultModel: "claude-opus-5",
+        whenUnavailable: "The Ask panel replies that it has no answer. Nothing else is affected.",
+    },
+    arbiter: {
+        role: "arbiter",
+        title: "Collision arbiter",
+        description: "Judges whether two agents declaring overlapping work actually conflict, on every intent_declare.",
+        cadence: "Every declaration by every agent — the highest-volume role.",
+        defaultModel: "claude-haiku-4-5",
+        whenUnavailable: "Falls back to the heuristic check, which catches interface overlaps but not subtler conflicts.",
+    },
+    cos_judge: {
+        role: "cos_judge",
+        title: "Chief of staff — judgment",
+        description: "Decides open questions on the board and judges whether stalled work still serves the goal. Its verdicts are written to the board.",
+        cadence: "Once a day, over at most a dozen items.",
+        defaultModel: "claude-sonnet-5",
+        whenUnavailable: "The chief of staff runs rules-only: it still tidies, coordinates and reports, but decides nothing.",
+    },
+};
+const DEFAULT_ANTHROPIC_KEY_ENV = "ANTHROPIC_API_KEY";
+/** A model id that is not a Claude one is assumed to speak the OpenAI dialect. */
+const inferProvider = (model) => /^claude[-.]/i.test(model) ? "anthropic" : "openai_compatible";
+/**
+ * Resolve one role.
+ *
+ * Precedence is settings, then environment, then the catalogue default —
+ * most specific wins. Settings are per project and editable in the dashboard;
+ * environment is per server and set by whoever runs it; the default is what
+ * ships.
+ *
+ * Environment names are `NAIB_MODEL_<ROLE>_MODEL` and friends, with the
+ * `KEEL_`/`CHARTER_` aliases honoured directly so this works whether or not
+ * `aliasEnv` has run.
+ *
+ * Never throws. A misconfiguration disables one role and explains itself; the
+ * caller degrades per `whenUnavailable` rather than failing.
+ */
+export function resolveRole(role, settings, env = {}) {
+    const definition = ROLE_CATALOG[role];
+    if (!definition) {
+        return { assignment: null, disabledReason: `unknown model role ${JSON.stringify(role)}` };
+    }
+    const upper = role.toUpperCase();
+    const scoped = (scope, suffix) => {
+        for (const prefix of ["NAIB_", "KEEL_", "CHARTER_"]) {
+            const v = env[`${prefix}MODEL_${scope}_${suffix}`]?.trim();
+            if (v)
+                return v;
+        }
+        return undefined;
+    };
+    /**
+     * Per-role first, then the server-wide default.
+     *
+     * `NAIB_MODEL_DEFAULT_*` exists because "plug whatever model in" should not
+     * mean repeating the same endpoint and key variable once per role, and
+     * repeating them again when a role is added.
+     */
+    const readEnv = (suffix) => scoped(upper, suffix) ?? scoped("DEFAULT", suffix);
+    const fromSettings = settings?.[role] ?? {};
+    const trimmed = (v) => {
+        const t = v?.trim();
+        return t ? t : undefined;
+    };
+    const settingsModel = trimmed(fromSettings.model);
+    const envModel = readEnv("MODEL");
+    /**
+     * The default's endpoint and key belong to the default's *model*, and must
+     * not follow a role that points somewhere else.
+     *
+     * Setting `NAIB_MODEL_DEFAULT_*` to GLM and then overriding one role to a
+     * Claude model used to leave that role resolving to Anthropic while still
+     * inheriting `GLM_API_KEY`, so every request came back
+     * `401 invalid x-api-key` — naming a key the operator had never pointed at
+     * Anthropic. Transport is inherited only when the role ends up on the same
+     * provider the default describes.
+     */
+    const defaultScopeModel = scoped("DEFAULT", "MODEL");
+    const model = settingsModel ?? envModel ?? definition.defaultModel;
+    const source = settingsModel
+        ? "settings"
+        : envModel
+            ? "environment"
+            : "default";
+    const explicitProvider = trimmed(fromSettings.provider) ?? scoped(upper, "PROVIDER") ?? scoped("DEFAULT", "PROVIDER");
+    if (explicitProvider && explicitProvider !== "anthropic" && explicitProvider !== "openai_compatible") {
+        return {
+            assignment: null,
+            disabledReason: `${definition.title}: unknown provider ${JSON.stringify(explicitProvider)} — expected anthropic or openai_compatible`,
+        };
+    }
+    const provider = explicitProvider ?? inferProvider(model);
+    // Whether this role may inherit the default's transport: only when the
+    // default names a model on the same provider, so a Claude role never picks
+    // up a GLM endpoint or key.
+    const inheritsDefaultTransport = defaultScopeModel !== undefined && inferProvider(defaultScopeModel) === provider;
+    const readTransport = (suffix) => scoped(upper, suffix) ?? (inheritsDefaultTransport ? scoped("DEFAULT", suffix) : undefined);
+    if (provider === "anthropic") {
+        return {
+            assignment: {
+                role,
+                model,
+                provider,
+                apiKeyEnv: trimmed(fromSettings.api_key_env) ?? readTransport("API_KEY_ENV") ?? DEFAULT_ANTHROPIC_KEY_ENV,
+                source,
+            },
+            disabledReason: null,
+        };
+    }
+    // Neither of these can be guessed. A default base URL would mean sending the
+    // board, and people's questions, to whatever host that default named — the
+    // wrong direction to fail in.
+    const baseUrl = trimmed(fromSettings.base_url) ?? readTransport("BASE_URL");
+    const apiKeyEnv = trimmed(fromSettings.api_key_env) ?? readTransport("API_KEY_ENV");
+    if (!baseUrl) {
+        return {
+            assignment: null,
+            disabledReason: `${definition.title}: ${model} needs a base URL (an OpenAI-compatible /chat/completions endpoint)`,
+        };
+    }
+    if (!apiKeyEnv) {
+        return {
+            assignment: null,
+            disabledReason: `${definition.title}: ${model} needs the name of the environment variable holding its key`,
+        };
+    }
+    return { assignment: { role, model, provider, baseUrl, apiKeyEnv, source }, disabledReason: null };
+}
+/**
+ * Resolve every role at once, for the settings screen.
+ *
+ * Returns a row per role whether or not it is usable, because "this one is
+ * misconfigured" is exactly what an operator opening this screen needs to see.
+ */
+export function resolveAllRoles(settings, env = {}) {
+    return MODEL_ROLES.map((role) => {
+        const resolution = resolveRole(role, settings, env);
+        return {
+            ...ROLE_CATALOG[role],
+            ...resolution,
+            // Whether the named variable actually holds anything — the single most
+            // common reason a correctly-configured role still does not run. The value
+            // itself is never read out.
+            keyPresent: Boolean(resolution.assignment && env[resolution.assignment.apiKeyEnv]?.trim()),
+        };
+    });
+}
+/** Validate a settings blob before storing it, so bad config cannot be saved. */
+export function validateRoleSettings(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return false;
+    for (const [role, setting] of Object.entries(value)) {
+        if (!MODEL_ROLES.includes(role))
+            return false;
+        if (setting === null || typeof setting !== "object" || Array.isArray(setting))
+            return false;
+        const s = setting;
+        for (const [key, v] of Object.entries(s)) {
+            if (!["model", "provider", "base_url", "api_key_env"].includes(key))
+                return false;
+            if (v !== undefined && typeof v !== "string")
+                return false;
+        }
+        if (typeof s.provider === "string" && !["anthropic", "openai_compatible"].includes(s.provider)) {
+            return false;
+        }
+    }
+    return true;
+}