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

package/src/invocation-config.ts

@@ -1,8 +1,7 @@
 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";
+import type { AgentConfig, IsolationMode, ThinkingLevel } from "./types.js";
 
 /**
  * The model-facing `isolation` parameter, shared by the `Agent` tool and the
@@ -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
@@ -169,7 +156,3 @@ export function resolveAgentInvocationConfig(
     isolation,
   };
 }
-
-export function resolveJoinMode(defaultJoinMode: JoinMode, runInBackground: boolean): JoinMode | undefined {
-  return runInBackground ? defaultJoinMode : undefined;
-}

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,21 @@
 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 { bindChildResourceLoader, runInChildSessionContext } from "./child-context.js";
+import { errorMessage } from "./error-message.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 +143,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 +154,12 @@ export async function runMentionClone(opts: MentionCloneOptions): Promise<Mentio
       noContextFiles: true,
       systemPromptOverride: (base: string | undefined) => systemPrompt || base,
       appendSystemPromptOverride: () => [],
-    });
-    await runInChildSessionContext(() => loader.reload());
+    }, opts.homeDir);
+    await bindChildResourceLoader(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,
@@ -184,7 +189,7 @@ export async function runMentionClone(opts: MentionCloneOptions): Promise<Mentio
     // renderer produces, where the reminder trails the message it is about.
     await session.prompt(`${message}\n\n${agentMentionReminder(type)}`);
   } catch (err) {
-    return { spawned, error: err instanceof Error ? err.message : String(err) };
+    return { spawned, error: errorMessage(err) };
   } finally {
     session?.dispose?.();
   }

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,22 +41,21 @@ 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);
 }
 
 /**
  * Narrows fuzzy candidates to the models the user enabled (pi's `enabledModels`),
  * as lowercase `provider/id` keys. Injected rather than imported so this module
- * stays free of settings I/O; `undefined` means no scope is configured.
+ * stays free of settings I/O; `undefined` means no scope is configured. An
+ * unresolved dispatch passes its config root only for its diagnostic.
  */
-export type ModelScopeProvider = (registry: ModelRegistry) => ReadonlySet<string> | undefined;
+export type ModelScopeProvider = (
+  registry: ModelRegistry,
+  context?: { cwd: string; homeDir?: string },
+) => ReadonlySet<string> | undefined;
 
 let modelScopeProvider: ModelScopeProvider | undefined;
 
@@ -87,6 +87,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";
 
@@ -156,16 +190,17 @@ function compareVersionsDesc(a: ModelVersion | undefined, b: ModelVersion | unde
 export function resolveModel(
   input: string,
   registry: ModelRegistry,
+  context?: { cwd: string; homeDir?: string },
 ): any | string {
   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")}`;
   }
-  return resolveCanonicalModel(input, registry);
+  return resolveCanonicalModel(input, registry, context);
 }
 
 /**
@@ -174,20 +209,44 @@ export function resolveModel(
  * match score. A bare family name like "opus" therefore means the newest opus
  * the user has enabled, not whichever id happens to be shortest.
  */
