orchestrator-workflow 0.28.0 → 0.29.0

package/dist/cli-apply.d.ts

@@ -1,6 +1,7 @@
 import type { ResolveInitInputsParams } from "./cli-inputs.js";
 import type { Harness } from "./detect.js";
 import type { Manifest } from "./init.js";
+import type { HarnessRouting } from "./routing.js";
 /** The subset of `apply`'s commander options that feed input resolution. */
 export interface ApplyResolutionOptions {
     harness?: string;
@@ -8,6 +9,7 @@ export interface ApplyResolutionOptions {
     profile?: string;
     opencodeProvider?: string;
     tiers?: boolean;
+    routing?: HarnessRouting;
 }
 /**
  * Builds `apply`'s own `resolveInitInputs` params, pinning the sticky-branch

package/dist/cli-inputs.d.ts

@@ -1,6 +1,8 @@
 import type { Harness } from "./detect.js";
 import type { Manifest } from "./init.js";
-import type { ModelClass, Profile, Role } from "./models.js";
+import type { Profile, Role } from "./models.js";
+import type { OpencodeModelMaps } from "./routing-state.js";
+import type { HarnessRouting } from "./routing.js";
 export declare function promptHarnesses(detected: Harness[], installed: Harness[], fallbackToClaude?: boolean, annotateDetected?: Harness[]): Promise<Harness[]>;
 export declare function promptProfile(base: Profile): Promise<Profile>;
 export declare function promptModels(base: Record<Role, string>, roles: Role[]): Promise<Record<Role, string>>;
@@ -11,6 +13,7 @@ export interface InitResolutionOptions {
     profile?: string;
     opencodeProvider?: string;
     tiers?: boolean;
+    routing?: HarnessRouting;
 }
 export interface ResolveInitInputsParams {
     /** Result of `detectHarnesses(targetDir)`; passed in so the caller can
@@ -52,15 +55,14 @@ export interface ResolveInitInputsParams {
      * The entries pre-checked in the interactive prompt when the target
      * recorded `harnesses: []` (the harnesses-stickiness gate's branch,
      * gated on `previousIsRecordedManifest && previous.
-     * harnessesRecordedEmpty`). Defaults to `[]` when omitted: `init` and
-     * `apply` share this semantics (D-002, agent-dx 7669907c). A fresh
+     * harnessesRecordedEmpty`). Defaults to `[]` when omitted, so `init` and
+     * `apply` share this semantics. A fresh
      * interactive re-run on a templates-only target starts with nothing
      * pre-checked, because the recorded `harnesses: []` is the intent that
      * matters, not a `.claude/`-style directory the harness itself left on
      * disk, which is a weak signal and must not re-widen a deliberate
-     * `--harness none` install just because a bare Enter is pressed
-     * (agent-tasks fe834823; the same argument applies identically to
-     * `init`). `apply`'s call site still passes `[]` explicitly, as defence
+     * `--harness none` install just because a bare Enter is pressed. `apply`'s
+     * call site still passes `[]` explicitly, as defence
      * in depth (see `buildApplyInitInputs`'s doc comment). Only the sticky
      * branch reads this field; the normal (non-recorded-empty) branch still
      * prompts from `detected` unchanged, matching `apply`'s existing
@@ -75,7 +77,7 @@ export interface ResolveInitInputsParams {
      * `stickyPreChecked`'s doc comment), the operator still sees which
      * harness is actually on disk, because labelling is a hint, not an
      * intent signal, so it is safe to annotate what the pre-check itself
-     * must not read (agent-tasks fe834823, fix round 3). `init`'s call site
+     * must not read. `init`'s call site
      * omits this field and gets its own `detectHarnesses(targetDir)` result
      * via this default; `apply`'s call site passes a fresh
      * `detectHarnesses(targetDir)` call explicitly, since its own
@@ -85,13 +87,12 @@ export interface ResolveInitInputsParams {
      */
     stickyAnnotateDetected?: Harness[];
 }
