@nredd/pi-subagents 0.22.0-nredd.7 → 0.22.0-nredd.8

package/src/invocation-config.ts

@@ -1,7 +1,6 @@
 import { homedir } from "node:os";
 import { resolve } from "node:path";
 import { Type } from "typebox";
-import { configuredAgentModel } from "./model-resolver.js";
 import type { AgentConfig, IsolationMode, JoinMode, ThinkingLevel } from "./types.js";
 
 /**
@@ -79,13 +78,11 @@ export const cwdParam = {
  * Blank means unset: models that fill every optional parameter send `""`.
  * Existence is checked later by the manager, which re-checks at start time.
  */
-export function resolveCwdParam(cwd: string | undefined, sessionCwd: string): string | undefined {
+export function resolveCwdParam(cwd: string | undefined, sessionCwd: string, homeDir = homedir()): string | undefined {
   const trimmed = cwd?.trim();
   if (!trimmed) return undefined;
-  // Bun 1.3 ignores HOME in os.homedir(); honor the same explicit override as Node.
-  const home = process.env[process.platform === "win32" ? "USERPROFILE" : "HOME"] || homedir();
-  if (trimmed === "~") return home;
-  if (trimmed.startsWith("~/")) return resolve(home, trimmed.slice(2));
+  if (trimmed === "~") return homeDir;
+  if (trimmed.startsWith("~/")) return resolve(homeDir, trimmed.slice(2));
   return resolve(sessionCwd, trimmed);
 }
 
@@ -107,8 +104,6 @@ interface AgentInvocationParams {
 }
 
 interface ResolveOptions {
-  /** The resolved agent type, for the `agentModels` lookup. Omitted → only the `"*"` entry applies. */
-  agentType?: string;
   /**
    * Whether worktree isolation is permitted at all. False when the project set
    * `worktreeIsolation: false`, which drops a requested worktree rather than
@@ -135,8 +130,6 @@ export function resolveAgentInvocationConfig(
   params: AgentInvocationParams,
   opts?: ResolveOptions,
 ): {
-  modelInput?: string;
-  modelFromParams: boolean;
   thinking?: ThinkingLevel;
   maxTurns?: number;
   inheritContext: boolean;
@@ -151,12 +144,6 @@ export function resolveAgentInvocationConfig(
   const isolation = requested === "worktree" && opts?.worktreeAllowed !== false ? "worktree" : undefined;
 
   return {
-    // A frontmatter model is a portable default, not a policy boundary. An
-    // explicit model on the Agent call must win so an orchestrator can select a
-    // specific model (e.g. a `router/*` virtual model) for this dispatch. Below
-    // it, the global `agentModels` setting outranks the definition's own default.
-    modelInput: params.model ?? configuredAgentModel(opts?.agentType ?? agentConfig?.name ?? "", agentConfig?.model),
-    modelFromParams: params.model != null,
     // A specialist's frontmatter is a reusable default, not a policy boundary:
     // an explicit dispatch chooses the effort for this run. Pi still clamps the
     // selected level to the resolved model, and agent-manager records that

package/src/memory.ts

@@ -13,8 +13,8 @@
 
 import { existsSync, lstatSync, mkdirSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { join, } from "node:path";
-import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { join } from "node:path";
+import { resolveAgentDir } from "./home-paths.js";
 import type { MemoryScope } from "./types.js";
 
 /** Maximum lines to read from MEMORY.md */
@@ -58,17 +58,17 @@ export function safeReadFile(filePath: string): string | undefined {
  * Resolve the memory directory path for a given agent + scope + cwd.
  * Throws if agentName contains path traversal characters.
  */
-export function resolveMemoryDir(agentName: string, scope: MemoryScope, cwd: string): string {
+export function resolveMemoryDir(agentName: string, scope: MemoryScope, cwd: string, homeDir = homedir()): string {
   if (isUnsafeName(agentName)) {
     throw new Error(`Unsafe agent name for memory directory: "${agentName}"`);
   }
   switch (scope) {
     case "user": {
-      const current = join(getAgentDir(), "agent-memory", agentName);
+      const current = join(resolveAgentDir(homeDir), "agent-memory", agentName);
       // Legacy location from when this path was hardcoded. Keep using it if it
       // already holds this agent's memory and the new location hasn't been
       // created yet — otherwise existing memories would be silently orphaned.
-      const legacy = join(homedir(), ".pi", "agent-memory", agentName);
+      const legacy = join(homeDir, ".pi", "agent-memory", agentName);
       if (!existsSync(current) && existsSync(legacy) && !isSymlink(legacy)) {
         return legacy;
       }
@@ -120,8 +120,8 @@ export function readMemoryIndex(memoryDir: string): string | undefined {
  * Build the memory block to inject into the agent's system prompt.
  * Also ensures the memory directory exists (creates it if needed).
  */
-export function buildMemoryBlock(agentName: string, scope: MemoryScope, cwd: string): string {
-  const memoryDir = resolveMemoryDir(agentName, scope, cwd);
+export function buildMemoryBlock(agentName: string, scope: MemoryScope, cwd: string, homeDir = homedir()): string {
+  const memoryDir = resolveMemoryDir(agentName, scope, cwd, homeDir);
   // Create the memory directory so the agent can immediately write to it
   ensureMemoryDir(memoryDir);
 
@@ -162,8 +162,8 @@ This memory persists across sessions. Use it to build up knowledge over time.`;
  * Build a read-only memory block for agents that lack write/edit tools.
  * Does NOT create the memory directory — agents can only consume existing memory.
  */
-export function buildReadOnlyMemoryBlock(agentName: string, scope: MemoryScope, cwd: string): string {
-  const memoryDir = resolveMemoryDir(agentName, scope, cwd);
+export function buildReadOnlyMemoryBlock(agentName: string, scope: MemoryScope, cwd: string, homeDir = homedir()): string {
+  const memoryDir = resolveMemoryDir(agentName, scope, cwd, homeDir);
   const existingMemory = readMemoryIndex(memoryDir);
 
   const header = `# Agent Memory (read-only)

package/src/mention-clone.ts

@@ -56,18 +56,20 @@
 import type { Model } from "@earendil-works/pi-ai";
 import {
   createAgentSession,
-  DefaultResourceLoader,
   type ExtensionContext,
   type ExtensionToolContext,
-  getAgentDir,
   SessionManager,
   type ToolDefinition,
 } from "@earendil-works/pi-coding-agent";
 import { runInChildSessionContext } from "./child-context.js";
+import { resolveAgentDir } from "./home-paths.js";
 import { agentMentionReminder } from "./mention.js";
+import { createHomeResourceLoader } from "./resource-loader.js";
 import type { SubagentType } from "./types.js";
 
 export interface MentionCloneOptions {
+  /** Home directory for the clone's user resources and settings. */
+  homeDir?: string;
   /** The MAIN session's context — what the spawn is attributed to, and the
    * source of both the conversation and the live system prompt. */
   ctx: ExtensionContext;
@@ -140,9 +142,10 @@ export async function runMentionClone(opts: MentionCloneOptions): Promise<Mentio
     // would add on top (AGENTS.md, skills, APPEND_SYSTEM.md) is already in the
     // rendered prompt, so it is suppressed, as agent-runner does.
     const systemPrompt = ctx.getSystemPrompt();
-    const loader = new DefaultResourceLoader({
+    const agentDir = resolveAgentDir(opts.homeDir);
+    const loader = createHomeResourceLoader({
       cwd: ctx.cwd,
-      agentDir: getAgentDir(),
+      agentDir,
       noExtensions: true,
       noSkills: true,
       noPromptTemplates: true,
@@ -150,11 +153,12 @@ export async function runMentionClone(opts: MentionCloneOptions): Promise<Mentio
       noContextFiles: true,
       systemPromptOverride: (base: string | undefined) => systemPrompt || base,
       appendSystemPromptOverride: () => [],
-    });
+    }, opts.homeDir);
     await runInChildSessionContext(() => loader.reload());
     const created = await runInChildSessionContext(() =>
       createAgentSession({
         cwd: ctx.cwd,
+        agentDir,
         // The parent's root-to-leaf path, which the clone projects itself:
         // compaction applied, branch summaries substituted. Not `getEntries()`,
         // whose last entry is not the leaf after `/tree` navigation. In memory,

package/src/model-resolver.ts

@@ -1,6 +1,7 @@
 /**
- * Model resolution: exact match ("provider/modelId") with fuzzy fallback.
+ * Model resolution: exact match ("provider/modelId") with fuzzy fallback for tool inputs.
  */
+import { exactTierModel } from "./model-tiers.js";
 
 export interface ModelEntry {
   id: string;
@@ -40,14 +41,9 @@ export function setAgentModels(models: Record<string, string> | undefined): void
   agentModels = new Map(Object.entries(models ?? {}).map(([type, model]) => [type.toLowerCase(), model]));
 }
 
-/**
- * The model input a spawn of `type` should use when the caller named none:
- * `agentModels[type]`, then `agentModels["*"]`, then the agent definition's own
- * `model:` (`definitionModel`). The parent model is the floor, applied by the
- * caller when this returns `undefined`.
- */
-export function configuredAgentModel(type: string, definitionModel: string | undefined): string | undefined {
-  return agentModels.get(type.toLowerCase()) ?? agentModels.get("*") ?? definitionModel;
+/** A snapshot for the shared selection policy; callers cannot mutate configuration. */
+export function getAgentModels(): ReadonlyMap<string, string> {
+  return new Map(agentModels);
 }
 
 /**
@@ -87,6 +83,40 @@ export function describeModel(
   };
 }
 
+/**
+ * A CONFIG model (`agentModels`, an agent's `model:`, a stored job's model) that
+ * did not resolve, so the spawn ran on the parent model instead. Recorded once on
+ * the `AgentRecord` by the shared spawn path; every surface reads it from there.
+ */
+export interface ModelFallback {
+  /** The configured input that failed to resolve. */
+  input: string;
+  /** Further configured inputs that also failed (e.g. a stored job model AND an `agentModels` override). */
+  also?: string[];
+  /** `provider/id` of the model actually used; absent when the session default (a parent with no model) ran. */
+  used?: string;
+  /** Whose model `used` is: the parent's (default) or the agent's own configured model (`agentModels` / definition `model:`), which took over from an unresolved stored model. */
+  via?: "parent" | "agent";
+}
+
+/** The fallback outcome for `input` when the spawn ran on `parent`. */
+export function modelFallbackTo(input: string, parent: { provider: string; id: string } | undefined): ModelFallback {
+  return parent ? { input, used: `${parent.provider}/${parent.id}` } : { input };
+}
+
+/**
+ * The disclosure line for a fallback: same `Note:` prefix as the unknown-agent-type
+ * note. Empty string when there was none, so callers can concatenate it blindly.
+ */
+export function modelFallbackNote(fallback: ModelFallback | undefined): string {
+  if (!fallback) return "";
+  const whose = fallback.via === "agent" ? "the agent's own model" : "parent model";
+  const used = fallback.used ? `${whose} ${fallback.used}` : "the session default model";
+  const inputs = [fallback.input, ...(fallback.also ?? [])];
+  const named = inputs.length === 1 ? `model "${inputs[0]}" did` : `models ${inputs.map(i => `"${i}"`).join(", ")} did`;
+  return `Note: configured ${named} not resolve; running on ${used}.`;
+}
+
 /** API id pi gives virtual catalog entries such as `router/default`; they never reach a provider. */
 const VIRTUAL_MODEL_API = "pi-virtual";
 
@@ -160,8 +190,8 @@ export function resolveModel(
   const aliasCandidates = modelAliases.get(input.trim().toLowerCase());
   if (aliasCandidates) {
     for (const candidate of aliasCandidates) {
-      const resolved = resolveCanonicalModel(candidate, registry);
-      if (typeof resolved !== "string") return resolved;
+      const resolved = exactTierModel(candidate, registry);
+      if (resolved) return resolved;
     }
     return `Model alias "${input}" has no available candidate.\n\nCandidates:\n${aliasCandidates.map(candidate => `  ${candidate}`).join("\n")}`;
   }

package/src/model-scope.ts

@@ -39,6 +39,7 @@ export type ModelScopeVerdict =
  *     user authored/installed this agent or chose the parent's model; trust it).
  */
 export function checkModelScope(args: {
+  homeDir?: string;
   model: { provider: string; id: string } | undefined;
   cwd: string;
   modelRegistry: ModelRegistryRef;
@@ -52,7 +53,7 @@ export function checkModelScope(args: {
   const { model, cwd, modelRegistry, callerSupplied, agentLabel, modelInput } = args;
   if (!scopeModelsEnabled || !model) return { kind: "ok" };
 
-  const allowed = resolveEnabledModels(readEnabledModels(cwd), modelRegistry, cwd);
+  const allowed = resolveEnabledModels(readEnabledModels(cwd, args.homeDir), modelRegistry, cwd, args.homeDir);
   if (!allowed || isModelInScope(model, allowed)) return { kind: "ok" };
 
   if (callerSupplied) {

package/src/model-selection.ts

@@ -0,0 +1,159 @@
+/** One selection policy for every dispatch, independent of its transport. */
+import type { Api, Model } from "@earendil-works/pi-ai";
+import { describeModel, describeVirtualModel, getAgentModels, getModelAliases, isVirtualModel, type ModelFallback, type ModelRegistry, modelFallbackNote, modelFallbackTo, resolveModel } from "./model-resolver.js";
+import { checkModelScope } from "./model-scope.js";
+import { exactTierModel, getModelResolution, parseTierBinding, resolveTier, type TierBinding, type TierDisclosure, type TierOutcome, tierBinding, tierNote } from "./model-tiers.js";
+import { type AdmissionEvents, admissionOutcome, type QuotaBlock } from "./quota-admission.js";
+
+/** Exact compatibility pins for user-defined legacy Explore definitions. User aliases win. */
+const LEGACY_MODEL_PINS = new Map([
+  ["claude-haiku-4-5", "anthropic/claude-haiku-4-5"],
+]);
+
+/** The winning precedence level, before resolution or fallback. */
+export type ModelSource = "param" | "agentModels:type" | "agentModels:*" | "definition" | "parent";
+
+/** Keep the original request even when it could not be resolved. */
+export interface ModelSelection {
+  requested?: string;
+  source: ModelSource;
+  model: Model<Api> | undefined;
+  outcome: "resolved" | "inherited" | "fallback";
+  fallback?: ModelFallback;
+  scopeWarning?: string;
+  /** Serializable tier provenance, retained when the answering model changes. */
+  tier?: TierOutcome;
+  /** A prepared binding is resolved with admission before starting the child. */
+  tierBinding?: TierBinding;
+  tierAdmitted?: boolean;
+  /** Startup-only parent floor if credentials/profile disappear between preflight and admission. */
+  tierParent?: Model<Api>;
+}
+
+/** Choose the input once: explicit parameter > type > wildcard > definition; blank strings are unset. */
+export function modelRequest(type: string, definitionModel?: string, paramModel?: string | Model<Api> | null): {
+  requested?: string;
+  source: ModelSource;
+} {
+  if (paramModel != null && (typeof paramModel !== "string" || paramModel.trim() !== "")) {
+    return { requested: typeof paramModel === "string" ? paramModel : `${paramModel.provider}/${paramModel.id}`, source: "param" };
+  }
+  const overrides = getAgentModels();
+  const typed = overrides.get(type.toLowerCase());
+  if (typed?.trim()) return { requested: typed, source: "agentModels:type" };
+  const wildcard = overrides.get("*");
+  if (wildcard?.trim()) return { requested: wildcard, source: "agentModels:*" };
+  if (definitionModel?.trim()) return { requested: definitionModel, source: "definition" };
+  return { source: "parent" };
+}
+
+/**
+ * Choose an exact configured input or tier binding before record creation.
+ * Only explicit non-tier tool inputs retain fuzzy matching. Tier admission is
+ * asynchronous and completes through admitModelSelection before startup; this
+ * synchronous preflight preserves spawn's immediate-id and validation contract.
+ * An already-open resume keeps the record and does not select again.
+ */
+export function selectModel(request: {
+  homeDir?: string;
+  agentType: string;
+  definitionModel?: string;
+  paramModel?: string | Model<Api> | null;
+  parentModel: Model<Api> | undefined;
+  registry: ModelRegistry;
+  cwd: string;
+  agentLabel?: string;
+}): ModelSelection | string {
+  const input = modelRequest(request.agentType, request.definitionModel, request.paramModel);
+  let selection: ModelSelection = { ...input, model: request.parentModel, outcome: "inherited" };
+  if (input.requested) {
+    const requested = input.requested.trim();
+    const legacy = getModelAliases().get(requested.toLowerCase());
+    const legacyBinding = legacy ? parseTierBinding("legacy", legacy) : undefined;
+    // Preserve existing enterprise manifests during the built-in Explore migration.
+    // An explicit cheap binding always wins, even when it is unavailable.
+    const cheapCompatibility = requested === "@cheap" && request.agentType === "Explore"
+      && input.source === "definition"
+      ? parseTierBinding("cheap", getModelAliases().get("claude-haiku-4-5")) : undefined;
+    const binding = requested.startsWith("@") ? tierBinding(requested.slice(1)) ?? cheapCompatibility
+      : legacyBinding ? { ...legacyBinding, tier: requested } : undefined;
+    if (requested.startsWith("@") || legacy) {
+      const tier = requested.startsWith("@") ? requested.slice(1) : requested;
+      const refs = binding?.kind === "routed" ? [binding.profile] : binding?.members ?? [];
+      const model = refs.map(ref => exactTierModel(ref, request.registry)).find(Boolean);
+      if (!binding || !model) {
+        const outcome: TierOutcome = binding ? { kind: "unavailable", tier, tried: refs } : { kind: "unmapped", tier };
+        const mode = outcome.kind === "unmapped" ? getModelResolution().onUnmapped : getModelResolution().onUnavailable;
+        if (mode === "error") return `Model tier @${tier} is ${outcome.kind}.`;
+        selection = { ...selection, tier: outcome, outcome: "fallback", fallback: modelFallbackTo(input.requested, request.parentModel) };
+      } else {
+        selection = { ...input, model, outcome: "resolved", tierBinding: binding, tierParent: request.parentModel };
+      }
+    } else {
+      const compatibilityPin = input.source === "definition" && request.agentType === "Explore"
+        ? LEGACY_MODEL_PINS.get(requested) : undefined;
+      const resolved = request.paramModel != null && typeof request.paramModel === "object"
+        ? request.paramModel : input.source === "param" ? resolveModel(requested, request.registry)
+        : exactTierModel(compatibilityPin ?? requested, request.registry) ?? `Model not found: "${requested}".`;
+      if (typeof resolved !== "string") selection = { ...input, model: resolved, outcome: "resolved" };
+      else if (compatibilityPin) {
+        const tier: TierOutcome = { kind: "unavailable", tier: requested, tried: [compatibilityPin] };
+        if (getModelResolution().onUnavailable === "error") return `Model tier @${requested} is unavailable.`;
+        selection = { ...selection, tier, outcome: "fallback", fallback: modelFallbackTo(input.requested, request.parentModel) };
+      } else {
+        if (input.source === "param" || getModelResolution().onUnavailable === "error") return resolved;
+        selection = { ...selection, outcome: "fallback", fallback: modelFallbackTo(input.requested, request.parentModel) };
+      }
+    }
+  }
+  const scope = checkModelScope({
+    model: selection.model, cwd: request.cwd, modelRegistry: request.registry,
+    callerSupplied: input.source === "param" && !selection.tierBinding && !selection.tier, agentLabel: request.agentLabel ?? request.agentType,
+    modelInput: input.requested, homeDir: request.homeDir,
+  });
+  if (scope.kind === "error") return scope.message;
+  if (scope.kind === "warn") selection.scopeWarning = scope.message;
+  return selection;
+}
+
+/** Label an admitted physical model before any response, without replacing the virtual selection. */
+export function describeSelection(selection: ModelSelection | undefined, registry: ModelRegistry): { modelName?: string; modelId?: string } {
+  const admitted = selection?.tier?.kind === "routed" ? selection.tier.admitted : undefined;
+  if (admitted) {
+    const slash = admitted.indexOf("/");
+    const provider = admitted.slice(0, slash);
+    const id = admitted.slice(slash + 1);
+    return describeModel(registry.find(provider, id) ?? { provider, id });
+  }
+  const model = selection?.model;
+  return model ? isVirtualModel(model) ? describeVirtualModel(model) : describeModel(model) : {};
+}
+
+/** One disclosure for records, persisted details, workflows and notices. */
+export function modelSelectionNote(carrier: { modelTier?: TierDisclosure; modelFallback?: ModelFallback; invocation?: { modelId?: string } } | undefined): string {
+  const tier = carrier?.modelTier;
+  const fallback = carrier?.modelFallback;
+  const sameRequest = tier && (fallback?.input === tier.tier || fallback?.input === `@${tier.tier}`);
+  return [tierNote(tier, carrier?.invocation?.modelId), sameRequest ? "" : modelFallbackNote(fallback)].filter(Boolean).join("\n");
+}
+
+/** Admission for tiers is made once and is shared by every transport. */
+export async function admitModelSelection(selection: ModelSelection, registry: ModelRegistry, events: AdmissionEvents): Promise<QuotaBlock | undefined> {
+  if (!selection.tierBinding || selection.tierAdmitted) return selection.tier?.kind === "exhausted" ? selection.tier.block : undefined;
+  selection.tier = await resolveTier(selection.tierBinding.tier, {
+    registry, binding: selection.tierBinding, admit: ref => admissionOutcome(events, ref),
+  });
+  selection.tierAdmitted = true;
+  if (selection.tier.kind === "routed" || selection.tier.kind === "static") selection.model = selection.tier.model;
+  if (selection.tier.kind === "exhausted") return selection.tier.block;
+  if (selection.tier.kind === "unavailable" || selection.tier.kind === "unmapped") {
+    const mode = selection.tier.kind === "unmapped" ? getModelResolution().onUnmapped : getModelResolution().onUnavailable;
+    if (mode === "error") throw new Error(`Model tier @${selection.tier.tier} is ${selection.tier.kind}.`);
+    selection.model = selection.tierParent;
+    selection.outcome = "fallback";
+    selection.fallback = modelFallbackTo(selection.requested ?? `@${selection.tier.tier}`, selection.tierParent);
+    delete selection.tierBinding;
+  }
+  delete selection.tierParent;
+  return undefined;
+}

package/src/model-tiers.ts

@@ -0,0 +1,171 @@
+/** Exact, provider-neutral model tiers. Router profiles retain ownership of failover. */
+import type { Api, Model } from "@earendil-works/pi-ai";
+import type { ModelRegistry } from "./model-resolver.js";
+import type { QuotaBlock } from "./quota-admission.js";
+
+/** One registered router profile OR an ordered exact physical chain, never both. */
+export type TierBinding =
+  | { kind: "routed"; tier: string; profile: string }
+  | { kind: "static"; tier: string; members: string[] };
+
+/** Why an earlier static member could not be selected. */
+interface TierSkip {
+  ref: string;
+  why: "no-credentials" | "quota";
+}
+
+/** Resolution is explicit even when no model can run; callers never guess a neighbouring tier. */
+export type TierOutcome =
+  | { kind: "routed"; tier: string; model: Model<Api>; profile: string; admitted?: string; answered?: string }
+  | { kind: "static"; tier: string; model: Model<Api>; member: string; skipped: TierSkip[]; quotaSignal: boolean; answered?: string }
+  | { kind: "unmapped"; tier: string }
+  | { kind: "unavailable"; tier: string; tried: string[] }
+  | { kind: "exhausted"; tier: string; block: QuotaBlock; skipped: TierSkip[] };
+
+/** Persist identity and decisions, never provider URLs, headers or credential-bearing model overlays. */
+export type TierDisclosure = TierOutcome extends infer Outcome
+  ? Outcome extends { model: Model<Api> } ? Omit<Outcome, "model"> & { model: Pick<Model<Api>, "provider" | "id" | "name" | "api"> } : Outcome
+  : never;
+
+/** Project a runtime outcome onto its credential-free persisted shape. */
+export function tierDisclosure(outcome: TierDisclosure): TierDisclosure {
+  if (outcome.kind !== "routed" && outcome.kind !== "static") return outcome;
+  const { provider, id, name, api } = outcome.model;
+  return { ...outcome, model: { provider, id, name, api } };
+}
+
+/** Trusted policy for configuration failures; quota exhaustion is handled separately. */
+export interface ModelResolution {
+  onUnmapped?: "error" | "inherit";
+  onUnavailable?: "error" | "inherit";
+}
+
+/** Admission metadata includes the physical label and distinguishes fail-open from measured admission. */
+export interface TierAdmission {
+  block?: QuotaBlock;
+  resolvedModel?: string;
+  quotaSignal: boolean;
+}
+
+const TIER_NAME = /^[a-z0-9][a-z0-9._-]*$/;
+const MODEL_REF = /^[^\s/]+\/\S+$/;
+let bindings: Record<string, string[]> = {};
+let policy: ModelResolution = {};
+
+/** Reject the entire binding, never silently shorten a malformed chain. */
+export function parseTierBinding(tier: string, members: unknown): TierBinding | undefined {
+  if (tier.trim() !== tier || !TIER_NAME.test(tier) || !Array.isArray(members) || members.length === 0
+    || members.some(ref => typeof ref !== "string" || ref.trim() !== ref || !MODEL_REF.test(ref))) return undefined;
+  const refs = members as string[];
+  if (refs.some(ref => ref.startsWith("router/"))) {
+    return refs.length === 1 ? { kind: "routed", tier, profile: refs[0]! } : undefined;
+  }
+  return { kind: "static", tier, members: [...refs] };
+}
+
+/** Settings have already been validated at the trusted global boundary. */
+export function setModelTiers(tiers: Record<string, string[]> | undefined, resolution: ModelResolution | undefined): void {
+  bindings = Object.fromEntries(Object.entries(tiers ?? {}).map(([key, refs]) => [key, [...refs]]));
+  policy = { ...resolution };
+}
+
+/** Return a snapshot; missing policies mean inherit with disclosure. */
+export function getModelResolution(): ModelResolution {
+  return { ...policy };
+}
+
+/** A missing or malformed name is unmapped, including bare @ and mixed case. */
+export function tierBinding(tier: string): TierBinding | undefined {
+  return parseTierBinding(tier, bindings[tier]);
+}
+
+/** Exact lookup independent of enabledModels, version ranking and provider retry. */
+export function exactTierModel(ref: string, registry: ModelRegistry): Model<Api> | undefined {
+  if (ref.trim() !== ref || !MODEL_REF.test(ref)) return undefined;
+  const slash = ref.indexOf("/");
+  const found = registry.find(ref.slice(0, slash), ref.slice(slash + 1)) as Model<Api> | undefined;
+  if (!found) return undefined;
+  if (ref.startsWith("router/")) return found.api === "pi-virtual" ? found : undefined;
+  const available = registry.getAvailable?.() ?? registry.getAll();
+  return available.some(model => model.provider === found.provider && model.id === found.id) ? found : undefined;
+}
+
+/** Resolve once per dispatch; a refused routed tier never tries another profile. */
+export async function resolveTier(tier: string, deps: {
+  registry: ModelRegistry;
+  admit: (ref: string) => Promise<TierAdmission>;
+  binding?: TierBinding;
+}): Promise<TierOutcome> {
+  const binding = deps.binding ?? tierBinding(tier);
+  if (!binding) return { kind: "unmapped", tier };
+  if (binding.kind === "routed") {
+    const model = exactTierModel(binding.profile, deps.registry);
+    if (!model) return { kind: "unavailable", tier, tried: [binding.profile] };
+    const admission = await deps.admit(binding.profile);
+    if (admission.block) return { kind: "exhausted", tier, block: admission.block, skipped: [] };
+    return { kind: "routed", tier, model, profile: binding.profile, admitted: admission.resolvedModel };
+  }
+  const skipped: TierSkip[] = [];
+  const blocks: QuotaBlock[] = [];
+  for (const member of binding.members) {
+    const model = exactTierModel(member, deps.registry);
+    if (!model) {
+      skipped.push({ ref: member, why: "no-credentials" });
+      continue;
+    }
+    const admission = await deps.admit(member);
+    if (admission.block) {
+      skipped.push({ ref: member, why: "quota" });
+      blocks.push(admission.block);
+      continue;
+    }
+    return { kind: "static", tier, model, member, skipped, quotaSignal: admission.quotaSignal };
+  }
+  if (blocks.length) {
+    // Wait only if every refusal permits it. Unknown resets must not invent a wake time.
+    const resets = blocks.flatMap(block => block.resetAt === undefined ? [] : [block.resetAt]);
+    return { kind: "exhausted", tier, skipped, block: {
+      model: `@${tier}`, wait: blocks.every(block => block.wait !== false),
+      resetAt: resets.length ? Math.min(...resets) : undefined,
+    } };
+  }
+  return { kind: "unavailable", tier, tried: [...binding.members] };
+}
+
+/** Validate stored provenance without re-resolving a historical request against today's registry. */
+export function isTierDisclosure(raw: unknown): raw is TierDisclosure {
+  if (!raw || typeof raw !== "object") return false;
+  const value = raw as Record<string, unknown>;
+  if (typeof value.tier !== "string") return false;
+  if (value.kind === "unmapped") return true;
+  if (value.kind === "unavailable") return Array.isArray(value.tried) && value.tried.every(ref => typeof ref === "string");
+  const skipsValid = Array.isArray(value.skipped) && value.skipped.every(skip => skip && typeof skip === "object"
+    && typeof skip.ref === "string" && (skip.why === "quota" || skip.why === "no-credentials"));
+  if (value.kind === "exhausted") {
+    const block = value.block as QuotaBlock | undefined;
+    return skipsValid && !!block && typeof block.model === "string"
+      && (block.wait === undefined || typeof block.wait === "boolean")
+      && (block.resetAt === undefined || (typeof block.resetAt === "number" && Number.isFinite(block.resetAt)));
+  }
+  const model = value.model as Partial<Model<Api>> | undefined;
+  if (!model || typeof model.provider !== "string" || typeof model.id !== "string"
+    || typeof model.name !== "string" || typeof model.api !== "string") return false;
+  if (value.answered !== undefined && typeof value.answered !== "string") return false;
+  if (value.kind === "routed") return typeof value.profile === "string" && value.profile.startsWith("router/")
+    && (value.admitted === undefined || typeof value.admitted === "string");
+  return value.kind === "static" && typeof value.member === "string" && skipsValid && typeof value.quotaSignal === "boolean";
+}
+
+/** Durable one-line disclosure, also useful before the first assistant response. */
+export function tierNote(outcome: TierDisclosure | undefined, answering?: string): string {
+  if (!outcome) return "";
+  const tier = `@${outcome.tier}`;
+  const answered = answering ?? ((outcome.kind === "routed" || outcome.kind === "static") ? outcome.answered : undefined);
+  switch (outcome.kind) {
+    case "routed": return `Model: ${tier} -> ${answered ?? outcome.admitted ?? outcome.profile} via ${outcome.profile}${answered && outcome.admitted && answered !== outcome.admitted ? ` (switched from ${outcome.admitted} within tier)` : ""}`;
+    case "static": return `Model: ${tier} -> ${answered ?? outcome.member} (static${outcome.quotaSignal ? "" : "; no quota signal"})${outcome.skipped.length ? `; skipped ${outcome.skipped.map(skip => `${skip.ref}: ${skip.why}`).join(", ")}` : ""}`;
+    case "unmapped": return `Note: model tier ${tier} is unmapped; inheriting the parent model.`;
+    case "unavailable": return `Note: model tier ${tier} is unavailable; inheriting the parent model.`;
+    case "exhausted": return `Model: ${tier} is exhausted.`;
+  }
+}