-function rankFuzzy(matches: { entry: ModelEntry; score: number }[], registry: ModelRegistry): ModelEntry | undefined {
-  const scope = modelScopeProvider?.(registry);
-  const scoped = scope ? matches.filter(c => scope.has(`${c.entry.provider}/${c.entry.id}`.toLowerCase())) : [];
-  const pool = scoped.length > 0 ? scoped : matches;
-  const ranked = pool
+function scopedCandidates<T extends { entry: ModelEntry }>(
+  candidates: T[],
+  registry: ModelRegistry,
+  context?: { cwd: string; homeDir?: string },
+): T[] {
+  const scope = modelScopeProvider?.(registry, context);
+  const scoped = scope ? candidates.filter(candidate => scope.has(`${candidate.entry.provider}/${candidate.entry.id}`.toLowerCase())) : [];
+  return scoped.length > 0 ? scoped : candidates;
+}
+
+/** Stable tie-breaker independent of registry insertion order and locale. */
+function compareModelIdentity(a: ModelEntry, b: ModelEntry): number {
+  const left = `${a.provider}/${a.id}`;
+  const right = `${b.provider}/${b.id}`;
+  return Number(left > right) - Number(left < right);
+}
+
+function rankFuzzy(
+  matches: { entry: ModelEntry; score: number }[],
+  registry: ModelRegistry,
+  context?: { cwd: string; homeDir?: string },
+): ModelEntry | undefined {
+  const ranked = scopedCandidates(matches, registry, context)
     .map(c => ({ ...c, version: parseModelVersion(c.entry.id) }))
-    .sort((a, b) => compareVersionsDesc(a.version, b.version) || b.score - a.score);
+    .sort((a, b) => compareVersionsDesc(a.version, b.version) || b.score - a.score || compareModelIdentity(a.entry, b.entry));
   return ranked[0]?.entry;
 }
 
+/** Numeric runs stay ordered and contiguous: `5-5` cannot reuse the `5` in `4-5`. */
+function versionRuns(value: string): string[] {
+  return [...value.replace(/-\d{8}$/, "").matchAll(/(?:^|[\s-])(\d+(?:[\s-]+\d+)*)(?=$|[\s-])/g)].map(match => match[1]!.replace(/\s+/g, "-"));
+}
+
 /** Resolve an exact or fuzzy provider/model request without consulting aliases. */
 function resolveCanonicalModel(
   input: string,
   registry: ModelRegistry,
+  context?: { cwd: string; homeDir?: string },
 ): any | string {
   // Available models (those with auth configured)
   const all = (registry.getAvailable?.() ?? registry.getAll()) as ModelEntry[];
@@ -209,6 +268,7 @@ function resolveCanonicalModel(
   // "claude-haiku-4-5" (dot vs dash in the version) resolve to the same model.
   const normalize = (s: string) => s.toLowerCase().replace(/\./g, "-");
   const query = normalize(input);
+  const requestedVersions = versionRuns(query.slice(slashIdx + 1));
 
   // Score each model: prefer exact id match > id contains > name contains > provider+id contains
   const matches: { entry: ModelEntry; score: number }[] = [];
@@ -217,6 +277,12 @@ function resolveCanonicalModel(
     const id = normalize(m.id);
     const name = normalize(m.name);
     const full = normalize(`${m.provider}/${m.id}`);
+    const idVersions = versionRuns(id);
+    const versions = idVersions.length > 0 ? idVersions : versionRuns(name);
+    // Filter before scope/ranking, including substring and name matches. A
+    // major-only input can select a newer minor, but never another major or
+    // a minor token masquerading as the requested major.
+    if (!requestedVersions.every(requested => versions.some(version => version === requested || version.startsWith(`${requested}-`)))) continue;
 
     let score = 0;
     if (id === query || full === query) {
@@ -241,8 +307,9 @@ function resolveCanonicalModel(
 
   // An exact id (or provider/id) is the caller naming a model, not describing
   // one: it wins outright, whatever the scope or any newer sibling.
-  const exact = matches.find(c => c.score === 100);
-  const bestMatch = exact?.entry ?? rankFuzzy(matches, registry);
+  const exact = matches.filter(c => c.score === 100);
+  const exactBest = exact.sort((a, b) => compareModelIdentity(a.entry, b.entry))[0];
+  const bestMatch = exactBest ? exactBest.entry : rankFuzzy(matches, registry, context);
   if (bestMatch) {
     const found = registry.find(bestMatch.provider, bestMatch.id);
     if (found) return found;
@@ -253,13 +320,13 @@ function resolveCanonicalModel(
   // named provider is preferred when present; this only kicks in when it isn't,
   // so the same model from another provider beats falling back to "inherit".
   if (slashIdx !== -1) {
-    const bare = resolveCanonicalModel(input.slice(slashIdx + 1), registry);
+    const bare = resolveCanonicalModel(input.slice(slashIdx + 1), registry, context);
     if (typeof bare !== "string") return bare;
   }
 
   // 4. No match — list available models
-  const modelList = all
-    .map(m => `  ${m.provider}/${m.id}`)
+  const modelList = scopedCandidates(all.map(entry => ({ entry })), registry, context)
+    .map(({ entry }) => `  ${entry.provider}/${entry.id}`)
     .sort()
     .join("\n");
   return `Model not found: "${input}".\n\nAvailable models:\n${modelList}`;

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,170 @@
+/** One selection policy for every dispatch, independent of its transport. */
+import type { Api, Model } from "@earendil-works/pi-ai";
+import { type Clock, realClock } from "./clock.js";
+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, { cwd: request.cwd, homeDir: request.homeDir })
+        : 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) : {};
+}
+
+/** Resolved selection identity for model-facing text, not an actionable fallback warning. */
+export function modelIdentityNote(carrier: { modelSelection?: ModelSelection; modelTier?: TierDisclosure } | undefined): string {
+  const selected = carrier?.modelSelection?.model;
+  // Tier notes already carry admission/answer provenance. Literal virtual
+  // selections have no such evidence, so never claim their alias is a leaf.
+  return selected && !carrier?.modelTier
+    ? `Resolved model: ${selected.provider}/${selected.id}${isVirtualModel(selected) ? " (routing alias; physical response model: unknown)" : ""}.`
+    : "";
+}
+
+/** 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, clock: Clock = realClock, signal?: AbortSignal): 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, undefined, clock, signal),
+  });
+  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;
+  // The binding is handed to `resolveTier`, so it is never `unmapped` here.
+  if (selection.tier.kind === "unavailable") {
+    if (getModelResolution().onUnavailable === "error") throw new Error(`Model tier @${selection.tier.tier} is unavailable.`);
+    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;
+}