-export interface ResolvedInitInputs {
+export interface ResolvedInitInputs extends OpencodeModelMaps {
     harnesses: Harness[];
     profile: Profile;
     models: Record<Role, string>;
     tiers: boolean;
-    opencodeModels?: Record<Role, string | undefined>;
-    opencodeClassModels?: Record<ModelClass, string | undefined>;
+    routing: HarnessRouting;
     /**
      * Warning lines to print, in order, exactly as `init` printed them to
      * stderr before this extraction (each written as `${line}\n`). Returned
@@ -112,12 +113,7 @@ export interface ResolvedInitInputs {
  * omitted) keeps the previously installed value; a fresh install with no
  * prior manifest falls back to the shipped default.
  *
- * `params.detected` is the fallback-chain input the non-sticky "else"
- * branch below prompts and falls back from. It plays no role in the
- * harnesses-stickiness branch's own pre-check any more: that branch
- * always pre-checks `stickyPreChecked ?? []` (D-002, agent-dx 7669907c),
- * never `detected`, so `init` and `apply` share one semantics there. It
- * still feeds that branch's " (detected)" label by default (see
- * `ResolveInitInputsParams.stickyAnnotateDetected`'s doc comment).
+ * `params.detected` is the non-sticky fallback-chain input; see
+ * `ResolveInitInputsParams.stickyPreChecked` for the sticky rule.
  */
 export declare function resolveInitInputs(params: ResolveInitInputsParams): Promise<ResolvedInitInputs>;

package/dist/cli-inputs.js

@@ -1,35 +1,16 @@
 import inquirer from "inquirer";
 import { HARNESSES, parseHarnessOption } from "./detect.js";
-import { CLASS_MODELS, DEFAULT_MODELS, DEFAULT_PROFILE, MODEL_ALIASES, MODEL_CLASSES, assertValidModelId, parseModelsSpec, parseProfile, rolesForProfile, } from "./models.js";
+import { CLASS_MODELS, DEFAULT_TIER, DEFAULT_MODELS, DEFAULT_PROFILE, MODEL_ALIASES, MODEL_CLASSES, assertValidModelId, parseModelsSpec, parseProfile, rolesForProfile, } from "./models.js";
+import { mergeRouting, parseRouting } from "./routing.js";
+import { legacyRouting, normalizeRoutingState, selectedTiers, parseOpencodeModelMaps, recordedOpencodeInheritance, } from "./routing-state.js";
 import { detectProvider, loadOpencodeCatalog, resolveAlias, resolveOpencodeModels, } from "./opencode.js";
 export async function promptHarnesses(detected, installed, fallbackToClaude = true, 
 // Drives only the checkbox's " (detected)" label suffix, independent of
-// `detected`'s own role in pre-checking a choice: defaults to `detected`
-// so a call site that omits this parameter keeps annotating exactly what
-// it pre-checks from, unchanged. `resolveInitInputs`'s harnesses-
-// stickiness branch (shared by `init` and `apply`, D-002, agent-dx
-// 7669907c) always passes an explicit value here (`stickyAnnotateDetected
-// ?? detected`) instead of relying on this default: that branch pre-checks
-// nothing but still wants the operator to see which harness is actually
-// on disk, so labelling and pre-checking are resolved separately
-// (agent-tasks fe834823, fix round 3).
+// `detected`'s role in pre-checking; see `stickyAnnotateDetected` below.
 annotateDetected = detected) {
     const known = [...new Set([...detected, ...installed])];
-    // Nothing detected and nothing previously installed: the plain-first-run
-    // case pre-checks `claude` as a sane default (`fallbackToClaude`'s default
-    // `true`). The templates-only re-run branch below opts OUT of that
-    // (`fallbackToClaude: false`): a repo the operator explicitly recorded as
-    // `harnesses: []` has no harness files by construction, and pre-checking
-    // `claude` on Enter would silently re-widen an explicit `--harness none`
-    // install -- contradicting README.md's and this function's own "nothing
-    // forced pre-selected" claim (see CHANGELOG). `resolveInitInputs`'s
-    // harnesses-stickiness branch (shared by `init` and `apply`, D-002,
-    // agent-dx 7669907c) always calls this function with `stickyPreChecked ??
-    // []` regardless of what is actually on disk or previously chosen --
-    // the operator's recorded `harnesses: []` is the intent that matters,
-    // not a harness config a harness itself left behind (agent-tasks
-    // fe834823; the residual noted in docs/okf/log.md's 2026-08-31 entry is
-    // closed).
+    // The templates-only branch disables this first-run fallback; see
+    // `ResolveInitInputsParams.stickyPreChecked` for the sticky rule.
     const preselected = known.length > 0 ? known : fallbackToClaude ? ["claude"] : [];
     const { harnesses } = await inquirer.prompt([
         {
@@ -118,6 +99,16 @@ export async function promptModels(base, roles) {
     }
     return models;
 }
+function modelOverrideRoles(spec) {
+    const roles = [];
+    for (const item of spec.split(",")) {
+        const role = item.trim().split("=", 1)[0]?.trim();
+        if (role && rolesForProfile("full").includes(role)) {
+            roles.push(role);
+        }
+    }
+    return [...new Set(roles)];
+}
 /**
  * Resolves everything `runInit` needs (harnesses, profile, models, tiers,
  * the opencode model resolutions) from the CLI-parsed options, the target
@@ -130,16 +121,15 @@ export async function promptModels(base, roles) {
  * omitted) keeps the previously installed value; a fresh install with no
  * prior manifest falls back to the shipped default.
  *
- * `params.detected` is the fallback-chain input the non-sticky "else"
- * branch below prompts and falls back from. It plays no role in the
- * harnesses-stickiness branch's own pre-check any more: that branch
- * always pre-checks `stickyPreChecked ?? []` (D-002, agent-dx 7669907c),
- * never `detected`, so `init` and `apply` share one semantics there. It
- * still feeds that branch's " (detected)" label by default (see
- * `ResolveInitInputsParams.stickyAnnotateDetected`'s doc comment).
+ * `params.detected` is the non-sticky fallback-chain input; see
+ * `ResolveInitInputsParams.stickyPreChecked` for the sticky rule.
  */
 export async function resolveInitInputs(params) {
     const { detected, interactive, previous, opts, previousIsRecordedManifest, stickyPreChecked, stickyAnnotateDetected, } = params;
+    const routingPatch = opts.routing === undefined ? undefined : parseRouting(opts.routing);
+    const previousRouting = previous?.routing === undefined
+        ? undefined
+        : parseRouting(previous.routing);
     let harnesses;
     if (opts.harness) {
         harnesses = parseHarnessOption(opts.harness);
@@ -171,19 +161,7 @@ export async function resolveInitInputs(params) {
         // as `[]` (not the recorded `previous.harnesses`) so nothing is
         // pre-checked from the previous install, unlike the "else" branch
         // below's normal re-run prompt.
-        // `stickyPreChecked ?? []` pre-checks nothing by default: `init` and
-        // `apply` share this semantics (D-002, agent-dx 7669907c; see
-        // CHANGELOG). Neither call site needs to pass `stickyPreChecked`
-        // itself for this default to apply (`apply` still does, as defence in
-        // depth; see `buildApplyInitInputs`'s doc comment); a bare Enter on a
-        // target recorded as `harnesses: []` must not re-widen a deliberate
-        // `--harness none` install just because a harness config happens to
-        // still be on disk, which is a weak signal, not the recorded intent
-        // (agent-tasks fe834823; the same argument applies identically to
-        // `init`). `fallbackToClaude: false` closes the same gap for the case
-        // where nothing is pre-checked either: without it, `promptHarnesses`
-        // would pre-check `claude` on its own "nothing known" fallback,
-        // re-widening the install on a bare Enter.
+        // See `ResolveInitInputsParams.stickyPreChecked` for the shared sticky rule.
         // `stickyAnnotateDetected ?? detected` is passed through as the fourth
         // argument so the checkbox's " (detected)" label still points at what
         // is actually on disk even though nothing is pre-checked from it: the
@@ -226,8 +204,16 @@ export async function resolveInitInputs(params) {
     };
     if (opts.models)
         models = parseModelsSpec(opts.models, models);
-    if (interactive && !opts.models)
+    const promptLegacyModels = interactive &&
+        !opts.models &&
+        harnesses.some((harness) => harness === "claude" || harness === "opencode");
+    if (promptLegacyModels)
         models = await promptModels(models, rolesForProfile(profile));
+    const legacyOverrideRoles = opts.models
+        ? modelOverrideRoles(opts.models)
+        : promptLegacyModels
+            ? rolesForProfile(profile)
+            : [];
     // Explicit --tiers/--no-tiers always override; a plain re-run (neither
     // flag passed) keeps whatever the previous install had (default false
     // for a fresh install), same override-vs-persist rule as
@@ -242,16 +228,28 @@ export async function resolveInitInputs(params) {
     // Resolve opencode model aliases against the live catalog when the opencode
     // harness is selected. The shell-out stays reachable only from this
     // resolution step, keeping runInit pure.
-    let opencodeModels;
-    let opencodeClassModels;
+    const previousMaps = parseOpencodeModelMaps(previous ?? {});
+    let opencodeModels = previousMaps.opencodeModels;
+    let opencodeClassModels = previousMaps.opencodeClassModels;
     const warnings = [];
-    if (harnesses.includes("opencode")) {
+    const availableRouting = mergeRouting(legacyRouting(harnesses, models, opencodeModels, opencodeClassModels), previousRouting, routingPatch);
+    const needsOpencodeResolution = harnesses.includes("opencode") &&
+        (opts.opencodeProvider !== undefined ||
+            legacyOverrideRoles.some((role) => !routingPatch?.opencode?.[role]?.[DEFAULT_TIER[role]]) ||
+            rolesForProfile(profile).some((role) => selectedTiers(role, tiers).some((tier) => !availableRouting.opencode?.[role]?.[tier] &&
+                !recordedOpencodeInheritance(previousMaps, role, tier))));
+    if (needsOpencodeResolution) {
         const catalog = loadOpencodeCatalog();
         const { resolved, warnings: modelWarnings } = resolveOpencodeModels(models, {
             catalog,
             explicitProvider: opts.opencodeProvider,
         });
-        opencodeModels = resolved;
+        opencodeModels =
+            previousMaps.opencodeModels !== undefined && !opts.opencodeProvider
+                ? { ...previousMaps.opencodeModels }
+                : resolved;
+        for (const role of legacyOverrideRoles)
+            opencodeModels[role] = resolved[role];
         for (const w of modelWarnings) {
             warnings.push(`Warning: ${w}`);
         }
@@ -263,11 +261,15 @@ export async function resolveInitInputs(params) {
             opencodeClassModels = {};
             for (const modelClass of MODEL_CLASSES) {
                 const alias = CLASS_MODELS[modelClass];
-                const resolvedModel = providerResult.provider
-                    ? resolveAlias(providerResult.provider, alias, catalog)
-                    : undefined;
+                const recordedClass = previousMaps.opencodeClassModels !== undefined &&
+                    !opts.opencodeProvider;
+                const resolvedModel = recordedClass
+                    ? previousMaps.opencodeClassModels?.[modelClass]
+                    : providerResult.provider
+                        ? resolveAlias(providerResult.provider, alias, catalog)
+                        : undefined;
                 opencodeClassModels[modelClass] = resolvedModel;
-                if (resolvedModel !== undefined)
+                if (resolvedModel !== undefined || recordedClass)
                     continue;
                 // One warning per unresolved model class: without it, every
                 // effort-tier variant keyed to this class is silently skipped
@@ -287,6 +289,18 @@ export async function resolveInitInputs(params) {
             }
         }
     }
+    const routing = normalizeRoutingState({
+        harnesses,
+        models,
+        opencodeModels,
+        opencodeClassModels,
+        previousRouting,
+        routing: routingPatch,
+        legacyOverrideRoles,
+        // Changing provider is an explicit request to resolve all opencode leaves.
+        updateOpencodeModels: opts.opencodeProvider !== undefined,
+        updateOpencodeClassModels: opts.opencodeProvider !== undefined,
+    });
     return {
         harnesses,
         profile,
@@ -294,6 +308,7 @@ export async function resolveInitInputs(params) {
         tiers,
         opencodeModels,
         opencodeClassModels,
+        routing,
         warnings,
     };
 }

package/dist/cli.js

@@ -10,6 +10,8 @@ import { resolveInitInputs } from "./cli-inputs.js";
 import { HARNESSES, detectHarnesses } from "./detect.js";
 import { DEFAULT_MODELS, PROFILES } from "./models.js";
 import { MANIFEST_PATH, readInstalledManifest, runInit } from "./init.js";
+import { parseRouting } from "./routing.js";
+import { codexCatalogWarnings, legacyOpencodeFallbacks, parseOpencodeModelMaps, mergeRoutingStateLayers, } from "./routing-state.js";
 import { OPERATOR_MANIFEST_FILENAME, OperatorManifestLockTimeoutError, applyRegistrationFailureMessage, createOperatorManifest, operatorManifestState, readOperatorManifest, resolveOperatorHome, safeRealpath, updateOperatorManifest, upsertOperatorTarget, } from "./operator-manifest.js";
 import { runUninstall } from "./uninstall.js";
 import { adoptExitCodeForStatus, adoptJsonExtras, inspectTarget, runDoctor, statOrClassify, suppressSuccessLine, targetReportToJson, } from "./doctor.js";
@@ -43,6 +45,20 @@ function requireDirectory(dir) {
     }
     return targetDir;
 }
+function readJsonOption(path, option) {
+    try {
+        return JSON.parse(readFileSync(resolve(path), "utf8"));
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new Error(`Could not read ${option} JSON file ${path}: ${reason}`);
+    }
+}
+function routingOption(path) {
+    return path === undefined
+        ? undefined
+        : parseRouting(readJsonOption(path, "--routing"));
+}
 /**
  * `resolveInitInputs` was extracted from `init` and typed against `init`'s
  * per-repo `Manifest` (kit/version/files/installedAt included), since that
@@ -64,6 +80,8 @@ function defaultsAsManifest(defaults) {
         models: { ...DEFAULT_MODELS, ...defaults.models },
         profile: defaults.profile,
         tiers: defaults.tiers,
+        routing: defaults.routing,
+        ...parseOpencodeModelMaps(defaults),
         files: {},
         installedAt: "",
     };
@@ -80,6 +98,8 @@ function defaultsEqual(a, b) {
         profile: d.profile,
         tiers: d.tiers,
         models: Object.fromEntries(Object.entries(d.models).sort(([x], [y]) => x.localeCompare(y))),
+        routing: d.routing ?? {},
+        ...parseOpencodeModelMaps(d),
     });
     return normalize(a) === normalize(b);
 }
@@ -96,6 +116,8 @@ program
     .option("-f, --force", "overwrite kit-owned files that have local edits")
     .option("--harness <list>", `comma-separated harnesses (${HARNESSES.join(", ")}), or "none" alone for templates-only mode (.ai/workflow/** and .ai/runs/.gitkeep only, no AGENTS.md/CLAUDE.md/harness files); default: detected`)
     .option("--models <spec>", 'per-role model overrides, e.g. "implementer=sonnet,reviewer=opus"')
+    .option("--routing <json-file>", "harness/role/tier routing patch JSON")
+    .option("--codex-catalog <json-file>", "optional offline Codex capability catalog JSON to validate before writing")
     .option("--profile <profile>", `subagent role profile (${PROFILES.join(", ")}); default: full, or the previously installed profile on a re-run`)
     .option("--opencode-provider <id>", "opencode provider id for alias resolution (e.g. github-copilot); auto-detected when omitted")
     .option("--tiers", "also render per-role effort-tier subagent variants (<role>-<tier>.md); default: off, or the previously installed value on a re-run")
@@ -105,6 +127,19 @@ program
     if (!targetDir)
         return;
     const interactive = !opts.yes && isInteractive();
+    let routing;
+    let codexCatalog;
+    try {
+        routing = routingOption(opts.routing);
+        codexCatalog = opts.codexCatalog
+            ? readJsonOption(opts.codexCatalog, "--codex-catalog")
+            : undefined;
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : error);
+        process.exitCode = 2;
+        return;
+    }
     // Say where files will land BEFORE anything is written; an accidental
     // cwd (e.g. $HOME) is the most likely operator mistake.
     console.log(`Installing into ${targetDir}`);
@@ -125,13 +160,16 @@ program
             : "none recorded";
         console.log(`Found existing install (${version.startsWith("unknown") ? version : `v${version}`}, harnesses: ${installedFor}, profile: ${previous.profile}, tiers: ${previous.tiers})`);
     }
-    const { harnesses, profile, models, tiers, opencodeModels, opencodeClassModels, warnings, } = await resolveInitInputs(
+    const { harnesses, profile, models, tiers, opencodeModels, opencodeClassModels, routing: resolvedRouting, warnings, } = await resolveInitInputs(
     // The sticky-branch wiring itself (neither `stickyPreChecked` nor
     // `stickyAnnotateDetected` overridden, so `resolveInitInputs`'s own
     // `?? []` / `?? detected` defaults apply) is pinned inside
     // `buildInitInitInputs` and covered by a dedicated test
     // (`test/cli-init.test.ts`), not by this call site.
-    buildInitInitInputs(detected, previous, interactive, opts));
+    buildInitInitInputs(detected, previous, interactive, {
+        ...opts,
+        routing,
+    }));
     for (const w of warnings) {
         process.stderr.write(`${w}\n`);
     }
@@ -144,6 +182,9 @@ program
         opencodeModels,
         tiers,
         opencodeClassModels,
+        routing: resolvedRouting,
+        routingMode: "replace",
+        codexCatalog,
     });
     showPaths("Created", report.written);
     showPaths("Updated", report.updated);
@@ -159,6 +200,8 @@ program
     .option("-y, --yes", "accept all defaults and skip prompts")
     .option("--harness <list>", `comma-separated harnesses (${HARNESSES.join(", ")}); default: previously stored, or claude`)
     .option("--models <spec>", 'per-role model overrides, e.g. "implementer=sonnet,reviewer=opus"')
+    .option("--routing <json-file>", "harness/role/tier routing patch JSON")
+    .option("--codex-catalog <json-file>", "optional offline Codex capability catalog JSON to validate before saving")
     .option("--profile <profile>", `subagent role profile (${PROFILES.join(", ")}); default: full, or the previously stored profile on a re-run`)
     .option("--opencode-provider <id>", "opencode provider id for alias resolution (e.g. github-copilot); auto-detected when omitted")
     .option("--tiers", "select per-role effort-tier subagent variants by default; default: off, or the previously stored value on a re-run")
@@ -166,6 +209,19 @@ program
     .action(async (opts) => {
     const interactive = !opts.yes && isInteractive();
     const home = resolveOperatorHome();
+    let routingPatch;
+    let codexCatalog;
+    try {
+        routingPatch = routingOption(opts.routing);
+        codexCatalog = opts.codexCatalog
+            ? readJsonOption(opts.codexCatalog, "--codex-catalog")
+            : undefined;
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : error);
+        process.exitCode = 2;
+        return;
+    }
     console.log(`Operator home: ${home}`);
     const existing = readOperatorManifest(home);
     if (existing) {
@@ -177,7 +233,7 @@ program
     // No target repository exists to detect harnesses against; "claude"
     // is the same shipped fallback `init` uses for a fresh install with
     // nothing detected and nothing previously recorded.
-    const { harnesses, profile, models, tiers, warnings } = await resolveInitInputs({
+    const { harnesses, profile, models, tiers, routing, warnings, opencodeModels, opencodeClassModels, } = await resolveInitInputs({
         // No target directory exists to detect against: the stored
         // harnesses are the baseline, and only a first-ever setup falls
         // back to claude, so a codex-only default is not widened silently.
@@ -186,16 +242,30 @@ program
             : ["claude"],
         interactive,
         previous: defaultsAsManifest(existing?.defaults),
-        opts,
+        opts: { ...opts, routing: routingPatch },
     });
     for (const w of warnings) {
         process.stderr.write(`${w}\n`);
     }
+    {
+        try {
+            for (const warning of codexCatalogWarnings(routing, { harnesses, profile, tiers }, codexCatalog)) {
+                process.stderr.write(`Warning: ${warning}\n`);
+            }
+        }
+        catch (error) {
+            console.error(error instanceof Error ? error.message : error);
+            process.exitCode = 2;
+            return;
+        }
+    }
     const newDefaults = {
         harnesses,
         profile,
         tiers,
         models,
+        routing,
+        ...legacyOpencodeFallbacks({ opencodeModels, opencodeClassModels }),
     };
     // The prompts and resolution above ran against `existing`, an
     // unlocked read taken before this point; another process (an
@@ -410,6 +480,7 @@ function buildApplyPrevious(repoManifest, operatorDefaults, sync) {
     const tiers = sync
         ? operatorDefaults.tiers
         : (repoManifest?.tiers ?? operatorDefaults.tiers);
+    const { routing, ...compatibility } = mergeRoutingStateLayers(operatorDefaults, ...(!sync && repoManifest ? [repoManifest] : []));
     return {
         kit: "orchestrator-workflow",
         version: PACKAGE_VERSION,
@@ -424,6 +495,8 @@ function buildApplyPrevious(repoManifest, operatorDefaults, sync) {
         models,
         profile,
         tiers,
+        ...(routing !== undefined ? { routing } : {}),
+        ...compatibility,
         files: {},
         installedAt: "",
     };
@@ -436,6 +509,8 @@ program
     .option("-f, --force", "overwrite kit-owned files that have local edits")
     .option("--harness <list>", `comma-separated harnesses (${HARNESSES.join(", ")}); default: the target's recorded harnesses, else the operator defaults, else detected`)
     .option("--models <spec>", 'per-role model overrides, e.g. "implementer=sonnet,reviewer=opus"')
+    .option("--routing <json-file>", "harness/role/tier routing patch JSON")
+    .option("--codex-catalog <json-file>", "optional offline Codex capability catalog JSON to validate before writing")
     .option("--profile <profile>", `subagent role profile (${PROFILES.join(", ")}); default: the target's recorded profile, else the operator default`)
     .option("--opencode-provider <id>", "opencode provider id for alias resolution (e.g. github-copilot); auto-detected when omitted")
     .option("--tiers", "also render per-role effort-tier subagent variants (<role>-<tier>.md); default: the target's recorded value, else the operator default")
@@ -445,6 +520,19 @@ program
     .option("--pin <version>", "set or replace the target's recorded kit-version pin and apply this operator install regardless of any existing pin")
     .option("--unpin", "clear the target's recorded kit-version pin and apply this operator install")
     .action(async (opts) => {
+    let routingPatch;
+    let codexCatalog;
+    try {
+        routingPatch = routingOption(opts.routing);
+        codexCatalog = opts.codexCatalog
+            ? readJsonOption(opts.codexCatalog, "--codex-catalog")
+            : undefined;
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : error);
+        process.exitCode = 2;
+        return;
+    }
     // --pin and --unpin express opposite intents (set a pin vs clear it);
     // accepting both silently would make the effective pin depend on
     // internal option-resolution order, so this is a usage error rather
@@ -536,7 +624,7 @@ program
     }
     const chosenHarnesses = resolveApplyHarnesses(targetDir, repoManifest, operatorManifest.defaults);
     const previous = buildApplyPrevious(repoManifest, operatorManifest.defaults, Boolean(opts.sync));
-    const { harnesses, profile, models, tiers, opencodeModels, opencodeClassModels, warnings, } = await resolveInitInputs(
+    const { harnesses, profile, models, tiers, opencodeModels, opencodeClassModels, routing: resolvedRouting, warnings, } = await resolveInitInputs(
     // `previous` is always defined here (`buildApplyPrevious` returns a
     // synthetic object even for a target with no manifest of its own),
     // so `previousIsRecordedManifest` cannot be `Boolean(previous)`; it
@@ -557,7 +645,10 @@ program
     // `stickyAnnotateDetected`) is pinned inside `buildApplyInitInputs`
     // rather than inlined here (agent-tasks fe834823, fix round 3,
     // review finding 1).
-    buildApplyInitInputs(targetDir, chosenHarnesses, previous, interactive, opts, Boolean(repoManifest)));
+    buildApplyInitInputs(targetDir, chosenHarnesses, previous, interactive, 
+    // Explicit routing is parsed before the first target write and is
+    // the final merge layer after repo/operator sticky resolution.
+    { ...opts, routing: routingPatch }, Boolean(repoManifest)));
     for (const w of warnings) {
         process.stderr.write(`${w}\n`);
     }
@@ -588,6 +679,9 @@ program
         opencodeModels,
         tiers,
         opencodeClassModels,
+        routing: resolvedRouting,
+        routingMode: "replace",
+        codexCatalog,
         pin,
     });
     showPaths("Created", report.written);
@@ -786,6 +880,12 @@ function printTargetDetail(target, operatorVersion) {
         if (target.divergence.models) {
             console.log(`  models: ${target.divergentModelRoles.join(", ")}`);
         }
+        if (target.divergence.routing) {
+            console.log("  routing: repo and operator selections differ");
+        }
+    }
+    for (const gap of target.routingComparisonGaps ?? []) {
+        console.log(`  Routing comparison incomplete: ${gap}`);
     }
     const showsVersionLagDetail = (target.status === "version-lag" ||
         ((target.status === "divergent" || target.status === "drift") &&
@@ -823,6 +923,10 @@ function operatorDefaultsFromRepoManifest(repoManifest) {
         profile: repoManifest.profile,
         tiers: repoManifest.tiers,
         models: { ...repoManifest.models },
+        ...parseOpencodeModelMaps(repoManifest),
+        ...(repoManifest.routing !== undefined
+            ? { routing: repoManifest.routing }
+            : {}),
     };
 }
 /**

package/dist/codex.d.ts

@@ -0,0 +1,8 @@
+import type { Role, Tier } from "./models.js";
+import type { ModelSelection } from "./routing.js";
+/**
+ * Produces a standalone Codex subagent definition. The reviewer intentionally
+ * inherits its parent's sandbox: its canonical prompt prohibits source edits,
+ * while inherited access lets it create test/build output in temporary paths.
+ */
+export declare function composeCodexAgent(role: Role, selection: ModelSelection, tier?: Tier): string;

package/dist/codex.js

@@ -0,0 +1,52 @@
+import { readAgentAsset } from "./assets.js";
+function tomlString(value) {
+    let escaped = "";
+    for (let index = 0; index < value.length; index += 1) {
+        const code = value.charCodeAt(index);
+        if (code === 0x22)
+            escaped += '\\"';
+        else if (code === 0x5c)
+            escaped += "\\\\";
+        else if (code === 0x08)
+            escaped += "\\b";
+        else if (code === 0x09)
+            escaped += "\\t";
+        else if (code === 0x0a)
+            escaped += "\\n";
+        else if (code === 0x0c)
+            escaped += "\\f";
+        else if (code === 0x0d)
+            escaped += "\\r";
+        else if (code < 0x20 || code === 0x7f) {
+            escaped += `\\u${code.toString(16).padStart(4, "0")}`;
+        }
+        else {
+            escaped += value[index];
+        }
+    }
+    return `"${escaped}"`;
+}
+function descriptionForTier(description, tier) {
+    return tier === undefined
+        ? description
+        : `${description} (Effort tier: ${tier}.)`;
+}
+/**
+ * Produces a standalone Codex subagent definition. The reviewer intentionally
+ * inherits its parent's sandbox: its canonical prompt prohibits source edits,
+ * while inherited access lets it create test/build output in temporary paths.
+ */
+export function composeCodexAgent(role, selection, tier) {
+    const asset = readAgentAsset(role);
+    const lines = [
+        `name = ${tomlString(tier === undefined ? asset.name : `${asset.name}-${tier}`)}`,
+        `description = ${tomlString(descriptionForTier(asset.description, tier))}`,
+        `model = ${tomlString(selection.model)}`,
+        `model_reasoning_effort = ${tomlString(selection.effort)}`,
+    ];
+    if (role === "explorer" || role === "advisor") {
+        lines.push('sandbox_mode = "read-only"');
+    }
+    lines.push(`developer_instructions = ${tomlString(asset.body.trimEnd())}`);
+    return `${lines.join("\n")}\n`;
+}

package/dist/doctor.d.ts

@@ -24,6 +24,8 @@ export interface TargetDivergence {
     profile: boolean;
     tiers: boolean;
     models: boolean;
+    /** Present only when explicit effective routing differs. */
+    routing?: boolean;
 }
 /**
  * Per-target report. Only `path`, `status`, `installedVersion`, `pin`,
@@ -40,6 +42,8 @@ export interface TargetReport {
     pin: string | null;
     divergence: TargetDivergence | null;
     driftFiles: string[] | null;
+    /** Selected legacy opencode leaves that cannot be compared offline. */
+    routingComparisonGaps?: string[];
     /** Human-output-only: the repo's own profile, or null when unknown. */
     repoProfile: Profile | null;
     /** Human-output-only: the operator default profile, for the comparison line. */
@@ -81,6 +85,8 @@ export interface TargetReportJson {
     pin: string | null;
     divergence: TargetDivergence | null;
     driftFiles: string[] | null;
+    /** Selected legacy opencode leaves that cannot be compared offline. */
+    routingComparisonGaps?: string[];
     versionLag: boolean;
     reason: string | null;
 }