pi-background-tasks 0.9.0 → 1.0.4

package/src/core/fusion/artifacts.ts

@@ -27,13 +27,13 @@ import {
   type FusionWorkflowId,
   type ResolvedFusionModels,
 } from './types.js';
-import { FUSION_BRAINSTORM_WORKFLOW, type FusionWorkflowProfile } from './workflows.js';
+import { fusionWorkflowProfile, type FusionWorkflowProfile } from './workflows.js';
 
 /**
  * Run ids are prefixed by workflow so an artifact directory is self-describing.
  * The prefix set is closed: an unknown prefix must fail rather than be accepted.
  */
-const RUN_ID_PATTERN = /^[fv][0-9a-f]{32}$/;
+const RUN_ID_PATTERN = /^(reason|investigate|research|validate)-[0-9a-f]{32}$/;
 
 interface MutableFusionArtifactManifest {
   schema_version: typeof FUSION_MANIFEST_SCHEMA_VERSION;
@@ -56,6 +56,8 @@ interface MutableFusionArtifactManifest {
     evaluation: FusionCapability;
     merge: FusionCapability;
   };
+  context: { kind: import('./types.js').FusionContextKind; policy_id: string; ledger_artifact?: string; source_policy_artifact?: string };
+  tool_policy: { candidate_tools: readonly string[]; evaluation_tools: readonly []; merge_tools: readonly [] };
   usage: FusionUsage;
   attempts: FusionAttemptArtifactRecord[];
   artifacts: Record<string, FusionArtifactRef>;
@@ -177,6 +179,8 @@ function publicManifest(manifest: MutableFusionArtifactManifest): FusionArtifact
     config: manifest.config,
     models: manifest.models,
     capabilities: manifest.capabilities,
+    context: { ...manifest.context },
+    tool_policy: { candidate_tools: [...manifest.tool_policy.candidate_tools], evaluation_tools: [], merge_tools: [] },
     usage: cloneFusionUsage(manifest.usage),
     attempts: [...manifest.attempts],
     artifacts: { ...manifest.artifacts },
@@ -204,6 +208,14 @@ function calibrationViolationName(prefix: string): string {
   return `${prefix}.calibration-violation.json`;
 }
 
+function artifactRefSha256Hex(value: string): string {
+  const hex = value.startsWith('sha256:') ? value.slice('sha256:'.length) : value;
+  if (!/^[0-9a-f]{64}$/u.test(hex)) {
+    throw errorForArtifact(`fusion artifact sha256 is not a lowercase hex digest: ${value}`);
+  }
+  return hex;
+}
+
 export class FusionArtifactStore {
   private readonly runDirAbs: string;
   private readonly runDirDisplay: string;
@@ -224,7 +236,7 @@ export class FusionArtifactStore {
   }
 
   static async create(options: CreateFusionArtifactStoreOptions): Promise<FusionArtifactStore> {
-    const profile = options.profile ?? FUSION_BRAINSTORM_WORKFLOW;
+    const profile = fusionWorkflowProfile(options.profile?.id ?? 'reason');
     const runId = options.runId ?? makeRunId(profile);
     if (!RUN_ID_PATTERN.test(runId)) throw errorForArtifact(`invalid fusion run id: ${runId}`);
     if (!runId.startsWith(profile.runIdPrefix)) {
@@ -257,6 +269,8 @@ export class FusionArtifactStore {
         evaluation: 'reason',
         merge: 'reason',
       },
+      context: { kind: profile.contextKind, policy_id: profile.contextKind === 'session_projection' ? 'fusion-session-projection-v1' : 'fusion-clean-task-v1' },
+      tool_policy: { candidate_tools: profile.candidateTools, evaluation_tools: [], merge_tools: [] },
       usage: cloneFusionUsage(EMPTY_FUSION_USAGE),
       attempts: [],
       artifacts: {},
@@ -331,7 +345,23 @@ export class FusionArtifactStore {
    * while the full omission accounting stays locally auditable.
    */
   async writeContextLedger(ledger: FusionContextOmissionLedgerV2): Promise<void> {
-    await this.writeArtifact('context-omission-ledger.json', canonicalJson(ledger));
+    const ref = await this.writeArtifact('context-omission-ledger.json', canonicalJson(ledger));
+    await this.updateManifest((manifest) => {
+      manifest.context.ledger_artifact = ref.path;
+    });
+  }
+
+  async writeSourcePolicy(serialized: string): Promise<void> {
+    const ref = await this.writeArtifact('source-policy.private.json', serialized);
+    await this.updateManifest((manifest) => {
+      manifest.context.source_policy_artifact = ref.path;
+    });
+  }
+
+  sourcePolicyLaunchReference(): { path: string; sha256: string } {
+    const ref = this.manifest.artifacts['source-policy.private.json'];
+    if (ref === undefined) throw errorForArtifact('research source policy has not been written');
+    return { path: this.artifactPath(ref.path), sha256: artifactRefSha256Hex(ref.sha256) };
   }
 
   /** Route capacities and the pre-candidate whole-workflow feasibility decision. */

package/src/core/fusion/budget.ts

@@ -22,12 +22,11 @@ import {
   buildMergePrompt,
   type AnonymousFusionCandidate,
 } from './prompts.js';
-import { FUSION_BRAINSTORM_WORKFLOW, type FusionWorkflowProfile } from './workflows.js';
+import { FUSION_REASON_WORKFLOW, type FusionWorkflowProfile } from './workflows.js';
 import {
   FUSION_BUDGET_PLAN_SCHEMA_VERSION,
   FUSION_CALIBRATION_VIOLATION_SCHEMA_VERSION,
   FUSION_EVALUATION_SCHEMA_VERSION,
-  FUSION_DEFAULT_CAPABILITY,
   FusionError,
   type FusionBudgetBlocker,
   type FusionBudgetCheckKind,
@@ -102,18 +101,61 @@ export const FUSION_BUDGET_POLICY: FusionBudgetPolicyDescriptor = {
   utilization_warning_threshold_basis_points: FUSION_UTILIZATION_WARNING_THRESHOLD_BASIS_POINTS,
 };
 
-const EMPTY_REMEDIATION: readonly string[] = Object.freeze([
-  'Start a fresh Pi conversation, or run Fusion earlier in the session.',
-  "Raise the route's context window with a larger-context model via /fusion-models.",
-  'Restate only the required prior findings as visible conversation text.',
+const REASON_EMPTY_REMEDIATION: readonly string[] = Object.freeze([
+  'Start a fresh Pi conversation, or run fusion_reason earlier in the session.',
+  "Raise the route's context window with a larger-context subscription model via /fusion-models.",
+  'Restate only the required prior findings in the fusion_reason prompt.',
 ]);
 
-const REQUEST_REMEDIATION: readonly string[] = Object.freeze([
-  'Provide a shorter, self-contained fusion_brainstorm prompt.',
-  'Start a fresh Pi conversation, or run Fusion earlier in the session.',
-  "Raise the route's context window with a larger-context model via /fusion-models.",
+const REASON_REQUEST_REMEDIATION: readonly string[] = Object.freeze([
+  'Provide a shorter fusion_reason prompt.',
+  'Start a fresh Pi conversation, or run fusion_reason earlier in the session.',
+  "Raise the route's context window with a larger-context subscription model via /fusion-models.",
 ]);
 
+const INVESTIGATE_EMPTY_REMEDIATION: readonly string[] = Object.freeze([
+  'Split the repository investigation into smaller independently complete path or subsystem scopes.',
+  "Raise the route's context window with a larger-context subscription model via /fusion-models.",
+]);
+const INVESTIGATE_REQUEST_REMEDIATION: readonly string[] = Object.freeze([
+  'Narrow the fusion_investigate objective, repository scope, or required evidence.',
+  "Raise the route's context window with a larger-context subscription model via /fusion-models.",
+]);
+const RESEARCH_EMPTY_REMEDIATION: readonly string[] = Object.freeze([
+  'Split the research into smaller independently complete source sets.',
+  "Raise the route's context window with a larger-context subscription model via /fusion-models.",
+]);
+const RESEARCH_REQUEST_REMEDIATION: readonly string[] = Object.freeze([
+  'Narrow the fusion_research question or split large declared-source sets across independent runs.',
+  "Raise the route's context window with a larger-context subscription model via /fusion-models.",
+]);
+const VALIDATE_EMPTY_REMEDIATION: readonly string[] = Object.freeze([
+  'Split validation into smaller independently complete change or acceptance-criterion scopes.',
+  "Raise the route's context window with a larger-context subscription model via /fusion-models.",
+]);
+const VALIDATE_REQUEST_REMEDIATION: readonly string[] = Object.freeze([
+  'Narrow the fusion_validate scope, acceptance criteria, or supplied verification evidence.',
+  "Raise the route's context window with a larger-context subscription model via /fusion-models.",
+]);
+
+function cleanRemediation(
+  profile: FusionWorkflowProfile,
+  requestDeterminesFeasibility: boolean,
+): readonly string[] {
+  if (profile.id === 'investigate') {
+    return requestDeterminesFeasibility
+      ? INVESTIGATE_REQUEST_REMEDIATION
+      : INVESTIGATE_EMPTY_REMEDIATION;
+  }
+  if (profile.id === 'research') {
+    return requestDeterminesFeasibility ? RESEARCH_REQUEST_REMEDIATION : RESEARCH_EMPTY_REMEDIATION;
+  }
+  if (profile.id === 'validate') {
+    return requestDeterminesFeasibility ? VALIDATE_REQUEST_REMEDIATION : VALIDATE_EMPTY_REMEDIATION;
+  }
+  return requestDeterminesFeasibility ? REASON_REQUEST_REMEDIATION : REASON_EMPTY_REMEDIATION;
+}
+
 const RESERVATION_REMEDIATION: readonly string[] = Object.freeze([
   'Route the blocking stage to a model with larger byte capacity.',
   'Keep producer output contracts intact; do not shrink or truncate child answers.',
@@ -455,16 +497,28 @@ function replaceRequestText(input: FusionCanonicalInputV3, text: string): Fusion
 }
 
 function visibleTextBytes(input: FusionCanonicalInputV3): number {
+  const projection = input.context?.kind === 'session_projection'
+    ? input.context.conversation_projection
+    : 'conversation_projection' in input
+      ? input.conversation_projection
+      : undefined;
+  if (projection === undefined) return 0;
   let total = 0;
-  for (const entry of input.conversation_projection.entries) {
+  for (const entry of projection.entries) {
     if (entry[0] === 't') total += utf8Bytes(JSON.stringify(entry[4]));
   }
   return total;
 }
 
 function omissionReceiptBytes(input: FusionCanonicalInputV3): number {
+  const projection = input.context?.kind === 'session_projection'
+    ? input.context.conversation_projection
+    : 'conversation_projection' in input
+      ? input.conversation_projection
+      : undefined;
+  if (projection === undefined) return 0;
   let total = 0;
-  for (const entry of input.conversation_projection.entries) {
+  for (const entry of projection.entries) {
     if (entry[0] === 'o') total += utf8Bytes(JSON.stringify(entry));
   }
   return total;
@@ -525,10 +579,11 @@ function dominantRemediation(
   verdict: FusionBudgetEmptyRequestVerdict,
   composition: FusionBudgetStageComposition | undefined,
   dominantByteClass: string,
+  profile: FusionWorkflowProfile,
 ): readonly string[] {
   if (dominantByteClass === 'dense_ascii') return DENSE_REMEDIATION;
   if (dominantByteClass === 'multibyte') return MULTIBYTE_REMEDIATION;
-  if (composition === undefined) return remediationFor(verdict);
+  if (composition === undefined) return remediationFor(verdict, profile);
   const entries = [
     { name: 'visible', bytes: composition.visible_text_bytes },
     { name: 'request', bytes: composition.request_bytes },
@@ -537,13 +592,24 @@ function dominantRemediation(
   const dominant = entries[0];
   if (dominant?.name === 'reservation') return RESERVATION_REMEDIATION;
   if (dominant?.name === 'request' && !verdict.still_fails_with_empty_request) {
-    return REQUEST_REMEDIATION;
+    return profile.contextKind === 'clean_task'
+      ? cleanRemediation(profile, true)
+      : REASON_REQUEST_REMEDIATION;
   }
-  return EMPTY_REMEDIATION;
+  if (profile.contextKind === 'clean_task') return cleanRemediation(profile, false);
+  return REASON_EMPTY_REMEDIATION;
 }
 
-function remediationFor(verdict: FusionBudgetEmptyRequestVerdict): readonly string[] {
-  return verdict.still_fails_with_empty_request ? EMPTY_REMEDIATION : REQUEST_REMEDIATION;
+function remediationFor(
+  verdict: FusionBudgetEmptyRequestVerdict,
+  profile: FusionWorkflowProfile,
+): readonly string[] {
+  if (profile.contextKind === 'clean_task') {
+    return cleanRemediation(profile, !verdict.still_fails_with_empty_request);
+  }
+  return verdict.still_fails_with_empty_request
+    ? REASON_EMPTY_REMEDIATION
+    : REASON_REQUEST_REMEDIATION;
 }
 
 function formatEmptyRequestVerdict(verdict: FusionBudgetEmptyRequestVerdict): string {
@@ -682,8 +748,8 @@ export class FusionBudget {
   constructor(
     models: ResolvedFusionModels,
     contextPolicyId: string,
-    candidateCapability: FusionCapability = FUSION_DEFAULT_CAPABILITY,
-    profile: FusionWorkflowProfile = FUSION_BRAINSTORM_WORKFLOW,
+    candidateCapability: FusionCapability = FUSION_REASON_WORKFLOW.candidateCapability,
+    profile: FusionWorkflowProfile = FUSION_REASON_WORKFLOW,
   ) {
     this.routes = fusionRouteCapacities(models);
     this.limiting = fusionLimitingRoute(this.routes);
@@ -851,7 +917,12 @@ export class FusionBudget {
   ): FusionError {
     const composition = plan.primary_blocker_composition;
     const dominantByteClass = primary.input_only_estimate.rateSource.dominant_byte_class;
-    const remediation = dominantRemediation(plan.empty_request, composition, dominantByteClass);
+    const remediation = dominantRemediation(
+      plan.empty_request,
+      composition,
+      dominantByteClass,
+      this.profile,
+    );
     const tokensOver = primary.input_only_input_tokens_upper_bound - primary.allowed_input_tokens;
     const budget: FusionBudgetErrorDetail = {
       budget_stage: primary.budget_stage,
@@ -925,6 +996,25 @@ export class FusionBudget {
     return new FusionError(message, details);
   }
 
+  private planMetadata(input?: FusionCanonicalInputV3): Pick<FusionBudgetPlanV1, 'workflow' | 'context' | 'fixed_candidate_policy' | 'tool_policy'> {
+    return {
+      workflow: this.profile.id,
+      context: {
+        kind: this.profile.contextKind,
+        policy_id: input?.context?.policy_id ?? this.contextPolicyId,
+      },
+      fixed_candidate_policy: {
+        capability: this.candidateCapability,
+        tools: this.profile.candidateTools,
+      },
+      tool_policy: {
+        candidate_tools: this.profile.candidateTools,
+        evaluation_tools: [] as readonly [],
+        merge_tools: [] as readonly [],
+      },
+    };
+  }
+
   plan(input: FusionCanonicalInputV3): FusionBudgetPlanV1 {
     const stages = this.entries(input);
     const blockers = selectBlockers(stages);
@@ -932,6 +1022,7 @@ export class FusionBudget {
     const emptyRequest = this.emptyRequestVerdict(input, stages);
     const base: FusionBudgetPlanV1 = {
       schema_version: FUSION_BUDGET_PLAN_SCHEMA_VERSION,
+      ...this.planMetadata(input),
       policy: FUSION_BUDGET_POLICY,
       routes: this.routes,
       stages,
@@ -994,6 +1085,7 @@ export class FusionBudget {
     const blocker = blockerFromEntry(entry);
     const plan: FusionBudgetPlanV1 = {
       schema_version: FUSION_BUDGET_PLAN_SCHEMA_VERSION,
+      ...this.planMetadata(),
       policy: FUSION_BUDGET_POLICY,
       routes: this.routes,
       stages: [entry],

package/src/core/fusion/child-protocol.ts

@@ -0,0 +1,82 @@
+import { createHash } from 'node:crypto';
+import type { Usage } from '@earendil-works/pi-ai';
+
+export const FUSION_CHILD_RESULT_SCHEMA_VERSION =
+  'pi-background-tasks.fusion-child-result.v2' as const;
+export const FUSION_CHILD_RESULT_PREFIX = '\u001ePI_FUSION_CHILD_RESULT ';
+export const FUSION_TOOL_CALL_LOG_PATH_ENV = 'PI_FUSION_TOOL_CALL_LOG_PATH';
+export const FUSION_RESEARCH_ENABLED_ENV = 'PI_FUSION_RESEARCH_ENABLED';
+export const FUSION_SOURCE_POLICY_PATH_ENV = 'PI_FUSION_SOURCE_POLICY_PATH';
+export const FUSION_SOURCE_POLICY_SHA256_ENV = 'PI_FUSION_SOURCE_POLICY_SHA256';
+export const FUSION_TOOL_CALL_SEAL_SCHEMA_VERSION =
+  'pi-background-tasks.fusion-tool-call-seal.v1' as const;
+export const FUSION_TOOL_CALL_SEAL_SUFFIX = '.seal.json';
+
+/**
+ * Aggregate ceiling on tool-result bytes a single candidate child may accumulate.
+ *
+ * v1 deliberately has no tool-call-count cap, so this byte budget is the only bound on
+ * how much a read-only candidate can pull into its context. 8 MiB is generous for
+ * targeted grep/read investigation while still preventing an unbounded read loop from
+ * degrading into an opaque provider-side context failure.
+ */
+export const FUSION_CHILD_MAX_TOTAL_TOOL_RESULT_BYTES = 8 * 1024 * 1024;
+
+export interface FusionChildTextBlockMetadata {
+  utf8_bytes: number;
+  sha256: string;
+}
+
+export type FusionChildResultUsageMetadata = Usage;
+
+export interface FusionChildResultMetadata {
+  schema_version: typeof FUSION_CHILD_RESULT_SCHEMA_VERSION;
+  provider: string;
+  model: string;
+  stop_reason: string;
+  text_blocks: FusionChildTextBlockMetadata[];
+  text_sha256: string;
+  usage: FusionChildResultUsageMetadata;
+}
+
+function protocolSha256(value: string | Buffer): string {
+  return createHash('sha256').update(value).digest('hex');
+}
+
+export function buildFusionChildResultMetadata(message: {
+  provider: string;
+  model: string;
+  stopReason: string;
+  content: ReadonlyArray<{ type: string; text?: string }>;
+  usage: Usage;
+}): FusionChildResultMetadata {
+  const textBlocks = message.content.flatMap((part) =>
+    part.type === 'text' && typeof part.text === 'string' ? [part.text] : [],
+  );
+  const usage: FusionChildResultUsageMetadata = {
+    input: message.usage.input,
+    output: message.usage.output,
+    cacheRead: message.usage.cacheRead,
+    cacheWrite: message.usage.cacheWrite,
+    totalTokens: message.usage.totalTokens,
+    cost: {
+      input: message.usage.cost.input,
+      output: message.usage.cost.output,
+      cacheRead: message.usage.cost.cacheRead,
+      cacheWrite: message.usage.cost.cacheWrite,
+      total: message.usage.cost.total,
+    },
+  };
+  return {
+    schema_version: FUSION_CHILD_RESULT_SCHEMA_VERSION,
+    provider: message.provider,
+    model: message.model,
+    stop_reason: message.stopReason,
+    text_blocks: textBlocks.map((text) => ({
+      utf8_bytes: Buffer.byteLength(text, 'utf8'),
+      sha256: protocolSha256(text),
+    })),
+    text_sha256: protocolSha256(textBlocks.join('')),
+    usage,
+  };
+}

package/src/core/fusion/clean-context.ts

@@ -0,0 +1,91 @@
+import { createHash } from 'node:crypto';
+import { canonicalJson } from '../attested-pi-run.js';
+import { normalizeFusionDeclaredSources, type DeclaredFusionSourceInput } from './source-policy.js';
+import {
+  FUSION_INPUT_SCHEMA_VERSION,
+  FusionError,
+  type FusionCanonicalRequestV3,
+  type FusionCleanTaskCanonicalInputV5,
+  type FusionDeclaredSourceV1,
+  type FusionSource,
+  type FusionWorkflowId,
+} from './types.js';
+
+export interface BuildFusionCleanTaskInputOptions {
+  cwd: string;
+  source: FusionSource;
+  request: string;
+  workflow: Exclude<FusionWorkflowId, 'reason'>;
+  declaredSources?: readonly DeclaredFusionSourceInput[] | undefined;
+}
+
+/**
+ * Public v1 clean builder. It is deliberately pure: callers provide cwd and
+ * normalized request text explicitly, and this module has no dependency on Pi
+ * session, snapshot, parent-context, or visible-conversation APIs.
+ */
+export const buildCleanFusionCanonicalInput = buildFusionCleanTaskCanonicalInput;
+
+export interface BuiltFusionCleanTaskCanonicalInput {
+  input: FusionCleanTaskCanonicalInputV5;
+  serialized: string;
+  declaredSources: readonly FusionDeclaredSourceV1[];
+  transcriptLeafId: null;
+}
+
+function sha256Text(value: string): string {
+  return createHash('sha256').update(Buffer.from(value, 'utf8')).digest('hex');
+}
+
+export function buildFusionCleanTaskCanonicalInput(
+  options: BuildFusionCleanTaskInputOptions,
+): BuiltFusionCleanTaskCanonicalInput {
+  if (options.request.trim().length === 0) {
+    throw new FusionError('fusion request must not be blank', {
+      code: 'context_capture_failed',
+      childCreated: false,
+    });
+  }
+  if (!['investigate', 'research', 'validate'].includes(options.workflow)) {
+    throw new FusionError('clean-task fusion input is available only to investigate, research, and validate workflows', {
+      code: 'context_capture_failed',
+      childCreated: false,
+    });
+  }
+  const declaredSources = normalizeFusionDeclaredSources(options.declaredSources ?? []);
+  if (options.workflow === 'research' && declaredSources.length === 0) {
+    throw new FusionError('fusion research requires at least one declared source URL and purpose', {
+      code: 'context_capture_failed',
+      childCreated: false,
+    });
+  }
+  if (options.workflow !== 'research' && declaredSources.length > 0) {
+    throw new FusionError('declared sources are accepted only by the research workflow', {
+      code: 'context_capture_failed',
+      childCreated: false,
+    });
+  }
+  const request: FusionCanonicalRequestV3 = {
+    source: options.source,
+    authority: 'explicit_text',
+    text: options.request,
+    sha256: sha256Text(options.request),
+  };
+  const input: FusionCleanTaskCanonicalInputV5 = {
+    schema_version: FUSION_INPUT_SCHEMA_VERSION,
+    workflow: options.workflow,
+    cwd: options.cwd,
+    request,
+    context: {
+      kind: 'clean_task',
+      policy_id: 'fusion-clean-task-v1',
+      declared_sources: declaredSources,
+    },
+  };
+  return {
+    input,
+    serialized: canonicalJson(input),
+    declaredSources,
+    transcriptLeafId: null,
+  };
+}

package/src/core/fusion/config.ts

@@ -24,6 +24,7 @@ export interface FusionModelRegistry {
   getAll(): Model<Api>[];
   getAvailable(): Model<Api>[];
   find?(provider: string, modelId: string): Model<Api> | undefined;
+  isUsingOAuth?(model: Model<Api>): boolean;
 }
 
 export interface ResolveFusionModelsInput {
@@ -163,12 +164,119 @@ function modelIndex(models: readonly Model<Api>[]): Map<string, Model<Api>> {
   return out;
 }
 
+const FRONTIER_MODEL_PATTERN =
+  /(?:^|[-_/])(?:gpt|codex|claude|opus|sonnet|o[134](?:-[a-z0-9.]+)*)(?:[-_/]|$)/iu;
+const TRUSTED_SUBSCRIPTION_ENDPOINTS = Object.freeze({
+  anthropic: 'https://api.anthropic.com',
+  'openai-codex': 'https://chatgpt.com/backend-api',
+} as const);
+const AUTH_HEADER_NAMES = new Set(['authorization', 'proxy-authorization', 'x-api-key', 'api-key']);
+
+function isKnownFrontierEndpoint(baseUrl: string | undefined): boolean {
+  if (baseUrl === undefined || baseUrl.trim().length === 0) return false;
+  try {
+    const hostname = new URL(baseUrl).hostname.toLowerCase().replace(/\.+$/u, '');
+    return (
+      hostname === 'api.openai.com' ||
+      hostname === 'api.anthropic.com' ||
+      hostname === 'openrouter.ai' ||
+      hostname === 'chatgpt.com' ||
+      hostname.endsWith('.openai.azure.com') ||
+      hostname.endsWith('.cognitiveservices.azure.com') ||
+      hostname.endsWith('.ai.azure.com')
+    );
+  } catch {
+    return false;
+  }
+}
+
+function assertTrustedSubscriptionEndpoint(
+  model: Model<Api>,
+  slotLabel: string,
+  provider: keyof typeof TRUSTED_SUBSCRIPTION_ENDPOINTS,
+): void {
+  const expectedText = TRUSTED_SUBSCRIPTION_ENDPOINTS[provider];
+  const effectiveText = model.baseUrl?.trim() || expectedText;
+  let effective: URL;
+  try {
+    effective = new URL(effectiveText);
+  } catch {
+    throw new FusionError(
+      `${slotLabel} route ${model.provider}/${model.id} has a malformed subscription endpoint`,
+      { code: 'model_unavailable', childCreated: false },
+    );
+  }
+  const expected = new URL(expectedText);
+  const effectivePath = effective.href.slice(effective.origin.length).replace(/\/+$/u, '');
+  const expectedPath = expected.href.slice(expected.origin.length).replace(/\/+$/u, '');
+  if (
+    effective.protocol !== 'https:' ||
+    effective.username !== '' ||
+    effective.password !== '' ||
+    effective.search !== '' ||
+    effective.hash !== '' ||
+    effective.origin !== expected.origin ||
+    effectivePath !== expectedPath
+  ) {
+    throw new FusionError(
+      `${slotLabel} route ${model.provider}/${model.id} does not use the trusted Pi subscription endpoint ${expectedText}`,
+      { code: 'model_unavailable', childCreated: false },
+    );
+  }
+  const unsafeHeader = Object.keys(model.headers ?? {}).find((name) =>
+    AUTH_HEADER_NAMES.has(name.toLowerCase()),
+  );
+  if (unsafeHeader !== undefined) {
+    throw new FusionError(
+      `${slotLabel} route ${model.provider}/${model.id} overrides subscription authentication header ${unsafeHeader}`,
+      { code: 'model_unavailable', childCreated: false },
+    );
+  }
+}
+
+function assertSubscriptionRoute(
+  model: Model<Api>,
+  slotLabel: string,
+  registry: FusionModelRegistry,
+): void {
+  const provider = model.provider.toLowerCase();
+  const frontier =
+    provider === 'openai' ||
+    provider === 'openrouter' ||
+    provider === 'anthropic' ||
+    provider === 'openai-codex' ||
+    provider.includes('azure') ||
+    FRONTIER_MODEL_PATTERN.test(`${provider}/${model.id}`) ||
+    isKnownFrontierEndpoint(model.baseUrl);
+  if (!frontier) return;
+  if (provider !== 'anthropic' && provider !== 'openai-codex') {
+    throw new FusionError(
+      `${slotLabel} route ${model.provider}/${model.id} is a frontier-model API channel; Fusion requires the Pi Anthropic or Codex subscription route`,
+      { code: 'model_unavailable', childCreated: false },
+    );
+  }
+  assertTrustedSubscriptionEndpoint(model, slotLabel, provider);
+  if (registry.isUsingOAuth === undefined) {
+    throw new FusionError(
+      `${slotLabel} route ${model.provider}/${model.id} cannot be admitted because ModelRegistry OAuth observation is unavailable`,
+      { code: 'model_unavailable', childCreated: false },
+    );
+  }
+  if (!registry.isUsingOAuth(model)) {
+    throw new FusionError(
+      `${slotLabel} route ${model.provider}/${model.id} is not using subscription OAuth; metered API credentials are forbidden for Fusion`,
+      { code: 'model_unavailable', childCreated: false },
+    );
+  }
+}
+
 function resolveSelection(
   selection: FusionModelSelection,
   slotLabel: string,
   availableByKey: Map<string, Model<Api>>,
   currentModel: Model<Api> | undefined,
   thinkingLevel: FusionThinkingLevel,
+  registry: FusionModelRegistry,
 ): ResolvedFusionModel {
   if (selection === CURRENT_MODEL_SELECTION) {
     if (currentModel === undefined) {
@@ -188,6 +296,7 @@ function resolveSelection(
         },
       );
     }
+    assertSubscriptionRoute(available, slotLabel, registry);
     return {
       selection,
       source: 'current',
@@ -205,6 +314,7 @@ function resolveSelection(
       childCreated: false,
     });
   }
+  assertSubscriptionRoute(model, slotLabel, registry);
   return {
     selection,
     source: 'configured',
@@ -219,44 +329,23 @@ function resolveSelection(
 export function resolveFusionModels(input: ResolveFusionModelsInput): ResolvedFusionModels {
   const availableByKey = modelIndex(input.modelRegistry.getAvailable());
   const [first, second, third] = input.config.candidates;
-  return {
-    candidates: [
-      resolveSelection(
-        first,
-        'candidate 1',
-        availableByKey,
-        input.currentModel,
-        input.thinkingLevel,
-      ),
-      resolveSelection(
-        second,
-        'candidate 2',
-        availableByKey,
-        input.currentModel,
-        input.thinkingLevel,
-      ),
-      resolveSelection(
-        third,
-        'candidate 3',
-        availableByKey,
-        input.currentModel,
-        input.thinkingLevel,
-      ),
-    ],
-    evaluator: resolveSelection(
-      input.config.evaluator,
-      'evaluator',
-      availableByKey,
-      input.currentModel,
-      input.thinkingLevel,
-    ),
-    merger: resolveSelection(
-      input.config.merger,
-      'merger',
+  const resolve = (selection: FusionModelSelection, slot: string): ResolvedFusionModel =>
+    resolveSelection(
+      selection,
+      slot,
       availableByKey,
       input.currentModel,
       input.thinkingLevel,
-    ),
+      input.modelRegistry,
+    );
+  return {
+    candidates: [
+      resolve(first, 'candidate 1'),
+      resolve(second, 'candidate 2'),
+      resolve(third, 'candidate 3'),
+    ],
+    evaluator: resolve(input.config.evaluator, 'evaluator'),
+    merger: resolve(input.config.merger, 'merger'),
   };
 }