orchestrator-workflow 0.28.0 → 0.30.0

package/dist/init.d.ts

@@ -1,5 +1,7 @@
 import type { Harness } from "./detect.js";
 import type { ModelClass, Profile, Role } from "./models.js";
+import type { HarnessRouting } from "./routing.js";
+import type { OpencodeModelMaps } from "./routing-state.js";
 import type { Report } from "./writers.js";
 export interface InitOptions {
     targetDir: string;
@@ -15,11 +17,14 @@ export interface InitOptions {
     /**
      * Resolved fully-qualified opencode model ids per role, or `undefined` to
      * omit the `model:` frontmatter line (subagent inherits the session model).
-     * When this field is absent the fallback is `opencodeModelValue(models[role])`,
-     * which passes through a fully-qualified id and returns `undefined` for bare
-     * aliases, producing the same inherit-session-model behaviour for bare inputs.
+     * Qualified values persist in routing; legacy bare IDs persist in the
+     * manifest compatibility map of the same name. A present map records
+     * inheritance for missing keys unless routing supplies that selection.
+     * When absent, prior
+     * selections survive; otherwise `opencodeModelValue(models[role])` passes
+     * through a qualified id or leaves bare aliases inheriting the session model.
      */
-    opencodeModels?: Record<Role, string | undefined>;
+    opencodeModels?: Partial<Record<Role, string | undefined>>;
     /**
      * Renders additional per-role effort-tier subagent variants
      * (`<role>-<tier>.md`) alongside the default agent file. Defaults to
@@ -33,9 +38,29 @@ export interface InitOptions {
      * that variant. Only consulted when `tiers` is true and the `opencode`
      * harness is selected; mirrors `opencodeModels` but keyed by model class
      * instead of role, since a tier variant's model is chosen by class, not
-     * by the role's own preselected model.
+     * by the role's own preselected model. Resolved ids are persisted per tier
+     * and retained on a later install that omits this field. Legacy bare IDs
+     * persist in the manifest compatibility map of the same name.
      */
-    opencodeClassModels?: Record<ModelClass, string | undefined>;
+    opencodeClassModels?: Partial<Record<ModelClass, string | undefined>>;
+    /**
+     * Per-harness role/tier selections. This is an additive, partial map: the
+     * installer preserves previous leaves and fills remaining omissions from
+     * deterministic harness defaults. An explicit leaf wins over legacy inputs.
+     */
+    routing?: HarnessRouting;
+    /**
+     * "patch" (default) preserves previous routing leaves. "replace" accepts
+     * an authoritative resolved map and excludes all previous routing, as used
+     * by CLI resolution and apply --sync. Omitted leaves still use defaults.
+     */
+    routingMode?: "patch" | "replace";
+    /**
+     * Optional, explicitly supplied Codex capability catalog. The installer
+     * never contacts a live service; when this is present it is validated
+     * before any kit-owned file is written.
+     */
+    codexCatalog?: unknown;
     /**
      * Repo kit-version pin (distinct from the actually-installed `version`),
      * so a later `apply` command can gate on it. A `string` sets a new
@@ -47,7 +72,7 @@ export interface InitOptions {
     pin?: string | null;
 }
 export declare const MANIFEST_PATH: string;
-export interface Manifest {
+export interface Manifest extends OpencodeModelMaps {
     kit: string;
     version: string;
     harnesses: Harness[];
@@ -56,6 +81,8 @@ export interface Manifest {
     profile: Profile;
     /** Whether per-role effort-tier subagent variants were rendered. */
     tiers: boolean;
+    /** Exact resolved harness/role/tier selections from the install. */
+    routing?: HarnessRouting;
     /**
      * sha256 of every kit-owned file as installed. This is how a re-run tells
      * "upstream changed, safe to update" apart from "user edited, conflict".

package/dist/init.js

@@ -4,6 +4,9 @@ import { isAbsolute, join, normalize, sep } from "node:path";
 import { PACKAGE_VERSION, listTemplateNames, readAgentAsset, readAsset, } from "./assets.js";
 import { HARNESSES } from "./detect.js";
 import { CLASS_MODELS, DEFAULT_PROFILE, DEFAULT_TIER, READ_ONLY_ROLES, ROLES, ROLE_TIERS, TIER_DEFS, assertValidModelId, claudeModelValue, isProfile, opencodeModelValue, rolesForProfile, } from "./models.js";
+import { composeCodexAgent } from "./codex.js";
+import { parseRouting } from "./routing.js";
+import { codexCatalogWarnings, normalizeRoutingState, legacyOpencodeFallbacks, parseOpencodeModelMaps, } from "./routing-state.js";
 import { emptyReport, ensureClaudeImport, installFile, upsertMarkerSection, } from "./writers.js";
 const SKILL_NAME = "orchestrator-workflow";
 export const MANIFEST_PATH = join(".ai", "workflow", "manifest.json"); // shared with doctor.ts/cli.ts (L9); see readInstalledManifest below
@@ -91,6 +94,14 @@ export function readInstalledManifest(targetDir) {
     // (the same per-field-degradation style as `profile` above) rather than
     // throwing on a legacy manifest.
     const tiers = typeof candidate.tiers === "boolean" ? candidate.tiers : false;
+    // Routing is intentionally stricter than the legacy per-role `models`
+    // map. A malformed routing record must stop a re-install instead of
+    // silently replacing the operator's explicit selections with new defaults.
+    const opencodeMaps = parseOpencodeModelMaps(candidate);
+    let routing;
+    if ("routing" in candidate) {
+        routing = parseRouting(candidate.routing);
+    }
     // A hand-written or damaged manifest may carry a non-string `pin`; that
     // degrades to "no recorded pin" here (the same per-field-degradation
     // style as `profile`/`tiers` above) rather than throwing. An empty or
@@ -105,6 +116,8 @@ export function readInstalledManifest(targetDir) {
         models: models,
         profile,
         tiers,
+        ...(routing !== undefined ? { routing } : {}),
+        ...opencodeMaps,
         files,
         installedAt: typeof candidate.installedAt === "string" ? candidate.installedAt : "",
         // The kit-version pin is deliberately free-form here: unlike the
@@ -118,6 +131,17 @@ export function readInstalledManifest(targetDir) {
 function yamlQuote(value) {
     return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
 }
+function yamlModelScalar(value) {
+    // Keep ordinary legacy aliases and provider ids byte-compatible, but quote
+    // values YAML would otherwise coerce when they originate in routing JSON.
+    if (/^(?:true|false|null|yes|no|on|off|~)$/i.test(value) ||
+        /^[-+]?\d+(?:\.\d+)?$/.test(value) ||
+        value.includes(":") ||
+        value.includes("#")) {
+        return yamlQuote(value);
+    }
+    return value;
+}
 /**
  * Composes the unsuffixed default agent file. It carries a pinned
  * `effort: <TIER_DEFS[DEFAULT_TIER[role]].effort>` line unconditionally
@@ -134,14 +158,14 @@ function yamlQuote(value) {
  * opencode's family-based `opencodeEffortLine` has, so there is no second,
  * potentially-diverging computation here to guard against.
  */
-function composeClaudeAgent(role, model) {
+function composeClaudeAgent(role, model, selection) {
     const asset = readAgentAsset(role);
     const frontmatter = [
         "---",
         `name: ${asset.name}`,
         `description: ${yamlQuote(asset.description)}`,
-        `model: ${claudeModelValue(model)}`,
-        `effort: ${TIER_DEFS[DEFAULT_TIER[role]].effort}`,
+        `model: ${selection ? yamlModelScalar(selection.model) : claudeModelValue(model)}`,
+        `effort: ${selection?.effort ?? TIER_DEFS[DEFAULT_TIER[role]].effort}`,
     ];
     // Read-only roles keep every read/search tool but cannot mutate files.
     if (READ_ONLY_ROLES.has(role)) {
@@ -168,7 +192,7 @@ function composeOpencodeAgent(role, modelValue, effortLine) {
     // Only emit `model:` when a resolved, non-empty FQ id is available.
     // Omitting it lets the subagent inherit the session/default model.
     if (modelValue) {
-        frontmatter.push(`model: ${modelValue}`);
+        frontmatter.push(`model: ${yamlModelScalar(modelValue)}`);
     }
     if (effortLine) {
         frontmatter.push(effortLine);
@@ -179,6 +203,9 @@ function composeOpencodeAgent(role, modelValue, effortLine) {
     frontmatter.push("---");
     return [...frontmatter, "", asset.body.trimEnd(), ""].join("\n");
 }
+function routingSelection(routing, harness, role, tier) {
+    return routing[harness]?.[role]?.[tier];
+}
 function tierDescriptionSuffix(asset, tier) {
     return `${asset.description} (Effort tier: ${tier}.)`;
 }
@@ -188,15 +215,15 @@ function tierDescriptionSuffix(asset, tier) {
  * `DEFAULT_TIER`), so `composeClaudeAgent`'s own output (pinned default
  * effort included) stays byte-identical whether or not tiers are on.
  */
-function composeClaudeAgentVariant(role, tier) {
+function composeClaudeAgentVariant(role, tier, selection) {
     const asset = readAgentAsset(role);
     const def = TIER_DEFS[tier];
     const frontmatter = [
         "---",
         `name: ${asset.name}-${tier}`,
         `description: ${yamlQuote(tierDescriptionSuffix(asset, tier))}`,
-        `model: ${claudeModelValue(CLASS_MODELS[def.modelClass])}`,
-        `effort: ${def.effort}`,
+        `model: ${selection ? yamlModelScalar(selection.model) : claudeModelValue(CLASS_MODELS[def.modelClass])}`,
+        `effort: ${selection?.effort ?? def.effort}`,
     ];
     if (READ_ONLY_ROLES.has(role)) {
         frontmatter.push("disallowedTools: Edit, Write, NotebookEdit");
@@ -264,7 +291,7 @@ function composeOpencodeAgentVariant(role, tier, modelValue, effortLine) {
         "mode: subagent",
     ];
     if (modelValue) {
-        frontmatter.push(`model: ${modelValue}`);
+        frontmatter.push(`model: ${yamlModelScalar(modelValue)}`);
     }
     if (effortLine) {
         frontmatter.push(effortLine);
@@ -288,6 +315,43 @@ export function runInit(options) {
     const tiers = options.tiers ?? false;
     const report = emptyReport();
     const previous = readInstalledManifest(targetDir);
+    const suppliedMaps = parseOpencodeModelMaps(options);
+    const previousMaps = options.routingMode === "replace"
+        ? {}
+        : parseOpencodeModelMaps(previous ?? {});
+    const opencodeModels = suppliedMaps.opencodeModels ??
+        (previousMaps.opencodeModels !== undefined
+            ? { ...previousMaps.opencodeModels }
+            : undefined);
+    if (opencodeModels && options.opencodeModels === undefined && previous) {
+        for (const role of ROLES) {
+            if (options.models[role] !== previous.models[role])
+                opencodeModels[role] = opencodeModelValue(options.models[role]);
+        }
+    }
+    const opencodeClassModels = suppliedMaps.opencodeClassModels ?? previousMaps.opencodeClassModels;
+    const compatibility = legacyOpencodeFallbacks({
+        opencodeModels,
+        opencodeClassModels,
+    });
+    const routing = normalizeRoutingState({
+        harnesses: options.harnesses,
+        models: options.models,
+        opencodeModels,
+        opencodeClassModels,
+        previousRouting: previous?.routing,
+        routing: options.routing,
+        routingMode: options.routingMode,
+        legacyOverrideRoles: previous
+            ? ROLES.filter((role) => options.models[role] !== previous.models[role])
+            : [],
+        updateOpencodeModels: options.opencodeModels !== undefined,
+        updateOpencodeClassModels: options.opencodeClassModels !== undefined,
+    });
+    // Check only rendered selections before the first mutation.
+    for (const warning of codexCatalogWarnings(routing, { harnesses: options.harnesses, profile, tiers }, options.codexCatalog)) {
+        report.notes.push(`Codex catalog: ${warning}`);
+    }
     // `null` clears an existing pin, a string sets a new one, and omitted
     // (`undefined`) carries the previous manifest's pin forward unchanged. An
     // empty or whitespace-only string is normalized to a clear as well: it can
@@ -315,7 +379,15 @@ export function runInit(options) {
     // sitting on disk and still becoming untracked either way. The ledger
     // (`previous.files`/`previous.harnesses`) is the only source of truth for
     // "what did the previous install actually put on disk."
-    const previousHarnessDirs = (previous?.harnesses ?? []).filter((harness) => harness === "claude" || harness === "opencode");
+    const previousHarnessDirs = (previous?.harnesses ?? [])
+        .map((harness) => harness === "claude"
+        ? { dir: ".claude", extension: ".md" }
+        : harness === "opencode"
+            ? { dir: ".opencode", extension: ".md" }
+            : harness === "codex"
+                ? { dir: ".codex", extension: ".toml" }
+                : undefined)
+        .filter((entry) => entry !== undefined);
     // A full -> minimal downgrade drops explorer/task-slicer from the roles
     // installed, but (like dropping a harness from --harness) existing role
     // files are never deleted: they simply fall out of the manifest's file
@@ -323,9 +395,9 @@ export function runInit(options) {
     // left as an unexplained, untracked leftover on disk.
     if (previous && previous.profile === "full" && profile !== previous.profile) {
         const droppedRoles = rolesForProfile(previous.profile).filter((role) => !rolesForProfile(profile).includes(role));
-        for (const harnessDir of previousHarnessDirs.map((harness) => harness === "claude" ? ".claude" : ".opencode")) {
+        for (const harnessDir of previousHarnessDirs) {
             for (const role of droppedRoles) {
-                const relativePath = join(harnessDir, "agents", `${role}.md`);
+                const relativePath = join(harnessDir.dir, "agents", `${role}${harnessDir.extension}`);
                 if (previous.files[relativePath] !== undefined) {
                     report.notes.push(`${relativePath}: now untracked after the full -> ${profile} profile downgrade; run \`orchestrator-workflow uninstall\` first next time, or remove it by hand.`);
                 }
@@ -338,7 +410,7 @@ export function runInit(options) {
                 for (const tier of ROLE_TIERS[role]) {
                     if (tier === DEFAULT_TIER[role])
                         continue;
-                    const variantPath = join(harnessDir, "agents", `${role}-${tier}.md`);
+                    const variantPath = join(harnessDir.dir, "agents", `${role}-${tier}${harnessDir.extension}`);
                     if (previous.files[variantPath] !== undefined) {
                         report.notes.push(`${variantPath}: now untracked after the full -> ${profile} profile downgrade; run \`orchestrator-workflow uninstall\` first next time, or remove it by hand.`);
                     }
@@ -353,12 +425,12 @@ export function runInit(options) {
     // there is no overlap between the two loops). Surface it the same way:
     // a note per file instead of a silent, unexplained leftover.
     if (previous && previous.tiers && !tiers) {
-        for (const harnessDir of previousHarnessDirs.map((harness) => harness === "claude" ? ".claude" : ".opencode")) {
+        for (const harnessDir of previousHarnessDirs) {
             for (const role of rolesForProfile(profile)) {
                 for (const tier of ROLE_TIERS[role]) {
                     if (tier === DEFAULT_TIER[role])
                         continue;
-                    const relativePath = join(harnessDir, "agents", `${role}-${tier}.md`);
+                    const relativePath = join(harnessDir.dir, "agents", `${role}-${tier}${harnessDir.extension}`);
                     if (previous.files[relativePath] !== undefined) {
                         report.notes.push(`${relativePath}: now untracked after tiers were turned off; run \`orchestrator-workflow uninstall\` first next time, or remove it by hand.`);
                     }
@@ -390,16 +462,15 @@ export function runInit(options) {
     // either way, whether or not `previous.harnesses` ever named it.
     if (previous) {
         const harnessDirs = {
-            claude: ".claude",
-            codex: ".agents",
-            opencode: ".opencode",
+            claude: [".claude"],
+            codex: [".agents", ".codex"],
+            opencode: [".opencode"],
         };
         for (const harness of HARNESSES) {
             if (options.harnesses.includes(harness))
                 continue;
-            const prefix = harnessDirs[harness] + sep;
             for (const relativePath of Object.keys(previous.files)) {
-                if (relativePath.startsWith(prefix)) {
+                if (harnessDirs[harness].some((dir) => relativePath.startsWith(dir + sep))) {
                     report.notes.push(`${relativePath}: now untracked after --harness dropped ${harness}; run \`orchestrator-workflow uninstall\` first next time, or remove it by hand.`);
                 }
             }
@@ -415,7 +486,7 @@ export function runInit(options) {
         // `previous.files`), not on the sanitized `previous.harnesses`, for the
         // same reason as the loop above: a damaged manifest can filter a valid
         // harness out of `previous.harnesses` while its files remain recorded.
-        const hadTrackedHarnessFiles = Object.keys(previous.files).some((relativePath) => HARNESSES.some((harness) => relativePath.startsWith(harnessDirs[harness] + sep)));
+        const hadTrackedHarnessFiles = Object.keys(previous.files).some((relativePath) => HARNESSES.some((harness) => harnessDirs[harness].some((dir) => relativePath.startsWith(dir + sep))));
         if (hadTrackedHarnessFiles && options.harnesses.length === 0) {
             for (const name of ["AGENTS.md", "CLAUDE.md"]) {
                 if (existsSync(join(targetDir, name))) {
@@ -466,12 +537,12 @@ export function runInit(options) {
     if (options.harnesses.includes("claude")) {
         installKitFile(join(".claude", "skills", SKILL_NAME, "SKILL.md"), skill);
         for (const role of rolesForProfile(profile)) {
-            installKitFile(join(".claude", "agents", `${role}.md`), composeClaudeAgent(role, options.models[role]));
+            installKitFile(join(".claude", "agents", `${role}.md`), composeClaudeAgent(role, options.models[role], routingSelection(routing, "claude", role, DEFAULT_TIER[role])));
             if (tiers) {
                 for (const tier of ROLE_TIERS[role]) {
                     if (tier === DEFAULT_TIER[role])
                         continue;
-                    installKitFile(join(".claude", "agents", `${role}-${tier}.md`), composeClaudeAgentVariant(role, tier));
+                    installKitFile(join(".claude", "agents", `${role}-${tier}.md`), composeClaudeAgentVariant(role, tier, routingSelection(routing, "claude", role, tier)));
                 }
             }
         }
@@ -479,21 +550,46 @@ export function runInit(options) {
     }
     if (options.harnesses.includes("codex")) {
         installKitFile(join(".agents", "skills", SKILL_NAME, "SKILL.md"), skill);
+        for (const role of rolesForProfile(profile)) {
+            const defaultSelection = routingSelection(routing, "codex", role, DEFAULT_TIER[role]);
+            // `defaultCodexRouting` makes every default-tier selection complete;
+            // retain this guard so a hand-constructed partial routing object cannot
+            // produce an invalid native agent file through the public runInit API.
+            if (!defaultSelection) {
+                throw new Error(`Missing Codex routing for ${role}/${DEFAULT_TIER[role]}`);
+            }
+            installKitFile(join(".codex", "agents", `${role}.toml`), composeCodexAgent(role, defaultSelection));
+            if (tiers) {
+                for (const tier of ROLE_TIERS[role]) {
+                    if (tier === DEFAULT_TIER[role])
+                        continue;
+                    const selection = routingSelection(routing, "codex", role, tier);
+                    if (!selection) {
+                        throw new Error(`Missing Codex routing for ${role}/${tier}`);
+                    }
+                    installKitFile(join(".codex", "agents", `${role}-${tier}.toml`), composeCodexAgent(role, selection, tier));
+                }
+            }
+        }
     }
     if (options.harnesses.includes("opencode")) {
         installKitFile(join(".opencode", "skills", SKILL_NAME, "SKILL.md"), skill);
         for (const role of rolesForProfile(profile)) {
-            const modelValue = options.opencodeModels !== undefined
-                ? options.opencodeModels[role]
-                : opencodeModelValue(options.models[role]);
-            const defaultEffortLine = opencodeEffortLine(DEFAULT_TIER[role], modelValue);
+            const modelValue = routingSelection(routing, "opencode", role, DEFAULT_TIER[role])
+                ?.model ??
+                (opencodeModels !== undefined
+                    ? opencodeModels[role]
+                    : opencodeModelValue(options.models[role]));
+            const defaultEffortLine = opencodeEffortLine(routingSelection(routing, "opencode", role, DEFAULT_TIER[role])
+                ?.effort ?? DEFAULT_TIER[role], modelValue);
             installKitFile(join(".opencode", "agents", `${role}.md`), composeOpencodeAgent(role, modelValue, defaultEffortLine));
             if (tiers) {
                 for (const tier of ROLE_TIERS[role]) {
                     if (tier === DEFAULT_TIER[role])
                         continue;
+                    const selection = routingSelection(routing, "opencode", role, tier);
                     const modelClass = TIER_DEFS[tier].modelClass;
-                    const variantModelValue = options.opencodeClassModels?.[modelClass];
+                    const variantModelValue = selection?.model ?? opencodeClassModels?.[modelClass];
                     if (variantModelValue === undefined) {
                         // No model resolved for this class: opencodeEffortLine always
                         // returns undefined too when its modelValue argument is
@@ -509,7 +605,7 @@ export function runInit(options) {
                         // rules in opencodeEffortLine above.
                         continue;
                     }
-                    const effortLine = opencodeEffortLine(tier, variantModelValue);
+                    const effortLine = opencodeEffortLine(selection?.effort ?? tier, variantModelValue);
                     installKitFile(join(".opencode", "agents", `${role}-${tier}.md`), composeOpencodeAgentVariant(role, tier, variantModelValue, effortLine));
                 }
             }
@@ -524,6 +620,8 @@ export function runInit(options) {
         models: options.models,
         profile,
         tiers,
+        routing,
+        ...compatibility,
         files: installedFiles,
         ...(pin !== undefined ? { pin } : {}),
     };
@@ -536,6 +634,8 @@ export function runInit(options) {
             models: previous.models,
             profile: previous.profile,
             tiers: previous.tiers,
+            ...(previous.routing !== undefined ? { routing: previous.routing } : {}),
+            ...legacyOpencodeFallbacks(previous),
             files: previous.files,
             ...(previous.pin !== undefined ? { pin: previous.pin } : {}),
         }) === JSON.stringify(desired)) {

package/dist/operator-manifest.d.ts

@@ -1,5 +1,7 @@
 import type { Harness } from "./detect.js";
 import type { Profile, Role } from "./models.js";
+import type { OpencodeModelMaps } from "./routing-state.js";
+import type { HarnessRouting } from "./routing.js";
 export declare const OPERATOR_HOME_DIRNAME = ".orchestrator-workflow";
 export declare const OPERATOR_HOME_ENV = "ORCHESTRATOR_WORKFLOW_HOME";
 export declare const OPERATOR_MANIFEST_FILENAME = "manifest.json";
@@ -11,11 +13,13 @@ export declare const OPERATOR_MANIFEST_FILENAME = "manifest.json";
  * some roles, and the rest should fall back to `DEFAULT_MODELS` at the call
  * site rather than forcing every role to be present here.
  */
-export interface OperatorManifestDefaults {
+export interface OperatorManifestDefaults extends OpencodeModelMaps {
     harnesses: Harness[];
     profile: Profile;
     tiers: boolean;
     models: Partial<Record<Role, string>>;
+    /** Explicit or resolved per-harness selections, carried additively. */
+    routing?: HarnessRouting;
 }
 /** One target directory this operator has applied the kit to. */
 export interface OperatorTarget {

package/dist/operator-manifest.js

@@ -4,6 +4,8 @@ import { homedir } from "node:os";
 import { isAbsolute, join, resolve } from "node:path";
 import { HARNESSES } from "./detect.js";
 import { DEFAULT_PROFILE, ROLES, assertValidModelId, isProfile, } from "./models.js";
+import { parseRouting } from "./routing.js";
+import { parseOpencodeModelMaps } from "./routing-state.js";
 export const OPERATOR_HOME_DIRNAME = ".orchestrator-workflow";
 export const OPERATOR_HOME_ENV = "ORCHESTRATOR_WORKFLOW_HOME";
 export const OPERATOR_MANIFEST_FILENAME = "manifest.json";
@@ -88,6 +90,25 @@ export function readOperatorManifest(home) {
         ? rawDefaults.profile
         : DEFAULT_PROFILE;
     const tiers = typeof rawDefaults.tiers === "boolean" ? rawDefaults.tiers : false;
+    let opencodeMaps;
+    try {
+        opencodeMaps = parseOpencodeModelMaps(rawDefaults);
+    }
+    catch {
+        return undefined;
+    }
+    let routing;
+    if ("routing" in rawDefaults) {
+        try {
+            routing = parseRouting(rawDefaults.routing);
+        }
+        catch {
+            // Unlike legacy aliases, an invalid routing map could silently change
+            // native Codex agents on a future install. Treat the whole operator
+            // manifest as unreadable so setup/apply cannot overwrite it by guess.
+            return undefined;
+        }
+    }
     const targets = (Array.isArray(candidate.targets) ? candidate.targets : []).filter((value) => {
         if (typeof value !== "object" || value === null)
             return false;
@@ -100,7 +121,14 @@ export function readOperatorManifest(home) {
     return {
         kit: "orchestrator-workflow",
         schemaVersion: 1,
-        defaults: { harnesses, profile, tiers, models },
+        defaults: {
+            harnesses,
+            profile,
+            tiers,
+            models,
+            ...(routing !== undefined ? { routing } : {}),
+            ...opencodeMaps,
+        },
         targets,
         createdAt: typeof candidate.createdAt === "string" ? candidate.createdAt : "",
         updatedAt: typeof candidate.updatedAt === "string" ? candidate.updatedAt : "",
@@ -135,6 +163,7 @@ function writeOperatorManifestUnlocked(home, manifest) {
     mkdirSync(home, { recursive: true });
     const path = join(home, OPERATOR_MANIFEST_FILENAME);
     const tmpPath = join(home, `${OPERATOR_MANIFEST_FILENAME}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`);
+    parseOpencodeModelMaps(manifest.defaults);
     writeFileSync(tmpPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
     renameSync(tmpPath, path);
 }
@@ -530,6 +559,9 @@ export function upsertOperatorTarget(manifest, targetPath, appliedVersion, appli
             defaults: {
                 ...manifest.defaults,
                 models: { ...manifest.defaults.models },
+                ...(manifest.defaults.routing !== undefined
+                    ? { routing: manifest.defaults.routing }
+                    : {}),
             },
             targets,
         },

package/dist/routing-state.d.ts

@@ -0,0 +1,60 @@
+import type { Harness } from "./detect.js";
+import type { ModelClass, Profile, Role, Tier } from "./models.js";
+import type { HarnessRouting } from "./routing.js";
+/** Legacy API resolution state: absent is unknown; present missing keys inherit. */
+export interface OpencodeModelMaps {
+    opencodeModels?: Partial<Record<Role, string | undefined>>;
+    opencodeClassModels?: Partial<Record<ModelClass, string | undefined>>;
+}
+/** Validate compatibility maps independently of strict explicit routing. */
+export declare function parseOpencodeModelMaps(value: {
+    opencodeModels?: unknown;
+    opencodeClassModels?: unknown;
+}): OpencodeModelMaps;
+/** Persist only the compatibility values that cannot live in strict routing. */
+export declare function legacyOpencodeFallbacks(value: OpencodeModelMaps): OpencodeModelMaps;
+/** Strip compatibility-only leaves before saving or parsing strict routing. */
+export declare function persistableRouting(routing: HarnessRouting): HarnessRouting;
+export interface RoutingScope {
+    harnesses: Harness[];
+    profile: Profile;
+    tiers: boolean;
+}
+export declare function selectedTiers(role: Role, tiers: boolean): Tier[];
+/** Selects only leaves that the requested adapters actually install. */
+export declare function selectedRouting(routing: HarnessRouting, scope: RoutingScope): HarnessRouting;
+/** One shared, offline catalog check for setup and installation. */
+export declare function codexCatalogWarnings(routing: HarnessRouting, scope: RoutingScope, catalog?: unknown): string[];
+export declare function legacyRouting(harnesses: Harness[], models: Record<Role, string>, opencodeModels: OpencodeModelMaps["opencodeModels"], opencodeClassModels: OpencodeModelMaps["opencodeClassModels"]): HarnessRouting;
+export interface RoutingStateInput extends OpencodeModelMaps {
+    harnesses: Harness[];
+    models: Record<Role, string>;
+    previousRouting?: HarnessRouting;
+    routing?: HarnessRouting;
+    routingMode?: "patch" | "replace";
+    /** Explicit legacy default-role updates; unrelated selections remain sticky. */
+    legacyOverrideRoles?: Role[];
+    /** Resolved opencode inputs supplied directly to the installer are updates. */
+    updateOpencodeModels?: boolean;
+    updateOpencodeClassModels?: boolean;
+}
+/** Materializes legacy inputs and preserves leaves unless explicitly replaced. */
+export declare function normalizeRoutingState(input: RoutingStateInput): HarnessRouting;
+interface ComparableRoutingState extends OpencodeModelMaps {
+    models: Partial<Record<Role, string>>;
+    routing?: HarnessRouting;
+}
+/** Materialize each precedence layer before a higher layer overrides it. */
+export declare function routingStateLayer(state: ComparableRoutingState & RoutingScope): HarnessRouting;
+/** Whether a missing concrete leaf has an explicit legacy inheritance record. */
+export declare function recordedOpencodeInheritance(maps: OpencodeModelMaps, role: Role, tier: Tier): boolean;
+/** Merge recorded resolution state independently of the active render scope. */
+export declare function mergeRoutingStateLayers(...states: (ComparableRoutingState & RoutingScope)[]): {
+    routing: HarnessRouting;
+} & OpencodeModelMaps;
+/** Compares installed scope without consulting a live opencode catalog. */
+export declare function compareRoutingState(repo: ComparableRoutingState, operator: ComparableRoutingState, scope: RoutingScope): {
+    differs: boolean;
+    gaps: string[];
+};
+export {};